Fleet & trips

Partner fleet positions and passenger trip sharing.

POST/v1/fleet/positionsPlanned

Publish vehicle positions (HTTP alternative to the stream `pub` op)

Host: https://api.atasumaps.com · publishFleetPositions
Access: API key with scope: fleet
Metering: realtime_msg (per message)
Idempotency-Key: Required: one key per command; a retry returns the first result

Server key only. Positions go to the organization's fleet channel and to subscribers of active trips of that vehicle; never to public channels. Snap to roads first (/v1/snap) for smooth display. Precise positions are not logged and are kept only as long as the trip needs.

Parameters

Name	In	Type	Required	Description
`Idempotency-Key`	header	`string`	yes	Client-generated unique key per logical command (UUID v4/v7 recommended). Scope: caller + endpoint + key. Same key + same body → first result (`Idempotent-Replayed: true`); same key + different body → `409 idempotency_key_reused`. Missing → `400 idempotency_key_required`. Keys are kept at least 24 hours.

Request body `FleetPositionBatch`

Name	Type	Required	Description
`positions`	`FleetPosition[]`	yes

Responses

Status	Description	Type
`202`	Accepted
`400`	Invalid request (`invalid_request`, `idempotency_key_required`, `limit_exceeded`, `future_departure_not_supported`, `observation_in_future`)	`Problem`
`401`	Missing or invalid credentials (`unauthenticated`, `key_invalid`, `key_revoked`, `token_expired`, `token_invalid`)	`Problem`
`402`	A budget cap is reached and no degraded answer exists (`budget_exhausted`; `context.level` is `organization` or `product`, `context.product` the product)	`Problem`
`403`	Authenticated but not allowed (`scope_denied`, `key_restriction_failed`, `forbidden`, `user_banned`, `mfa_required`, `self_moderation_forbidden`, `feature_disabled`)	`Problem`
`409`	Conflict — never a silent overwrite. Codes: `idempotency_key_reused` (same key, different body), `version_conflict` (stale `expected_version`; body has `current_version`), `invalid_state` (transition not allowed from the current status), `appeal_already_used`, `base_version_stale` (place changed since the edit's baseline; rebase first), `later_edits_exist` (revert needs compensation), `already_claimed`, `last_owner`, `already_member`, `deletion_pending`. A retry with the original `Idempotency-Key` still returns the original result, never a 409.	`Problem`
`429`	Rate limit (`rate_limited`) or monthly plan quota (`quota_exceeded`: `reject` plans only; `Retry-After` = seconds until the next Asia/Almaty month; `context` = `product`, `included`, `used`, `period_end`)	`Problem`

POST/v1/tripsPlanned

Start sharing a trip (vehicle ↔ passenger)

Host: https://api.atasumaps.com · createTrip
Access: API key with scope: fleet
Metering: Not metered
Idempotency-Key: Required: one key per command; a retry returns the first result

Server key with fleet scope. The trip belongs to the key's organization; only that organization and the trip's passenger (with a ticket) can see it.

Parameters

Name	In	Type	Required	Description
`Idempotency-Key`	header	`string`	yes	Client-generated unique key per logical command (UUID v4/v7 recommended). Scope: caller + endpoint + key. Same key + same body → first result (`Idempotent-Replayed: true`); same key + different body → `409 idempotency_key_reused`. Missing → `400 idempotency_key_required`. Keys are kept at least 24 hours.

Request body `TripCreate`

Name	Type	Required	Description
`fleet_id`	`string`
`vehicle_id`	`string`	yes
`passenger_ref`	`string`	yes	Partner's opaque passenger ID (no personal data)
`external_ref`	`string`		Partner's order ID
`pickup`	`Waypoint`		Exactly one of `lnglat`, `place_id`, `entrance_id`. A `place_id` destination resolves to an evidence-backed entrance / pickup point for the costing, else the building or street.
`dropoff`	`Waypoint`		Exactly one of `lnglat`, `place_id`, `entrance_id`. A `place_id` destination resolves to an evidence-backed entrance / pickup point for the costing, else the building or street.
`expires_at`	`string (date-time)`		Hard end; default 6 hours after creation

Responses

Status	Description	Type
`201`	Trip	`Trip`
`400`	Invalid request (`invalid_request`, `idempotency_key_required`, `limit_exceeded`, `future_departure_not_supported`, `observation_in_future`)	`Problem`
`401`	Missing or invalid credentials (`unauthenticated`, `key_invalid`, `key_revoked`, `token_expired`, `token_invalid`)	`Problem`
`403`	Authenticated but not allowed (`scope_denied`, `key_restriction_failed`, `forbidden`, `user_banned`, `mfa_required`, `self_moderation_forbidden`, `feature_disabled`)	`Problem`
`409`	Conflict — never a silent overwrite. Codes: `idempotency_key_reused` (same key, different body), `version_conflict` (stale `expected_version`; body has `current_version`), `invalid_state` (transition not allowed from the current status), `appeal_already_used`, `base_version_stale` (place changed since the edit's baseline; rebase first), `later_edits_exist` (revert needs compensation), `already_claimed`, `last_owner`, `already_member`, `deletion_pending`. A retry with the original `Idempotency-Key` still returns the original result, never a 409.	`Problem`

POST/v1/trips/{trip_id}/ticketsPlanned

Issue a short-lived passenger ticket for a trip

Host: https://api.atasumaps.com · createTripTicket
Access: API key with scope: fleet
Metering: Not metered
Idempotency-Key: Required: one key per command; a retry returns the first result

The partner backend issues a ticket bound to (passenger, trip) and hands it to its app; the app presents it on the stream to subscribe to trip (WEBSOCKET.md). Tickets expire with the trip or after ttl_s, whichever comes first.

Parameters

Name	In	Type	Required	Description
`trip_id`	path	`string`	yes
`Idempotency-Key`	header	`string`	yes	Client-generated unique key per logical command (UUID v4/v7 recommended). Scope: caller + endpoint + key. Same key + same body → first result (`Idempotent-Replayed: true`); same key + different body → `409 idempotency_key_reused`. Missing → `400 idempotency_key_required`. Keys are kept at least 24 hours.

Request body `TripTicketCreate`

Name	Type	Required	Description
`passenger_ref`	`string`	yes	Must equal the trip's passenger
`ttl_s`	`integer`

Responses

Status	Description	Type
`201`	Ticket (shown once)	`TripTicket`
`401`	Missing or invalid credentials (`unauthenticated`, `key_invalid`, `key_revoked`, `token_expired`, `token_invalid`)	`Problem`
`403`	Authenticated but not allowed (`scope_denied`, `key_restriction_failed`, `forbidden`, `user_banned`, `mfa_required`, `self_moderation_forbidden`, `feature_disabled`)	`Problem`
`404`	No such resource, or not visible to the caller (`not_found`)	`Problem`
`409`	Conflict — never a silent overwrite. Codes: `idempotency_key_reused` (same key, different body), `version_conflict` (stale `expected_version`; body has `current_version`), `invalid_state` (transition not allowed from the current status), `appeal_already_used`, `base_version_stale` (place changed since the edit's baseline; rebase first), `later_edits_exist` (revert needs compensation), `already_claimed`, `last_owner`, `already_member`, `deletion_pending`. A retry with the original `Idempotency-Key` still returns the original result, never a 409.	`Problem`

POST/v1/trips/{trip_id}/endPlanned

End a trip; tickets stop working and subscribers get a tombstone

Host: https://api.atasumaps.com · endTrip
Access: API key with scope: fleet
Metering: Not metered
Idempotency-Key: Required: one key per command; a retry returns the first result

Parameters

Name	In	Type	Required	Description
`trip_id`	path	`string`	yes
`Idempotency-Key`	header	`string`	yes	Client-generated unique key per logical command (UUID v4/v7 recommended). Scope: caller + endpoint + key. Same key + same body → first result (`Idempotent-Replayed: true`); same key + different body → `409 idempotency_key_reused`. Missing → `400 idempotency_key_required`. Keys are kept at least 24 hours.

Responses

Status	Description	Type
`200`	Ended trip	`Trip`
`401`	Missing or invalid credentials (`unauthenticated`, `key_invalid`, `key_revoked`, `token_expired`, `token_invalid`)	`Problem`
`403`	Authenticated but not allowed (`scope_denied`, `key_restriction_failed`, `forbidden`, `user_banned`, `mfa_required`, `self_moderation_forbidden`, `feature_disabled`)	`Problem`
`404`	No such resource, or not visible to the caller (`not_found`)	`Problem`
`409`	Conflict — never a silent overwrite. Codes: `idempotency_key_reused` (same key, different body), `version_conflict` (stale `expected_version`; body has `current_version`), `invalid_state` (transition not allowed from the current status), `appeal_already_used`, `base_version_stale` (place changed since the edit's baseline; rebase first), `later_edits_exist` (revert needs compensation), `already_claimed`, `last_owner`, `already_member`, `deletion_pending`. A retry with the original `Idempotency-Key` still returns the original result, never a 409.	`Problem`

Fleet & trips

Publish vehicle positions (HTTP alternative to the stream `pub` op)

Parameters

Request body FleetPositionBatch

Responses

Start sharing a trip (vehicle ↔ passenger)

Parameters

Request body TripCreate

Responses

Issue a short-lived passenger ticket for a trip

Parameters

Request body TripTicketCreate

Responses

End a trip; tickets stop working and subscribers get a tombstone

Parameters

Responses

Request body `FleetPositionBatch`

Request body `TripCreate`

Request body `TripTicketCreate`