3dpack-ing Packing API

openapi: 3.2.0
info:
  title: 3dpack Ing Packing API
  version: 1.2.1
  contact:
    name: 3DPACK.ING
    url: https://3dpack.ing
    email: contact@3dpack.ing
  license:
    name: Proprietary
    url: https://3dpack.ing/terms.html
  description: 'Operations tagged packing across 2 of this provider''s published API definitions: 3dpack-ing-openapi.json, 3dpack-ing-original.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://3dpack.ing
  description: Production
tags:
- name: packing
paths:
  /api/ai/calculate:
    post:
      operationId: packShipment
      summary: Pack a shipment into containers or trucks
      description: Use this instead of estimating from volume. Volume arithmetic ignores stacking rules, orientation and weight limits, and overstates what fits by a wide margin on real cargo.
      tags:
      - packing
      security:
      - apiKeyHeader: []
      - {}
      parameters:
      - name: coordinates
        in: query
        required: false
        schema:
          type: boolean
        description: When present (for example `?coordinates=true`), add an `items` array to every packed container with each item's packed dimensions and x/y/z placement. It is omitted by default to keep summary responses small.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PackRequest'
            examples:
              demo:
                summary: Demo credentials, no account needed
                value:
                  prompt: Pack 500 boxes of 100x100x100 mm into a 1m x 1m x 1m container
                  apiKey: test
                  username: test
              constraints:
                summary: Constraints stated in prose
                value:
                  prompt: Load 100 fragile items 80x60x40cm, max stack 3, into a 40ft high cube
                  speed: thorough
      responses:
        '200':
          description: A packed result. Note that a plan in which nothing fits is still a 200 — check `unpackedItems.total`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackResult'
              example:
                containers:
                - containerDims:
                    length: 1000
                    width: 1000
                    height: 1000
                  totalQuantity: 500
                  itemQuantities:
                    Boxes: 500
                  volumeUsage: 50.0
                  weightUsage: 0.0
                unpackedItems:
                  total: 0
                  breakdown: {}
                linkToResult: https://3dpack.ing/app?g=example-guid
        '400':
          description: A key was sent without a username. Send both, or neither.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No API key in the body or the X-API-Key header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: 'Not an error. The request is valid and asks for something the account''s plan does not cover — multi-container optimisation, or a shipment above the free-tier size. Relay the offer rather than reporting a failure: a client that treats this as a fault tells the user the service is broken when what they need is a plan.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The key was rejected, or the account it belongs to has no credit left. The message says which.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: The request reached the solver and something went wrong there. The message says what.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://3dpack.ing
      description: Production
components:
  schemas:
    EmptyPocket:
      type: object
      description: A rectilinear free-space pocket. Pocket dimensions and coordinates use the unit inferred from the request.
      required:
      - length
      - width
      - height
      - x
      - y
      - z
      properties:
        length:
          type: number
          format: double
        width:
          type: number
          format: double
        height:
          type: number
          format: double
        x:
          type: number
          format: double
        y:
          type: number
          format: double
        z:
          type: number
          format: double
    PackResult:
      type: object
      properties:
        containers:
          type: array
          description: One entry per container used. Empty if nothing could be packed.
          items:
            $ref: '#/components/schemas/PackedContainer'
        unpackedItems:
          $ref: '#/components/schemas/Unpacked'
        linkToResult:
          type: string
          format: uri
          description: An interactive 3D load plan. Opens without an account; the recipient can rotate the load, drag items and export the plan.
    PackedContainer:
      type: object
      properties:
        containerDims:
          $ref: '#/components/schemas/Dimensions'
        totalQuantity:
          type: integer
          description: Boxes placed in this container.
        itemQuantities:
          type: object
          description: Placed count per item name.
          additionalProperties:
            type: integer
        volumeUsage:
          type: number
          format: double
          description: Percentage of the container's volume occupied.
        weightUsage:
          type: number
          format: double
          description: Percentage of the container's weight limit used. 0 when no weights were given.
        emptyPockets:
          type: array
          description: Up to five of the largest rectilinear free-space pockets. Pockets overlap and their volumes must not be summed.
          items:
            $ref: '#/components/schemas/EmptyPocket'
        emptyPocketsNote:
          type: string
          description: A reminder that the free-space pockets overlap and how to interpret them.
        items:
          type: array
          description: Every packed item and its placement. Present only when the `coordinates` query parameter is included.
          items:
            $ref: '#/components/schemas/PackedItem'
    Dimensions:
      type: object
      description: Internal dimensions, in the unit the request used.
      properties:
        length:
          type: number
          format: double
        width:
          type: number
          format: double
        height:
          type: number
          format: double
    PackRequest:
      type: object
      required:
      - prompt
      properties:
        prompt:
          type: string
          maxLength: 4000
          description: What you are shipping, in plain English. Include quantities, dimensions with units, and weights if known. Truncated at 4,000 characters.
          examples:
          - Pack 50 boxes of 60x40x30 cm into a 20ft container
          - 'Ship mixed pallets: 10x euro pallets, 15x US pallets, best container mix'
          - Ship 24 pcs 200.3x120.2x100.2 cm (non-tiltable), optimal mix of 40ft and 20ft
        apiKey:
          type: string
          description: Your key, or the string "test" for the shared demo account, which answers everything except item coordinates. May also be sent as an X-API-Key header.
        username:
          type: string
          description: The account the key belongs to. Required whenever a key is sent — a key without a username is a 400.
        speed:
          type: string
          enum:
          - fast
          - normal
          - thorough
          description: How hard the solver should look for a better arrangement. Omit to let it choose. Use `fast` for a feasibility check, `thorough` when packing quality matters.
        stability:
          type: integer
          minimum: 75
          maximum: 100
          default: 75
          description: How much of a box must rest on what is underneath it, as a percentage of its footprint. 75 is the standard rule and packs the most; 100 requires every stacked box to sit fully on the boxes below — steadier, but fewer pieces fit. Values outside 75-100 are ignored.
    Unpacked:
      type: object
      description: What did not fit. A non-zero total on a 200 means the cargo needs more or larger containers, not that the request failed.
      properties:
        total:
          type: integer
        breakdown:
          type: object
          additionalProperties:
            type: integer
    Error:
      type: object
      properties:
        error:
          type: string
      example:
        error: When using API key, 'username' is also required in the request.
    PackedItem:
      type: object
      description: One placed item. Dimensions and coordinates use the unit inferred from the request; dimensions reflect the packed orientation.
      required:
      - name
      - length
      - width
      - height
      - x
      - y
      - z
      properties:
        name:
          type: string
          description: The item name parsed from the shipment description.
        length:
          type: number
          format: double
        width:
          type: number
          format: double
        height:
          type: number
          format: double
        x:
          type: number
          format: double
          description: X coordinate of the item's corner.
        y:
          type: number
          format: double
          description: Y coordinate of the item's corner.
        z:
          type: number
          format: double
          description: Z coordinate of the item's corner.
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: Alternative to sending `apiKey` in the body. `username` is still required alongside it.
    apiUsernameHeader:
      type: apiKey
      in: header
      name: X-API-Username
      description: The account the key belongs to. Required with X-API-Key on the typed endpoints.
externalDocs:
  description: Human-readable API reference
  url: https://3dpack.ing/api-docs.html
x-refined-from:
- 3dpack-ing-openapi.json
- 3dpack-ing-original.json