Queries, access and diagnostics

Use this reference with the complete developer tour and Python types. The example at the end runs after the tour setup.

query

Page through an authorized collection with supported filters and search.

query(self, collection: str, **options: Any)

Parameter	Type and default	Usage
collection	str (required)	One of the documented query collections.
**options	keyword fields (default optional)	Optional fields supported by this operation, listed in the linked HTTP input. Unknown fields are not a supported extension mechanism.

Returns: QueryPage: items, next_cursor when more scanning remains, order.

Permissions, lifecycle and errors: Default limit 50, range 1 to 200. Cursor expires after 24 hours and is tied to actor, scope and query. Continue even if items is empty when next_cursor is present.

Working Python example. Input/output fields are in the types reference.

capabilities

Check which operations are available for a target, request, connection or descriptor.

capabilities(self, **options: Any)

Parameter	Type and default	Usage
**options	keyword fields (default optional)	Optional fields supported by this operation, listed in the linked HTTP input. Unknown fields are not a supported extension mechanism.

Returns: observed_at, operations map, request_version and allowed outcomes where applicable.

Permissions, lifecycle and errors: This is a current snapshot, not a reservation or permission grant. The actual mutation checks authorization and version again.

Working Python example. Input/output fields are in the types reference.

access

Inspect effective role assignments for yourself or an authorized subject.

access(self, subject_id: str='')

Parameter	Type and default	Usage
subject_id	str (default ‘’)	Optional access subject ID. Empty means the current caller.

Returns: Authorized access projection including roles and assignment information.

Permissions, lifecycle and errors: Other subjects require management rights. Directory groups, policy roles and chat membership have distinct effects; do not substitute one for another.

Working Python example. Input/output fields are in the types reference.

request_trace

Inspect a request’s current delivery evidence and execution reports.

request_trace(self, request_id: str, cursor: str='')

Parameter	Type and default	Usage
request_id	str (required)	Canonical durable request ID. This is not a worker delivery ID.
cursor	str (default ‘’)	Opaque continuation token, scoped to the same actor, workspace and query; expires after 24 hours.

Returns: Request trace projection; delivery evidence may include a next cursor.

Permissions, lifecycle and errors: Supply delivery cursor to continue paging. Queued, provider-accepted, replied and executed are different facts. Visibility is projected for the caller.

Working Python example. Input/output fields are in the types reference.

workspace

Read the authenticated workspace’s identity and deployment metadata.

workspace(self)

Parameter	Type and default	Usage

Returns: JSON with scope, company, environment, deployment and schema metadata.

Permissions, lifecycle and errors: This endpoint is available to headless OSS clients too; it is not a browser-only feature.

Working Python example. Input/output fields are in the types reference.

account

Read account access and runtime-applied service limits.

account(self)

Parameter	Type and default	Usage

Returns: JSON account projection including applied state.

Permissions, lifecycle and errors: Person-only with account view authority, or operator. Self-hosted account state differs from managed billing and does not require a paid offering.

Working Python example. Input/output fields are in the types reference.

provider_catalog

Read the providers actually supported by this engine and their setup fields.

provider_catalog(self)

Parameter	Type and default	Usage

Returns: Array of provider capabilities, field definitions and setup modes.

Permissions, lifecycle and errors: A catalog entry describes supported functionality, not a configured or live-qualified connection. Generic webhooks are not native adapters.

Working Python example. Input/output fields are in the types reference.

connection_setup

Obtain setup instructions and safe callback/manifest information for one connection.

connection_setup(self, connection_id: str)

Parameter	Type and default	Usage
connection_id	str (required)	Configured channel connection ID.

Returns: ProviderSetup with supported steps and safe setup values.

Permissions, lifecycle and errors: Requires current connection authority. Credentials are not returned as setup text. Provider installation, account linking and contact permissions remain separate.

Working Python example. Input/output fields are in the types reference.

preview_contact_permissions

Inspect effective contact access or preview a versioned draft without saving.

preview_contact_permissions(self, subject: dict[str, str], *, rules: list[dict[str, str]] | None=None, version: int=0, targets: list[dict[str, str]] | None=None)

Parameter	Type and default	Usage
subject	dict[str, str] (required)	Optional authorized access subject ID. Empty means the current caller.
rules	list[dict[str, str]] | None (default None)	Directional permission rules granted by this policy role.
version	int (default 0)	Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts.
targets	list[dict[str, str]] | None (default None)	Explicit targets for a private batch or shared chat. These have different audience semantics.

Returns: Current dedicated policy, effective contact actions and sources, warnings and can_save.

Permissions, lifecycle and errors: Omit rules to observe; use an empty list to preview defaults. Reload on conflict. A preview grants no authority.

Working Python example. Input/output fields are in the types reference.

Example

Run this region after the shared setup. Assertions check the returned data; the full tour is a runnable program.

page = owner.query('messages', filters={'conversation_id': sent['conversation_id']}, limit=1)
seen = list(page['items'])
while page.get('next_cursor'):
    page = owner.query('messages', filters={'conversation_id': sent['conversation_id']}, limit=1, cursor=page['next_cursor'])
    seen.extend(page['items'])
assert len(seen) == 2
assert owner.capabilities(request_id=blocking['id'])['operations']['cancel']
assert 'roles' in owner.access()
assert owner.request_trace(blocking['id'])['request']['id'] == blocking['id']
assert owner.workspace()['deployment'] == 'self_hosted'
assert 'applied' in owner.account()
assert owner.provider_catalog()
connection = owner.call('POST', '/api/v1/connections', {
    'name': 'Tour webhook ' + run_id, 'kind': 'webhook', 'enabled': False,
    'config': {'url': 'https://example.com/beepgrid'}, 'secret': uuid.uuid4().hex})
assert owner.connection_setup(connection['id'])

---

Read this page as Markdown