> ## 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.

# Authentication

> Sign up as a carrier or a brokerage with a work email, an MC or DOT number and an 8-digit code, then send the key on every request.

Every request (except signup and `/health`) needs a Lanesurf API key in the `Authorization` header:

```bash theme={null}
curl https://agent.lanesurf.com/v1/me \
  -H "Authorization: Bearer ls_live_..."
```

* Keys look like `ls_live_…` and are sent as a bearer token.
* A missing key returns `401 missing_api_key`; a wrong or revoked one returns `401 invalid_api_key`.
* Each key can make up to 120 requests per minute on the authenticated `/v1` routes (counted on each Lanesurf server, so treat it as the most to send). Over that you get
  `429 rate_limited` with a `Retry-After` header. Wait that many seconds, then retry.

## What a key can reach

| Key | Belongs to | Reaches |
| - | - | - |
| Broker | One rep at a brokerage | `/v1/loads/*` and `/v1/broker/setup`. Only loads that brokerage posted **through this API**, whichever of its reps posted them. Never loads from the brokerage's TMS or from other brokerages |
| Carrier | One carrier signup | `/v1/carrier/*`. Its own trucks, lanes and bids. Search covers active loads from Lanesurf brokers that show their loads to carriers' agents, without broker names, contacts or max rates. Reading loads and bidding need a **verified** key; a key under review (`needs_review`) can't |

A broker key on a carrier route, or a carrier key on a broker route, gets `403 wrong_role`.

> [!WARNING]
>
> Treat the key like a password. Don't paste it into shared chats, logs or prompts, and never show it back to the person after it's stored.

## Get a key

Carriers and brokerages sign up themselves, in two calls, with no human at Lanesurf involved:

1. `POST /v1/signup` with `role` (`carrier` or `broker`), a **work email** and an MC and/or DOT number.
   Free mail (Gmail, Yahoo, Outlook, Hotmail, Live, MSN, iCloud, me.com, mac.com, AOL, Proton, GMX, Zoho,
   Yandex and mail.com, including country versions such as yahoo.co.uk or gmx.de) is refused with
   `400 invalid_request` ("use your work email"). There is no signup by phone. Lanesurf emails an 8-digit code.
2. `POST /v1/signup/{signup_id}/verify` with the code (brokers also send `name`, `job_title` and
   `company_name`). The API key comes back **once**.

Every signup reply, including errors, has `next_step`: what the agent should do next.

> [card] [Brokers](https://docs.lanesurf.com/brokers/get-a-key.md)
>
> Sign up your brokerage. Lanesurf reviews it, then turns on carrier outreach.

> [card] [Carriers](https://docs.lanesurf.com/carriers/sign-up.md)
>
> Verified automatically when your work email matches the carrier's record; otherwise Lanesurf reviews the account.

## Sign in from an AI app

Apps that can't send an API key, such as ChatGPT and the Claude app, connect to
`https://agent.lanesurf.com/mcp` by URL. The app opens a Lanesurf sign-in page, where the person:

* **Already a Lanesurf customer:** signs in with their Lanesurf dashboard email and password, then enters the
  code Lanesurf emails, or with **Sign in with Google** if their dashboard account uses Google. Someone at
  more than one brokerage picks the brokerage. Lanesurf makes a broker key for them the first time.
* **Has an API key:** pastes it, then enters the code Lanesurf emails to the address on the key. A key
  with no email on file can't sign in here; use it directly instead.
* **New carrier or brokerage:** signs up on the page with a work email and an MC or DOT number, then
  enters the 8-digit code Lanesurf emails.

Then they allow the app, and it goes back to the chat signed in.

Every sign-in from an app with a password or an API key asks for a new emailed code. It works once, for 10
minutes. Five wrong codes end the sign-in. After a minute the page offers to send a new code, which replaces the old one. Google
sign-in doesn't ask for a code.

* It follows the MCP authorization spec (OAuth with PKCE and dynamic client registration). `/mcp` without
  credentials answers `401` with a `WWW-Authenticate` header pointing at
  `/.well-known/oauth-protected-resource/mcp`, which is how the app finds the sign-in page.
* Access tokens last 1 hour. The app gets new ones with its refresh token.
* Each sign-in stands for one Agent API key. Revoking that key signs the person out of every app.
* API keys keep working everywhere, `/mcp` included.

## Check a key

`GET /v1/me` returns who the key belongs to: its role (`broker` or `carrier`), and for carriers its
`verification`: `verified` or `needs_review`.


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