:::open-api-operation
---
operation:
  kind: operation
  method: post
  path: /shipments
  operationId: createShipment
  summary: Book a shipment
  deprecated: false
  tags:
    - Shipments
  requestBody:
    required: true
    content:
      - type: application/json
        schema:
          name: Shipment
          ref: "#/components/schemas/Shipment"
          types:
            - object
          title: Shipment
          description: One shipment, as the first API saw it.
          properties:
            - name: id
              required: true
              schema:
                types:
                  - string
                format: uuid
                readOnly: true
            - name: label
              required: true
              schema:
                types:
                  - string
                description: Renamed to `reference` in 2.x.
                constraints:
                  minLength: 1
                  maxLength: 120
            - name: state
              required: true
              schema:
                types:
                  - string
                description: Renamed to `status` in 2.x, and gained `cancelled`.
                enum: &a1
                  - booked
                  - sailing
                  - landed
            - name: createdAt
              required: false
              schema:
                types:
                  - string
                format: date-time
                readOnly: true
  responses:
    - status: "201"
      description: Booked.
      content:
        - type: application/json
          schema:
            name: Shipment
            ref: "#/components/schemas/Shipment"
            types:
              - object
            title: Shipment
            description: One shipment, as the first API saw it.
            properties:
              - name: id
                required: true
                schema:
                  types:
                    - string
                  format: uuid
                  readOnly: true
              - name: label
                required: true
                schema:
                  types:
                    - string
                  description: Renamed to `reference` in 2.x.
                  constraints:
                    minLength: 1
                    maxLength: 120
              - name: state
                required: true
                schema:
                  types:
                    - string
                  description: Renamed to `status` in 2.x, and gained `cancelled`.
                  enum: *a1
              - name: createdAt
                required: false
                schema:
                  types:
                    - string
                  format: date-time
                  readOnly: true
servers:
  - url: https://api.example.org/v1
    description: The invented production host, switched off.
security:
  - - key: apiKey
      scheme:
        key: apiKey
        type: apiKey
        description: A key from the account page.
        name: X-Api-Key
        in: header
securitySchemes:
  - key: apiKey
    type: apiKey
    description: A key from the account page.
    name: X-Api-Key
    in: header
---
:::