Skip to content
Log inGet an API key
Documentation menu
docs / api / post-v1-jobs-matrix
routing

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
FieldTypeRequiredDescription
idstringyesThe job id to poll.
kindstringyesoptimise, replan, matrix or coverage.
result_urlstringyesWhere to fetch it. The same URL the webhook will carry.
statusstringyesAlways queued, the worker has not looked at it yet.
units_chargedintegeryesQuota 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.

Also under routing

POST /centroidPOST /isochronePOST /locatePOST /matrixPOST /optimisePOST /optimise/replanPOST /routePOST /route/alongPOST /route/progressPOST /route/reportGET /route/v1/{profile}/{coordinates}POST /trace_attributesPOST /trace_routePOST /v1/cameras/alongPOST /v1/charging/alongPOST /v1/clusterPOST /v1/errands/planPOST /v1/ev/planPOST /v1/fuel/alongPOST /v1/incidents/alongPOST /v1/jobs/coveragePOST /v1/jobs/optimisePOST /v1/jobs/replanPOST /v1/route/heritagePOST /v1/route/observationsPOST /v1/weather/alongGET /v1/zones

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