Get started

Collaboration & AI

Collaboration

The live event stream for a resource being edited: who is present, what they have selected, and what changed. It is what lets two people edit one route without overwriting each other.

Stream one itinerary's collaboration session over SSE

GET
/v1/itineraries/{itinerary_id}/events

Opens a Server-Sent Events (SSE) stream of one itinerary's real-time editing session, so every member with the itinerary open converges on the same view and sees who else is editing. The response Content-Type is text/event-stream and the connection stays open until the client disconnects or the credential it was opened with ends.

Path parameters

itinerary_id

string (uuid)

in path

required

Identifier of the itinerary the operation acts on. An itinerary this credential does not reach is a 404 rather than a 403, and so is one that does not exist, so the parameter cannot be used to learn which itinerary ids exist.

Headers

Last-Event-ID

string

in header

The last stream id the client received, <milliseconds>-<sequence> as the stream wrote it, for example 1778577393417-0. A value of any other shape is a 400, answered before the stream opens. When set, the server replays the events after that id that the stream still holds before resuming the live feed. A stream holds about its last thousand events, for an hour after the latest one, or for five minutes after an agent run's done event, so a client that reconnects within that window misses no event that carries an id. An id older than what the stream still holds is not refused: the replay starts at the oldest event held, and nothing marks the gap.

Response 200 text/event-stream

A text/event-stream of the itinerary's collaboration session, framed as id:/event:/data: records, open until the client disconnects or the credential ends, when a last reconnect event closes it. The schema describes one decoded frame, the data: JSON of a single record with the record's event: type folded in, not the byte stream as a whole.

Errors 400, 401, 402, 403, 404, 429, 500, 503. See Errors.

curl -sN "https://api.mountaya.com/v1/itineraries/0b6d1a4e-6d3f-4f7a-9c2e-1f0a5b8c3d21/events" \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token"

# Every durable frame carries an id. Send the last one you handled when you reopen,
# after a drop or after a `reconnect` event with a fresh session token, and the
# stream replays from just after it, so an edit made in between is not lost.
curl -sN "https://api.mountaya.com/v1/itineraries/0b6d1a4e-6d3f-4f7a-9c2e-1f0a5b8c3d21/events" \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Last-Event-ID: 1778577393417-1"

Send a collaboration signal into an itinerary's session

POST
/v1/itineraries/{itinerary_id}/collab

Sends a live collaboration signal into an itinerary's real-time session, fanned out over the editor stream (getItineraryEvents) to every connection on it. The sender's own connections receive it too, recognizable by their user_id, which is the sender's. The request body shape is selected by its type discriminator:

Path parameters

itinerary_id

string (uuid)

in path

required

Identifier of the itinerary the operation acts on. An itinerary this credential does not reach is a 404 rather than a 403, and so is one that does not exist, so the parameter cannot be used to learn which itinerary ids exist.

Body

The collaboration signal to broadcast to everyone editing this itinerary: a selection, a cursor move, a lock, or a draft update.

Response 200

The collaboration signal is accepted and fanned out to the editor stream. data is null.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

any | null

required

Always null: this operation answers with no payload.

Errors 400, 401, 402, 403, 404, 409, 413, 429, 500, 504. See Errors.

# Signals are ephemeral: they go out on the editor stream and are never stored.
# Send the durable change through the ordinary write instead.
curl -s -X POST https://api.mountaya.com/v1/itineraries/0b6d1a4e-6d3f-4f7a-9c2e-1f0a5b8c3d21/collab \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Content-Type: application/json" \
  -d '{"type": "cursor", "position": {"lng": 6.8712, "lat": 45.9231}}'
200
Response
{
  "data": null
}

Stream one zone's collaboration session over SSE

GET
/v1/zones/{zone_id}/events

Opens a Server-Sent Events (SSE) stream of one zone's real-time editing session, so every member with the zone open converges on the same view and sees who else is editing. The response Content-Type is text/event-stream and the connection stays open until the client disconnects or the credential it was opened with ends. It is the zone twin of the itinerary editor stream, getItineraryEvents. A HEAD on this path answers the stream's headers and opens no subscription.

Path parameters

zone_id

string (uuid)

in path

required

Identifier of the zone the operation acts on.

Headers

Last-Event-ID

string

in header

The last stream id the client received, <milliseconds>-<sequence> as the stream wrote it, for example 1778577393417-0. A value of any other shape is a 400, answered before the stream opens. When set, the server replays the events after that id that the stream still holds before resuming the live feed. A stream holds about its last thousand events, for an hour after the latest one, or for five minutes after an agent run's done event, so a client that reconnects within that window misses no event that carries an id. An id older than what the stream still holds is not refused: the replay starts at the oldest event held, and nothing marks the gap.

Response 200 text/event-stream

The zone's collaboration session as a text/event-stream, framed as id:/event:/data: records and ended by a reconnect record when the credential ends. The schema describes one decoded frame, the data: JSON of a single record with the record's event: type folded in, not the byte stream as a whole.

Errors 400, 401, 402, 403, 404, 429, 500, 503. See Errors.

# Server-sent events, held open. Read it with a client that streams; buffering the
# whole response waits forever by design.
curl -sN https://api.mountaya.com/v1/zones/c40f8a25-7e63-4d19-b8a0-9f2e5c31d764/events \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token"

Send a collaboration signal into a zone's session

Sends a live collaboration signal into a zone's real-time session, fanned out over the editor stream, getZoneEvents, to every connection on it. The sender's own connections receive it too, recognizable by their user_id, which is the sender's. It is the zone twin of postItineraryCollab and reuses the same signal shapes. The request body shape is selected by its type discriminator:

Path parameters

zone_id

string (uuid)

in path

required

Identifier of the zone the operation acts on.

Body

The collaboration signal to broadcast to everyone editing this zone: a selection, a cursor move, a lock, or a draft update.

Response 200

The collaboration signal is accepted and fanned out to the editor stream. data is null.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

any | null

required

Always null: this operation answers with no payload.

Errors 400, 401, 402, 403, 404, 409, 413, 429, 500, 504. See Errors.

# Signals are ephemeral: they go out on the editor stream and are never stored.
# Send the durable change through the ordinary write instead.
curl -s -X POST https://api.mountaya.com/v1/zones/c40f8a25-7e63-4d19-b8a0-9f2e5c31d764/collab \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Content-Type: application/json" \
  -d '{"type": "cursor", "position": {"lng": 6.8712, "lat": 45.9231}}'
200
Response
{
  "data": null
}

Stream an organization's list events over SSE

GET
/v1/organizations/{organization_id}/events

Opens a Server-Sent Events (SSE) stream of the changes to the target organization's itineraries, zones and collections, so every member watching the studio sees its lists converge without polling. The path names the key's own organization: a key is pinned to the organization it was issued for, and naming another is a 403 whether or not it exists. The response Content-Type is text/event-stream and the connection stays open until the client disconnects or the credential it was opened with ends. A HEAD on this path answers the stream's headers and opens no subscription.

Path parameters

organization_id

string (uuid)

in path

required

Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.

Headers

Last-Event-ID

string

in header

The last stream id the client received, <milliseconds>-<sequence> as the stream wrote it, for example 1778577393417-0. A value of any other shape is a 400, answered before the stream opens. When set, the server replays the events after that id that the stream still holds before resuming the live feed. A stream holds about its last thousand events, for an hour after the latest one, or for five minutes after an agent run's done event, so a client that reconnects within that window misses no event that carries an id. An id older than what the stream still holds is not refused: the replay starts at the oldest event held, and nothing marks the gap.

Response 200 text/event-stream

The organization's list events as a text/event-stream, framed as id:/event:/data: records and ended by a reconnect record when the credential ends. The schema describes one decoded frame, the data: JSON of a single record with the record's event: type folded in, not the byte stream as a whole.

Errors 400, 401, 402, 403, 404, 429, 500, 503. See Errors.

# Server-sent events, held open. One stream for every itinerary, zone and
# collection in the organization, so a list view stays current without polling.
curl -sN https://api.mountaya.com/v1/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b/events \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token"