Authentication
Collector routes use /collect/{workspace}/{action}. Each request must come from the registered website origin or use the workspace server token as a bearer token. Keep server tokens on your backend; never expose them in browser code. Collection also requires an enabled workspace and active website.
Consent and session
POST /collect/{workspace}/session requires a UUID device_id and explicit true values for analytics and personalisation consent. The response includes a short-lived insight capability for the matching workspace and device. Do not start a personalised session without the required consent.
Event collection
POST /collect/{workspace}/signals accepts batches using schema travelspy.batch.v1 with a collector version and up to 20 travelspy.signal.v1 events. Each event has a UUID idempotency key, UTC timestamp, session and device identifiers, context and consent flags. Supported events and attributes are explicitly validated; unknown fields are rejected.
Responses report accepted and duplicate events. The collector only accepts the configured event vocabulary; it is not an open-ended profile or package API.
Live stream and resume
GET /collect/{workspace}/stream provides server-sent events for a valid insight capability. The stream sends a snapshot when no usable cursor is supplied, otherwise it resumes after the supplied sequence. Use Last-Event-ID or the after cursor to reconnect. Connections are bounded and clients should reconnect when they close; a refreshed capability is delivered as an event.
GET /collect/{workspace}/changes returns a bounded JSON change batch for clients that cannot use an SSE stream. The insight capability is scoped to the current workspace and traveller session.
Identity assertions
POST /collect/{workspace}/identity is server-only and accepts schema travelspy.identity.v1, a device UUID, provider key and customer identifier. It links records only through the identifier submitted by your configured integration. It does not discover or verify the same person across devices by itself.
Booking outcomes
POST /collect/{workspace}/bookings accepts schema travelspy.booking.v1 and a confirmed booking associated with an active consented device. Include a provider, booking identifier, monotonically increasing revision, status, ISO currency, integer minor-unit values, cumulative refunded amount and UTC millisecond timestamp. Revisions are idempotent and conflicting updates are rejected.
Browser-origin requests can record confirmed bookings only. Server authentication is required for cancellations and refunds. TravelSpy records outcomes supplied by your booking system; it does not calculate future booking probability or expected booking value.
Deletion and privacy
POST /collect/{workspace}/forget removes the device’s collected subject data. Configure collection and retention with your privacy team, provide only permitted identifiers, and ensure the data sent matches your consent and legal requirements.
Need integration details?
Contact us to confirm workspace access, endpoint configuration and the appropriate schema for your integration.