> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.goautolane.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.goautolane.com/_mcp/server.

# Report bot status

POST https://api.goautolane.com/rs/v1/reservations/{id}/bot
Content-Type: application/json

Reports where your bot is for this reservation. Statuses move forward only (`INBOUND`, `ARRIVED`, `READY_FOR_HANDOFF`, `SECURED`, `DEPARTED`; any may be skipped); `ABORTED` is accepted before `SECURED` and is final. Repeating the current status is a `200` and still updates `label` and `eta`. A status behind the current one is `409 BOT_STATUS_REGRESSION`. On a `completed` or `canceled` reservation only a repeat is accepted; anything else is `409 INVALID_STATE`.

Side effects land in the same transaction as the report and fire the matching webhooks: `ARRIVED` or later marks a `confirmed` reservation `arrived`; `READY_FOR_HANDOFF` opens the handoff for a runner waiting at your bot; `SECURED` ends the runner's task (loaded if the compartment was opened, otherwise the order goes back to the counter; an open still in flight is waited for); `DEPARTED` completes the reservation; `ABORTED` flags or fails the runner's task and leaves the reservation open until you cancel it or its window expires. The status table in the Reservations guide has the per-status detail.

Reference: https://docs.goautolane.com/reservations/api-reference/reservations/assert-bot-status

## Authentication

- `Authorization` header (bearer token, required) — API key generated in the Autolane Portal. Keys are organization-scoped, carry granular permissions, and are environment-specific: a sandbox key only works against the sandbox host, and a production key only against the production host.

## Servers

- `https://api.goautolane.com` (Production, default)
- `https://api-sandbox.goautolane.com` (Sandbox)

## Request

### Path parameters

- `id` (string, required) — Reservation id

### Body (application/json)

This endpoint expects an AssertBotStatusBody.

- `status` (enum, required) — Forward only, in this order: INBOUND, ARRIVED, READY_FOR_HANDOFF, SECURED, DEPARTED. ABORTED is accepted from any status before SECURED and is final.
  - Allowed values: `INBOUND`, `ARRIVED`, `READY_FOR_HANDOFF`, `SECURED`, `DEPARTED`, `ABORTED`
- `label` (string, optional) — Your identifier for the bot, shown to the runner; updated on every accepted report
- `eta` (datetime, optional) — When the bot expects to reach the stall (RFC 3339 with offset). Must be within 24 hours of now on either side (a deployment default, tunable per environment); re-anchors the runner's staging time while no runner has been dispatched
- `occurred_at` (datetime, optional) — When the status became true on your side (RFC 3339 with offset). Defaults to now; may not be more than five minutes in the future
- `reason` (string, optional) — Free text for ABORTED, recorded with the task exception

## Response

### 200

The reservation with its updated bot block (and handoff block, if the report moved the runner's task)

- `success` (boolean, required)
- `data` (ReservationResponseData, required)

## Errors

### 400 Bad Request Error

The id is not a UUID, the body is invalid JSON or fails validation, eta is more than 24 hours from now, or `occurred_at` is more than five minutes in the future (`VALIDATION_ERROR`)

- `success` (boolean, required)
- `error` (string, required) — Human-readable error message
- `code` (string, required) — Stable machine-readable error code

### 401 Unauthorized Error

Missing or invalid API key (`INVALID_API_KEY`)

- `success` (boolean, required)
- `error` (string, required) — Human-readable error message
- `code` (string, required) — Stable machine-readable error code

### 403 Forbidden Error

Key valid but not usable here: wrong environment (`WRONG_ENV_KEY`), missing `reservations:write` permission (`PERMISSION_DENIED`), the organization is not enrolled as a fleet partner (`NOT_FLEET_PARTNER`), or the organization is deactivated or not yet provisioned in this environment (`ORG_INACTIVE`)

- `success` (boolean, required)
- `error` (string, required) — Human-readable error message
- `code` (string, required) — Stable machine-readable error code

### 404 Not Found Error

No such reservation for your organization (`RESERVATION_NOT_FOUND`). A reservation owned by another organization returns this same 404, never a 403, so ids cannot be probed.

- `success` (boolean, required)
- `error` (string, required) — Human-readable error message
- `code` (string, required) — Stable machine-readable error code

### 409 Conflict Error

`BOT_STATUS_REGRESSION`: the status is behind the current one; it was recorded but not applied. `INVALID_STATE`: the reservation is `completed` or `canceled` and this is not a repeat of its current bot status.

- `success` (boolean, required)
- `error` (string, required) — Human-readable error message
- `code` (string, required) — Stable machine-readable error code

### 500 Internal Server Error

Internal error (`INTERNAL_ERROR`)

- `success` (boolean, required)
- `error` (string, required) — Human-readable error message
- `code` (string, required) — Stable machine-readable error code

## Types

### ReservationResponseData

- `reservation` (Reservation, required)

### Reservation

- `reservation_id` (string, required)
- `status` (enum, required)
  - Allowed values: `requested`, `confirmed`, `arrived`, `completed`, `canceled`
- `zone_id` (string, required)
- `stall_id` (string, required)
- `stall_label` (string, required, nullable) — Human-readable stall label, e.g. "Blue 3"
- `retailer_id` (string, required)
- `order_number` (string, required)
- `end_user_name` (string, required)
- `end_user_phone` (string, required) — E.164
- `arrival_window_start` (datetime, required)
- `arrival_window_end` (datetime, required)
- `open_link_url` (string, required)
- `canceled_by` (string, required, nullable) — Who canceled: partner, runner, ops, or system. Null unless the reservation is canceled.
- `cancel_reason` (string, required, nullable) — Why the reservation was canceled: the free-text reason you sent on DELETE, echoed back, or window_expired when the system canceled it because the arrival window had passed by the grace period, or a reason entered by Autolane operations when they canceled it (1 to 500 characters, delivered here and on reservation.status_changed). Null while the reservation is not canceled, and null when it was canceled without a reason.
- `retailer_pickup_ref` (string, required, nullable) — What the runner says at the retailer counter; the order number is used when null
- `payload_limit` (PayloadLimit, required, nullable) — Size and weight the bot compartment accepts. Sent on create and echoed on every read; its presence turns on the runner's pre-collect check at the counter. Every measure is positive and at most 1000 (kilograms or centimetres).
- `bot` (Bot, required, nullable) — Your last accepted bot status report. Null until the first one.
- `handoff` (Handoff, required, nullable) — The runner's progress carrying the order to your bot. Null when the reservation has no runner task.
- `created_at` (datetime, required)
- `updated_at` (datetime, required)

### PayloadLimit

Size and weight the bot compartment accepts. Sent on create and echoed on every read; its presence turns on the runner's pre-collect check at the counter. Every measure is positive and at most 1000 (kilograms or centimetres).

- `max_weight_kg` (double, optional)
- `max_dimensions_cm` (PayloadLimitMaxDimensionsCm, optional)

### Bot

Your last accepted bot status report. Null until the first one.

- `status` (enum, required) — Forward only, in this order: INBOUND, ARRIVED, READY_FOR_HANDOFF, SECURED, DEPARTED. ABORTED is accepted from any status before SECURED and is final.
  - Allowed values: `INBOUND`, `ARRIVED`, `READY_FOR_HANDOFF`, `SECURED`, `DEPARTED`, `ABORTED`
- `label` (string, required, nullable) — Display label you supplied so the runner can pick your bot out at the pad. Never a gate: the open link guarantees the right compartment.
- `eta` (datetime, required, nullable) — Your latest arrival estimate; anchors the runner's staging time while no runner is dispatched yet
- `asserted_at` (datetime, required, nullable) — When the current status was reached (your occurred_at, or the time we received it)

### Handoff

The runner's progress carrying the order to your bot. Null when the reservation has no runner task.

- `status` (enum, required) — Runner task status. QUEUED (waiting for a runner), ASSIGNED, AT_STORE, HELD (order not ready yet), RETRIEVED (order in hand), AT_UNIT (runner at your bot), HANDOFF_READY (compartment may be opened), LOADED, CANCELED, FAILED.
  - Allowed values: `QUEUED`, `ASSIGNED`, `AT_STORE`, `HELD`, `RETRIEVED`, `AT_UNIT`, `HANDOFF_READY`, `LOADED`, `CANCELED`, `FAILED`
- `task_started_at` (datetime, required, nullable)
- `order_in_hand_at` (datetime, required, nullable)
- `ready_estimate` (datetime, required, nullable) — When the counter said the order would be ready, if the runner is holding
- `runner_at_unit_at` (datetime, required, nullable)
- `handoff_completed_at` (datetime, required, nullable)
- `load_photo_url` (string, required, nullable) — Signed, time-limited link to the load photo, valid for 24 hours by default, counted from when the link was signed (at the runner's load, before the webhook is queued) for the webhook and from the read for GET. Set on GET /rs/v1/reservations/\{id} and on the reservation.handoff\_updated webhook with milestone handoff\_complete, and on the sandbox advance endpoint's response for its load step; null until the photo lands, and null in every other webhook and response. The webhook carries null when the link could not be minted at that moment (load\_photo\_skipped false, handoff\_completed\_at set); fetch the reservation for a link. Photos are kept for a limited period set per environment (90 days by default), after which the link answers 404 and fetching again does not help. The link expires, so fetch the reservation for a fresh one.
- `load_photo_skipped` (boolean, required, nullable) — True when the load was recorded without a photo, for example because your bot reported SECURED before the runner's photo landed. Null until a load is recorded.
- `runner_delay_seconds` (integer, required, nullable) — How late the runner is against the staging time while still waiting or dispatched. Null when not late.

### PayloadLimitMaxDimensionsCm

- `length` (double, required)
- `width` (double, required)
- `height` (double, required)

## Examples

**Request**

```json
{
  "status": "INBOUND"
}
```

**Response**

```json
{
  "success": true,
  "data": {
    "reservation": {
      "reservation_id": "string",
      "status": "requested",
      "zone_id": "string",
      "stall_id": "string",
      "stall_label": "string",
      "retailer_id": "string",
      "order_number": "string",
      "end_user_name": "string",
      "end_user_phone": "+15125550123",
      "arrival_window_start": "2024-01-15T09:30:00Z",
      "arrival_window_end": "2024-01-15T09:30:00Z",
      "open_link_url": "string",
      "canceled_by": "string",
      "cancel_reason": "string",
      "retailer_pickup_ref": "string",
      "payload_limit": {
        "max_weight_kg": 1.1,
        "max_dimensions_cm": {
          "length": 1.1,
          "width": 1.1,
          "height": 1.1
        }
      },
      "bot": {
        "status": "INBOUND",
        "label": "string",
        "eta": "2024-01-15T09:30:00Z",
        "asserted_at": "2024-01-15T09:30:00Z"
      },
      "handoff": {
        "status": "QUEUED",
        "task_started_at": "2024-01-15T09:30:00Z",
        "order_in_hand_at": "2024-01-15T09:30:00Z",
        "ready_estimate": "2024-01-15T09:30:00Z",
        "runner_at_unit_at": "2024-01-15T09:30:00Z",
        "handoff_completed_at": "2024-01-15T09:30:00Z",
        "load_photo_url": "string",
        "load_photo_skipped": true,
        "runner_delay_seconds": 1
      },
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.goautolane.com/rs/v1/reservations/id/bot"

payload = { "status": "INBOUND" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.goautolane.com/rs/v1/reservations/id/bot';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"status":"INBOUND"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.goautolane.com/rs/v1/reservations/id/bot"

	payload := strings.NewReader("{\n  \"status\": \"INBOUND\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.goautolane.com/rs/v1/reservations/id/bot")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"status\": \"INBOUND\"\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.goautolane.com/rs/v1/reservations/id/bot")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"status\": \"INBOUND\"\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.goautolane.com/rs/v1/reservations/id/bot', [
  'body' => '{
  "status": "INBOUND"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.goautolane.com/rs/v1/reservations/id/bot");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"status\": \"INBOUND\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["status": "INBOUND"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.goautolane.com/rs/v1/reservations/id/bot")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```