Add list endpoint for out-of-band records

[kukgini]

Summary

The out-of-band protocol currently has no endpoint to list OOB records. Unlike DID Exchange, which shares ConnRecord with the connections API and is therefore queryable via GET /connections, OOB maintains its own separate record types (OobRecord and InvitationRecord) — an appropriate design given connectionless use cases. However, this means OOB records are not discoverable through any existing list endpoint.

Current OOB Endpoints

Method	Endpoint	Description
POST	/out-of-band/create-invitation	Create an invitation
POST	/out-of-band/receive-invitation	Receive an invitation
GET	/out-of-band/invitations?oob_id=...	Fetch a single record by oob_id
DELETE	/out-of-band/invitations/{invi_msg_id}	Delete records by invi_msg_id

Both the fetch and delete endpoints require knowing the specific record ID (oob_id or invi_msg_id). There is no way to list or query all existing OOB records.

Problem

If the oob_id or invi_msg_id is lost (e.g., due to operational errors, application restarts, or logging gaps), there is no way to:

1. Discover which OOB records exist in the wallet
2. Clean up stale or orphaned OOB records accumulated from failed or abandoned exchanges

This makes it difficult to manage garbage data that builds up over time, particularly in production environments with high invitation volume.

Comparison with Connections

The connections API provides GET /connections with rich filtering (by state, alias, protocol, etc.), making it easy to audit and clean up connection records. OOB records lack equivalent functionality.

Proposed Solution

Add a GET /out-of-band/records (or similar) endpoint that lists OobRecord entries with support for:

• Pagination — offset and limit parameters to prevent out-of-memory errors when the record count is large
• Filtering — optional query parameters such as:
  • state (initial, await-response, done, etc.)
  • role (sender, receiver)
  • connection_id

This would bring OOB record management in line with the patterns established by other protocols in ACA-Py (e.g., GET /connections supports pagination and filtering).

[swcurran]

Are you planning on implementing this @kukgini , or looking for help? Discussed at the ACA-Py Maintainers Meeting 2026-02-10, agreed on the approach.

[kukgini]

I created a PR for this: #4046
Please review. If possible, it would be great if it could be included in the next release of 1.3-lts.