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

# Cover a load

> Post a load as JSON fields. Lanesurf reaches carriers and brings back offers with rates.

**1. Post the load**

Turn what the person told you into fields. Every field is on the `POST /v1/loads` page.

```bash theme={null}
curl -X POST https://agent.lanesurf.com/v1/loads \
  -H "Authorization: Bearer $LANESURF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "equipment_type": "Dry Van",
    "weight_lbs": 40000,
    "rate_max": 1800,
    "reference_number": "PO-4471",
    "origins": [{"city": "Dallas", "state": "TX", "pickup_ready_date": "2026-10-23"}],
    "destinations": [{"city": "Atlanta", "state": "GA", "delivery_ready_date": "2026-10-24"}]
  }'
```

**2. Answer what's missing**

To start covering a load, Lanesurf needs: **equipment, the first pickup's city, state and date,
and the last delivery's city, state and date**. If any is missing you get `422`:

```json theme={null}
{ "code": "missing_fields", "missing": ["destinations[0].delivery_ready_date"] }
```

Ask the person for those only, add them, and send the whole load again.

`reference_number` is optional: your own load number (your TMS or customer reference). It shows on the
load and in the Lanesurf dashboard, so loads match between your systems.

Values are checked before anything is posted. A bad one answers `400 invalid_request` saying which field
and why, and nothing is created:

* **Stops:** at most 20. A state is a US state, Canadian province or Mexican state, as its code (`TX`) or
  its name (`Texas`); Lanesurf stores the code.
* **Dates:** the first pickup can't have passed, and no delivery can be before it.
* **Numbers:** rates from $1 to $500,000 (`rate_min` no more than `rate_max`), weight from 1 to 200,000 lbs,
  pallets 0 to 100, temperature -60 to 120 °F. Commas may group thousands (`"$1,950"`).
* **Text:** plain text within the lengths in the [API reference](https://docs.lanesurf.com/api-reference/broker-loads/post-a-load.md),
  no HTML tags. Currency is USD, CAD or MXN.
* **Only the documented fields.** Any other field is refused, not ignored. Put anything else carriers must
  know (a hazmat class, tarps, appointment notes) in `explicit_special_instructions`.

If Lanesurf can't process the load (bad stop cities, states, zip codes or dates), you get
`400 load_rejected`. Don't send it again unchanged: check the stops and dates with the person, then send
it with a new `Idempotency-Key`.

**3. Lanesurf starts covering it**

```json theme={null}
{
  "status": "sourcing",
  "load_id": "3f2a…",
  "tms_id": "api-7c1e…",
  "post_with": { "email": "jane@loads.example.com", "phone": "+14155550100" },
  "assumed": { "commodity": "General freight" }
}
```

When the answer has `post_with`, put that email and phone on the load wherever you advertise it (load
boards, emails), so carrier calls and replies reach Lanesurf. It comes back only when Lanesurf has set a
posting email and phone for your key. Keys made by signing in from an AI app don't have one.

**4. Read offers and pick a carrier**

See [Load status and offers](https://docs.lanesurf.com/brokers/load-status.md).

## Safe retries

Every load post needs an `Idempotency-Key` header (up to 200 characters; a new UUID per load). Without it
you get `400 idempotency_key_required` and nothing is created, because a retry after a timeout would
otherwise create a second load and Lanesurf would contact the same carriers twice. Missing fields are
reported first. Over MCP, send it as `post_load`'s `idempotency_key`. The key is scoped to the API key
that sends it:

| Call | Answer |
| - | - |
| First post with a key | `201`, a new `load_id` |
| Retry with the same key and the same load, from the same API key | `200`, the original load with its current `status` (`sourcing`, `covered`, …). No second load |
| Same key, same API key, but a different load | `422 idempotency_key_reused`. Nothing is created or changed. Use a new key |
| Retry while the first post is still running | `409 idempotency_in_progress` with `Retry-After: 5`. Wait, then retry with the same key and load |
| Same key from a different API key, even at the same brokerage | `201`, a different load |
| Post with no key | `400 idempotency_key_required`. Nothing is created |

A `200` retry answers with the original load as it is now:

```json theme={null}
{
  "status": "covered",
  "load_id": "3f2a…",
  "tms_id": "api-7c1e…",
  "post_with": { "email": "jane@loads.example.com", "phone": "+14155550100" },
  "message": "This Idempotency-Key was already used for this load: this is the original load, not a new one. Check GET /v1/loads/3f2a…."
}
```

Use a new key for each new load. A used key can't be used to change a load.

> [!TIP]
>
> Commodity defaults to "General freight" and rate is optional. Numbers can be sent as numbers or
> strings (`40000`, `"40000"` or `"$40,000"`). A value that isn't a number is refused with `invalid_request`
> naming the field, and nothing is posted.


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