openapi: 3.1.0
info:
  title: Vizion Container Tracking API
  description: >-
    The Vizion Container Tracking API provides standardized shipment tracking
    events from ocean carriers, terminals, rail, and customs data sources.
    Subscribe to a container by providing its container ID and carrier SCAC code.
    Receive real-time updates via webhooks or poll for tracking milestones via
    GET endpoints. All events follow a consistent JSON schema regardless of
    carrier or data source.
  version: 1.0.0
  contact:
    name: Vizion Support
    url: https://support.vizionapi.com/
  license:
    name: Proprietary
    url: https://www.vizionapi.com/
externalDocs:
  description: Vizion API Documentation
  url: https://docs.vizionapi.com
servers:
  - url: https://prod.vizionapi.com
    description: Vizion Production API
tags:
  - name: References
    description: Manage container tracking subscriptions (references)
  - name: Updates
    description: Retrieve tracking event updates for a reference
  - name: Webhooks
    description: Real-time webhook payloads delivered to your callback URL
paths:
  /references:
    get:
      operationId: listReferences
      summary: List Active References
      description: Returns a paginated list of all active container tracking references for your account.
      tags:
        - References
      security:
        - ApiKeyAuth: []
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
          description: Page number for pagination
        - name: per_page
          in: query
          required: false
          schema:
            type: integer
            default: 20
            maximum: 100
          description: Number of references per page
      responses:
        '200':
          description: List of references
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Reference'
                  total:
                    type: integer
                  page:
                    type: integer
                  per_page:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createReference
      summary: Create Container Reference
      description: >-
        Subscribe to tracking updates for a container. Provide the container ID
        and carrier SCAC code. Optionally include a callback_url to receive
        real-time webhook updates. Once created, Vizion will begin tracking
        the container and deliver events as they occur.
      tags:
        - References
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReferenceRequest'
            examples:
              byCarrierCode:
                summary: Create reference with carrier SCAC code
                value:
                  container_id: "MSCU1234567"
                  carrier_code: "MSCU"
                  callback_url: "https://myapp.example.com/webhooks/vizion"
      responses:
        '200':
          description: Reference created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reference'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /references/{reference_id}:
    get:
      operationId: getReference
      summary: Get Reference Status
      description: Retrieve the current status and metadata for a specific container tracking reference.
      tags:
        - References
      security:
        - ApiKeyAuth: []
      parameters:
        - name: reference_id
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the reference returned when it was created
      responses:
        '200':
          description: Reference details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reference'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteReference
      summary: Delete Reference
      description: Cancel tracking and delete a container reference. No further webhook updates will be sent.
      tags:
        - References
      security:
        - ApiKeyAuth: []
      parameters:
        - name: reference_id
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the reference to delete
      responses:
        '200':
          description: Reference deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /references/{reference_id}/updates:
    get:
      operationId: listReferenceUpdates
      summary: List Reference Updates
      description: >-
        Retrieve tracking event updates for a specific reference. This is the
        polling alternative to webhooks. Returns all tracking milestones and
        location events received for the container since subscription.
      tags:
        - Updates
      security:
        - ApiKeyAuth: []
      parameters:
        - name: reference_id
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the reference
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          required: false
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: List of tracking updates
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TrackingUpdate'
                  total:
                    type: integer
                  page:
                    type: integer
                  per_page:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your Vizion API key. Include in all requests.
  schemas:
    CreateReferenceRequest:
      type: object
      required:
        - container_id
        - carrier_code
      description: Request body for creating a container tracking reference.
      properties:
        container_id:
          type: string
          description: The container identification number (e.g. MSCU1234567).
          example: "MSCU1234567"
        carrier_code:
          type: string
          description: SCAC carrier code (e.g. MSCU for MSC, MAEU for Maersk).
          example: "MSCU"
        callback_url:
          type: string
          format: uri
          description: >-
            Webhook endpoint URL. When provided, Vizion will POST tracking
            updates to this URL as they become available.
          example: "https://myapp.example.com/webhooks/vizion"
    Reference:
      type: object
      description: A container tracking subscription (reference) with status metadata.
      properties:
        id:
          type: string
          description: Unique reference identifier.
          example: "ref_abc123"
        container_id:
          type: string
          description: The tracked container identification number.
          example: "MSCU1234567"
        carrier_scac:
          type: string
          description: The carrier SCAC code used for tracking.
          example: "MSCU"
        active:
          type: boolean
          description: Whether the reference is actively receiving tracking updates.
          example: true
        callback_url:
          type: string
          format: uri
          description: Webhook URL for real-time update delivery.
          example: "https://myapp.example.com/webhooks/vizion"
        last_update_status:
          type: string
          description: Status of the last tracking update delivery attempt.
          enum:
            - success
            - pending
            - failed
            - none
        created_at:
          type: string
          format: date-time
          description: Timestamp when the reference was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp of the last update.
    TrackingUpdate:
      type: object
      description: A tracking event update for a container reference.
      properties:
        id:
          type: string
          description: Unique update identifier.
        reference_id:
          type: string
          description: The reference ID this update belongs to.
        container_id:
          type: string
          description: Container identification number.
        carrier_scac:
          type: string
          description: Carrier SCAC code.
        events:
          type: array
          description: Array of tracking milestone events.
          items:
            $ref: '#/components/schemas/TrackingEvent'
        estimated_departure:
          type: string
          format: date-time
          description: Estimated departure from origin port.
        estimated_arrival:
          type: string
          format: date-time
          description: Estimated arrival at destination port.
        actual_departure:
          type: string
          format: date-time
          description: Actual departure date.
        actual_arrival:
          type: string
          format: date-time
          description: Actual arrival date.
        origin:
          $ref: '#/components/schemas/Location'
        destination:
          $ref: '#/components/schemas/Location'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    TrackingEvent:
      type: object
      description: An individual tracking milestone event.
      properties:
        description:
          type: string
          description: Human-readable event description.
          example: "Container loaded on vessel"
        event_type:
          type: string
          description: Standardized event type code.
          example: "LOAD"
        event_timestamp:
          type: string
          format: date-time
          description: When the event occurred.
        location:
          $ref: '#/components/schemas/Location'
        vessel:
          $ref: '#/components/schemas/Vessel'
        is_actual:
          type: boolean
          description: True if this is an actual (historical) event; false if estimated.
    Location:
      type: object
      description: A geographic location (port, terminal, or rail yard).
      properties:
        name:
          type: string
          description: Location name.
          example: "Port of Los Angeles"
        locode:
          type: string
          description: UN/LOCODE for the location.
          example: "USLAX"
        country:
          type: string
          description: Two-letter ISO 3166-1 country code.
          example: "US"
        city:
          type: string
          description: City name.
          example: "Los Angeles"
        state:
          type: string
          description: State or province.
          example: "CA"
        timezone:
          type: string
          description: IANA timezone identifier.
          example: "America/Los_Angeles"
    Vessel:
      type: object
      description: Vessel information for a tracking event.
      properties:
        name:
          type: string
          description: Vessel name.
          example: "MSC MAYA"
        imo:
          type: string
          description: IMO vessel number.
          example: "9398405"
        voyage:
          type: string
          description: Voyage number.
          example: "FE427R"
    Error:
      type: object
      description: Standard error response.
      properties:
        error:
          type: string
          description: Error type or code.
        message:
          type: string
          description: Human-readable error message.
        details:
          type: object
          description: Additional error details.
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: unauthorized
            message: Invalid or missing X-API-Key header
    BadRequest:
      description: Invalid request body or parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Reference not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: not_found
            message: Reference not found
    UnprocessableEntity:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'