openapi: 3.0.1
info:
  title: Terminal49 Containers 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: Containers
paths:
  /containers:
    get:
      operationId: listContainers
      tags:
      - Containers
      summary: List containers
      parameters:
      - $ref: '#/components/parameters/PageNumber'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A list of containers.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ContainerList'
  /containers/{id}:
    get:
      operationId: getContainer
      tags:
      - Containers
      summary: Retrieve a container
      parameters:
      - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: The requested container.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ContainerSingle'
    patch:
      operationId: updateContainer
      tags:
      - Containers
      summary: Edit a container
      parameters:
      - $ref: '#/components/parameters/ResourceId'
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/ContainerSingle'
      responses:
        '200':
          description: The updated container.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ContainerSingle'
  /containers/{id}/refresh:
    post:
      operationId: refreshContainer
      tags:
      - Containers
      summary: Force a container data refresh
      parameters:
      - $ref: '#/components/parameters/ResourceId'
      responses:
        '202':
          description: Refresh accepted.
  /containers/{id}/map:
    get:
      operationId: getContainerMap
      tags:
      - Containers
      summary: Retrieve GeoJSON map data for a container
      parameters:
      - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: GeoJSON map data for the container journey.
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:
    ContainerSingle:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ContainerResource'
    ContainerAttributes:
      type: object
      properties:
        number:
          type: string
        seal_number:
          type: string
          nullable: true
        ref_numbers:
          type: array
          items:
            type: string
        equipment_type:
          type: string
          description: e.g. dry, reefer, open_top, flat_rack, bulk, tank.
        equipment_length:
          type: integer
          description: Container length in feet (10, 20, 40, 45).
        equipment_height:
          type: string
          enum:
          - standard
          - high_cube
        weight_in_lbs:
          type: integer
          nullable: true
        current_status:
          type: string
          description: e.g. new, on_ship, available, delivered.
        availability_known:
          type: boolean
        available_for_pickup:
          type: boolean
          nullable: true
        pickup_lfd:
          type: string
          format: date-time
          nullable: true
          description: Last free day, coalesced from import deadlines.
        pickup_appointment_at:
          type: string
          format: date-time
          nullable: true
        pod_arrived_at:
          type: string
          format: date-time
          nullable: true
        pod_discharged_at:
          type: string
          format: date-time
          nullable: true
        pod_full_out_at:
          type: string
          format: date-time
          nullable: true
        location_at_pod_terminal:
          type: string
          nullable: true
        ind_eta_at:
          type: string
          format: date-time
          nullable: true
        ind_ata_at:
          type: string
          format: date-time
          nullable: true
        ind_rail_unloaded_at:
          type: string
          format: date-time
          nullable: true
        pod_rail_carrier_scac:
          type: string
          nullable: true
        ind_rail_carrier_scac:
          type: string
          nullable: true
        holds_at_pod_terminal:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              status:
                type: string
              description:
                type: string
        fees_at_pod_terminal:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                description: e.g. demurrage, exam, extended_dwell_time, other, total.
              amount:
                type: number
              currency:
                type: string
        terminal_checked_at:
          type: string
          format: date-time
          nullable: true
    ContainerList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ContainerResource'
        links:
          $ref: '#/components/schemas/JsonApiLinks'
    ContainerResource:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - container
        attributes:
          $ref: '#/components/schemas/ContainerAttributes'
        relationships:
          type: object
    JsonApiLinks:
      type: object
      properties:
        self:
          type: string
        first:
          type: string
        prev:
          type: string
        next:
          type: string
        last:
          type: string
  securitySchemes:
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Token-based authentication. Send the header `Authorization: Token YOUR_API_KEY`.'