Schemas¶

Generated at build time from docs/api/openapi.yaml; the gateway uses the same schemas. Do not edit this page: change the document.

Uuid¶

UUIDv7 (RFC 9562), lowercase canonical form.

Type: string (uuid)

CorrelationId¶

W3C trace ID (16 bytes) of the request, written as a lowercase UUID; not a UUIDv7. Generated by the server.

Type: string (uuid)

Example: 4bf92f35-77b3-4da6-a3ce-929d0e0e4736.

Timestamp¶

RFC 3339 timestamp in UTC with millisecond precision and suffix Z.

Type: string (date-time)

Cursor¶

Opaque pagination cursor. Clients must not parse or build cursors.

Type: string

Example: eyJrIjoiMDE5MmY0YTAtN2IxYy03MDAwLThhMDAtMDAwMDAwMDAwMDAxIn0.

Level¶

Grant level. Ordered read < write < trigger.

Type: string

Values: read, write, trigger.

Capability¶

Capability next to the level. terminal exists only on the target host.

Type: string

Values: approve_actions, upload, export, manage, terminal.

PrincipalKind¶

Type: string

Values: user, agent, app.

ActorKind¶

Type: string

Values: user, agent, app, system.

BillingMode¶

Backend policy of an agent. personal runs on the subscription of exactly one person.

Type: string

Values: personal, organization.

ToolClass¶

Tool class of an agent runtime, ordered chat < scoped < host (07, 2.11).

Type: string

Values: chat, scoped, host.

ToolClassSet¶

Property	Type	Required	Description
`tool_class`	ToolClass	yes
`reason`	string	yes	Max length 500. Example: `Agent now works in a project checkout`.

No other properties are allowed.

BillingEvidence¶

How the runtime proves its actual billing mode. Never a key value or prefix (schema billing_evidence.v1).

Property	Type	Required	Description
`provider`	string	no	Pattern `^[a-z0-9][a-z0-9_.:-]*$`. Example: `anthropic`.
`key_type`	string	yes	Values: `api_key`, `oauth`, `cloud`, `none`, `unknown`.
`method`	string	no	Pattern `^[a-z0-9][a-z0-9_.:-]*$`. Example: `resolved_credentials`.

No other properties are allowed.

Money¶

Amount in micro units of the currency. Never a float.

Property	Type	Required	Description
`amount_micros`	integer (int64)	yes	Example: `1250000`.
`currency`	string	yes	ISO 4217 code. Example: `USD`.
`is_estimate`	boolean	yes	True until the amount was reconciled with the provider invoice.

CspReportList¶

Reports of the Reporting API (https://www.w3.org/TR/reporting-1/); each item is a report object whose body is a CSP violation report (https://www.w3.org/TR/CSP3/#reporting). The server reads only type, body.effectiveDirective, body.blockedURL and body.disposition.

Type: array of JsonObject

CspReportLegacy¶

Legacy report of the report-uri directive (CSP Level 2). The server reads only effective-directive (else violated-directive), blocked-uri and disposition of csp-report.

Property	Type	Required	Description
`csp-report`	JsonObject	yes

No other properties are allowed.

JsonObject¶

Free-form JSON object whose schema is named in the field description.

Type: object

JsonValue¶

Any JSON value except null. The schema of the value is defined by its key.

Type: any

JsonPatchOperation¶

One RFC 6902 operation, restricted to add, replace and remove.

Property	Type	Required	Description
`op`	string	yes	Values: `add`, `replace`, `remove`.
`path`	string	yes	JSON Pointer (RFC 6901) into the run document. Example: `/steps/0192f4a0-7b1c-7000-8a00-0000000000a1/status`.
`value`	JsonValue	no

No other properties are allowed.

PrincipalRef¶

Minimal public view of a principal, embedded in other objects.

Property	Type	Required	Description
`id`	Uuid	yes
`kind`	PrincipalKind	yes
`handle`	string	yes	Example: `alex`.
`display_name`	string	yes	Example: `Alex`.
`avatar_file_id`	Uuid	no

Problem¶

Error body after RFC 9457 (application/problem+json). type is a relative URI with full path /api/v1/problems/{code}; code repeats its last segment for convenience.

Property	Type	Required	Description
`type`	string (uri-reference)	yes	Example: `/api/v1/problems/not_found`.
`title`	string	yes	Example: `Not found`.
`status`	integer	yes	Example: `404`.
`detail`	string	no	Human-readable explanation for this occurrence. Never contains content or secrets.
`instance`	string (uri-reference)	no	Request path of this occurrence without query string. Path parameters that carry a secret (the `token` of `postIncomingWebhook`) appear as their template, e.g. `{token}`. Example: `/api/v1/threads/0192f4a0-7b1c-7000-8a00-000000000301`.
`code`	string	yes	Stable machine code; the known values are `x-problem-codes` of this schema. Clients treat unknown codes by HTTP status. Example: `not_found`.
`correlation_id`	CorrelationId	yes
`reason`	string	no	Machine-readable cause that refines `code` (06 section 5): the deny reason of 07 section 4.1 for denials where it reveals nothing, or a cause named by the chapter of the operation, e.g. `billing_mode_personal_not_holder`, `quota_exceeded`. A new cause is a new `reason`, never a new `code` outside `x-problem-codes`. Clients treat unknown values by `code`.
`hint`	string	no	Short instruction for the person making the change, e.g. switch the agent to `organization` first.
`errors`	array of FieldError	no	Field errors for `validation_failed`.
`current`	JsonObject	no	Current representation of the resource for `version_conflict` and `base_version_conflict`.
`attempts_remaining`	integer	no	Present with `fingerprint_mismatch`; `0` means the host fell back to `pairing` and needs a new pairing code (24, 3.2). Minimum 0.
`conflicts`	array of InvariantViolation	no	Present with `i1_violation` (one entry per agent, 10-backend-policy, 5.4) and `i6_violation` (one entry per host, 24, 7.3).

FieldError¶

Property	Type	Required	Description
`pointer`	string	yes	Where the violation is: a JSON Pointer (RFC 6901) to the offending member of the request body (for an unknown or missing member the pointer names that member, e.g. `/name`), or `#path/<name>`, `#query/<name>`, `#header/<name>` for parameters; empty for a rule of the whole request or the body as a whole. Example: `/content_md`.
`code`	string	yes	Machine-readable rule the field violates. Schema validation uses `required`, `unknown_member` (W7: request schemas are closed), `invalid_type`, `invalid_format`, `invalid_enum`, `too_long`, `too_short`, `too_large`, `too_small`, `too_many_items`, `too_few_items`, `pattern_mismatch` and `invalid` for any other rule; use cases add `limit_reached` and `not_enabled` (06 section 5). Clients treat unknown codes like `invalid`. Example: `too_long`.
`detail`	string	no	Short English explanation; never repeats the submitted value.

ProblemType¶

Documentation of one problem type, served at its type URI.

Property	Type	Required	Description
`code`	string	yes	Example: `version_conflict`.
`status`	integer	yes	Example: `412`.
`title`	string	yes	Example: `Version conflict`.
`description`	string	yes
`client_action`	string	no	What a client should do.

Discovery¶

Public instance metadata for login screens, SDKs and adapters.

Property	Type	Required	Description
`instance_id`	Uuid	yes
`setup_required`	boolean	yes	True until the first owner exists (08, 4); every other operation answers `503 setup_required` until then.
`api_versions`	array of string	yes
`spec_version`	string	yes	SemVer of openapi.yaml served by this instance. Example: `1.0.0`.
`features`	array of string	no	Feature keys this server implements beyond the base contract of its spec version.
`gateway`	GatewayInfo	yes
`branding`	PublicBranding	yes
`auth_providers`	array of AuthProviderInfo	yes
`local_password_enabled`	boolean	no
`jwks_uri`	string (uri-reference)	yes	Example: `/api/v1/instance/jwks`.
`webhook_keys_uri`	string (uri-reference)	yes	Example: `/api/v1/instance/webhook-keys`.
`min_client_versions`	array of ClientVersionRequirement	no

GatewayInfo¶

Property	Type	Required	Description
`url`	string (uri-reference)	yes	Example: `/api/v1/gateway`.
`protocol_versions`	array of integer	yes

ClientVersionRequirement¶

Property	Type	Required	Description
`platform`	DevicePlatform	yes
`min_version`	string	yes	Below this version the app does not connect (`client.min_version.<platform>`, 18 section 9). Example: `1.0.0`.
`recommended_version`	string	no	Below this version the app shows an update note (`client.recommended_version.<platform>`). Example: `1.2.0`.

AuthProviderInfo¶

Property	Type	Required	Description
`id`	Uuid	yes
`kind`	IdentityProviderKind	yes
`name`	string	yes	Example: `Company SSO`.

PublicBranding¶

Property	Type	Required	Description
`product_name`	string	yes	Example: `Team Chat`.
`accent_color`	string	no	Key of a category color of the design system (`spruce`, `loch`, `heather`, `rowan`, `amber`, `gorse`, `moss`), never a free color value (ADR 0044). Example: `loch`.
`logo_url`	string (uri-reference)	no	Example: `/api/v1/instance/branding/logo`.

Branding¶

Property	Type	Required	Description
`product_name`	string	yes	Example: `Team Chat`.
`accent_color`	string	no	Example: `loch`.
`logo_file_id`	Uuid	no
`version`	integer (int64)	yes

BrandingUpdate¶

Property	Type	Required	Description
`product_name`	string	yes	Min length 1. Example: `Team Chat`.
`accent_color`	string	no	Example: `loch`.

No other properties are allowed.

Jwks¶

JSON Web Key Set (RFC 7517) with the public keys for access tokens, invocation tokens and terminal session tokens.

Property	Type	Required	Description
`keys`	array of JsonObject	yes

WebhookKeys¶

Public keys for Standard Webhooks v1a signatures.

Property	Type	Required	Description
`keys`	array of WebhookKey	yes

WebhookKey¶

Property	Type	Required	Description
`kid`	string	yes	Example: `whk-2026-10`.
`public_key`	string	yes	Ed25519 public key with prefix `whpk_`, followed by the standard base64 (with padding) of its DER-encoded SubjectPublicKeyInfo (RFC 8410). Example: `whpk_MCowBQYDK2VwAyEA6h3uZ0Q4i1Yv1o1Wg8bQq3c0o8bq9oQm3Kc8n3m3v0I=`.
`state`	string	yes	Values: `next`, `active`, `retiring`.
`not_after`	Timestamp	no

InstanceInfo¶

Instance view for an authenticated principal.

Property	Type	Required	Description
`instance_id`	Uuid	yes
`branding`	Branding	yes
`locale_default`	string	yes	Example: `de`.
`spec_version`	string	yes	Example: `1.0.0`.
`features`	array of EvaluatedFlag	yes	Feature flags evaluated for the caller.
`limits`	InstanceLimits	yes
`telemetry_dashboard_url`	string (uri)	no	Link of the administration to the telemetry backend, from the configuration key `telemetry.dashboard_url` (17 8). Present only for owners and only when the key is set, because the address names internal infrastructure; clients open it in the system browser or a new tab, never in a WebView or iframe. Example: `https://telemetry.example.com/d/bothy`.
`stats_time_zone`	string	no	IANA name of the time zone in which the day, week and month buckets of the statistics operations start (`stats.time_zone`, 17 8); clients align the ranges of their statistics queries to its calendar days. Example: `Europe/Berlin`.

EvaluatedFlag¶

Property	Type	Required	Description
`key`	string	yes	Example: `dm.enabled`.
`enabled`	boolean	yes

InstanceLimits¶

Effective values of limits that clients enforce before sending.

Property	Type	Required	Description
`message_max_content_bytes`	integer (int64)	yes	Example: `262144`.
`message_max_attachments`	integer	yes	Example: `10`.
`file_max_upload_bytes`	integer (int64)	yes	Example: `104857600`.
`thread_title_max_chars`	integer	yes	Example: `200`.
`voice_max_duration_ms`	integer (int64)	yes	Longest voice message (`voice.max_duration`, 12). Example: `900000`.

InstanceSetting¶

A registered key without a stored row has its default value and version 0, without updated_by and updated_at.

Property	Type	Required	Description
`key`	string	yes	Example: `locale.default`.
`value`	JsonValue	yes
`version`	integer (int64)	yes
`updated_by`	Uuid	no
`updated_at`	Timestamp	no

InstanceSettingPut¶

Property	Type	Required	Description
`value`	JsonValue	yes

No other properties are allowed.

InstanceSettingList¶

Property	Type	Required	Description
`items`	array of InstanceSetting	yes

FeatureFlag¶

Registration from the code plus the stored value (ADR 0064). A key without a stored row has its default and version 0; a stored key without registration is orphaned and off.

Property	Type	Required	Description
`key`	string	yes	Example: `voice.enabled`.
`kind`	string	no	Absent for orphaned keys. Values: `release`, `option`.
`description`	string	no	From the registration (English); absent for orphaned keys. Example: `Voice messages with transcription`.
`default`	boolean	no	Registered default; absent for orphaned keys.
`remove_by`	string	no	Server version by which a `release` flag is removed. Example: `1.4.0`.
`module`	string	no	Module that owns the flag. Example: `files`.
`orphaned`	boolean	yes
`enabled`	boolean	yes	Global value; the stored value or the registered default.
`rollout`	FlagRollout	yes
`version`	integer (int64)	yes
`updated_by`	Uuid	no
`updated_at`	Timestamp	no

FlagRollout¶

Principals and groups for which the flag has the opposite value of enabled.

Property	Type	Required	Description
`user_ids`	array of Uuid	no
`group_ids`	array of Uuid	no

No other properties are allowed.

FeatureFlagPut¶

Property	Type	Required	Description
`enabled`	boolean	yes
`rollout`	FlagRollout	no
`reason`	string	yes	Min length 1. Example: `Pilot with the support team`.

No other properties are allowed.

FeatureFlagList¶

Property	Type	Required	Description
`items`	array of FeatureFlag	yes

SigningKeyRotate¶

Property	Type	Required	Description
`purpose`	SigningKeyPurpose	yes
`mode`	string	yes	`scheduled` announces the next key (state `next`); the rotation job makes it `active` after `agent.jwks_max_age`. `emergency` retires every key of the purpose at once and creates a new `active` key. Required, because the two modes have opposite effects. Values: `scheduled`, `emergency`. Example: `scheduled`.
`reason`	string	yes	Example: `Scheduled rotation`.

No other properties are allowed.

SigningKeyRotation¶

Property	Type	Required	Description
`purpose`	SigningKeyPurpose	yes
`new_kid`	string	yes	Example: `inv-2026-11`.
`previous_kid`	string	yes	Example: `inv-2026-10`.
`previous_not_after`	Timestamp	yes

IdentityProvider¶

Property	Type	Required	Description
`id`	Uuid	yes
`kind`	IdentityProviderKind	yes
`name`	string	yes	Example: `Company SSO`.
`config`	JsonObject	yes	Schema `identity_provider.<kind>.v1`. Secrets appear only as `secret_ref` names.
`enabled`	boolean	yes
`allow_provisioning`	boolean	yes
`updated_at`	Timestamp	no

IdentityProviderCreate¶

Property	Type	Required	Description
`kind`	IdentityProviderKind	yes
`name`	string	yes	Example: `Company SSO`.
`config`	JsonObject	yes
`enabled`	boolean	no
`allow_provisioning`	boolean	no

No other properties are allowed.

IdentityProviderUpdate¶

Property	Type	Required
`name`	string	no
`config`	JsonObject	no
`enabled`	boolean	no
`allow_provisioning`	boolean	no

No other properties are allowed.

IdentityProviderList¶

Property	Type	Required	Description
`items`	array of IdentityProvider	yes

DevicePlatform¶

Type: string

Values: ios, android, macos, windows, web, cli.

DeviceRegistration¶

Device and device keys sent with every login completion. The DPoP proof of the request must be signed with the dpop key (public_jwk); step_up_key is the second key with user verification (08, 6.1), absent where no secure key store exists.

Property	Type	Required	Description
`device_id`	Uuid	yes
`name`	string	yes	Example: `Alex iPhone`.
`platform`	DevicePlatform	yes
`app_version`	string	no	Example: `1.4.0`.
`public_jwk`	JsonObject	yes	Public JWK (RFC 7517) of the device key, without private members.
`alg`	string	yes	Values: `ES256`, `EdDSA`.
`attestation`	JsonObject	no	Platform attestation, if the platform provides one.
`step_up_key`	DeviceKeyRegistration	no

No other properties are allowed.

DeviceKeyRegistration¶

Property	Type	Required	Description
`public_jwk`	JsonObject	yes	Public JWK (RFC 7517) without private members.
`alg`	string	yes	Values: `ES256`, `EdDSA`.
`attestation`	JsonObject	no

No other properties are allowed.

PairingBeginRequest¶

Property	Type	Required	Description
`device`	DeviceRegistration	yes

No other properties are allowed.

PairingStarted¶

Property	Type	Required	Description
`pairing_id`	Uuid	yes
`pairing_code`	string	yes	Shown on the new device only; `auth.pairing_code_chars` characters (Crockford Base32). Example: `7KQ2-M9XD`.
`expires_at`	Timestamp	yes

DeviceApprove¶

Property	Type	Required	Description
`verification_code`	string	yes	Code shown on the pending device, typed by the approving person. Pattern `^[0-9]+$`. Example: `042517`.

No other properties are allowed.

PairingApprove¶

Property	Type	Required	Description
`pairing_code`	string	yes	Example: `7KQ2-M9XD`.

No other properties are allowed.

PairingCompleteRequest¶

Property	Type	Required	Description
`pairing_id`	Uuid	yes

No other properties are allowed.

PairingStatus¶

Property	Type	Required	Description
`pairing_id`	Uuid	yes
`status`	string	yes	Not yet approved; ask again after a short wait. Values: `requested`.
`expires_at`	Timestamp	yes

OidcBeginRequest¶

Property	Type	Required	Description
`client`	LoginClient	no
`provider_id`	Uuid	yes
`app_redirect_uri`	string	yes	Redirect target of the app (loopback or claimed scheme, RFC 8252). Must match the allow-list of the provider. Example: `com.example.teamchat:/login`.
`client_challenge`	string	yes	Base64url SHA-256 of a client verifier, binds the later `login_code` to this app instance. Example: `E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM`.
`enrollment_code`	string	no	Optional enrollment code (purpose `first_login`, `recovery` or `identity_link`). Checked at begin, consumed at complete; an unknown subject is then linked to the person of the code (08, 3.1). Example: `en_EXAMPLE`.

No other properties are allowed.

OidcBeginResponse¶

Property	Type	Required	Description
`login_attempt_id`	Uuid	yes
`authorization_url`	string (uri)	yes	Example: `https://login.example.com/authorize?client_id=chat&state=s1`.
`expires_at`	Timestamp	yes

OidcCompleteRequest¶

Property	Type	Required	Description
`client`	LoginClient	no
`login_code`	string	yes	One-time code the server appended to `app_redirect_uri` after the provider callback. Example: `lc_8f2d1c`.
`client_verifier`	string	yes	Example: `dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk`.
`device`	DeviceRegistration	no

No other properties are allowed.

TrustedHeaderLoginRequest¶

Property	Type	Required	Description
`client`	LoginClient	no
`device`	DeviceRegistration	no
`enrollment_code`	string	no	Optional enrollment code; links an unknown header login to the person of the code (08, 3.1). Example: `en_EXAMPLE`.

No other properties are allowed.

EnrollRedeemRequest¶

Redeems an enrollment code with device keys only; the redeeming device becomes active (08, 3.2).

Property	Type	Required	Description
`enrollment_code`	string	yes	Example: `en_EXAMPLE`.
`device`	DeviceRegistration	yes

No other properties are allowed.

ExtensionSessionCreate¶

Child session of the calling app session for an app extension with its own refresh family (08, 7.4).

Property	Type	Required	Description
`client_component`	string	yes	Values: `share_ext`.

No other properties are allowed.

WebAuthnChallenge¶

Property	Type	Required	Description
`challenge_id`	Uuid	yes	ID of the stored ceremony challenge; valid once until `expires_at`.
`public_key`	JsonObject	yes	WebAuthn `PublicKeyCredentialRequestOptions` or `PublicKeyCredentialCreationOptions` in JSON form.
`expires_at`	Timestamp	yes

PasskeyLoginBeginRequest¶

Property	Type	Required	Description
`login_name`	string	no	Optional; without it the server offers discoverable credentials. Example: `alex`.

No other properties are allowed.

PasskeyLoginCompleteRequest¶

Property	Type	Required	Description
`client`	LoginClient	no
`challenge_id`	Uuid	yes
`credential`	JsonObject	yes	WebAuthn `PublicKeyCredential` in JSON form.
`device`	DeviceRegistration	no

No other properties are allowed.

EnrollBeginRequest¶

Property	Type	Required	Description
`enrollment_code`	string	yes	Example: `en_4KX9-2MQA`.

No other properties are allowed.

EnrollCompleteRequest¶

Property	Type	Required	Description
`challenge_id`	Uuid	yes
`credential`	JsonObject	yes
`passkey_name`	string	yes	Example: `Laptop`.
`device`	DeviceRegistration	yes

No other properties are allowed.

PasswordLoginRequest¶

Property	Type	Required	Description
`client`	LoginClient	no
`login_name`	string	yes	Example: `alex`.
`password`	string (password)	yes
`totp_code`	string	yes	Example: `492039`.
`device`	DeviceRegistration	no

No other properties are allowed.

TokenRefreshRequest¶

Property	Type	Required	Description
`refresh_token`	string	yes	Example: `rt_q2Z0`.

No other properties are allowed.

TokenResponse¶

Token pair after login or refresh. token_type is always DPoP (RFC 9449).

Property	Type	Required	Description
`access_token`	string	yes	Example: `eyJhbGciOiJFZERTQSJ9.e30.sig`.
`token_type`	string	yes	Values: `DPoP`.
`expires_in`	integer	yes	Seconds until the access token expires. Example: `900`.
`refresh_token`	string	yes	Example: `rt_q2Z0`.
`refresh_expires_at`	Timestamp	yes
`session`	Session	yes
`device`	Device	yes

LoginClient¶

console: no device or DPoP; cookie, no token (08, 7.5).

Type: string

Values: app, console.

ConsoleSession¶

Property	Type	Required	Description
`user_id`	Uuid	yes
`display_name`	string	yes
`expires_at`	Timestamp	yes
`idle_timeout_seconds`	integer	yes
`step_up_at`	Timestamp	no
`step_up_method`	string	no	Values: `passkey`, `password_totp`, `oidc_reauth`.
`step_up_valid_until`	Timestamp	no
`step_up_methods_available`	array of string	yes	Values: `passkey`, `oidc_reauth`, `password_totp`.
`view_as`	object	no
`view_as.user_id`	Uuid	yes
`view_as.display_name`	string	yes
`view_as.started_at`	Timestamp	yes
`view_as.ends_at`	Timestamp	yes

StepUpPasswordRequest¶

Property	Type	Required
`challenge_id`	Uuid	yes
`password`	string (password)	yes
`totp_code`	string	yes

No other properties are allowed.

StepUpOidcBeginRequest¶

Property	Type	Required
`challenge_id`	Uuid	yes
`provider_id`	Uuid	yes
`app_redirect_uri`	string	yes
`client_challenge`	string	yes

No other properties are allowed.

StepUpChallenge¶

Property	Type	Required	Description
`challenge_id`	Uuid	yes
`challenge`	string	yes	Base64url random value to sign. Single use, valid `auth.step_up_challenge_ttl`. Clients show their own localized prompt text. Example: `Zm9vYmFyYmF6`.
`passkey_options`	JsonObject	no	WebAuthn request options when the user has passkeys; their challenge is this step-up challenge.
`expires_at`	Timestamp	yes

StepUpPasskeyRequest¶

Property	Type	Required	Description
`challenge_id`	Uuid	yes
`credential`	JsonObject	yes

No other properties are allowed.

StepUpDeviceKeyRequest¶

Property	Type	Required	Description
`challenge_id`	Uuid	yes
`signature`	string	yes	Compact JWS signed by the active `step_up` key of the session's device after user verification on the device. Header `alg` only (no `jwk`, `jku`, `x5u`, `x5c`, `crit`); payload `{"challenge": <challenge>, "sid": <session id>, "iat": <NumericDate>}` (08, 6.2). Example: `eyJhbGciOiJFUzI1NiJ9.EXAMPLEpayload.EXAMPLEsignature`.

No other properties are allowed.

StepUpResult¶

Property	Type	Required	Description
`step_up_at`	Timestamp	yes
`valid_until`	Timestamp	yes

Me¶

The calling principal.

Property	Type	Required	Description
`principal`	PrincipalRef	yes
`is_owner`	boolean	yes
`email`	string (email)	no	Example: `alex@example.com`.
`locale`	string	no	Example: `de`.
`time_zone`	string	no	Example: `Europe/Berlin`.
`permission_version`	integer (int64)	yes
`session_id`	Uuid	no
`device_id`	Uuid	no
`step_up_valid_until`	Timestamp	no

User¶

Directory entry of a person.

Property	Type	Required	Description
`id`	Uuid	yes
`handle`	string	yes	Example: `sam`.
`display_name`	string	yes	Example: `Sam`.
`avatar_file_id`	Uuid	no
`status`	UserStatus	yes	Example: `active`.
`is_owner`	boolean	yes
`locale`	string	no	Example: `en`.
`time_zone`	string	no	Example: `Europe/Berlin`.
`created_at`	Timestamp	yes

UserCreate¶

Property	Type	Required	Description
`handle`	string	yes	Pattern `^[a-z0-9][a-z0-9._-]*$`. Example: `robin`.
`display_name`	string	yes	Example: `Robin`.
`email`	string (email)	no	Example: `robin@example.com`.
`locale`	string	no	Example: `de`.
`time_zone`	string	no	Example: `Europe/Berlin`.
`local_account`	boolean	no	Create an enrollment code for the local identity provider.

No other properties are allowed.

UserCreated¶

Property	Type	Required	Description
`user`	User	yes
`enrollment`	EnrollmentCode	no

UserUpdate¶

Property	Type	Required
`display_name`	string	no
`email`	string (email)	no
`locale`	string	no
`time_zone`	string	no

No other properties are allowed.

ProfileUpdate¶

Property	Type	Required	Description
`display_name`	string	no	Example: `Alex`.
`locale`	string	no	Example: `de`.
`time_zone`	string	no	Example: `Europe/Berlin`.

No other properties are allowed.

EnrollmentCode¶

One-time code shown once to the owner, handed to the person out of band. A replay of the creating request with the same Idempotency-Key does not repeat it (409 conflict, reason: one_time_secret).

Property	Type	Required	Description
`code`	string	yes	Example: `en_4KX9-2MQA`.
`purpose`	string	yes	Values: `first_login`, `recovery`, `identity_link`.
`expires_at`	Timestamp	yes

ReasonBody¶

Property	Type	Required	Description
`reason`	string	yes	Min length 1. Example: `Left the team`.

No other properties are allowed.

ResolveI1¶

Guided flow (05 rule 1.6, 10 section 11): switch these agents to organization first, in the same transaction as the change.

Property	Type	Required	Description
`switch_to_organization`	array of Uuid	yes	Min items 1; unique items True.
`reason`	string	yes	Reason of the switch, in the audit entry of every switched agent; at most `audit.reason_max_chars` characters, no control or bidi characters. Min length 1. Example: `Sam triggers the assistant too`.

No other properties are allowed.

OwnerAdd¶

Property	Type	Required	Description
`user_id`	Uuid	yes
`reason`	string	yes	Example: `Second owner as deputy`.
`resolve_i1`	ResolveI1	no

No other properties are allowed.

Owner¶

Property	Type	Required
`user`	PrincipalRef	yes
`granted_by`	Uuid	no
`granted_at`	Timestamp	yes
`reason`	string	yes

OwnerList¶

Property	Type	Required	Description
`items`	array of Owner	yes

Identity¶

Property	Type	Required	Description
`id`	Uuid	yes
`provider_id`	Uuid	yes
`provider_kind`	IdentityProviderKind	yes
`subject`	string	yes	Example: `alex`.
`issuer`	string	no	Example: `https://login.example.com`.
`email_at_link`	string (email)	no
`linked_at`	Timestamp	yes
`last_login_at`	Timestamp	no

Passkey¶

Property	Type	Required	Description
`id`	Uuid	yes
`name`	string	yes	Example: `Laptop`.
`aaguid`	Uuid	no
`backup_eligible`	boolean	yes
`created_at`	Timestamp	yes
`last_used_at`	Timestamp	no

CredentialOverview¶

Property	Type	Required
`identities`	array of Identity	yes
`passkeys`	array of Passkey	yes
`local_password_set`	boolean	yes
`totp_enrolled`	boolean	yes

IdentityLinkBegin¶

Property	Type	Required	Description
`provider_id`	Uuid	yes
`app_redirect_uri`	string	yes	Example: `com.example.teamchat:/link`.
`client_challenge`	string	yes	Example: `E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM`.

No other properties are allowed.

IdentityLinkComplete¶

Property	Type	Required	Description
`login_code`	string	yes	Example: `lc_8f2d1c`.
`client_verifier`	string	yes	Example: `dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk`.

No other properties are allowed.

PasskeyRegisterComplete¶

Property	Type	Required	Description
`challenge_id`	Uuid	yes
`credential`	JsonObject	yes
`name`	string	yes	Example: `Laptop`.

No other properties are allowed.

LocalCredentialSet¶

Sets or replaces the local password, starts a TOTP enrollment (totp_enroll, the response carries the new secret once) or confirms it (totp_code). At least one member; the first call sets password. The password path counts as established once TOTP is confirmed (08, 2.5).

Property	Type	Required	Description
`password`	string (password)	no
`totp_enroll`	boolean	no
`totp_code`	string	no	Current code of the enrolled TOTP secret; confirms the enrollment. Pattern `^[0-9]{6}$`. Example: `492039`.

No other properties are allowed.

LocalCredentialResult¶

Property	Type	Required	Description
`password_set`	boolean	yes
`totp_enabled`	boolean	yes	True once a TOTP enrollment is confirmed.
`totp_secret_uri`	string	no	otpauth URI, returned once when `totp_enroll` was set. Example: `otpauth://totp/Team%20Chat:alex?secret=JBSWY3DPEHPK3PXP`.

Device¶

Property	Type	Required	Description
`id`	Uuid	yes
`user_id`	Uuid	yes
`name`	string	yes	Example: `Alex iPhone`.
`platform`	DevicePlatform	yes
`state`	string	yes	Values: `pending`, `active`, `revoked`. Example: `active`.
`app_version`	string	no	Example: `1.4.0`.
`key_thumbprint`	string	no	RFC 7638 thumbprint of the active `dpop` device key (`cnf.jkt`). Example: `0ZcOCORZNYy-DWpqq30jZyJGHTN0d2HglBV3uiguA4I`.
`step_up_key_thumbprint`	string	no	RFC 7638 thumbprint of the active `step_up` device key, if the device has one.
`verification_code`	string	no	Only in responses to the pending device itself (`TokenResponse`, `getDevice`, `listMyDevices` for its own entry); never shown to other devices or owners (08, 5.2). Pattern `^[0-9]+$`.
`revoke_reason`	string	no	Values: `revoked_by_self`, `revoked_by_owner`, `user_disabled`, `inactive`, `verification_failed`, `pending_expired`, `pairing_expired`.
`approved_at`	Timestamp	no
`revoked_at`	Timestamp	no
`created_at`	Timestamp	yes
`last_seen_at`	Timestamp	no
`push_registrations`	array of PushRegistration	no	Every push registration of the device, active and disabled, ascending by `id`, never with a token (13, 13). Absent when the device has none.

Session¶

Property	Type	Required	Description
`id`	Uuid	yes
`user_id`	Uuid	yes
`device_id`	Uuid	yes
`auth_method`	string	yes	Values: `oidc`, `trusted_header`, `passkey`, `password_totp`, `enrollment_code`, `device_pairing`.
`client_component`	string	no	Values: `app`, `share_ext`, `console`.
`created_at`	Timestamp	yes
`expires_at`	Timestamp	yes
`step_up_at`	Timestamp	no
`step_up_method`	string	no	Values: `passkey`, `device_key`, `password_totp`, `oidc_reauth`.
`last_seen_at`	Timestamp	no
`current`	boolean	no	True for the session of this request. Set only in REST responses.

ApiToken¶

Property	Type	Required	Description
`id`	Uuid	yes
`principal_id`	Uuid	yes
`name`	string	yes	Example: `Adapter production`.
`token_prefix`	string	yes	`bothy_<kind>_` plus the first characters of the random part (03 `api_tokens`). Example: `bothy_agt_EXAMPL`.
`scopes`	array of AppScope	yes
`dpop_jkt`	string	no
`expires_at`	Timestamp	no
`created_at`	Timestamp	yes
`last_used_at`	Timestamp	no
`revoked_at`	Timestamp	no

ApiTokenCreate¶

Property	Type	Required	Description
`name`	string	yes	Example: `Adapter production`.
`scopes`	array of AppScope	no	Only for app tokens, a subset of the granted scopes of the installation; absent or empty takes all granted scopes at this moment. A scope granted later needs a new token. Agent tokens (all agent scopes implicitly) and personal tokens (the grants of the person) carry none.
`dpop_jkt`	string	no	RFC 7638 thumbprint (43 base64url characters) of the key the token is bound to; requests must then use DPoP. Required for the kinds in `auth.dpop_required_for`.
`expires_at`	Timestamp	yes	Required; at most `auth.api_token_max_ttl` (agents, apps) or `auth.personal_token_max_ttl` (personal) ahead.

No other properties are allowed.

ApiTokenCreated¶

Property	Type	Required	Description
`token`	ApiToken	yes
`secret`	string	yes	Full token value `bothy_<kind>_<random>_<checksum>` (prefix for secret scanners). Shown exactly once. Example: `bothy_agt_EXAMPLEOnlyNotARealTokenForTheChecksumTests_3NymP3`.

AppScope¶

Type: string

Values: messages:read, messages:write, files:read, files:write, commands:write, components:write, users:read, events:subscribe, costs:reconcile.

Group¶

Property	Type	Required	Description
`id`	Uuid	yes
`name`	string	yes	Example: `Support`.
`description`	string	yes	Example: `Support team`.
`source`	GroupSource	yes
`provider_id`	Uuid	no	OIDC provider whose group claim manages the members; set exactly for `source = oidc_claim`.
`external_ref`	string	no	Claim value of the provider; set exactly for `source = oidc_claim`.
`member_count`	integer	yes
`created_at`	Timestamp	yes

GroupCreate¶

Property	Type	Required	Description
`name`	string	yes	Example: `Support`.
`description`	string	no
`source`	GroupSource	no
`provider_id`	Uuid	no	Required with `source = oidc_claim`; the OIDC provider whose claim manages the members.
`external_ref`	string	no	Required with `source = oidc_claim`; the claim value.

No other properties are allowed.

GroupUpdate¶

Property	Type	Required	Description
`name`	string	no	Example: `Support`.
`description`	string	no

No other properties are allowed.

GroupMember¶

Property	Type	Required
`user`	PrincipalRef	yes
`added_by`	Uuid	no
`added_at`	Timestamp	yes
`expires_at`	Timestamp	no

GroupMemberAdd¶

Property	Type	Required
`user_id`	Uuid	yes
`expires_at`	Timestamp	no
`resolve_i1`	ResolveI1	no

No other properties are allowed.

TargetKind¶

host is a connected host for the terminal; it has no level and only the capability terminal (24, 8.1).

Type: string

Values: instance, space, channel, host.

GrantSubjectKind¶

Type: string

Values: user, group, agent, app.

Grant¶

Property	Type	Required	Description
`id`	Uuid	yes
`subject_kind`	GrantSubjectKind	yes
`subject_id`	Uuid	yes	Principal ID for `user`, `agent`, `app`; group ID for `group`.
`target_kind`	TargetKind	yes
`target_id`	Uuid	no	Absent for `instance`.
`level`	Level	no	Absent exactly for `target_kind = host`.
`capabilities`	array of Capability	yes
`expires_at`	Timestamp	no
`reason`	string	yes	Example: `Support team works in this space`.
`granted_by`	Uuid	yes
`granted_at`	Timestamp	yes
`revoked_at`	Timestamp	no
`revoked_by`	Uuid	no
`revoke_reason`	string	no

GrantCreate¶

level is required for every target except host, where it must be absent and capabilities must be exactly [terminal] (07, 2.12).

Property	Type	Required	Description
`subject_kind`	GrantSubjectKind	yes
`subject_id`	Uuid	yes
`target_kind`	TargetKind	yes
`target_id`	Uuid	no
`level`	Level	no
`capabilities`	array of Capability	no
`expires_at`	Timestamp	no
`reason`	string	yes	Example: `Support team works in this space`.
`resolve_i1`	ResolveI1	no

No other properties are allowed.

GrantPreview¶

Effect of a grant before it is created. No state changes (07, 9.3).

Property	Type	Required	Description
`allowed`	boolean	yes	False if a delegation limit of the caller (`denial_reason`) or an invariant would reject the grant.
`denial_reason`	string	no	Reason code of 07 section 4.1 when a delegation limit rejects the grant, for example `delegation_exceeds_own_level`. Example: `delegation_exceeds_own_level`.
`effects`	array of AccessEffect	yes
`invariant_violations`	array of InvariantViolation	yes
`hints`	array of PreviewHint	yes
`text`	string	yes	Plain text from templates in `text_locale`, lines separated by a line feed, no trailing line feed.
`text_locale`	string	yes	Values: `de`, `en`.

PreviewHint¶

terminal_not_effective (grant on a host, 07, 2.12 point 4) says that SR10 or SR12 keep the grant from taking effect: with principal_id for a user subject, with group_id and count (members in effect it does not reach, absent when 0) for a group subject.

Property	Type	Required	Description
`code`	string	yes	Values: `read_horizon`, `trigger_blocked_tool_class`, `group_reach`, `expiry_missing`, `terminal_not_effective`.
`agent_id`	Uuid	no
`principal_id`	Uuid	no
`group_id`	Uuid	no
`space_id`	Uuid	no
`channel_id`	Uuid	no
`count`	integer (int64)	no

AccessEffect¶

Property	Type	Required
`principal`	PrincipalRef	yes
`target_kind`	TargetKind	yes
`target_id`	Uuid	no
`before_level`	LevelOrNone	yes
`after_level`	LevelOrNone	yes
`capabilities_added`	array of Capability	yes

InvariantViolation¶

i1_violation names agent_id; i6_violation names host_id.

Property	Type	Required	Description
`code`	string	yes	Example: `i1_violation`.
`agent_id`	Uuid	no
`host_id`	Uuid	no
`credential_holder_id`	Uuid	no	Credential holder of the agent (`i1_violation`) or of the personal LLM login of the host (`i6_violation`); absent if the agent has none.
`principal_ids`	array of Uuid	yes	With `i1_violation` the principals that would gain `trigger` next to the credential holder; with `i6_violation` the people other than the holder that a valid grant on the host names, directly or as members in effect of a group grant (empty for a group without members).
`organization_ready`	boolean	no	True when the agent reports `organization` among its `billing_modes_supported`.
`hint`	string	no	Example: `Switch the agent to organization first`.

AccessExplanation¶

Property	Type	Required
`target_kind`	AccessTargetKind	yes
`target_id`	Uuid	yes
`entries`	array of AccessEntry	yes

AccessEntry¶

Property	Type	Required	Description
`principal`	PrincipalRef	yes
`level`	LevelOrNone	yes	`none` only for entries whose sources are all `via_agent`.
`inactive`	boolean	no	True when the principal is not `active`; the level is what its grants would give (07, 9.1).
`capabilities`	array of Capability	yes
`sources`	array of AccessSource	yes

AccessSource¶

Property	Type	Required	Description
`kind`	string	yes	Values: `owner`, `direct`, `group`, `inherited`, `dm_participant`, `operator`, `via_agent`, `guard_blocked`.
`grant_id`	Uuid	no
`group_id`	Uuid	no
`from_target_kind`	TargetKind	no
`from_target_id`	Uuid	no
`agent_id`	Uuid	no	Agent of an `operator`, `via_agent` or `guard_blocked` source.
`rule`	string	no	Guard rule of a `guard_blocked` source. Values: `sr2`, `sr3`.
`expires_at`	Timestamp	no	Expiry of the grant.
`membership_expires_at`	Timestamp	no
`reason`	string	no	Reason of the grant.

AccessTarget¶

Property	Type	Required
`kind`	AccessTargetKind	yes
`id`	Uuid	yes
`level`	Level	no
`previous_level`	Level	no
`capabilities`	array of Capability	no

Space¶

Property	Type	Required	Description
`id`	Uuid	yes
`name`	string	yes	Example: `Support`.
`icon`	string	no	Glyph name from the list `space-icons` of the design tokens (`kernel/designkeys`). No emoji. Example: `headset`.
`color`	string	no	Key of a category color of the design system, never a hex value. Example: `moss`.
`sort_key`	string	yes	Fractional index, compared bytewise. Example: `a0`.
`default_operator_agent_id`	Uuid	no
`archived_at`	Timestamp	no
`version`	integer (int64)	yes
`created_at`	Timestamp	yes

SpaceCreate¶

Property	Type	Required	Description
`name`	string	yes	At most `space.name_max_chars` characters. Min length 1. Example: `Research`.
`icon`	string	no	Glyph name from the list `space-icons` of the design tokens. Example: `flask`.
`color`	string	no	Key of a category color of the design system, never a hex value. Example: `heather`.
`after_space_id`	Uuid	no	Insert after this space; absent inserts at the end.

No other properties are allowed.

SpaceUpdate¶

Changes only the fields sent; icon and color cannot be cleared.

Property	Type	Required	Description
`name`	string	no	At most `space.name_max_chars` characters. Min length 1. Example: `Research`.
`icon`	string	no	Glyph name from the list `space-icons` of the design tokens.
`color`	string	no	Key of a category colour of the design system, never a hex value.

No other properties are allowed.

MovePosition¶

New position relative to siblings. Exactly one of both fields; none moves to the start.

Property	Type	Required	Description
`after_id`	Uuid	no
`before_id`	Uuid	no

No other properties are allowed.

OperatorSet¶

Operator assignment. inherit is only valid for channels.

Property	Type	Required	Description
`mode`	OperatorMode	yes
`agent_id`	Uuid	no	Required for mode `agent`.
`reason`	string	yes	Example: `Support agent takes over`.
`resolve_i1`	ResolveI1	no

No other properties are allowed.

SpaceView¶

Property	Type	Required	Description
`space`	Space	yes
`level`	Level	yes	Effective level on the space. A space visible only through one of its channels reports `read` and no capabilities.
`capabilities`	array of Capability	yes

ChannelKind¶

Type: string

Values: text, forum, dm.

ChannelOperator¶

Property	Type	Required	Description
`mode`	OperatorMode	yes
`agent_id`	Uuid	no
`effective_agent_id`	Uuid	no	Operator after resolving inheritance; absent means no operator.

Channel¶

Property	Type	Required	Description
`id`	Uuid	yes
`space_id`	Uuid	no	Absent for `dm`.
`kind`	ChannelKind	yes
`name`	string	yes	Example: `tickets`.
`topic`	string	yes	Example: `Customer tickets`.
`sort_key`	string	yes	Example: `a1`.
`operator`	ChannelOperator	yes
`forum_default_sort`	ForumSort	no
`default_notification_level`	NotificationLevel	no	Default for people without an own setting (13, 3.1); absent means none.
`read_only`	boolean	yes	Write-protected for every principal including owners; only a running import writes (05, rule 1.8).
`main_thread_id`	Uuid	no	Thread with `kind = main` of text and DM channels.
`dm_participant_ids`	array of Uuid	no
`archived_at`	Timestamp	no
`version`	integer (int64)	yes
`settings_version`	integer (int64)	yes
`created_at`	Timestamp	yes

ChannelCreate¶

Property	Type	Required	Description
`kind`	string	yes	Values: `text`, `forum`.
`name`	string	yes	Min length 1. Example: `tickets`.
`topic`	string	no	At most `channel.topic_max_chars` characters, no control or bidi characters.
`forum_default_sort`	ForumSort	no
`after_channel_id`	Uuid	no

No other properties are allowed.

ChannelUpdate¶

Property	Type	Required	Description
`name`	string	no	Min length 1. Example: `tickets`.
`topic`	string	no	At most `channel.topic_max_chars` characters, no control or bidi characters.
`forum_default_sort`	ForumSort	no
`default_notification_level`	NotificationLevel	no
`clear_default_notification_level`	boolean	no	Removes the channel default; there is no JSON null (R-API-03).

No other properties are allowed.

ChannelReadOnlySet¶

Property	Type	Required	Description
`read_only`	boolean	yes
`reason`	string	yes	Max length 500. Example: `Channel is mirrored from the old system`.

No other properties are allowed.

ChannelView¶

Property	Type	Required
`channel`	Channel	yes
`level`	Level	yes
`capabilities`	array of Capability	yes

ChannelBehavior¶

Behavior of the operator in a channel. Readable only with manage; never in events.

Property	Type	Required	Description
`require_mention`	boolean	yes
`thread_require_mention`	boolean	yes
`free_response`	boolean	yes
`auto_thread`	boolean	yes
`allow_mentioned_agents`	boolean	yes
`history_backfill_limit`	integer	yes	Example: `20`.
`prompt`	string	yes	Example: `Answer support tickets politely. Ask before closing a ticket.`.
`skills`	array of string	yes	Ordered skill references the adapter understands; the server does not interpret them.
`project_binding`	ProjectBinding	no
`settings_version`	integer (int64)	yes

ChannelBehaviorPut¶

Property	Type	Required	Description
`require_mention`	boolean	yes
`thread_require_mention`	boolean	yes
`free_response`	boolean	yes
`auto_thread`	boolean	yes
`allow_mentioned_agents`	boolean	yes
`history_backfill_limit`	integer	yes	Minimum 0. Example: `20`.
`prompt`	string	yes	Example: `Answer support tickets politely.`.
`skills`	array of string	yes

No other properties are allowed.

ProjectBinding¶

Property	Type	Required	Description
`workspace_ref`	string	yes	Opaque reference the runner resolves; never a server path. Example: `website`.
`repository_url`	string	no	Display only; the server never fetches this URL. Example: `https://git.example.com/team/website`.
`default_branch`	string	no	Example: `main`.
`runner_config`	ProjectRunnerConfig	yes
`ready`	boolean	yes
`version`	integer (int64)	yes

ProjectBindingPut¶

Property	Type	Required	Description
`workspace_ref`	string	yes	Example: `website`.
`repository_url`	string	no	Example: `https://git.example.com/team/website`.
`default_branch`	string	no	Example: `main`.
`runner_config`	ProjectRunnerConfig	no
`reason`	string	yes	Min length 1. Example: `Website project moves to this forum`.

No other properties are allowed.

ProjectRunnerConfig¶

Schema project_runner_config.v1. No secrets.

Property	Type	Required	Description
`model`	string	no	Min length 1.
`allowed_tools`	array of string	no	Unique items True.

No other properties are allowed.

AgentChannelConfig¶

Configuration an operator agent loads for a channel it serves.

Property	Type	Required
`channel_id`	Uuid	yes
`space_id`	Uuid	no
`behavior`	ChannelBehavior	yes

DmCreate¶

Property	Type	Required	Description
`participant_ids`	array of Uuid	yes	Other people in the conversation; the caller is added. Min items 1.

No other properties are allowed.

SidebarState¶

Property	Type	Required	Description
`space_id`	Uuid	yes
`collapsed`	boolean	yes
`sort_key`	string	no	Personal order; absent uses the global order. Example: `a0V`.
`version`	integer (int64)	yes
`updated_by_device_id`	Uuid	no

SidebarStatePut¶

Property	Type	Required	Description
`collapsed`	boolean	yes
`sort_key`	string	no
`use_global_order`	boolean	no	True removes the personal order. Replaces sending null.

No other properties are allowed.

SidebarStateList¶

Property	Type	Required	Description
`items`	array of SidebarState	yes

ForumTag¶

Property	Type	Required	Description
`id`	Uuid	yes
`channel_id`	Uuid	yes
`name`	string	yes	Example: `bug`.
`color`	string	no	Key of a category color of the design system, never a hex value. Example: `rowan`.
`sort_key`	string	yes	Example: `a0`.
`restricted`	boolean	yes

ForumTagCreate¶

Property	Type	Required	Description
`name`	string	yes	Example: `bug`.
`color`	string	no	Key of a category color of the design system, never a hex value. Example: `rowan`.
`restricted`	boolean	no
`after_tag_id`	Uuid	no

No other properties are allowed.

ForumTagUpdate¶

Property	Type	Required	Description
`name`	string	no	Example: `bug`.
`color`	string	no	Key of a category color of the design system, never a hex value.
`clear_color`	boolean	no	Removes the color; not together with `color`. There is no JSON null (R-API-03).
`restricted`	boolean	no

No other properties are allowed.

ForumTagList¶

Property	Type	Required	Description
`items`	array of ForumTag	yes

Thread¶

Property	Type	Required	Description
`id`	Uuid	yes
`channel_id`	Uuid	yes
`kind`	string	yes	Values: `main`, `thread`.
`parent_message_id`	Uuid	no
`title`	string	yes	Example: `Invoice export fails`.
`title_source`	string	yes	Values: `auto`, `manual`.
`state`	ThreadState	yes
`closed_at`	Timestamp	no
`closed_by`	Uuid	no
`operator_agent_id`	Uuid	no	Fixed operator of a thread of kind `thread` (R-DM-12). Absent for the main thread (`kind = main`, R-DM-21) and for threads without operator; clients then use `Channel.operator.effective_agent_id`.
`billing_mode`	BillingMode	no	Current policy of `operator_agent_id`, for the header badge; absent exactly when `operator_agent_id` is absent. Changes arrive with `agent.updated`.
`last_message_seq`	integer (int64)	yes
`unread_floor_seq`	integer (int64)	no	Messages up to this `thread_seq` never count as unread (import); absent means 0.
`last_activity_at`	Timestamp	yes
`message_count`	integer	yes
`created_by`	Uuid	yes
`created_at`	Timestamp	yes
`moved_at`	Timestamp	no
`version`	integer (int64)	yes
`tag_ids`	array of Uuid	yes

ThreadCreate¶

Creates a forum post (with title and first_message) or a thread from a message of the main thread (with parent_message_id, optional first_message). first_message.run_id is never valid, because a new thread has no run: 400 validation_failed with pointer /first_message/run_id and errors[].code run_mismatch.

Property	Type	Required	Description
`title`	string	no	Example: `Invoice export fails`.
`parent_message_id`	Uuid	no
`tag_ids`	array of Uuid	no	Forum posts only; at most `thread.max_tags`. Restricted tags need `manage`, as with `setThreadTags`.
`first_message`	MessageCreate	no

No other properties are allowed.

ThreadCreated¶

Property	Type	Required	Description
`thread`	Thread	yes
`first_message`	Message	no

ThreadTitlePut¶

Property	Type	Required	Description
`title`	string	yes	Min length 1. Example: `Invoice export fails for March`.

No other properties are allowed.

ThreadMove¶

Property	Type	Required	Description
`target_channel_id`	Uuid	yes
`reason`	string	yes	Example: `Belongs to billing`.

No other properties are allowed.

ThreadTagsPut¶

Property	Type	Required	Description
`tag_ids`	array of Uuid	yes	Complete set, at most `thread.max_tags`, without duplicates.

No other properties are allowed.

AgentSession¶

Property	Type	Required	Description
`id`	Uuid	yes
`thread_id`	Uuid	yes
`agent_id`	Uuid	yes
`external_session_ref`	string	no	Example: `sess-7f3a`.
`is_current`	boolean	yes
`started`	boolean	yes
`model`	string	no	Example: `model-large`.
`cost`	Money	yes
`created_at`	Timestamp	yes
`ended_at`	Timestamp	no
`end_reason`	string	no	Values: `reset`, `rebind`, `import`, `agent_changed`.
`cost_baseline_micros`	integer (int64)	no	The cumulative amount of the external session before it was bound to this row (`agent_sessions.cost_baseline_micros`, 22 9 step 7), in micro units of `currency`; present only when above 0. An adapter whose runtime reports cumulative session values books per run only the part above it (09, 18.7; RK-75). Example: `1250000`.
`currency`	string	no	ISO 4217 code of `cost_baseline_micros` (`agent_sessions.currency`); present exactly when `cost_baseline_micros` is. Example: `USD`.
`version`	integer (int64)	yes

AgentSessionList¶

Property	Type	Required	Description
`items`	array of AgentSession	yes

AgentSessionBind¶

Property	Type	Required	Description
`external_session_ref`	string	yes	Example: `sess-7f3a`.
`expected_current_session_id`	Uuid	no	Current session of the thread as the client saw it; absent when the thread has none. A mismatch answers 409 `conflict` with `reason` `session_changed` (09, 9.4).
`take_over`	boolean	no	Required when the session is current in another thread; otherwise 409 `conflict` with `reason` `session_bound_elsewhere`. Default: `false`.

No other properties are allowed.

AgentSessionReport¶

Property	Type	Required	Description
`external_session_ref`	string	yes	The reference the runtime actually uses; a different one replaces the stored reference of the session (09, 9.5 item 3). At most `agent.session_ref_max_bytes` bytes of display text. Example: `sess-7f3a`.
`model`	string	no	The pattern of `default_model` (09, 2.2), at most `agent.session_ref_max_bytes` bytes. Example: `model-large`.
`started`	boolean	no	`true` once the runtime confirmed the external session (09, 9.1); `started` only moves forward, `false` never resets it.
`bind_failed`	string	no	The bound session no longer exists in the runtime and the adapter started a new one (09, 9.5 item 4); only for a started session, otherwise 409 `conflict` with `reason` `session_not_bound`. Values: `session_missing`.

No other properties are allowed.

MessageKind¶

Type: string

Values: text, voice, run, card, system.

MessageOrigin¶

Type: string

Values: human, agent, app, import, system.

TriggerState¶

Type: string

Values: received, queued, working, done, failed, cancelled, followup_delivered.

Message¶

Property	Type	Required	Description
`id`	Uuid	yes
`thread_id`	Uuid	yes
`channel_id`	Uuid	yes
`thread_seq`	integer (int64)	yes	Example: `42`.
`author`	PrincipalRef	yes
`client_msg_id`	Uuid	yes
`origin`	MessageOrigin	yes
`kind`	MessageKind	yes
`system_code`	string	no	Set exactly for `kind = system`; clients render the localized line from it and `author`. `content_md` is empty then. `agent_session.resume_failed` is written once when the runtime no longer knew the bound session and the agent started a new one (09 9.5, 03 R-DM-42); its `author` is the run's agent. A system line never reopens a done thread. Values: `thread.reopened`, `agent_session.resume_failed`.
`content_md`	string	yes	Markdown. In lists longer contents are cut at `message.list_content_max_bytes` with `content_truncated`. Example: `@support-agent the invoice export fails since this morning.`.
`content_format`	integer	yes	Version of the Markdown dialect; `1` is CommonMark 0.31.2 without raw HTML, with mention tokens (03 `messages`). Example: `1`.
`content_truncated`	boolean	no	Set when `content_md` was cut (events above `sync.event_payload_max_bytes`, lists above `message.list_content_max_bytes`); `getMessage` returns the full content.
`reply_to_message_id`	Uuid	no
`run_id`	Uuid	no	Set only for `kind = run`: the run whose live box this anchor holds.
`trigger_state`	TriggerState	no
`trigger_state_at`	Timestamp	no
`trigger_state_reason`	string	no	Reason when `trigger_state` is `failed` or `cancelled`, e.g. `billing_mode_personal_not_holder`, `run_active_other_agent`, `user_cancelled`.
`silent`	boolean	yes
`attachments`	array of Attachment	yes	Attachments in position order (the order of `attachment_file_ids` at sending); empty for a message without attachments and for a deleted message.
`mention_ids`	array of Uuid	yes	Principals resolved from the mention tokens of `content_md`, sorted. Clients render a token as a mention only for these.
`reactions`	array of ReactionSummary	yes
`my_reactions`	array of string	no	Emoji the caller reacted with. Only in REST responses, never in events.
`pinned`	boolean	yes
`components`	array of Component	yes
`version`	integer (int64)	yes
`edited_at`	Timestamp	no
`deleted_at`	Timestamp	no
`created_at`	Timestamp	yes

MessageCreate¶

Property	Type	Required	Description
`client_msg_id`	Uuid	yes	UUIDv7 created by the client before the first attempt; unique per author forever.
`kind`	string	no	`voice` is a voice message (12, 8.1): exactly one entry in `attachment_file_ids` (none gives `400 validation_failed` with `errors[].code` `required`, more than one `limit_reached`, pointer `/attachment_file_ids`), an MP4 audio file (`audio/mp4`, `.m4a`) for every author and also MP3 (`audio/mpeg`) for agents, and the file must be ready. Another format, an MP4 with a video track or without a duration in `mvhd` give `400 validation_failed` with `errors[].code` `voice_format_unsupported`, a duration above `voice.max_duration` `voice_too_long`, both with the pointer of the entry (`/attachment_file_ids/0`); a file whose upload or scan has not ended gives `409 file_not_ready`, a blocked or failed file `409 file_blocked`. `content_md` may be empty. Values: `text`, `voice`, `card`.
`content_md`	string	no	Empty or white space only content is allowed only when `attachment_file_ids` lists at least one file (a picture without caption); otherwise `400 validation_failed` with `errors[].code` `empty`. Example: `@support-agent the invoice export fails since this morning.`.
`reply_to_message_id`	Uuid	no
`attachment_file_ids`	array of Uuid	no	Own files uploaded for the channel of this message with a completed upload session, in the order they appear in the message; at most `message.max_attachments`. Needs the right `upload` in addition to `write` (`403 forbidden` with `reason` `capability_missing`). A file that is not attachable (not the caller's, another channel, upload not completed or failed, deleted, already attached, or listed twice) answers `409 conflict` with `reason` `file_not_attachable` and the pointer of the entry in `detail`; more than `message.max_attachments` answer `400 validation_failed` with `errors[].code` `limit_reached`. Files whose scan has not ended are attachable.
`mention_ids`	array of Uuid	no	Optional check. The server resolves mentions from `content_md` (03 `messages`, content format; 07 section 4.6); when present, the set must equal the resolved set, else `400 validation_failed` with code `mention_mismatch`.
`silent`	boolean	no
`clear_draft`	boolean	no
`run_id`	Uuid	no	Agents only; the run this message belongs to. It must name an active run (`queued`, `running`, `waiting_input`) of the calling agent in this thread. Never stored on the message (`Message.run_id` stays absent). A person or app, an unknown run, a run of another thread or of another agent answer alike `400 validation_failed` with `errors[].code` `run_mismatch`; an ended own run answers `409 conflict` with `reason` `run_not_active`. With `kind = card` it also binds the components of the card to this run (`Component.run_id`, 09 11.4) and is part of the canonical request of `client_msg_id` (`bothy-msg-v2`); for every other kind it is not (09 4.7).
`components`	array of ComponentCreate	no	Requires `kind = card`, and `kind = card` requires at least one component; at most `component.max_per_message`. Agents and apps send cards (people get `invalid`). An app needs `write` and `messages:write` as for every message; without `components:write` its components stay inactive, and a use answers `409 component_used`. The whole `message.created` payload of the card must fit `sync.event_payload_max_bytes`, else `too_long` on `/components`. An agent whose owner switched `supports_components` off gets `403 feature_disabled` (09, 2.2 and 11.1); the switch does not apply to apps.

No other properties are allowed.

MessageUpdate¶

The server resolves the mentions of the resulting content again; mention_ids is an optional check as in MessageCreate.

Property	Type	Required	Description
`content_md`	string	no	Example: `@support-agent the invoice export fails since 08:00.`.
`mention_ids`	array of Uuid	no

No other properties are allowed.

MessagePage¶

Messages in ascending thread_seq. Tombstones are included.

Property	Type	Required
`items`	array of Message	yes
`has_more_before`	boolean	yes
`has_more_after`	boolean	yes

MessageRevision¶

Property	Type	Required	Description
`revision`	integer	yes	Example: `1`.
`content_md`	string	yes	Example: `@support-agent the invoice export fails.`.
`edited_by`	Uuid	yes
`created_at`	Timestamp	yes

MessageRevisionList¶

Property	Type	Required	Description
`items`	array of MessageRevision	yes

Property	Type	Required	Description
`emoji`	string	yes	Exactly one Unicode grapheme cluster. Example: `👍`.
`count`	integer	yes	Example: `3`.

Reaction¶

Property	Type	Required	Description
`emoji`	string	yes	Example: `👍`.
`principal`	PrincipalRef	yes
`created_at`	Timestamp	yes

Pin¶

Property	Type	Required
`message_id`	Uuid	yes
`thread_id`	Uuid	yes
`pinned_by`	Uuid	yes
`pinned_at`	Timestamp	yes

MentionItem¶

Property	Type	Required	Description
`message`	Message	yes
`created_at`	Timestamp	yes

Template¶

Property	Type	Required	Description
`id`	Uuid	yes
`scope`	string	yes	Values: `personal`, `channel`.
`channel_id`	Uuid	no
`name`	string	yes	Example: `Escalation`.
`content_md`	string	yes	Example: `Please escalate this ticket to second level.`.
`version`	integer (int64)	yes

TemplateCreate¶

Property	Type	Required	Description
`name`	string	yes	Example: `Escalation`.
`content_md`	string	yes	Example: `Please escalate this ticket to second level.`.

No other properties are allowed.

TemplateUpdate¶

Property	Type	Required	Description
`name`	string	no
`content_md`	string	no

No other properties are allowed.

TemplateList¶

Property	Type	Required	Description
`items`	array of Template	yes

Attachment¶

Property	Type	Required	Description
`position`	integer	yes
`file`	File	yes

File¶

Property	Type	Required	Description
`id`	Uuid	yes
`sha256`	string	no	Hex SHA-256 of the stored bytes. Example: `9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08`.
`size_bytes`	integer (int64)	yes	Example: `48213`.
`mime_type`	string	yes	Detected by the server. Example: `image/png`.
`original_name`	string	yes	Example: `screenshot.png`.
`uploaded_by`	Uuid	yes
`purpose`	string	yes	Values: `attachment`, `avatar`, `branding`, `gdpr_export`.
`scope_channel_id`	Uuid	no	Channel the file was uploaded for; present only before the file is attached to a message. An attached file is read through the channel of its message.
`upload_state`	string	yes	Values: `pending`, `complete`, `failed`. Example: `complete`.
`scan_status`	string	yes	Values: `pending`, `clean`, `infected`, `error`, `skipped`. Example: `clean`.
`width`	integer	no
`height`	integer	no
`duration_ms`	integer (int64)	no
`transcript_status`	TranscriptStatus	yes
`transcript_language`	string	no
`transcript_source`	TranscriptSource	no
`thumbnails`	array of Thumbnail	yes
`created_at`	Timestamp	yes

Thumbnail¶

Property	Type	Required	Description
`variant`	string	yes	Values: `small`, `medium`, `large`, `poster`.
`mime_type`	string	yes	Example: `image/jpeg`.
`width`	integer	yes	Example: `320`.
`height`	integer	yes	Example: `180`.

UploadCreate¶

Property	Type	Required	Description
`name`	string	yes	Example: `screenshot.png`.
`size_bytes`	integer (int64)	yes	Minimum 1. Example: `48213`.
`declared_mime_type`	string	no	Example: `image/png`.
`sha256`	string	yes	Lowercase hex SHA-256 of the whole file; the verify pass checks it. Pattern `^[0-9a-f]{64}$`.

No other properties are allowed.

UploadSession¶

Upload plan. In mode direct the part URLs point to this server; in mode presigned they point to the object store. The client uploads all parts, then calls complete.

Property	Type	Required	Description
`file_id`	Uuid	yes
`mode`	string	yes	Values: `direct`, `presigned`.
`part_size_bytes`	integer (int64)	yes
`parts`	array of UploadPart	yes
`expires_at`	Timestamp	yes

UploadState¶

State of an own upload session, for resuming after a network loss.

Property	Type	Required	Description
`file_id`	Uuid	yes
`upload_state`	string	yes	Values: `pending`, `uploading`, `complete`.
`part_size_bytes`	integer (int64)	yes
`completed_parts`	array of object	yes	Parts the server has confirmed, with their ETag.
`completed_parts[].part_number`	integer	yes	Minimum 1.
`completed_parts[].etag`	string	yes	Example: `"9b2cf535f27731c974343645a3985328"`.
`expires_at`	Timestamp	yes

FileTicketCreate¶

Property	Type	Required	Description
`variant`	string	yes	Values: `original`, `small`, `medium`, `large`, `poster`.

No other properties are allowed.

FileTicket¶

Short-lived fetch URL for media players without DPoP (12, 9.2). Checked again on every fetch.

Property	Type	Required	Description
`url`	string (uri-reference)	yes	Example: `/api/v1/files/0192f4a0-7b1c-75c7-88f6-199cc394b56a/content?ticket=c2lnbmVk`.
`expires_at`	Timestamp	yes

UploadPart¶

Property	Type	Required	Description
`part_number`	integer	yes	Minimum 1.
`url`	string (uri-reference)	yes	Example: `/api/v1/uploads/0192f4a0-7b1c-7000-8a00-000000000501/parts/1`.
`headers`	array of HeaderPair	yes	Headers the client must send with the PUT.

HeaderPair¶

Property	Type	Required	Description
`name`	string	yes	Example: `Content-Type`.
`value`	string	yes	Example: `application/octet-stream`.

UploadPartResult¶

Property	Type	Required	Description
`part_number`	integer	yes
`etag`	string	yes	Example: `"3858f62230ac3c915f300c664312c11f"`.

No other properties are allowed.

UploadComplete¶

Property	Type	Required	Description
`parts`	array of UploadPartResult	yes

No other properties are allowed.

TranscriptSubmit¶

Property	Type	Required	Description
`text`	string	yes	The transcript; may be empty (a silent recording), must not contain U+0000 and is at most `message.max_content_bytes` UTF-8 bytes. Example: `Please call the customer back tomorrow morning.`.
`language`	string	no	Optional BCP 47 tag of the spoken language, a primary subtag of two or three letters followed by subtags of two to eight letters or digits. Pattern `^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$`. Example: `en`.

No other properties are allowed.

Transcript¶

Property	Type	Required	Description
`file_id`	Uuid	yes
`status`	TranscriptStatus	yes
`text`	string	no	Example: `Please call the customer back tomorrow morning.`.
`language`	string	no	Example: `en`.
`source`	TranscriptSource	no

SearchHit¶

One hit. kind names which of the optional objects is set.

Property	Type	Required	Description
`kind`	SearchHitKind	yes
`score`	number (double)	no	Only with `sort = relevance`.
`message`	Message	no
`thread`	Thread	no
`file`	File	no
`thread_title`	string	no
`channel_name`	string	no
`space_name`	string	no
`segments`	array of object	yes	Excerpt split at the matches; no markup, HTML in the content stays text (14, 4.6).
`segments[].text`	string	yes
`segments[].match`	boolean	yes

ReadState¶

Property	Type	Required	Description
`thread_id`	Uuid	yes
`channel_id`	Uuid	yes
`last_read_seq`	integer (int64)	yes	Example: `41`.
`mention_count`	integer	yes	Unread mentions of the caller in this thread, computed when the response or event is built (03 `read_states`); never stored.
`version`	integer (int64)	yes
`updated_by_device_id`	Uuid	no
`updated_at`	Timestamp	no

ReadStatePut¶

Advances the read position. The server keeps the maximum of old and new.

Property	Type	Required	Description
`last_read_seq`	integer (int64)	yes	Minimum 0. Example: `42`.

No other properties are allowed.

ReadStateList¶

Property	Type	Required	Description
`items`	array of ReadState	yes

Draft¶

Property	Type	Required	Description
`id`	Uuid	yes
`thread_id`	Uuid	no
`channel_id`	Uuid	yes
`content_md`	string	yes	Example: `Draft of a reply`.
`reply_to_message_id`	Uuid	no
`file_ids`	array of Uuid	yes
`version`	integer (int64)	yes
`updated_by_device_id`	Uuid	no
`updated_at`	Timestamp	no

DraftPut¶

Property	Type	Required	Description
`content_md`	string	yes	Example: `Draft of a reply`.
`reply_to_message_id`	Uuid	no
`file_ids`	array of Uuid	no
`base_version`	integer (int64)	no	Version the client edited; older than current sets `overwrote_newer`.

No other properties are allowed.

DraftPutResult¶

Property	Type	Required	Description
`draft`	Draft	yes
`overwrote_newer`	boolean	yes

DraftList¶

Property	Type	Required	Description
`items`	array of Draft	yes

UserSetting¶

Property	Type	Required	Description
`key`	string	yes	Example: `composer.enter_sends`.
`value`	JsonValue	yes
`version`	integer (int64)	yes
`updated_by_device_id`	Uuid	no
`updated_at`	Timestamp	no

UserSettingPut¶

Property	Type	Required	Description
`value`	JsonValue	yes

No other properties are allowed.

UserSettingList¶

Property	Type	Required	Description
`items`	array of UserSetting	yes

NotificationLevel¶

Type: string

Values: all, mentions, mute.

NotificationPreference¶

Property	Type	Required	Description
`target_kind`	string	yes	Values: `space`, `channel`, `thread`.
`target_id`	Uuid	yes
`level`	NotificationLevel	yes
`muted_until`	Timestamp	no
`version`	integer (int64)	yes

NotificationPreferencePut¶

Property	Type	Required	Description
`level`	NotificationLevel	yes
`muted_until`	Timestamp	no

No other properties are allowed.

NotificationPreferenceList¶

Property	Type	Required	Description
`items`	array of NotificationPreference	yes

QuietHoursRule¶

Property	Type	Required	Description
`id`	Uuid	yes
`weekdays`	integer	yes	Bit mask, bit 0 = Monday. Minimum 1; maximum 127. Example: `31`.
`start_local`	string	yes	Local time `HH:MM`. Pattern `^([01][0-9]\|2[0-3]):[0-5][0-9]$`. Example: `22:00`.
`end_local`	string	yes	Pattern `^([01][0-9]\|2[0-3]):[0-5][0-9]$`. Example: `07:00`.
`time_zone`	string	no	IANA time zone name; absent means the person's time zone (users.time_zone). Example: `Europe/Berlin`.
`enabled`	boolean	yes
`version`	integer (int64)	yes

QuietHoursRuleInput¶

Property	Type	Required	Description
`weekdays`	integer	yes	Minimum 1; maximum 127. Example: `31`.
`start_local`	string	yes	Pattern `^([01][0-9]\|2[0-3]):[0-5][0-9]$`. Example: `22:00`.
`end_local`	string	yes	Pattern `^([01][0-9]\|2[0-3]):[0-5][0-9]$`. Example: `07:00`.
`time_zone`	string	no	IANA time zone name; absent means the person's time zone (users.time_zone). Example: `Europe/Berlin`.
`enabled`	boolean	yes

No other properties are allowed.

QuietHoursList¶

Property	Type	Required	Description
`items`	array of QuietHoursRule	yes

PushRegistration¶

Property	Type	Required	Description
`id`	Uuid	yes
`device_id`	Uuid	yes
`provider`	PushProvider	yes
`environment`	PushEnvironment	yes
`app_id`	string	yes	Example: `com.example.teamchat`.
`created_at`	Timestamp	yes
`disabled_at`	Timestamp	no
`disabled_reason`	string	no

PushRegistrationCreate¶

Property	Type	Required	Description
`provider`	PushProvider	yes
`token`	string	yes	Push token of the provider, at most `push.registration_field_max_bytes` bytes (`too_long` at `/token`). Never returned. An `apns` token is an even number of hexadecimal digits and is stored in lower case; an `fcm` token is printable ASCII without white space; otherwise `pattern_mismatch` at `/token`. Example: `EXAMPLE-device-token-a1b2`.
`environment`	PushEnvironment	no
`app_id`	string	yes	Bundle ID or package of the app, at most `push.registration_field_max_bytes` bytes (`too_long` at `/app_id`). For `apns` it must be one of `push.apns.topics` (`invalid` at `/app_id`). `apns` needs a device with platform `ios` or `macos`, `fcm` one with `android` (`invalid` at `/provider`); `sandbox` exists only for `apns` (`invalid` at `/environment`); an absent `environment` is `production`. Example: `com.example.teamchat`.

No other properties are allowed.

PushRegistrationCreated¶

A new push registration with its preview token, which is shown exactly once and never again (13, 6.4).

All of: PushRegistration

Property	Type	Required	Description
`preview_token`	string	yes	Preview token of the registration (`bothy_pvw_...`), shown exactly once. The app keeps it in the store it shares with its notification extension. Example: `bothy_pvw_EXAMPLEpushpreviewtoken00000000000000000000_4Z1L0A`.

UnreadThread¶

Property	Type	Required
`thread_id`	Uuid	yes
`channel_id`	Uuid	yes
`unread_count`	integer	yes
`mention_count`	integer	yes
`last_message_seq`	integer (int64)	yes
`last_read_seq`	integer (int64)	yes

DraftRef¶

Property	Type	Required
`id`	Uuid	yes
`thread_id`	Uuid	no
`channel_id`	Uuid	yes
`version`	integer (int64)	yes

AgentPresence¶

Property	Type	Required
`agent_id`	Uuid	yes
`state`	AgentRuntimeState	yes
`reported_billing_mode`	BillingMode	no

Snapshot¶

State without thread contents, delivered by ready and GET /sync/snapshot.

Property	Type	Required	Description
`head_seq`	integer (int64)	yes	Example: `5300`.
`permission_version`	integer (int64)	yes	Example: `418`.
`sync_epoch`	Uuid	yes	Time line of the event log (04, 7.5).
`principal`	PrincipalRef	yes
`is_owner`	boolean	yes
`spaces`	array of SpaceView	yes
`channels`	array of ChannelView	yes
`sidebar`	array of SidebarState	yes
`unread_threads`	array of UnreadThread	yes	Only threads with unread messages or mentions.
`active_runs`	array of RunSummary	yes
`agents`	array of AgentPresence	yes
`settings`	array of UserSetting	yes
`drafts`	array of DraftRef	yes
`features`	array of EvaluatedFlag	yes	Feature flags evaluated for the principal, as in `InstanceInfo.features` (04 section 6.3, step 4).

Agent¶

Property	Type	Required	Description
`id`	Uuid	yes
`handle`	string	yes	Example: `support-agent`.
`display_name`	string	yes	Example: `Support Agent`.
`avatar_file_id`	Uuid	no
`status`	string	yes	Values: `active`, `disabled`, `deleted`.
`adapter_kind`	string	yes	Example: `hermes`.
`description`	string	yes	Example: `Answers support tickets`.
`billing_mode`	BillingMode	yes
`credential_holder_id`	Uuid	no
`billing_mode_changed_at`	Timestamp	no
`tool_class`	ToolClass	yes
`presence`	AgentRuntimeStatus	yes
`operator_config`	JsonObject	yes	Schema `agent_operator_config.v1`. No secrets.
`version`	integer (int64)	yes

AgentRuntimeStatus¶

Reported state of the agent runtime (heartbeat), not the configured state.

Property	Type	Required	Description
`state`	AgentRuntimeState	yes
`reported_billing_mode`	BillingMode	no
`runtime_version`	string	no	Example: `2.3.1`.
`last_heartbeat_at`	Timestamp	no
`billing_modes_supported`	array of BillingMode	no
`reported_tool_class`	ToolClass	no
`billing_mode_matches`	boolean	no	False when the reported mode differs from the configured `billing_mode`.
`rate_limit`	AgentRateLimitState	no
`billing_evidence`	BillingEvidence	no
`warnings`	array of string	no	Known values `billing_mode_mismatch` (the reported mode has differed from the configured one for longer than `billing.mismatch_alert_after`), `billing_mode_unsupported` (no reported mode and the configured one is not in `billing_modes_supported`), `billing_evidence_unknown` (`billing_evidence.key_type` is `unknown`) and `tool_class_mismatch` (the reported tool class differs from the configured one). Only while the state is `online` or `degraded`.

AgentCreate¶

Property	Type	Required	Description
`handle`	string	yes	Pattern `^[a-z0-9][a-z0-9._-]*$`. Example: `support-agent`.
`display_name`	string	yes	Example: `Support Agent`.
`adapter_kind`	string	yes	Example: `hermes`.
`description`	string	no	Example: `Answers support tickets`.
`operator_config`	JsonObject	no

No other properties are allowed.

AgentUpdate¶

Property	Type	Required	Description
`display_name`	string	no	Example: `Support Agent`.
`description`	string	no
`operator_config`	JsonObject	no

No other properties are allowed.

BillingModeSet¶

Property	Type	Required	Description
`billing_mode`	BillingMode	yes
`credential_holder_id`	Uuid	no	Required for `personal`.
`reason`	string	yes	Min length 1. Example: `Team uses the agent now`.

No other properties are allowed.

BillingModeSetAll¶

Switches several agents in one transaction, all or nothing (10, 9.1).

Property	Type	Required	Description
`billing_mode`	BillingMode	yes
`credential_holder_id`	Uuid	no	Required for `personal`.
`agent_ids`	array of Uuid	no	Required for `personal`. Without it `organization` affects every agent not yet on `organization`.
`reason`	string	yes	Min length 1. Example: `Switch all agents to the company key`.

No other properties are allowed.

BillingModeSetAllResult¶

Property	Type	Required	Description
`changed_agent_ids`	array of Uuid	yes

CredentialHolderSet¶

Property	Type	Required	Description
`credential_holder_id`	Uuid	yes
`reason`	string	yes	Min length 1. Example: `Handover to deputy`.

No other properties are allowed.

Heartbeat¶

Property	Type	Required	Description
`state`	string	yes	Values: `online`, `degraded`.
`runtime_version`	string	no	Version of the agent runtime (column `reported_runtime_version`); the adapter's own version is `details.adapter.version`. Pattern `^[0-9A-Za-z][0-9A-Za-z.+_-]*$`. Example: `2.3.1`.
`reported_billing_mode`	BillingMode	no	Absent when the adapter follows the configured mode per run; then `billing_modes_supported` names both modes and the per-run check binds (ruling L8).
`billing_modes_supported`	array of BillingMode	no
`billing_evidence`	BillingEvidence	no
`reported_tool_class`	ToolClass	no
`rate_limit`	AgentRateLimitState	no	Stored in `agents.reported_details.rate_limit` as exactly `state` and `resets_at`; absent clears a stored one, because every heartbeat is the full reported state. Shown by `getStatsBackends`.
`details`	JsonObject	no	Further fields of schema `agent_heartbeat.v1`, a closed object; any other key, also inside `capabilities`, `adapter` and `runtime`, is refused. Keys: `capabilities` (object: `followups` `steer` or `queue`; `components`, `voice_input`, `title`, `files_out` booleans), `active_runs` (distinct run ids), `degraded_reasons` (distinct codes), `adapter` (`name` required, `version` optional), `runtime` (`name` required), `protocol_version` (integer, at least 1). Names match `^[a-z0-9][a-z0-9._-]$`, versions `^[0-9A-Za-z][0-9A-Za-z.+_-]$`, codes `^[a-z0-9][a-z0-9_.:-]*$`. No secrets, no content, no paths.
`project_readiness`	array of ProjectReadiness	no	Readiness per bound forum of a runner (M2-03); the channels must be distinct. Applied only when present and different from the last list this server process applied; absent means "unchanged".

No other properties are allowed.

ProjectReadiness¶

Property	Type	Required	Description
`channel_id`	Uuid	yes
`ready`	boolean	yes

No other properties are allowed.

HeartbeatAck¶

Property	Type	Required	Description
`presence`	AgentRuntimeStatus	yes
`interval_ms`	integer (int64)	yes	Interval the adapter should keep, `sync.heartbeat_interval`.

ConsumerAck¶

Property	Type	Required	Description
`seq`	integer (int64)	yes	Minimum 0. Example: `5301`.

No other properties are allowed.

ConsumerState¶

Property	Type	Required	Description
`consumer`	string	yes	Example: `default`.
`acked_seq`	integer (int64)	yes
`head_seq`	integer (int64)	yes

RunState¶

Type: string

Values: queued, running, waiting_input, completed, failed, cancelled.

RunMetrics¶

Schema run_metrics.v1.

Property	Type	Required	Description
`context_pct`	number (double)	no	Example: `37.5`.
`tokens_in`	integer (int64)	no
`tokens_out`	integer (int64)	no
`tokens_cache_read`	integer (int64)	no
`tokens_cache_write`	integer (int64)	no	Cache writes with 5 minutes (or without a stated duration).
`tokens_cache_write_1h`	integer (int64)	no	Cache writes with 1 hour, counted separately.
`subagents`	integer	no
`background_jobs`	integer	no
`api_retries`	integer	no
`progress_events`	integer	no	Count of progress messages of the runtime in the current turn that changed nothing visible (for example a long running tool); a patch of it counts as progress against `run.stall_after` (09 5.5, 18.4).
`last_api_retry`	RunApiRetry	no

No other properties are allowed.

RunApiRetry¶

Last retry of a model API call, shown in the live box while set.

Property	Type	Required	Description
`attempt`	integer	yes	Example: `2`.
`max_retries`	integer	no	Example: `5`.
`retry_delay_ms`	integer (int64)	no	Example: `4000`.
`error`	string	no	Example: `overloaded`.

No other properties are allowed.

RunPlan¶

Schema run_plan.v1, shown in the live box.

Property	Type	Required	Description
`items`	array of object	yes
`items[].id`	string	yes	Example: `step-1`.
`items[].text`	string	yes	Example: `Reproduce the export error`.
`items[].status`	string	yes	Values: `pending`, `in_progress`, `completed`.

RunContext¶

Context of an own active run, schema run_context.v1 (09, 4.6). Built by the server because only authz knows how trustworthy each author is.

Property	Type	Required	Description
`run_id`	Uuid	yes
`trigger_message`	RunContextMessage	yes
`thread_context`	array of RunContextMessage	yes
`channel_context`	array of RunContextMessage	no	Main-thread messages before the parent message of the thread, without the parent message itself. Present (possibly empty) exactly on a run in session mode `new` or `bind` and on a guest run, in a thread with `parent_message_id` whose parent message lies in the thread's current channel; absent otherwise, also after the thread was moved to another channel.
`context_floor_seq`	integer (int64)	yes
`truncated_before_seq`	integer (int64)	no	Refers to the run's thread. Set when older selectable messages of `thread_context` are missing (the `history_backfill_limit` window or the byte budget left them out); then it is the `thread_seq` of the oldest element of `thread_context`, or of the triggering message when `thread_context` is empty. Load older messages with `thread.read`.

RunContextMessage¶

Property	Type	Required	Description
`message_id`	Uuid	yes
`thread_seq`	integer (int64)	yes
`created_at`	Timestamp	yes
`author`	PrincipalRef	yes
`role`	string	yes	Values: `user`, `assistant`, `other`.
`origin`	MessageOrigin	yes
`kind`	MessageKind	yes
`channel_id`	Uuid	yes	Channel of the message (SEC-AI-1).
`content_md`	string	yes
`truncated`	boolean	no	Present and true only when `content_md` was cut at `agent.context_message_max_bytes` on a UTF-8 boundary; never on `trigger_message`.
`attachments`	array of RunContextAttachment	yes
`reply_to_message_id`	Uuid	no
`trust`	string	yes	How the runtime must treat the content; `unverified` only as marked data, never as instruction. Values: `trigger`, `authorized`, `self`, `unverified`, `system`.
`already_delivered`	boolean	no	Present and true only in session mode `resume` for a message already delivered to this session as a follow-up (`run_followups` in `delivered` or `absorbed`).

RunContextAttachment¶

Property	Type	Required	Description
`file_id`	Uuid	yes
`original_name`	string	yes	Example: `screenshot.png`.
`mime_type`	string	yes	Example: `image/png`.
`size_bytes`	integer (int64)	yes
`scan_status`	string	yes	Example: `clean`.
`transcript`	string	no

AgentTriggerers¶

Principals that may trigger the calling agent (allow list of the adapter).

Property	Type	Required	Description
`principal_ids`	array of Uuid	yes
`permission_version`	integer (int64)	yes	Example: `418`.

RunSummary¶

Summary for sidebars, "running now" and collapsed live boxes.

Property	Type	Required	Description
`id`	Uuid	yes
`thread_id`	Uuid	yes
`channel_id`	Uuid	yes
`agent_id`	Uuid	yes
`triggered_by`	Uuid	yes
`state`	RunState	yes
`state_reason`	string	no	Example: `user_cancelled`.
`version`	integer (int64)	yes
`billing_mode_expected`	BillingMode	yes
`billing_mode_used`	BillingMode	no
`status_line`	string	no	Example: `Reading the export logs`.
`summary`	string	no	Example: `Found the cause and proposed a fix`.
`cost`	Money	yes
`step_count`	integer	yes
`duration_ms`	integer (int64)	no
`queued_at`	Timestamp	yes
`started_at`	Timestamp	no
`finished_at`	Timestamp	no
`stall_warned_at`	Timestamp	no	Set by `runs.stall_check` when a `running` run made no progress for `run.stall_after` (notice "no movement since ..."); the next stored patch clears it (09 5.5).

Run¶

Run document (run_document.v1), the content of the live box.

Property	Type	Required	Description
`id`	Uuid	yes
`thread_id`	Uuid	yes
`channel_id`	Uuid	yes
`agent_id`	Uuid	yes
`agent_session_id`	Uuid	no
`trigger_kind`	string	no	Values: `message`, `command`, `interaction`.
`triggering_message_id`	Uuid	no
`triggering_command_id`	Uuid	no
`triggering_interaction_id`	Uuid	no
`triggered_by`	Uuid	yes
`state`	RunState	yes
`state_reason`	string	no
`version`	integer (int64)	yes
`billing_mode_expected`	BillingMode	yes
`billing_mode_used`	BillingMode	no
`model`	string	no	Example: `model-large`.
`status_line`	string	no	Example: `Reading the export logs`.
`last_text_excerpt`	string	no
`metrics`	RunMetrics	yes
`cost`	Money	yes
`summary`	string	no
`steps`	map of RunStep	yes	Steps keyed by step ID; order comes from `ordinal`.
`followups`	map of RunFollowup	yes	Follow-ups keyed by message ID.
`queued_at`	Timestamp	yes
`started_at`	Timestamp	no
`finished_at`	Timestamp	no
`duration_ms`	integer (int64)	no
`plan`	RunPlan	no
`stall_warned_at`	Timestamp	no	Set by `runs.stall_check` when a `running` run made no progress for `run.stall_after` (notice "no movement since ..."); the next stored patch clears it (09 5.5).

RunStep¶

Property	Type	Required	Description
`id`	Uuid	yes
`ordinal`	integer	yes
`parent_step_id`	Uuid	no
`kind`	string	yes	Values: `tool_call`, `status`, `subagent`, `workflow`, `background_job`.
`name`	string	yes	Example: `read_file`.
`title`	string	yes	Example: `Reading export.log`.
`status`	string	yes	Values: `pending`, `running`, `completed`, `failed`, `cancelled`.
`detail`	JsonObject	no	Schema `run_step_detail.v1`, cut to `run.step_detail_max_bytes`. A step of kind `subagent`, `workflow` or `background_job` may carry the member `usage` (object with the optional integers `tokens`, `tool_uses`, `duration_ms`, `cost_micros` and the text `currency`, required with `cost_micros`), reported by the adapter for display only, never a booking (09 5.6).
`started_at`	Timestamp	yes
`finished_at`	Timestamp	no

RunStepPage¶

Property	Type	Required	Description
`items`	array of RunStep	yes
`next_cursor`	Cursor	no

RunFollowup¶

Property	Type	Required	Description
`message_id`	Uuid	yes
`state`	string	yes	Values: `queued`, `delivered`, `absorbed`, `deferred`, `discarded`.

RunPatch¶

Property	Type	Required	Description
`base_version`	integer (int64)	yes	Example: `7`.
`ops`	array of JsonPatchOperation	yes	Min items 1.

No other properties are allowed.

RunPatchResult¶

Property	Type	Required	Description
`version`	integer (int64)	yes	Example: `8`.

RunStart¶

Property	Type	Required	Description
`invocation_token`	string	yes	JWS from the delivered invocation (I3). Example: `eyJhbGciOiJFZERTQSIsImtpZCI6Imludi0yMDI2LTEwIn0.e30.sig`.
`billing_mode_used`	BillingMode	yes
`tool_class_used`	ToolClass	yes
`external_session_ref`	string	no	Absent when the runtime creates the reference only during the run; then the first `reportAgentSession` creates the session row. Example: `sess-7f3a`.
`model`	string	no	Example: `model-large`.
`billing_evidence`	BillingEvidence	no

No other properties are allowed.

InvocationTokenRenew¶

Property	Type	Required	Description
`invocation_token`	string	yes	The current invocation token of the run, or on a retry after a lost answer the token the last renewal replaced; it may have expired (09 section 4.5.1). Example: `eyJhbGciOiJFZERTQSIsImtpZCI6Imludi0yMDI2LTEwIn0.e30.sig`.

No other properties are allowed.

InvocationTokenGrant¶

Property	Type	Required	Description
`invocation_token`	string	yes	Fresh invocation token with a new `jti`; it replaces the current one of the run. Example: `eyJhbGciOiJFZERTQSIsImtpZCI6Imludi0yMDI2LTEwIn0.e30.signature`.
`expires_at`	string (date-time)	yes	Example: `2026-10-10T09:31:00.000Z`.

RunAwaitInput¶

Property	Type	Required	Description
`status_line`	string	yes	Example: `Waiting for approval`.

No other properties are allowed.

RunFinish¶

Property	Type	Required	Description
`state`	string	yes	Values: `completed`, `failed`, `cancelled`.
`reason`	string	no	Required for `failed` and `cancelled`, e.g. `billing_mode_mismatch`, `adapter_error`, `user_cancelled`. Example: `adapter_error`.
`summary`	string	no	Example: `Found the cause and proposed a fix`.
`metrics`	RunMetrics	no
`costs`	array of CostReport	no	The consumption of this run, one report per model (a second report of the same provider and model is invalid). The server books one cost entry per report at the end of the run (10, 12.1); a repeated finish books nothing. Only a run that started (`billing_mode_used` set) may report costs.

No other properties are allowed.

CostReport¶

Cost of one model in this run as reported by the adapter: the consumption of this run, never a session sum; stored as estimate. The server computes the amount from the price table when the price set of provider, model and the end of the run covers every consumed unit (source computed, the adapter amount is ignored), otherwise it books amount_micros (source adapter_reported), otherwise 0 (source unpriced, "Price missing"). Token counts and amount_micros are not negative and below 2^53; absent token counts are 0.

Property	Type	Required	Description
`provider`	string	yes	Example: `anthropic`.
`model`	string	yes	Example: `model-large`.
`tokens_in`	integer (int64)	no
`tokens_out`	integer (int64)	no
`tokens_cache_read`	integer (int64)	no
`tokens_cache_write`	integer (int64)	no	Cache writes with 5 minutes (or without a stated duration).
`tokens_cache_write_1h`	integer (int64)	no	Cache writes with 1 hour, priced with `cache_write_1h_mtok`.
`amount_micros`	integer (int64)	no	Absent lets the server compute from the price table.
`currency`	string	yes	ISO 4217 code. Example: `USD`.

No other properties are allowed.

RunCancel¶

Property	Type	Required	Description
`reason`	string	no	Example: `Wrong ticket`.

No other properties are allowed.

CostBreakdown¶

Property	Type	Required	Description
`thread_id`	Uuid	yes
`totals`	array of CostTotal	yes	Valid sums per billing mode and currency, never converted; sums of mode `personal` only when `billing.show_personal_estimates` is on.
`runs`	array of RunCost	yes	Runs of the thread with at least one valid cost entry, by `run_id` ascending.

CostTotal¶

Property	Type	Required	Description
`billing_mode`	BillingMode	yes
`amount_micros`	integer (int64)	yes
`currency`	string	yes	ISO 4217 code. Example: `USD`.
`is_estimate`	boolean	yes	True while any summed entry is an estimate.

RunCost¶

Property	Type	Required	Description
`run_id`	Uuid	yes
`billing_mode`	BillingMode	yes
`agent_session_id`	Uuid	no
`tokens`	TokenCounts	yes
`costs`	array of Money	no	One amount per currency; absent when amounts are hidden (mode `personal` without `billing.show_personal_estimates`).
`unpriced`	boolean	yes	A valid entry of the run has neither a price nor an amount of the adapter ("Price missing").

TokenCounts¶

Property	Type	Required
`tokens_in`	integer (int64)	yes
`tokens_out`	integer (int64)	yes
`tokens_cache_read`	integer (int64)	yes
`tokens_cache_write`	integer (int64)	yes
`tokens_cache_write_1h`	integer (int64)	yes

Component¶

Property	Type	Required	Description
`id`	Uuid	yes
`custom_id`	string	yes	Example: `approve-refund`.
`type`	ComponentType	yes
`definition`	JsonObject	yes	Schema `component.v1` (09, 11.1) as stored, with the defaults applied (button `style`, select `min_values` and `max_values`, field `required`).
`position`	integer	yes
`single_use`	boolean	yes
`required_capability`	Capability	no
`restricted_to`	ComponentRestriction	yes
`run_id`	Uuid	no
`state`	string	yes	Values: `active`, `used`, `expired`, `disabled`.
`expires_at`	Timestamp	no
`used_by`	Uuid	no
`used_at`	Timestamp	no
`version`	integer (int64)	yes

ComponentCreate¶

Property	Type	Required	Description
`custom_id`	string	yes	Example: `approve-refund`.
`type`	ComponentType	yes
`definition`	JsonObject	yes	Schema `component.v1` (09, 11.1), a closed member set per type; `400 validation_failed` with one entry per finding below `/components/<index>/definition` and the codes `required`, `invalid` or `limit_reached`.
`single_use`	boolean	no
`required_capability`	Capability	no
`restricted_to`	ComponentRestriction	no
`expires_at`	Timestamp	no

No other properties are allowed.

ComponentUpdate¶

Property	Type	Required	Description
`state`	string	no	Values: `active`, `disabled`.
`definition`	JsonObject	no	A new `component.v1` object for the type of the component (09, 11.1); it may change in every state. Type, `custom_id`, `single_use`, `required_capability`, `restricted_to` and `run_id` cannot change.

No other properties are allowed.

InteractionCreate¶

Property	Type	Required	Description
`client_interaction_id`	Uuid	yes
`values`	JsonObject	no	Selected options or form values, validated against the component definition (09, 11.1); absent means `{}`. Button: `{}`. Select: `{"selected": [<option value>, ...]}` with between `min_values` and `max_values` distinct option values. Form: an object keyed by field `name` (`text` and `textarea` strings, `number` a finite number, `boolean` a boolean, `choice` one of `choices`). A finding gives `400 validation_failed` with code `interaction_values_invalid` and its pointer; values whose `interaction.created` would exceed `sync.event_payload_max_bytes` give `too_long` on `/values`.

No other properties are allowed.

Interaction¶

Property	Type	Required	Description
`id`	Uuid	yes
`component_id`	Uuid	yes
`custom_id`	string	no	Example: `approve-refund`.
`message_id`	Uuid	yes
`thread_id`	Uuid	no
`run_id`	Uuid	no	Run of the agent card the component belongs to; absent for a component of an app card.
`principal_id`	Uuid	yes
`client_interaction_id`	Uuid	yes
`values`	JsonObject	yes
`state`	string	yes	`received` when stored. For a component of an agent card the delivery sets `dispatched` when it hands `interaction.created` to the agent, or `failed` when the re-check denies (09, 11.2). For a component of an app card the job `runs.app_dispatch` acts after the commit: `failed` when the app has no active installation; for an app whose manifest declares `delivery.interactions_url` it re-checks with the rights of that moment (`failed` without a request on a denial), sets `dispatched` when it hands the event to that address, then `acknowledged` on a `200` answer whose reply message is written in the name of the app, and `failed` when the app does not answer within `app.interaction_timeout` or gives any other answer; a `202` keeps `dispatched` until the app calls `respondToInteraction`. For an app that receives its events over the gateway the interaction stays `received` until `respondToInteraction`. `respondToInteraction` moves the state from `received` or `dispatched` to `acknowledged`, `failed` or `rejected`; every change is a compare-and-swap, so the first of the job and the owner wins and the job never overwrites the answer of the owner. Values: `received`, `dispatched`, `acknowledged`, `failed`, `rejected`.
`response`	InteractionResponse	no
`created_at`	Timestamp	yes

InteractionResponse¶

Property	Type	Required	Description
`text`	string	no	Example: `Refund approved`.

No other properties are allowed.

InteractionRespond¶

Property	Type	Required	Description
`state`	string	yes	Values: `acknowledged`, `failed`, `rejected`.
`response`	InteractionResponse	no

No other properties are allowed.

CommandOption¶

Property	Type	Required	Description
`name`	string	yes	Example: `ticket`.
`description`	string	yes	Example: `Ticket number`.
`type`	string	yes	Values: `string`, `integer`, `boolean`, `choice`, `user`, `file`.
`required`	boolean	yes
`choices`	array of CommandChoice	no
`autocomplete`	boolean	no

No other properties are allowed.

CommandChoice¶

Property	Type	Required	Description
`name`	string	yes	Example: `High priority`.
`value`	string	yes	Canonical string form of the value; the option type defines its syntax. Example: `high`.

No other properties are allowed.

Command¶

Property	Type	Required	Description
`id`	Uuid	yes
`owner_principal_id`	Uuid	yes
`name`	string	yes	Example: `escalate`.
`description`	string	yes	Example: `Escalate the ticket to second level`.
`scope_kind`	TargetKind	yes
`scope_id`	Uuid	no
`options`	array of CommandOption	yes
`required_level`	CommandLevel	yes
`control`	boolean	yes
`version`	integer (int64)	yes

CommandRegister¶

Property	Type	Required	Description
`name`	string	yes	Pattern `^[a-z0-9][a-z0-9_-]*$`. Example: `escalate`.
`description`	string	yes	Example: `Escalate the ticket to second level`.
`scope_kind`	TargetKind	no
`scope_id`	Uuid	no
`options`	array of CommandOption	no
`required_level`	CommandLevel	no
`control`	boolean	no

No other properties are allowed.

CommandList¶

Property	Type	Required	Description
`items`	array of Command	yes

CommandOptionValue¶

Property	Type	Required	Description
`name`	string	yes	Example: `ticket`.
`value`	string	yes	Example: `4711`.

No other properties are allowed.

CommandInvoke¶

Property	Type	Required	Description
`thread_id`	Uuid	no	Absent: in a text channel the main thread for a control command, and for a model command only when `auto_thread` is false; otherwise `400 validation_failed` (`/thread_id`, `required`), because a command has no message from which the `auto_thread` thread could start. For an app command absent means the main thread in a text channel and no thread in a forum channel, never `400`; `auto_thread` does not apply.
`options`	array of CommandOptionValue	no

No other properties are allowed.

CommandInvocation¶

Property	Type	Required	Description
`invocation_id`	Uuid	yes	New per accepted invocation; it appears as `invocation_id` in `command.invoked` and, for agent commands, as `command_invocation_id` in `agent.invocation`.
`command_id`	Uuid	yes
`channel_id`	Uuid	yes
`thread_id`	Uuid	no	Target thread of the invocation; absent when there is none, for example for an app command in a forum channel without `thread_id`.
`run_id`	Uuid	no	Run created for non-control commands of agents. Always absent for app commands, because apps have no runs.
`accepted`	boolean	yes	Always true, also for app commands; a refusal is an error response.

AutocompleteQuery¶

Property	Type	Required	Description
`thread_id`	Uuid	no
`option`	string	yes	Example: `ticket`.
`value`	string	yes	Example: `47`.
`options`	array of CommandOptionValue	no	Values of the other options entered so far.

No other properties are allowed.

AutocompleteResult¶

Property	Type	Required	Description
`choices`	array of CommandChoice	yes	At most `command.autocomplete_max_choices`. Max items 25.

AutocompleteAnswer¶

Property	Type	Required	Description
`choices`	array of CommandChoice	yes	At most `command.autocomplete_max_choices`. Max items 25.

No other properties are allowed.

AppManifest¶

Schema app_manifest.v1 (11, 3.1). Unknown members are an error. Beyond the schema the server applies the check rules of 11, 3.2: scopes from the catalogue, only subscribable events with the scope of their receive action and events:subscribe, https delivery addresses whose host is in webhook.allowed_hosts, requested_grants at most write and at most the capability upload and never on a host, commands without reserved names and at most command.max_per_principal, and at most app.manifest_max_bytes.

Property	Type	Required	Description
`schema_version`	integer	yes	Values: `1`. Example: `1`.
`slug`	string	yes	Unique in the instance; becomes the handle of the app principal. Pattern `^[a-z0-9][a-z0-9-]*$`. Example: `ticket-sync`.
`name`	string	yes	Becomes the display name of the app principal. Min length 1. Example: `Ticket Sync`.
`description`	string	yes	Min length 1. Example: `Mirrors tickets of a help desk into a forum.`.
`publisher`	string	yes	Min length 1. Example: `Example Ltd`.
`version`	string	yes	SemVer 2.0.0 of the manifest (`apps.manifest_version`). Example: `1.2.0`.
`homepage_url`	string	no	Absolute `https` address for display only; the server never loads it. Example: `https://apps.example.com/ticket-sync`.
`min_api_version`	string	yes	Lowest API version (major.minor) the app needs; not above the version of this server. Pattern `^[0-9]+\.[0-9]+$`. Example: `1.0`.
`scopes`	object	yes
`scopes.required`	array of AppScope	yes
`scopes.optional`	array of AppScope	yes
`events`	array of string	no	Durable event types (05, 6) the app may subscribe to; each needs the scope of its receive action and `events:subscribe`.
`delivery`	object	no	Required with `events`, `commands` or `components`.
`delivery.mode`	string	yes	Values: `gateway`, `webhook`.
`delivery.events_url`	string	no	Required for `webhook`, not allowed for `gateway`; `https`, host in `webhook.allowed_hosts`. Example: `https://apps.example.com/ticket-sync/events`.
`delivery.interactions_url`	string	no	Required for commands or components without the gateway; `https`, host in `webhook.allowed_hosts`. Example: `https://apps.example.com/ticket-sync/interactions`.
`commands`	array of CommandRegister	no	Commands after 09, 10, without reserved names and without a target.
`components`	array of string	no	Component types the app uses; only shown for the consent. Values: `button`, `select`, `form`.
`requested_grants`	array of object	no	Grants the app asks for; the owner creates them per target with `createGrant`. Only `read` or `write`, at most the capability `upload`, never on a host.
`requested_grants[].target_kind`	TargetKind	yes
`requested_grants[].level`	Level	yes
`requested_grants[].capabilities`	array of Capability	no
`requested_grants[].purpose`	string	yes	Min length 1. Example: `Posts per ticket`.
`incoming_webhooks`	array of object	no
`incoming_webhooks[].name`	string	yes	Min length 1. Example: `alerts`.
`incoming_webhooks[].purpose`	string	yes	Min length 1. Example: `Alerts of the help desk`.
`data_egress`	string	no	Plain text on which data leave the instance and where to; required with `events` or `interactions_url`. Example: `Messages of the granted channels go to apps.example.com.`.

No other properties are allowed.

App¶

Property	Type	Required	Description
`id`	Uuid	yes
`slug`	string	yes	Example: `ticket-sync`.
`display_name`	string	yes	Example: `Ticket Sync`.
`manifest`	AppManifest	yes
`manifest_version`	string	yes	Example: `1.2.0`.
`installation`	AppInstallation	yes

AppInstallation¶

Property	Type	Required	Description
`id`	Uuid	yes
`granted_scopes`	array of AppScope	yes
`event_subscriptions`	array of string	yes
`state`	string	yes	Values: `active`, `suspended`, `uninstalled`.
`installed_by`	Uuid	no
`installed_at`	Timestamp	yes

AppInstall¶

Property	Type	Required	Description
`manifest`	AppManifest	yes
`granted_scopes`	array of AppScope	yes
`event_subscriptions`	array of string	no
`reason`	string	yes	Example: `Sync tickets with the help desk`.

No other properties are allowed.

AppScopesPut¶

Property	Type	Required	Description
`granted_scopes`	array of AppScope	yes
`event_subscriptions`	array of string	no
`reason`	string	yes	Example: `App no longer needs files`.

No other properties are allowed.

ManifestValidation¶

Property	Type	Required	Description
`valid`	boolean	yes
`errors`	array of FieldError	yes

WebhookSubscription¶

Property	Type	Required	Description
`id`	Uuid	yes
`app_id`	Uuid	no	Set for subscriptions of an app.
`agent_id`	Uuid	no	Set for subscriptions of an agent (agent transport, 04 15.6); exactly one of `app_id` and `agent_id`.
`url`	string	yes	Example: `https://hooks.example.com/chat`.
`event_types`	array of string	yes
`state`	string	yes	Values: `active`, `paused`, `disabled`.
`consecutive_failures`	integer	yes
`signature_schemes`	array of string	yes	Values: `v1a`, `v1`.
`signing_key_kid`	string	yes	Example: `whk-2026-10`.
`created_at`	Timestamp	yes
`disabled_at`	Timestamp	no

WebhookSubscriptionCreate¶

Property	Type	Required	Description
`url`	string	yes	HTTPS URL; the host must be in `webhook.allowed_hosts`. Example: `https://hooks.example.com/chat`.
`event_types`	array of string	yes
`enable_hmac`	boolean	no	Also sign with Standard Webhooks `v1` (HMAC); the secret is returned once.

No other properties are allowed.

WebhookSubscriptionUpdate¶

Property	Type	Required	Description
`url`	string	no
`event_types`	array of string	no
`state`	string	no	Values: `active`, `paused`.
`rotate_hmac_secret`	boolean	no

No other properties are allowed.

WebhookSubscriptionCreated¶

Property	Type	Required	Description
`subscription`	WebhookSubscription	yes
`hmac_secret`	string	no	Standard Webhooks secret with prefix `whsec_`. Shown once. Example: `whsec_EXAMPLE`.

WebhookSubscriptionList¶

Property	Type	Required	Description
`items`	array of WebhookSubscription	yes

WebhookDelivery¶

Property	Type	Required	Description
`id`	Uuid	yes
`subscription_id`	Uuid	yes
`event_id`	Uuid	yes
`event_seq`	integer (int64)	yes
`event_type`	string	no	Type of the event, read from the event log; absent once the event left the event log (`sync.event_retention`). Example: `message.created`.
`attempt`	integer	yes
`status`	WebhookDeliveryStatus	yes
`response_code`	integer	no
`last_error`	string	no	Example: `timeout`.
`next_attempt_at`	Timestamp	no
`created_at`	Timestamp	yes
`delivered_at`	Timestamp	no

IncomingWebhook¶

Property	Type	Required	Description
`id`	Uuid	yes
`app_id`	Uuid	yes
`channel_id`	Uuid	yes
`thread_id`	Uuid	no
`name`	string	yes	Example: `Monitoring alerts`.
`created_at`	Timestamp	yes
`last_used_at`	Timestamp	no
`revoked_at`	Timestamp	no

IncomingWebhookCreate¶

Body of createIncomingWebhook. app_id names an app principal whose installation is active (else 400 validation_failed with errors[].code app_not_installed) and that may write in the channel (else app_cannot_write); thread_id, when present, is a thread of this channel (else not_in_channel, an unknown ID too). name is not empty and has no control or bidi characters.

Property	Type	Required	Description
`app_id`	Uuid	yes
`name`	string	yes	Example: `Monitoring alerts`.
`thread_id`	Uuid	no

No other properties are allowed.

IncomingWebhookCreated¶

Property	Type	Required	Description
`webhook`	IncomingWebhook	yes
`url`	string	yes	Absolute URL from `server.public_url` including the token, shown once. Senders that set a header drop the last segment and send the token as `Authorization: Bearer <token>`. Example: `https://chat.example.com/api/v1/hooks/0192f4a0-7b1c-7000-8a00-000000000901/bothy_whi_EXAMPLE000000000000000000000000000000000000_2WwD3e`.

IncomingWebhookList¶

The active incoming webhooks of a channel in creation order; revoked ones are not listed.

Property	Type	Required	Description
`items`	array of IncomingWebhook	yes

IncomingWebhookPost¶

Body of an incoming webhook call in one of two shapes, recognised per request (11 8.2, docs/DECISIONS.md D-M2-27-5, D-M7-20-5). A body with at least one Alertmanager member (version, groupKey, truncatedAlerts, status, receiver, groupLabels, commonLabels, commonAnnotations, externalURL, alerts) is the unchanged webhook payload of Prometheus Alertmanager (format alertmanager) and must contain no native member; other members of such a payload, at the top and in each alert, are ignored, because Alertmanager adds members in new versions and drops a notification answered with 400. Every other body is native, needs content_md and refuses every other member with 400 validation_failed and errors[].code unknown_member.

Property	Type	Required	Description
`content_md`	string	no	Native. Markdown content, at most `message.max_content_bytes` UTF-8 bytes. Example: `Disk usage above threshold on build host.`.
`client_msg_id`	Uuid	no	Native. Optional UUIDv7; makes retries of the sender idempotent.
`title`	string	no	Native. Title of a new thread when the webhook has no fixed thread; required in a forum. Example: `Disk alert`.
`thread_id`	Uuid	no	Native. Thread of the webhook's channel to write into when the webhook has no fixed thread.
`version`	string	no	Alertmanager. Version of the webhook payload. Values: `4`.
`groupKey`	string	no	Alertmanager. Key of the alert group.
`truncatedAlerts`	integer (int64)	no	Alertmanager. Number of alerts left out of `alerts`. Minimum 0.
`status`	string	no	Alertmanager. State of the group. Values: `firing`, `resolved`.
`receiver`	string	no	Alertmanager. Name of the receiver.
`groupLabels`	JsonObject	no	Alertmanager. Labels of the group; every value is a string.
`commonLabels`	JsonObject	no	Alertmanager. Labels all alerts share; every value is a string.
`commonAnnotations`	JsonObject	no	Alertmanager. Annotations all alerts share; every value is a string.
`externalURL`	string	no	Alertmanager. Address of the sending Alertmanager; written as text, never fetched.
`alerts`	array of AlertmanagerAlert	no	Alertmanager. The alerts of the notification. Min items 1.

AlertmanagerAlert¶

One alert of an Alertmanager webhook payload; status and labels are required (checked with errors[].code required); other members are ignored (D-M7-20-5).

Property	Type	Required	Description
`status`	string	no	Values: `firing`, `resolved`.
`labels`	JsonObject	no	Labels of the alert; every value is a string.
`annotations`	JsonObject	no	Annotations of the alert; every value is a string.
`startsAt`	string (date-time)	no
`endsAt`	string (date-time)	no
`generatorURL`	string	no	Address of the rule's source; written as text, never fetched.
`fingerprint`	string	no

AuditEvent¶

Property	Type	Required	Description
`seq`	integer (int64)	yes
`id`	Uuid	yes
`occurred_at`	Timestamp	yes
`actor_principal_id`	Uuid	no
`actor_device_id`	Uuid	no
`actor_session_id`	Uuid	no
`action`	string	yes	Example: `grant.create`.
`decision`	AuditDecision	yes
`deny_reason`	string	no
`resource_kind`	string	no	Example: `grant`.
`resource_id`	Uuid	no
`details`	JsonObject	yes
`correlation_id`	CorrelationId	no
`prev_hash`	string	yes	Hex.
`hash`	string	yes	Hex.

AuditVerifyRequest¶

Property	Type	Required	Description
`from_seq`	integer (int64)	no
`to_seq`	integer (int64)	no

No other properties are allowed.

AuditVerifyResult¶

Property	Type	Required	Description
`ok`	boolean	yes
`checked_from_seq`	integer (int64)	yes
`checked_to_seq`	integer (int64)	yes
`first_broken_seq`	integer (int64)	no
`failure_reason`	string	no	Values: `hash_mismatch`, `link_mismatch`, `seq_gap`, `checkpoint_mismatch`, `checkpoint_invalid`.
`checkpoints_compared`	integer (int64)	yes
`last_checkpoint_seq`	integer (int64)	no
`warnings`	array of string	yes	Known value `checkpoint_sink_not_configured`.

StatsBucket¶

One time bucket of one group. group_key is set when the query groups (space, agent, tool).

Property	Type	Required	Description
`start`	Timestamp	yes	Start of the bucket as a UTC instant (local midnight of `stats.time_zone` for `day`, `week` and `month`).
`group_key`	string	no	Space ID, agent ID or tool name, as the operation names it; never a person. Example: `0192f4a0-7b1c-7000-8a00-000000000101`.
`metrics`	map of number (double)	yes	Metric name to value. Names per endpoint are listed in its description; a metric without a value is absent.
`below_min_group`	array of string	no	Metrics that count people and were withheld because their value is below `privacy.stats_min_group_size`; the client shows "fewer than" the minimum group.

StatsSeries¶

Property	Type	Required	Description
`granularity`	StatsGranularity	yes
`buckets`	array of StatsBucket	yes

CostSeries¶

Property	Type	Required	Description
`granularity`	StatsGranularity	yes
`currency`	string	yes	Example: `USD`.
`buckets`	array of CostBucket	yes

CostBucket¶

Property	Type	Required
`start`	Timestamp	yes
`group_key`	string	no
`billing_mode`	BillingMode	yes
`amount_micros`	integer (int64)	yes
`is_estimate`	boolean	yes

Price¶

Property	Type	Required	Description
`id`	Uuid	yes
`provider`	string	yes	Example: `anthropic`.
`model`	string	yes	Example: `model-large`.
`unit`	PriceUnit	yes
`price_micros`	integer (int64)	yes
`currency`	string	yes	Example: `USD`.
`valid_from`	Timestamp	yes
`valid_to`	Timestamp	no
`source_url`	string	yes	Example: `https://provider.example.com/pricing`.
`retrieved_at`	Timestamp	yes

PriceCreate¶

A price per unit (per million tokens for the *_mtok units) with its public source. valid_to, when present, lies after valid_from; valid_from may lie in the past. source_url is an absolute https URL without user info and fragment; retrieved_at is not in the future.

Property	Type	Required	Description
`provider`	string	yes	Example: `anthropic`.
`model`	string	yes	Example: `model-large`.
`unit`	PriceUnit	yes
`price_micros`	integer (int64)	yes
`currency`	string	yes	Example: `USD`.
`valid_from`	Timestamp	yes
`valid_to`	Timestamp	no
`source_url`	string	yes	Example: `https://provider.example.com/pricing`.
`retrieved_at`	Timestamp	yes

No other properties are allowed.

PriceClose¶

The new end of the validity, after valid_from.

Property	Type	Required	Description
`valid_to`	Timestamp	yes

No other properties are allowed.

PriceList¶

Property	Type	Required	Description
`items`	array of Price	yes

CostReconcile¶

Property	Type	Required	Description
`provider`	string	yes	Min length 1. Example: `anthropic`.
`period_start`	Timestamp	yes
`period_end`	Timestamp	yes
`entries`	array of ReconcileEntry	yes

No other properties are allowed.

ReconcileEntry¶

Property	Type	Required	Description
`run_id`	Uuid	yes
`amount_micros`	integer (int64)	yes	Minimum 0.
`currency`	string	yes	ISO 4217 code. Pattern `^[A-Z]{3}$`. Example: `USD`.

No other properties are allowed.

CostReconcileResult¶

Property	Type	Required	Description
`reconciled`	integer	yes
`unmatched_run_ids`	array of Uuid	yes

CostEstimate¶

Estimate of one run in the requested range for the reconciliation (10, 12.4; 05, R-AZ-28). Names no channel, thread or content.

Property	Type	Required	Description
`run_id`	Uuid	yes
`agent_id`	Uuid	yes
`provider`	string	yes	Example: `anthropic`.
`currency`	string	yes	ISO 4217 code. Example: `USD`.
`estimate_micros`	integer (int64)	yes	Sum in micro units of the run's estimate entries in the range whose successor, if any, is not an estimate; the estimate before any reconciliation. Example: `1250000`.
`reconciled`	boolean	yes	True when every valid entry of the run in the range has `source = reconciled`.

CostEstimatePage¶

One page. next_cursor is absent on the last page.

Property	Type	Required	Description
`items`	array of CostEstimate	yes
`next_cursor`	Cursor	no

ClientMetricsBatch¶

Anonymous client measurements (15, section 17). No contents, no IDs of threads, channels or people.

Property	Type	Required	Description
`platform`	string	yes	Values: `ios`, `android`, `macos`, `windows`, `web`.
`app_version`	string	yes	Example: `1.4.0`.
`density`	string	no	Mobile apps always send `touch` (01, section 11). Values: `comfortable`, `compact`, `touch`.
`theme`	string	no	Values: `light`, `dark`.
`metrics`	array of ClientMetric	yes	Max items 200.

No other properties are allowed.

ClientMetric¶

Property	Type	Required	Description
`name`	string	yes	One name of the closed list in docs/observability/signals.md section 4.6a: `client.cold_start.duration`, `client.thread_open.duration`, `client.send_local.duration`, `client.frames`, `client.frames.over_budget`, `client.catchup.duration`, `client.catchup.events`, `client.resync`, `client.reconnects`, `client.outbox.depth`, `client.push_display.duration`, `client.push.placeholder`. Not an enum on purpose: the server drops an entry with an unknown name, or with a `kind` that does not match the type of its name, one by one and still accepts the rest of the batch, so a newer app does not lose its batch against an older server. Max length 64; pattern `^client\.[a-z_.]+$`. Example: `client.thread_open.duration`.
`kind`	string	yes	Values: `histogram`, `counter`, `gauge`.
`close_code`	integer	no	Only for `client.reconnects`; a close code of 04 section 6.4. Example: `4009`.
`value`	number (double)	no	Counter increment or gauge value.
`buckets`	array of object	no	Histogram buckets (upper bound and count).
`buckets[].le`	number (double)	yes
`buckets[].count`	integer (int64)	yes

No other properties are allowed.

StatusComponentState¶

Type: string

Values: operational, degraded, partial_outage, major_outage, maintenance.

StatusComponent¶

Property	Type	Required	Description
`id`	Uuid	yes
`name`	string	yes	Example: `Messages`.
`description`	string	yes
`sort_key`	string	yes	Example: `a0`.
`state`	StatusComponentState	yes
`health_source`	string	no	Example: `db`.
`agent_id`	Uuid	no
`updated_at`	Timestamp	yes

StatusComponentInput¶

Property	Type	Required	Description
`name`	string	yes	Example: `Messages`.
`description`	string	no
`state`	StatusComponentState	no
`health_source`	string	no
`agent_id`	Uuid	no
`after_component_id`	Uuid	no

No other properties are allowed.

StatusIncidentState¶

Type: string

Values: scheduled, investigating, identified, monitoring, resolved.

StatusIncident¶

Property	Type	Required	Description
`id`	Uuid	yes
`title`	string	yes	Example: `Push notifications delayed`.
`kind`	StatusIncidentKind	yes
`impact`	StatusIncidentImpact	yes
`state`	StatusIncidentState	yes
`started_at`	Timestamp	yes
`resolved_at`	Timestamp	no
`component_ids`	array of Uuid	yes
`updates`	array of StatusIncidentUpdate	yes

StatusIncidentUpdate¶

Property	Type	Required	Description
`id`	Uuid	yes
`state`	StatusIncidentState	yes
`body_md`	string	yes	Example: `The push provider reports delays. We are monitoring.`.
`created_at`	Timestamp	yes

StatusIncidentCreate¶

Property	Type	Required	Description
`title`	string	yes	Example: `Push notifications delayed`.
`kind`	StatusIncidentKind	yes
`impact`	StatusIncidentImpact	yes
`state`	StatusIncidentState	no
`started_at`	Timestamp	yes
`component_ids`	array of Uuid	yes
`body_md`	string	yes	Example: `The push provider reports delays.`.

No other properties are allowed.

StatusIncidentUpdateCreate¶

Property	Type	Required	Description
`state`	StatusIncidentState	yes
`body_md`	string	yes	Example: `Delays are resolved.`.

No other properties are allowed.

StatusPage¶

Property	Type	Required	Description
`overall_state`	StatusComponentState	yes
`components`	array of StatusComponent	yes
`incidents`	array of StatusIncident	yes	Open incidents and recent ones within `status.history_window`.

ImportSource¶

Property	Type	Required	Description
`id`	Uuid	yes
`kind`	ImportKind	yes
`name`	string	yes	Example: `Old community server`.
`config`	JsonObject	yes	Schema `import_source.<kind>.v1`; credentials only as `secret_ref` names.
`state`	string	yes	A dry run writes nothing and keeps the state. Values: `draft`, `running`, `paused`, `completed`, `failed`.
`stats`	JsonObject	yes	Counters without content. The server's counters per item kind and state are under `server` (`server.<item_kind>.<state>`, `server.source_changed`, `server.cancelled`); the counters of the import tool from `setImportCursor` are under `tool`.
`cursor`	JsonObject	no	The object last stored by `setImportCursor` (progress and the run lease of the import tool, 22 7.3 and 7.4); `{}` before the first one. The server never interprets it.
`created_at`	Timestamp	yes
`started_at`	Timestamp	no
`finished_at`	Timestamp	no

ImportSourceCreate¶

Property	Type	Required	Description
`kind`	ImportKind	yes
`name`	string	yes	Example: `Old community server`.
`config`	JsonObject	yes	For `kind = discord` the mapping of schema `import_source.discord.v1`, see `ImportSourceDiscordConfig` (22, 5.2); every violation is one error of `400 validation_failed` with its JSON pointer, all reported at once. `kind = archive` is `400 validation_failed` with the code `not_enabled`.

No other properties are allowed.

ImportItem¶

Property	Type	Required	Description
`id`	Uuid	yes
`origin_key`	string	yes	Example: `message:1029384756:0`.
`item_kind`	string	yes	Values: `space`, `channel`, `forum_tag`, `thread`, `message`, `file`, `user`, `reaction`, `pin`.
`target_kind`	string	no
`target_id`	Uuid	no
`state`	ImportItemState	yes
`error`	string	no
`source_changed`	boolean	no	Present and `true` when a repeated key came with a `content_sha256` different from the stored one; nothing was changed (22, 7.2 item 4).
`session`	string	no	Present on a `thread` item that carried `earlier_session` and has a thread (22, 9 step 1): `taken_over` when the earlier `agent_sessions` row was written by this batch, `already_present` when a row of the same thread, agent and reference with `end_reason = import` existed, `dropped_late` when the thread has had a current session since the import and nothing was written (22, 9 step 6). Values: `taken_over`, `already_present`, `dropped_late`.
`created_at`	Timestamp	yes

GdprRequest¶

Property	Type	Required	Description
`id`	Uuid	yes
`subject_user_id`	Uuid	yes
`kind`	GdprRequestKind	yes
`state`	GdprRequestState	yes
`requested_by`	Uuid	yes
`approved_by`	Uuid	no
`reason`	string	yes	Example: `Request by the person`.
`due_at`	Timestamp	yes
`result_expires_at`	Timestamp	no
`progress`	JsonObject	no
`error`	string	no
`created_at`	Timestamp	yes
`completed_at`	Timestamp	no

GdprRequestCreate¶

Property	Type	Required	Description
`subject_user_id`	Uuid	no	Absent means the caller. Others only for owners.
`kind`	GdprRequestKind	yes
`reason`	string	yes	Example: `Request by the person`.

No other properties are allowed.

GdprDecision¶

Property	Type	Required	Description
`decision`	string	yes	Values: `approve`, `reject`.
`reason`	string	yes	Example: `Identity verified`.

No other properties are allowed.

ViewAsSnapshot¶

Read-only view of what a person can see, for owners (07, 9.2). Direct messages never appear.

Property	Type	Required	Description
`user`	PrincipalRef	yes
`expires_at`	Timestamp	yes	End of the view, `authz.view_as_max_duration` after its start.
`spaces`	array of SpaceView	yes
`channels`	array of ChannelView	yes

EventScope¶

Location of the event. Members are absent where not applicable.

Property	Type	Required
`space_id`	Uuid	no
`channel_id`	Uuid	no
`thread_id`	Uuid	no

EventResource¶

Property	Type	Required	Description
`kind`	string	yes	Example: `message`.
`id`	Uuid	no
`version`	integer (int64)	no

EventActor¶

Property	Type	Required	Description
`id`	Uuid	no
`kind`	ActorKind	yes

EventEnvelope¶

Common envelope of every event. Each event schema adds type and its payload. Durable events carry seq and permission_version; ephemeral events carry neither. Delivery-only members (invocation_token, redelivered, sync_epoch) are set per delivery and never stored in the event log.

Property	Type	Required	Description
`id`	Uuid	yes
`seq`	integer (int64)	no	Global commit-ordered sequence; absent for ephemeral events. Example: `5301`.
`schema_version`	integer	yes	Example: `1`.
`occurred_at`	Timestamp	yes
`actor`	EventActor	no
`scope`	EventScope	yes
`resource`	EventResource	yes
`audience`	string	no	Values: `self`.
`redacted`	boolean	no
`truncated`	boolean	no	The payload was cut to `sync.event_payload_max_bytes`; load the resource via REST.
`correlation_id`	CorrelationId	no
`trace_context`	string	no	W3C `traceparent` of the triggering request; only in deliveries to agent adapters and only if the request was recorded. Example: `00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01`.
`client_msg_id`	Uuid	no
`permission_version`	integer (int64)	no
`invocation_token`	string	no	Fresh invocation token (JWS, I3); only on agent-addressed invocation events.
`redelivered`	boolean	no	Set on redelivery to an agent consumer after `agent.ack_timeout`.
`sync_epoch`	Uuid	no	Delivery-only member of outgoing webhooks; the time line of the event log (04, 7.5; ADR 0059). A receiver that sees a new epoch resets its `seq` state.

MessagePayload¶

Property	Type	Required	Description
`message`	Message	yes

MessageDeletedPayload¶

Property	Type	Required
`message_id`	Uuid	yes
`thread_id`	Uuid	yes
`thread_seq`	integer (int64)	yes
`deleted_at`	Timestamp	yes
`deleted_by`	Uuid	no

ReactionPayload¶

Property	Type	Required	Description
`message_id`	Uuid	yes
`thread_id`	Uuid	yes
`emoji`	string	yes	Example: `👍`.
`principal_id`	Uuid	yes
`count`	integer	yes	Count for this emoji after the change.

PinPayload¶

Property	Type	Required	Description
`pin`	Pin	yes

ThreadPayload¶

Property	Type	Required	Description
`thread`	Thread	yes

ThreadMovedPayload¶

Property	Type	Required	Description
`thread`	Thread	yes
`from_channel_id`	Uuid	yes

ThreadMovedOutPayload¶

Sent in the source channel. Does not name the target channel.

Property	Type	Required	Description
`thread_id`	Uuid	yes
`channel_id`	Uuid	yes

AgentSessionChangedPayload¶

Property	Type	Required	Description
`thread_id`	Uuid	yes
`agent_session`	AgentSession	yes

RunStateChangedPayload¶

Property	Type	Required
`run`	RunSummary	yes
`triggering_message_id`	Uuid	no
`trigger_state`	TriggerState	no

SpacePayload¶

Property	Type	Required	Description
`space`	Space	yes

ChannelPayload¶

Property	Type	Required	Description
`channel`	Channel	yes

ChannelSettingsChangedPayload¶

Property	Type	Required	Description
`channel_id`	Uuid	yes
`settings_version`	integer (int64)	yes

CommandChangedPayload¶

Property	Type	Required	Description
`command`	Command	yes
`change`	string	yes	Values: `registered`, `updated`, `removed`.

FilePayload¶

Property	Type	Required	Description
`file`	File	yes

UserPayload¶

Property	Type	Required	Description
`user`	User	yes

AgentPayload¶

Property	Type	Required	Description
`agent`	Agent	yes

InstanceUpdatedPayload¶

Property	Type	Required	Description
`changed_keys`	array of string	yes	Setting or flag keys that changed; values are loaded via REST.

StatusUpdatedPayload¶

Property	Type	Required
`overall_state`	StatusComponentState	yes
`changed_component_ids`	array of Uuid	no
`changed_incident_ids`	array of Uuid	no

GrantChangedPayload¶

Property	Type	Required	Description
`grant`	Grant	yes
`change`	string	yes	Values: `created`, `revoked`, `expired`.

GroupChangedPayload¶

Property	Type	Required	Description
`group`	Group	yes
`change`	string	yes	`member_expired`: a membership ended by expiry, reported once by the job `authz.expiry_sweep`. Values: `created`, `updated`, `deleted`, `member_added`, `member_removed`, `member_expired`.
`user_id`	Uuid	no

AccessChangedPayload¶

Property	Type	Required	Description
`permission_version`	integer (int64)	yes	Example: `418`.
`added`	array of AccessTarget	yes
`removed`	array of AccessTarget	yes
`changed`	array of AccessTarget	yes

AccessExpiringPayload¶

A grant or group membership ends within authz.expiry_reminder_lead.

Property	Type	Required	Description
`kind`	string	yes	Values: `grant`, `group_membership`.
`grant_id`	Uuid	no
`group_id`	Uuid	no
`subject_id`	Uuid	yes
`target`	AccessTarget	no	Absent for a grant on the instance.
`expires_at`	Timestamp	yes

DevicePendingPayload¶

A new device of the human waits for approval (R-AZ-31). Carries only IDs and the platform.

Property	Type	Required	Description
`device_id`	Uuid	yes
`platform`	DevicePlatform	yes

GdprRequestDuePayload¶

An open privacy request reaches the reminder lead before its statutory deadline (R-AZ-35). Carries only the ID, the kind and the deadline.

Property	Type	Required
`request_id`	Uuid	yes
`kind`	GdprRequestKind	yes
`due_at`	Timestamp	yes

SessionRevokedPayload¶

Property	Type	Required	Description
`session_id`	Uuid	yes
`reason`	string	yes	Values: `logout`, `admin`, `device_revoked`, `refresh_reuse`, `user_disabled`, `expired`, `inactive`, `step_up_failed`, `trusted_header_mismatch`.

ReadStatePayload¶

Property	Type	Required	Description
`read_state`	ReadState	yes

DraftPayload¶

Property	Type	Required	Description
`draft`	Draft	yes

DraftDeletedPayload¶

Property	Type	Required
`draft_id`	Uuid	yes
`thread_id`	Uuid	no
`channel_id`	Uuid	yes

SettingsPayload¶

Property	Type	Required	Description
`setting`	UserSetting	yes
`deleted`	boolean	no

SidebarPayload¶

Property	Type	Required	Description
`state`	SidebarState	yes

NotificationPrefPayload¶

Property	Type	Required	Description
`preference`	NotificationPreference	yes
`deleted`	boolean	no

QuietHoursPayload¶

Property	Type	Required	Description
`rules`	array of QuietHoursRule	yes	Complete list after the change, ascending by id.

GdprRequestPayload¶

Property	Type	Required	Description
`request`	GdprRequest	yes

ImportProgressPayload¶

Property	Type	Required	Description
`import`	ImportSource	yes

AgentInvocationPayload¶

Sent to the agent; the envelope carries a fresh invocation_token per delivery.

Property	Type	Required	Description
`run_id`	Uuid	yes
`thread_id`	Uuid	yes
`channel_id`	Uuid	yes
`space_id`	Uuid	no
`trigger_kind`	string	yes	Values: `message`, `interaction`, `command`.
`message_id`	Uuid	no	Triggering message; the adapter reads its content with `run.context.read` (09, 4.6). Events outside resource `message` never carry message content (04, 2.2).
`interaction_id`	Uuid	no
`command_invocation_id`	Uuid	no
`command_id`	Uuid	no	Triggering command; set exactly for `trigger_kind = command`.
`command_name`	string	no	Name of the triggering command; set exactly for `trigger_kind = command`. Example: `escalate`.
`options`	array of CommandOptionValue	no	Parsed option values in the order of the command definition; set exactly for `trigger_kind = command`.
`triggered_by`	PrincipalRef	yes
`billing_mode`	BillingMode	yes
`agent_session`	AgentSession	no	The session row of the run (09, 9.1); absent for `session_mode = new` without a row and for a guest run. With `started = false` the adapter reuses its `external_session_ref`; its `version` is the `If-Match` of the first `reportAgentSession`.
`session_mode`	string	no	`session.mode` of 09, 9.1: `new` creates the external session (with the reference of `agent_session` when present), `resume` continues it, `bind` takes over a session that no run used yet (rebinding, import; 9.5). Present exactly for a run of the thread's operator; a guest run has neither `session_mode` nor `agent_session` (09, 3.6). Values: `new`, `resume`, `bind`.
`settings_version`	integer (int64)	no	Channel settings version; reload `agent.config.read` when newer than cached.

AgentFollowupPayload¶

Property	Type	Required	Description
`run_id`	Uuid	yes
`thread_id`	Uuid	yes
`message_id`	Uuid	yes	Follow-up message; the adapter reads its content with `getMessage` (`message.read`); its author is `sub` of the invocation token of this delivery.

RunCancelRequestedPayload¶

Property	Type	Required	Description
`run_id`	Uuid	yes
`thread_id`	Uuid	yes
`reason`	string	yes	Values: `user_cancelled`, `access_revoked`, `agent_disabled`, `user_disabled`, `channel_read_only`.
`requested_by`	Uuid	no

InteractionCreatedPayload¶

Property	Type	Required	Description
`interaction`	Interaction	yes

CommandInvokedPayload¶

Property	Type	Required	Description
`invocation_id`	Uuid	yes
`command_id`	Uuid	yes
`command_name`	string	yes	Example: `escalate`.
`control`	boolean	yes
`channel_id`	Uuid	yes
`thread_id`	Uuid	no
`run_id`	Uuid	no	Active run of the command owner in the thread at execution time; absent when the owner has none (R-AZ-25). Never the run of another agent. Always absent for app commands, because apps have no runs.
`invoked_by`	PrincipalRef	yes
`options`	array of CommandOptionValue	yes

AgentConfigChangedPayload¶

Property	Type	Required	Description
`channel_id`	Uuid	yes
`settings_version`	integer (int64)	yes

TypingStartedPayload¶

Property	Type	Required
`thread_id`	Uuid	yes
`principal_id`	Uuid	yes
`expires_at`	Timestamp	yes

RunUpdatedPayload¶

Coalesced live-box patch. Either ops (from base_version to version) or a full snapshot.

Property	Type	Required
`run_id`	Uuid	yes
`base_version`	integer (int64)	no
`version`	integer (int64)	yes
`ops`	array of JsonPatchOperation	no
`snapshot`	Run	no

AgentPresencePayload¶

Property	Type	Required
`agent_id`	Uuid	yes
`state`	AgentRuntimeState	yes
`reported_billing_mode`	BillingMode	no

CommandAutocompleteRequestedPayload¶

Sent to one gateway connection of the command owner (04, 15.7); agents get an invocation token with trigger_kind = autocomplete in the delivery fields.

Property	Type	Required	Description
`request_id`	Uuid	yes
`command_id`	Uuid	yes
`channel_id`	Uuid	yes
`thread_id`	Uuid	no
`user_id`	Uuid	yes
`option`	string	yes	Example: `ticket`.
`value`	string	yes	Example: `47`.
`options`	array of CommandOptionValue	no
`expires_at`	Timestamp	yes

EventPage¶

Property	Type	Required	Description
`events`	array of Event	yes
`next_cursor`	integer (int64)	yes	Highest checked `seq`; use as `after` for the next call even if `events` is empty.
`head_seq`	integer (int64)	yes
`sync_epoch`	Uuid	yes	Time line of the event log; a client stores it with its cursor (04, 7.5).

GatewayHello¶

Property	Type	Required	Description
`heartbeat_interval_ms`	integer (int64)	yes	Example: `30000`.
`resume_window_ms`	integer (int64)	yes	Example: `300000`.
`protocol_versions`	array of integer	yes
`dpop_nonce`	string	yes	Example: `eyJ7S_zG.eyJH0-Z.HX4w-7v`.
`server_time`	Timestamp	yes
`sync_epoch`	Uuid	yes	Time line of the event log; a client stores it with its cursor (04, 7.5).

GatewayClientInfo¶

Property	Type	Required	Description
`platform`	DevicePlatform	yes
`version`	string	yes	Example: `1.4.0`.

No other properties are allowed.

GatewayIdentify¶

People send access_token, dpop, device_id; agents and apps send api_token, consumer and dpop when the token is DPoP-bound.

Property	Type	Required	Description
`protocol_version`	integer	yes	Example: `1`.
`access_token`	string	no
`api_token`	string	no
`dpop`	string	no	DPoP proof with `htm = GET`, `htu` = HTTPS form of the gateway URL, `nonce` from `hello`, `ath`.
`device_id`	Uuid	no
`consumer`	string	no	Pattern `^[a-z0-9][a-z0-9_-]*$`. Example: `default`.
`cursor`	integer (int64)	no	Last processed `seq`; absent on first connect.
`sync_epoch`	Uuid	no	Epoch stored with the cursor; absent on first connect. A mismatch gives `resync_required` with `epoch_changed`.
`client`	GatewayClientInfo	no

No other properties are allowed.

GatewayReady¶

Property	Type	Required	Description
`gateway_session_id`	Uuid	yes
`principal`	PrincipalRef	yes
`device_id`	Uuid	no
`permission_version`	integer (int64)	yes
`head_seq`	integer (int64)	yes
`snapshot`	Snapshot	yes
`sync_epoch`	Uuid	yes	Time line of the event log; a client stores it with its cursor (04, 7.5).

GatewayResume¶

Property	Type	Required
`gateway_session_id`	Uuid	yes
`access_token`	string	no
`api_token`	string	no
`dpop`	string	no
`cursor`	integer (int64)	yes
`sync_epoch`	Uuid	no

No other properties are allowed.

GatewayResumed¶

Property	Type	Required	Description
`gateway_session_id`	Uuid	yes
`head_seq`	integer (int64)	yes
`sync_epoch`	Uuid	yes	Time line of the event log; a client stores it with its cursor (04, 7.5).

GatewayHeartbeat¶

Property	Type	Required	Description
`last_seq`	integer (int64)	yes
`agent`	Heartbeat	no	Agents only; equivalent to `POST /agents/me/heartbeat`. The liveness rules of the op run first (`heartbeat_ack`); then the agent part passes `rl.agent_runtime` and `agent.heartbeat`. Its errors (`forbidden`, `validation_failed`, `rate_limited`, `internal_error`) answer `error` and keep the connection. A heartbeat of an agent without this member changes no presence.

No other properties are allowed.

GatewayHeartbeatAck¶

Property	Type	Required	Description
`server_time`	Timestamp	yes

GatewayReauth¶

Property	Type	Required	Description
`access_token`	string	yes
`dpop`	string	yes

No other properties are allowed.

GatewayReauthRequired¶

Property	Type	Required	Description
`expires_at`	Timestamp	yes
`dpop_nonce`	string	yes

GatewayFocus¶

Property	Type	Required	Description
`thread_ids`	array of Uuid	yes	Complete set of focused threads; replaces the previous set. More than `sync.max_focused_threads` ids answer `error` with `validation_failed` and keep the previous set.
`idle`	boolean	no	True when the window is open but unused; live-box patches continue, but the person does not count as watching (13, 4.4).
`background_thread_ids`	array of Uuid	no	Threads whose runs the app shows without their messages (control room cards, a run graph opened from a card). They get the run document and `run.updated` but no typing, never count as "Active in the thread" and are not part of the presence focus (13 4.4). Unreadable threads are ignored as in `thread_ids`; a thread in both lists counts as in `thread_ids`; both lists together hold at most `sync.max_focused_threads` distinct threads (04 6.2, R-SY-27).

No other properties are allowed.

GatewayTyping¶

Property	Type	Required	Description
`thread_id`	Uuid	yes

No other properties are allowed.

GatewayAck¶

Property	Type	Required	Description
`seq`	integer (int64)	yes	Minimum 0.

No other properties are allowed.

GatewayRunUpdate¶

Property	Type	Required	Description
`run_id`	Uuid	yes
`base_version`	integer (int64)	yes
`ops`	array of JsonPatchOperation	yes
`ref`	string	no	Client reference echoed in `error` frames for this op.

No other properties are allowed.

GatewayAutocompleteResult¶

Answer of the command owner to command.autocomplete_requested (action command.autocomplete.respond).

Property	Type	Required	Description
`request_id`	Uuid	yes
`choices`	array of CommandChoice	yes	At most `command.autocomplete_max_choices`. Max items 25.
`ref`	string	no	Client reference echoed in `error` frames for this op.

No other properties are allowed.

GatewayCursor¶

Property	Type	Required	Description
`seq`	integer (int64)	yes

GatewayCatchupComplete¶

Property	Type	Required	Description
`head_seq`	integer (int64)	yes

GatewayResyncRequired¶

Property	Type	Required	Description
`reason`	string	yes	Values: `epoch_changed`, `retention`, `too_far_behind`, `cursor_ahead`.
`head_seq`	integer (int64)	yes
`sync_epoch`	Uuid	yes	Time line of the event log; a client stores it with its cursor (04, 7.5).

GatewayError¶

Property	Type	Required	Description
`op`	string	yes	Example: `focus`.
`code`	string	yes	Same codes as REST problem types. Example: `rate_limited`.
`detail`	string	no
`ref`	string	no

PageLimit¶

Page size. Default api.page_size_default; larger values than api.page_size_max are capped.

Type: integer

Minimum 1.

ImageUpload¶

Image as the one multipart part file (a further part is rejected with 400 validation_failed). The server detects the type from the bytes; it accepts only JPEG and PNG, whose metadata it removes losslessly, and still WebP, which it converts to PNG or JPEG without metadata. Thumbnails are re-encoded. Any other detected type ends the file failed with file_type_denied.

Property	Type	Required	Description
`file`	string (binary)	yes

No other properties are allowed.

IncomingWebhookResult¶

Property	Type	Required	Description
`message_id`	Uuid	yes
`thread_id`	Uuid	yes	The thread the message landed in; with a `title` in a text channel the new thread that starts from the message, which itself stands in the main thread.

StatsMetric¶

Metric of the own measurement in stats_minutes (docs/spec/25-visualization.md, section 3.2).

Type: string

Values: messages_created, threads_created, runs_started, runs_finished, tool_calls, approval_cards, cost, invocations_denied, billing_mode_switches, catchups, resyncs, slow_consumer_closes, sli.api_availability, sli.delivery_latency, sli.reconnect, sli.push_acceptance, sli.run_start, sli.turn_duration.

StatsScope¶

Property	Type	Required	Description
`kind`	string	yes	Values: `instance`, `space`.
`space_id`	Uuid	no

AgentRateLimitState¶

Rate-limit state of the agent runtime at its provider as reported by the adapter (agent_heartbeat.v1). Never quotas of an account, keys or subscription names.

Property	Type	Required	Description
`state`	string	yes	Values: `ok`, `near_limit`, `limited`, `unknown`.
`resets_at`	Timestamp	no

No other properties are allowed.

StatsLiveStep¶

Current step of a run; only kind and name (for tools the tool name), never title or detail.

Property	Type	Required	Description
`kind`	string	yes	Values: `tool_call`, `status`, `subagent`, `workflow`, `background_job`.
`name`	string	yes	Example: `Bash`.

StatsLiveRun¶

Property	Type	Required	Description
`run_id`	Uuid	yes
`thread_id`	Uuid	yes
`channel_id`	Uuid	yes
`space_id`	Uuid	yes
`agent_id`	Uuid	yes
`state`	string	yes	Values: `queued`, `running`, `waiting_input`.
`queued_at`	Timestamp	yes
`started_at`	Timestamp	no
`billing_mode`	BillingMode	yes	Mode used by the run, else the configured mode.
`step`	StatsLiveStep	no
`approval_pending`	boolean	yes	An approval card of this run waits for a decision.
`cost_micros`	integer (int64)	no	Cost so far; only with `cost.read.aggregate`.
`currency`	string	no	Example: `USD`.
`cost_is_estimate`	boolean	no

StatsLiveAgent¶

Property	Type	Required	Description
`agent_id`	Uuid	yes
`presence`	AgentRuntimeState	yes
`billing_mode`	BillingMode	yes
`reported_billing_mode`	BillingMode	no	Absent when the adapter follows the configured mode per run.
`rate_limit`	AgentRateLimitState	no

StatsLiveRate¶

Sum of count (and sum where meaningful) of one metric over the last full minute and the current minute up to at.

Property	Type	Required	Description
`metric`	StatsMetric	yes
`dimension`	string	no	Dimension code; absent means all dimensions summed.
`last_minute`	integer (int64)	yes
`current_minute`	integer (int64)	yes
`last_minute_sum`	integer (int64)	no	Sum of values (milliseconds or micro units) of the last full minute.
`currency`	string	no	Only for metric `cost`.

StatsLiveSli¶

Property	Type	Required	Description
`metric`	StatsMetric	yes
`total`	integer (int64)	yes
`good`	integer (int64)	yes
`ratio`	number (double)	no	`good / total`; absent when `total` is 0.

StatsLiveConnections¶

Gateway connections of this node; only with cluster.mode = single.

Property	Type	Required
`user`	integer	yes
`agent`	integer	yes
`app`	integer	yes

StatsLiveFrame¶

Live frame (docs/spec/25-visualization.md, section 5.2). No person values, no content.

Property	Type	Required	Description
`at`	Timestamp	yes
`interval_ms`	integer	yes	Example: `1000`.
`scope`	StatsScope	yes
`runs`	array of StatsLiveRun	yes
`runs_truncated`	boolean	yes
`agents`	array of StatsLiveAgent	yes
`rates`	array of StatsLiveRate	yes
`sli`	array of StatsLiveSli	no	Only for the instance scope.
`connections`	StatsLiveConnections	no

StatsTimelineBucket¶

One row of stats_minutes.

Property	Type	Required	Description
`start`	Timestamp	yes
`metric`	StatsMetric	yes
`channel_id`	Uuid	no
`agent_id`	Uuid	no
`dimension`	string	yes	Code from the closed list per metric; empty string when the metric has none.
`currency`	string	no
`count`	integer (int64)	yes
`sum`	integer (int64)	yes
`good`	integer (int64)	yes

StatsTimelineRun¶

Property	Type	Required
`run_id`	Uuid	yes
`channel_id`	Uuid	yes
`agent_id`	Uuid	yes
`queued_at`	Timestamp	yes
`started_at`	Timestamp	no
`finished_at`	Timestamp	no
`state`	RunState	yes

StatsTimeline¶

Property	Type	Required	Description
`from`	Timestamp	yes
`to`	Timestamp	yes
`buckets`	array of StatsTimelineBucket	yes
`runs`	array of StatsTimelineRun	yes	Runs of the visible channels whose interval from `queued_at` to `finished_at` (now for an unfinished run) intersects the range, ordered by `queued_at`, then `run_id`; at most `stats.timeline_max_runs`.
`runs_truncated`	boolean	yes	True when more runs intersect the range than `runs` holds.

StatsSloState¶

Traffic light of one SLO (docs/spec/25-visualization.md, section 6.4).

Type: string

Values: green, amber, red, insufficient_data.

StatsSloEntry¶

Property	Type	Required	Description
`slo`	string	yes	`service/name` of the Sloth file. Example: `bothy-sync/delivery-latency`.
`metric`	StatsMetric	yes
`objective`	number (double)	yes	Objective in percent from the Sloth file.
`threshold_ms`	integer	no	Threshold of a latency SLO; absent for ratio SLOs.
`period_days`	integer	yes
`total`	integer (int64)	yes
`good`	integer (int64)	yes
`ratio`	number (double)	no
`budget_remaining`	number (double)	no	Remaining error budget, `1 - (1 - ratio) / (1 - objective/100)`; may be negative.
`state`	StatsSloState	yes

StatsSloReport¶

Property	Type	Required	Description
`at`	Timestamp	yes
`measured_by`	string	yes	Always `own`; the values come from the own measurement, not from Prometheus. Values: `own`.
`items`	array of StatsSloEntry	yes

StatsBackendCost¶

Property	Type	Required
`billing_mode`	BillingMode	yes
`currency`	string	yes
`amount_micros`	integer (int64)	yes
`is_estimate`	boolean	yes

StatsBackendDenials¶

Property	Type	Required	Description
`i2_denied`	integer (int64)	yes
`billing_mode_mismatch`	integer (int64)	yes

StatsBackendAgent¶

Property	Type	Required	Description
`agent_id`	Uuid	yes
`billing_mode`	BillingMode	yes
`reported_billing_mode`	BillingMode	no
`billing_modes_supported`	array of BillingMode	yes
`switches`	integer (int64)	yes	Billing mode switches in the range.
`invocations_denied`	StatsBackendDenials	yes
`costs`	array of StatsBackendCost	no	Only with `cost.read.aggregate`.
`rate_limit`	AgentRateLimitState	no

StatsBackendReport¶

Property	Type	Required	Description
`items`	array of StatsBackendAgent	yes

GatewayStatsSubscribe¶

Subscribe to stats.live; without space_id the instance (owner). Replaces an earlier subscription of the connection.

Property	Type	Required	Description
`space_id`	Uuid	no

No other properties are allowed.

GatewayStatsUnsubscribe¶

End the stats.live subscription of the connection.

Type: object

No other properties are allowed.

StatsLiveEvent¶

Ephemeral event stats.live (no seq, at most once), only to connections with a subscription.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `stats.live`.
`payload`	StatsLiveFrame	yes

StatsGranularity¶

Size of a statistics bucket.

Type: string

Values: hour, day, week, month.

IdentityProviderKind¶

Kind of identity provider (B9).

Type: string

Values: oidc, trusted_header, local.

ForumSort¶

Sort order of forum posts.

Type: string

Values: last_activity, created.

AgentRuntimeState¶

State derived from heartbeats.

Type: string

Values: unknown, online, degraded, offline.

SigningKeyPurpose¶

Purpose of a server signing key (03 server_signing_keys.purpose). terminal signs terminal session tokens (24 section 5.3); audit_checkpoint signs audit checkpoints (19 SEC-AUD-7).

Type: string

Values: access_token, invocation, terminal, webhook_out, audit_checkpoint.

UserStatus¶

Type: string

Values: pending, active, disabled, deleted.

GroupSource¶

Type: string

Values: local, oidc_claim.

LevelOrNone¶

Level including none for no access.

Type: string

Values: none, read, write, trigger.

AccessTargetKind¶

host appears only in access.changed and access.expiring (terminal capability, no level).

Type: string

Values: space, channel, host.

OperatorMode¶

inherit takes the default operator of the space (channels only).

Type: string

Values: inherit, none, agent.

ThreadState¶

Type: string

Values: open, closed.

TranscriptStatus¶

Type: string

Values: none, pending, done, failed.

TranscriptSource¶

Type: string

Values: agent, service.

SearchHitKind¶

Type: string

Values: message, thread, file.

PushProvider¶

Type: string

Values: apns, fcm, unifiedpush, wns.

PushEnvironment¶

Type: string

Values: production, sandbox.

ComponentType¶

Type: string

Values: button, select, form.

ComponentRestriction¶

run_starter: only the person who started the run, or an owner. owner: only owners.

Type: string

Values: any, run_starter, owner.

CommandLevel¶

Type: string

Values: write, trigger.

WebhookDeliveryStatus¶

Type: string

Values: pending, succeeded, failed, dead.

AuditDecision¶

Type: string

Values: allow, deny, error.

PriceUnit¶

Type: string

Values: input_mtok, output_mtok, cache_read_mtok, cache_write_mtok, cache_write_1h_mtok, request.

StatusIncidentKind¶

Type: string

Values: incident, maintenance.

StatusIncidentImpact¶

Type: string

Values: none, minor, major, critical.

ImportKind¶

Type: string

Values: discord, archive.

ImportItemState¶

Type: string

Values: pending, posted, skipped, failed.

ImportObject¶

Property	Type	Required	Description
`origin_key`	string	yes	Example: `message:1029384756`.
`item_kind`	string	yes	Values: `space`, `channel`, `forum_tag`, `thread`, `message`, `user`, `pin`.
`content_sha256`	string	no	Hex SHA-256 of the converted content; a different value on a later run is counted as changed at the source.
`data`	JsonObject	yes	Fields of the target object, schema `import_object.<item_kind>.v1` (22, sections 5 and 6). Structure items use `ImportSpaceData` (`space`), `ImportChannelData` (`channel`), `ImportForumTagData` (`forum_tag`) and `ImportUserData` (`user`); content items `ImportThreadData` (`thread`), `ImportMessageData` (`message`) and `ImportPinData` (`pin`).

No other properties are allowed.

ImportBatch¶

One transaction. Objects of one thread, in source order; structure objects (space, channel, forum tag, person) come in batches without thread_origin_key.

Property	Type	Required	Description
`thread_origin_key`	string	no	`thread:<id>` for a thread or forum post, `channel:<id>` for the main thread of a text channel; absent for a structure batch. Example: `thread:1029384700`.
`items`	array of ImportObject	yes	At most `import.batch_max_items`. Min items 1; max items 100.

No other properties are allowed.

ImportBatchResult¶

Property	Type	Required	Description
`items`	array of ImportItem	yes
`unread_floor_seq`	integer (int64)	no	New `threads.unread_floor_seq` of the thread of this batch.

ImportFileCreate¶

Property	Type	Required	Description
`origin_key`	string	yes	Example: `file:1029384799`.
`channel_id`	Uuid	yes
`author_id`	Uuid	yes
`name`	string	yes	Example: `report.pdf`.
`size_bytes`	integer (int64)	yes	Minimum 1.
`sha256`	string	yes	Lowercase hex SHA-256 of the bytes (`file_upload_sessions.declared_sha256`); the scan checks the bytes against it. Pattern `^[0-9a-f]{64}$`.
`declared_mime_type`	string	no	Example: `application/pdf`.

No other properties are allowed.

ImportFileSlot¶

The pending item reserves the file ID; a repeated call with the same key returns the same ID (22, 7.2).

Property	Type	Required	Description
`item`	ImportItem	yes
`upload`	UploadSession	no	Absent when the file is already `posted`. Its part URLs name `uploadImportFilePart`.

ImportThreadData¶

Data of a thread item (22, 5.1.1). The title is name cut to thread.title_max_chars, title_source is auto for a placeholder name and manual otherwise; the operator is the planned operator of the channel in the mapping; parent_message_id is the starter message only when its item is posted in the main thread of the same channel; the tags are the posted forum_tag items of the same channel. A posted thread only follows the mirror rules of 22 12.2 step 3.

Property	Type	Required	Description
`channel_origin_key`	string	yes	Example: `channel:1029384600`.
`name`	string	yes	Example: `Login fails on mobile`.
`created_at`	Timestamp	yes
`last_activity_at`	Timestamp	yes
`closed`	boolean	yes	The archive rule of the tool (22 5.1.1, R-IM-11).
`closed_at`	Timestamp	no	Required exactly when `closed` is true.
`starter_message_origin_key`	string	no	Example: `message:1029384700`.
`tag_origin_keys`	array of string	no
`earlier_session`	ImportEarlierSession	no

No other properties are allowed.

ImportEarlierSession¶

The agent session the thread had before the migration (22, 9 step 1; --sessions of the tool). The server writes one earlier agent_sessions row (is_current = false, started = true, ended_at = the time of the batch, end_reason = import, the cost baseline) exactly once per thread, agent and reference, also for a thread posted by an earlier run, and never after the thread has had a current session; the item member session names the outcome. agent_id must be the operator of the thread (threads.operator_agent_id), else 400 validation_failed at /items/<i>/data/earlier_session/agent_id. The reference is opaque, at most agent.session_ref_max_bytes bytes, and is never logged.

Property	Type	Required	Description
`agent_id`	Uuid	yes
`external_session_ref`	string	yes	Min length 1. Example: `sess-7f3a`.
`cost_baseline_micros`	integer (int64)	no	The cumulative amount of the external session before the binding, in micro units of `currency` (22, 9 step 7); absent means 0. Minimum 0; maximum 9007199254740991. Example: `1250000`.
`currency`	string	no	ISO 4217 code of `cost_baseline_micros`; required when it is above 0. Pattern `^[A-Z]{3}$`. Example: `USD`.

No other properties are allowed.

ImportMessageData¶

Data of a message item (22, 6.2). The message gets origin = import, kind = text, silent, no mentions and no trigger_state; content_md is stored as given (at most message.max_content_bytes, never split); the reply target must be a posted message of the same thread; the files must be posted file items of this source uploaded for the channel of the thread by the author, at most message.max_attachments.

Property	Type	Required	Description
`author_origin_key`	string	yes	Example: `user:1029384000`.
`content_md`	string	yes	Example: `The invoice export fails.`.
`created_at`	Timestamp	yes
`edited_at`	Timestamp	no
`reply_to_origin_key`	string	no	Example: `message:1029384701`.
`attachment_file_ids`	array of Uuid	no

No other properties are allowed.

ImportPinData¶

Data of a pin item (22, 6.6); pinned_by is the importing owner.

Property	Type	Required	Description
`message_origin_key`	string	yes	Example: `message:1029384756`.

No other properties are allowed.

ImportCursorSet¶

Property	Type	Required	Description
`cursor`	JsonObject	yes	Progress per source channel and thread; only after a successful batch.
`stats`	JsonObject	no

No other properties are allowed.

ImportLeadSet¶

Property	Type	Required	Description
`source_channel`	string	yes	ID of the channel in the source. Example: `1029384000`.
`lead`	string	yes	`discord`: the source leads, the channel here is read-only and mirrored; `bothy`: this server leads (22, 12.1). Values: `discord`, `bothy`.

No other properties are allowed.

ImportSourceDiscordConfig¶

Mapping file of schema import_source.discord.v1 as JSON (22, 5.2); the web console converts the YAML of the owner. It holds no secret.

Property	Type	Required	Description
`version`	integer	yes	Values: `1`.
`guild_id`	ImportDiscordId	yes
`defaults`	object	yes
`defaults.unmapped_human`	string	yes	Values: `placeholder`, `skip`.
`defaults.unmapped_bot`	string	yes	Values: `placeholder`, `skip`.
`defaults.uncategorized_space`	string	yes	`skip` or the `discord_category` of an entry in `spaces`. Example: `skip`.
`spaces`	array of object	no
`spaces[].discord_category`	ImportDiscordId	yes
`spaces[].target`	ImportMappingTarget	yes
`channels`	array of object	no
`channels[].discord_channel`	ImportDiscordId	yes
`channels[].target`	ImportMappingTarget	yes
`channels[].planned_operator`	string	no	`agent:<handle>` of an active agent or `none` (default). Example: `agent:lotse`.
`channels[].lead`	string	no	Values: `discord`, `bothy`. Default: `discord`.
`users`	array of object	no
`users[].discord_user`	ImportDiscordId	yes
`users[].target`	string	yes	`user:<handle>`, `agent:<handle>` or `placeholder`. Example: `user:alex`.

No other properties are allowed.

ImportDiscordId¶

A Discord snowflake as a string of digits.

Type: string

Pattern ^[0-9]+$. Example: 1029384000.

ImportMappingTarget¶

Exactly one of the string skip, {create: {name}} or {existing: <uuid>} (22, 5.2). The server checks the form and reports a violation at the pointer of the member.

Type: any

ImportSpaceData¶

data of a space item (origin key space:<category_id>). Exactly one of name (a new space as the mapping says create) and existing_space_id (equal to the mapping's existing).

Property	Type	Required	Description
`name`	string	no
`sort_key`	string	yes	Fractional index key of the space order, derived by the tool from the Discord `position`. Example: `a0`.
`existing_space_id`	Uuid	no

No other properties are allowed.

ImportChannelData¶

data of a channel item (origin key channel:<channel_id>). The space is the target of the posted item space_origin_key or, without it, of the category named in defaults.uncategorized_space; existing_space_id and existing_channel_id must equal the stored mapping. read_only is not a member: the server derives it from the stored lead.

Property	Type	Required	Description
`space_origin_key`	string	no	Example: `space:1029384001`.
`existing_space_id`	Uuid	no
`name`	string	no
`kind`	string	yes	Values: `text`, `forum`.
`topic`	string	no
`sort_key`	string	yes	Fractional index key of the order in the space. Example: `a0`.
`existing_channel_id`	Uuid	no

No other properties are allowed.

ImportForumTagData¶

data of a forum_tag item (origin key forum_tag:<channel_id>:<tag_id>). A tag with the same name, without regard to case, is adopted (22, 6.6). emoji is accepted and not stored (forum tags have no emoji).

Property	Type	Required	Description
`channel_origin_key`	string	yes	Example: `channel:1029384000`.
`name`	string	yes
`emoji`	string	no

No other properties are allowed.

ImportUserData¶

data of a user item (origin key user:<user_id>). The target comes from the stored mapping and its defaults; a webhook author is always a placeholder (22, 5.3).

Property	Type	Required	Description
`discord_kind`	string	yes	Values: `user`, `bot`, `webhook`.
`username`	string	yes
`global_name`	string	no

No other properties are allowed.

GdprRequestKind¶

Type: string

Values: export, deletion, rectification.

GdprRequestState¶

Type: string

Values: requested, approved, running, completed, failed, rejected, cancelled.

MessageCreatedEvent¶

Durable event message.created.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `message.created`.
`payload`	MessagePayload	yes

MessageUpdatedEvent¶

Durable event message.updated.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `message.updated`.
`payload`	MessagePayload	yes

MessageDeletedEvent¶

Durable event message.deleted.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `message.deleted`.
`payload`	MessageDeletedPayload	yes

ReactionAddedEvent¶

Durable event reaction.added.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `reaction.added`.
`payload`	ReactionPayload	yes

ReactionRemovedEvent¶

Durable event reaction.removed.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `reaction.removed`.
`payload`	ReactionPayload	yes

PinAddedEvent¶

Durable event pin.added.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `pin.added`.
`payload`	PinPayload	yes

PinRemovedEvent¶

Durable event pin.removed.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `pin.removed`.
`payload`	PinPayload	yes

ThreadCreatedEvent¶

Durable event thread.created.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `thread.created`.
`payload`	ThreadPayload	yes

ThreadUpdatedEvent¶

Durable event thread.updated.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `thread.updated`.
`payload`	ThreadPayload	yes

ThreadClosedEvent¶

Durable event thread.closed.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `thread.closed`.
`payload`	ThreadPayload	yes

ThreadReopenedEvent¶

Durable event thread.reopened.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `thread.reopened`.
`payload`	ThreadPayload	yes

ThreadMovedEvent¶

Durable event thread.moved.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `thread.moved`.
`payload`	ThreadMovedPayload	yes

ThreadMovedOutEvent¶

Durable event thread.moved_out.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `thread.moved_out`.
`payload`	ThreadMovedOutPayload	yes

AgentSessionChangedEvent¶

Durable event agent_session.changed.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `agent_session.changed`.
`payload`	AgentSessionChangedPayload	yes

RunStateChangedEvent¶

Durable event run.state_changed.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `run.state_changed`.
`payload`	RunStateChangedPayload	yes

SpaceCreatedEvent¶

Durable event space.created.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `space.created`.
`payload`	SpacePayload	yes

SpaceUpdatedEvent¶

Durable event space.updated.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `space.updated`.
`payload`	SpacePayload	yes

SpaceArchivedEvent¶

Durable event space.archived.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `space.archived`.
`payload`	SpacePayload	yes

ChannelCreatedEvent¶

Durable event channel.created.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `channel.created`.
`payload`	ChannelPayload	yes

ChannelUpdatedEvent¶

Durable event channel.updated.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `channel.updated`.
`payload`	ChannelPayload	yes

ChannelSettingsChangedEvent¶

Durable event channel.settings_changed.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `channel.settings_changed`.
`payload`	ChannelSettingsChangedPayload	yes

ChannelArchivedEvent¶

Durable event channel.archived.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `channel.archived`.
`payload`	ChannelPayload	yes

CommandChangedEvent¶

Durable event command.changed.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `command.changed`.
`payload`	CommandChangedPayload	yes

FileUpdatedEvent¶

Durable event file.updated.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `file.updated`.
`payload`	FilePayload	yes

UserUpdatedEvent¶

Durable event user.updated.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `user.updated`.
`payload`	UserPayload	yes

AgentUpdatedEvent¶

Durable event agent.updated.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `agent.updated`.
`payload`	AgentPayload	yes

InstanceUpdatedEvent¶

Durable event instance.updated.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `instance.updated`.
`payload`	InstanceUpdatedPayload	yes

StatusUpdatedEvent¶

Durable event status.updated.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `status.updated`.
`payload`	StatusUpdatedPayload	yes

GrantChangedEvent¶

Durable event grant.changed.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `grant.changed`.
`payload`	GrantChangedPayload	yes

GroupChangedEvent¶

Durable event group.changed.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `group.changed`.
`payload`	GroupChangedPayload	yes

AccessChangedEvent¶

Durable event access.changed.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `access.changed`.
`payload`	AccessChangedPayload	yes

AccessExpiringEvent¶

Durable event access.expiring.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `access.expiring`.
`payload`	AccessExpiringPayload	yes

DevicePendingEvent¶

Durable event device.pending.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `device.pending`.
`payload`	DevicePendingPayload	yes

SessionRevokedEvent¶

Durable event session.revoked.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `session.revoked`.
`payload`	SessionRevokedPayload	yes

ReadStateUpdatedEvent¶

Durable event read_state.updated.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `read_state.updated`.
`payload`	ReadStatePayload	yes

DraftUpdatedEvent¶

Durable event draft.updated.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `draft.updated`.
`payload`	DraftPayload	yes

DraftDeletedEvent¶

Durable event draft.deleted.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `draft.deleted`.
`payload`	DraftDeletedPayload	yes

SettingsUpdatedEvent¶

Durable event settings.updated.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `settings.updated`.
`payload`	SettingsPayload	yes

SidebarUpdatedEvent¶

Durable event sidebar.updated.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `sidebar.updated`.
`payload`	SidebarPayload	yes

NotificationPrefUpdatedEvent¶

Durable event notification_pref.updated.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `notification_pref.updated`.
`payload`	NotificationPrefPayload	yes

QuietHoursUpdatedEvent¶

Durable event quiet_hours.updated.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `quiet_hours.updated`.
`payload`	QuietHoursPayload	yes

GdprRequestUpdatedEvent¶

Durable event gdpr.request_updated.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `gdpr.request_updated`.
`payload`	GdprRequestPayload	yes

GdprRequestDueEvent¶

Durable event gdpr.request_due.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `gdpr.request_due`.
`payload`	GdprRequestDuePayload	yes

ImportProgressEvent¶

Durable event import.progress.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `import.progress`.
`payload`	ImportProgressPayload	yes

AgentInvocationEvent¶

Durable event agent.invocation.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `agent.invocation`.
`payload`	AgentInvocationPayload	yes

AgentFollowupEvent¶

Durable event agent.followup.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `agent.followup`.
`payload`	AgentFollowupPayload	yes

RunCancelRequestedEvent¶

Durable event run.cancel_requested.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `run.cancel_requested`.
`payload`	RunCancelRequestedPayload	yes

InteractionCreatedEvent¶

Durable event interaction.created.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `interaction.created`.
`payload`	InteractionCreatedPayload	yes

CommandInvokedEvent¶

Durable event command.invoked.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `command.invoked`.
`payload`	CommandInvokedPayload	yes

AgentConfigChangedEvent¶

Durable event agent.config_changed.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `agent.config_changed`.
`payload`	AgentConfigChangedPayload	yes

TypingStartedEvent¶

Ephemeral event typing.started (no seq, at most once).

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `typing.started`.
`payload`	TypingStartedPayload	yes

RunUpdatedEvent¶

Ephemeral event run.updated (no seq, at most once).

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `run.updated`.
`payload`	RunUpdatedPayload	yes

AgentPresenceChangedEvent¶

Ephemeral event agent.presence_changed (no seq, at most once).

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `agent.presence_changed`.
`payload`	AgentPresencePayload	yes

CommandAutocompleteRequestedEvent¶

Ephemeral event command.autocomplete_requested (no seq, at most once).

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `command.autocomplete_requested`.
`payload`	CommandAutocompleteRequestedPayload	yes

NotificationCreatedEvent¶

Ephemeral event notification.created (no seq, at most once), only to connections of the recipient instead of a push (13, 6.3).

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `notification.created`.
`payload`	NotificationCreatedPayload	yes

NotificationCreatedPayload¶

Property	Type	Required	Description
`nid`	Uuid	yes
`kind`	NotificationKind	yes
`thread_id`	Uuid	no	Thread of the hint; absent for hints without a thread.
`message_id`	Uuid	no	Message the hint points at; absent when the hint points at no message.
`target_id`	Uuid	no	Target of a hint without a thread: the waiting device for `security`, the grant or group of the reminder for `admin` (R-AZ-30).
`quiet`	boolean	yes	Inside quiet hours; show without sound.
`count`	integer	yes	1, or the unread count of a bundled hint (13 4.5).
`space_name`	string	no
`channel_name`	string	no
`thread_title`	string	no
`sender_display_name`	string	no
`excerpt`	string	no	Plain text, at most `notify.preview_max_chars`; only with `notify.preview_mode = full`.
`attachment_count`	integer	no
`image_url`	string (uri-reference)	no	Fetch ticket for the `small` variant of the first image.

NotificationKind¶

Type: string

Values: message, mention, dm, run_done, run_failed, input_needed, security, admin.

PushPreview¶

Preview for the notification extension, fields depend on notify.preview_mode (13, 6.4).

Property	Type	Required	Description
`kind`	NotificationKind	yes
`thread_id`	Uuid	no
`message_id`	Uuid	no
`badge`	integer	yes
`space_name`	string	no
`channel_name`	string	no
`thread_title`	string	no
`sender_display_name`	string	no
`excerpt`	string	no
`attachment_count`	integer	no
`image_url`	string (uri-reference)	no	Fetch ticket for the `small` variant of the first image.

Event¶

Any durable event, discriminated by type. Clients skip unknown types and still advance their cursor.

One of: MessageCreatedEvent, MessageUpdatedEvent, MessageDeletedEvent, ReactionAddedEvent, ReactionRemovedEvent, PinAddedEvent, PinRemovedEvent, ThreadCreatedEvent, ThreadUpdatedEvent, ThreadClosedEvent, ThreadReopenedEvent, ThreadMovedEvent, ThreadMovedOutEvent, AgentSessionChangedEvent, RunStateChangedEvent, SpaceCreatedEvent, SpaceUpdatedEvent, SpaceArchivedEvent, ChannelCreatedEvent, ChannelUpdatedEvent, ChannelSettingsChangedEvent, ChannelArchivedEvent, CommandChangedEvent, FileUpdatedEvent, UserUpdatedEvent, AgentUpdatedEvent, InstanceUpdatedEvent, StatusUpdatedEvent, GrantChangedEvent, GroupChangedEvent, AccessChangedEvent, AccessExpiringEvent, DevicePendingEvent, SessionRevokedEvent, ReadStateUpdatedEvent, DraftUpdatedEvent, DraftDeletedEvent, SettingsUpdatedEvent, SidebarUpdatedEvent, NotificationPrefUpdatedEvent, QuietHoursUpdatedEvent, GdprRequestUpdatedEvent, GdprRequestDueEvent, ImportProgressEvent, AgentInvocationEvent, AgentFollowupEvent, RunCancelRequestedEvent, InteractionCreatedEvent, CommandInvokedEvent, AgentConfigChangedEvent, HostUpdatedEvent, TerminalSessionChangedEvent

Discriminator: type

MentionItemPage¶

One page. next_cursor is absent on the last page.

Property	Type	Required	Description
`items`	array of MentionItem	yes
`next_cursor`	Cursor	no

UserPage¶

One page. next_cursor is absent on the last page.

Property	Type	Required	Description
`items`	array of User	yes
`next_cursor`	Cursor	no

DevicePage¶

One page. next_cursor is absent on the last page.

Property	Type	Required	Description
`items`	array of Device	yes
`next_cursor`	Cursor	no

SessionPage¶

One page. next_cursor is absent on the last page.

Property	Type	Required	Description
`items`	array of Session	yes
`next_cursor`	Cursor	no

ApiTokenPage¶

One page. next_cursor is absent on the last page.

Property	Type	Required	Description
`items`	array of ApiToken	yes
`next_cursor`	Cursor	no

GroupPage¶

One page. next_cursor is absent on the last page.

Property	Type	Required	Description
`items`	array of Group	yes
`next_cursor`	Cursor	no

GroupMemberPage¶

One page. next_cursor is absent on the last page.

Property	Type	Required	Description
`items`	array of GroupMember	yes
`next_cursor`	Cursor	no

PermissionHintKind¶

Kind of a permission hint (07 section 9.5), in the order of the list.

Type: string

Values: h1_read_horizon, grant_to_disabled, trigger_blocked, agent_personal.

PermissionHint¶

One permission hint. h1_read_horizon names agent_id, person_id, space_id and channel_id (the person can learn content of the channel through the agent, 07 section 6). grant_to_disabled and trigger_blocked carry the grant; trigger_blocked names the blocking rules (SR2 tool class, SR3 dev isolation). agent_personal names agent_id, credential_holder_id (absent when the agent has none) and the trigger_set (I1 asks for exactly the holder).

Property	Type	Required	Description
`kind`	PermissionHintKind	yes
`agent_id`	Uuid	no
`person_id`	Uuid	no
`space_id`	Uuid	no
`channel_id`	Uuid	no
`grant`	Grant	no
`rules`	array of string	no	Values: `sr2`, `sr3`.
`credential_holder_id`	Uuid	no
`trigger_set`	array of Uuid	no	The people with effective `trigger` on a target the agent serves, ascending.

AccessLabel¶

Name of a group or space named on a page.

Property	Type	Required	Description
`id`	Uuid	yes
`name`	string	yes	Example: `Support`.

ChannelLabel¶

Name and space of a channel named on a page.

Property	Type	Required	Description
`id`	Uuid	yes
`space_id`	Uuid	yes
`name`	string	yes	Example: `Intern`.

AccessLabels¶

The names of the principals, groups, spaces and channels a page of hints or expiring access names, as the administration lists show them; never content.

Property	Type	Required
`principals`	array of PrincipalRef	yes
`groups`	array of AccessLabel	yes
`spaces`	array of AccessLabel	yes
`channels`	array of ChannelLabel	yes

PermissionHintPage¶

One page. next_cursor is absent on the last page.

Property	Type	Required
`items`	array of PermissionHint	yes
`labels`	AccessLabels	yes
`next_cursor`	Cursor	no

ExpiringAccessItem¶

One access that expires within authz.expiry_reminder_lead. grant carries the grant; membership names membership_id, group_id and user_id; token names token_id and the holder principal_id (an agent or an app), never the token value.

Property	Type	Required	Description
`kind`	string	yes	Values: `grant`, `membership`, `token`.
`expires_at`	Timestamp	yes
`grant`	Grant	no
`membership_id`	Uuid	no
`group_id`	Uuid	no
`user_id`	Uuid	no
`token_id`	Uuid	no
`principal_id`	Uuid	no

ExpiringAccessPage¶

One page. next_cursor is absent on the last page.

Property	Type	Required
`items`	array of ExpiringAccessItem	yes
`labels`	AccessLabels	yes
`next_cursor`	Cursor	no

GrantPage¶

One page. next_cursor is absent on the last page.

Property	Type	Required	Description
`items`	array of Grant	yes
`next_cursor`	Cursor	no

SpaceViewList¶

Property	Type	Required	Description
`items`	array of SpaceView	yes

ChannelViewList¶

Property	Type	Required	Description
`items`	array of ChannelView	yes

ThreadPage¶

One page. next_cursor is absent on the last page.

Property	Type	Required	Description
`items`	array of Thread	yes
`next_cursor`	Cursor	no

RunSummaryPage¶

One page. next_cursor is absent on the last page.

Property	Type	Required	Description
`items`	array of RunSummary	yes
`next_cursor`	Cursor	no

PinList¶

Property	Type	Required	Description
`items`	array of Pin	yes

ReactionPage¶

One page. next_cursor is absent on the last page.

Property	Type	Required	Description
`items`	array of Reaction	yes
`next_cursor`	Cursor	no

SearchHitPage¶

One page. next_cursor is absent on the last page.

Property	Type	Required	Description
`items`	array of SearchHit	yes
`next_cursor`	Cursor	no
`candidates_capped`	boolean	no	The candidate limit `search.max_candidates` was reached; ask for a narrower query.

ThreadTitleHitList¶

Property	Type	Required	Description
`items`	array of object	yes
`items[].thread_id`	Uuid	yes
`items[].channel_id`	Uuid	yes
`items[].title`	string	yes	Example: `Invoice export fails`.
`items[].last_activity_at`	Timestamp	yes

AgentPage¶

One page. next_cursor is absent on the last page.

Property	Type	Required	Description
`items`	array of Agent	yes
`next_cursor`	Cursor	no

AgentChannelConfigList¶

Property	Type	Required	Description
`items`	array of AgentChannelConfig	yes

AppPage¶

One page. next_cursor is absent on the last page.

Property	Type	Required	Description
`items`	array of App	yes
`next_cursor`	Cursor	no

WebhookDeliveryPage¶

One page. next_cursor is absent on the last page.

Property	Type	Required	Description
`items`	array of WebhookDelivery	yes
`next_cursor`	Cursor	no

AuditEventPage¶

One page. next_cursor is absent on the last page.

Property	Type	Required	Description
`items`	array of AuditEvent	yes
`next_cursor`	Cursor	no

ImportSourcePage¶

One page. next_cursor is absent on the last page.

Property	Type	Required	Description
`items`	array of ImportSource	yes
`next_cursor`	Cursor	no

ImportItemPage¶

One page. next_cursor is absent on the last page.

Property	Type	Required	Description
`items`	array of ImportItem	yes
`next_cursor`	Cursor	no

GdprRequestPage¶

One page. next_cursor is absent on the last page.

Property	Type	Required	Description
`items`	array of GdprRequest	yes
`next_cursor`	Cursor	no

HostState¶

Life cycle of a host (24, 3.1). Only active allows sessions.

Type: string

Values: pairing, confirming, active, disabled, retired.

LlmCredentials¶

Owner declaration of the LLM login on a host (24, 7.2). personal needs credential_holder_id (I6).

Type: string

Values: none, personal, organization.

HostPlatform¶

Type: string

Values: macos, linux, windows.

HostProfile¶

Profile reported by the host service (host_profiles.v1). Never a command line, path or environment.

Property	Type	Required	Description
`name`	string	yes	Pattern `^[a-z0-9][a-z0-9_-]*$`. Example: `shell`.
`display_name`	string	yes	Example: `Shell`.
`kind`	string	yes	Values: `shell`, `claude`, `command`.

No other properties are allowed.

HostDoctorCheck¶

Result of one self-check of the host service (host_doctor.v1, checks HD1 to HD11 in 24, 2.2). Codes and, following the rule for names (24, 2.2), the name of each account a person with a terminal can cause the finding in; never content, paths or values. When HD6 or HD11 fails, the list has one entry per affected session user; when HD10 fails with a wrong peer, one entry per session user of that channel; when HD9 fails, one entry per former session user whose home can be listed, plus one entry without a name for any other user; check and session_user together are unique in the list.

Property	Type	Required	Description
`check`	string	yes	Values: `hd1_user`, `hd2_groups`, `hd3_sudo`, `hd4_state_dir`, `hd5_server_host`, `hd6_llm_login`, `hd7_profiles`, `hd8_separation`, `hd9_foreign_homes`, `hd10_helper_integrity`, `hd11_shared_locations`.
`ok`	boolean	yes
`code`	string	no	Pattern `^[a-z0-9_]+$`. Example: `subscription_login_detected`.
`session_user`	string	no	Only when not passed: the account the rule for names gives (see the schema; 24, 2.2 and 7.4). A name, never a path. Pattern `^[A-Za-z0-9_][A-Za-z0-9_.-]*$`. Example: `bothy-s-robin`.

HostSessionUserAssign¶

Assigns a person their own session user on a host (ruling T12, 24 section 2.2). The name must be one the host reported (reported_session_users); any other name gives 400 validation_failed with errors[].code session_user_not_on_host, and nothing is stored.

Property	Type	Required	Description
`user_id`	Uuid	yes
`os_user`	string	yes	Operating system user name from `host_service.session_users`; at most `host.os_user_max_chars` characters; never a path. Pattern `^[A-Za-z0-9_][A-Za-z0-9_.-]*$`. Example: `bothy-s-robin`.

No other properties are allowed.

HostSessionUser¶

A valid assignment of a person to their own session user on the host (ruling T12, 24 section 2.2).

Property	Type	Required	Description
`user_id`	Uuid	yes
`os_user`	string	yes	Example: `bothy-s-robin`.
`created_at`	Timestamp	yes

HostReportedSessionUser¶

A session user the host service reports (host_reported_session_users.v1, 24 section 2.2), with the display names of its own working directories of the claude profile (ruling T13). Names only, never paths.

Property	Type	Required	Description
`os_user`	string	yes	Operating system user name from `host_service.session_users`. Pattern `^[A-Za-z0-9_][A-Za-z0-9_.-]*$`. Example: `bothy-s-robin`.
`workdirs`	array of string	yes	Display names of the working directories of this session user in `host_service.claude_workdirs` after check HD7, in their order (a directory listed under two session users is dropped from both lists); empty means no `claude` profile for this session user. A client sends the index into its own list, never a path; the host service resolves the index in exactly this list (24, 2.2 and 5.3).

No other properties are allowed.

Host¶

A connected host. Keys are public; the client pins noise_public_key per device (24, 5.5).

Property	Type	Required	Description
`id`	Uuid	yes
`name`	string	yes	Example: `Build server`.
`state`	HostState	yes
`disabled_reason`	string	no	Present exactly with `state = disabled`. `duplicate_connection` means a second live control connection with the same keys; only re-pairing helps (24, 3.4). Values: `owner`, `duplicate_connection`.
`platform`	HostPlatform	no
`assigned_user_id`	Uuid	no	Person the host is assigned to (SR10); absent means owners only.
`llm_credentials`	LlmCredentials	yes
`credential_holder_id`	Uuid	no	Present exactly with `llm_credentials = personal`.
`declared_server_host`	boolean	yes
`reported_is_server_host`	boolean	no	Report of the host service (24, 2.3); absent before the first report.
`noise_public_key`	string	no	Static X25519 key of the host, 32 bytes base64url without padding; absent while the host has no keys (before pairing and after a re-pairing or the fallback of `confirmHost`). Example: `Zm9vYmFyZm9vYmFyZm9vYmFyZm9vYmFyZm9vYmFyMTI`.
`key_fingerprint`	string	no	Fingerprint of the stored keys (24, 4.3), 13 groups of four Crockford base32 characters; absent while the host has no keys. Example: `7K2Q-M9XD-0000-0000-0000-0000-0000-0000-0000-0000-0000-0000-0000`.
`key_generation`	integer	yes	Example: `1`.
`profiles`	array of HostProfile	yes
`doctor`	array of HostDoctorCheck	yes	One entry per check HD1 to HD11; a failed HD6, HD9, HD10 or HD11 has one entry per account named by the rule for names (24, 2.2).
`session_users`	array of HostSessionUser	no	Valid session user assignments (ruling T12), visible like every other member to everyone with `host.read`. Absent when there is none.
`reported_session_users`	array of HostReportedSessionUser	no	Session users the host service reported at pairing and in its last `report` (24 section 2.2). An assignment works only while its name is in this list (SR12); `confirmHost` and `updateHost` accept only these names. Absent before pairing.
`require_local_confirm`	boolean	no	Report whether `host_service.require_local_confirm` is on.
`connected`	boolean	yes	Usable for sessions, from the first `report` after `ready` to the end of the control connection (24, 3.5).
`host_version`	string	no	Example: `1.0.0`.
`os_version`	string	no	Example: `Debian 13`.
`last_seen_at`	Timestamp	no
`created_at`	Timestamp	yes
`version`	integer (int64)	yes

HostPage¶

One page. next_cursor is absent on the last page.

Property	Type	Required	Description
`items`	array of Host	yes
`next_cursor`	Cursor	no

HostCreate¶

Property	Type	Required	Description
`name`	string	yes	Example: `Build server`.
`assigned_user_id`	Uuid	no
`reason`	string	yes	Example: `Shared build machine for Alex`.

No other properties are allowed.

HostPairingCode¶

The pairing code is shown exactly once; the server stores only its HMAC.

Property	Type	Required	Description
`host_id`	Uuid	yes
`pairing_code`	string	yes	Pattern `^bothy_hpc_[0-9A-Za-z]{43}_[0-9A-Za-z]{6}$`. Example: `bothy_hpc_EXAMPLE000000000000000000000000000000000000_EXAMPL`.
`expires_at`	Timestamp	yes

HostPairRequest¶

Property	Type	Required	Description
`pairing_code`	string	yes	Pattern `^bothy_hpc_[0-9A-Za-z]{43}_[0-9A-Za-z]{6}$`.
`noise_public_key`	string	yes	Static X25519 public key, 32 bytes base64url without padding.
`auth_public_jwk`	JsonObject	yes	Ed25519 public key as JWK (`kty = OKP`, `crv = Ed25519`); a private member is rejected.
`platform`	HostPlatform	yes
`os_version`	string	no
`host_version`	string	yes	Example: `1.0.0`.
`profiles`	array of HostProfile	yes
`session_users`	array of HostReportedSessionUser	yes	The session users of `host_service.session_users` with the display names of their working directories (24 section 2.2).

No other properties are allowed.

HostPairResult¶

Property	Type	Required
`host_id`	Uuid	yes
`key_fingerprint`	string	yes
`instance_id`	Uuid	yes

HostUpdate¶

Members that are absent stay unchanged. To remove the assignee send clear_assigned_user (no JSON null, ADR 0053).

Property	Type	Required	Description
`name`	string	no
`assigned_user_id`	Uuid	no
`clear_assigned_user`	boolean	no
`add_session_users`	array of HostSessionUserAssign	no	New session user assignments (ruling T12).
`revoke_session_users`	array of Uuid	no	People whose session user assignment ends; their names stay taken on this host.
`reason`	string	yes

No other properties are allowed.

HostConfirm¶

Property	Type	Required	Description
`fingerprint_prefix`	string	yes	First `terminal.fingerprint_confirm_chars` characters of the fingerprint without separators, case-insensitive. Example: `7K2QM9XD`.
`llm_credentials`	LlmCredentials	yes
`credential_holder_id`	Uuid	no
`declared_server_host`	boolean	yes
`session_users`	array of HostSessionUserAssign	no	Session user per person (ruling T12); a person without one gets no terminal on the host (SR12).
`reason`	string	yes

No other properties are allowed.

HostLlmCredentialsSet¶

Property	Type	Required	Description
`llm_credentials`	LlmCredentials	yes
`credential_holder_id`	Uuid	no	Required exactly with `personal`. `errors[].code` `required` when missing with `personal`, `not_allowed` when sent with `none` or `organization`, `unknown_user` when it names no person or a deleted one.
`reason`	string	yes

No other properties are allowed.

HostStateSet¶

Property	Type	Required	Description
`state`	string	yes	Values: `active`, `disabled`, `retired`.
`reason`	string	yes

No other properties are allowed.

TerminalSessionState¶

Type: string

Values: opening, active, detached, closed.

TerminalCloseReason¶

Why a session ended (24, 10.3).

Type: string

Values: client_closed, closed_by_owner, process_exited, idle_timeout, max_duration, detach_expired, access_revoked, i6_violation, host_disabled, host_retired, host_rekeyed, host_restarted, user_disabled, device_revoked, session_revoked, logout, open_failed, host_policy_violation.

TerminalCloseDetail¶

Type: string

Values: token_invalid, token_expired, token_replayed, handshake_failed, profile_unknown, session_user_unknown, session_user_mismatch, server_host_owner_only, local_confirm_denied, subscription_login_detected, helper_untrusted, shared_location, pty_failed, open_timeout.

TerminalSession¶

Metadata of a terminal session. Never content.

Property	Type	Required	Description
`id`	Uuid	yes
`host_id`	Uuid	yes
`user_id`	Uuid	yes
`device_id`	Uuid	yes
`profile`	string	yes	Example: `shell`.
`state`	TerminalSessionState	yes
`opened_at`	Timestamp	yes
`started_at`	Timestamp	no
`detached_at`	Timestamp	no
`closed_at`	Timestamp	no
`close_reason`	TerminalCloseReason	no
`close_detail`	TerminalCloseDetail	no
`exit_code`	integer	no
`bytes_in`	integer (int64)	yes
`bytes_out`	integer (int64)	yes
`version`	integer (int64)	yes

TerminalSessionPage¶

One page. next_cursor is absent on the last page.

Property	Type	Required	Description
`items`	array of TerminalSession	yes
`next_cursor`	Cursor	no

TerminalSessionOpen¶

Property	Type	Required	Description
`profile`	string	yes	Example: `shell`.
`workdir_index`	integer	no	Required exactly with a `claude` profile: index into `workdirs` of the caller's own entry in `reported_session_users` (ruling T13). A `claude` profile without a valid index, or an index with another profile, gives 403 `terminal_denied` with `reason: profile_unknown`; other profiles omit it. The token carries it as `wdi` (24, 5.3, 11.1). Minimum 0.
`cols`	integer	yes	Minimum 1; maximum 65535.
`rows`	integer	yes	Minimum 1; maximum 65535.
`client_ephemeral_key_hash`	string	yes	SHA-256 of the ephemeral X25519 public key the device sends in Noise message 1, base64url without padding; becomes the claim `cek`. Pattern `^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$`.
`pin_changed`	boolean	no	`true` when the person confirmed a host key that differs from the key this device pinned earlier (docs/spec/24-terminal.md section 5.5, docs/spec/15-client-architecture.md section 23.3); recorded in the audit entry of `terminal.open`. Default: `false`.

No other properties are allowed.

TerminalSessionAttach¶

Property	Type	Required	Description
`cols`	integer	yes	Minimum 1; maximum 65535.
`rows`	integer	yes	Minimum 1; maximum 65535.
`client_ephemeral_key_hash`	string	yes	Pattern `^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$`.
`pin_changed`	boolean	no	Same as in `TerminalSessionOpen`; recorded in the audit entry of `terminal.attach`. Default: `false`.

No other properties are allowed.

TerminalSessionGrant¶

Everything the device needs for the Noise handshake (24, 5). The token is valid once and for terminal.session_token_ttl.

Property	Type	Required	Description
`session`	TerminalSession	yes
`session_token`	string	yes	Compact JWS, `typ = terminal-session+jwt`, `alg = EdDSA`.
`session_token_expires_at`	Timestamp	yes
`stream_path`	string	yes	Example: `/api/v1/terminal/sessions/0192f4a0-7b1c-7b22-9d4f-5a6b7c8d9e0f/stream`.
`noise_public_key`	string	yes
`key_fingerprint`	string	yes
`key_generation`	integer	yes
`noise_protocol`	string	yes	Values: `Noise_NK_25519_ChaChaPoly_SHA256`.
`prologue_version`	string	yes	Values: `bothy-terminal/1`.

HostUpdatedPayload¶

Property	Type	Required	Description
`host`	Host	yes
`key_changed`	boolean	no	True after a re-pairing (24, 3.3).

HostUpdatedEvent¶

Durable event host.updated.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `host.updated`.
`payload`	HostUpdatedPayload	yes

TerminalSessionChangedEvent¶

Durable personal event terminal_session.changed to the person of the session.

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `terminal_session.changed`.
`payload`	TerminalSession	yes

HostPresencePayload¶

Property	Type	Required	Description
`host_id`	Uuid	yes
`connected`	boolean	yes

HostPresenceChangedEvent¶

Ephemeral event host.presence_changed (no seq, at most once).

All of: EventEnvelope

Property	Type	Required	Description
`type`	string	yes	Values: `host.presence_changed`.
`payload`	HostPresencePayload	yes

TerminalStreamHello¶

First text frame of the device stream; the binary Noise frames follow identify.

Property	Type	Required
`protocol_versions`	array of integer	yes
`dpop_nonce`	string	yes
`server_time`	Timestamp	yes

TerminalStreamIdentify¶

Native apps send an access token with DPoP proof (htm = GET, htu = HTTPS form of the stream URL, nonce from hello, ath). The web console sends neither: its stream authenticates with the console session cookie of the upgrade request and the same-origin check of the upgrade (docs/spec/08-identity.md section 7.5, docs/spec/15-client-architecture.md section 23.2); the server rejects an identify without token from any other session. Only the device of the current session token passes (terminal.stream).

Property	Type	Required	Description
`protocol_version`	integer	yes	Example: `1`.
`access_token`	string	no
`dpop`	string	no
`device_id`	Uuid	yes

HostChannelHello¶

First text frame on the control and data connections of a host service. It carries server values the host service applies; the values of the hello of a data connection apply to the session of that connection (24, 5.3, 6.2 and 6.3).

Property	Type	Required	Description
`protocol_versions`	array of integer	yes
`challenge`	string	yes	Random value; the host signs it with its Ed25519 key in `identify`.
`server_time`	Timestamp	yes
`heartbeat_interval_ms`	integer (int64)	yes	Example: `20000`.
`heartbeat_miss_limit`	integer	yes	Minimum 1.
`clock_leeway_ms`	integer (int64)	yes	`auth.clock_leeway` in milliseconds. The host service applies it to the session of this data connection: the tolerance on `exp` of the session token and how long it remembers the `jti` after `exp` (24, 5.3). Minimum 0.
`idle_timeout_ms`	integer (int64)	yes	`terminal.idle_timeout` in milliseconds. The host service applies it to the idle timer of the session of this data connection (24, 6.3). Minimum 1.
`detach_grace_ms`	integer (int64)	yes	`terminal.detach_grace` in milliseconds. The host service applies it to the detach timer of the session of this data connection (24, 6.2). Minimum 1.
`jwks`	Jwks	yes	Public keys with purpose `terminal` for checking session tokens.

HostIdentify¶

Login of a host service. proof is a compact JWS (alg = EdDSA, typ = host-auth+jwt, kid) over exactly {challenge, host_id, iat} with the registered Ed25519 key (24, 3.5).

Property	Type	Required	Description
`protocol_version`	integer	yes	Example: `1`.
`host_id`	Uuid	yes
`proof`	string	yes
`host_version`	string	yes	Pattern `^(0\|[1-9]\d)\.(0\|[1-9]\d)\.(0\|[1-9]\d)(?:-((?:0\|[1-9]\d\|\d[a-zA-Z-][0-9a-zA-Z-])(?:\.(?:0\|[1-9]\d\|\d[a-zA-Z-][0-9a-zA-Z-]))))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$`.
`session_id`	Uuid	no	Only on a data connection; the session the connection belongs to.
`live_sessions`	array of Uuid	no	Only on the control connection, always present there (empty when none). The sessions the host service knows, those whose PTY still runs and those whose end it could not report yet (it reports that end with `session.ended` after `ready`). After a restart of the host service the list is empty. The server ends every other session of the host in state `active` or `detached` with `host_restarted` (24, 6.2).

HostReady¶

Sent after login and again on every change of llm_credentials; the host service treats each ready as the current declaration (24, 2.2 and 7.4).

Property	Type	Required
`host_id`	Uuid	yes
`state`	HostState	yes
`llm_credentials`	LlmCredentials	yes

HostHeartbeat¶

Property	Type	Required	Description
`active_sessions`	integer	yes	Minimum 0.

HostHeartbeatAck¶

Property	Type	Required	Description
`server_time`	Timestamp	no
`jwks`	Jwks	no

HostReport¶

Report of profiles, session users and self-checks; never content, paths or values. Sent after every ready before the host service accepts session.open, and on every change. When doctor refuses the start, the host service still logs in, sends one report and closes the connection without accepting session.open (24 section 2.2).

Property	Type	Required	Description
`profiles`	array of HostProfile	yes
`session_users`	array of HostReportedSessionUser	yes
`doctor`	array of HostDoctorCheck	yes	One entry per check HD1 to HD11; a failed HD6, HD9, HD10 or HD11 has one entry per account named by the rule for names (24, 2.2).
`is_server_host`	boolean	yes
`require_local_confirm`	boolean	yes
`os_version`	string	no

HostSessionOpen¶

The server asks the host service to open the data connection of a session.

Property	Type	Required	Description
`session_id`	Uuid	yes
`data_path`	string	yes	Example: `/api/v1/hosts/sessions/0192f4a0-7b1c-7b22-9d4f-5a6b7c8d9e0f/stream`.
`profile`	string	yes
`expires_at`	Timestamp	yes	Without a valid handshake until then the host service drops the request (`terminal.open_timeout`).

HostSessionClose¶

Property	Type	Required	Description
`session_id`	Uuid	yes
`close_reason`	TerminalCloseReason	yes

HostSessionStarted¶

Property	Type	Required	Description
`session_id`	Uuid	yes

HostSessionEnded¶

Property	Type	Required
`session_id`	Uuid	yes
`close_reason`	TerminalCloseReason	yes
`close_detail`	TerminalCloseDetail	no
`exit_code`	integer	no

NoiseFrame¶

One binary WebSocket message carrying exactly one Noise message (at most 65535 bytes). After the handshake each transport message holds one frame type (1 byte) || body (24, 5.4). The relay never decrypts it.

Type: string (binary)