POST/v1/jobs/matrix

API key required, sent as Authorization: Bearer snk_… or ?api_key=snk_….

Call it

bash

curl -fsS -X POST "https://api.mapmap.ai/v1/jobs/matrix" \
  -H "Authorization: Bearer $MAPMAP_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

Request body

application/json

Exactly the POST /matrix body: sources, targets, costing, optional units, costing_options, exclude_polygons and exclude_locations, plus an optional webhook_url. The element cap here is SN_MATRIX_MAX_ELEMENTS_ASYNC (40,000 by default), four times the synchronous 10,000

The OpenAPI document declares this body as a free-form JSON object with no field list, so there is nothing here to generate a table from. The prose above is what the gateway states about it; the raw document is the authority.

Responses

202Accepted and queued. Poll result_url, or wait for the signed webhook

Field	Type	Required	Description
id	string	yes	The job id to poll.
kind	string	yes	`optimise`, `replan` or `matrix`.
result_url	string	yes	Where to fetch it. The same URL the webhook will carry.
status	string	yes	Always `queued` — the worker has not looked at it yet.
units_charged	integer	yes	Quota units this submission drew. Charged now, refunded in full if the job fails.

400Invalid matrix request, or an unusable webhook_url

401Missing or invalid API key

409A webhook_url was given but the key has no webhook signing secret

422More than SN_MATRIX_MAX_ELEMENTS_ASYNC elements, or a matrix spanning further than the engine's max_matrix_distance

429Quota, rate limit, or too many jobs already queued or running

Error bodies follow the shared problem model documented on API conventions.

Generated from https://api.mapmap.ai/openapi.json on 2026-09-17 · operationId post_matrix_job

POST/v1/jobs/matrix

Call it

Request body

Responses

Also under routing