Broker y Connections

Todas las rutas están bajo la base URL (/api/v1) y requieren autenticación. El broker está gated: apagado por defecto en producción, con un rollout de lane externa aparte y grants por principal (ver Broker). Las lecturas necesitan broker:read; invoke necesita broker:invoke o work:write; grants y criterion necesitan broker:admin. El setup (connect/disconnect) no está aquí; vive bajo integraciones.

Disponibilidad

Cuando el broker está deshabilitado, toda la superficie devuelve 503. Cuando la lane externa está cerrada o ningún grant coincide, las lecturas de un caller externo devuelven un resultado vacío en vez de un error. Los callers internos (una API key propia o una sesión del dashboard) se gobiernan por identidad y scopes; un caller OAuth sin rostro además necesita el rollout encendido y un grant que coincida.

Descubrir y leer

Método	Ruta	Perm	Propósito
`GET`	`/workspaces/:slug/broker/connections`	member (`broker:read`)	Lista connections
`GET`	`/workspaces/:slug/broker/operations`	member (`broker:read`)	Busca operaciones entre providers (cursor)
`GET`	`/workspaces/:slug/broker/connections/:provider/operations`	member (`broker:read`)	Operaciones de un provider
`GET`	`/workspaces/:slug/broker/connections/:provider/capabilities`	member (`broker:read`)	El capability directory
`GET`	`/workspaces/:slug/broker/connections/:provider/operations/:operation`	member (`broker:read`)	Inspecciona una operación
`GET`	`/workspaces/:slug/broker/connections/:provider/models`	member (`broker:read`)	Record models importables
`GET`	`/workspaces/:slug/broker/connections/:provider/records`	member (`broker:read`)	Records desde el mirror (cursor)
`GET`	`/workspaces/:slug/broker/connections/notion/pages/:pageId/content`	member (`broker:read`)	Contenido de página en vivo, acotado
`GET`	`/workspaces/:slug/broker/events`	member (`broker:read`)	Eventos entrantes del provider

Invocar y materializar

Método	Ruta	Perm	Propósito
`POST`	`/workspaces/:slug/broker/connections/:provider/invoke`	member (`broker:invoke` / `work:write`)	Ejecuta una operación inline
`POST`	`/workspaces/:slug/broker/connections/:provider/criterion`	member (`broker:admin` / `work:write`)	Adjunta un slug de criterion
`DELETE`	`/workspaces/:slug/broker/connections/:provider/criterion/:topic`	member (`broker:admin` / `work:write`)	Quita un slug de criterion
`POST`	`/workspaces/:slug/broker/connections/:provider/index/preview`	member (`broker:admin` / `work:write`)	Index en seco
`POST`	`/workspaces/:slug/broker/connections/:provider/index`	member (`broker:admin` / `work:write`)	Materializa connector documents
`POST`	`/workspaces/:slug/broker/connections/:provider/import`	member (`broker:invoke` / `work:write`)	Importa records del mirror a Records de Collection
`GET`	`/workspaces/:slug/broker/connections/:provider/context`	member (`broker:read`)	El contexto efectivo de la connection (criterion resuelto a trust/staleness)
`GET`	`/workspaces/:slug/broker/connections/:provider/documents/:externalId/content`	member (`broker:read`)	Contenido acotado de un documento, general para providers

invoke ejecuta inline (no hay cola de aprobación). Para un efecto de escritura, pasa idempotency_key para un replay seguro; las escrituras nunca se reintentan solas. index e index/preview están mapeados en OAuth a broker:admin (o al scope amplio work:write): indexar selecciona lo que todo el workspace puede recuperar y citar, la misma clase de acto que adjuntar criterion, así que nunca usa broker:invoke; la capa de servicio aún aplica los grants del principal externo a las lecturas de records subyacentes. La ruta de escritura preview sigue deliberadamente sin mapear (denegada para OAuth) hasta que se publique el contrato de escritura gobernada. La lectura context devuelve {provider, connection, criterion, context: [{slug, title, what, trust, stale, missing?}], next_action} y se audita como un recibo de lectura (broker.context.read): es la llamada que un agente hace antes de trabajar con una connection. La lectura genérica documents/:externalId/content reemplaza la ruta exclusiva de Notion connections/notion/pages/:pageId/content (que se conserva como alias deprecado). Ambas aceptan un selector opcional ?connection=, preparado para múltiples cuentas; hoy cada provider tiene una sola connection, así que se omite.

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

Método	Ruta	Perm	Propósito
`GET`	`/workspaces/:slug/broker/grants`	member (`broker:read`)	Lista grants
`POST`	`/workspaces/:slug/broker/grants`	owner/admin (`broker:admin` / `work:write`)	Concede `{ principal, provider, effect }`
`DELETE`	`/workspaces/:slug/broker/grants/:id`	owner/admin	Revoca un grant

Los grants gobiernan solo la lane externa; gestionarlos es owner/admin.

Errores

El controller tiene rate limit por principal; invoke, preview y page-content tienen throttle más estricto, e index / import aún más. Los errores mapean a códigos estables: RATE_LIMITED, INVALID_VALUE (corrige la petición) y un INTERNAL transitorio para 5xx del proveedor. Ver errores para el sobre.

Relacionado

Broker - acciones, gates y semántica de lectura/escritura.
Integraciones y Connections - setup y disponibilidad por provider.

Primeros pasos

Conectar

Conceptos

Trabajar y colaborar

Guías

Agentes

Referencia MCP

Referencia CLI

Referencia API

Plataforma

Broker y Connections

Disponibilidad

Descubrir y leer

Invocar y materializar

Grants

Errores

Relacionado

​Disponibilidad

​Descubrir y leer

​Invocar y materializar

​Grants

​Errores

​Relacionado

Disponibilidad

Descubrir y leer

Invocar y materializar

Grants

Errores

Relacionado