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

# Instructions for AI agents

> The rules an AI agent follows when it uses Lanesurf for a freight broker or a carrier.

You are an AI agent acting for a person in freight: a **broker** with a load to cover, or a **carrier /
dispatcher** with a truck to fill. Lanesurf's job is to book the load: an eligible truck at an eligible rate.
Follow these rules.

## 1. Pick the path

| The person says | They are | Do this |
| - | - | - |
| "Cover this load", "I need a truck Dallas to Atlanta" | Broker | [Cover a load](https://docs.lanesurf.com/brokers/cover-a-load.md) with `POST /v1/loads` |
| "Find me a load", "My truck is empty in Dallas Friday" | Carrier | [Get loaded](https://docs.lanesurf.com/carriers/find-a-load.md): post the truck, search, bid |
| "Did my load get covered?", "Any offers?" | Broker | [Load status and offers](https://docs.lanesurf.com/brokers/load-status.md) with `GET /v1/loads/{id}` |
| "Did I get that load?" | Carrier | `GET /v1/carrier/bids` (see [Bidding](https://docs.lanesurf.com/carriers/bid-on-a-load.md)) |

If you can't tell, ask: "Do you have a load that needs a truck, or a truck that needs a load?"

## 2. Get a key

* Use the key the person already gave you. Send it as `Authorization: Bearer ls_live_…`.
* No key: sign them up. Every signup reply, including errors, has `next_step`; follow it. Over HTTP use
  `POST /v1/signup` (no key needed). An MCP app with no key gets the Lanesurf sign-in page, where the
  person can sign up.

**A new carrier** (see [Carrier sign up](https://docs.lanesurf.com/carriers/sign-up.md)):

1. Ask for the carrier's **MC and/or DOT number** and their **work email** (not a free mailbox such as Gmail,
   Yahoo or Outlook; see [Carrier sign up](https://docs.lanesurf.com/carriers/sign-up.md) for the list; there is no phone signup).
2. `POST /v1/signup` with `role: "carrier"`. Tell them where the code went (`sent_to`).
3. Ask for the 8-digit code, then `POST /v1/signup/{signup_id}/verify` with `code`.
4. Give them `api_key` to store securely. It's shown once.
5. Read `principal.verification`. `needs_review`: tell them their carrier account is under review; they
   can post and manage trucks and lanes and list bids, but can't search loads, read a load, get truck
   matches, see outreach they received or bid until Lanesurf verifies it.

**A new brokerage** (see [Sign up your brokerage](https://docs.lanesurf.com/brokers/get-a-key.md)):

1. Ask for the brokerage's **MC and/or DOT number** and their **work email**.
2. `POST /v1/signup` with `role: "broker"`.
3. Ask for the code and their **name**, **job title** and **company name** (phone and website optional),
   then `POST /v1/signup/{signup_id}/verify` with `code`, `name`, `job_title`, `company_name`. A missing
   one answers `422 missing_fields` before a code attempt is used: ask for it and send the same code again.
4. Give them `api_key` to store securely. It's shown once.
5. Tell them Lanesurf reviews new brokerages before carrier outreach starts (`activated: false`). They can
   fill in their setup (`PATCH /v1/broker/setup`) and post loads, which show `stalled` until then.

Call `GET /v1/me` if you're not sure who a key belongs to.

## 3. Ask only for what's missing

Turn what the person said into the fields in the schema (`LoadFields` for loads, `TruckInput` for
trucks). If the reply is `422` with `code: missing_fields`:

1. Read the `missing` list. It names exact fields (e.g. `destinations[0].delivery_ready_date`).
2. Ask the person for **those items only**. One short question.
3. Add them and send the whole load (or truck) again. Nothing was created yet.
4. For a load, `201` with `status: sourcing` means Lanesurf is working it. Every load answer has
   `next_step`; follow it.

Don't guess missing values and don't re-ask for things already given. Check `assumed` and tell the
person what Lanesurf filled in (for example, commodity "General freight").

Every load post needs an `Idempotency-Key` header (a fresh UUID per load; over MCP, `idempotency_key`).
Without it you get `400 idempotency_key_required` (missing fields are reported first). If the call times
out, retry with the **same** key, the same API key and the same load: you get the original load back
(`200`) with its current status, never a second one.

* `400 load_rejected`: Lanesurf couldn't process the load. Don't send it again unchanged.
  Check the stop cities, states, zip codes and dates with the person, then send it with a new key.
* `422 idempotency_key_reused`: the key was already used for a different load. Nothing was created. Use
  a new key for a new load.
* `409 idempotency_in_progress`: the first post is still running. Wait `Retry-After` seconds, then retry
  with the same key and load.

## 4. Capture the carrier basics

Every carrier interaction should end with three things on record: the **MC or DOT number**, the
**dispatch contact** (email or phone), and the carrier's **terminals** (the lanes its trucks run).
Save terminals with `POST /v1/carrier/lanes` (see [Lanes](https://docs.lanesurf.com/carriers/lanes.md)). When you post a truck, put
where it wants to go in `destinations`. Posted trucks and saved lanes are how Lanesurf pitches the
carrier loads: its reps email or call the carrier about matching loads (verified carriers only). Remove a
truck once it's loaded.

## 5. Confirm before you commit

Before you **accept an offer** or **bid on a load**, show the person:

* the load (lane, dates, equipment),
* the carrier or the load id,
* the rate,

and wait for a clear yes. Accepting takes the load off the market and stops Lanesurf's outreach. A bid
is not a booking: the broker's team follows up with the dispatcher, and Lanesurf does not book the load.

To accept, send the rate the person agreed to (`{"rate": 1850}`; over MCP, `rate`). If the carrier
changed its rate since, nothing is accepted and you get `409 offer_changed` with `current_rate`. Tell the
person the new rate and ask again.

## 6. Know what Lanesurf does and doesn't do

* Accepting an offer records the choice and stops Lanesurf's outreach. Lanesurf does **not** contact the
  carrier or send a rate confirmation: give the person the winner's `contact_email` / `contact_phone` so
  their team reaches out to book, and sends the rate confirmation from their own TMS.
* Declining an offer only records the choice. It doesn't stop Lanesurf's outreach to that carrier.
* When posting a load returns `post_with`, tell the broker to use that email and phone wherever they
  advertise the load, so carrier replies reach Lanesurf. No `post_with` (common for app sign-ins): say nothing
  about it; Lanesurf's own outreach runs either way.
* If the broker covered the load another way, call `POST /v1/loads/{id}/covered` so Lanesurf stops.
* To change a load use `PATCH /v1/loads/{id}`; on hold, pause it; cancelled, delete it; carrier fell off,
  reopen it. Never post it again or mark it covered to change or cancel it. See [Manage a load](https://docs.lanesurf.com/brokers/manage-a-load.md).
* With many open loads, `GET /v1/loads?needs_decision=true` shows which have offers waiting, in one call.
* A `409 already_covered` means the load already has a winner, was marked covered, or is gone. Read the
  load again and tell the person.

## 7. Poll politely

* Check a load with `GET /v1/loads/{id}`, or bids with `GET /v1/carrier/bids`, about every
  **2 to 5 minutes**, not every second. Stop polling a load when its status is `covered`, `inactive` or
  `deleted`.
* Each API key can make up to 120 requests per minute (counted on each Lanesurf server, so treat it as the most to send). On `429`, wait the `Retry-After` seconds. On `500`,
  `502` or `503`, back off and retry later.
* On `400`, fix the request. Don't send the same thing again.
* Every answer has an `X-Request-Id` header, and every error a `request_id` (over MCP, successful results
  have it in `_meta["lanesurf/request_id"]`). When something keeps failing, tell the person to quote it to
  [support@lanesurf.com](mailto:support@lanesurf.com). See [Request IDs](https://docs.lanesurf.com/errors.md#request-ids).

## 8. Keep secrets

* Never show, log or repeat an API key. Never put it in a URL.
* Never share one party's contact details with another. Load search, load details and truck matches hide
  the broker's identity and contacts. Outreach a carrier received (`GET /v1/carrier/outreach`) names the
  brokerage that contacted it, with no contacts. To go for a load, a carrier bids.
* Only use data the key gives you for the person you're working for.

## Machine-readable docs

| What | Where |
| - | - |
| Page index | `/llms.txt` |
| Every page in one file | `/llms-full.txt` |
| Any page as Markdown | Add `.md` to its URL, e.g. [`/for-ai-agents.md`](https://docs.lanesurf.com/for-ai-agents.md) |
| API contract | [`/openapi.yaml`](https://docs.lanesurf.com/openapi.yaml) |
| Errors and statuses | [Errors](https://docs.lanesurf.com/errors.md), [Statuses](https://docs.lanesurf.com/statuses.md) |


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