Saltar al contenido principal
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étodoRutaPermPropósito
GET/workspaces/:slug/broker/connectionsmember (broker:read)Lista connections
GET/workspaces/:slug/broker/operationsmember (broker:read)Busca operaciones entre providers (cursor)
GET/workspaces/:slug/broker/connections/:provider/operationsmember (broker:read)Operaciones de un provider
GET/workspaces/:slug/broker/connections/:provider/capabilitiesmember (broker:read)El capability directory
GET/workspaces/:slug/broker/connections/:provider/operations/:operationmember (broker:read)Inspecciona una operación
GET/workspaces/:slug/broker/connections/:provider/modelsmember (broker:read)Record models importables
GET/workspaces/:slug/broker/connections/:provider/recordsmember (broker:read)Records desde el mirror (cursor)
GET/workspaces/:slug/broker/connections/notion/pages/:pageId/contentmember (broker:read)Contenido de página en vivo, acotado
GET/workspaces/:slug/broker/eventsmember (broker:read)Eventos entrantes del provider

​
Invocar y materializar

MétodoRutaPermPropósito
POST/workspaces/:slug/broker/connections/:provider/invokemember (broker:invoke / work:write)Ejecuta una operación inline
POST/workspaces/:slug/broker/connections/:provider/criterionmember (broker:admin / work:write)Adjunta un slug de criterion
DELETE/workspaces/:slug/broker/connections/:provider/criterion/:topicmember (broker:admin / work:write)Quita un slug de criterion
POST/workspaces/:slug/broker/connections/:provider/index/previewmember (API key / sesión)Index en seco
POST/workspaces/:slug/broker/connections/:provider/indexmember (API key / sesión)Materializa connector documents
POST/workspaces/:slug/broker/connections/:provider/importmember (broker:invoke / work:write)Importa records del mirror a Records de Collection
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 no están mapeados para OAuth, así que un bearer OAuth sin rostro no puede llamarlos; una API key propia o una sesión sí. 
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

MétodoRutaPermPropósito
GET/workspaces/:slug/broker/grantsmember (broker:read)Lista grants
POST/workspaces/:slug/broker/grantsowner/admin (broker:admin / work:write)Concede { principal, provider, effect }
DELETE/workspaces/:slug/broker/grants/:idowner/adminRevoca 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