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

# List your loads

> The loads your brokerage posted through the API, newest first, a page at a time.

The loads your brokerage posted through this API, newest first: each one's status, lane, equipment,
dates, rates and outreach counts. Any rep's key at the brokerage sees all of them; loads from your TMS or
the dashboard aren't listed. For a load's offers, call `GET /v1/loads/{id}`.

Pages: `limit` loads at a time (1 to 100, default 25). When there are more, `next_cursor` is set: send it
back as `cursor` for the next page. It is `null` on the last page.


## OpenAPI

````yaml /openapi.yaml get /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:
    get:
      tags:
        - Broker loads
      summary: List your loads
      description: >
        The loads the caller's brokerage posted through this API, newest first,
        with the same statuses as

        `GET /v1/loads/{id}`. Any rep's key at the brokerage sees all of them;
        loads from the TMS or the dashboard

        aren't listed. Paged with `limit` and `cursor`: send `next_cursor` back
        as `cursor` until it is `null`.
      operationId: listLoads
      parameters:
        - name: limit
          in: query
          description: >-
            How many loads per page, a whole number from 1 to 100. Defaults to
            25. Anything else answers 400.
          schema:
            type: integer
            default: 25
            minimum: 1
            maximum: 100
        - name: cursor
          in: query
          description: >-
            The `next_cursor` from the previous page, sent with the same
            `status` and `needs_decision` as that page (other filters answer
            400). Leave it out for the first page.
          schema:
            type: string
            maxLength: 500
        - name: status
          in: query
          description: >
            Only loads with this status. With `sourcing` or `stalled`, a page
            can hold fewer than `limit` loads

            even when more follow: keep paging until `next_cursor` is `null`.
          schema:
            type: string
            enum:
              - sourcing
              - stalled
              - covered
              - inactive
              - deleted
        - name: needs_decision
          in: query
          description: >
            `true`: only open loads with offers waiting for your answer
            (`offers.pending` above 0). One call answers

            "anything new on my loads?" instead of reading every load. Send the
            cursor with the same filter.
          schema:
            type: boolean
      responses:
        '200':
          description: One page of loads, newest first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoadList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/WrongRole'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/Internal'
        '503':
          $ref: '#/components/responses/AuthUnavailable'
components:
  schemas:
    LoadList:
      type: object
      required:
        - loads
        - next_cursor
        - next_step
      properties:
        loads:
          type: array
          description: Newest first.
          items:
            $ref: '#/components/schemas/LoadSummary'
        next_cursor:
          type:
            - string
            - 'null'
          description: Send it as `cursor` for the next page. `null` on the last page.
        next_step:
          $ref: '#/components/schemas/NextStep'
    LoadSummary:
      type: object
      required:
        - load_id
        - status
        - origin
        - destination
        - outreach
      properties:
        load_id:
          type: string
          format: uuid
        tms_id:
          type: string
          description: >-
            Lanesurf's id for the load in the dashboard, e.g. `api-7c1e…`. Also
            works as `{id}`.
        reference_number:
          type: string
          description: Your own load number, when you sent one.
        status:
          type: string
          enum:
            - sourcing
            - stalled
            - covered
            - inactive
            - deleted
          description: The same status `GET /v1/loads/{id}` answers with.
        status_reason:
          type: string
          description: Why, when the status alone would mislead. Set for `stalled`.
        origin:
          $ref: '#/components/schemas/LoadPlace'
        destination:
          $ref: '#/components/schemas/LoadPlace'
        equipment_type:
          type: string
          example: Dry Van
        pickup_date:
          type: string
          format: date
          description: The first pickup's date (YYYY-MM-DD), as posted.
          example: '2026-11-03'
        delivery_date:
          type: string
          format: date
          description: The last delivery's date (YYYY-MM-DD), as posted.
          example: '2026-11-04'
        max_rate:
          type: number
        agreed_rate:
          type: number
          description: The accepted offer's rate, once there is one.
        covered_by:
          type: string
          enum:
            - lanesurf
            - rep
          description: >-
            Set for `covered`: `lanesurf` when you accepted one of the offers,
            `rep` when you marked it covered elsewhere.
        outreach:
          type: object
          required:
            - sessions
          properties:
            sessions:
              type: integer
              description: >-
                Carrier conversations on this load (calls, emails and inbound
                bids). `GET /v1/loads/{id}` has the offers.
        offers:
          type: object
          description: >-
            Offers waiting for your answer (accepted or declined ones aren't
            counted). Only open loads have them.
          required:
            - pending
          properties:
            pending:
              type: integer
              description: Offers with no answer yet.
            best_rate:
              type: number
              description: The lowest of them.
            latest_at:
              type: string
              format: date-time
              description: When the newest one came in.
        created_at:
          type: string
          format: date-time
    NextStep:
      type: string
      description: >-
        For the agent. Exactly what to do next and which MCP tool to call (REST
        path in brackets).
    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
    LoadPlace:
      type: object
      description: The first pickup (origin) or last delivery (destination).
      properties:
        city:
          type: string
          example: Dallas
        state:
          type: string
          description: >-
            The two-letter code for US states and Canadian provinces; anything
            else as posted.
          example: TX
        zip_code:
          type: string
          example: '75201'
  responses:
    BadRequest:
      description: >-
        `invalid_request`: the request is malformed or a value is invalid. The
        message says which. Don't retry unchanged.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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'
    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_<key>
      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.