> ## Documentation Index
> Fetch the complete documentation index at: https://docs.driftless.icu/llms.txt
> Use this file to discover all available pages before exploring further.

# Collections, Records y Entities

> Endpoints REST para el sustrato operacional: collections configuradas, records tipados y entities cross-collection.

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. Ver [Collections](/es/concepts/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`)   |
| `GET`   | `/workspaces/:slug/collections/doctor`      | member                | Audita collections (`?full`)    |
| `GET`   | `/workspaces/:slug/collections/:id`         | member                | Detalle de la collection        |
| `GET`   | `/workspaces/:slug/collections/:id/context` | member                | Resuelve el criterion Knowledge |
| `PATCH` | `/workspaces/:slug/collections/:id`         | member (`work:write`) | Actualiza una collection        |

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`, `status` (`active` o `archived`), `record_schema`, `views`, `criterion_rel_slugs`, `distill_policy`.

## Records

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

| Método   | Ruta                    | Perm                  | Propósito                                 |
| -------- | ----------------------- | --------------------- | ----------------------------------------- |
| `POST`   | `.../records`           | member (`work:write`) | Agrega un record                          |
| `GET`    | `.../records`           | member                | Lista records (paginado por cursor)       |
| `GET`    | `.../retrieve`          | member                | Records más criterion en una sola llamada |
| `GET`    | `.../records/:recordId` | member                | Detalle del record                        |
| `PATCH`  | `.../records/:recordId` | member (`work:write`) | Actualiza un record                       |
| `DELETE` | `.../records/:recordId` | member (`work:write`) | Elimina un record                         |

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. List y retrieve aceptan `status`, `entity_id`, `drifted`, `updated_after`, `view`, `fields`, `limit` y `cursor`.

## 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)`.

```bash theme={"theme":"github-light"}
curl -X POST https://api.driftless.icu/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

Records y retrieve paginan por keyset (`limit` más `cursor`, devolviendo `nextCursor`). Collections y entities listan 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`. Ver [errores](/es/api/errors) para el sobre.

## Relacionado

* [Collections](/es/concepts/collections) - arquetipos, tipos de campo y la costura del criterion.
* [CLI: Collections, Records y Entities](/es/cli/collections) - la superficie de línea de comandos.