Collections, Records y Entities

Todas las rutas están bajo la base URL (/api/v1) y requieren autenticación. Las lecturas son de miembro del workspace; las escrituras requieren el scope work:write por OAuth; purge es solo owner/admin. Las lecturas son active-only, acotadas y brief por defecto — los objetos archived solo aparecen con un opt-in explícito. Ver Collections para el modelo.

Collections

Método	Ruta	Perm	Propósito
`POST`	`/workspaces/:slug/collections`	member (`work:write`)	Crea una collection
`GET`	`/workspaces/:slug/collections`	member	Lista collections (`?status=&owner=&updated_after=&limit=&cursor=`). Por defecto `active`; bare array, o `{items, shown, has_more, nextCursor}` cuando hay un param de paging
`GET`	`/workspaces/:slug/collections/search`	member	Búsqueda por intención (`?q=&status=&include_archived=&owner=&updated_after=&limit=&cursor=`). `q` obligatorio; los `items[]` llevan `score`; active-only salvo `include_archived=true`
`GET`	`/workspaces/:slug/collections/doctor`	member	Audita collections (`?full`); solo lectura, hallazgos acotados
`GET`	`/workspaces/:slug/collections/:id`	member	Detalle de la collection (`?view=brief\|full`). Brief por defecto; `full` devuelve config + `stage_counts`
`GET`	`/workspaces/:slug/collections/:id/context`	member	Resuelve el criterion Knowledge (`{criterion, missing}`)
`GET`	`/workspaces/:slug/collections/:id/connector-mapping`	member	Lee la config del connector mapping
`PATCH`	`/workspaces/:slug/collections/:id`	member (`work:write`)	Actualiza config. Rechaza `status=archived` (`409`) — usa archive/restore
`PUT`	`/workspaces/:slug/collections/:id/connector-mapping`	member (`work:write`)	Setea el connector mapping; valida campos contra `record_schema`; nunca corre una acción del provider
`POST`	`/workspaces/:slug/collections/:id/archive`	member (`work:write`)	Retira de forma reversible una collection activa; `version += 1`; archived es inmutable
`POST`	`/workspaces/:slug/collections/:id/restore`	member (`work:write`)	Restaura una collection archived a `active`
`DELETE`	`/workspaces/:slug/collections/:id`	owner/admin	Purga una collection archived (`?dry_run=&expected_version=`). CAS, auditado, idempotente, preserva distilled Notes

Cuerpo de creación (CreateCollectionDto): name (obligatorio), archetype (obligatorio, uno de pipeline, analysis, content), record_schema, views, criterion_rel_slugs, distill_policy, owner_clerk_id. El update acepta name, record_schema, views, criterion_rel_slugs, distill_policy — un status de archived devuelve 409 y nombra la ruta de ciclo de vida que usar.

Records

Ruta base /workspaces/:slug/collections/:id.

Método	Ruta	Perm	Propósito
`POST`	`.../records`	member (`work:write`)	Agrega un record; devuelve el record (con `context_outcome` cuando el stage es terminal)
`GET`	`.../records`	member	Lista records (`?status=&entity_id=&drifted=&updated_after=&view=&limit=&cursor=`). Dual-shape: bare array (sin param nuevo), o `{records, nextCursor}`
`GET`	`.../retrieve`	member	Records más criterion en una sola llamada acotada (`?query=&fields=&status=&entity_id=&drifted=&updated_after=&view=&limit=&cursor=`); devuelve `{records, nextCursor, criterion, criterion_missing}`
`GET`	`.../records/:recordId`	member	Detalle del record
`PATCH`	`.../records/:recordId`	member (`work:write`)	Actualiza un record; devuelve `context_outcome` en una transición a terminal
`DELETE`	`.../records/:recordId`	member (`work:write`)	Elimina un record (`?dry_run=`). Idempotente; preserva distilled Notes

Cuerpo de record (CreateRecordDto / UpdateRecordDto): fields, status, field_meta, entity_id, y drifted en el update. El status de un record se valida contra los stages de la collection. entity_id es una propiedad top-level del record, nunca un campo dentro de fields (pasa "" en update para limpiar el link). Una transición a un stage terminal dispara el distill_policy y puede adjuntar un context_outcome (created · already_exists · skipped · failed) al record — best-effort, nunca bloquea la escritura.

Entities

Método	Ruta	Perm	Propósito
`POST`	`/workspaces/:slug/entities`	member (`work:write`)	Hace upsert de una entity
`GET`	`/workspaces/:slug/entities`	member	Lista entities (`?kind`)
`GET`	`/workspaces/:slug/entities/:id`	member	Detalle de la entity

Cuerpo de upsert (UpsertEntityDto): kind (obligatorio), name (obligatorio), dedup_key, attributes. El upsert es idempotente sobre (kind, dedup_key) — re-upsertar el mismo par mergea name/attributes en vez de crear un duplicado.

curl -X POST https://api.trybrein.com/api/v1/workspaces/acme/entities \
  -H "x-api-key: drift_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"kind":"company","name":"Acme","dedup_key":"acme.com"}'

Paginación y errores

list y search de collections paginan por keyset cursor (limit 1–50, default 20; cursor opaco del nextCursor previo); list es dual-shape por back-compat — bare array cuando no hay param de paging/filter, el sobre {items, nextCursor} en caso contrario. list y retrieve de records paginan por keyset (limit 1–100, default 25; keyset sobre created_at, id). La lista de entities es un array acotado (sin cursor). Un status inválido (fuera de los stages de la collection) o un archetype inválido, o un campo de cuerpo desconocido, devuelve 400 VALIDATION_FAILED. Un fields JSON malformado en retrieve se ignora silenciosamente, nunca erroriza. Ver errores para el sobre.

Ciclo de vida: archive y purge

POST .../:id/archive retira una collection activa. POST .../:id/restore reviven una collection archived a active. Ambos incrementan version y se auditan. Una collection archived es inmutable — PATCH, las escrituras de records y retrieve devuelven 409 PROTECTED_RESOURCE.
DELETE .../:id?dry_run=true previsualiza el impacto (distilled_notes_preserved cuenta las distilled Notes que sobreviven al borrado; entity_links_removed cuenta los record links rotos). DELETE .../:id?expected_version=<n> ejecuta el purge con compare-and-set; un expected_version que no coincide devuelve 409 VERSION_CONFLICT. Solo owner/admin, auditado, idempotente — un reintento tras el purge devuelve already_absent.

El safe delete de records sigue la misma forma: DELETE .../records/:recordId solo elimina de una collection no archived; ?dry_run=true previsualiza el Entity link removido y las distilled Notes preservadas (sobreviven al borrado, no se re-evalúan). El delete está gateado por membresía del workspace (no owner/admin), auditado, idempotente — un reintento tras el borrado devuelve already_absent.

Relacionado

Collections - arquetipos, tipos de campo y la costura del criterion.
CLI: Collections, Records y Entities - la superficie de línea de comandos.
MCP: Collections y operaciones - la superficie MCP.

Primeros pasos

Conectar

Conceptos

Trabajar y colaborar

Guías

Agentes

Referencia MCP

Referencia CLI

Referencia API

Plataforma

Collections, Records y Entities

Collections

Records

Entities

Paginación y errores

Ciclo de vida: archive y purge

Relacionado

​Collections

​Records

​Entities

​Paginación y errores

​Ciclo de vida: archive y purge

​Relacionado

Collections

Records

Entities

Paginación y errores

Ciclo de vida: archive y purge

Relacionado