openapi: 3.1.0 info: title: Silicon DM API version: 0.6.0 license: name: Proprietary identifier: LicenseRef-Proprietary description: Carbon/Silicon messaging, IAM application sessions, and isolated testing environments. Bearer tokens must be issued to DM and bound to the selected organization. See SocketFrame for WebSocket protocol version 3; sender devices also receive deliveries and clients upsert messages by (id, version). Attachments are stored links and are never uploaded, fetched, or proxied by DM. Every DM JSON request and response has exactly type and data at the root. Message text is data.message and metadata is data.metadata. Bodyless HTTP requests, 204 responses, and signed incoming IAM webhook payloads retain their HTTP/provider contracts. servers: - url: https://backend.dm.teamofsilicons.com/api/v1 security: - bearerAuth: [] tags: - name: Realtime description: Authenticated WebSocket sessions and durable actor streams - name: Conversations description: Exact-participant-set conversations - name: Groups description: Named organization groups with invitations and dynamic IAM tag access - name: Messages description: Durable content, receipts, and attachment access - name: Bundles description: Non-destructive Silicon message bundles - name: Drafts description: Private cross-device draft synchronization - name: Presence description: Authorized availability and transient activity - name: GIFs description: Safe Giphy discovery and recent history - name: Auth description: IAM application-session exchange and maintenance - name: Testing description: Production-owned test environments; lifecycle control uses production IAM authority - name: IAM webhooks description: Signed IAM callbacks, outside the /api/v1 base path - name: Operations description: Deployment health probes paths: "/groups": get: tags: - "Groups" operationId: "listGroups" summary: "List groups accessible to the current IAM token" parameters: - $ref: "#/components/parameters/OrgId" - $ref: "#/components/parameters/TestingKey" - $ref: "#/components/parameters/Cursor" - $ref: "#/components/parameters/Limit" responses: 200: description: "Successful group operation" content: application/json: schema: type: "object" additionalProperties: false required: - "type" - "data" properties: type: type: "string" const: "groups" data: type: "object" required: - "items" - "next_cursor" properties: items: type: "array" items: $ref: "#/components/schemas/Conversation" next_cursor: type: - "string" - "null" 401: $ref: "#/components/responses/Unauthorized" 403: $ref: "#/components/responses/Error" 404: $ref: "#/components/responses/Error" 409: $ref: "#/components/responses/Error" 422: $ref: "#/components/responses/Error" default: $ref: "#/components/responses/Error" post: tags: - "Groups" operationId: "createGroup" summary: "Create a group as an organization administrator or owner" parameters: - $ref: "#/components/parameters/OrgId" - $ref: "#/components/parameters/TestingKey" - $ref: "#/components/parameters/IdempotencyKey" responses: 201: description: "Successful group operation" content: application/json: schema: type: "object" additionalProperties: false required: - "type" - "data" properties: type: type: "string" const: "create_group" data: $ref: "#/components/schemas/Conversation" 401: $ref: "#/components/responses/Unauthorized" 403: $ref: "#/components/responses/Error" 404: $ref: "#/components/responses/Error" 409: $ref: "#/components/responses/Error" 422: $ref: "#/components/responses/Error" default: $ref: "#/components/responses/Error" requestBody: required: true content: application/json: schema: type: "object" additionalProperties: false required: - "type" - "data" properties: type: type: "string" const: "create_group" data: $ref: "#/components/schemas/GroupCreate" description: "Creator is invited automatically. Groups have stable conversation UUIDs and full prior message history for new members. Private groups admit invited members or actors with any matching current IAM tag. Public groups automatically admit organization Carbons; Silicons always require an explicit invitation. Only org_admin/org_owner (and canonical IAM admin/owner aliases) may create, update, invite or remove invitations. Group administration does not itself grant history access." "/groups/{group_id}": get: tags: - "Groups" operationId: "getGroup" summary: "Read group settings, active participants and latest message" parameters: - $ref: "#/components/parameters/OrgId" - $ref: "#/components/parameters/TestingKey" - name: "group_id" in: "path" required: true schema: type: "string" format: "uuid" responses: 200: description: "Successful group operation" content: application/json: schema: type: "object" additionalProperties: false required: - "type" - "data" properties: type: type: "string" const: "group" data: $ref: "#/components/schemas/Conversation" 401: $ref: "#/components/responses/Unauthorized" 403: $ref: "#/components/responses/Error" 404: $ref: "#/components/responses/Error" 409: $ref: "#/components/responses/Error" 422: $ref: "#/components/responses/Error" default: $ref: "#/components/responses/Error" patch: tags: - "Groups" operationId: "updateGroup" summary: "Replace group settings with an exact current version" parameters: - $ref: "#/components/parameters/OrgId" - $ref: "#/components/parameters/TestingKey" - name: "group_id" in: "path" required: true schema: type: "string" format: "uuid" - $ref: "#/components/parameters/IdempotencyKey" - name: "If-Match" in: "header" required: true schema: type: "integer" minimum: 1 responses: 200: description: "Successful group operation" content: application/json: schema: type: "object" additionalProperties: false required: - "type" - "data" properties: type: type: "string" const: "update_group" data: $ref: "#/components/schemas/GroupDetails" 401: $ref: "#/components/responses/Unauthorized" 403: $ref: "#/components/responses/Error" 404: $ref: "#/components/responses/Error" 409: $ref: "#/components/responses/Error" 422: $ref: "#/components/responses/Error" default: $ref: "#/components/responses/Error" requestBody: required: true content: application/json: schema: type: "object" additionalProperties: false required: - "type" - "data" properties: type: type: "string" const: "update_group" data: $ref: "#/components/schemas/GroupSettings" "/groups/{group_id}/members": post: tags: - "Groups" operationId: "inviteGroupMembers" summary: "Add explicit invitations as an organization administrator or owner" parameters: - $ref: "#/components/parameters/OrgId" - $ref: "#/components/parameters/TestingKey" - name: "group_id" in: "path" required: true schema: type: "string" format: "uuid" - $ref: "#/components/parameters/IdempotencyKey" responses: 200: description: "Successful group operation" content: application/json: schema: type: "object" additionalProperties: false required: - "type" - "data" properties: type: type: "string" const: "invite_group_members" data: $ref: "#/components/schemas/GroupDetails" 401: $ref: "#/components/responses/Unauthorized" 403: $ref: "#/components/responses/Error" 404: $ref: "#/components/responses/Error" 409: $ref: "#/components/responses/Error" 422: $ref: "#/components/responses/Error" default: $ref: "#/components/responses/Error" requestBody: required: true content: application/json: schema: type: "object" additionalProperties: false required: - "type" - "data" properties: type: type: "string" const: "invite_group_members" data: $ref: "#/components/schemas/GroupMembers" delete: tags: - "Groups" operationId: "removeGroupMembers" summary: "Remove explicit invitations; tag and public grants remain independent" parameters: - $ref: "#/components/parameters/OrgId" - $ref: "#/components/parameters/TestingKey" - name: "group_id" in: "path" required: true schema: type: "string" format: "uuid" - $ref: "#/components/parameters/IdempotencyKey" responses: 200: description: "Successful group operation" content: application/json: schema: type: "object" additionalProperties: false required: - "type" - "data" properties: type: type: "string" const: "remove_group_members" data: $ref: "#/components/schemas/GroupDetails" 401: $ref: "#/components/responses/Unauthorized" 403: $ref: "#/components/responses/Error" 404: $ref: "#/components/responses/Error" 409: $ref: "#/components/responses/Error" 422: $ref: "#/components/responses/Error" default: $ref: "#/components/responses/Error" requestBody: required: true content: application/json: schema: type: "object" additionalProperties: false required: - "type" - "data" properties: type: type: "string" const: "remove_group_members" data: $ref: "#/components/schemas/GroupMembers" "/contracts": get: tags: [Operations] operationId: discoverContracts summary: Discover contract lifecycle and compatibility security: [] parameters: - "$ref": "#/components/parameters/TestingKey" responses: '200': description: Contract versions and compatibility matrix for the selected plane content: application/json: schema: type: object required: [type, data] properties: type: {type: string, const: contracts} data: {type: object, additionalProperties: true} '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" "/ws/shared": get: tags: [Realtime] operationId: prewarmSharedConnection summary: Prewarm one socket for independently authenticated subscriptions security: [] description: >- Negotiates shared transport v1. Each subscribe frame must carry its own bearer, organization, actor, device, and optional test app secret. Up to 64 subscriptions share one connection. Channel frames wrap unchanged WebSocket v3 frames under data.subscription_id and data.frame. Credentials are never URL parameters. See https://docs.dm.teamofsilicons.com/contracts/ for the complete protocol. parameters: - in: header name: X-DM-Protocol-Version schema: {type: integer, enum: [1]} responses: '101': description: Transport prewarmed; authenticate each subscription before accessing data '406': "$ref": "#/components/responses/Error" '410': "$ref": "#/components/responses/Error" default: "$ref": "#/components/responses/Error" "/reports": post: tags: [Operations] operationId: submitBugReport summary: Durably submit a report and queue a Postmark notification description: >- Production retries notification delivery. Sandbox email is simulated. Reuse Idempotency-Key after an uncertain response. Ten new reports per actor per hour. parameters: - "$ref": "#/components/parameters/OrgId" - "$ref": "#/components/parameters/TestingKey" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: [type, data] properties: type: {type: string, const: report} data: type: object additionalProperties: false required: [message, client_version] properties: message: {type: string, minLength: 1, maxLength: 60000} pr: {type: [string, 'null'], format: uri} client_version: {type: string, maxLength: 100} responses: '202': description: Durable acknowledgement; notification is queued, sent or simulated content: application/json: schema: type: object required: [type, data] properties: type: {type: string, const: report} data: type: object required: [id, submitted, notification, repository] properties: id: {type: string, format: uuid} submitted: {type: boolean} notification: {type: string, enum: [queued, sent, simulated]} repository: {type: string, format: uri} '401': "$ref": "#/components/responses/Unauthorized" '409': "$ref": "#/components/responses/Error" '429': "$ref": "#/components/responses/Error" '503': "$ref": "#/components/responses/Error" default: "$ref": "#/components/responses/Error" "/telemetry": post: tags: [Operations] operationId: recordDiagnostic summary: Record a bounded diagnostic event without distributing the ingest key description: >- X-DM-Telemetry off disables collection. Sandbox diagnostics remain in their own schema. Message content, URLs and secrets are excluded from the accepted schema. parameters: - "$ref": "#/components/parameters/OrgId" - "$ref": "#/components/parameters/TestingKey" - in: header name: X-DM-Telemetry schema: {type: string, enum: ['on', 'off']} requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: [type, data] properties: type: {type: string, const: telemetry} data: type: object additionalProperties: false required: [source, event, success, duration_ms] properties: source: {type: string, enum: [cli, sdk, daemon, web]} event: {type: string, enum: [command, connection, callback, queue, update, page_view, request, web_error]} success: {type: boolean} duration_ms: {type: integer, minimum: 0, maximum: 604800000} responses: '204': description: Diagnostic accepted or opted out '401': "$ref": "#/components/responses/Unauthorized" '422': "$ref": "#/components/responses/Error" default: "$ref": "#/components/responses/Error" "/iam": get: tags: - Auth operationId: iamInformation summary: Discover the public IAM application configuration security: [] description: Available before login. Returns only public identifiers and URLs, never application secrets. parameters: - "$ref": "#/components/parameters/TestingKey" responses: '200': description: Public application configuration content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: iam data: type: object required: [app_id, iam_base_url, api_base_url] properties: app_id: type: string iam_base_url: type: string format: uri api_base_url: type: string format: uri testing_environment_id: type: [string, 'null'] format: uuid testing_generation: type: [integer, 'null'] testing_environment: type: [object, 'null'] additionalProperties: true '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" "/ws": get: tags: - Realtime operationId: openRealtimeConnection summary: Upgrade to the DM WebSocket protocol security: - bearerAuth: [] description: Authenticate with a DM application bearer token. Query parameters org_id and device_id occur exactly once; actors is repeated. Sends ready with protocol_version=3. Server ping every 30 seconds requires same ping_id pong;120-second timeout closes 4000/heartbeat-timeout. Revoked authority closes 4001/authorization-revoked and unavailable authority 1013/authorization-unavailable. Durable messages, version updates, tombstones and receipts use cumulative actor-stream ACKs. Sender devices receive message deliveries too. Dedupe delivery_id and upsert Message by id/version; do not append an edited message as a new message. x-websocket-frame: "$ref": "#/components/schemas/SocketFrame" parameters: - name: actors in: query required: true schema: type: array minItems: 1 maxItems: 100 uniqueItems: true items: type: string style: form explode: true description: Repeat actors query parameter for each actor; this IAM integration grants only the authenticated principal. Multiple independent accounts use separate authenticated connections. - name: org_id in: query required: true schema: type: string description: IAM-verified organization context for every represented actor - name: device_id in: query required: true schema: type: string minLength: 1 maxLength: 255 pattern: "^[^\\u0000-\\u001F\\u007F]{1,255}$" description: Stable consumer identifier used for resume and device-aware receipts - "$ref": "#/components/parameters/TestingKey" - name: testing_generation in: query schema: type: integer minimum: 1 description: Generation persisted from ready.testing_generation. Missing/mismatched testing generation resets server cursor/resume to0; production does not use it. responses: '101': description: Switching Protocols '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" "/conversations": get: tags: - Conversations operationId: listConversations summary: List the current actor's conversations parameters: - "$ref": "#/components/parameters/OrgId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/Limit" - "$ref": "#/components/parameters/TestingKey" responses: '200': description: Conversations content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: conversations data: type: object properties: items: type: array items: "$ref": "#/components/schemas/Conversation" next_cursor: type: - string - 'null' '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" post: tags: - Conversations operationId: createConversation summary: Create or resolve an exact-participant-set conversation description: Recipients require an active IAM membership projection supplied by a prior sign-in or verified webhook. Known recipients may be offline. IAM currently provides no arbitrary-member lookup for application sessions; an unknown recipient returns 422 explaining that the recipient can sign in. security: - bearerAuth: [] parameters: - "$ref": "#/components/parameters/OrgId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/TestingKey" requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: create_conversation data: type: object required: - participant_ids properties: participant_ids: type: array minItems: 1 maxItems: 100 uniqueItems: true items: type: string description: IAM actor IDs; DM adds the authenticated actor, allows at most 100 total unique participants, and resolves the exact participant set to one conversation. responses: '201': description: Conversation content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: create_conversation data: "$ref": "#/components/schemas/Conversation" '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" "/conversations/{conversation_id}/messages": get: tags: - Messages operationId: listMessages summary: List durable conversation messages parameters: - "$ref": "#/components/parameters/OrgId" - "$ref": "#/components/parameters/ConversationId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/Limit" - name: include_bundled_members in: query schema: type: boolean default: false description: Include original messages hidden behind bundle display messages - "$ref": "#/components/parameters/TestingKey" responses: '200': description: Messages in stable sequence order content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: messages data: type: object properties: items: type: array items: "$ref": "#/components/schemas/Message" next_cursor: type: - string - 'null' '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" post: tags: - Messages operationId: sendMessage summary: Durably accept and queue a message parameters: - "$ref": "#/components/parameters/OrgId" - "$ref": "#/components/parameters/ConversationId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/TestingKey" requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: new_message data: "$ref": "#/components/schemas/MessageCreate" responses: '202': description: Message durably accepted content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: new_message data: "$ref": "#/components/schemas/Message" '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" "/conversations/{conversation_id}/messages/{message_id}/receipts": post: tags: - Messages operationId: recordMessageReceipt summary: Record a monotonic device receipt parameters: - "$ref": "#/components/parameters/OrgId" - "$ref": "#/components/parameters/ConversationId" - name: message_id in: path required: true schema: type: string format: uuid - "$ref": "#/components/parameters/TestingKey" requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: receipt data: type: object required: - status - device_id properties: status: type: string enum: - delivered - read device_id: type: string minLength: 1 maxLength: 255 pattern: "^[^\\u0000-\\u001F\\u007F]{1,255}$" responses: '200': description: Aggregate receipt state content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: receipt data: "$ref": "#/components/schemas/Message" '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" "/conversations/{conversation_id}/bundles": post: tags: - Bundles operationId: createMessageBundle summary: Bundle existing messages behind one display message description: Only an authenticated Silicon may create a bundle. The operation is non-destructive; each original message remains stored and records the created bundle ID. parameters: - "$ref": "#/components/parameters/OrgId" - "$ref": "#/components/parameters/ConversationId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/TestingKey" requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: create_bundle data: "$ref": "#/components/schemas/BundleCreate" responses: '201': description: Bundle and display message created content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: create_bundle data: "$ref": "#/components/schemas/Bundle" '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" "/conversations/{conversation_id}/bundles/{bundle_id}": get: tags: - Bundles operationId: getMessageBundle summary: Retrieve a bundle and its original messages description: >- Expanded message payloads are limited to 128 MiB in aggregate. One individually legal oversized message is allowed when all remaining message payloads total at most 16 MiB. Larger expansions return 413 response_too_large; retrieve originals individually by message ID. parameters: - "$ref": "#/components/parameters/OrgId" - "$ref": "#/components/parameters/ConversationId" - name: bundle_id in: path required: true schema: type: string format: uuid - "$ref": "#/components/parameters/TestingKey" responses: '200': description: Bundle with display and original messages content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: bundle data: "$ref": "#/components/schemas/BundleDetail" '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" "/conversations/{conversation_id}/draft": get: tags: - Drafts operationId: getDraft summary: Get the current actor's draft parameters: - "$ref": "#/components/parameters/OrgId" - "$ref": "#/components/parameters/ConversationId" - "$ref": "#/components/parameters/TestingKey" responses: '200': description: Current actor's synchronized draft content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: draft data: "$ref": "#/components/schemas/Draft" '401': "$ref": "#/components/responses/Unauthorized" '404': description: No draft default: "$ref": "#/components/responses/Error" put: tags: - Drafts operationId: putDraft summary: Create or conditionally replace a draft parameters: - "$ref": "#/components/parameters/OrgId" - "$ref": "#/components/parameters/ConversationId" - name: If-Match in: header schema: type: integer minimum: 0 description: Exact last observed draft version. Omit or send 0 only when creating a draft that does not yet exist. Versions continue increasing across deletion and automatic clearing; use the returned version for the next save. - "$ref": "#/components/parameters/TestingKey" requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: put_draft data: "$ref": "#/components/schemas/DraftInput" responses: '200': description: Draft stored content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: put_draft data: "$ref": "#/components/schemas/Draft" '401': "$ref": "#/components/responses/Unauthorized" '409': description: Version conflict. Returns the current draft when one exists, or an error envelope when it was deleted after the supplied version was observed. content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: error data: oneOf: - "$ref": "#/components/schemas/Draft" - "$ref": "#/components/schemas/Error" default: "$ref": "#/components/responses/Error" delete: tags: - Drafts operationId: deleteDraft summary: Delete the current actor's draft parameters: - "$ref": "#/components/parameters/OrgId" - "$ref": "#/components/parameters/ConversationId" - "$ref": "#/components/parameters/TestingKey" responses: '204': description: Draft deleted '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" "/presence/{actor_id}": get: tags: - Presence operationId: getPresence summary: Get an authorized actor's presence security: - bearerAuth: [] parameters: - "$ref": "#/components/parameters/OrgId" - name: actor_id in: path required: true schema: type: string - "$ref": "#/components/parameters/TestingKey" responses: '200': description: Presence content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: presence data: "$ref": "#/components/schemas/Presence" '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" "/gifs/trending": get: tags: - GIFs operationId: listTrendingGifs summary: List safe trending GIFs parameters: - "$ref": "#/components/parameters/OrgId" - "$ref": "#/components/parameters/TestingKey" responses: '200': description: Trending Giphy results content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: gifs data: type: object properties: items: type: array items: "$ref": "#/components/schemas/Gif" '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" "/gifs/search": get: tags: - GIFs operationId: searchGifs summary: Search safe GIF results parameters: - "$ref": "#/components/parameters/OrgId" - name: q in: query required: true schema: type: string minLength: 1 maxLength: 50 pattern: "^[^\\u0000-\\u001F\\u007F]{1,50}$" - "$ref": "#/components/parameters/TestingKey" responses: '200': description: Giphy results content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: gifs data: type: object properties: items: type: array items: "$ref": "#/components/schemas/Gif" '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" "/gifs/recent": get: tags: - GIFs operationId: listRecentGifs summary: List the current Carbon's recent GIFs parameters: - "$ref": "#/components/parameters/OrgId" - "$ref": "#/components/parameters/TestingKey" responses: '200': description: Current Carbon's last 20 GIFs content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: gifs data: type: object properties: items: type: array maxItems: 20 items: "$ref": "#/components/schemas/Gif" '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" "/auth/login": post: tags: - Auth operationId: login summary: Exchange an organization-bound IAM SLT security: [] parameters: - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/TestingKey" description: Maximum JSON body 16 KiB. No separate Bearer/X-Org-ID header required. Repeat the exact body with the same Idempotency-Key after an uncertain result. Credentials and backend app secrets must never be logged. The returned session is live-verified by IAM and has no-store/no-cache response headers. requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: login data: "$ref": "#/components/schemas/LoginInput" responses: '200': description: Verified application session content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: login data: "$ref": "#/components/schemas/ApplicationSession" '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" "/auth/refresh": post: tags: - Auth operationId: refreshSession summary: Rotate a DM application refresh token security: [] parameters: - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/TestingKey" description: Maximum JSON body 16 KiB. No separate Bearer/X-Org-ID header required. Repeat the exact body with the same Idempotency-Key after an uncertain result. Credentials and backend app secrets must never be logged. The returned session is live-verified by IAM and has no-store/no-cache response headers. requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: refresh data: "$ref": "#/components/schemas/RefreshInput" responses: '200': description: Verified application session content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: refresh data: "$ref": "#/components/schemas/ApplicationSession" '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" "/auth/logout": post: tags: - Auth operationId: logout summary: Revoke one application token or refresh family security: [] parameters: - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/TestingKey" description: Maximum JSON body 16 KiB. No separate Bearer/X-Org-ID header required. Repeat the exact body with the same Idempotency-Key after an uncertain result. Credentials and backend app secrets must never be logged. Use the current refresh token for full-family logout; an access token revokes only itself. requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: logout data: "$ref": "#/components/schemas/LogoutInput" responses: '204': description: Token revoked '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" "/auth/me": get: tags: - Auth operationId: currentIdentity summary: Get current IAM identity and effective authority parameters: - "$ref": "#/components/parameters/OrgId" - "$ref": "#/components/parameters/TestingKey" responses: '200': description: Live introspected identity content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: me data: "$ref": "#/components/schemas/Identity" '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" "/conversations/{conversation_id}/messages/{message_id}": get: tags: - Messages operationId: getMessage summary: Get a message and its latest content version parameters: - "$ref": "#/components/parameters/OrgId" - "$ref": "#/components/parameters/ConversationId" - "$ref": "#/components/parameters/MessageId" - "$ref": "#/components/parameters/TestingKey" responses: '200': description: Latest message or deletion tombstone content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: message data: "$ref": "#/components/schemas/Message" '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" patch: tags: - Messages operationId: editMessage summary: Replace an authored message with optimistic concurrency parameters: - "$ref": "#/components/parameters/OrgId" - "$ref": "#/components/parameters/ConversationId" - "$ref": "#/components/parameters/MessageId" - "$ref": "#/components/parameters/TestingKey" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MessageVersion" responses: '200': description: Latest message or deletion tombstone content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: edit_message data: "$ref": "#/components/schemas/Message" '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" '409': description: Version or idempotency conflict; fetch latest Message content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: error data: "$ref": "#/components/schemas/Error" description: Only the original sender may change the message. Idempotency covers exact body, path, and observed version. Reusing the same key after a lost response is safe. Deleted messages cannot be edited or resurrected; status receipts never change content version. requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: edit_message data: "$ref": "#/components/schemas/MessageCreate" delete: tags: - Messages operationId: deleteMessage summary: Publish an authored message deletion tombstone parameters: - "$ref": "#/components/parameters/OrgId" - "$ref": "#/components/parameters/ConversationId" - "$ref": "#/components/parameters/MessageId" - "$ref": "#/components/parameters/TestingKey" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MessageVersion" responses: '200': description: Latest message or deletion tombstone content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: delete_message data: "$ref": "#/components/schemas/Message" '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" '409': description: Version or idempotency conflict; fetch latest Message content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: error data: "$ref": "#/components/schemas/Error" description: Only the original sender may change the message. Idempotency covers exact body, path, and observed version. Reusing the same key after a lost response is safe. Deleted messages cannot be edited or resurrected; status receipts never change content version. "/testing-environments": get: tags: - Testing operationId: listTestingEnvironments summary: List environments owned by production organization parameters: - "$ref": "#/components/parameters/OrgId" - name: include_deleted in: query schema: type: boolean default: false responses: '200': description: List environments owned by production organization content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: testing_environments data: "$ref": "#/components/schemas/TestingEnvironmentList" '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" description: Lifecycle authority uses a production IAM application session. The DM test key does not bypass production management authorization. Creator or current organization administrator required for changes/key access; any current member may create/list/read environments. post: tags: - Testing operationId: createTestingEnvironment summary: Create a DM environment paired with an imported IAM test app parameters: - "$ref": "#/components/parameters/OrgId" - "$ref": "#/components/parameters/IdempotencyKey" responses: '201': description: Create a DM environment paired with an imported IAM test app content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: create_testing_environment data: "$ref": "#/components/schemas/TestingEnvironmentWithKey" '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" description: Lifecycle authority uses a production IAM application session. The DM test key does not bypass production management authorization. Creator or current organization administrator required for changes/key access; any current member may create/list/read environments. Import the canonical DM application through IAM CLI first, supplying its fresh test-only app secret. IAM production cannot back a DM test environment. Idempotency-Key is required. Exact request replays return the original result; changed body or target with the same key returns409. Responses use Cache-Control:no-store. requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: create_testing_environment data: "$ref": "#/components/schemas/TestingEnvironmentCreate" "/testing-environments/{environment_id}": get: tags: - Testing operationId: getTestingEnvironment summary: Read environment metadata parameters: - "$ref": "#/components/parameters/OrgId" - "$ref": "#/components/parameters/EnvironmentId" responses: '200': description: Read environment metadata content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: testing_environment data: "$ref": "#/components/schemas/TestingEnvironment" '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" description: Lifecycle authority uses a production IAM application session. The DM test key does not bypass production management authorization. Creator or current organization administrator required for changes/key access; any current member may create/list/read environments. patch: tags: - Testing operationId: updateTestingEnvironment summary: Update environment name or description parameters: - "$ref": "#/components/parameters/OrgId" - "$ref": "#/components/parameters/EnvironmentId" - "$ref": "#/components/parameters/IdempotencyKey" responses: '200': description: Update environment name or description content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: update_testing_environment data: "$ref": "#/components/schemas/TestingEnvironment" '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" description: Lifecycle authority uses a production IAM application session. The DM test key does not bypass production management authorization. Creator or current organization administrator required for changes/key access; any current member may create/list/read environments. Idempotency-Key is required. Exact request replays return the original result; changed body or target with the same key returns409. Responses use Cache-Control:no-store. requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: update_testing_environment data: "$ref": "#/components/schemas/TestingEnvironmentUpdate" delete: tags: - Testing operationId: deleteTestingEnvironment summary: Delete environment with 30-day recovery window parameters: - "$ref": "#/components/parameters/OrgId" - "$ref": "#/components/parameters/EnvironmentId" - "$ref": "#/components/parameters/IdempotencyKey" responses: '204': description: Delete environment with 30-day recovery window '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" description: Lifecycle authority uses a production IAM application session. The DM test key does not bypass production management authorization. Creator or current organization administrator required for changes/key access; any current member may create/list/read environments. Idempotency-Key is required. Exact request replays return the original result; changed body or target with the same key returns409. Responses use Cache-Control:no-store. "/testing-environments/{environment_id}/key": get: tags: - Testing operationId: getTestingEnvironmentKey summary: Retrieve current test root key parameters: - "$ref": "#/components/parameters/OrgId" - "$ref": "#/components/parameters/EnvironmentId" responses: '200': description: Retrieve current test root key content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: testing_environment_key data: "$ref": "#/components/schemas/TestingEnvironmentKey" '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" description: Lifecycle authority uses a production IAM application session. The DM test key does not bypass production management authorization. Creator or current organization administrator required for changes/key access; any current member may create/list/read environments. "/testing-environments/{environment_id}/rotate-key": post: tags: - Testing operationId: rotateTestingEnvironmentKey summary: Rotate root key and disconnect existing sessions parameters: - "$ref": "#/components/parameters/OrgId" - "$ref": "#/components/parameters/EnvironmentId" - "$ref": "#/components/parameters/IdempotencyKey" responses: '200': description: Rotate root key and disconnect existing sessions content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: rotate_testing_environment_key data: "$ref": "#/components/schemas/TestingEnvironmentWithKey" '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" description: Lifecycle authority uses a production IAM application session. The DM test key does not bypass production management authorization. Creator or current organization administrator required for changes/key access; any current member may create/list/read environments. Idempotency-Key is required. Exact request replays return the original result; changed body or target with the same key returns409. Responses use Cache-Control:no-store. "/testing-environments/{environment_id}/restore": post: tags: - Testing operationId: restoreTestingEnvironment summary: Recover retained data with a fresh root key parameters: - "$ref": "#/components/parameters/OrgId" - "$ref": "#/components/parameters/EnvironmentId" - "$ref": "#/components/parameters/IdempotencyKey" responses: '200': description: Recover retained data with a fresh root key content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: restore_testing_environment data: "$ref": "#/components/schemas/TestingEnvironmentWithKey" '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" description: Lifecycle authority uses a production IAM application session. The DM test key does not bypass production management authorization. Creator or current organization administrator required for changes/key access; any current member may create/list/read environments. Idempotency-Key is required. Exact request replays return the original result; changed body or target with the same key returns409. Responses use Cache-Control:no-store. "/testing-environments/{environment_id}/clean": post: tags: - Testing operationId: cleanTestingEnvironment summary: Erase test data while retaining environment and key parameters: - name: X-Org-ID in: header required: false schema: type: string description: Required when using production bearer authorization; unnecessary with test root key. - "$ref": "#/components/parameters/EnvironmentId" - "$ref": "#/components/parameters/TestingKey" - "$ref": "#/components/parameters/IdempotencyKey" responses: '204': description: Erase test data while retaining environment and key '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" description: Authorize with this environment root key alone, or creator/admin production IAM session. The path ID and key must match. Removes all message, draft, delivery, receipt, presence and webhook-receipt rows; retains environment metadata/key. Other environments and production are unchanged. Idempotency-Key is required. Exact request replays return the original result; changed body or target with the same key returns409. Responses use Cache-Control:no-store. security: - bearerAuth: [] - testingEnvironmentKey: [] "/webhook/": post: tags: - IAM webhooks operationId: receiveIamWebhook summary: Receive signature-authenticated IAM events servers: - url: https://backend.dm.teamofsilicons.com security: [] description: Backend-to-backend IAM callback. Exactly one of each signature header is required. Official SDK verifies exact bytes, five-minute signing-time tolerance, key version, event identity and 1 MiB limit. Test envelopes are verified before matching the IAM key to an active DM test environment. Root keys and raw bodies are never persisted. Duplicate event IDs are safe. Successful receipt durably prompts connected token revalidation; IAM remains authoritative. A bounded redacted test-key hint selects candidates; exact SDK signature and environment binding are verified before initializing runtimes. One authenticated IAM test event invalidates all active DM environments paired to that IAM realm, including inherited/overridden signer versions. Invalid signatures cannot initialize a testing runtime. parameters: - name: X-Silicon-IAM-Event-ID in: header required: true schema: type: string - name: X-Silicon-IAM-Timestamp in: header required: true schema: type: string - name: X-Silicon-IAM-Key-Version in: header required: true schema: type: string - name: X-Silicon-IAM-Signature in: header required: true schema: type: string requestBody: required: true content: application/json: schema: type: object additionalProperties: true description: Exact IAM production event or signed testing envelope; see official IAM WebhookEvent contract. responses: '204': description: Verified event committed or duplicate acknowledged '401': "$ref": "#/components/responses/Unauthorized" default: "$ref": "#/components/responses/Error" "/live": get: tags: - Operations operationId: live servers: - url: https://backend.dm.teamofsilicons.com security: [] summary: Process liveness responses: '204': description: Ready '503': description: Dependency or migration unavailable "/ready": get: tags: - Operations operationId: ready servers: - url: https://backend.dm.teamofsilicons.com security: [] summary: Database and migration readiness responses: '204': description: Ready '503': description: Dependency or migration unavailable components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: IAM application access token (oat_) testingEnvironmentKey: type: apiKey in: header name: X-Testing-Environment-Key description: 32-character DM testing root key. Selects an isolated data plane; normal actions still require its IAM user session. parameters: OrgId: name: X-Org-ID in: header required: true schema: type: string ConversationId: name: conversation_id in: path required: true schema: type: string format: uuid IdempotencyKey: name: Idempotency-Key in: header required: true schema: type: string minLength: 8 maxLength: 255 pattern: "^[!-~]{8,255}$" Cursor: name: cursor in: query schema: type: string Limit: name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 50 TestingKey: name: X-Testing-Environment-Key in: header required: false schema: type: string pattern: "^(ask_[A-Za-z0-9_-]{43}|[A-Za-z0-9]{32})$" description: IAM test app secret for automatic discovery, or a legacy DM root key. Omit for production. Never send the IAM environment root key. EnvironmentId: name: environment_id in: path required: true schema: type: string format: uuid MessageId: name: message_id in: path required: true schema: type: string format: uuid MessageVersion: name: If-Match in: header required: true schema: type: string pattern: ^"?[1-9][0-9]*"?$ description: Exact observed positive message version, e.g. "1". PATCH replaces all message content. Missing/invalid versions are 422; a stale version is 409. responses: Error: description: Error content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: error data: "$ref": "#/components/schemas/Error" Unauthorized: description: Authentication credentials are missing or invalid content: application/json: schema: type: object additionalProperties: false required: - type - data properties: type: type: string const: error data: "$ref": "#/components/schemas/Error" schemas: "GroupSettings": type: "object" required: - "name" properties: name: type: "string" minLength: 1 maxLength: 120 description: type: "string" maxLength: 4000 default: "" is_public: type: "boolean" default: false tag_ids: type: "array" maxItems: 100 items: type: "string" format: "uuid" default: [] "GroupCreate": type: "object" required: - "name" properties: name: type: "string" minLength: 1 maxLength: 120 description: type: "string" maxLength: 4000 default: "" is_public: type: "boolean" default: false tag_ids: type: "array" maxItems: 100 items: type: "string" format: "uuid" default: [] member_ids: type: "array" maxItems: 100 items: type: "string" default: [] "GroupDetails": type: "object" required: - "name" - "description" - "is_public" - "tag_ids" - "version" - "invited_members" properties: name: type: "string" minLength: 1 maxLength: 120 description: type: "string" maxLength: 4000 default: "" is_public: type: "boolean" default: false tag_ids: type: "array" maxItems: 100 items: type: "string" format: "uuid" default: [] version: type: "integer" minimum: 1 invited_members: type: "array" items: $ref: "#/components/schemas/ActorRef" "GroupMembers": type: "object" additionalProperties: false required: - "member_ids" properties: member_ids: type: "array" maxItems: 100 items: type: "string" default: [] ActorRef: type: object required: - type - id properties: type: type: string enum: - carbon - silicon id: type: string Conversation: type: object required: - id - org_id - participants - created_at - updated_at properties: group: "$ref": "#/components/schemas/GroupDetails" id: type: string format: uuid org_id: type: string participants: type: array minItems: 1 items: "$ref": "#/components/schemas/ActorRef" last_message: anyOf: - "$ref": "#/components/schemas/Message" - type: 'null' created_at: type: string format: date-time updated_at: type: string format: date-time Attachment: type: object required: - permanent_url properties: permanent_url: type: string format: uri maxLength: 8192 pattern: "^https://(?![^/?#]*@)[^/?#]+(?:[/?#]|$)" description: Credential-free HTTPS link, at most 8192 bytes. DM stores this link without contacting its host. No upload, proxy, or temporary-URL endpoint exists. name: type: string minLength: 1 maxLength: 1024 content_type: type: string minLength: 1 maxLength: 255 size: type: integer minimum: 0 maximum: 5368709120 description: Untrusted client-declared byte size. VoiceAttachment: allOf: - "$ref": "#/components/schemas/Attachment" - type: object required: - duration_milliseconds properties: duration_milliseconds: type: integer minimum: 1 maximum: 172800000 description: Untrusted caller-supplied total playback duration, capped at 48 hours. StoredVoiceAttachment: allOf: - "$ref": "#/components/schemas/Attachment" - type: object required: - duration_milliseconds properties: duration_milliseconds: type: - integer - 'null' minimum: 1 maximum: 172800000 description: Total playback duration. Null is returned only for a historical pre-v 2 voice row whose provider did not supply duration metadata. Gif: type: object required: - provider_id - url properties: provider_id: type: string minLength: 1 maxLength: 255 url: type: string format: uri maxLength: 8192 pattern: "^https://" preview_url: type: string format: uri maxLength: 8192 pattern: "^https://" title: type: string maxLength: 1000 MessageCreate: type: object properties: sender_id: type: string description: Explicit sender account, optionally ISI@silicon:org (for example compose@writer:tos). The underlying account must be authorized by IAM; ISI requires a silicon. recipient_id: type: string maxLength: 255 description: Optional intended participant address, such as deliberate@cos:tos. ISI requires a silicon participant. This is routing metadata; all conversation participants still receive the message and retain normal history access. attachments: type: array maxItems: 100 items: "$ref": "#/components/schemas/Attachment" description: Combined attachment and voice item count may not exceed 100. voice: "$ref": "#/components/schemas/VoiceAttachment" description: Counts toward the combined 100 attachment-item maximum. voice_transcript: type: - string - 'null' maxLength: 100000000 description: Optional client-supplied transcript preserved as message content; requires voice. gif: "$ref": "#/components/schemas/Gif" metadata: type: object additionalProperties: true default: {} description: Arbitrary caller-owned JSON object, always returned. Nested JSON values are preserved. PATCH is full replacement; include the metadata to retain it. reply_to_message_id: type: - string - 'null' format: uuid description: Reply target in this same conversation. A message cannot reply to itself. message: type: string minLength: 1 maxLength: 100000000 anyOf: - required: - message properties: message: {} - required: - attachments properties: attachments: minItems: 1 - required: - voice properties: voice: {} - required: - gif properties: gif: {} allOf: - if: required: - voice_transcript properties: voice_transcript: type: string then: required: - voice properties: voice: {} description: At least one content item (text, attachments, voice, or GIF) is required. Metadata alone does not count as content. On PATCH this is a full replacement; omitted metadata becomes {}, and omitted optional fields are cleared. Routing is immutable on PATCH; omitted sender_id and recipient_id retain the original route. Logical text/transcript limits apply independently; the configured encoded-body limit may be lower. Message: type: object required: - id - conversation_id - sender - sequence - status - created_at - metadata - version - deleted_at properties: id: type: string format: uuid conversation_id: type: string format: uuid sender: "$ref": "#/components/schemas/ActorRef" sender_id: type: string description: Qualified sender address when an ISI was supplied; sender.id remains the canonical IAM identity. recipient_id: type: string description: Intended recipient address, including the optional ISI prefix, preserved in history and delivery. sequence: type: integer minimum: 1 status: type: string enum: - waiting - sent - delivered - read - failed attachments: type: array maxItems: 100 items: "$ref": "#/components/schemas/Attachment" description: Combined attachment and voice item count may not exceed 100. voice: "$ref": "#/components/schemas/StoredVoiceAttachment" voice_transcript: type: - string - 'null' maxLength: 100000000 gif: "$ref": "#/components/schemas/Gif" bundle: anyOf: - "$ref": "#/components/schemas/BundleRef" - type: 'null' created_at: type: string format: date-time delivered_at: type: - string - 'null' format: date-time read_at: type: - string - 'null' format: date-time failure_reason: type: - string - 'null' metadata: type: object additionalProperties: true default: {} description: Arbitrary caller-owned JSON object, always returned. Nested JSON values are preserved. PATCH is full replacement; include the metadata to retain it. reply_to_message_id: type: - string - 'null' format: uuid description: Reply target in this same conversation. A message cannot reply to itself. version: type: integer minimum: 1 description: Content version, initially 1. Edits and deletion increment it; receipts do not. deleted_at: type: - string - 'null' format: date-time message: type: string minLength: 1 maxLength: 100000000 allOf: - if: required: - voice_transcript properties: voice_transcript: type: string then: required: - voice properties: voice: {} description: Latest version of a durable message. Deleted messages remain as content-free tombstones with the same id, sequence, sender, and version. Do not resurrect them from older replayed deliveries. BundleRef: type: object required: - id - role properties: id: type: string format: uuid role: type: string enum: - display - member BundleCreate: type: object required: - message_ids - display_message properties: message_ids: type: array minItems: 1 maxItems: 100 uniqueItems: true items: type: string format: uuid display_message: "$ref": "#/components/schemas/MessageCreate" Bundle: type: object required: - id - conversation_id - original_message_ids - display_message - created_by - created_at properties: id: type: string format: uuid conversation_id: type: string format: uuid original_message_ids: type: array minItems: 1 maxItems: 100 items: type: string format: uuid display_message: "$ref": "#/components/schemas/Message" created_by: "$ref": "#/components/schemas/ActorRef" created_at: type: string format: date-time BundleDetail: allOf: - "$ref": "#/components/schemas/Bundle" - type: object required: - original_messages properties: original_messages: type: array minItems: 1 maxItems: 100 items: "$ref": "#/components/schemas/Message" DraftInput: type: object properties: message_content: type: string maxLength: 100000000 attachments: type: array maxItems: 100 items: "$ref": "#/components/schemas/Attachment" description: Combined attachment and voice item count may not exceed 100. voice: "$ref": "#/components/schemas/VoiceAttachment" description: Counts toward the combined 100 attachment-item maximum. voice_transcript: type: - string - 'null' maxLength: 100000000 description: Optional synchronized client-supplied transcript; requires voice. gif: "$ref": "#/components/schemas/Gif" metadata: type: object additionalProperties: true default: {} description: Arbitrary caller-owned JSON object, always returned. Nested JSON values are preserved. PATCH is full replacement; include the metadata to retain it. reply_to_message_id: type: - string - 'null' format: uuid description: Reply target in this same conversation. A message cannot reply to itself. allOf: - if: required: - voice_transcript properties: voice_transcript: type: string then: required: - voice properties: voice: {} Draft: type: object required: - conversation_id - actor_id - version - updated_at - metadata properties: conversation_id: type: string format: uuid actor_id: type: string version: type: integer minimum: 1 description: Monotonic token retained across draft deletion and automatic clearing. Gaps are allowed. Use this returned value for the next save. message_content: type: string maxLength: 100000000 attachments: type: array maxItems: 100 items: "$ref": "#/components/schemas/Attachment" voice: "$ref": "#/components/schemas/StoredVoiceAttachment" voice_transcript: type: - string - 'null' maxLength: 100000000 gif: "$ref": "#/components/schemas/Gif" updated_at: type: string format: date-time metadata: type: object additionalProperties: true default: {} description: Arbitrary caller-owned JSON object, always returned. Nested JSON values are preserved. PATCH is full replacement; include the metadata to retain it. reply_to_message_id: type: - string - 'null' format: uuid description: Reply target in this same conversation. A message cannot reply to itself. allOf: - if: required: - voice_transcript properties: voice_transcript: type: string then: required: - voice properties: voice: {} Presence: type: object required: - actor_id - availability properties: actor_id: type: string availability: type: string enum: - online - offline activity: type: - string - 'null' enum: - typing - recording_voice - transcribing_voice - uploading_file - searching_gifs - last_seen_at: type: - string - 'null' format: date-time ClientSocketFrame: oneOf: - "$ref": "#/components/schemas/PongFrame" - "$ref": "#/components/schemas/AckFrame" - "$ref": "#/components/schemas/ResumeFrame" - "$ref": "#/components/schemas/PresenceFrame" - "$ref": "#/components/schemas/ReceiptCommandFrame" - "$ref": "#/components/schemas/SendMessageFrame" ServerSocketFrame: oneOf: - "$ref": "#/components/schemas/ReadyFrame" - "$ref": "#/components/schemas/PingFrame" - "$ref": "#/components/schemas/MessageAcceptedFrame" - "$ref": "#/components/schemas/ReceiptRecordedFrame" - "$ref": "#/components/schemas/MessageDeliveryFrame" - "$ref": "#/components/schemas/ReceiptDeliveryFrame" - "$ref": "#/components/schemas/SocketErrorFrame" SocketFrame: description: Union of client-to-server and server-to-client application frames. oneOf: - "$ref": "#/components/schemas/ClientSocketFrame" - "$ref": "#/components/schemas/ServerSocketFrame" PongFrame: type: object additionalProperties: false required: - type - data properties: type: type: string const: pong data: type: object required: - ping_id properties: ping_id: type: string AckFrame: type: object additionalProperties: false required: - type - data properties: type: type: string const: ack data: type: object required: - actor_id - through_sequence properties: actor_id: type: string through_sequence: type: integer minimum: 0 ResumeFrame: type: object additionalProperties: false required: - type - data properties: type: type: string const: resume data: type: object required: - actor_id - after_sequence properties: actor_id: type: string after_sequence: type: integer minimum: 0 PresenceFrame: type: object additionalProperties: false required: - type - data properties: type: type: string const: presence data: type: object required: - actor_id - activity properties: actor_id: type: string activity: type: - string - 'null' enum: - typing - recording_voice - transcribing_voice - uploading_file - searching_gifs - ReceiptCommandFrame: type: object additionalProperties: false required: - type - data properties: type: type: string const: receipt data: type: object required: - actor_id - conversation_id - message_id - status - device_id properties: actor_id: type: string conversation_id: type: string format: uuid message_id: type: string format: uuid status: type: string enum: - delivered - read device_id: type: string minLength: 1 maxLength: 255 pattern: "^[^\\u0000-\\u001F\\u007F]{1,255}$" SendMessageFrame: type: object additionalProperties: false required: - type - data properties: type: type: string const: new_message data: allOf: - type: object required: - actor_id - org_id - conversation_id - idempotency_key properties: actor_id: type: string org_id: type: string conversation_id: type: string format: uuid idempotency_key: type: string minLength: 8 maxLength: 255 pattern: "^[!-~]{8,255}$" - "$ref": "#/components/schemas/MessageCreate" ReadyFrame: type: object additionalProperties: false required: - type - data properties: type: type: string const: ready data: type: object required: - protocol_version - connection_id - actors - acknowledged_through - testing_generation properties: protocol_version: const: 3 connection_id: type: string format: uuid actors: type: array minItems: 1 maxItems: 100 uniqueItems: true items: type: string acknowledged_through: type: object additionalProperties: type: integer minimum: 0 testing_generation: type: - integer - 'null' minimum: 1 description: Current testing data generation; null in production. Changed generation requires clearing old local cursors and archived inbox before resume0. PingFrame: type: object additionalProperties: false required: - type - data properties: type: type: string const: ping data: type: object required: - ping_id properties: ping_id: type: string MessageAcceptedFrame: type: object additionalProperties: false required: - type - data properties: type: type: string const: message_accepted data: allOf: - type: object description: Ephemeral confirmation that a new_message command was durably accepted. It does not consume a delivery sequence and is not ACKed. required: - idempotency_key properties: idempotency_key: type: string minLength: 8 maxLength: 255 pattern: "^[!-~]{8,255}$" - "$ref": "#/components/schemas/Message" ReceiptRecordedFrame: type: object additionalProperties: false required: - type - data properties: type: type: string const: receipt_recorded data: type: object description: Ephemeral confirmation that a device receipt was durably recorded. It does not consume a delivery sequence and is not ACKed. required: - message_id - status properties: message_id: type: string format: uuid status: type: string enum: - delivered - read MessageDeliveryFrame: type: object additionalProperties: false required: - type - data properties: type: type: string const: new_message data: allOf: - type: object required: - delivery_id - actor_id - delivery_sequence properties: delivery_id: type: string format: uuid actor_id: type: string delivery_sequence: type: integer minimum: 1 description: Durable creation, edit, or deletion delivered to every participant, including sender devices. The message is the latest version; repeated or older delivery records can therefore contain the same latest message. Deduplicate transport by delivery_id and upsert content by data.id/version. - "$ref": "#/components/schemas/Message" ReceiptDeliveryFrame: type: object additionalProperties: false required: - type - data properties: type: type: string const: receipt data: type: object required: - delivery_id - actor_id - delivery_sequence - message_id - status properties: delivery_id: type: string format: uuid actor_id: type: string delivery_sequence: type: integer minimum: 1 message_id: type: string format: uuid status: type: string enum: - sent - delivered - read - failed SocketErrorFrame: type: object additionalProperties: false required: - type - data properties: type: type: string const: error data: type: object required: - code - message - recoverable properties: code: type: string message: type: string recoverable: type: boolean Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string message: type: string ApplicationSession: type: object properties: access_token: type: string writeOnly: false refresh_token: type: string token_type: const: Bearer expires_in: type: integer minimum: 1 scope: type: string actor: "$ref": "#/components/schemas/ActorRef" organization_id: type: string description: Initial workspace; first currently selected organization handle in sorted order. organization_ids: type: array minItems: 1 uniqueItems: true description: Organizations explicitly selected in IAM with current active memberships. Each request still authorizes X-Org-ID. items: type: string required: - access_token - refresh_token - token_type - expires_in - scope - actor - organization_id - organization_ids Identity: type: object properties: actor: "$ref": "#/components/schemas/ActorRef" organization_id: type: string principal_id: type: string format: uuid session_id: type: - string - 'null' format: uuid org_role: type: - string - 'null' capabilities: type: array items: type: string required: - actor - organization_id - principal_id - session_id - org_role - capabilities LoginInput: type: object properties: slt: type: string writeOnly: true description: Opaque IAM short-lived token. Current IAM wire values use oac_; the field is named slt. Never assume the field name is a token prefix. required: - slt additionalProperties: false RefreshInput: type: object properties: refresh_token: type: string writeOnly: true pattern: "^ort_" required: - refresh_token additionalProperties: false LogoutInput: type: object properties: token: type: string writeOnly: true required: - token additionalProperties: false TestingEnvironment: type: object properties: environment_id: type: string format: uuid organization_id: type: string creator_actor_id: type: string creator_actor_kind: type: string enum: - carbon - silicon name: type: string minLength: 1 maxLength: 128 description: type: - string - 'null' maxLength: 4096 iam_environment_id: type: string format: uuid iam_app_id: type: string status: type: string enum: - creating - active - deleted - purging version: type: integer minimum: 1 created_at: type: string format: date-time last_activity_at: type: string format: date-time deleted_at: type: - string - 'null' format: date-time purge_after: type: - string - 'null' format: date-time required: - environment_id - organization_id - creator_actor_id - creator_actor_kind - name - description - iam_environment_id - iam_app_id - status - version - created_at - last_activity_at - deleted_at - purge_after TestingEnvironmentWithKey: allOf: - "$ref": "#/components/schemas/TestingEnvironment" - type: object properties: root_key: type: string pattern: "^[A-Za-z0-9]{32}$" required: - root_key TestingEnvironmentKey: type: object properties: environment_id: type: string format: uuid root_key: type: string pattern: "^[A-Za-z0-9]{32}$" required: - environment_id - root_key TestingEnvironmentList: type: object properties: items: type: array items: "$ref": "#/components/schemas/TestingEnvironment" required: - items TestingEnvironmentCreate: type: object properties: name: type: string description: type: - string - 'null' iam_environment_id: type: string format: uuid iam_environment_key: type: string writeOnly: true pattern: "^[A-Za-z0-9]{32}$" iam_app_id: type: string iam_app_secret: type: string writeOnly: true iam_webhook_secret: type: string writeOnly: true minLength: 32 maxLength: 512 pattern: "^[!-~]{32,512}$" description: Optional dedicated IAM test webhook signer. Supply together with iam_webhook_key_version, or omit both to inherit the backend signer. iam_webhook_key_version: type: integer minimum: 1 description: Exact webhook signer version registered in the paired IAM testing application. Requires iam_webhook_secret. required: - name - iam_environment_id - iam_environment_key - iam_app_id - iam_app_secret additionalProperties: false dependentRequired: iam_webhook_secret: - iam_webhook_key_version iam_webhook_key_version: - iam_webhook_secret TestingEnvironmentUpdate: type: object properties: name: type: string description: type: - string - 'null' description: Empty string clears displayed description; omitted/null leaves unchanged. additionalProperties: false