openapi: 3.0.3
info:
  title: Shipwell v2 Core Carriers API
  description: 'Partial, honestly-modeled OpenAPI description of the Shipwell transportation management system (TMS) API. Shipwell is an AI-powered freight execution platform; its public documentation and full API reference live at https://docs.shipwell.com/ but the complete platform and API are enterprise and contract-gated, so exact request and response schemas are best confirmed against the live reference and an authenticated account.


    Endpoints marked "confirmed" below appear directly in Shipwell''s public docs (shipment create/list/get, shipment notes, carrier assignments, tenders, and the events list). Endpoints marked "modeled" are honestly inferred from the documented resource groups (quoting, spot-negotiations, carrier-bids, carriers, carrier-relationships, orders, purchase-orders, webhooks) and are included to represent the shape of each logical API - verify them before use.


    Base URLs. Most of the v2 Core API is served under https://api.shipwell.com/v2 with a fully separate sandbox at https://sandbox-api.shipwell.com/v2. The newer Orders API is served under the host root without the /v2 prefix (for example https://api.shipwell.com/orders). Requests are authenticated with company-scoped API keys passed in the Authorization header (the docs call this the AuthToken scheme). Production and sandbox use separate keys, and objects created in one environment cannot be manipulated from the other.'
  version: '2.0'
  contact:
    name: Shipwell
    url: https://docs.shipwell.com/
servers:
- url: https://api.shipwell.com/v2
  description: Production (v2 Core API)
- url: https://sandbox-api.shipwell.com/v2
  description: Sandbox (v2 Core API)
- url: https://api.shipwell.com
  description: Production host root (Orders API, served without the /v2 prefix)
security:
- authToken: []
tags:
- name: Carriers
  description: Carriers, carrier relationships, and carrier assignments. (partly confirmed)
paths:
  /shipments/{shipmentId}/carrier-assignments/:
    parameters:
    - $ref: '#/components/parameters/ShipmentId'
    post:
      operationId: createCarrierAssignment
      tags:
      - Carriers
      summary: Create a new carrier assignment
      description: Assigns a carrier to a shipment. (confirmed)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierAssignment'
      responses:
        '201':
          description: The created carrier assignment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierAssignment'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /carriers/:
    get:
      operationId: listCarriers
      tags:
      - Carriers
      summary: List carriers
      description: Lists carriers in your network, including compliance and performance master data. Modeled from the documented carriers resource group. (modeled)
      responses:
        '200':
          description: A list of carriers.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Carrier'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /carriers/{carrierId}/:
    parameters:
    - name: carrierId
      in: path
      required: true
      description: The ID of the carrier.
      schema:
        type: string
    get:
      operationId: getCarrier
      tags:
      - Carriers
      summary: Retrieve a carrier
      description: Retrieves a single carrier by its ID. (modeled)
      responses:
        '200':
          description: The requested carrier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Carrier'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    ShipmentId:
      name: shipmentId
      in: path
      required: true
      description: The ID of the shipment.
      schema:
        type: string
  schemas:
    CarrierAssignment:
      type: object
      properties:
        id:
          type: string
        carrier:
          type: string
        rate:
          type: number
        currency:
          type: string
    Error:
      type: object
      properties:
        error_description:
          type: string
        errors:
          type: array
          items:
            type: object
            additionalProperties: true
    Carrier:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        scac:
          type: string
        dot_number:
          type: string
        mc_number:
          type: string
        compliance_status:
          type: string
  securitySchemes:
    authToken:
      type: apiKey
      in: header
      name: Authorization
      description: Company-scoped API key passed in the Authorization header (the docs refer to this as the AuthToken scheme). Production and sandbox use separate keys. Keys can be permission-restricted.