:::open-api-operation
---
operation:
  kind: operation
  method: post
  path: /consignments
  operationId: createConsignment
  summary: Book a consignment
  deprecated: false
  tags:
    - Consignments
  requestBody:
    required: true
    content:
      - type: application/json
        schema:
          name: Consignment
          ref: "#/components/schemas/Consignment"
          types:
            - object
          title: Consignment
          description: One consignment, as 2.x sees it.
          properties:
            - name: id
              required: true
              schema:
                types:
                  - string
                format: uuid
                readOnly: true
            - name: reference
              required: true
              schema:
                types:
                  - string
                description: Called `label` in 1.x.
                constraints:
                  minLength: 1
                  maxLength: 120
            - name: status
              required: true
              schema:
                types:
                  - string
                description: Called `state` in 1.x. `cancelled` is new in 3.x.
                enum: &a1
                  - booked
                  - sailing
                  - landed
            - name: createdAt
              required: false
              schema:
                types:
                  - string
                format: date-time
                readOnly: true
        examples:
          - name: minimal
            summary: The smallest body that works
            value:
              reference: HB-1042
              status: booked
  responses:
    - status: "201"
      description: Booked.
      headers:
        - name: Location
          required: true
          schema:
            types:
              - string
            format: uri
      content:
        - type: application/json
          schema:
            name: Consignment
            ref: "#/components/schemas/Consignment"
            types:
              - object
            title: Consignment
            description: One consignment, as 2.x sees it.
            properties:
              - name: id
                required: true
                schema:
                  types:
                    - string
                  format: uuid
                  readOnly: true
              - name: reference
                required: true
                schema:
                  types:
                    - string
                  description: Called `label` in 1.x.
                  constraints:
                    minLength: 1
                    maxLength: 120
              - name: status
                required: true
                schema:
                  types:
                    - string
                  description: Called `state` in 1.x. `cancelled` is new in 3.x.
                  enum: *a1
              - name: createdAt
                required: false
                schema:
                  types:
                    - string
                  format: date-time
                  readOnly: true
    - 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
              - name: status
                required: true
                schema:
                  types:
                    - integer
                  constraints:
                    minimum: 400
                    maximum: 599
servers:
  - url: https://api.example.org/v2
    description: The invented production host.
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
        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
    bearerFormat: JWT
---
:::