> ## 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. # Post a load > Send a load as JSON fields. Lanesurf starts finding carriers. Send the load as JSON fields (the `LoadFields` schema). The minimum is: `equipment_type`, the first origin's `city`, `state` and `pickup_ready_date`, and the last destination's `city`, `state` and `delivery_ready_date`. Commodity defaults to "General freight" (returned in `assumed`). Rate is optional. Numbers may be sent as numbers or strings; one that isn't a number answers 400. If something required is missing you get **422** `missing_fields` with a `missing` list of exact field paths (e.g. `destinations[0].delivery_ready_date`). Ask the person only for those, then send the whole load again. When the load is complete you get **201** with `status: sourcing` and a `load_id`. Lanesurf starts reaching carriers. `post_with`, when the answer has it, is the email and phone to put on the load wherever it is advertised, so carrier 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 yet. A brokerage that signed up through the API starts with carrier outreach off: its loads are saved with `status: stalled` and a `status_reason` saying outreach starts after Lanesurf's review. Every reply, and the `missing_fields` error, has `next_step`: what the agent should do next. **Retries.** The `Idempotency-Key` header is **required** (up to 200 characters; a new UUID per load). Without it the post is refused with **400** `idempotency_key_required`, because a retry after a timeout would otherwise create a second load and Lanesurf would contact the same carriers twice. The key is scoped to the API key that sends it. With the same API key and the same `Idempotency-Key`: * First post: **201**, a new load. * Retry with the same load: **200** with the original load and its current `status` (`sourcing`, `covered`, …). No second load. * Retry with a different load: **422** `idempotency_key_reused`. Nothing is created or changed. * Retry while the first post is still running: **409** `idempotency_in_progress` with `Retry-After: 5`. Wait, then retry. The same `Idempotency-Key` from a different API key, even at the same brokerage, creates a different load. Use a new key for each new load. ## OpenAPI ````yaml /openapi.yaml post /v1/loads openapi: 3.1.0 info: title: Lanesurf Agent API version: 0.4.0 summary: >- Let any AI agent get a freight load covered, or get a truck loaded, through Lanesurf. description: > Lanesurf finds carriers for freight loads by email, phone and text, and negotiates the rate. This API lets AI agents (Claude, ChatGPT, Grok, Cursor and others) and scripts use Lanesurf directly. There are two kinds of caller: - **Broker agents** ("cover this load for me"): post a load as JSON fields, send any fields Lanesurf says are missing, then read carrier offers and pick one. Paths under `/v1/loads`. - **Carrier / dispatcher agents** ("find a load for my truck"): post trucks and lanes, search loads, and bid on a load. Paths under `/v1/carrier`. Every request (except signup and `/health`) uses `Authorization: Bearer ls_live_...`. - A **broker key** belongs to one rep at a brokerage. It reaches only loads that brokerage posted through this API, whichever of the brokerage's reps posted them. It never reaches loads that came from the brokerage's TMS or from other brokerages. - A **carrier key** belongs to one carrier signup. Its trucks, lanes and bids are its own; no other key sees them. Load search covers active loads from Lanesurf brokers that show their loads to carriers' agents, without broker identity or contacts. Only **verified** carrier keys can read loads (search, one load, matches) and bid; keys whose carrier account is under review (`needs_review`) get `403 verification_required` there. Anyone can get a key with `POST /v1/signup` (carrier or broker, a work email, an MC and/or DOT number) and `POST /v1/signup/{signup_id}/verify`. Every signup reply has `next_step`, which tells an agent what to do next. A brokerage that signs up starts with carrier outreach off until Lanesurf reviews it. Broker keys can't call `/v1/carrier/*` and carrier keys can't call `/v1/loads/*` (`403 wrong_role`). Every response has an `X-Request-Id` header, and every error body a `request_id`. Send your own `X-Request-Id` (8-64 letters, digits, `.`, `_` or `-`) to have it used instead. Quote it to Lanesurf support when something fails. Every authenticated `/v1` route is limited to 120 requests per minute per API key, counted on each Lanesurf server (treat it as the most to send). Over the limit you get `429 rate_limited` with a `Retry-After` header. **Lists.** Your loads (`GET /v1/loads`) come a page at a time: `limit` (1 to 100, default 25), then send `next_cursor` back as `cursor` until it is `null`. Load search (`GET /v1/carrier/loads/search`) and truck matches (`GET /v1/carrier/trucks/{truck_id}/matches`) take `limit` (1 to 100, default 25) and return the closest loads first (see each route), with `total` = the number returned. There is no `offset` or cursor: to see other loads, narrow or change the search. The other lists have no paging and return the newest items up to a cap: trucks 200, lanes 500, bids 200, and a carrier's outreach 50 loads (from the last 30 days). A load's outreach lists every carrier on that load. Lanesurf doesn't send webhooks: poll a load (`GET /v1/loads/{id}`) or your bids (`GET /v1/carrier/bids`) every few minutes. Versioning, limits and changes: see https://docs.lanesurf.com/versioning, https://docs.lanesurf.com/rate-limits and https://docs.lanesurf.com/changelog. contact: name: Lanesurf support url: https://docs.lanesurf.com email: support@lanesurf.com license: name: Proprietary. Use is subject to the Lanesurf Terms of Service url: https://www.lanesurf.com/terms servers: - url: https://agent.lanesurf.com description: Production security: - bearerAuth: [] tags: - name: Broker loads description: A broker's agent posts a load and gets it covered. - name: Authentication description: >- Sign up as a carrier or a brokerage with a work email and a one-time code, and see who a key belongs to. - name: Broker setup description: >- What Lanesurf's agents tell carriers about a brokerage, and whether carrier outreach is on. - name: Carrier trucks description: A carrier's agent says where its trucks are and when they're free. - name: Carrier lanes description: A carrier's agent saves the lanes the carrier runs (its terminals). - name: Carrier loads description: A carrier's agent finds loads, bids on one, and follows its bids. - name: System description: Service health. paths: /v1/loads: post: tags: - Broker loads summary: Post a load description: > Send the load as JSON fields (the `LoadFields` schema). The minimum is: `equipment_type`, the first origin's `city`, `state` and `pickup_ready_date`, and the last destination's `city`, `state` and `delivery_ready_date`. Commodity defaults to "General freight" (returned in `assumed`). Rate is optional. Numbers may be sent as numbers or strings; one that isn't a number answers 400. If something required is missing you get **422** `missing_fields` with a `missing` list of exact field paths. Ask the person only for those, then send the whole load again. When the load is complete you get **201** with `status: sourcing` and a `load_id`. Lanesurf starts reaching carriers. `post_with`, when the answer has it, is the email and phone to put on the load wherever it is advertised (only when Lanesurf has set them for your key). The `Idempotency-Key` header is required (up to 200 characters, a new UUID per load); without it the post answers 400 `idempotency_key_required`. If Lanesurf can't process the load (bad stops or dates) the answer is 400 `load_rejected`: fix the load rather than retrying it unchanged. The key is scoped to the API key that sends it. The first call answers 201. A retry of the same load with the same key from the same API key answers 200 with the original load and its current `status`. A different load with a used key answers 422 `idempotency_key_reused`. A retry while the first post is still running answers 409 `idempotency_in_progress` with `Retry-After: 5`. The same `Idempotency-Key` from a different API key, even at the same brokerage, creates a different load. Use a new key for each new load. operationId: postLoad parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LoadFields' example: equipment_type: Dry Van weight_lbs: 40000 rate_max: 1800 origins: - city: Dallas state: TX pickup_ready_date: '2026-10-23' destinations: - city: Atlanta state: GA delivery_ready_date: '2026-10-24' responses: '200': description: > A retry of the same load with an `Idempotency-Key` this API key already used. This is the original load with its current `status`; no second load was created. `assumed` is not set. content: application/json: schema: $ref: '#/components/schemas/PostLoadResult' example: status: covered load_id: 3f2a9c4e-1d7b-4c55-8a7e-0b9d6e5f1234 tms_id: api-7c1e0b5a2f4d4c8e9a3b6d1f0e2c4a8b 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/3f2a9c4e-1d7b-4c55-8a7e-0b9d6e5f1234. next_step: >- The load is covered by the accepted offer (winner); stop polling. Lanesurf does not contact the carrier: tell the person to reach out to the winner (contact_email / contact_phone) to book, and to send the rate confirmation from their own TMS. Lanesurf has also emailed the brokerage's reps the carrier's details. '201': description: The load was created and Lanesurf is contacting carriers. content: application/json: schema: $ref: '#/components/schemas/PostLoadResult' example: status: sourcing load_id: 3f2a9c4e-1d7b-4c55-8a7e-0b9d6e5f1234 tms_id: api-7c1e0b5a2f4d4c8e9a3b6d1f0e2c4a8b post_with: email: jane@loads.example.com phone: '+14155550100' assumed: commodity: General freight message: >- Lanesurf is contacting carriers. Put jane@loads.example.com / +14155550100 on the load wherever you advertise it so carrier replies reach Lanesurf. Check GET /v1/loads/3f2a9c4e-1d7b-4c55-8a7e-0b9d6e5f1234 for offers. next_step: >- Tell the person what Lanesurf assumed (assumed). Tell them to advertise the load with the post_with email and phone so carrier replies reach Lanesurf. Then call get_load with load_id every 2 to 5 minutes to see carrier offers (GET /v1/loads/3f2a9c4e-1d7b-4c55-8a7e-0b9d6e5f1234). '400': description: > `invalid_request`: the body isn't JSON load fields, or the `Idempotency-Key` is over 200 characters. `idempotency_key_required`: no `Idempotency-Key` header. Nothing was created. `load_rejected`: Lanesurf couldn't process the load (check the stop cities, states, zip codes and dates). Don't retry it unchanged; fix it and send it with a new `Idempotency-Key`. content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/WrongRole' '409': description: > `idempotency_in_progress`: a post with this `Idempotency-Key` from this API key is still being processed. Wait `Retry-After` seconds (5), then retry with the same key and the same load. headers: Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: >- a post with this Idempotency-Key is still being processed; retry in a few seconds code: idempotency_in_progress '422': description: > `missing_fields`: required fields are missing. Send the whole load again with them. `idempotency_key_reused`: this API key already used this `Idempotency-Key` for a different load. Nothing was created or changed. Use a new key for a new load. content: application/json: schema: oneOf: - $ref: '#/components/schemas/MissingFields' - type: object required: - error - code properties: error: type: string code: type: string enum: - idempotency_key_reused examples: missing_fields: summary: Required fields are missing value: error: >- the load is missing required fields; send them and try again code: missing_fields missing: - destinations[0].delivery_ready_date idempotency_key_reused: summary: The key was used for a different load value: error: >- this Idempotency-Key was already used for a different load; use a new key for a new load code: idempotency_key_reused '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/Internal' '502': $ref: '#/components/responses/Upstream' '503': $ref: '#/components/responses/AuthUnavailable' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: true description: > Required. Any string up to 200 characters, unique per load (a UUID works). Scoped to the API key that sends it. A retry of the same load with the same key from the same API key answers 200 with the original load, so a retry never creates a second one. A different load with a used key answers 422 `idempotency_key_reused`; a retry while the first post is still running answers 409 `idempotency_in_progress`. The same key from a different API key, even at the same brokerage, creates a different load. schema: type: string maxLength: 200 example: 6b1f0c2e-load-4471 schemas: LoadFields: type: object description: > A load as fields. Required: `equipment_type`, the first origin's `city`, `state` and `pickup_ready_date` (or `pickup_by_date`), and the last destination's `city`, `state` and `delivery_ready_date` (or `delivery_by_date`). Fields typed string-or-number accept either (`40000` or `"40000"`; `$` is ignored and `,` may group thousands: `"$1,250"`). A value that isn't a number (`"about 1250"`, `"1,2,5,0"`) answers **400** `invalid_request` naming the field; nothing is posted. Values are checked before anything is posted, and a bad one answers **400** `invalid_request` saying which field and why. The checks: - **Stops:** at most 20 in total. A state must be a US state, Canadian province or Mexican state, sent as its code or its name (stored as the code). - **Dates:** the first pickup can't have passed (a day's grace for time zones), and no delivery date can be before the first pickup. - **Numbers:** rates from $1 to $500,000, with `rate_min` no more than `rate_max`. `weight_lbs` from 1 to 200,000. `pallet_count` a whole number from 0 to 100. `temperature` from -60 to 120 °F. - **Text:** within the lengths below, and no HTML tags. - **Fields:** a field not listed here is refused, not ignored. Put anything else carriers must know, such as a hazmat class, in `explicit_special_instructions`. required: - equipment_type - origins - destinations additionalProperties: false properties: equipment_type: type: string maxLength: 100 example: Dry Van description: e.g. Dry Van, Reefer, Flatbed, Step Deck. origins: type: array minItems: 1 description: Pickup stops, in order. items: type: object required: - city - state additionalProperties: false properties: city: type: string maxLength: 100 example: Dallas state: type: string example: TX description: >- State or province: its two-letter code, or its name (stored as the code). zip_code: type: string maxLength: 10 description: ZIP or postal code, e.g. 75201 or M5V 2T6. pickup_ready_date: type: string example: '2026-10-23' description: >- Earliest pickup, date (YYYY-MM-DD) or date-time. On the first origin, this or pickup_by_date is required. pickup_by_date: type: string description: Latest pickup, date or date-time. pickup_appointment_type: type: string description: FCFS or APPOINTMENT. Other values are ignored. example: FCFS destinations: type: array minItems: 1 description: Delivery stops, in order. items: type: object required: - city - state additionalProperties: false properties: city: type: string maxLength: 100 example: Atlanta state: type: string example: GA description: >- State or province: its two-letter code, or its name (stored as the code). zip_code: type: string maxLength: 10 delivery_ready_date: type: string example: '2026-10-24' description: >- Earliest delivery, date or date-time. On the last destination, this or delivery_by_date is required. delivery_by_date: type: string description: Latest delivery, date or date-time. delivery_appointment_type: type: string description: FCFS or APPOINTMENT. Other values are ignored. example: APPOINTMENT weight_lbs: type: - string - number example: 40000 description: 1 to 200,000. commodity: type: string maxLength: 200 description: Defaults to "General freight". rate_min: type: - string - number description: >- Posted rate, $1 to $500,000. If only one of rate_min / rate_max is given it is used for both. rate_max: type: - string - number description: Most the broker will pay, $1 to $500,000, and no less than rate_min. currency: type: string example: USD description: USD, CAD or MXN (any letter case). Any other value answers 400. temperature: type: - string - number description: Reefer setpoint (°F), -60 to 120. is_palletized: type: boolean pallet_count: type: - string - number description: A whole number, 0 to 100. driver_requirements: type: string maxLength: 200 description: Say "team" for a team load. Other text is not used. special_requirements: type: string maxLength: 2000 description: >- Used as the special instructions when explicit_special_instructions is empty. explicit_special_instructions: type: string maxLength: 2000 description: Special instructions for carriers (plain text, no HTML). reference_number: type: string maxLength: 100 description: >- Your own load number (your TMS or customer reference). Shown on the load and in the Lanesurf dashboard. example: PO-4471 PostLoadResult: type: object required: - status - load_id - next_step properties: status: type: string enum: - sourcing - stalled - covered - inactive - deleted description: > A new load is `sourcing`, or `stalled` when the brokerage signed up through the API and Lanesurf hasn't turned carrier outreach on yet (`status_reason` says so). On an `Idempotency-Key` retry (200) this is the original load's current status; see `LoadStatus`. load_id: type: string format: uuid tms_id: type: string description: >- Lanesurf's name for the load (starts with `api-`). Works in place of `load_id` in `/v1/loads/{id}`. example: api-7c1e0b5a2f4d4c8e9a3b6d1f0e2c4a8b post_with: $ref: '#/components/schemas/PostWith' assumed: type: object additionalProperties: type: string description: >- Values Lanesurf filled in because they weren't given (e.g. commodity). Not set on a retry. message: type: string description: > What happens next, for people. On an `Idempotency-Key` retry it says the key was already used for this load and this is the original load, not a new one. status_reason: type: string description: Set when `status` is `stalled`. example: >- Carrier outreach starts after Lanesurf's review of your brokerage. This load is saved and starts sourcing once outreach is on; nothing to do until then. next_step: $ref: '#/components/schemas/NextStep' Error: type: object required: - error - code properties: error: type: string description: A message for people. example: invalid API key code: type: string description: A stable machine-readable code. Branch on this, not on `error`. enum: - missing_api_key - invalid_api_key - wrong_role - verification_required - invalid_request - missing_fields - not_found - already_covered - invalid_state - already_bid - bid_decided - idempotency_in_progress - idempotency_key_reused - idempotency_key_required - load_rejected - offer_changed - bid_update_limit - existing_customer - already_redeemed - rate_limited - invalid_code - signup_expired - broker_name_taken - broker_name_mismatch - unavailable - upstream_error - internal example: invalid_api_key missing: type: array description: '`missing_fields` only: exact field names or paths still needed.' items: type: string next_step: allOf: - $ref: '#/components/schemas/NextStep' description: >- On signup errors and on every broker load tool's errors (`list_loads`, `post_load`, `get_load`, `load_outreach`, accept, decline, covered). current_rate: type: number description: '`offer_changed` only: the offer''s rate now.' request_id: type: string description: >- This request's id (also the `X-Request-Id` response header). Quote it to Lanesurf support. example: req_0192f3a4-7b1c-7d2e-9f00-1a2b3c4d5e6f MissingFields: type: object required: - error - code - missing properties: error: type: string code: type: string enum: - missing_fields missing: type: array description: Exact field names or paths still needed. items: type: string example: destinations[0].delivery_ready_date next_step: $ref: '#/components/schemas/NextStep' PostWith: type: object description: >- The email and phone to put on the load wherever it is advertised, so carrier replies reach Lanesurf. Only set when Lanesurf has set a posting email and phone for the key; keys made by signing in from an AI app don't have one yet. properties: email: type: string format: email phone: type: string NextStep: type: string description: >- For the agent. Exactly what to do next and which MCP tool to call (REST path in brackets). responses: Unauthorized: description: >- `missing_api_key` (no `Authorization` header) or `invalid_api_key` (wrong, malformed or revoked key). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: invalid API key code: invalid_api_key WrongRole: description: >- `wrong_role`: this key's role can't use this route (a carrier key on a broker route, or the reverse). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: this API key can't use broker routes code: wrong_role TooManyRequests: description: > `rate_limited`: too many requests. Signup has limits per contact, per carrier and per IP (the 300 per 10 minutes limit groups IPv6 addresses by /64). Every authenticated `/v1` route is limited to 120 requests per minute per API key, counted on each Lanesurf server. Wait `Retry-After` seconds, then retry. headers: Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: too many requests for this API key; slow down code: rate_limited Internal: description: '`internal`: unexpected error. Safe to retry later.' content: application/json: schema: $ref: '#/components/schemas/Error' Upstream: description: >- `upstream_error`: a Lanesurf system behind the API failed. Safe to retry later. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: a Lanesurf system behind the API failed; try again later code: upstream_error AuthUnavailable: description: >- `unavailable`: Lanesurf couldn't check the API key right now (the key may be fine; don't ask for a new one): wait `Retry-After` (30) seconds and send the same request again. headers: Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/Error' headers: RetryAfter: description: Seconds to wait before trying again. schema: type: integer securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: ls_live_ description: One key per broker rep or per carrier signup. Keep it secret. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.