Get started
API conventions

Request IDs and headers

Request IDs and headers

Every answer from every Mountaya API carries an X-Request-Id. Log it beside every failure, and quote it when you contact support: it finds your request among all the others.

Request IDs

curl -s -i https://api.mountaya.com/v1/itineraries/0b6d1a4e-6d3f-4f7a-9c2e-1f0a5b8c3d21 \
  -H "X-API-Key: $MOUNTAYA_PUBLISHABLE_KEY"
Response
HTTP/1.1 404 Not Found
Cache-Control: private, no-store
Content-Type: application/json
X-Request-Id: 8ee0073c046aa0ff1b55b3b43515b870

{"errors":[{"message":"The requested resource was not found","extensions":{"code":"NOT_FOUND"}}]}

Request headers

HeaderSend it
X-API-KeyOn every request: your publishable key, or your secret key on POST /v1/sessions
X-Session-TokenWhere the operation or your organization needs a session token
Idempotency-KeyOn every Map Studio API write. See idempotency
If-MatchTo make a write conditional. See conditional writes
Accept-LanguageTo translate error messages and localized names
Content-Type: application/jsonWith every request body

Response headers

HeaderSent on
X-Request-IdEvery answer
Retry-AfterEvery 429 but a ceiling's (LIMIT_REACHED), and a 409 coded IDEMPOTENCY_KEY_IN_USE
RateLimit, RateLimit-PolicyData API and Tile API answers. See rate limits
ETagEvery answer that returns a resource you can write conditionally, and a 412
Idempotent-Replayedtrue on a write's stored answer, replayed
LocationEvery 201, naming what was created, and every 308
WWW-AuthenticateEvery 401, naming the credential to send
AllowEvery 405, naming the methods the path takes

Browsers on other origins can read all of these through CORS.

Caching

Mountaya answers each request by the state it reads as the request arrives. Revoking a key or rotating a share link takes effect on the next request. Only public answers, such as a published itinerary or a public tile, may be stored by a shared cache, for at most a few minutes.

Timeouts

Each request runs under a time budget: 30 seconds, and 55 for an import. Past it, the API answers 504 Gateway Timeout. Let your HTTP client wait a little longer than the budget, so it never abandons an answer that was coming.

In the TypeScript client

The TypeScript client applies all of this for you. It sends an Idempotency-Key with every write, waits out Retry-After, and follows cursors with paginate. Every error carries its requestId.

Next steps

Last updated