Filtering and pagination

Collection operations use only the filters and pagination style declared on their operation pages. Operade does not apply one universal list contract across every resource.

Filtering#

Agent lists can filter by keyword, archive state, and creator. Conversation lists expose filters such as Agent, Branch, source, status, date, keyword, and Analysis result. Knowledge lists can filter by folder, keyword, type, and creator. Tool lists can filter by keyword, type, and creator. Branch history and deployment operations use their own branch or version parameters.

Omit a filter when you do not want to constrain the result. Do not send an empty string as a substitute unless the operation schema allows it. Filter names, value types, and accepted enums belong to the operation page and can differ from dashboard labels.

Page-based lists#

Agents and Conversations use page-based listing. Supply the positive page number shown by the contract, preserve all active filters when advancing, and stop when a returned page no longer supplies another result page. Page-based results can shift when resources are created or changed between requests, so do not use page number as a durable synchronization cursor.

Cursor-based lists#

Version history and Deployment history use cursor-based traversal with cursor and limit. Treat a returned cursor as opaque: store and send it exactly, without decoding or editing it. A cursor_invalid response means restart the traversal without that cursor. Keep the same parent resource and filters while consuming a cursor sequence.

Lists without pagination#

Knowledge and Tool list operations currently expose filters but no pagination parameter. Callers must not invent page, cursor, or limit behavior for them. The absence of pagination is current behavior, not a promise that list size is unlimited or that the contract will never evolve.

Stable integrations#

Read the operation's query parameter table before generating a client. Deduplicate by returned resource identifier when a changing collection is traversed. For polling, avoid aggressive loops and prefer fetching only when the product workflow needs current data.

See API introduction, API errors, and Conversations for the visible filter model.