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

# Start signup

> Say carrier or broker, give an MC and/or DOT number and a work email. We email a code.

Step 1 of 2 to get an API key, for a carrier or a brokerage, with no human at Lanesurf involved.
Send `role` (`carrier` or `broker`), the company's `mc_number` and/or `dot_number`, and the person's
**work email**. Lanesurf emails an 8-digit code there.

* **Work email only.** Free mail (Gmail, Yahoo, Outlook, Hotmail, Live, MSN, iCloud, me.com, mac.com, AOL,
  Proton, GMX, Zoho, Yandex, mail.com, and their country versions such as yahoo.co.uk) is refused with `400 invalid_request` ("use your work email").
* **Email is required.** There is no phone-only signup.
* Missing `role`, `email`, or both `mc_number` and `dot_number`: `422 missing_fields` with a `missing` list.

The reply only says where the code went. How a carrier's check went is shown by
`POST /v1/signup/{signup_id}/verify`, once the person has proved the inbox with the code.
Every reply, including errors, has `next_step`: what the agent should do next.

Limits: 5 starts per email per hour and 10 per day, 10 per MC/DOT number per day, and per-IP limits.


## OpenAPI

````yaml /openapi.yaml post /v1/signup
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/signup:
    post:
      tags:
        - Authentication
      summary: Start signup (carrier or broker)
      description: >
        Step 1 of 2 to get an API key, for a carrier or a brokerage. Send role
        (carrier or broker), the

        company's mc_number and/or dot_number, and the person's work email.
        Lanesurf emails an 8-digit code.

        Free mail (Gmail, Yahoo, Outlook, iCloud, AOL and the other listed
        providers) is refused with 400 invalid_request ("use your work email");
        email is

        required (no phone-only signup). Missing fields answer 422
        missing_fields. The reply only says where

        the code went; verify reports how the carrier check went. Every reply
        has next_step.

        Limits: 5 starts per email per hour and 10 per day, 10 per MC/DOT number
        per day, and per-IP limits.
      operationId: startSignup
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignupRequest'
            examples:
              carrier:
                summary: A carrier
                value:
                  role: carrier
                  dot_number: '1234567'
                  email: dispatch@exampletrucking.example.com
              broker:
                summary: A brokerage
                value:
                  role: broker
                  mc_number: '654321'
                  email: dana@acmefreight.example.com
      responses:
        '201':
          description: Code sent. Follow `next_step`.
          headers:
            Cache-Control:
              $ref: '#/components/headers/NoStore'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Signup'
              example:
                signup_id: 5d0e8a3c-6f1b-4e2a-9c7d-1b2a3c4d5e6f
                role: carrier
                channel: email
                sent_to: d*******@exampletrucking.example.com
                expires_at: '2026-10-23T14:10:00Z'
                next_step: >-
                  Ask the person for the 8-digit code we emailed to
                  d*******@exampletrucking.example.com, then call verify_signup
                  with signup_id and code (POST /v1/signup/{signup_id}/verify).
                  The code expires in 10 minutes.
        '400':
          description: >-
            `invalid_request`: a value is invalid, e.g. a free or personal email
            ("use your work email").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignupError'
              example:
                error: >-
                  use your work email: free and personal mail (Gmail, Yahoo,
                  Outlook, iCloud, AOL and the like) is not accepted
                code: invalid_request
                next_step: >-
                  Ask the person for their work email at the company (not Gmail,
                  Yahoo, Outlook, iCloud or another personal mailbox), then call
                  start_signup again.
        '422':
          description: '`missing_fields`: `missing` lists what to ask for.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignupError'
              example:
                error: signup needs email
                code: missing_fields
                missing:
                  - email
                next_step: >-
                  Ask the person for email, then call start_signup again with
                  role, email and mc_number and/or dot_number.
        '429':
          $ref: '#/components/responses/SignupRateLimited'
        '500':
          $ref: '#/components/responses/SignupInternal'
        '503':
          $ref: '#/components/responses/SignupUnavailable'
      security: []
components:
  schemas:
    SignupRequest:
      type: object
      required:
        - role
        - email
      description: '`role`, a work `email`, and at least one of `mc_number` / `dot_number`.'
      properties:
        role:
          type: string
          enum:
            - carrier
            - broker
          description: '`carrier` (has trucks) or `broker` (posts loads).'
        email:
          type: string
          format: email
          description: >-
            The person's work email at the company. Free mail (Gmail, Yahoo,
            Outlook and the other providers listed on signup) is refused. The
            code goes here.
          example: dispatch@exampletrucking.example.com
        mc_number:
          type: string
          example: '123456'
          description: Digits; an MC- prefix is accepted. Give this and/or `dot_number`.
        dot_number:
          type: string
          example: '1234567'
          description: >-
            Digits; a DOT or USDOT prefix is accepted. Give this and/or
            `mc_number`.
    Signup:
      type: object
      required:
        - signup_id
        - role
        - channel
        - sent_to
        - expires_at
        - next_step
      description: >-
        Where the code went. It says nothing about the carrier check; verify
        does.
      properties:
        signup_id:
          type: string
          format: uuid
        role:
          type: string
          enum:
            - carrier
            - broker
        channel:
          type: string
          enum:
            - email
        sent_to:
          type: string
          example: d*******@exampletrucking.example.com
          description: Masked email.
        expires_at:
          type: string
          format: date-time
          description: The code stops working at this time (10 minutes).
        next_step:
          $ref: '#/components/schemas/NextStep'
    SignupError:
      type: object
      required:
        - error
        - code
        - next_step
      properties:
        error:
          type: string
          description: A message for people.
        code:
          type: string
          enum:
            - invalid_request
            - missing_fields
            - not_found
            - invalid_code
            - signup_expired
            - broker_name_taken
            - broker_name_mismatch
            - existing_customer
            - already_redeemed
            - rate_limited
            - unavailable
            - internal
        missing:
          type: array
          description: '`missing_fields` only: the fields to ask for.'
          items:
            type: string
            example: job_title
        next_step:
          $ref: '#/components/schemas/NextStep'
        retry_after_seconds:
          type: integer
          description: MCP only; REST sends the `Retry-After` header.
    NextStep:
      type: string
      description: >-
        For the agent. Exactly what to do next and which MCP tool to call (REST
        path in brackets).
  headers:
    NoStore:
      description: Responses that carry secrets are never cached.
      schema:
        type: string
        example: no-store
    RetryAfter:
      description: Seconds to wait before trying again.
      schema:
        type: integer
  responses:
    SignupRateLimited:
      description: >-
        `rate_limited`: too many signups for this email, this MC/DOT number or
        this network. Wait `Retry-After` seconds.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SignupError'
    SignupInternal:
      description: '`internal`: unexpected error. Safe to retry later.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SignupError'
    SignupUnavailable:
      description: >
        `unavailable`: signup can't run right now (code sending or a Lanesurf
        system is down). Retry later;

        when `Retry-After` is set, wait that many seconds. If the carrier check
        can't run, signup still works:

        the carrier is `needs_review`.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SignupError'
  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.