:::open-api-operation
---
operation:
  kind: operation
  method: post
  path: /consignments
  operationId: createConsignment
  summary: Book a consignment
  deprecated: false
  tags:
    - Consignments
  parameters:
    - name: X-Request-Id
      in: header
      description: An identifier echoed back on every response.
      required: false
      schema:
        types:
          - string
        format: uuid
  requestBody:
    description: The consignment to book.
    required: true
    content:
      - type: application/json
        schema:
          name: NewConsignment
          ref: "#/components/schemas/NewConsignment"
          types:
            - object
          description: One consignment, as the API sees it.
          properties:
            - name: id
              required: true
              schema:
                types:
                  - string
                format: uuid
                readOnly: true
            - name: reference
              required: true
              schema:
                types:
                  - string
                constraints:
                  minLength: 1
                  maxLength: 120
            - name: status
              required: true
              schema:
                name: ConsignmentStatus
                ref: "#/components/schemas/ConsignmentStatus"
                types:
                  - string
                description: Where a consignment has got to.
                enum: &a1
                  - booked
                  - loading
                  - sailing
                  - landed
                  - cancelled
            - name: createdAt
              required: false
              schema:
                types:
                  - string
                format: date-time
                readOnly: true
            - name: parent
              required: false
              schema:
                ref: "#/components/schemas/Consignment"
                name: Consignment
                circular: true
            - name: tags
              required: false
              schema:
                types:
                  - array
                constraints:
                  uniqueItems: true
                items:
                  types:
                    - string
            - name: metadata
              required: false
              schema:
                types:
                  - object
                additionalProperties:
                  types:
                    - string
            - name: callbackUrl
              required: false
              schema:
                types:
                  - string
                format: uri
                description: Where to send the callback once the load is aboard.
        examples:
          - name: minimal
            summary: The smallest body that works
            value:
              reference: HB-1042
              status: booked
          - name: withManifest
            summary: With the paperwork attached
            value:
              reference: HB-1042
              status: booked
              callbackUrl: https://example.org/hooks/harbour
              tags:
                - refrigerated
      - type: multipart/form-data
        schema:
          types:
            - object
          properties:
            - name: reference
              required: false
              schema:
                types:
                  - string
            - name: manifest
              required: false
              schema:
                types:
                  - string
                format: binary
        encoding:
          - property: manifest
            contentType: application/pdf
  responses:
    - status: "201"
      description: Booked.
      headers:
        - name: Location
          description: Where the new consignment can be read.
          required: true
          schema:
            types:
              - string
            format: uri
      content:
        - type: application/json
          schema:
            name: Consignment
            ref: "#/components/schemas/Consignment"
            types:
              - object
            description: One consignment, as the API sees it.
            properties:
              - name: id
                required: true
                schema:
                  types:
                    - string
                  format: uuid
                  readOnly: true
              - name: reference
                required: true
                schema:
                  types:
                    - string
                  constraints:
                    minLength: 1
                    maxLength: 120
              - name: status
                required: true
                schema:
                  name: ConsignmentStatus
                  ref: "#/components/schemas/ConsignmentStatus"
                  types:
                    - string
                  description: Where a consignment has got to.
                  enum: *a1
              - name: createdAt
                required: false
                schema:
                  types:
                    - string
                  format: date-time
                  readOnly: true
              - name: parent
                required: false
                schema:
                  ref: "#/components/schemas/Consignment"
                  name: Consignment
                  circular: true
              - name: tags
                required: false
                schema:
                  types:
                    - array
                  constraints:
                    uniqueItems: true
                  items:
                    types:
                      - string
              - name: metadata
                required: false
                schema:
                  types:
                    - object
                  additionalProperties:
                    types:
                      - string
    - status: "422"
      description: Something went wrong, described the same way every time.
      content:
        - type: application/problem+json
          schema:
            name: Problem
            ref: "#/components/schemas/Problem"
            types:
              - object
            properties:
              - name: title
                required: true
                schema:
                  types:
                    - string
                  description: A short, human-readable summary.
              - name: status
                required: true
                schema:
                  types:
                    - integer
                  constraints:
                    minimum: 400
                    maximum: 599
              - name: detail
                required: false
                schema:
                  types:
                    - string
                    - "null"
  callbacks:
    - name: consignmentLoaded
      operations:
        - expression: "{$request.body#/callbackUrl}"
          method: post
          summary: Sent once the consignment has been loaded.
          requestBody:
            required: false
            content:
              - type: application/json
                schema:
                  name: Consignment
                  ref: "#/components/schemas/Consignment"
                  types:
                    - object
                  description: One consignment, as the API sees it.
                  properties:
                    - name: id
                      required: true
                      schema:
                        types:
                          - string
                        format: uuid
                        readOnly: true
                    - name: reference
                      required: true
                      schema:
                        types:
                          - string
                        constraints:
                          minLength: 1
                          maxLength: 120
                    - name: status
                      required: true
                      schema:
                        name: ConsignmentStatus
                        ref: "#/components/schemas/ConsignmentStatus"
                        types:
                          - string
                        description: Where a consignment has got to.
                        enum: *a1
                    - name: createdAt
                      required: false
                      schema:
                        types:
                          - string
                        format: date-time
                        readOnly: true
                    - name: parent
                      required: false
                      schema:
                        ref: "#/components/schemas/Consignment"
                        name: Consignment
                        circular: true
                    - name: tags
                      required: false
                      schema:
                        types:
                          - array
                        constraints:
                          uniqueItems: true
                        items:
                          types:
                            - string
                    - name: metadata
                      required: false
                      schema:
                        types:
                          - object
                        additionalProperties:
                          types:
                            - string
          responses:
            - status: "204"
              description: Acknowledged.
servers:
  - url: https://api.example.org/{stage}
    description: The invented production host.
    variables:
      - name: stage
        default: v3
        enum:
          - v1
          - v2
          - v3
        description: Which line of the API to talk to.
  - url: http://localhost:8080
    description: A local process, for trying things out.
security:
  - - key: apiKey
      scheme:
        key: apiKey
        type: apiKey
        description: A key from the account page.
        name: X-Api-Key
        in: header
  - - key: bearer
      scheme:
        key: bearer
        type: http
        description: A token obtained from the authorisation server.
        scheme: bearer
        example: demo-token
        bearerFormat: JWT
securitySchemes:
  - key: apiKey
    type: apiKey
    description: A key from the account page.
    name: X-Api-Key
    in: header
  - key: bearer
    type: http
    description: A token obtained from the authorisation server.
    scheme: bearer
    example: demo-token
    bearerFormat: JWT
  - key: oauth
    type: oauth2
    description: For applications acting on someone else's behalf.
    flows:
      - name: authorizationCode
        authorizationUrl: https://auth.example.org/authorize
        tokenUrl: https://auth.example.org/token
        scopes:
          - name: consignments:read
            description: Read consignments
          - name: consignments:write
            description: Book and change consignments
---
Books one consignment and tells you where it ended up.
:::