Queries, access and diagnostics

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

query

Page through an authorized collection with supported filters and search.

query<T = unknown>(input: QueryInput): Promise<QueryPage<T>>

Parameter	Type and default	Usage
input	QueryInput (required)	Typed operation input. See its declaration in the language types reference.

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.

Declared return type: Promise<QueryPage<T>>.

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

capabilities

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

capabilities(input?: { target?: { kind: string; id: string; }; request_id?: string; connection_id?: string; descriptor?: Action; }): Promise<CapabilityResult>

Parameter	Type and default	Usage
input	{target?:{kind:string;id:string};request_id?:string;connection_id?:string;descriptor?:Action} (default {})	Typed operation input. See its declaration in the language types reference.

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.

Declared return type: Promise<CapabilityResult>.

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

access

Inspect effective role assignments for yourself or an authorized subject.

access(subject?: string): Promise<unknown>

Parameter	Type and default	Usage
subject	string (default “”)	Optional authorized 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.

Declared return type: Promise<unknown>.

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

requestTrace

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

requestTrace(id: string, cursor?: string): Promise<unknown>

Parameter	Type and default	Usage
id	string (required)	Existing stable resource ID, returned by the corresponding create/read operation.
cursor	string (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.

Declared return type: Promise<unknown>.

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

workspace

Read the authenticated workspace’s identity and deployment metadata.

workspace(): Promise<unknown>

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.

Declared return type: Promise<unknown>.

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

account

Read account access and runtime-applied service limits.

account(): Promise<unknown>

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.

Declared return type: Promise<unknown>.

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

providerCatalog

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

providerCatalog(): Promise<unknown[]>

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.

Declared return type: Promise<unknown[]>.

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

connectionSetup

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

connectionSetup(id: string): Promise<unknown>

Parameter	Type and default	Usage
id	string (required)	Existing stable resource ID, returned by the corresponding create/read operation.

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.

Declared return type: Promise<unknown>.

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

previewContactPermissions

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

previewContactPermissions(input: ContactPreviewInput): Promise<unknown>

Parameter	Type and default	Usage
input	ContactPreviewInput (required)	Typed operation input. See its declaration in the language types reference.

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.

Declared return type: Promise<unknown>.

Working TypeScript 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.

const input = { collection: 'messages', filters: { conversation_id: sent.conversation_id }, limit: 1 };
let page = await owner.query<Message>(input), seen = [...page.items];
while (page.next_cursor) {
  page = await owner.query<Message>({ ...input, cursor: page.next_cursor });
  seen.push(...page.items);
}
assert.equal(seen.length, 2);
assert.ok((await owner.capabilities({ request_id: blocking.id })).operations.cancel);
assert.ok('roles' in readObject(await owner.access()));
assert.equal(readObject(readObject(await owner.requestTrace(blocking.id)).request).id, blocking.id);
assert.equal(readObject(await owner.workspace()).deployment, 'self_hosted');
assert.ok(readObject(await owner.account()).applied);
assert.ok((await owner.providerCatalog()).length);
const connection = await owner.call<{id:string}>('POST', '/api/v1/connections', {
  name: 'Tour webhook ' + runId, kind: 'webhook', enabled: false,
  config: { url: 'https://example.com/beepgrid' }, secret: crypto.randomUUID() });
assert.ok(await owner.connectionSetup(connection.id));

---

Read this page as Markdown