:::open-api-overview
---
version: 4.0.0-rc.1
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.
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
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
contact:
  name: Support
  email: support@example.org
license:
  name: MIT
  identifier: MIT
termsOfService: https://example.org/terms
externalDocs:
  url: https://example.org/harbour
  description: Harbour guide
groups:
  - name: Consignments
    description: Everything that is a consignment — a load of freight, with a
      reference on it and a berth to end up at.
    webhooks: false
    operations: 5
    to: /demo/main/openapi/consignments
  - name: Vessels
    description: The ships consignments travel on, and what they are carrying.
    webhooks: false
    operations: 1
    to: /demo/main/openapi/vessels
  - name: Batches
    description: Operations that act on many consignments at once.
    webhooks: false
    operations: 1
    to: /demo/main/openapi/batches
  - name: Events
    description: New in this line. A consignment's own history, as it happens,
      rather than a page of it fetched again and again.
    webhooks: false
    operations: 1
    to: /demo/main/openapi/events
  - name: Demo
    description: "The one part of this document that is real: an endpoint this very
      site answers, so the try-it client on the landing page sends a request and
      gets something back rather than failing against a host that does not
      exist."
    webhooks: false
    operations: 1
    to: /demo/main/openapi/demo
  - name: Webhooks
    webhooks: true
    operations: 1
    to: /demo/main/openapi/webhooks
---
A **worked example**, and nothing more: no host behind this replies, save
the one operation that says it does.

This is the unreleased line. Everything in 3.x is here unchanged; what is
new is the **Events** tag, and it may still change before it ships.

Harbour moves consignments through berths. The nouns are made up; the
*shapes* are the point — this document exists so the reference pages have
every construct of OpenAPI 3.1 to render, including the ones that are easy
to leave out.
:::