API reference

Reservations

A spot held for one vehicle in one staging area. It is held until the vehicle arrives or the hold runs out; then the vehicle checks in, and later checks out.

A reservation moves through these statuses, and never back: held to checked_in to checked_out. A held reservation can instead end as expired (the vehicle did not arrive in time) or cancelled (by you, or by the staging area closing).

The reservation object

idstringrequired

Unique, starting res_.

object"reservation"required

vehicle_idstringrequired

Your own name for the vehicle. We only use it to tell your vehicles apart.

staging_areastringrequired

The staging area's id.

spotstringrequired

The spot held, as it is marked in the staging area.

locationpointrequired

Where the spot is.

latnumberrequired

Latitude, WGS 84.

lngnumberrequired

Longitude, WGS 84.

statusenumrequired

held: a spot is kept for the vehicle. checked_in: the vehicle is in its spot. checked_out: it has left. expired: it did not arrive before held_until. cancelled: given up before it arrived.

One of held, checked_in, checked_out, expired, cancelled.

arrive_bytimestamprequired

When you said the vehicle would arrive.

held_untiltimestamprequired

When the hold runs out: arrive_by plus the staging area's hold_minutes.

checked_in_attimestamp or null

leave_bytimestamp or null

Set at check-in: when the vehicle has to leave. Null while it may stay as long as it likes. Moved to the moment it closes if the staging area closes suddenly.

checked_out_attimestamp or null

cancellation_reasonenum

Why it was cancelled: you asked, or the staging area closed.

One of requested, staging_area_closed.

metadataobject

Your own key-value pairs: up to 20, keys up to 40 characters, values up to 500. We store them and return them; we never read them.

created_attimestamprequired

The reservation object

{
  "id": "res_8f2c41",
  "object": "reservation",
  "vehicle_id": "rt-0417",
  "staging_area": "sa_norreport",
  "spot": "2",
  "location": {
    "lat": 55.6838,
    "lng": 12.5721
  },
  "status": "held",
  "arrive_by": "2026-11-02T14:02:00Z",
  "held_until": "2026-11-02T14:07:00Z",
  "checked_in_at": null,
  "leave_by": null,
  "checked_out_at": null,
  "cancellation_reason": null,
  "metadata": {},
  "created_at": "2026-11-02T13:51:12Z"
}

Reserve a spot

POST/v1/reservations

Holds a spot in the staging area you name, for one vehicle, until held_until. The vehicle should check in before then, or the hold runs out and the spot goes to whoever is next.

If the staging area is full or closed, nothing is held and the error offers others nearby with room. A planned closure counts: a spot in one of its closures is not held for a time inside it. Send an Idempotency-Key, so a request sent twice reserves once.

Body

vehicle_idstringrequired

Your own name for the vehicle, up to 64 characters.

staging_areastringrequired

The staging area's id.

arrive_bytimestamprequired

When the vehicle will arrive.

metadataobject

Your own key-value pairs: up to 20, keys up to 40 characters, values up to 500.

vehicle_length_mnumber

The vehicle's length in metres. Checked against the staging area's max_vehicle_length_m, if it has one.

Headers

Idempotency-Keystring, header

A unique key, such as a UUID, for this request. Send the same key when you retry: the request takes effect once, and the retry gets the first answer back. Kept for 24 hours. The same key with a different body is refused with idempotency_key_reused (422).

Responses

201

The reservation, held.

409

no_spot_available

The staging area is full at that time. alternatives lists others nearby with room.

409

staging_area_closed

The staging area is closed at that time. alternatives lists others nearby with room.

404

not_found

No staging area with this id is open to your fleet.

409

vehicle_already_reserved

The vehicle already has a reservation that is held or checked in.

422

arrive_by_out_of_range

arrive_by is in the past, or more than the staging area's book_ahead_minutes ahead.

422

vehicle_too_large

vehicle_length_m is longer than the staging area's max_vehicle_length_m.

Endpoint

POST https://api.golanoo.com/v1/reservations

Request

curl -X POST https://api.golanoo.com/v1/reservations \
  -H "Authorization: Bearer lk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "vehicle_id": "rt-0417",
    "staging_area": "sa_norreport",
    "arrive_by": "2026-11-02T14:02:00Z"
  }'

Response

{
  "id": "res_8f2c41",
  "object": "reservation",
  "vehicle_id": "rt-0417",
  "staging_area": "sa_norreport",
  "spot": "2",
  "location": {
    "lat": 55.6838,
    "lng": 12.5721
  },
  "status": "held",
  "arrive_by": "2026-11-02T14:02:00Z",
  "held_until": "2026-11-02T14:07:00Z",
  "checked_in_at": null,
  "leave_by": null,
  "checked_out_at": null,
  "cancellation_reason": null,
  "metadata": {},
  "created_at": "2026-11-02T13:51:12Z"
}

List reservations

GET/v1/reservations

Your fleet's reservations, newest first. You only ever see your own.

Parameters

statusenum

Only reservations with this status.

vehicle_idstring

Only this vehicle's reservations.

staging_areastring

Only reservations in this staging area.

limitinteger

How many to return, 1 to 100. Defaults to 20.

starting_afterstring

For the next page, the id of the last item on this one.

Responses

200

A page of reservations.

Endpoint

GET https://api.golanoo.com/v1/reservations

Request

curl https://api.golanoo.com/v1/reservations \
  -H "Authorization: Bearer lk_test_..."

Response

{
  "object": "list",
  "data": [
    {
      "id": "res_8f2c41",
      "object": "reservation",
      "vehicle_id": "rt-0417",
      "staging_area": "sa_norreport",
      "spot": "2",
      "location": {
        "lat": 55.6838,
        "lng": 12.5721
      },
      "status": "held",
      "arrive_by": "2026-11-02T14:02:00Z",
      "held_until": "2026-11-02T14:02:00Z",
      "checked_in_at": "2026-11-02T14:02:00Z",
      "leave_by": "2026-11-02T14:02:00Z",
      "checked_out_at": "2026-11-02T14:02:00Z",
      "cancellation_reason": "requested",
      "metadata": {},
      "created_at": "2026-11-02T14:02:00Z"
    }
  ],
  "has_more": true
}

Get a reservation

GET/v1/reservations/{id}

Parameters

idstring, pathrequired

The reservation's id.

Responses

200

The reservation.

404

not_found

No reservation with this id belongs to your fleet.

Endpoint

GET https://api.golanoo.com/v1/reservations/{id}

Request

curl https://api.golanoo.com/v1/reservations/res_8f2c41 \
  -H "Authorization: Bearer lk_test_..."

Response

{
  "id": "res_8f2c41",
  "object": "reservation",
  "vehicle_id": "rt-0417",
  "staging_area": "sa_norreport",
  "spot": "2",
  "location": {
    "lat": 55.6838,
    "lng": 12.5721
  },
  "status": "held",
  "arrive_by": "2026-11-02T14:02:00Z",
  "held_until": "2026-11-02T14:02:00Z",
  "checked_in_at": "2026-11-02T14:02:00Z",
  "leave_by": "2026-11-02T14:02:00Z",
  "checked_out_at": "2026-11-02T14:02:00Z",
  "cancellation_reason": "requested",
  "metadata": {},
  "created_at": "2026-11-02T14:02:00Z"
}

Change the arrival time

PATCH/v1/reservations/{id}

For a vehicle running late or early. Only a held reservation can be changed. The spot stays the same if it is free at the new time; otherwise nothing changes and the error says so.

Parameters

idstring, pathrequired

The reservation's id.

Body

arrive_bytimestamprequired

The new arrival time.

Headers

Idempotency-Keystring, header

Responses

200

The reservation, with its new arrive_by and held_until.

404

not_found

No reservation with this id belongs to your fleet.

409

no_spot_available

No spot is free at the new time. The reservation is unchanged; alternatives lists others nearby with room.

409

staging_area_closed

The staging area is closed at the new time. The reservation is unchanged; alternatives lists others nearby with room.

409

reservation_not_held

The reservation is no longer held.

422

arrive_by_out_of_range

arrive_by is in the past, or more than the staging area's book_ahead_minutes ahead.

Endpoint

PATCH https://api.golanoo.com/v1/reservations/{id}

Request

curl -X PATCH https://api.golanoo.com/v1/reservations/res_8f2c41 \
  -H "Authorization: Bearer lk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "arrive_by": "2026-11-02T14:10:00Z"
  }'

Response

{
  "id": "res_8f2c41",
  "object": "reservation",
  "vehicle_id": "rt-0417",
  "staging_area": "sa_norreport",
  "spot": "2",
  "location": {
    "lat": 55.6838,
    "lng": 12.5721
  },
  "status": "held",
  "arrive_by": "2026-11-02T14:02:00Z",
  "held_until": "2026-11-02T14:02:00Z",
  "checked_in_at": "2026-11-02T14:02:00Z",
  "leave_by": "2026-11-02T14:02:00Z",
  "checked_out_at": "2026-11-02T14:02:00Z",
  "cancellation_reason": "requested",
  "metadata": {},
  "created_at": "2026-11-02T14:02:00Z"
}

Check in

POST/v1/reservations/{id}/check_in

The vehicle is in its spot. It can check in any time while the reservation is held, early too. From now it may stay until leave_by: the staging area's max_stay_minutes from now, or the start of a planned closure of its spot, if that comes first. With no limit and no closure planned, leave_by is null and the vehicle may stay as long as it likes.

Parameters

idstring, pathrequired

The reservation's id.

Headers

Idempotency-Keystring, header

Responses

200

The reservation, checked in.

404

not_found

No reservation with this id belongs to your fleet.

409

hold_expired

The hold ran out before the vehicle checked in: the reservation is expired. Reserve again.

409

reservation_not_held

The reservation is already checked in, checked out or cancelled.

Endpoint

POST https://api.golanoo.com/v1/reservations/{id}/check_in

Request

curl -X POST https://api.golanoo.com/v1/reservations/res_8f2c41/check_in \
  -H "Authorization: Bearer lk_test_..." \
  -H "Idempotency-Key: $(uuidgen)"

Response

{
  "id": "res_8f2c41",
  "object": "reservation",
  "vehicle_id": "rt-0417",
  "staging_area": "sa_norreport",
  "spot": "2",
  "location": {
    "lat": 55.6838,
    "lng": 12.5721
  },
  "status": "checked_in",
  "arrive_by": "2026-11-02T14:02:00Z",
  "held_until": "2026-11-02T14:07:00Z",
  "checked_in_at": "2026-11-02T14:01:37Z",
  "leave_by": "2026-11-02T14:46:37Z",
  "checked_out_at": null,
  "cancellation_reason": null,
  "metadata": {},
  "created_at": "2026-11-02T13:51:12Z"
}

Check out

POST/v1/reservations/{id}/check_out

The vehicle has left its spot. The spot frees up for whoever is next. A vehicle past leave_by checks out the same way.

Parameters

idstring, pathrequired

The reservation's id.

Headers

Idempotency-Keystring, header

Responses

200

The reservation, checked out.

404

not_found

No reservation with this id belongs to your fleet.

409

reservation_not_checked_in

The reservation is not checked in: it is still held (cancel it instead), or it has already ended.

Endpoint

POST https://api.golanoo.com/v1/reservations/{id}/check_out

Request

curl -X POST https://api.golanoo.com/v1/reservations/res_8f2c41/check_out \
  -H "Authorization: Bearer lk_test_..." \
  -H "Idempotency-Key: $(uuidgen)"

Response

{
  "id": "res_8f2c41",
  "object": "reservation",
  "vehicle_id": "rt-0417",
  "staging_area": "sa_norreport",
  "spot": "2",
  "location": {
    "lat": 55.6838,
    "lng": 12.5721
  },
  "status": "checked_out",
  "arrive_by": "2026-11-02T14:02:00Z",
  "held_until": "2026-11-02T14:07:00Z",
  "checked_in_at": "2026-11-02T14:01:37Z",
  "leave_by": "2026-11-02T14:46:37Z",
  "checked_out_at": "2026-11-02T14:23:05Z",
  "cancellation_reason": null,
  "metadata": {},
  "created_at": "2026-11-02T13:51:12Z"
}

Cancel a reservation

POST/v1/reservations/{id}/cancel

Gives up a held spot before the vehicle arrives.

Parameters

idstring, pathrequired

The reservation's id.

Headers

Idempotency-Keystring, header

Responses

200

The reservation, cancelled.

404

not_found

No reservation with this id belongs to your fleet.

409

reservation_not_held

Only a held reservation can be cancelled. A checked-in vehicle checks out.

Endpoint

POST https://api.golanoo.com/v1/reservations/{id}/cancel

Request

curl -X POST https://api.golanoo.com/v1/reservations/res_8f2c41/cancel \
  -H "Authorization: Bearer lk_test_..." \
  -H "Idempotency-Key: $(uuidgen)"

Response

{
  "id": "res_8f2c41",
  "object": "reservation",
  "vehicle_id": "rt-0417",
  "staging_area": "sa_norreport",
  "spot": "2",
  "location": {
    "lat": 55.6838,
    "lng": 12.5721
  },
  "status": "cancelled",
  "arrive_by": "2026-11-02T14:02:00Z",
  "held_until": "2026-11-02T14:07:00Z",
  "checked_in_at": null,
  "leave_by": null,
  "checked_out_at": null,
  "cancellation_reason": "requested",
  "metadata": {},
  "created_at": "2026-11-02T13:51:12Z"
}