> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lanesurf.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> You are reading the Lanesurf Agent API docs. Start with /for-ai-agents.md for the rules an agent must follow.
> The API is at https://agent.lanesurf.com and the MCP server at https://agent.lanesurf.com/mcp. Lanesurf doesn't send webhooks: poll.
> Limits: /rate-limits.md. Keys: /api-keys.md. Safe retries: /idempotency.md. Every route on one page: /api-reference.md.
> Always confirm with the person before accepting a carrier offer or bidding on a load. Never reveal an API key, and never show broker contact details to a carrier.
> The full contract is at /openapi.yaml.
> Sign up with POST /v1/signup (carrier or broker, a work email, an MC and/or DOT number), then POST /v1/signup/{signup_id}/verify. Follow next_step on every signup answer.

# API reference

> Every Lanesurf Agent API route and MCP tool on one page: base URL, auth, roles, errors and the OpenAPI contract.

| | |
| - | - |
| Base URL | `https://agent.lanesurf.com` |
| MCP server | `https://agent.lanesurf.com/mcp` (streamable HTTP). See [Connect over MCP](https://docs.lanesurf.com/agents/mcp.md) |
| Auth | `Authorization: Bearer ls_live_…` on every route except signup and `/health`. See [API keys](https://docs.lanesurf.com/api-keys.md) |
| Format | JSON in, JSON out. Request bodies up to 1 MB |
| Contract | [`/openapi.yaml`](https://docs.lanesurf.com/openapi.yaml), OpenAPI 3.1 |
| Version | `/v1` in the path. See [Versioning](https://docs.lanesurf.com/versioning.md) and the [changelog](https://docs.lanesurf.com/changelog.md) |
| Limits | Up to 120 requests per minute per key, counted on each Lanesurf server, so treat it as the most to send. See [Rate limits](https://docs.lanesurf.com/rate-limits.md) |

Broker keys can't call `/v1/carrier/*` and carrier keys can't call `/v1/loads/*` (`403 wrong_role`).
Routes marked **verified** need a verified carrier key (`403 verification_required` otherwise).

## Signup and keys

| Method and path | MCP tool | Key | What it does |
| - | - | - | - |
| [`POST /v1/signup`](https://docs.lanesurf.com/api-reference/authentication/start-signup-carrier-or-broker) | `start_signup` | none | Start signup as a carrier or a brokerage; emails an 8-digit code |
| [`POST /v1/signup/{signup_id}/verify`](https://docs.lanesurf.com/api-reference/authentication/finish-signup-with-the-code) | `verify_signup` | none | Finish signup with the code; returns the API key once |
| [`GET /v1/me`](https://docs.lanesurf.com/api-reference/authentication/who-this-key-belongs-to) | `whoami` | any | Who this key belongs to: role, and a carrier's verification |
| `GET /health` | | none | `{"status": "ok"}` when the service is up |

## Brokers

| Method and path | MCP tool | Key | What it does |
| - | - | - | - |
| [`GET /v1/loads`](https://docs.lanesurf.com/api-reference/broker-loads/list-your-loads) | `list_loads` | broker | Your brokerage's loads posted through the API, newest first, a page at a time |
| [`POST /v1/loads`](https://docs.lanesurf.com/api-reference/broker-loads/post-a-load) | `post_load` | broker | Post a load as JSON fields; Lanesurf starts finding carriers. Needs `Idempotency-Key` |
| [`GET /v1/loads/{id}`](https://docs.lanesurf.com/api-reference/broker-loads/load-status-and-carrier-offers) | `get_load` | broker | Load status and carrier offers |
| [`GET /v1/loads/{id}/outreach`](https://docs.lanesurf.com/api-reference/broker-loads/who-was-contacted-on-a-load) | `load_outreach` | broker | Which carriers Lanesurf contacted on the load |
| [`POST /v1/loads/{id}/offers/{session_id}/accept`](https://docs.lanesurf.com/api-reference/broker-loads/accept-a-carriers-offer) | `accept_offer` | broker | Accept a carrier's offer at the rate the person agreed to |
| [`POST /v1/loads/{id}/offers/{session_id}/decline`](https://docs.lanesurf.com/api-reference/broker-loads/decline-a-carriers-offer) | `decline_offer` | broker | Record that the rep passes on an offer |
| [`POST /v1/loads/{id}/covered`](https://docs.lanesurf.com/api-reference/broker-loads/mark-the-load-covered-elsewhere) | `mark_covered` | broker | The rep covered it elsewhere; Lanesurf stops |
| [`GET /v1/broker/setup`](https://docs.lanesurf.com/api-reference/broker-setup/your-brokerages-setup) | `get_broker_setup` | broker | What Lanesurf's agents tell carriers about the brokerage, and whether outreach is on |
| [`PATCH /v1/broker/setup`](https://docs.lanesurf.com/api-reference/broker-setup/change-your-brokerages-setup) | `update_broker_setup` | broker | Change that setup |

## Carriers

| Method and path | MCP tool | Key | What it does |
| - | - | - | - |
| [`POST /v1/carrier/trucks`](https://docs.lanesurf.com/api-reference/carrier-trucks/post-an-available-truck) | `post_truck` | carrier | Post an available truck: where, when, equipment, where it wants to go |
| [`GET /v1/carrier/trucks`](https://docs.lanesurf.com/api-reference/carrier-trucks/list-my-trucks) | `list_trucks` | carrier | List my trucks |
| [`GET /v1/carrier/trucks/{truck_id}`](https://docs.lanesurf.com/api-reference/carrier-trucks/get-a-truck) | `get_truck` | carrier | One truck |
| [`PATCH /v1/carrier/trucks/{truck_id}`](https://docs.lanesurf.com/api-reference/carrier-trucks/update-a-truck) | `update_truck` | carrier | Update a truck |
| [`DELETE /v1/carrier/trucks/{truck_id}`](https://docs.lanesurf.com/api-reference/carrier-trucks/remove-a-truck) | `remove_truck` | carrier | Take a truck down |
| [`GET /v1/carrier/trucks/{truck_id}/matches`](https://docs.lanesurf.com/api-reference/carrier-loads/loads-that-fit-this-truck) | `truck_matches` | verified | Loads that fit this truck, closest first |
| [`POST /v1/carrier/lanes`](https://docs.lanesurf.com/api-reference/carrier-lanes/save-a-lane) | `save_lane` | carrier | Save a lane the carrier runs |
| [`GET /v1/carrier/lanes`](https://docs.lanesurf.com/api-reference/carrier-lanes/list-my-lanes) | `list_lanes` | carrier | List my lanes |
| [`DELETE /v1/carrier/lanes/{lane_id}`](https://docs.lanesurf.com/api-reference/carrier-lanes/remove-a-lane) | `remove_lane` | carrier | Remove a lane |
| [`GET /v1/carrier/loads/search`](https://docs.lanesurf.com/api-reference/carrier-loads/search-loads-near-a-zip-or-city-or-by-state) | `search_loads` | verified | Search loads near a ZIP or city, or by state |
| [`GET /v1/carrier/loads/{load_id}`](https://docs.lanesurf.com/api-reference/carrier-loads/one-loads-details) | `get_carrier_load` | verified | One load's details, without broker identity or contacts |
| [`POST /v1/carrier/loads/{load_id}/bids`](https://docs.lanesurf.com/api-reference/carrier-loads/bid-on-a-load) | `bid_on_load` | verified | Bid on a load; bidding again updates the bid |
| [`GET /v1/carrier/bids`](https://docs.lanesurf.com/api-reference/carrier-loads/my-bids-and-their-status) | `list_bids` | carrier | My bids and their status |
| [`GET /v1/carrier/outreach`](https://docs.lanesurf.com/api-reference/carrier-loads/lanesurf-outreach-i-received) | `my_outreach` | verified | Loads Lanesurf contacted this carrier about in the last 30 days |

## Lists

Your loads (`GET /v1/loads`) come a page at a time: `limit` (1 to 100, default 25), then send `next_cursor`
back as `cursor` until it is `null`.

Load search and truck matches take `limit` (1 to 100, default 25) and return the closest loads first,
with `total`, the number returned. There is no `offset` or cursor: narrow or change the search to see
other loads. The other lists have no paging and return your newest items up to a cap: trucks 200, lanes 500,
bids 200, and carrier outreach 50 loads. A load's outreach lists every carrier on that load.

## Errors

Every error is JSON with a stable `code` to branch on and a `request_id` to quote to support:

```json theme={null}
{ "error": "too many requests for this API key; slow down", "code": "rate_limited", "request_id": "req_…" }
```

Some errors add `missing`, `current_rate` or `next_step`. See [Errors](https://docs.lanesurf.com/errors.md) for every code
and what to do, and [Idempotency and retries](https://docs.lanesurf.com/idempotency.md) for when to retry.

## Discovery files

| File | What |
| - | - |
| [`/openapi.yaml`](https://docs.lanesurf.com/openapi.yaml) | The full contract |
| `/llms.txt`, `/llms-full.txt` | This site as Markdown, for agents. Add `.md` to any page URL for its Markdown |
| `https://agent.lanesurf.com/.well-known/oauth-authorization-server` | OAuth metadata for AI apps that sign in |
| `https://agent.lanesurf.com/.well-known/oauth-protected-resource/mcp` | Which sign-in server protects `/mcp` |
| `https://agent.lanesurf.com/.well-known/api-catalog` | The API catalog (RFC 9727): links to this contract, these docs and the health check |
| `https://agent.lanesurf.com/.well-known/mcp/server-card.json` | The MCP server card: name, endpoint and how to authenticate |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.