Map Studio API

The Map Studio API is where Mountaya's content lives. It serves the resources the map renders — itineraries and their segments, waypoints and segment groups, zones, and the collections that organize them — as JSON over https://internal.mountaya.com. Its operations, grouped by resource, cover reading, writing, importing, exporting, sharing, and publishing.

It is the only surface that writes. The Data API computes answers about geography and stores nothing; the Tile API renders what already exists. When you need a route to persist, be edited, and come back tomorrow, it goes through here.

When to use it

Reach for the Map Studio API when your product owns the content: a route builder that saves what a user draws, a bulk importer for a catalog of GPX files, a back-office that curates collections. If you would rather not build the editing UI at all, Map Embedding drops the full studio into an iframe and writes through this same API on your behalf.

Authentication

Every operation states the scope it requires, both as an x-pkey-scope on the operation and as a line in its description. Most take a publishable key with the resources scope in the X-API-Key header; the studio-only surfaces (the AI agent, real-time collaboration, layers and activities) take embedding, and the organization-administration operations — keys, billing, members, settings, usage — take management.

POST /v1/sessions is the exception that takes no publishable-key scope at all: it mints session tokens, so it takes your secret key instead.

Write requests — POST, PUT, PATCH, DELETE — also require an X-User-Id header naming the organization member the write is attributed to. Reads do not. See authentication for where that id comes from and which roles qualify.

The envelope

A successful response carries the resource under data. Response-scoped metadata, when an operation has any, rides under extensions.metadata.

{
  "data": {
    "id": "0b6d1a4e-6d3f-4f7a-9c2e-1f0a5b8c3d21",
    "name": "Tour du Mont Blanc"
  }
}

A failure replaces data with errors. Both APIs share one error envelope and one closed code vocabulary — see errors for the sixteen codes, the field paths, and what a 402, a 429, and a 504 each mean.

Scoping a listing

GET /v1/itineraries returns one scope at a time, and organization_id is the only thing that selects it. Omit it and you get the caller's personal view: their own itineraries, grouped by their own personal collections. An itinerary owned by a real organization does not appear there, so ask for that organization by name to see it. Send it and you get that organization's view: the itineraries it owns, grouped by the collections it owns, including folders a colleague created, because a collection belongs to its organization rather than to its author.

The caller must be an active member of the organization they name. A non-member receives 404, not 403, so the parameter cannot be used to probe which organization ids exist. The root organization is refused the same way: it is the personal scope, and that scope has exactly one spelling, which is leaving organization_id out.

Pagination

Pagination is opt-in per operation, not a property of every list endpoint. Five operations accept limit and offset:

• GET /v1/itineraries
• GET /v1/itineraries/{itinerary_id}/collections
• GET /v1/zones/{zone_id}/collections
• GET /v1/users/{user_id}/collections
• GET /v1/organizations/{organization_id}/collections

Each reports the window it served at extensions.metadata.pagination, carrying the limit and offset you sent back plus the total you are authorized to see, counted before the window was applied. So offset + len(data) < total means there is another page.

limit has no default. Omit it and you receive the complete set, which is what an unparameterized request has to mean — a client counting its own itineraries against a plan limit would otherwise under-count a truncated page. When you do send one it may not exceed 50, the same ceiling the Data API enforces.

Explore