Skip to main content
GET
Error

Authorizations

Authorization
string
header
required

The control surface credential. Send Authorization: Bearer <token>.

Two kinds of token are accepted and they are told apart by shape, not by a separate header. A token beginning pbk_ is an org scoped API key, whose public half and secret half are generated together and of which only a hash of the secret is ever stored; anything else is treated as an OAuth 2.1 access token and verified against the authorization server's keys.

Both resolve to the same context: an org, a principal and a set of scopes. Nothing downstream branches on which channel you used, with one deliberate exception, key management, which requires a signed-in person so that a key can never mint another key.

Scopes are enforced when MCP tools are REGISTERED rather than when they are called, so a tool your credential cannot use is absent from tools/list rather than refused mid gesture.

Path Parameters

refreshId
string
required
Pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$
Example:

"app_01"

Query Parameters

cursor
string

Opaque org/principal/filter/sort/snapshot-bound cursor. Do not combine with changed filters. 409 cursor_expired requires restart; no hidden mutation.

limit
integer
default:50

Bounded by runtime policy.maxPageSize.

Required range: 1 <= x <= 100

Response

Successful response.

items
object[]
required
nextCursor
string | null
required
snapshotId
string
required
snapshotExpiresAt
string<date-time>
required
Example:

"2026-09-30T18:00:00Z"