> ## Documentation Index > Fetch the complete documentation index at: https://docs.brew.new/llms.txt > Use this file to discover all available pages before exploring further. # Data Model > The entities behind Brew's Public API v1, how they link, and what every identifier looks like, for builders joining sends, runs, and events. Every v1 resource hangs off an organization or one of its brands, and every row that one resource writes about another carries that other resource's id. This page is the map: which entities exist, which id each one answers to, and how a fire, a run, a send, and its events join up. Per-endpoint request and response shapes live in the generated OpenAPI reference. ## The Entity Map ```mermaid theme={null} erDiagram Organization ||--o{ Brand : owns Organization ||--o{ ApiKey : mints Organization ||--o{ Template : shares Brand ||--o{ Domain : sends_from Brand ||--o{ Contact : holds Brand ||--o{ Field : defines Brand ||--o{ Audience : segments Brand ||--o{ Email : designs Brand ||--o{ Trigger : listens Brand ||--o{ Automation : runs Brand ||--o{ Send : delivers Brand ||--o{ Integration : connects Brand ||--o{ Chat : records Contact }o--o{ Field : customFields Audience ||--o{ AudienceRun : launches Email ||--o{ EmailVersion : versions Email }o--o| EmailGroup : grouped_in Trigger ||--o| PayloadContract : declares Trigger ||--o{ TriggerInstance : fires TriggerInstance ||--o{ AutomationRun : starts Automation ||--o{ AutomationVersion : versions Automation ||--o{ AutomationRun : executes AutomationVersion }o--o{ EmailVersion : sendEmail_nodes AutomationVersion }o--o{ Domain : sends_from Send }o--|| Email : of Send }o--o| Domain : via Send }o--o| Audience : targets Send ||--o{ SendEvent : produces AutomationRun ||--o{ Send : delivers AutomationRun ||--o{ SendEvent : produces SendEvent }o--o| Automation : attributed_to Organization { string usage "GET /v1/usage" } Brand { string brandId } Send { string sendId string kind "campaign | automation" string automationRunId "automation rows: the run that delivered it" string triggerInstanceId "automation rows: the fire behind the run" } Contact { string email string consent "source, capturedAt, policyVersion?, evidence?" } AutomationRun { string automationRunId string automationVersionId "the version it executed; a valid publish pin" string definitionHash "sha256 graph fingerprint" string triggerInstanceId } TriggerInstance { string triggerInstanceId "tin_" } ``` Two entities are organization-wide: templates (a shared design, addressed by `emailId`) and usage. Everything else belongs to one brand. A brand-scoped API key names its brand implicitly; an organization-scoped key names it per call with `X-Brand-Id`. See [Organization and brand scope](/api-reference/api/organization-and-brand-scope). ## What Each Entity Holds * **Brand** (`brandId`): the tenant every other row belongs to. It holds domains, contacts, audiences, designs, triggers, automations, and sends. * **Domain** (`domainId`): a verified sending domain. A send and every `sendEmail` node name the domain they deliver from. * **Contact** (`email`): one recipient with its core columns, `customFields` keyed by field name, and an optional `consent` record (`source`, `capturedAt`, `policyVersion`, `evidence`). * **Field** (`fieldName`): the definition behind a custom field, typed once per brand. * **Audience** (`audienceId`, or the literal `all` on a send for every subscribed contact): a saved filter over contacts. Launching a manual-audience automation against one produces an **audience run** (`audienceRunId`). * **Email** (`emailId`): a design and its versions (`emailVersionId`), filed under a group (`groupId`, or `ungrouped`). * **Trigger** (`triggerEventId`): a named event your systems fire. Its payload contract (`contractHash`, `version`, `enforcement`) validates each fire, and each fire is recorded as a **trigger instance** (`triggerInstanceId`) that lists the runs it started. * **Automation** (`automationId`): the graph, versioned (`automationVersionId`; `liveAutomationVersionId` is the version that runs). Each `sendEmail` node (`nodeId`) pins an `emailId`, an `emailVersionId`, and a `domainId`. * **Automation run** (`automationRunId`): one execution of one automation for one recipient. It carries the version it ran, its `definitionHash`, the `triggerInstanceId` that started it, and per-node `logs`. * **Send** (`sendId`): the unit of delivery. `kind: campaign` rows carry `emailId`, `emailVersionId`, `domainId`, and the audience or inline recipients. `kind: automation` rows add `automationId`, `nodeId`, and `automationRunId`, plus `triggerInstanceId` when a fire started the run or `audienceRunId` when a manual-audience launch did. * **Event**: one delivery or engagement event, stamped with the send, design, automation, node, run, fire, and audience run it belongs to. ## Identifiers | Identifier | Shape | Notes | | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | emailId, emailVersionId | opaque, 21 chars (older designs: 36-char UUID) | The design and one persisted version of it. Returned by every generate, import, edit and restore. | | automationId, automationVersionId | opaque, 21 chars | Stable across versions; `liveAutomationVersionId` is the version publish serves. | | automationRunId | opaque, 32 lowercase alphanumerics | One per run of one automation for one recipient. | | sendId | campaign: opaque 21 chars; automation per-recipient: `as_` prefix; audience-run node: `arn_` prefix | The analytics join key. `kind` on the row says which. | | audienceRunId | `arun_` prefix | One manual-audience launch of an automation. | | triggerInstanceId | `tin_` prefix, 4 to 64 chars | One inbound fire; `GET /v1/automations/trigger-instances?triggerInstanceId=` lists the runs it started. | | triggerEventId | caller-supplied, up to 256 chars (a 21-char opaque id when omitted); integration triggers are composite `provider:...` | URL-encode composite ids in paths. | | groupId | `grp_` prefix, or the literal `ungrouped` | Email folders. | | brandId, domainId, audienceId, keyId | opaque, 32 lowercase alphanumerics | `audienceId` also accepts the literal `all` on `POST /v1/sends` (every contact in the brand). | | chatId | opaque, 21 chars | A Brew chat, for `GET /v1/chats/{chatId}`. | | email, fieldName | caller-defined | Contacts are keyed by address and custom fields by name; URL-encode in paths (`jane%40example.com`). | | Idempotency-Key | caller-defined, up to 100 chars | Namespaced per organization server-side; 24-hour window. | Treat every identifier as opaque. Prefixes such as `as_`, `arn_`, `arun_`, `tin_`, and `grp_` are stable, but they are not a contract to parse: the `kind` field on a send row says what kind of send it is. ## From a Fire to an Inbox The join keys above let you follow one event end to end: 1. `POST /v1/automations/triggers/{triggerEventId}/fire` answers with a `triggerInstanceId` and the `automationRunIds` it started. 2. `GET /v1/automations/trigger-instances/{triggerInstanceId}` shows the fire's `state` and the same run ids; `GET /v1/automations/runs/{automationRunId}?include=logs` shows one run node by node. 3. `GET /v1/sends?automationRunId={automationRunId}` lists that run's per-recipient sends (`kind: automation`), each with its `nodeId` and `triggerInstanceId`. 4. `GET /v1/sends/{sendId}?include=events` reads one send with its recipient events, and `GET /v1/analytics/events?automationRunId={automationRunId}` reads every event the run produced. For a one-off campaign the chain is shorter: `POST /v1/sends` returns the `sendId`, `GET /v1/sends?emailId={emailId}` lists the sends of one design, and the same `include=events` read applies. ## See Also * [Pagination](/api-reference/api/pagination) for the list envelope every collection shares. * [Errors](/api-reference/api/errors) for the `*_NOT_FOUND` code each identifier answers with. * [Migrate to the new v1 surface](/api-reference/api/v1-migration) if you knew the pre-cleanup spellings. ## Need Help? Our team is ready to support you at every step of your journey with Brew. Choose the option that works best for you: Type in the "Ask any question" search bar at the top left to instantly find relevant documentation pages. Click "Open in ChatGPT" at the top right of any page to explore it further with ChatGPT or Claude. Book time with our founders for personalized guidance on strategy, best practices, or complex implementation questions. Need immediate assistance? Reach us at **+1-(332)-203-2145** for urgent issues or time-sensitive questions. Our preferred support channel. You'll receive an invite after signup for direct founder support and fast responses. Contact us at **[support@brew.new](mailto:support@brew.new)** for detailed inquiries or if you prefer not to use Slack.