Queries, access and diagnostics

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

Query

Page through an authorized collection with supported filters and search.

func (c *Client) Query(ctx context.Context, in QueryInput) (QueryPage, error)

Parameter	Type and default	Usage
ctx	context.Context (required)	Required Go context. Cancellation bounds this local call; it does not withdraw a durable request.
in	QueryInput (required)	Typed operation input. Every field is listed 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.

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

Capabilities

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

func (c *Client) Capabilities(ctx context.Context, in CapabilityInput) (CapabilityResult, error)

Parameter	Type and default	Usage
ctx	context.Context (required)	Required Go context. Cancellation bounds this local call; it does not withdraw a durable request.
in	CapabilityInput (required)	Typed operation input. Every field is listed 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.

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

Access

Inspect effective role assignments for yourself or an authorized subject.

func (c *Client) Access(ctx context.Context, subject string) (json.RawMessage, error)

Parameter	Type and default	Usage
ctx	context.Context (required)	Required Go context. Cancellation bounds this local call; it does not withdraw a durable request.
subject	string (required)	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.

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

RequestTrace

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

func (c *Client) RequestTrace(ctx context.Context, id, cursor string) (json.RawMessage, error)

Parameter	Type and default	Usage
ctx	context.Context (required)	Required Go context. Cancellation bounds this local call; it does not withdraw a durable request.
id	string (required)	Existing stable resource ID, returned by the corresponding create/read operation.
cursor	string (required)	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 Go example. Input/output fields are in the types reference.

Workspace

Read the authenticated workspace’s identity and deployment metadata.

func (c *Client) Workspace(ctx context.Context) (json.RawMessage, error)

Parameter	Type and default	Usage
ctx	context.Context (required)	Required Go context. Cancellation bounds this local call; it does not withdraw a durable request.

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 Go example. Input/output fields are in the types reference.

Account

Read account access and runtime-applied service limits.

func (c *Client) Account(ctx context.Context) (json.RawMessage, error)

Parameter	Type and default	Usage
ctx	context.Context (required)	Required Go context. Cancellation bounds this local call; it does not withdraw a durable request.

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 Go example. Input/output fields are in the types reference.

ProviderCatalog

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

func (c *Client) ProviderCatalog(ctx context.Context) (json.RawMessage, error)

Parameter	Type and default	Usage
ctx	context.Context (required)	Required Go context. Cancellation bounds this local call; it does not withdraw a durable request.

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 Go example. Input/output fields are in the types reference.

ConnectionSetup

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

func (c *Client) ConnectionSetup(ctx context.Context, id string) (json.RawMessage, error)

Parameter	Type and default	Usage
ctx	context.Context (required)	Required Go context. Cancellation bounds this local call; it does not withdraw a durable request.
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.

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

PreviewContactPermissions

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

func (c *Client) PreviewContactPermissions(ctx context.Context, in ContactPreviewInput) (map[string]any, error)

Parameter	Type and default	Usage
ctx	context.Context (required)	Required Go context. Cancellation bounds this local call; it does not withdraw a durable request.
in	ContactPreviewInput (required)	Typed operation input. Every field is listed 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.

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

input := beepgrid.QueryInput{Collection: "messages", Filters: map[string]string{"conversation_id": sent.ConversationID}, Limit: 1}
page := must(owner.Query(ctx, input))
seen := len(page.Items)
for page.NextCursor != "" {
  input.Cursor = page.NextCursor
  page = must(owner.Query(ctx, input))
  seen += len(page.Items)
}
check(seen == 2)
check(must(owner.Capabilities(ctx, beepgrid.CapabilityInput{RequestID: blocking.ID})).Operations["cancel"])
check(decoded(must(owner.Access(ctx, "")))["roles"] != nil)
check(decoded(must(owner.RequestTrace(ctx, blocking.ID, "")))["request"] != nil)
check(decoded(must(owner.Workspace(ctx)))["deployment"] == "self_hosted")
check(decoded(must(owner.Account(ctx)))["applied"] != nil)
check(len(must(owner.ProviderCatalog(ctx))) > 0)
var connection struct {
  ID string `json:"id"`
}
if err := owner.Do(ctx, "POST", "/api/v1/connections", map[string]any{"name": "Tour webhook " + runID, "kind": "webhook", "enabled": false, "config": map[string]string{"url": "https://example.com/beepgrid"}, "secret": beepgrid.Key()}, &connection, ""); err != nil {
  panic(err)
}
check(len(must(owner.ConnectionSetup(ctx, connection.ID))) > 0)

---

Read this page as Markdown