openapi: 3.1.0
info:
  title: Flexport REST API
  version: "2023-07-01"
  description: |
    Best-effort OpenAPI 3.1 description of the Flexport REST API v2.
    Derived from the public developer documentation at https://apidocs.flexport.com/.
    Covers a representative subset of the v2 resource model: shipments, bookings,
    purchase orders, customs, documents, network entities, and webhooks. JSON
    request and response bodies use Flexport's standard envelope (`data`, `meta`,
    `errors`); operation-specific schemas are not modeled here.
  contact:
    name: Flexport
    url: https://www.flexport.com/
servers:
  - url: https://api.flexport.com
    description: Production
security:
  - oauth2: []
  - bearerAuth: []
tags:
  - name: Shipments
  - name: Bookings
  - name: PurchaseOrders
  - name: Customs
  - name: Documents
  - name: Network
  - name: Products
  - name: Invoices
  - name: Webhooks
paths:
  /v2/shipments:
    get:
      tags: [Shipments]
      summary: List shipments
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
      responses:
        '200': { $ref: '#/components/responses/Collection' }
  /v2/shipments/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      tags: [Shipments]
      summary: Retrieve a shipment
      responses:
        '200': { $ref: '#/components/responses/Resource' }
    patch:
      tags: [Shipments]
      summary: Update a shipment
      requestBody: { $ref: '#/components/requestBodies/JsonBody' }
      responses:
        '200': { $ref: '#/components/responses/Resource' }
  /v2/shipments/shareable:
    post:
      tags: [Shipments]
      summary: Create a shareable shipment URL
      requestBody: { $ref: '#/components/requestBodies/JsonBody' }
      responses:
        '201': { $ref: '#/components/responses/Resource' }
  /v2/containers:
    get:
      tags: [Shipments]
      summary: List containers
      responses:
        '200': { $ref: '#/components/responses/Collection' }
  /v2/container-legs:
    get:
      tags: [Shipments]
      summary: List container legs
      responses:
        '200': { $ref: '#/components/responses/Collection' }
  /v2/shipment-legs:
    get:
      tags: [Shipments]
      summary: List shipment legs
      responses:
        '200': { $ref: '#/components/responses/Collection' }
  /v2/bookings:
    get:
      tags: [Bookings]
      summary: List bookings
      responses:
        '200': { $ref: '#/components/responses/Collection' }
    post:
      tags: [Bookings]
      summary: Create a booking
      requestBody: { $ref: '#/components/requestBodies/JsonBody' }
      responses:
        '201': { $ref: '#/components/responses/Resource' }
  /v2/bookings/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      tags: [Bookings]
      summary: Retrieve a booking
      responses:
        '200': { $ref: '#/components/responses/Resource' }
  /v2/booking-amendments:
    post:
      tags: [Bookings]
      summary: Create a booking amendment
      requestBody: { $ref: '#/components/requestBodies/JsonBody' }
      responses:
        '201': { $ref: '#/components/responses/Resource' }
  /v2/booking-line-items:
    get:
      tags: [Bookings]
      summary: List booking line items
      responses:
        '200': { $ref: '#/components/responses/Collection' }
    post:
      tags: [Bookings]
      summary: Create a booking line item
      requestBody: { $ref: '#/components/requestBodies/JsonBody' }
      responses:
        '201': { $ref: '#/components/responses/Resource' }
  /v2/purchase-orders:
    get:
      tags: [PurchaseOrders]
      summary: List purchase orders
      responses:
        '200': { $ref: '#/components/responses/Collection' }
  /v2/purchase-order-line-items:
    get:
      tags: [PurchaseOrders]
      summary: List purchase order line items
      responses:
        '200': { $ref: '#/components/responses/Collection' }
  /v2/commercial-invoices:
    get:
      tags: [Customs]
      summary: List commercial invoices
      responses:
        '200': { $ref: '#/components/responses/Collection' }
  /v2/customs-entries:
    get:
      tags: [Customs]
      summary: List customs entries
      responses:
        '200': { $ref: '#/components/responses/Collection' }
  /v2/documents:
    get:
      tags: [Documents]
      summary: List documents
      responses:
        '200': { $ref: '#/components/responses/Collection' }
    post:
      tags: [Documents]
      summary: Upload a document
      requestBody: { $ref: '#/components/requestBodies/JsonBody' }
      responses:
        '201': { $ref: '#/components/responses/Resource' }
  /v2/companies:
    get:
      tags: [Network]
      summary: List companies
      responses:
        '200': { $ref: '#/components/responses/Collection' }
    post:
      tags: [Network]
      summary: Create a company
      requestBody: { $ref: '#/components/requestBodies/JsonBody' }
      responses:
        '201': { $ref: '#/components/responses/Resource' }
  /v2/contacts:
    get:
      tags: [Network]
      summary: List contacts
      responses:
        '200': { $ref: '#/components/responses/Collection' }
    post:
      tags: [Network]
      summary: Create a contact
      requestBody: { $ref: '#/components/requestBodies/JsonBody' }
      responses:
        '201': { $ref: '#/components/responses/Resource' }
  /v2/locations:
    get:
      tags: [Network]
      summary: List locations
      responses:
        '200': { $ref: '#/components/responses/Collection' }
    post:
      tags: [Network]
      summary: Create a location
      requestBody: { $ref: '#/components/requestBodies/JsonBody' }
      responses:
        '201': { $ref: '#/components/responses/Resource' }
  /v2/products:
    get:
      tags: [Products]
      summary: List products
      responses:
        '200': { $ref: '#/components/responses/Collection' }
    post:
      tags: [Products]
      summary: Create a product
      requestBody: { $ref: '#/components/requestBodies/JsonBody' }
      responses:
        '201': { $ref: '#/components/responses/Resource' }
  /v2/invoices:
    get:
      tags: [Invoices]
      summary: List invoices
      responses:
        '200': { $ref: '#/components/responses/Collection' }
  /v2/webhooks:
    get:
      tags: [Webhooks]
      summary: List webhook subscriptions
      responses:
        '200': { $ref: '#/components/responses/Collection' }
    post:
      tags: [Webhooks]
      summary: Create a webhook subscription
      requestBody: { $ref: '#/components/requestBodies/JsonBody' }
      responses:
        '201': { $ref: '#/components/responses/Resource' }
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 client credentials issued from the Flexport admin console
      flows:
        clientCredentials:
          tokenUrl: https://api.flexport.com/oauth/token
          scopes: {}
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    Id:
      name: id
      in: path
      required: true
      schema: { type: string }
    Page:
      name: page
      in: query
      required: false
      schema: { type: integer, minimum: 1 }
    PerPage:
      name: per_page
      in: query
      required: false
      schema: { type: integer, minimum: 1, maximum: 100 }
  requestBodies:
    JsonBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
  responses:
    Resource:
      description: Single resource envelope
      content:
        application/json:
          schema:
            type: object
            properties:
              data: { type: object, additionalProperties: true }
              meta: { type: object, additionalProperties: true }
    Collection:
      description: Collection envelope
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                items: { type: object, additionalProperties: true }
              meta: { type: object, additionalProperties: true }