Broker & Connections

All paths are under the base URL (/api/v1) and require authentication. The broker is gated: off by default in production, with a separate external-lane rollout and per-principal grants (see Broker). Reads need broker:read; invoke needs broker:invoke or work:write; grants and criterion need broker:admin. Setup (connect/disconnect) is not here; it lives under integrations.

Availability

When the broker is disabled the whole surface returns 503. When the external lane is closed or no grant matches, an external caller’s reads return an empty result rather than an error. Internal callers (an owned API key or dashboard session) are governed by identity and scopes; a faceless OAuth caller additionally needs rollout on and a matching grant.

Discover and read

Method	Path	Perm	Purpose
`GET`	`/workspaces/:slug/broker/connections`	member (`broker:read`)	List connections
`GET`	`/workspaces/:slug/broker/operations`	member (`broker:read`)	Search operations across providers (cursor)
`GET`	`/workspaces/:slug/broker/connections/:provider/operations`	member (`broker:read`)	A provider’s operations
`GET`	`/workspaces/:slug/broker/connections/:provider/capabilities`	member (`broker:read`)	The capability directory
`GET`	`/workspaces/:slug/broker/connections/:provider/operations/:operation`	member (`broker:read`)	Inspect one operation
`GET`	`/workspaces/:slug/broker/connections/:provider/models`	member (`broker:read`)	Importable record models
`GET`	`/workspaces/:slug/broker/connections/:provider/records`	member (`broker:read`)	Records from the mirror (cursor)
`GET`	`/workspaces/:slug/broker/connections/notion/pages/:pageId/content`	member (`broker:read`)	Live bounded page content
`GET`	`/workspaces/:slug/broker/events`	member (`broker:read`)	Inbound provider events

Invoke and materialize

Method	Path	Perm	Purpose
`POST`	`/workspaces/:slug/broker/connections/:provider/invoke`	member (`broker:invoke` / `work:write`)	Execute one operation inline
`POST`	`/workspaces/:slug/broker/connections/:provider/criterion`	member (`broker:admin` / `work:write`)	Attach a criterion slug
`DELETE`	`/workspaces/:slug/broker/connections/:provider/criterion/:topic`	member (`broker:admin` / `work:write`)	Detach a criterion slug
`POST`	`/workspaces/:slug/broker/connections/:provider/index/preview`	member (`broker:admin` / `work:write`)	Dry-run index
`POST`	`/workspaces/:slug/broker/connections/:provider/index`	member (`broker:admin` / `work:write`)	Materialize connector documents
`POST`	`/workspaces/:slug/broker/connections/:provider/import`	member (`broker:invoke` / `work:write`)	Import mirror records into Collection Records
`GET`	`/workspaces/:slug/broker/connections/:provider/context`	member (`broker:read`)	The connection’s effective context (criterion resolved to trust/staleness)
`GET`	`/workspaces/:slug/broker/connections/:provider/documents/:externalId/content`	member (`broker:read`)	Provider-general bounded document content

invoke executes inline (there is no approval queue). For a write effect, pass idempotency_key for safe replay; writes are never auto-retried. index and index/preview are OAuth-mapped to broker:admin (or broad work:write): indexing curates what the whole workspace can retrieve and cite — the same class of act as attaching criterion — so it never rides broker:invoke, and the service layer still grant-gates external principals on the underlying record reads. The write preview route stays deliberately unmapped (OAuth-denied) until the governed-write contract ships. The context read returns {provider, connection, criterion, context: [{slug, title, what, trust, stale, missing?}], next_action} and is audited as a read receipt (broker.context.read) — the call an agent makes before working a connection. The generic documents/:externalId/content read supersedes the Notion-only connections/notion/pages/:pageId/content route (kept as a deprecated alias). Both accept an optional ?connection= selector — forward-compatible for multi-account; today each provider has one connection, so omit it.

curl -X POST https://api.trybrein.com/api/v1/workspaces/acme/broker/connections/notion/invoke \
  -H "x-api-key: drift_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"operation":"notion-page-content","input":{"page_id":"..."}}'

Grants

Method	Path	Perm	Purpose
`GET`	`/workspaces/:slug/broker/grants`	member (`broker:read`)	List grants
`POST`	`/workspaces/:slug/broker/grants`	owner/admin (`broker:admin` / `work:write`)	Grant `{ principal, provider, effect }`
`DELETE`	`/workspaces/:slug/broker/grants/:id`	owner/admin	Revoke a grant

Grants gate the external lane only; managing them is owner/admin.

Errors

The controller is rate limited per principal; invoke, preview, and page-content are throttled tighter, and index / import tighter still. Errors map to stable codes: RATE_LIMITED, INVALID_VALUE (fix the request), and a transient INTERNAL for upstream 5xx. See errors for the envelope.

Broker - actions, gates, and read/write semantics.
Integrations and Connections - setup and provider availability.

Get started

Connect

Concepts

Work & collaborate

Guides

Agents

MCP reference

CLI reference

API reference

Platform

Broker & Connections

Availability

Discover and read

Invoke and materialize

Grants

Errors

​Availability

​Discover and read

​Invoke and materialize

​Grants

​Errors

​Related

Availability

Discover and read

Invoke and materialize

Grants

Errors

Related