# Data models

Every public API model, field, enum and constraint.

Fields use JSON wire names. Timestamps are RFC 3339 unless a field explicitly specifies another unit. Optional response fields may be omitted; inspect lifecycle state before using a decision. SDK types preserve language-specific names and representations.

## Target



| Field | Type | Usage |
| --- | --- | --- |
| `kind` (required) | `person \| agent \| service \| group \| instance` | Resource or operation kind. Use one of the listed values, not a display label. |
| `id` (required) | `string` | Stable identifier returned by the engine. Treat it as opaque. |

## Person



| Field | Type | Usage |
| --- | --- | --- |
| `id` (required) | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `kind` (required) | `person` | Resource or operation kind. Use one of the listed values, not a display label. |
| `external_id` | `string` | Your stable identifier for this person, agent or service within the workspace. |
| `name` (required) | `string` | Human-readable name. It is not necessarily unique. |
| `metadata` | `object` | Application-supplied JSON metadata. Do not put credentials here. |
| `disabled` | `boolean` | Whether the identity is disabled; disabled identities cannot retain normal access. |
| `created_at` | `string` | Creation timestamp in RFC 3339 UTC. format="date-time". |

## Agent



| Field | Type | Usage |
| --- | --- | --- |
| `id` (required) | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `kind` (required) | `agent` | Resource or operation kind. Use one of the listed values, not a display label. |
| `external_id` | `string` | Your stable identifier for this person, agent or service within the workspace. |
| `name` (required) | `string` | Human-readable name. It is not necessarily unique. |
| `metadata` | `object` | Application-supplied JSON metadata. Do not put credentials here. |
| `disabled` | `boolean` | Whether the identity is disabled; disabled identities cannot retain normal access. |
| `created_at` | `string` | Creation timestamp in RFC 3339 UTC. format="date-time". |
| `instances` | array of [Instance](https://beepgrid.com/docs/reference/models/#instance) | Runtime connections and their observed presence. |

## Service



| Field | Type | Usage |
| --- | --- | --- |
| `id` (required) | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `kind` (required) | `service` | Resource or operation kind. Use one of the listed values, not a display label. |
| `external_id` | `string` | Your stable identifier for this person, agent or service within the workspace. |
| `name` (required) | `string` | Human-readable name. It is not necessarily unique. |
| `metadata` | `object` | Application-supplied JSON metadata. Do not put credentials here. |
| `disabled` | `boolean` | Whether the identity is disabled; disabled identities cannot retain normal access. |
| `created_at` | `string` | Creation timestamp in RFC 3339 UTC. format="date-time". |

## Instance



| Field | Type | Usage |
| --- | --- | --- |
| `id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `agent_id` | `string` | Logical agent identity ID, shared by its runtime instances. |
| `presence` | `connected \| stale \| offline` | Observed runtime presence: connected, stale or offline. |
| `last_seen` | `string` | Most recent runtime heartbeat timestamp. |
| `capabilities` | array of `string` | Application-declared runtime capabilities. This does not grant contact permission. |
| `progress` | `object` | Explicit application-reported progress metadata; not automatic model telemetry. |

## PersonInput



| Field | Type | Usage |
| --- | --- | --- |
| `external_id` | `string` | Your stable identifier for this person, agent or service within the workspace. |
| `name` (required) | `string` | Human-readable name. It is not necessarily unique. |
| `email` | `string` | Person email address. An address alone does not prove identity or decision authority. |
| `department` | `string` | Optional person organization metadata. |
| `manager_id` | `string` | Manager identity for a person, or current shared-chat manager according to the resource. |

## Enrollment



| Field | Type | Usage |
| --- | --- | --- |
| `agent` (required) | `string` | Stable agent external ID when enrolling; an Agent object in a Session response. |
| `name` (required) | `string` | Human-readable name. It is not necessarily unique. |
| `parent_id` | `string` | Optional parent agent identity for a deliberately bounded enrollment. |
| `capabilities` | array of `string` | Application-declared runtime capabilities. This does not grant contact permission. |
| `metadata` | `object` | Application-supplied JSON metadata. Do not put credentials here. |
| `connection_name` | `string` | Human-readable label for this Agent runtime connection. |
| `never_expires` | `boolean` | Explicit non-expiring connection. Cannot be combined with renewable or expires_at. default=false. |
| `renewable` | `boolean` | Use a renewable 24-hour worker lease bounded by the supplied hard expiry. Renewal never extends the hard deadline. default=false. |
| `expires_at` | `string` | Hard deadline. Renewable workers use a 24-hour active lease up to this date. format="date-time". |

## Session



| Field | Type | Usage |
| --- | --- | --- |
| `token` | `string` | Bearer credential. Save in protected server-side storage and never expose it in browser code or logs. |
| `agent` | [Agent](https://beepgrid.com/docs/reference/models/#agent) | Stable agent external ID when enrolling; an Agent object in a Session response. |
| `instance_id` | `string` | Exact connected runtime ID, separate from the logical agent identity. |
| `expires_at` | `string \| null` | Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it. format="date-time". |

## Action



| Field | Type | Usage |
| --- | --- | --- |
| `name` (required) | `string` | Human-readable name. It is not necessarily unique. |
| `executor_id` (required) | `string` | Identity allowed to redeem the exact approved action. |
| `resource` (required) | `string` | Customer-defined resource identifier. The engine does not control the external resource. |
| `resource_version` (required) | `string` | Customer-defined version fence that the external tool must also enforce. |
| `operation_key` (required) | `string` | Stable identity of the external business operation, separate from the HTTP retry key. |
| `arguments` | `object` | JSON action arguments covered by the exact approval binding. |

## SendInput



| Field | Type | Usage |
| --- | --- | --- |
| `preview_token` | `string` | Dispatch preview token. A stale audience or route requires a fresh preview. |
| `target` | [Target](https://beepgrid.com/docs/reference/models/#target) | Target kind and stable ID. Choose a new target or an existing conversation, not both. |
| `conversation_id` | `string` | Canonical conversation ID. Use it to continue the same authorized history. |
| `body` (required) | `string` | Message or request content, bounded to 32 KiB of UTF-8 bytes. |
| `title` | `string` | Optional short label. A normal message does not require a title. |
| `mentions` | array of [Mention](https://beepgrid.com/docs/reference/models/#mention) | Addressing metadata for existing chat participants. It does not narrow audience or grant authority. maxItems=20. |
| `reuse_direct` | `boolean` | Reuse authorized exact two-principal history. Defaults to false. Does not merge shared group chats. default=false. |
| `attachment_ids` | array of `string` | IDs of staged private drafts to claim in the initial operation; at most five. maxItems=5. |

## Message



| Field | Type | Usage |
| --- | --- | --- |
| `id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `conversation_id` | `string` | Canonical conversation ID. Use it to continue the same authorized history. |
| `sender_id` | `string` | Identity that sent the message, independent of the delivering channel. |
| `instance_id` | `string` | Exact connected runtime ID, separate from the logical agent identity. |
| `body` | `string` | Message or request content, bounded to 32 KiB of UTF-8 bytes. |
| `created_at` | `string` | Creation timestamp in RFC 3339 UTC. |
| `mentions` | array of [Mention](https://beepgrid.com/docs/reference/models/#mention) | Addressing metadata for existing chat participants. It does not narrow audience or grant authority. maxItems=20. |
| `attachments` | array of [Attachment](https://beepgrid.com/docs/reference/models/#attachment) | Currently visible attachment metadata. |
| `received_by` | array of `string` | Read-only native Agent runtime acknowledgement IDs, visible only to the message sender for current Agent participants. Not evidence of model reading or business execution. Provider acceptance is excluded. |

## SendResult



| Field | Type | Usage |
| --- | --- | --- |
| `conversation_id` | `string` | Canonical conversation ID. Use it to continue the same authorized history. |
| `messages` | array of [Message](https://beepgrid.com/docs/reference/models/#message) | Canonical message records in this response, not worker delivery envelopes. |

## SendReceipt



| Field | Type | Usage |
| --- | --- | --- |
| `conversation_id` | `string` | Canonical conversation ID. Use it to continue the same authorized history. |
| `message_count` | `integer` | Number of canonical messages accepted in the compact receipt; no bodies returned. minimum=1. |

## Conversation



| Field | Type | Usage |
| --- | --- | --- |
| `id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `title` | `string` | Optional short label. A normal message does not require a title. |
| `created_by` | `string` | Identity that created the resource. |
| `created_at` | `string` | Creation timestamp in RFC 3339 UTC. |
| `participants` | array of `object` | Current participants in the authorized history projection. |
| `messages` | array of [Message](https://beepgrid.com/docs/reference/models/#message) | Canonical message records in this response, not worker delivery envelopes. |
| `last_activity_at` | `string` | Most recent conversation activity timestamp; used for recency ordering. format="date-time". |
| `last_preview` | `string` | Last visible message preview; hidden history is not exposed through previews. |
| `shared` | `boolean` | True for a shared chat, distinct from private histories created by a batch. |
| `version` | `integer` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `manager_id` | `string` | Manager identity for a person, or current shared-chat manager according to the resource. |
| `history_start` | `integer` | Earliest event boundary disclosed to this participant. |
| `past_participants` | array of `object` | Former participant metadata visible to the caller; does not restore their access. |

## AskInput



| Field | Type | Usage |
| --- | --- | --- |
| `preview_token` | `string` | Dispatch preview token. A stale audience or route requires a fresh preview. |
| `target` | [Target](https://beepgrid.com/docs/reference/models/#target) | Target kind and stable ID. Choose a new target or an existing conversation, not both. |
| `conversation_id` | `string` | Canonical conversation ID. Use it to continue the same authorized history. |
| `kind` | `question \| approval \| task` | Resource or operation kind. Use one of the listed values, not a display label. default="question". |
| `title` | `string` | Optional short label. A normal message does not require a title. |
| `body` | `string` | Message or request content, bounded to 32 KiB of UTF-8 bytes. |
| `choices` | array of `string` | Optional exact answer strings. A chosen answer must match an offered value. |
| `action` | [Action](https://beepgrid.com/docs/reference/models/#action) | Optional exact bound-action descriptor for the advanced execution contract. |
| `expires_at` | `string` | Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it. |
| `shared_key` | `string` | Explicit reusable-answer key; reuse also requires exact matching question context and current authority. |
| `mentions` | array of [Mention](https://beepgrid.com/docs/reference/models/#mention) | Addressing metadata for existing chat participants. It does not narrow audience or grant authority. maxItems=20. |
| `reuse_direct` | `boolean` | Reuse authorized exact two-principal history. Defaults to false. Does not merge shared group chats. default=false. |
| `blocking` | `boolean` | Explicit agent-to-individual-agent dependency. Ordinary open requests are not deadlocks. |
| `attachment_ids` | array of `string` | IDs of staged private drafts to claim in the initial operation; at most five. maxItems=5. |

## ResponseInput



| Field | Type | Usage |
| --- | --- | --- |
| `outcome` (required) | `answered \| approved \| denied \| completed \| failed \| rejected` | Typed final result: answered; approved/denied; or completed/failed/rejected according to request kind. |
| `answer` | `JSON value` | JSON response value; for choices, the selected exact string. |
| `version` (required) | `integer` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |

## Response



| Field | Type | Usage |
| --- | --- | --- |
| `responder_instance_id` | `string` | Runtime that supplied the final response, when applicable. |
| `outcome` | `string` | Typed final result: answered; approved/denied; or completed/failed/rejected according to request kind. |
| `answer` | `JSON value` | JSON response value; for choices, the selected exact string. |
| `version` | `integer` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `source_answer_id` | `string` | Published answer used as response provenance. |
| `source_invalidated` | `boolean` | Whether the source informational answer has since been invalidated. |
| `reuse_method` | `string` | How an existing informational answer was reused. |
| `reuse_reason` | `string` | Recorded reason or provenance for reuse. |

## Request



| Field | Type | Usage |
| --- | --- | --- |
| `requester_instance_id` | `string` | Runtime that initiated the request, when applicable. |
| `id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `requester_id` | `string` | Identity that opened the requested decision. |
| `conversation_id` | `string` | Canonical conversation ID. Use it to continue the same authorized history. |
| `kind` | `question \| approval \| task` | Resource or operation kind. Use one of the listed values, not a display label. |
| `title` | `string` | Optional short label. A normal message does not require a title. |
| `body` | `string` | Message or request content, bounded to 32 KiB of UTF-8 bytes. |
| `choices` | array of `string` | Optional exact answer strings. A chosen answer must match an offered value. |
| `action` | [Action](https://beepgrid.com/docs/reference/models/#action) | Optional exact bound-action descriptor for the advanced execution contract. |
| `state` | `open \| resolved \| cancelled \| expired \| superseded` | Lifecycle state. Read the resource-specific enum; request and execution states differ. |
| `version` | `integer` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `response` | [Response](https://beepgrid.com/docs/reference/models/#response) | Recorded final typed decision, absent while pending. |
| `resolved_by` | `string` | Identity that resolved the request. |
| `resolved_at` | `string` | Timestamp of the terminal decision. |
| `expires_at` | `string` | Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it. |
| `created_at` | `string` | Creation timestamp in RFC 3339 UTC. |
| `shared_key` | `string` | Explicit reusable-answer key; reuse also requires exact matching question context and current authority. |
| `mentions` | array of [Mention](https://beepgrid.com/docs/reference/models/#mention) | Addressing metadata for existing chat participants. It does not narrow audience or grant authority. maxItems=20. |
| `blocking` | `boolean` | Explicit agent-to-individual-agent dependency. Ordinary open requests are not deadlocks. |
| `attachments` | array of [Attachment](https://beepgrid.com/docs/reference/models/#attachment) | Currently visible attachment metadata. |

## Rule



| Field | Type | Usage |
| --- | --- | --- |
| `effect` | `allow \| deny` | Omitted means allow. Explicit contact blocks override all matching role grants, except administrator credentials. |
| `action` (required) | `view \| message \| ask \| decide \| manage \| *` | Directional permission action: view, message, ask, decide, manage or an explicitly granted wildcard. |
| `target_kind` (required) | `string` | Kind of identity or managed resource matched by the rule. |
| `target_id` (required) | `string` | Stable ID or explicitly supported wildcard of the rule's target. |
| `connection_id` | `string` | Configured channel connection ID. |
| `action_name` | `string` | Optional action-name constraint; not required for ordinary approval communication. |
| `conditions` | `object` | Optional descriptor/time/amount constraints on the rule. |

**`conditions` fields**

| Field | Type | Usage |
| --- | --- | --- |
| `conditions.resource` | `string` | Customer-defined resource identifier. The engine does not control the external resource. |
| `conditions.resource_version` | `string` | Customer-defined version fence that the external tool must also enforce. |
| `conditions.currency` | `string` | Optional currency code used to constrain a bound business action. |
| `conditions.max_amount_minor` | `integer` | Optional maximum action amount in minor currency units. minimum=0. |
| `conditions.before` | `string` | Whether the check is allowed under the current effective role grants. |

## Role



| Field | Type | Usage |
| --- | --- | --- |
| `version` | `integer` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. minimum=0. |
| `id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `name` (required) | `string` | Human-readable name. It is not necessarily unique. |
| `rules` (required) | array of [Rule](https://beepgrid.com/docs/reference/models/#rule) | Directional permission rules granted by this policy role. |

## Group



| Field | Type | Usage |
| --- | --- | --- |
| `icon` | `string` | Presentation-only role icon. Change with POST /appearance. |
| `purpose` | `contacts \| team \| agent_role` | Directory group purpose: contacts, team or agent_role. This is separate from policy roles. |
| `created_by` | `string` | Identity that created the resource. |
| `version` | `integer` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. minimum=0. |
| `member` | `boolean` | Whether the current identity belongs to this directory group. |
| `members_complete` | `boolean` | Whether the visible member list is complete rather than permission-projected. |
| `id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `name` (required) | `string` | Human-readable name. It is not necessarily unique. |
| `members` (required) | array of `string` | Directory-group or chat member identity IDs. Membership never substitutes for contact authority. |

## Binding



| Field | Type | Usage |
| --- | --- | --- |
| `role_id` (required) | `string` | Policy role ID used by a binding; not the agent_role directory-group ID. |
| `subject_kind` (required) | `principal \| group` | principal for an individual identity, or group for a directory group. |
| `subject_id` (required) | `string` | Identity or directory group receiving a policy-role assignment. |
| `remove` | `boolean` | True to remove the specified role binding rather than add it. |

## Connection



| Field | Type | Usage |
| --- | --- | --- |
| `version` | `integer` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. minimum=0. |
| `id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `name` (required) | `string` | Human-readable name. It is not necessarily unique. |
| `kind` (required) | `webhook \| slack \| email \| telegram \| discord` | Resource or operation kind. Use one of the listed values, not a display label. |
| `config` | `object` | Provider-specific configuration. Use the catalog's actual fields; secret material is separately protected. |
| `enabled` | `boolean` | Whether this configured connection is enabled. |
| `secret_configured` | `boolean` | Whether protected secret material is configured, without returning it. |
| `secret` | `string` | Write-only provider secret. Omitted from ordinary read/setup responses. |

## Destination



| Field | Type | Usage |
| --- | --- | --- |
| `version` | `integer` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. minimum=0. |
| `id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `connection_id` (required) | `string` | Configured channel connection ID. |
| `principal_id` (required) | `string` | Person, agent or service identity ID. This is an API term, not a separate product entity. |
| `address` (required) | `string` | Provider-native destination address for a linked identity. |
| `mode` | `primary \| fallback \| copy` | primary, copy or fallback routing mode. |
| `priority` | `integer` | Routing order within the applicable mode; lower numeric values are considered first. |

## Execution



| Field | Type | Usage |
| --- | --- | --- |
| `id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `request_id` | `string` | Canonical durable request ID. This is not a worker delivery ID. |
| `executor_id` | `string` | Identity allowed to redeem the exact approved action. |
| `operation_key` | `string` | Stable identity of the external business operation, separate from the HTTP retry key. |
| `action` | [Action](https://beepgrid.com/docs/reference/models/#action) | Optional exact bound-action descriptor for the advanced execution contract. |
| `state` | `authorized \| running \| succeeded \| failed \| unknown` | Lifecycle state. Read the resource-specific enum; request and execution states differ. |
| `result` | `JSON value` | Executor-reported JSON result. It is not independent proof of an external effect. |

## Delivery



| Field | Type | Usage |
| --- | --- | --- |
| `id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `recipient_id` | `string` | Intended individual identity for the delivery or event projection. |
| `operation_id` | `string` | Canonical operation correlation identifier. |
| `payload` | `object` | Canonical message/request information inside a delivery envelope. |
| `state` | `string` | Lifecycle state. Read the resource-specific enum; request and execution states differ. |
| `generation` | `integer` | Current inbox lease generation. Ack must echo this generation. |
| `attempts` | `integer` | Delivery attempt count or recorded attempt evidence, as defined by this response. |
| `last_error` | `string` | Latest safe delivery error, not a successful execution report. |
| `connection_id` | `string` | Configured channel connection ID. |
| `address` | `string` | Provider-native destination address for a linked identity. |
| `expires_at` | `string` | Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it. |

## Attachment



| Field | Type | Usage |
| --- | --- | --- |
| `id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `conversation_id` | `string` | Canonical conversation ID. Use it to continue the same authorized history. |
| `file_name` | `string` | Safe file name shown with the attachment. |
| `media_type` | `string` | Declared media type, for example application/pdf. |
| `size` | `integer` | File length in bytes, from 1 byte through 5 MiB. |
| `sha256` | `string` | SHA-256 digest of the stored file bytes. |
| `created_at` | `string` | Creation timestamp in RFC 3339 UTC. |
| `message_id` | `string` | Canonical message ID for deduplication and correlation. |
| `request_id` | `string` | Canonical durable request ID. This is not a worker delivery ID. |

## PublishAnswer



| Field | Type | Usage |
| --- | --- | --- |
| `request_id` (required) | `string` | Canonical durable request ID. This is not a worker delivery ID. |
| `key` | `string` | Stable idempotency key or shared-answer lookup key according to the endpoint. |
| `audience` (required) | array of `string` | Explicit identities allowed to reuse the published informational answer. |
| `valid_until` | `string` | Reusable-answer expiry timestamp; omission defaults to 24 hours. |

## SharedAnswer



| Field | Type | Usage |
| --- | --- | --- |
| `id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `key` | `string` | Stable idempotency key or shared-answer lookup key according to the endpoint. |
| `context_hash` | `string` | Digest of the exact shared key, title, body and choices used for reuse eligibility. |
| `question` | `string` | Original informational question title, retained with the published answer. |
| `answer` | `JSON value` | JSON response value; for choices, the selected exact string. |
| `author_id` | `string` | Identity that supplied the original informational answer. |
| `publisher_id` | `string` | Identity whose current publication authority must remain valid for reuse. |
| `audience` | array of `string` | Explicit identities allowed to reuse the published informational answer. |
| `valid_until` | `string` | Reusable-answer expiry timestamp; omission defaults to 24 hours. format="date-time". |
| `invalidated` | `boolean` | Whether this published informational answer has been explicitly invalidated. |
| `source_request` | `string` | Canonical question request from which this answer was published. |

## AssistanceSettings



| Field | Type | Usage |
| --- | --- | --- |
| `overseer` | `boolean` | Whether OSS Coordinator is enabled in this workspace. The wire name is retained for compatibility. |
| `version` | `integer` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `overseer_configured` | `boolean` | Whether the engine has a configured Coordinator provider; not the enablement switch. |

## AssistanceUpdate



| Field | Type | Usage |
| --- | --- | --- |
| `version` | `integer` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. minimum=0. |
| `overseer` | `boolean` | Whether OSS Coordinator is enabled in this workspace. The wire name is retained for compatibility. |

## FleetAgent



| Field | Type | Usage |
| --- | --- | --- |
| `agent` | [Agent](https://beepgrid.com/docs/reference/models/#agent) | Stable agent external ID when enrolling; an Agent object in a Session response. |
| `instances` | array of [Instance](https://beepgrid.com/docs/reference/models/#instance) | Runtime connections and their observed presence. |
| `fresh` | `boolean` | Whether the reported runtime evidence is current. |

## OverseerInput



| Field | Type | Usage |
| --- | --- | --- |
| `prompt` (required) | `string` | Instruction to Coordinator. The engine supplies only currently permitted specialist context. maxLength=4000. |
| `target` | [Target](https://beepgrid.com/docs/reference/models/#target) | Target kind and stable ID. Choose a new target or an existing conversation, not both. |
| `previous_plan_id` | `string` | Optional prior plan belonging to the caller for continuing permitted context. |

## OverseerDispatch



| Field | Type | Usage |
| --- | --- | --- |
| `agent_id` | `string` | Logical agent identity ID, shared by its runtime instances. |
| `conversation_id` | `string` | Canonical conversation ID. Use it to continue the same authorized history. |
| `request_id` | `string` | Canonical durable request ID. This is not a worker delivery ID. |

## OverseerPlan



| Field | Type | Usage |
| --- | --- | --- |
| `id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `prompt` | `string` | Instruction to Coordinator. The engine supplies only currently permitted specialist context. |
| `context_agent_ids` | array of `string` | Agent IDs included in the current permitted plan context. |
| `target` | [Target](https://beepgrid.com/docs/reference/models/#target) | Target kind and stable ID. Choose a new target or an existing conversation, not both. |
| `operation` | `status \| message \| question \| task` | Requested operation, with values defined by that endpoint. |
| `summary` | `string` | Plan explanation or status answer, as defined by its operation. |
| `body` | `string` | Message or request content, bounded to 32 KiB of UTF-8 bytes. |
| `sources` | array of [FleetAgent](https://beepgrid.com/docs/reference/models/#fleetagent) | Authorized specialist context used for this plan, not omniscient agent execution state. |
| `requires_confirmation` | `boolean` | Whether this saved plan needs explicit confirmation before dispatch. |
| `created_at` | `string` | Creation timestamp in RFC 3339 UTC. |
| `expires_at` | `string` | Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it. |
| `dispatches` | array of [OverseerDispatch](https://beepgrid.com/docs/reference/models/#overseerdispatch) | Attributed conversation/request IDs created by a confirmed or automatic plan. |
| `replies` | array of [Request](https://beepgrid.com/docs/reference/models/#request) | Specialist requested decisions visible to the current caller. |
| `reply_summary` | `string` | Model-generated summary of the authorized replies, including pending/missing evidence. |
| `reply_digest` | `string` | Digest identifying the reply evidence used by the summary. |
| `instructions` | array of `object` | Per-agent communication instructions, when different specialists need different tasks. |
| `automatic` | `boolean` | True when Coordinator delegated without a separate review step. |
| `summary_error` | `string` | Safe model-summary error. Existing durable instructions remain separately inspectable. |

**`instructions` fields**

Array result.

| Field | Type | Usage |
| --- | --- | --- |
| `instructions[].agent_id` (required) | `string` | Logical agent identity ID, shared by its runtime instances. |
| `instructions[].operation` (required) | `message \| question \| task` | Requested operation, with values defined by that endpoint. |
| `instructions[].body` (required) | `string` | Message or request content, bounded to 32 KiB of UTF-8 bytes. |

## Event



| Field | Type | Usage |
| --- | --- | --- |
| `sequence` | `integer` | Monotonically ordered canonical event sequence. Checkpoint after application processing. |
| `kind` | `string` | Resource or operation kind. Use one of the listed values, not a display label. |
| `actor_id` | `string` | Identity responsible for the canonical event. |
| `conversation_id` | `string` | Canonical conversation ID. Use it to continue the same authorized history. |
| `recipient_id` | `string` | Intended individual identity for the delivery or event projection. |
| `data` | `JSON value` | Event-specific JSON data. Full events contain the canonical payload; summary mode is smaller. |
| `created_at` | `string` | Creation timestamp in RFC 3339 UTC. |

## Error



| Field | Type | Usage |
| --- | --- | --- |
| `error` (required) | `object` | Error envelope with code and message; do not treat it as a successful result. |

**`error` fields**

| Field | Type | Usage |
| --- | --- | --- |
| `error.code` (required) | `string` | Stable API error code for programmatic handling. |
| `error.message` (required) | `string` | Safe human-readable API error message. |

## Mention

Stable explicit addressee. start/end are Unicode code-point offsets for the exact @name token. Must be a current visible conversation participant. All members receive the original message and may contribute.

| Field | Type | Usage |
| --- | --- | --- |
| `principal_id` (required) | `string` | Person, agent or service identity ID. This is an API term, not a separate product entity. |
| `start` (required) | `integer` | Inclusive Unicode code-point offset of the mention, not a byte or UTF-16 index. minimum=0. |
| `end` (required) | `integer` | Exclusive Unicode code-point offset of the mention. minimum=1. |

## ChannelPolicy



| Field | Type | Usage |
| --- | --- | --- |
| `mode` (required) | `preferred \| all` | preferred follows destination order with failure fallback and optional unanswered-request follow-up; all sends to all selected channels immediately. |
| `destinations` (required) | array of `string` | Recipient-owned delivery destination IDs in preference order. An empty list keeps delivery in the workspace only. maxItems=16. |
| `followup_seconds` (required) | `integer` | 0 disables unanswered-request follow-ups. Otherwise 5 to 900 seconds. Previously saved longer delays may be retained unchanged. Only questions and approvals; all mode requires 0. minimum=0, maximum=604800. |

## ChannelOverride



| Field | Type | Usage |
| --- | --- | --- |
| `source` (required) | `object` | Sender selector for a channel override: an exact Agent or an Agent role group. |
| `policy` (required) | [ChannelPolicy](https://beepgrid.com/docs/reference/models/#channelpolicy) | Channel delivery policy. It changes delivery destinations without granting contact or decision authority. |

**`source` fields**

| Field | Type | Usage |
| --- | --- | --- |
| `source.kind` (required) | `agent \| group` | Resource or operation kind. Use one of the listed values, not a display label. |
| `source.id` (required) | `string` | Stable identifier returned by the engine. Treat it as opaque. |

## DeliveryPreferences



| Field | Type | Usage |
| --- | --- | --- |
| `person_id` | `string` | Stable recipient Person identity ID. |
| `version` (required) | `integer` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. minimum=0. |
| `default` (required) | `JSON value` | Recipient default channel policy; null preserves existing destination-based routing. |
| `overrides` (required) | array of [ChannelOverride](https://beepgrid.com/docs/reference/models/#channeloverride) | Ordered sender-specific delivery preferences. An exact Agent match precedes matching Agent roles, then the recipient default. maxItems=64. |

## Credential



| Field | Type | Usage |
| --- | --- | --- |
| `id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `principal_id` | `string` | Person, agent or service identity ID. This is an API term, not a separate product entity. |
| `owner_name` | `string` | Display name of the identity that owns the credential. |
| `name` | `string` | Human-readable name. It is not necessarily unique. |
| `kind` | `string` | Resource or operation kind. Use one of the listed values, not a display label. |
| `prefix` | `string` | Permitted enrollment namespace prefix for a bounded launcher. |
| `token_hint` | `string` | Non-secret token suffix used to identify a credential. It cannot authenticate. |
| `created_at` | `string` | Creation timestamp in RFC 3339 UTC. |
| `last_used_at` | `string \| null` | Most recently recorded authenticated use, or null. Updates are throttled and are not an exact per-request audit trail. format="date-time". |
| `expires_at` | `string \| null` | Credential expiry timestamp, or null for a non-expiring credential. Renewable worker leases remain bounded by renewable_until. format="date-time". |
| `renewable_until` | `string \| null` | Hard deadline for a renewable worker credential, or null when it is not renewable. format="date-time". |
| `previous_until` | `string \| null` | Deadline for the previous token during rotation overlap, or null when no previous token remains valid. format="date-time". |
| `permissions` | `array \| null` | Optional credential-specific restriction to read, message, request, respond, execute or manage. Underlying identity permissions still apply. |
| `version` | `integer` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `revoked` | `boolean` | Whether the credential has been revoked and can no longer authenticate. |
| `parent_credential_id` | `string` | Credential that enrolled this worker, when applicable; used for optional worker revocation with the parent. |

## IssuedCredential



| Field | Type | Usage |
| --- | --- | --- |
| `id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `kind` | `string` | Resource or operation kind. Use one of the listed values, not a display label. |
| `token` | `string` | Bearer credential. Save in protected server-side storage and never expose it in browser code or logs. |
| `expires_at` | `string \| null` | Credential expiry timestamp, or null for a non-expiring credential. Renewable worker leases remain bounded by renewable_until. format="date-time". |

## CredentialReplacement



| Field | Type | Usage |
| --- | --- | --- |
| `token` | `string` | Bearer credential. Save in protected server-side storage and never expose it in browser code or logs. |
| `credential` | [Credential](https://beepgrid.com/docs/reference/models/#credential) | Non-secret credential metadata returned with a newly rotated bearer token. |

## ProviderField



| Field | Type | Usage |
| --- | --- | --- |
| `name` | `string` | Human-readable name. It is not necessarily unique. |
| `required` | `boolean` | Whether this provider field must be configured. |
| `secret` | `boolean` | Write-only provider secret. Omitted from ordinary read/setup responses. |

## ProviderCapability



| Field | Type | Usage |
| --- | --- | --- |
| `kind` | `string` | Resource or operation kind. Use one of the listed values, not a display label. |
| `fields` | array of [ProviderField](https://beepgrid.com/docs/reference/models/#providerfield) | Provider setup field definitions with types, requirements and safe constraints. |
| `inbound_messages` | `boolean` | Whether native inbound messages are accepted. |
| `native_approvals` | `boolean` | Whether authenticated native channel decisions are supported. |
| `web_continuation` | `boolean` | Whether the conversation can continue in the workspace. |
| `attachments` | `boolean` | Currently visible attachment metadata. |
| `builtin` | `boolean` | Whether the capability is provided by the engine without a provider installation. |
| `directions` | array of `string` | Supported inbound/outbound directions. |
| `replies` | `boolean` | Specialist requested decisions visible to the current caller. |
| `file_mode` | `native \| workspace_link` | Actual attachment transport behavior for the provider. |
| `setup_modes` | array of `string` | Supported setup methods; use only advertised modes. |
| `identity` | `string` | Provider identity-linking requirements or current evidence. |
| `constraints` | array of `string` | Provider field validation constraints. |

## ConnectionTestEvidence



| Field | Type | Usage |
| --- | --- | --- |
| `delivery_id` | `string` | Transport delivery record ID. Different attempts can refer to the same canonical message/request. |
| `conversation_id` | `string` | Canonical conversation ID. Use it to continue the same authorized history. |
| `state` | `string` | Lifecycle state. Read the resource-specific enum; request and execution states differ. |
| `detail` | `string` | Safe diagnostic explanation, without credentials. |
| `created_at` | `string` | Creation timestamp in RFC 3339 UTC. |
| `inbound_reply` | `boolean` | Whether authenticated native replies can update canonical conversations. |

## ConnectionDiagnostic



| Field | Type | Usage |
| --- | --- | --- |
| `connection_id` | `string` | Configured channel connection ID. |
| `version` | `integer` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `enabled` | `boolean` | Whether this configured connection is enabled. |
| `configuration_valid` | `boolean` | Whether the current non-sending configuration check passed. |
| `issues` | array of `string` | Safe configuration issues that need operator attention. |
| `provider_acceptance` | `not_tested \| observed` | Transport acceptance evidence, separate from an attributed reply. |
| `sends` | `False` | Whether a preview itself sends anything; dispatch preview returns false. |
| `state` | `configured \| setup_incomplete \| disconnected \| verifying \| action_needed \| connected` | Lifecycle state. Read the resource-specific enum; request and execution states differ. |
| `qualification` | `not_verified \| provider_acceptance_observed \| engine_round_trip_observed` | Recorded qualification evidence level; configuration alone is not a live round trip. |
| `last_test` | [ConnectionTestEvidence](https://beepgrid.com/docs/reference/models/#connectiontestevidence) | Latest explicit connection test evidence. |

## ProviderSetup



| Field | Type | Usage |
| --- | --- | --- |
| `connection_id` | `string` | Configured channel connection ID. |
| `kind` | `string` | Resource or operation kind. Use one of the listed values, not a display label. |
| `version` | `integer` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `mode` | `string` | primary, copy or fallback routing mode. |
| `steps` | array of `string` | Ordered setup actions supported by this provider. |
| `callbacks` | `object` | Safe callback URLs and verification requirements. |
| `manifest` | `object` | Safe provider application manifest for setup. |
| `registration` | `object` | Provider callback registration information. |
| `diagnostic` | [ConnectionDiagnostic](https://beepgrid.com/docs/reference/models/#connectiondiagnostic) | Non-sending configuration and identity diagnostic projection. |