POST/v1/tripsIdempotency-Key required

Create a trip

Crée une course confirmée. Pour un compte DRIVER, vous êtes l'exécutant de la course. Pour un CONTRACTOR, la course est créée non-assignée — vous transférerez plus tard via le tableau de bord.

Body fields

Name	Type	Required	Description
`pickup`	object { address, lat, lng }	required	Pickup point. lat/lng must come from your own geocoder.
`dropoff`	object { address, lat, lng }	required	Drop-off point.
`scheduledAt`	string (ISO 8601)	required	Future pickup time. Past values are rejected.
`price`	number (EUR)	required	Price the rider will be charged, in EUR (TTC). Use the value returned by /v1/quotes.
`client`	object { firstName, lastName, phone?, email? }	optional	New rider. Either client or clientId is required. Phone or email must be set.
`clientId`	string (Mongo ID)	optional	Existing rider in your account.
`paxNumber`	integer (1-20)	optional	Number of passengers. Defaults to 1.
`note`	string (≤ 2000 chars)	optional	Free-text note for the driver.
`serviceTierId`	string (Mongo ID)	optional	Vehicle category.
`vehicleId`	string (Mongo ID)	optional	Specific vehicle to use. Must belong to the caller.
`pricingSchemeId`	string (Mongo ID)	optional	Pricing scheme. Must belong to the caller.
`tripType`	"TRIP" \| "AVAILABILITY"	optional	See /v1/quotes.

Response fields

Name	Type	Required	Description
`data._id`	string	required	Trip identifier — store this for follow-up calls.
`data.status`	string	required	Initial status. Always "CONFIRMED" right after creation.
`data.userId`	string	required	Owner — same as the calling user.

Example

curl -X POST https://api.mastro.app/v1/trips \
  -H "Authorization: Bearer $MASTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "pickup": { "address": "10 rue de Rivoli, 75004 Paris", "lat": 48.8559, "lng": 2.3590 },
    "dropoff": { "address": "Aéroport CDG", "lat": 49.0097, "lng": 2.5479 },
    "scheduledAt": "2026-05-12T08:30:00Z",
    "price": 95.50,
    "client": { "firstName": "Marie", "lastName": "Durand", "phone": "+33612345678" }
  }'

Error codes

IDEMPOTENCY_KEY_REQUIREDIDEMPOTENCY_KEY_CONFLICTIDEMPOTENCY_KEY_IN_PROGRESSCLIENT_REQUIREDVEHICLE_NOT_FOUNDPRICING_SCHEME_NOT_FOUNDRATE_LIMITED

GET/v1/trips

List your trips

Liste paginée de vos courses, filtrable par statut, plage de dates et tri implicite par date de création décroissante.

Query parameters

Name	Type	Required	Description
`page`	integer (≥1)	optional	Page number, default 1.
`limit`	integer (1-100)	optional	Page size, default 20.
`status`	TripStatus enum	optional	CONFIRMED · OTWTP · OTWTD · FINISHED · FINISHED_PAYED · CANCELLED.
`from`	string (ISO 8601)	optional	Earliest scheduled pickup.
`to`	string (ISO 8601)	optional	Latest scheduled pickup.

Example

curl -G https://api.mastro.app/v1/trips \
  -H "Authorization: Bearer $MASTRO_API_KEY" \
  --data-urlencode "status=CONFIRMED" \
  --data-urlencode "limit=50"

GET/v1/trips/:id

Get a single trip

Détails complets d'une course, y compris l'historique de statuts. Renvoie 404 si la course n'existe pas ou ne vous appartient pas.

Path parameters

Name	Type	Required	Description
`id`	string (Mongo ID)	required	Trip identifier.

Example

curl https://api.mastro.app/v1/trips/65b3f4e8d1c2a3b4e5f60718 \
  -H "Authorization: Bearer $MASTRO_API_KEY"

POST/v1/trips/:id/cancel

Cancel a trip

Passe la course en statut CANCELLED. Idempotent : un second appel sur une course déjà annulée renvoie TRIP_ALREADY_CANCELLED.

Path parameters

Name	Type	Required	Description
`id`	string (Mongo ID)	required	Trip identifier.

Body fields

Name	Type	Required	Description
`reason`	string (≤ 500 chars)	optional	Free-text cancellation reason. Stored only as length in operator logs (privacy).

Example

curl -X POST https://api.mastro.app/v1/trips/65b3f4e8d1c2a3b4e5f60718/cancel \
  -H "Authorization: Bearer $MASTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "client cancelled" }'

Error codes

TRIP_ALREADY_CANCELLEDRATE_LIMITED