> ## 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. # Idempotency and retries > Which calls are safe to send twice, how Idempotency-Key works, and how to retry after an error. Networks fail. When a call times out you don't know whether it worked, so Lanesurf makes every write safe to send again. Posting a load needs an `Idempotency-Key`; the other writes are safe to repeat on their own. ## Post a load: `Idempotency-Key` (required) `POST /v1/loads` must carry an `Idempotency-Key` header (over MCP: the `idempotency_key` argument of `post_load`). * Make a **new UUID for each load**, and keep it until you know the load was created. * On a retry of the same load, send the **same key** and the same body. * Up to 200 characters. Keys are scoped to your API key. | You send | You get | A load is created? | | - | - | - | | No key | `400 idempotency_key_required` | No | | A new key | `201` with the new load | Yes | | The same key again, same load | `200` with the original load and its current status | No, it's the same load | | The same key while the first post is still running | `409 idempotency_in_progress` with `Retry-After: 5` | No. Wait 5 seconds and retry with the same key | | The same key for a different load | `422 idempotency_key_reused` | No. Use a new key for a new load | A load that is missing fields (`422 missing_fields`) or that Lanesurf can't process (`400 load_rejected`) is never created. Fix it and send it again: after `missing_fields`, reuse the same key; after `load_rejected`, check the stops and dates with the person and use a new key. ## Post a truck: optional `Idempotency-Key` `POST /v1/carrier/trucks` takes an optional `Idempotency-Key` (MCP: `post_truck`'s `idempotency_key`), up to 200 characters. Posting again with the same key from the same API key returns the existing truck, with the same `truck_id`, instead of a duplicate (the answer is `201` either way). Without a key, every post is a new truck. ## Writes that are safe to repeat as they are | Call | Sending it again | | - | - | | Accept an offer | Same offer, same answer. `409 offer_changed` if the carrier changed its rate since; ask the person again | | Mark a load covered | Same answer | | Bid on a load | Updates your bid on that load (latest terms win): `200` with `action: updated` or `unchanged`. One bid per carrier per load, never a duplicate. After the broker accepts it: `409 bid_decided`. A bid can be changed up to 5 times (`409 bid_update_limit`) | | Finish an `incomplete` bid | Send the bid again. Within 2 minutes, from the same key: the original rate, truck and note are used. After that, from any of your carrier's keys: the new request's terms are used | | Save a lane | The same lane (same states, cities and equipment, any letter case) returns the lane already saved | | Remove a truck or lane | A second remove answers `404 not_found`; the item is already gone | | Decline an offer | Records the same choice. `409 already_covered` once the load is covered | Reads (`GET`) are always safe to repeat. ## When to retry | Answer | Retry? | How | | - | - | - | | Timeout or connection error | Yes | The same request; for `POST /v1/loads`, the same `Idempotency-Key` | | `429 rate_limited` | Yes | After `Retry-After` seconds. See [Rate limits](https://docs.lanesurf.com/rate-limits.md) | | `409 idempotency_in_progress` | Yes | After 5 seconds, same key and load | | `409 already_bid` | Yes | In a few seconds; another key of your carrier is bidding on this load right now | | `500 internal`, `502 upstream_error` | Yes, a few times | Wait, then back off: for example 2, 4, 8, 16 seconds, then stop and tell the person | | `503 unavailable` | Yes, later | Wait `Retry-After` when it's set. If the key couldn't be checked, the key may be fine: don't ask for a new one | | Any other `4xx` | No | Fix the request first. Sending it unchanged gives the same answer | When a call keeps failing, quote its `request_id` to [support@lanesurf.com](mailto:support@lanesurf.com). You can also send your own `X-Request-Id` and keep it with your retries. See [Request IDs](https://docs.lanesurf.com/errors.md#request-ids). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.