:::open-api-operation --- operation: kind: operation method: get path: /consignments operationId: listConsignments summary: List consignments 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 - 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 - name: status in: query description: Only consignments in these states. required: false style: form explode: false schema: types: - array constraints: uniqueItems: true items: name: ConsignmentStatus ref: "#/components/schemas/ConsignmentStatus" types: - string description: Where a consignment has got to. enum: &a1 - booked - loading - sailing - landed - cancelled - name: session in: cookie description: An optional session, for a personalised order. required: false schema: types: - string - name: session in: query description: | The same session, for callers that cannot set the cookie — a page cannot, because `Cookie` is a header the browser refuses to let a script write. Deliberately the same *name* in a second location: OpenAPI identifies a parameter by the pair `(name, in)`, so these are two parameters, and a reference that keyed its try-it form on the name alone would send one box's answer to both. required: false schema: types: - string responses: - status: "200" description: A page of consignments. headers: - name: X-Request-Id required: true schema: types: - string format: uuid content: - type: application/json schema: types: - object properties: - name: items required: true schema: types: - array items: 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 - name: next required: false schema: types: - string - "null" description: The cursor for the following page, if any. - type: text/csv schema: types: - string description: The same page, one consignment per line. examples: - name: default value: | id,reference,status 6f1c…,HB-1042,loading links: - name: NextPage operationId: listConsignments description: The same call again, with `cursor` set from `next`. - 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 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" - status: default 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" 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 --- Returns a page of consignments, newest first. Paging is by `cursor`; the value comes from the previous response's `next` field and is opaque. :::