openapi: 3.0.1
info:
  title: Terminal49 Containers Tracking Requests API
  description: Terminal49 v2 container and ocean-freight tracking API. A single integration to track Bills of Lading, bookings, and container numbers across global ocean carriers and North American rail, returning normalized milestones, ETAs, terminal availability, holds, demurrage fees, and last free day. The API follows the JSON:API specification; all requests and responses use the `application/vnd.api+json` media type and authenticate with a Token header.
  termsOfService: https://www.terminal49.com/terms-of-service/
  contact:
    name: Terminal49 Support
    url: https://terminal49.com/docs/api-docs/api-reference/introduction
    email: support@terminal49.com
  version: '2.0'
servers:
- url: https://api.terminal49.com/v2
  description: Terminal49 v2 production API
security:
- TokenAuth: []
tags:
- name: Tracking Requests
paths:
  /tracking_requests:
    get:
      operationId: listTrackingRequests
      tags:
      - Tracking Requests
      summary: List tracking requests
      parameters:
      - $ref: '#/components/parameters/PageNumber'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A list of tracking requests.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/TrackingRequestList'
    post:
      operationId: createTrackingRequest
      tags:
      - Tracking Requests
      summary: Create a tracking request
      description: Ask Terminal49 to begin tracking a shipment by submitting a Bill of Lading, booking, or container number together with the carrier SCAC.
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/TrackingRequestCreate'
      responses:
        '201':
          description: The created tracking request.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/TrackingRequestSingle'
  /tracking_requests/{id}:
    get:
      operationId: getTrackingRequest
      tags:
      - Tracking Requests
      summary: Retrieve a tracking request
      parameters:
      - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: The requested tracking request.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/TrackingRequestSingle'
    patch:
      operationId: updateTrackingRequest
      tags:
      - Tracking Requests
      summary: Edit a tracking request
      parameters:
      - $ref: '#/components/parameters/ResourceId'
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/TrackingRequestSingle'
      responses:
        '200':
          description: The updated tracking request.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/TrackingRequestSingle'
components:
  parameters:
    PageNumber:
      name: page[number]
      in: query
      required: false
      description: Page number for JSON:API pagination.
      schema:
        type: integer
    PageSize:
      name: page[size]
      in: query
      required: false
      description: Number of records per page.
      schema:
        type: integer
    ResourceId:
      name: id
      in: path
      required: true
      description: The resource identifier (UUID).
      schema:
        type: string
  schemas:
    TrackingRequestAttributes:
      type: object
      properties:
        request_number:
          type: string
          description: The Bill of Lading, booking, or container number to track.
        request_type:
          type: string
          enum:
          - bill_of_lading
          - booking_number
          - container
        scac:
          type: string
          description: The carrier SCAC code.
        ref_numbers:
          type: array
          items:
            type: string
        status:
          type: string
          enum:
          - pending
          - created
          - failed
          - tracking_stopped
        failed_reason:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
    TrackingRequestSingle:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/TrackingRequestResource'
    JsonApiLinks:
      type: object
      properties:
        self:
          type: string
        first:
          type: string
        prev:
          type: string
        next:
          type: string
        last:
          type: string
    TrackingRequestCreate:
      type: object
      properties:
        data:
          type: object
          properties:
            type:
              type: string
              enum:
              - tracking_request
            attributes:
              type: object
              required:
              - request_number
              - request_type
              - scac
              properties:
                request_number:
                  type: string
                request_type:
                  type: string
                  enum:
                  - bill_of_lading
                  - booking_number
                  - container
                scac:
                  type: string
                ref_numbers:
                  type: array
                  items:
                    type: string
    TrackingRequestList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TrackingRequestResource'
        links:
          $ref: '#/components/schemas/JsonApiLinks'
    TrackingRequestResource:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - tracking_request
        attributes:
          $ref: '#/components/schemas/TrackingRequestAttributes'
  securitySchemes:
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Token-based authentication. Send the header `Authorization: Token YOUR_API_KEY`.'