Schemas

A promoted event field the event-aggregate composer (#413) may reference. `numeric` fields are eligible for sum/avg/min/max; every field is usable for count + where conditions.

A company/account entity in ackDB's entity store.

Aggregated entity profile - everything known about an entity in a single object. This is the primary response format for AI agent queries (L1 tier).

Complete definition of one event type within a source. Includes field schemas with descriptions, compute hints, examples, and a complete POST /ingest template. The full event contract also carries `eventScope` (`person` vs `entity`) and, for person-scope events, a `contactMapping`/`contactMappings` describing how a contact is extracted at ingest time - see `EventTypeInput`/`ContactMappingInput` for those declaration-side fields.

A per-deployment override of an Observe field's DISPLAY label (#191). Presentation only - the key, compiler whitelist, filters, sort, and ingest are untouched.

Full file metadata including extracted text and content chunk link.

A universal identity link type (#310) — resolves/matches an entity from ANY source, not just the one that declared it (like `domain`, but tenant-defined). Match-only by default; an entity-scoped type with `canMint: true` (#451) is a secondary anchor that can also CREATE an entity at ingest, for companies that have no domain. `domain` itself is built-in (`builtIn: true`) and always mints.

A raw source payload stored in Postgres. Used for L3 evidence tier - deep evidence, citations, and debugging.

A saved Observe Segment - config only (no data snapshot). Owned + per-user shared (#284); soft-deleted via deleted_at.

One segment's placement inside a folder.

Lightweight Segment list-item (no filter/sort/columns).

Trait definition. Like Salesforce custom fields - defines what computed fields exist. AI agents discover fields by listing these at runtime.

One node in the workflow's action graph. `data[0]` is always the synthetic input node (`action_id: "input"`); subsequent elements are actions in topological execution order.

A note attached to an action instance.

Outcome of an Add Rows batch.

A lead in a campaign. `email` is the identity and dedup key — re-adding the same address updates it.

A connected mailbox in the organization, flagged with whether this campaign sends from it.

A step type that can be added to a sequence. Pass `id` as `type` in Add Node.

Outcome of a Delete All Rows call.

Response data for Get Action Field Options.

Response data for Get Source Field Options.

Paginated list of rows with their inputs and per-cell status.

Outcome of a Run Rows call.

Confirmation envelope for a deleted child sheet.

A shortcut wraps a workflow with typed input/output schemas, providing a simplified interface for running workflows programmatically. Shortcuts can be shared across an organization.

Create result envelope. `source_instance_id` is the new source's UUID — pass it to Sync / Get Source Data / Pause-Resume.

Preview result envelope. `data` is capped per source (at most 100 rows — e.g. find_job_postings returns up to 25, Slack up to 10). `metadata.total_results` is the upstream count. Per-row keys depend on the source.

Caller bootstrap payload. Identity and org membership are always present. Use List Workflows for accessible workflow metadata.

A workflow summary. Timestamps are ISO 8601 UTC; `last_run_at` is `null` until the first run.

Body for Add Action. `action_id` is the template; `after` (optional) is an `action_instance_id`; `name` (optional) overrides the template's default display name.

Body for Configure Action. Send only the fields you want to set — unset fields keep their current value.

Body for Create Workflow. Only `name` is required.

Body for Get Action Field Options. `context` carries any earlier cascading selections (e.g. `{ salesforce_object: "Account" }` for Salesforce field lookups). Resolvers without cascades accept an empty body.

Body for List Rows. All fields optional. **Filtering** (browse mode only — `filters` / `status_filters` / `created_at` cannot combine with `row_ids`; the server returns 400 if you mix them): - `filters[]` — value filters on **sheet input columns**. Each entry: `{ variable, operator, values }`. `variable` is an `{{input.<column>}}` reference token. - `status_filters[]` — per-action cell-status filters. Each entry: `{ action_instance_id, is?, is_not? }` (exactly one of `is` / `is_not`). - `created_at` — single time filter on the row's creation timestamp. `{ operator, values }`.

Lifecycle control for the source.

Body for Rename Sheet. `name` is the only field.

Body for Reorder Waterfall Providers. Lists every currently configured provider by display name, exactly once, in the desired execution order.

Body for Save Action Note. Overwrites any existing note on the action.

Per-source preview body. Shape depends on `source_id` — see the provider README under `modules/sources/` (and optionally `/docs/source-detail/{source_id}.txt`). Validated at the handler level; the schema only enforces that the body is a JSON object.

Request body for POST /contacts/{contactId}/links. Only a REGISTERED universal type is accepted (no source-declared types, no 'domain'); always stamped source:'manual'.

Per-provider API key status. The raw key is write-only and never returned.

An attribute definition (standard or custom) — a trait_definitions row shaped for the Attributes API.

Set/clear attribute values on one record. `null` clears a value (DELETEs the row). All-or-nothing: every key/value is validated before anything is written.

Bulk-assign one member to many targets (#252). Supply at least one of entityIds, domains, or contactIds. isPrimary applies to every target.

Bulk-unassign one member from many explicit targets (#252). Supply at least one of entityIds, domains, or contactIds.

Maps an external ID to a contact (#310). One contact can have many links across many sources. Contact writes only accept REGISTERED universal link types (never per-source-declared types) — see POST /schemas/identity-link-types.

Re-parent this edge to the company it really belongs to (a correction — its events move with it).

Any subset. `title` and `status` transitions emit timeline events (see the endpoint description).

Group the segment's rows by one field and reduce each group to a number. A `date` groupBy is bucketed to the day; a NULL label is a real group ("unset"), never dropped.

Recent membership changes for the pinned segment, from the S1 change log. `reenter` is reported (and filtered) as `enter`.

One number. `count` is the segment's row count and takes NO field; every other agg requires a numeric catalog FIELD KEY (numeric traits/attributes, `sc__` score columns, `evc__` per-event-type counts, `emf__` promoted event fields). Contact-aggregate (#214) and event-aggregate (#413) columns are inline column specs, not field keys, so they cannot be named here.

Escape hatch. A single read-only SELECT on the `ackdb_readonly` role (BEGIN READ ONLY + statement timeout + row/byte caps + extended wire protocol). Segment-less by design; never cached. No bind params in this build.

One dense point per bucket. `bucket` x `windowDays` must yield at most 366 points (so a `day` bucket caps at 366 days), rejected at save/preview otherwise.

A trait that ships with a source definition as a default.

Response from DELETE /data/events. A committed delete returns `deleted` (per-table counts); a dry-run returns `resolved` + `wouldDelete` with the identical report. `retained` says what was deliberately left standing; `pendingRebuild` reports, per entity+source pair, the derived content removed now and the surviving payloads queued for re-embedding.

Standard error response envelope.

Event type definition payload for declaring/editing an event type. The same shape is accepted in `SourceCreateRequest.events[]`, `POST .../events`, and `PUT .../events/{eventType}`.

Request body for POST /schemas/identity-link-types.

One person to create or update at the resolved entity, pushed via IngestRequest.contacts. Resolution is person-first: durable keys (LinkedIn, then email, then person-scoped ids) find the human globally, then the affiliation edge at this company is found or created.

Identity link in an ingest request - maps an external ID to the data.

Response from a successful ingest operation.

A known internal team member for contact classification.

A member of the tenant's internal GTM team (the full internal_users row).

The ownership link between a member and an owned company (entityId) or contact (contactId) — exactly one target is set. isPrimary marks the owner/DRI.

One first-writer-wins key conflict: a write tried to attach a key that another person already owns. It is recorded, never acted on — merging is always a human decision. A repeat of the same tuple bumps `updatedAt`; a dismissed candidate stays dismissed.

Request to merge two duplicate entities. Winner keeps its entity_id.

A condition on a fixed entity attribute (name, domain, status, timestamps, event counts, sources, last activity, or source presence).

A condition on a promoted event-metadata field's reduced scalar value (#212). `columnKey` is the synthetic field-catalog key (`emf__<source>__<field>` for the latest value, or `…__sum` for a numeric running total) and is whitelisted against the catalog; the operator must be legal for the field's valueType (same legality as a trait of that type).

Recursive Observe filter DSL. A node is either a boolean `group` (with `op` and a `children` array of further nodes) or a leaf condition (`trait`, `attribute`, `event`, or `event_field`). The root node is always a group. Empty groups compile to TRUE (match all).

Body for POST /observe/companies/query (and the /observe/contacts/query, /observe/persons/query twins). All fields optional - an empty body returns the default page of all active rows. The envelope is validated: an unknown top-level key, or a `group` node carrying an unknown key / a non-array `children`, is a 400 rather than a silently unfiltered query.

A condition on a registered entity trait. `traitKey` is whitelisted against the field catalog; the operator must be legal for the trait's valueType.

Pagination metadata included in paginated responses.

One human. The true identity is the ULID; durable keys are pointers into it (exactly as `domain` → entityId). `status` is the IDENTITY lifecycle only — a person with three ended jobs is still `active`; employment state lives on each contact edge.

Manual person create. All fields are optional — a person with no keys is a legal singleton.

Attach one durable key to a person.

Merge `loserId` into the path person (or into `winnerOverride`, which must be one of the two).

The person grain's L1 read: who they are, how we know them, where they work(ed), what just happened.

Response from a purge operation. Includes per-table counts of deleted records so callers can verify the expected data was removed.

Response from a successful resolve operation.

One scoring rule: a field reference + exactly one scoring mode. Field refs — `trait:<key>` / `attribute:<key>` (company grain; person grain: `attribute:is_internal|affiliation_count|key_count`), `identity_link:<type>`, `event:<source>.<bareType>` (aggregate), `contacts` (company grain persona count), `company:trait:<key>` (person grain, best match over ANY active affiliation), `convergence` (both grains: the count of DISTINCT `sources` with activity — or of DISTINCT fired `signals` event refs — inside `windowDays`, scored via `bands`; exactly one of sources | signals).

Create/replace body for a score definition.

A subject's score series from the sweep's change-only `score.changed` events. `changes`: one point per emission (date = full ISO timestamp). `locf`: one point per UTC day (date = YYYY-MM-DD), last observation carried forward, seeded from before the range; days before the first-ever observation are omitted (never fabricated as zero).

One change-log row: a member's transition for a segment.

One projected column: a field key, optionally frozen to the left edge, optionally a persisted pixel width. Width is per-segment layout (presentation only) - the compiler ignores it.

Request body for PUT /contacts/{contactId}/links/{type}. Declarative: this becomes the complete value set for the type; [] clears it. Adding requires a registered universal type; removing never does.

A default trait to register when declaring a source. The key MUST be `<sourceType>_*`.

Partial source edit. Every field is optional; provided fields replace the existing ones. Allowed on custom sources and shipped packs (an edit marks the row `user_modified`).

Rows verbatim from the grain's row compiler - byte-identical to GET /observe/segments/{id}/results.

The frozen `(type, value)` pairs, stored exactly as the resolvers store them (domains as ingested, emails lowercased, LinkedIn canonical) — the guard compares with plain equality.

Transfer a member's book (companies + contacts) to another member (#252). Destination by toMemberId OR toEmail. all:true moves the whole book; otherwise list entityIds/contactIds.

A non-fatal issue detected while applying a Configure Action request.

An input field to add to a workflow sheet. `reference` is server-computed from `name` and is never accepted on the request.

One value the resolver returned. `value` is what to send back via Configure Action; `label` is the human-readable text. `extras` carries integration-specific metadata when present (Salesforce field metadata, HubSpot property type, etc.).

A row the server couldn't accept. Original content is echoed back so the caller can fix and resend without position tracking.

A row on a sheet with its inputs and per-cell action status/outputs.

One value the resolver returned. `value` is what to send back in the source's create / preview payload; `label` is the human-readable text. `extras` carries integration-specific metadata when present (HubSpot property type, list color, etc.).