GET /v1/sessions, which are what a
restarted process — or a coordinator with several agents working on one thing —
asks first.
Parameters
order is absent on four collections — agents, webhooks, model connections and
environment profiles — because they publish no timestamp to sort by. They take
limit and after.
has_more is decided by looking one row further rather than by counting,
because these collections are written to while they are read. Page with
?after=<last_id> until has_more is false.
A cursor that cannot be placed
A cursor the collection cannot place answers with an empty page. If the row was deleted, or the cursor never came from us, you getdata: [] and
has_more: false rather than the first page again — so a paging loop ends
instead of quietly repeating itself. It is not an error, because a cursor
naming another organization’s row must be indistinguishable from one naming
nothing.
Filtering sessions
GET /v1/sessions takes five filters on top of those, each one answering a
different question about the collection a list is otherwise organisation-wide:
required_actions, so a restarted worker
can find everything it owes an answer to in one call and answer without a
second one.
root is the only one of the five that names another session rather than a
value: it walks parent_session_id down from the id you pass, so passing a
leaf of the tree — not the coordinator — returns only that leaf. See
AGENTS.md §2 for how a session joins a tree in the first place.
Unknown parameters
A query parameter an endpoint does not read is refused, the same as an unknown field in a body, and for a sharper reason: the thing people invent in a query string is a filter, and an ignored filter hands back the whole collection looking exactly like a filter that matched everything. Every parameter each endpoint accepts is inGET /v1/openapi.json.
Next
- reference — every endpoint, and which of these each takes
- sessions.md — what
metadatais for, and how to set it - errors.md — the shape of the
400an out-of-rangelimitreturns