openapi: 3.0.1
info:
  title: Cargoson Carriers Price Requests API
  description: Cargoson is a multi-carrier transport management (TMS) REST API. It exposes a single, unified interface for requesting freight rates, creating shipment queries and direct bookings, retrieving labels and tracking details, and listing carrier services across 2,000+ carriers. Authentication uses an API key as a Bearer token. Requests must send an Accept header of `application/vnd.api.v1`. Endpoints and field names below reflect Cargoson's public integration documentation; request/response schemas not published by Cargoson are intentionally left open (additionalProperties true) rather than fabricated.
  termsOfService: https://www.cargoson.com/en/terms
  contact:
    name: Cargoson Support
    url: https://www.cargoson.com/en/integrations
  version: '1'
servers:
- url: https://www.cargoson.com/api/v1
  description: Cargoson production API (v1)
security:
- bearerAuth: []
tags:
- name: Price Requests
  description: Retrieve live freight rate quotes across activated carriers.
paths:
  /freightPrices/list:
    post:
      operationId: listFreightPrices
      tags:
      - Price Requests
      summary: Get freight rate quotes
      description: Returns live freight rate quotes and available services from the carriers activated on the account, based on the supplied collection, delivery, and shipment row details.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FreightPriceListRequest'
      responses:
        '200':
          description: List of freight price quotes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FreightPriceListResponse'
        '401':
          description: Missing or invalid API key.
        '422':
          description: Validation error in the request body.
components:
  schemas:
    FreightPrice:
      type: object
      description: A single carrier rate quote. Exact fields vary by carrier.
      additionalProperties: true
    ShipmentRow:
      type: object
      description: A single line/row in a shipment.
      properties:
        quantity:
          type: integer
          description: Number of packages.
        package_type:
          type: string
          description: Package type code (e.g. pallet, parcel, box).
        weight:
          type: number
          description: Weight of the row.
        description:
          type: string
          description: Goods description.
      additionalProperties: true
    FreightPriceListResponse:
      type: object
      description: Collection of freight price quotes.
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/FreightPrice'
      additionalProperties: true
    FreightPriceListRequest:
      type: object
      description: Request for freight rate quotes. Uses the same collection, delivery, and rows_attributes structure as a query.
      properties:
        collection_country:
          type: string
        collection_postcode:
          type: string
        collection_city:
          type: string
        delivery_country:
          type: string
        delivery_postcode:
          type: string
        delivery_city:
          type: string
        rows_attributes:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentRow'
      additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key passed as a Bearer token in the Authorization header (`Authorization: Bearer YOUR_API_KEY`). Requests must also send `Accept: application/vnd.api.v1`.'