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

# Bid on a load

> Tell the broker you want to run a load. The broker's team follows up with your dispatcher.

```bash theme={null}
curl -X POST https://agent.lanesurf.com/v1/carrier/loads/$LOAD_ID/bids \
  -H "Authorization: Bearer $LANESURF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rate": 1900, "truck_id": "c1d2…", "note": "Empty in Dallas Fri 8am"}'
```

```json theme={null}
{
  "bid_id": "7f6e…",
  "load_id": "9e8d…",
  "rate": 1900,
  "truck_id": "c1d2…",
  "note": "Empty in Dallas Fri 8am",
  "status": "submitted",
  "created_at": "2026-10-22T16:40:00Z",
  "action": "created"
}
```

## What happens next

1. The bid shows up on the broker's Lanesurf dashboard as an inbound bid, with your MC/DOT, your dispatch
   contact (the email or phone you signed up with), the rate, and your note and truck. The broker's reps
   are emailed about it.
2. The broker's team follows up with your dispatcher by email or phone to confirm the truck and agree the
   rate. If the broker accepts your bid, the broker's team reaches out to you to book.
3. Bids that look like a mistake (for example an absurd rate) may be held for review instead of going to the
   broker straight away.
4. **Lanesurf does not book the load.** Booking and the rate confirmation happen between you and the broker.
5. Follow the outcome with `GET /v1/carrier/bids`. Poll it every few minutes.

| Bid `status` | Meaning |
| - | - |
| `submitted` | The broker has it and the load is still open |
| `accepted` | The broker accepted this bid |
| `declined` | The broker passed on this bid. Send it again with a new rate to reopen it |
| `load_closed` | The load was covered some other way, closed, or booked to someone else, and the broker made no choice on this bid |
| `incomplete` | The bid was recorded but never reached the broker (a failure mid-bid). `POST` it again to finish it: within 2 minutes from the same key (its original rate, truck and note are used), after that from any of your carrier's keys (the new terms are used) |

The broker's choice wins: an `accepted` or `declined` bid keeps that status after the load closes.
`GET /v1/carrier/bids` lists your carrier's bids, placed from any of its keys (up to 200, newest first). Keys under review can call it too.

## Rules

* **A bid is not a booking.** Confirm with the dispatcher before you send it.
* Only **verified** carriers can bid. Keys under review (`needs_review`) get `403 verification_required`.
* `rate` is all-in USD, from $1 to $500,000, rounded to the cent. Commas may group thousands (`"1,250"`), but
  `"1,2,5,0"` isn't a number. Leave it out to ask for the broker's rate.
* `truck_id` is optional; it must be one of your active trucks.
* `note` is optional, up to 1,000 characters of plain text. The broker sees it as your note.
* The body is optional. No body, an empty body or `{}` means "I want to run this, send me your rate".
* **One bid per carrier per load**, across all of that carrier's keys. The carrier is its DOT number, or its
  MC number if it has no DOT.
* **To change your rate, bid again.** It updates the same bid (latest terms win) and replies `200` with
  `action: updated`, or `action: unchanged` if nothing changed. Fields you leave out keep their value. The
  broker sees the new rate on the same bid. A brand-new bid replies `201` with `action: created`.
* A bid can be changed at most 5 times. After that it stands as it is: `409 bid_update_limit`.
* Once the broker has **accepted** your bid, it can't change: `409 bid_decided`. A declined bid can be sent
  again: a new rate reopens it for the broker. Changing only the note or truck keeps it declined.
* If another key of your carrier is placing a bid on the same load at that moment, you get `409 already_bid`.
  Try again in a few seconds.
* A bid that shows `incomplete` never reached the broker. Send it again to finish it. Within 2 minutes only the
  key that placed it can, and the original rate, truck and note are used. After 2 minutes the bid counts as
  abandoned: any of your carrier's keys can finish it, and that request's terms are used.
* You can't bid on a load that is gone, covered, paused or deleted. A load you already bid on stays readable with
  `GET /v1/carrier/loads/{load_id}`, showing `open: false`.


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