> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # List retained messages > Every message the Courier holds because no engine could receive it, every rail, oldest retention first. Read-only, and it never carries the message's content. A releasable message leaves by itself on the first re-check after its cause lifts — its account enters the ownership map, its owner is enabled again. An UNRECOGNIZED_TYPE of a non-financial code releases once a delivery mode is declared for its code and is not re-checked before that; one of a financial code releases on the re-check after a Courier release reads its destination. Each is re-checked at most once a minute, and within that minute while the tenant holds up to about 6,000 due retentions and its queue is empty, or about 600 while messages keep arriving (re-checks then take at most a tenth of the consumer's time; measured at 10 ms a re-check); above that, less often in proportion. Re-evaluate one to have it re-checked first: within a second while messages arrive, within 10 seconds otherwise. A Pix retention is re-checked at most once a minute. A re-evaluation has it re-checked within about 10 seconds while the engines answer; Pix tenants are re-checked one after another, and a tenant's pass that meets an engine that does not answer takes up to about 75 seconds, which every tenant after it waits out. Its release is a delivery the Courier starts with no vendor waiting: the engine's answer is stored and answers the vendor's next resend. ## OpenAPI ````yaml /pt/openapi/v3-current/jd-courier.yaml get /v1/retained openapi: 3.1.0 info: contact: email: support@lerian.studio name: Lerian Studio Support description: >- JD Courier lets several core engines share one JD channel and one ISPB on the SPB and Pix rails. Operators use this API to register the engines, keep the ownership map that decides which engine each message belongs to, activate the rails, re-run the routing of retained messages and reconcile what the channel carried. Engines use it to resolve and claim ownership and to relay a same-bank payment to the core that owns the payee account; their SPB sends and reads go through the Courier's mirror of the vendor's SOAP surface, and their Pix calls through its JDPI transit, not through this API. license: name: Lerian Studio General License title: JD Courier API version: v1.0.0 servers: [] security: - BearerAuth: [] tags: - description: >- The engine registry: the cores that consume the JD channel through the Courier, each with its participant set name: Engines - description: 'The ownership map: which engine owns each key. Every change is audited.' name: ownership - description: >- The rails: what each declares about itself, its activation and state per tenant, and its delivery modes name: channels - description: >- The engines' side of the ownership map: resolution for the on-us gate, authoritative and never advisory, the claim of the accounts, charger documents and Pix Automático recurrences the engine holds, and the declaration of a payment leg it holds. name: ownership-query - description: >- A same-bank Pix or TED between two cores: the Courier asks the map who owns the payee account, forwards the body byte for byte to that engine's address for the rail, and relays its answer. It stores, retries and posts nothing; bodies are not modelled. name: cross-core - description: >- The durable message store: redelivery on demand, without asking the vendor again name: ledger - description: >- Count reconciliation per rail: E(m) = C(m) + T(m) + R(m), the sequence gaps it saw, and the sends whose return leg never arrived name: assurance - description: >- The SPB send journal: every send, written before it leaves, and the sends whose outcome is unknown. A by-hand close records an operator's finding and never resends. name: send-journal - description: >- Per-(tenant, channel) state an operator acts on: lifting a durable channel halt name: channel-leases - description: >- Messages the Courier holds because no engine could receive them. A routing or delivery retention leaves by itself once its cause lifts, or when an operator asks for its routing decision to be run again. name: retained paths: /v1/retained: get: tags: - retained summary: List retained messages description: >- Every message the Courier holds because no engine could receive it, every rail, oldest retention first. Read-only, and it never carries the message's content. A releasable message leaves by itself on the first re-check after its cause lifts — its account enters the ownership map, its owner is enabled again. An UNRECOGNIZED_TYPE of a non-financial code releases once a delivery mode is declared for its code and is not re-checked before that; one of a financial code releases on the re-check after a Courier release reads its destination. Each is re-checked at most once a minute, and within that minute while the tenant holds up to about 6,000 due retentions and its queue is empty, or about 600 while messages keep arriving (re-checks then take at most a tenth of the consumer's time; measured at 10 ms a re-check); above that, less often in proportion. Re-evaluate one to have it re-checked first: within a second while messages arrive, within 10 seconds otherwise. A Pix retention is re-checked at most once a minute. A re-evaluation has it re-checked within about 10 seconds while the engines answer; Pix tenants are re-checked one after another, and a tenant's pass that meets an engine that does not answer takes up to about 75 seconds, which every tenant after it waits out. Its release is a delivery the Courier starts with no vendor waiting: the engine's answer is stored and answers the vendor's next resend. operationId: listRetainedMessages parameters: - description: Page, 1-based. explode: false in: query name: page schema: default: 1 description: Page, 1-based. format: int64 minimum: 1 type: integer - description: Items per page. explode: false in: query name: limit schema: default: 50 description: Items per page. format: int64 maximum: 200 minimum: 1 type: integer - description: Filter by rail. Omitted returns every rail. explode: false in: query name: channelId schema: description: Filter by rail. Omitted returns every rail. enum: - spb - pix type: string - description: Filter by retention reason. explode: false in: query name: reason schema: description: Filter by retention reason. enum: - UNRECOGNIZED_TYPE - ACCOUNT_UNASSIGNED - CLASSIFICATION_FAILED - OWNERSHIP_DECISION_UNAVAILABLE - DELIVERY_FAILED type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/RetainedMessagePage' description: OK '400': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Bad Request '401': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Unauthorized '403': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Forbidden '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Internal Server Error '503': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Service Unavailable components: schemas: RetainedMessagePage: additionalProperties: false properties: items: items: $ref: '#/components/schemas/RetainedMessage' type: - array - 'null' limit: format: int64 minimum: 1 type: integer page: format: int64 minimum: 1 type: integer required: - items - page - limit type: object Detail: additionalProperties: true properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object RetainedMessage: additionalProperties: false properties: channelId: enum: - spb - pix type: string messageId: format: uuid type: string receivedAt: format: date-time type: string reevaluatedAt: description: >- The last time the rail tried its routing decision again and the message stayed retained, whether the decision ran or failed; null when it never tried. format: date-time type: - string - 'null' reevaluation: $ref: '#/components/schemas/ReevaluationRequest' description: The last operator request to re-evaluate it; null when nobody asked. releasable: description: >- True when the cause is routing or delivery: no owner in the map, a map that could not answer, an owner disabled or unreachable, no delivery mode declared for its code. Only these are re-checked by themselves once the cause lifts, and only these can be re-evaluated; a Pix retention also clears when the vendor resends it. An UNRECOGNIZED_TYPE of a non-financial code releases once a delivery mode is declared for its code and is not re-checked before that; one of a financial code releases on the re-check after a Courier release reads its destination. type: boolean retainedAt: format: date-time type: string retentionReason: type: string unassignedKey: $ref: '#/components/schemas/UnassignedKey' description: >- ACCOUNT_UNASSIGNED only: the key the Courier looked up in the ownership map and found no owner for. Assign it (POST /v1/ownership/assignments) and the message is released on its next re-check: for ACCOUNT, send the text before ':' as branch (empty means a payment account) and the text after it as account; any other kind takes keyValue as shown. A raw key (one the map cannot hold) cannot be assigned; it needs a person. Null for every other reason, and for a Pix leg that waits on an earlier leg of its payment, which no key routes. required: - messageId - channelId - retentionReason - releasable - receivedAt - retainedAt - reevaluatedAt type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object ReevaluationRequest: additionalProperties: false properties: pending: description: >- True until the rail tries the routing decision again, on its next pass; a try that failed also answers the request. type: boolean reason: type: string requestedAt: format: date-time type: string requestedBy: type: string required: - requestedBy - requestedAt - reason - pending type: object UnassignedKey: additionalProperties: false properties: keyKind: enum: - ACCOUNT - DOCUMENT - PIX_KEY_EMAIL - PIX_KEY_PHONE - PIX_KEY_RANDOM - PAYMENT_ID - PIX_RECURRENCE_ID - PIX_RECURRENCE_ID_CHARGER type: string keyValue: description: >- Normalized, as the map holds it: ACCOUNT is :, and : for a payment account. A TED account the map cannot hold is shown raw, as the message carries it. maxLength: 256 type: string required: - keyKind - keyValue type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.