openapi: 3.0.1
info:
  title: Terminal49 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
  - name: Shipments
  - name: Containers
  - name: Transport Events
  - name: Terminals
  - name: Shipping Lines
  - name: Webhooks
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'
  /shipments:
    get:
      operationId: listShipments
      tags:
        - Shipments
      summary: List shipments
      parameters:
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A list of shipments.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ShipmentList'
  /shipments/{id}:
    get:
      operationId: getShipment
      tags:
        - Shipments
      summary: Retrieve a shipment
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: The requested shipment.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ShipmentSingle'
    patch:
      operationId: updateShipment
      tags:
        - Shipments
      summary: Edit a shipment
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/ShipmentSingle'
      responses:
        '200':
          description: The updated shipment.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ShipmentSingle'
  /shipments/{id}/stop_tracking:
    post:
      operationId: stopTrackingShipment
      tags:
        - Shipments
      summary: Stop tracking a shipment
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: Tracking stopped.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ShipmentSingle'
  /shipments/{id}/resume_tracking:
    post:
      operationId: resumeTrackingShipment
      tags:
        - Shipments
      summary: Resume tracking a shipment
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: Tracking resumed.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ShipmentSingle'
  /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}/transport_events:
    get:
      operationId: listContainerTransportEvents
      tags:
        - Transport Events
      summary: List transport events for a container
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: A list of transport events.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/TransportEventList'
  /containers/{id}/raw_events:
    get:
      operationId: listContainerRawEvents
      tags:
        - Transport Events
      summary: List raw events for a container (deprecated)
      deprecated: true
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: A list of raw events.
  /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.
  /transport_events:
    get:
      operationId: listTransportEvents
      tags:
        - Transport Events
      summary: List transport events
      parameters:
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A list of transport events.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/TransportEventList'
  /shipping_lines:
    get:
      operationId: listShippingLines
      tags:
        - Shipping Lines
      summary: List shipping lines
      responses:
        '200':
          description: A list of supported shipping lines with SCAC codes.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ShippingLineList'
  /shipping_lines/{id}:
    get:
      operationId: getShippingLine
      tags:
        - Shipping Lines
      summary: Retrieve a shipping line
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: The requested shipping line.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ShippingLineSingle'
  /terminals/{id}:
    get:
      operationId: getTerminal
      tags:
        - Terminals
      summary: Retrieve a terminal
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: The requested terminal.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/TerminalSingle'
  /webhooks:
    get:
      operationId: listWebhooks
      tags:
        - Webhooks
      summary: List webhooks
      responses:
        '200':
          description: A list of webhooks.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/WebhookList'
    post:
      operationId: createWebhook
      tags:
        - Webhooks
      summary: Create a webhook
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/WebhookSingle'
      responses:
        '201':
          description: The created webhook.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/WebhookSingle'
  /webhooks/{id}:
    get:
      operationId: getWebhook
      tags:
        - Webhooks
      summary: Retrieve a webhook
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: The requested webhook.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/WebhookSingle'
    patch:
      operationId: updateWebhook
      tags:
        - Webhooks
      summary: Edit a webhook
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/WebhookSingle'
      responses:
        '200':
          description: The updated webhook.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/WebhookSingle'
    delete:
      operationId: deleteWebhook
      tags:
        - Webhooks
      summary: Delete a webhook
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '204':
          description: Webhook deleted.
  /webhooks/{id}/test:
    post:
      operationId: testWebhook
      tags:
        - Webhooks
      summary: Trigger a test delivery for a webhook
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '202':
          description: Test delivery triggered.
  /webhook_notifications:
    get:
      operationId: listWebhookNotifications
      tags:
        - Webhooks
      summary: List webhook notifications
      parameters:
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A list of webhook notifications.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/WebhookNotificationList'
  /webhook_notifications/{id}:
    get:
      operationId: getWebhookNotification
      tags:
        - Webhooks
      summary: Retrieve a webhook notification
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: The requested webhook notification.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/WebhookNotificationSingle'
components:
  securitySchemes:
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Token-based authentication. Send the header
        `Authorization: Token YOUR_API_KEY`.
  parameters:
    ResourceId:
      name: id
      in: path
      required: true
      description: The resource identifier (UUID).
      schema:
        type: string
    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
  schemas:
    JsonApiLinks:
      type: object
      properties:
        self:
          type: string
        first:
          type: string
        prev:
          type: string
        next:
          type: string
        last:
          type: string
    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
    TrackingRequestResource:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum: [tracking_request]
        attributes:
          $ref: '#/components/schemas/TrackingRequestAttributes'
    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
    TrackingRequestSingle:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/TrackingRequestResource'
    TrackingRequestList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TrackingRequestResource'
        links:
          $ref: '#/components/schemas/JsonApiLinks'
    ShipmentAttributes:
      type: object
      properties:
        bill_of_lading_number:
          type: string
        normalized_number:
          type: string
        ref_numbers:
          type: array
          items:
            type: string
        shipping_line_scac:
          type: string
        shipping_line_name:
          type: string
        shipping_line_short_name:
          type: string
        port_of_lading_locode:
          type: string
        port_of_lading_name:
          type: string
        port_of_discharge_locode:
          type: string
        port_of_discharge_name:
          type: string
        destination_locode:
          type: string
        destination_name:
          type: string
        pod_vessel_name:
          type: string
        pod_vessel_imo:
          type: string
        pod_voyage_number:
          type: string
        pol_atd_at:
          type: string
          format: date-time
          nullable: true
        pod_eta_at:
          type: string
          format: date-time
          nullable: true
        pod_ata_at:
          type: string
          format: date-time
          nullable: true
        destination_eta_at:
          type: string
          format: date-time
          nullable: true
        destination_ata_at:
          type: string
          format: date-time
          nullable: true
        line_tracking_stopped_at:
          type: string
          format: date-time
          nullable: true
        line_tracking_stopped_reason:
          type: string
          nullable: true
    ShipmentResource:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum: [shipment]
        attributes:
          $ref: '#/components/schemas/ShipmentAttributes'
        relationships:
          type: object
    ShipmentSingle:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ShipmentResource'
    ShipmentList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentResource'
        links:
          $ref: '#/components/schemas/JsonApiLinks'
    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
    ContainerResource:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum: [container]
        attributes:
          $ref: '#/components/schemas/ContainerAttributes'
        relationships:
          type: object
    ContainerSingle:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ContainerResource'
    ContainerList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ContainerResource'
        links:
          $ref: '#/components/schemas/JsonApiLinks'
    TransportEventAttributes:
      type: object
      properties:
        event:
          type: string
          description: Normalized milestone name (e.g. vessel_departed, vessel_arrived, transshipment_discharged, full_out, rail_departed).
        created_at:
          type: string
          format: date-time
        timestamp:
          type: string
          format: date-time
        location_locode:
          type: string
          nullable: true
        timezone:
          type: string
          nullable: true
        voyage_number:
          type: string
          nullable: true
        vessel_name:
          type: string
          nullable: true
        vessel_imo:
          type: string
          nullable: true
    TransportEventResource:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum: [transport_event]
        attributes:
          $ref: '#/components/schemas/TransportEventAttributes'
    TransportEventList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TransportEventResource'
        links:
          $ref: '#/components/schemas/JsonApiLinks'
    ShippingLineAttributes:
      type: object
      properties:
        scac:
          type: string
        name:
          type: string
        short_name:
          type: string
        bill_of_lading_prefixes:
          type: array
          items:
            type: string
    ShippingLineResource:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum: [shipping_line]
        attributes:
          $ref: '#/components/schemas/ShippingLineAttributes'
    ShippingLineSingle:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ShippingLineResource'
    ShippingLineList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ShippingLineResource'
        links:
          $ref: '#/components/schemas/JsonApiLinks'
    TerminalAttributes:
      type: object
      properties:
        nickname:
          type: string
        name:
          type: string
        firms_code:
          type: string
          nullable: true
        smdg_code:
          type: string
          nullable: true
        port_locode:
          type: string
    TerminalResource:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum: [terminal]
        attributes:
          $ref: '#/components/schemas/TerminalAttributes'
    TerminalSingle:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/TerminalResource'
    WebhookAttributes:
      type: object
      properties:
        url:
          type: string
          description: The callback URL Terminal49 POSTs notifications to.
        active:
          type: boolean
        events:
          type: array
          items:
            type: string
            description: Event types to subscribe to (e.g. tracking_request.succeeded, container.transport.vessel_departed).
        secret:
          type: string
          description: Shared secret used to sign notification payloads.
        created_at:
          type: string
          format: date-time
    WebhookResource:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum: [webhook]
        attributes:
          $ref: '#/components/schemas/WebhookAttributes'
    WebhookSingle:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/WebhookResource'
    WebhookList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/WebhookResource'
        links:
          $ref: '#/components/schemas/JsonApiLinks'
    WebhookNotificationAttributes:
      type: object
      properties:
        event:
          type: string
        delivery_status:
          type: string
          enum:
            - pending
            - succeeded
            - failed
        response_status_code:
          type: integer
          nullable: true
        created_at:
          type: string
          format: date-time
        body:
          type: object
          description: The JSON:API payload delivered to the webhook URL.
    WebhookNotificationResource:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum: [webhook_notification]
        attributes:
          $ref: '#/components/schemas/WebhookNotificationAttributes'
    WebhookNotificationSingle:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/WebhookNotificationResource'
    WebhookNotificationList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/WebhookNotificationResource'
        links:
          $ref: '#/components/schemas/JsonApiLinks'