:::open-api-operation
---
operation:
  kind: operation
  method: get
  path: /consignments
  operationId: listConsignments
  summary: List consignments
  deprecated: false
  tags:
    - Consignments
  parameters:
    - name: limit
      in: query
      description: How many consignments to return.
      required: false
      schema:
        types:
          - integer
        default: 20
        constraints:
          minimum: 1
          maximum: 100
    - name: cursor
      in: query
      description: Where to continue from.
      required: false
      schema:
        types:
          - string
  responses:
    - status: "200"
      description: A page of consignments.
      content:
        - type: application/json
          schema:
            types:
              - object
            properties:
              - name: items
                required: true
                schema:
                  types:
                    - array
                  items:
                    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:
                            - booked
                            - sailing
                            - landed
                      - name: createdAt
                        required: false
                        schema:
                          types:
                            - string
                          format: date-time
                          readOnly: true
              - name: next
                required: false
                schema:
                  types:
                    - string
                    - "null"
                  description: The cursor for the following page, if any.
    - status: "400"
      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
---
Returns a page of consignments, newest first.

**Changed in 2.0.** Paging is by `cursor` rather than by page number;
the value comes from the previous response's `next` field.
:::