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

# Eventos de Brein

> El libro de lo que pasa en tu espacio: qué emite un evento, su forma y cómo leerlo.

Todo cambio que importa en tu espacio queda anotado como un evento: llegó algo, nació un Contacto, una Oportunidad se ganó. El evento se escribe **en la misma transacción que el cambio**: si no se anota, el cambio tampoco ocurre. Con eso una integración o un agente puede seguir lo que pasa sin perderse nada.

Lo puedes **leer** cuando quieras ([abajo](#leer-el-libro)), **recibirlo** en tu servidor con un [Destino](/es/api/destinations), o **suscribirte** desde un agente con [MCP Events](/es/mcp/events).

## Qué emite un evento

Emite un cambio durable en un objeto: nace, cambia de estado, se liga a otro, se llenan sus campos, o termina de procesarse algo que llegó.

No emiten leer, buscar, cotizar ni proponer (el evento es lo que se hizo, no la propuesta), las comodidades de pantalla ni los reintentos que no cambiaron nada.

## La forma

Cada evento es un [CloudEvent 1.0](https://cloudevents.io):

```json theme={"theme":"github-light"}
{
  "specversion": "1.0",
  "id": "4d6f0c2e-6a1b-5f7e-9c3d-2b8a7e1f0a55",
  "source": "https://api.trybrein.com/workspaces/9a0e…",
  "type": "opportunity.moved",
  "subject": "opportunity/7b2c…",
  "time": "2026-10-15T18:04:11.000Z",
  "datacontenttype": "application/json",
  "dataschema": "https://trybrein.com/schemas/events/opportunity.moved/v0",
  "data": { "pipeline": "c1d9…", "from": "Propuesta", "to": "Ganada", "outcome": "won" },
  "workspace": "9a0e…",
  "actorkind": "human",
  "actor": "user_2f…",
  "via": "app",
  "causationid": "e81a…",
  "correlationid": "0b44…"
}
```

| Campo | Qué es |
| - | - |
| `id` | Único. Si recibes el mismo `id` dos veces, es el mismo evento. |
| `type` | `objeto.verbo` en inglés. Ver el [catálogo](#catálogo). |
| `subject` | `objeto/id` del objeto que cambió. |
| `time` | Cuándo pasó. |
| `dataschema` | El JSON Schema público de ese tipo. |
| `workspace` | Tu espacio. |
| `actorkind` | `human`, `agent` o `system`. |
| `actor` | Quién: la persona, el agente o la Fuente. Puede faltar. |
| `via` | Por dónde: `app`, `mcp`, `api`, `door` o `routine`. |
| `causationid` | El evento que causó este. Puede faltar en el primero de una cadena. Un agente que escribe de vuelta tras una entrega lo fija con el encabezado `X-Brein-Cause` (ver [Destinos](/es/api/destinations#un-agente-que-responde-no-se-avisa-a-sí-mismo)). |
| `correlationid` | El primer evento de la cadena. Con él sigues una venta hasta lo que la originó. |
| `runid` | La corrida de un agente, si la hubo. |

`data` lleva referencias (ids) y qué cambió (nombres de campos, etapa anterior y nueva), **nunca correo ni teléfono**, y pesa hasta 20 KiB. Quien tiene permiso lee el dato completo por la API o el MCP.

## Catálogo

| `type` | Cuándo | `data` |
| - | - | - |
| `arrival.pending_decision` | La identidad es ambigua; espera a una persona. | `candidates` (número) |
| `arrival.failed` | Se agotaron los intentos. | `code`, `attempts` |
| `sequence.replied` | Un Contacto respondió a un envío de una Secuencia. | `sequence`, `contact`, `send`; opcional `opportunity` |
| `contact.created` | Nació un Contacto. | `origin`; opcional `company` |
| `contact.updated` | Cambió su correo, teléfono, LinkedIn, etapa de vida o responsable. Cualquier otro cambio no emite nada. | `fields` (nombres, nunca valores); opcional `previous` (la `lifecycle_stage` y el `owner` anteriores) |
| `company.created` | Nació una Empresa. | `domain` |
| `opportunity.created` | Nació una Oportunidad. | `pipeline`, `stage`; opcionales `company`, `contacts` |
| `opportunity.moved` | Cambió de etapa. | `pipeline`, `from`, `to`, `outcome` (`won`, `lost` o `null`) |

El recorrido de una Llegada (recibida, decidida, aceptada, rechazada, apartada, reprocesada) no es un evento: se lee con `arrival_read`. El esquema exacto de cada uno, sobre incluido, está en `https://trybrein.com/schemas/events/<type>/v0`. Los ids son texto; un campo que no está en el esquema no se acepta.

## Leer el libro

```bash theme={"theme":"github-light"}
curl "https://api.trybrein.com/api/v1/workspaces/<slug>/events?limit=50" \
  -H "X-API-Key: $BREIN_API_KEY"
```

```json theme={"theme":"github-light"}
{ "data": [ { "specversion": "1.0", "id": "…", "type": "contact.created" } ], "next_cursor": "MTIzOjQ1", "has_more": true }
```

| Parámetro | Qué hace |
| - | - |
| `after` | El `next_cursor` de la página anterior. Sin él, empieza desde el principio. |
| `types` | Tipos separados por coma: `opportunity.moved,contact.updated`. |
| `subject` | Un objeto exacto: `opportunity/<id>`. |
| `limit` | De 1 a 100. Por omisión, 50. |

Para mantenerte al día, guarda `next_cursor` y vuelve a pedir con `after`. Cuando no hay nada nuevo, la respuesta trae `data` vacío y el mismo cursor: sigue con él. **El cursor no se salta ningún evento**: un evento solo aparece cuando su transacción y todas las anteriores ya terminaron, así que lo que llegue tarde siempre queda después de tu cursor.

Un evento por id: `GET …/workspaces/<slug>/events/<id>`.

| Error | Cuándo |
| - | - |
| `400` `invalid_cursor` | El cursor no es uno que Brein haya dado. |
| `400` `unknown_event_type` | Un tipo de `types` no está en el catálogo. |
| `404` `event_not_found` | Ese evento no existe en tu espacio. |

Cualquier miembro del espacio puede leer su libro. Una llave de API o una app conectada lo lee con el permiso de lectura.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.