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.
/v1/itineraries/{itinerary_id}/eventsOpens 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_idstring (uuid)
in path
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-IDstring
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.
/v1/itineraries/{itinerary_id}/collabSends 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_idstring (uuid)
in path
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.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataany | null
Always null: this operation answers with no payload.
Errors 400, 401, 402, 403, 404, 409, 413, 429, 500, 504. See Errors.
/v1/zones/{zone_id}/eventsOpens 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_idstring (uuid)
in path
Identifier of the zone the operation acts on.
Headers
Last-Event-IDstring
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.
/v1/zones/{zone_id}/collabSends 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_idstring (uuid)
in path
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.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataany | null
Always null: this operation answers with no payload.
Errors 400, 401, 402, 403, 404, 409, 413, 429, 500, 504. See Errors.
/v1/organizations/{organization_id}/eventsOpens 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_idstring (uuid)
in path
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-IDstring
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.