Skip to main content
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

MethodPathPermPurpose
GET/workspaces/:slug/broker/connectionsmember (broker:read)List connections
GET/workspaces/:slug/broker/operationsmember (broker:read)Search operations across providers (cursor)
GET/workspaces/:slug/broker/connections/:provider/operationsmember (broker:read)A provider’s operations
GET/workspaces/:slug/broker/connections/:provider/capabilitiesmember (broker:read)The capability directory
GET/workspaces/:slug/broker/connections/:provider/operations/:operationmember (broker:read)Inspect one operation
GET/workspaces/:slug/broker/connections/:provider/modelsmember (broker:read)Importable record models
GET/workspaces/:slug/broker/connections/:provider/recordsmember (broker:read)Records from the mirror (cursor)
GET/workspaces/:slug/broker/connections/notion/pages/:pageId/contentmember (broker:read)Live bounded page content
GET/workspaces/:slug/broker/eventsmember (broker:read)Inbound provider events

​
Invoke and materialize

MethodPathPermPurpose
POST/workspaces/:slug/broker/connections/:provider/invokemember (broker:invoke / work:write)Execute one operation inline
POST/workspaces/:slug/broker/connections/:provider/criterionmember (broker:admin / work:write)Attach a criterion slug
DELETE/workspaces/:slug/broker/connections/:provider/criterion/:topicmember (broker:admin / work:write)Detach a criterion slug
POST/workspaces/:slug/broker/connections/:provider/index/previewmember (API key / session)Dry-run index
POST/workspaces/:slug/broker/connections/:provider/indexmember (API key / session)Materialize connector documents
POST/workspaces/:slug/broker/connections/:provider/importmember (broker:invoke / work:write)Import mirror records into Collection Records
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 not mapped for OAuth, so a faceless OAuth bearer cannot call them; an owned API key or session can. 
curl -X POST https://api.driftless.icu/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

MethodPathPermPurpose
GET/workspaces/:slug/broker/grantsmember (broker:read)List grants
POST/workspaces/:slug/broker/grantsowner/admin (broker:admin / work:write)Grant { principal, provider, effect }
DELETE/workspaces/:slug/broker/grants/:idowner/adminRevoke 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.