{ "info": { "title": "Anima API", "version": "0.1.0", "description": "The Anima API provides programmatic access to unified infrastructure for AI agents: create and manage agents; send and receive email; place phone calls and send/receive SMS and voice; store and retrieve vault credentials; manage agent identity; and configure webhooks for real-time events. Authenticate using a Bearer token or an API key passed via the X-API-Key header.", "contact": { "name": "Anima Labs", "url": "https://useanima.sh", "email": "support@useanima.sh" }, "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" } }, "servers": [ { "url": "https://api.useanima.sh/v1", "description": "Production" } ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "openapi": "3.1.1", "paths": { "/addresses": { "post": { "operationId": "address.create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier that owns this address" }, "type": { "enum": [ "BILLING", "SHIPPING", "MAILING", "REGISTERED" ], "type": "string", "description": "Type of address to create" }, "label": { "type": "string", "description": "User-defined label for the address" }, "street1": { "type": "string", "minLength": 1, "description": "Primary street address line" }, "street2": { "type": "string", "description": "Secondary street address line (apt, suite, etc.)" }, "city": { "type": "string", "minLength": 1, "description": "City name" }, "state": { "type": "string", "minLength": 1, "description": "State or province" }, "postalCode": { "type": "string", "minLength": 1, "description": "Postal or ZIP code" }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^[A-Z]{2}$", "description": "2-character ISO 3166-1 alpha-2 country code" } }, "required": [ "agentId", "type", "street1", "city", "state", "postalCode", "country" ], "description": "Input for creating a new address identity" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique address identity identifier" }, "agentId": { "type": "string", "description": "Agent that owns this address" }, "orgId": { "type": "string", "description": "Organization the address belongs to" }, "type": { "enum": [ "BILLING", "SHIPPING", "MAILING", "REGISTERED" ], "type": "string", "description": "Address type" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-defined label" }, "street1": { "type": "string", "description": "Primary street address line" }, "street2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Secondary street address line" }, "city": { "type": "string", "description": "City name" }, "state": { "type": "string", "description": "State or province" }, "postalCode": { "type": "string", "description": "Postal or ZIP code" }, "country": { "type": "string", "description": "2-character ISO country code" }, "validated": { "type": "boolean", "description": "Whether the address has been validated" }, "validatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the address was validated" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Validation provider name" }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Additional metadata" }, "isPrimary": { "type": "boolean", "description": "Whether this is the primary address for its type" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the address was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the address was last updated" } }, "required": [ "id", "agentId", "orgId", "type", "label", "street1", "street2", "city", "state", "postalCode", "country", "validated", "validatedAt", "provider", "metadata", "isPrimary", "createdAt", "updatedAt" ], "description": "Full address identity record" } } } } } }, "get": { "operationId": "address.list", "parameters": [ { "name": "agentId", "in": "query", "required": true, "schema": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier to list addresses for" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "type", "in": "query", "required": false, "schema": { "enum": [ "BILLING", "SHIPPING", "MAILING", "REGISTERED" ], "type": "string", "description": "Filter addresses by type" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique address identity identifier" }, "agentId": { "type": "string", "description": "Agent that owns this address" }, "orgId": { "type": "string", "description": "Organization the address belongs to" }, "type": { "enum": [ "BILLING", "SHIPPING", "MAILING", "REGISTERED" ], "type": "string", "description": "Address type" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-defined label" }, "street1": { "type": "string", "description": "Primary street address line" }, "street2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Secondary street address line" }, "city": { "type": "string", "description": "City name" }, "state": { "type": "string", "description": "State or province" }, "postalCode": { "type": "string", "description": "Postal or ZIP code" }, "country": { "type": "string", "description": "2-character ISO country code" }, "validated": { "type": "boolean", "description": "Whether the address has been validated" }, "validatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the address was validated" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Validation provider name" }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Additional metadata" }, "isPrimary": { "type": "boolean", "description": "Whether this is the primary address for its type" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the address was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the address was last updated" } }, "required": [ "id", "agentId", "orgId", "type", "label", "street1", "street2", "city", "state", "postalCode", "country", "validated", "validatedAt", "provider", "metadata", "isPrimary", "createdAt", "updatedAt" ], "description": "Full address identity record" }, "description": "List of address identities" } } } } } } }, "/addresses/{id}": { "get": { "operationId": "address.get", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Address identity identifier" } }, { "name": "agentId", "in": "query", "required": true, "schema": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier that owns this address" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique address identity identifier" }, "agentId": { "type": "string", "description": "Agent that owns this address" }, "orgId": { "type": "string", "description": "Organization the address belongs to" }, "type": { "enum": [ "BILLING", "SHIPPING", "MAILING", "REGISTERED" ], "type": "string", "description": "Address type" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-defined label" }, "street1": { "type": "string", "description": "Primary street address line" }, "street2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Secondary street address line" }, "city": { "type": "string", "description": "City name" }, "state": { "type": "string", "description": "State or province" }, "postalCode": { "type": "string", "description": "Postal or ZIP code" }, "country": { "type": "string", "description": "2-character ISO country code" }, "validated": { "type": "boolean", "description": "Whether the address has been validated" }, "validatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the address was validated" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Validation provider name" }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Additional metadata" }, "isPrimary": { "type": "boolean", "description": "Whether this is the primary address for its type" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the address was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the address was last updated" } }, "required": [ "id", "agentId", "orgId", "type", "label", "street1", "street2", "city", "state", "postalCode", "country", "validated", "validatedAt", "provider", "metadata", "isPrimary", "createdAt", "updatedAt" ], "description": "Full address identity record" } } } } } }, "put": { "operationId": "address.update", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Address identity identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier that owns this address" }, "type": { "enum": [ "BILLING", "SHIPPING", "MAILING", "REGISTERED" ], "type": "string", "description": "Updated address type" }, "label": { "type": "string", "description": "Updated label" }, "street1": { "type": "string", "minLength": 1, "description": "Updated primary street address line" }, "street2": { "type": "string", "description": "Updated secondary street address line" }, "city": { "type": "string", "minLength": 1, "description": "Updated city name" }, "state": { "type": "string", "minLength": 1, "description": "Updated state or province" }, "postalCode": { "type": "string", "minLength": 1, "description": "Updated postal or ZIP code" }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^[A-Z]{2}$", "description": "Updated 2-character ISO 3166-1 alpha-2 country code" }, "isPrimary": { "type": "boolean", "description": "Set as primary address for this type" } }, "required": [ "agentId" ], "description": "Input for updating an existing address identity" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique address identity identifier" }, "agentId": { "type": "string", "description": "Agent that owns this address" }, "orgId": { "type": "string", "description": "Organization the address belongs to" }, "type": { "enum": [ "BILLING", "SHIPPING", "MAILING", "REGISTERED" ], "type": "string", "description": "Address type" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-defined label" }, "street1": { "type": "string", "description": "Primary street address line" }, "street2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Secondary street address line" }, "city": { "type": "string", "description": "City name" }, "state": { "type": "string", "description": "State or province" }, "postalCode": { "type": "string", "description": "Postal or ZIP code" }, "country": { "type": "string", "description": "2-character ISO country code" }, "validated": { "type": "boolean", "description": "Whether the address has been validated" }, "validatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the address was validated" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Validation provider name" }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Additional metadata" }, "isPrimary": { "type": "boolean", "description": "Whether this is the primary address for its type" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the address was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the address was last updated" } }, "required": [ "id", "agentId", "orgId", "type", "label", "street1", "street2", "city", "state", "postalCode", "country", "validated", "validatedAt", "provider", "metadata", "isPrimary", "createdAt", "updatedAt" ], "description": "Full address identity record" } } } } } }, "delete": { "operationId": "address.delete", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Address identity identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier that owns this address" } }, "required": [ "agentId" ], "description": "Input for identifying a specific address identity" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true, "description": "Always true on successful deletion" } }, "required": [ "success" ] } } } } } } }, "/addresses/{id}/validate": { "post": { "operationId": "address.validate", "description": "Structural (format-only) address validation: normalizes the country to ISO 3166-1 alpha-2, checks US state codes and ZIP shape, and verifies required fields are present. It does NOT check that the address exists or is deliverable, and `suggestions` is currently always empty (reserved for a future postal-data provider).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Address identity identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier that owns this address" } }, "required": [ "agentId" ], "description": "Input for identifying a specific address identity" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "Whether the address passed structural (format-only) validation: ISO 3166-1 alpha-2 country, US state code + ZIP shape for US addresses, non-empty street/city. This is NOT a deliverability or postal-database check." }, "standardized": { "type": "object", "properties": { "type": { "enum": [ "BILLING", "SHIPPING", "MAILING", "REGISTERED" ], "type": "string", "description": "Address type" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-defined label" }, "street1": { "type": "string", "description": "Primary street address line" }, "street2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Secondary street address line" }, "city": { "type": "string", "description": "City name" }, "state": { "type": "string", "description": "State or province" }, "postalCode": { "type": "string", "description": "Postal or ZIP code" }, "country": { "type": "string", "description": "2-character ISO country code" } }, "required": [ "type", "label", "street1", "street2", "city", "state", "postalCode", "country" ], "description": "Standardized version of the address" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Confidence score between 0 and 1" }, "suggestions": { "type": "array", "items": { "type": "object", "properties": { "street1": { "type": "string", "description": "Suggested street address" }, "street2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Suggested secondary address" }, "city": { "type": "string", "description": "Suggested city" }, "state": { "type": "string", "description": "Suggested state" }, "postalCode": { "type": "string", "description": "Suggested postal code" }, "country": { "type": "string", "description": "Suggested country code" } }, "required": [ "street1", "street2", "city", "state", "postalCode", "country" ] }, "description": "Reserved: alternative address suggestions. Currently ALWAYS an empty array — the built-in validator is structural only (provider `anima_lite`) and does not generate alternatives. Populated only if/when a postal-data provider is integrated." } }, "required": [ "valid", "standardized", "confidence", "suggestions" ], "description": "Address validation result. Validation is structural/format-only (provider `anima_lite`): it normalizes the country code and US state, and checks field shapes — it does not verify the address exists or is deliverable." } } } } } } }, "/orgs": { "post": { "operationId": "org.create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120, "description": "Display name of the organization" }, "slug": { "type": "string", "minLength": 2, "maxLength": 64, "pattern": "^[a-z0-9-]+$", "description": "URL-friendly identifier using lowercase letters, digits, and hyphens" }, "clerkOrgId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "External Clerk organization ID for SSO linkage" }, "settings": { "default": {}, "type": "object", "additionalProperties": {}, "description": "Arbitrary key-value settings for the organization" } }, "required": [ "name", "slug" ], "description": "Request body for creating a new organization" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier for the organization" }, "name": { "type": "string", "description": "Display name of the organization" }, "slug": { "type": "string", "description": "URL-friendly identifier for the organization" }, "clerkOrgId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "External Clerk organization ID, null if not linked" }, "tier": { "enum": [ "FREE", "STARTER", "GROWTH", "ENTERPRISE" ], "type": "string", "description": "Current subscription tier" }, "keyRotatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp of the last master-key rotation, null if never rotated" }, "settings": { "type": "object", "additionalProperties": {}, "description": "Arbitrary key-value settings for the organization" }, "outboundConsent": { "type": "object", "properties": { "attested": { "type": "boolean", "description": "True once consent source, DNC attestation, and stamp are all present" }, "consentSource": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Declared basis for outbound contact consent, null if unset" }, "dncAttestation": { "type": "boolean", "description": "Whether the org attested it scrubs against Do-Not-Call lists" }, "attestedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp the attestation was recorded, null if never" }, "attestedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Principal (user id or auth method) that recorded the attestation" } }, "required": [ "attested", "consentSource", "dncAttestation", "attestedAt", "attestedBy" ], "description": "Outbound TCPA consent attestation status for this organization" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the organization was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the organization was last modified" }, "masterKey": { "type": "string", "description": "Master API key for the organization. Returned ONCE on creation — store it securely." } }, "required": [ "id", "name", "slug", "clerkOrgId", "tier", "keyRotatedAt", "settings", "outboundConsent", "createdAt", "updatedAt", "masterKey" ], "description": "Newly-minted organization with one-time master key disclosure" } } } } } }, "get": { "operationId": "org.list", "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Opaque cursor from a previous response to fetch the next page" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of items to return per page (1–100, default 20)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "query", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Search query to filter organizations by name or slug" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier for the organization" }, "name": { "type": "string", "description": "Display name of the organization" }, "slug": { "type": "string", "description": "URL-friendly identifier for the organization" }, "clerkOrgId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "External Clerk organization ID, null if not linked" }, "tier": { "enum": [ "FREE", "STARTER", "GROWTH", "ENTERPRISE" ], "type": "string", "description": "Current subscription tier" }, "keyRotatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp of the last master-key rotation, null if never rotated" }, "settings": { "type": "object", "additionalProperties": {}, "description": "Arbitrary key-value settings for the organization" }, "outboundConsent": { "type": "object", "properties": { "attested": { "type": "boolean", "description": "True once consent source, DNC attestation, and stamp are all present" }, "consentSource": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Declared basis for outbound contact consent, null if unset" }, "dncAttestation": { "type": "boolean", "description": "Whether the org attested it scrubs against Do-Not-Call lists" }, "attestedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp the attestation was recorded, null if never" }, "attestedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Principal (user id or auth method) that recorded the attestation" } }, "required": [ "attested", "consentSource", "dncAttestation", "attestedAt", "attestedBy" ], "description": "Outbound TCPA consent attestation status for this organization" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the organization was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the organization was last modified" } }, "required": [ "id", "name", "slug", "clerkOrgId", "tier", "keyRotatedAt", "settings", "outboundConsent", "createdAt", "updatedAt" ], "description": "Organization resource with full details (no secrets)" }, "description": "Array of organization resources in the current page" }, "pagination": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "Cursor to pass as the `cursor` parameter to retrieve the next page, or null if no more results" }, "hasMore": { "type": "boolean", "description": "Whether additional pages of results are available" } }, "required": [ "nextCursor", "hasMore" ], "description": "Cursor-based pagination metadata" } }, "required": [ "items", "pagination" ], "description": "Paginated list of organizations" } } } } } } }, "/orgs/me": { "get": { "operationId": "org.me", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier for the organization" }, "name": { "type": "string", "description": "Display name of the organization" }, "slug": { "type": "string", "description": "URL-friendly identifier for the organization" }, "clerkOrgId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "External Clerk organization ID, null if not linked" }, "tier": { "enum": [ "FREE", "STARTER", "GROWTH", "ENTERPRISE" ], "type": "string", "description": "Current subscription tier" }, "keyRotatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp of the last master-key rotation, null if never rotated" }, "settings": { "type": "object", "additionalProperties": {}, "description": "Arbitrary key-value settings for the organization" }, "outboundConsent": { "type": "object", "properties": { "attested": { "type": "boolean", "description": "True once consent source, DNC attestation, and stamp are all present" }, "consentSource": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Declared basis for outbound contact consent, null if unset" }, "dncAttestation": { "type": "boolean", "description": "Whether the org attested it scrubs against Do-Not-Call lists" }, "attestedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp the attestation was recorded, null if never" }, "attestedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Principal (user id or auth method) that recorded the attestation" } }, "required": [ "attested", "consentSource", "dncAttestation", "attestedAt", "attestedBy" ], "description": "Outbound TCPA consent attestation status for this organization" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the organization was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the organization was last modified" } }, "required": [ "id", "name", "slug", "clerkOrgId", "tier", "keyRotatedAt", "settings", "outboundConsent", "createdAt", "updatedAt" ], "description": "Organization resource with full details (no secrets)" } } } } } } }, "/orgs/{id}": { "get": { "operationId": "org.get", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique organization identifier" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier for the organization" }, "name": { "type": "string", "description": "Display name of the organization" }, "slug": { "type": "string", "description": "URL-friendly identifier for the organization" }, "clerkOrgId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "External Clerk organization ID, null if not linked" }, "tier": { "enum": [ "FREE", "STARTER", "GROWTH", "ENTERPRISE" ], "type": "string", "description": "Current subscription tier" }, "keyRotatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp of the last master-key rotation, null if never rotated" }, "settings": { "type": "object", "additionalProperties": {}, "description": "Arbitrary key-value settings for the organization" }, "outboundConsent": { "type": "object", "properties": { "attested": { "type": "boolean", "description": "True once consent source, DNC attestation, and stamp are all present" }, "consentSource": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Declared basis for outbound contact consent, null if unset" }, "dncAttestation": { "type": "boolean", "description": "Whether the org attested it scrubs against Do-Not-Call lists" }, "attestedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp the attestation was recorded, null if never" }, "attestedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Principal (user id or auth method) that recorded the attestation" } }, "required": [ "attested", "consentSource", "dncAttestation", "attestedAt", "attestedBy" ], "description": "Outbound TCPA consent attestation status for this organization" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the organization was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the organization was last modified" } }, "required": [ "id", "name", "slug", "clerkOrgId", "tier", "keyRotatedAt", "settings", "outboundConsent", "createdAt", "updatedAt" ], "description": "Organization resource with full details (no secrets)" } } } } } }, "patch": { "operationId": "org.update", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the organization to update" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120, "description": "Updated display name" }, "slug": { "type": "string", "minLength": 2, "maxLength": 64, "pattern": "^[a-z0-9-]+$", "description": "Updated URL-friendly identifier" }, "clerkOrgId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ], "description": "Updated external Clerk organization ID" }, "settings": { "type": "object", "additionalProperties": {}, "description": "Updated key-value settings" } }, "required": [], "description": "Request body for updating an existing organization" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier for the organization" }, "name": { "type": "string", "description": "Display name of the organization" }, "slug": { "type": "string", "description": "URL-friendly identifier for the organization" }, "clerkOrgId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "External Clerk organization ID, null if not linked" }, "tier": { "enum": [ "FREE", "STARTER", "GROWTH", "ENTERPRISE" ], "type": "string", "description": "Current subscription tier" }, "keyRotatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp of the last master-key rotation, null if never rotated" }, "settings": { "type": "object", "additionalProperties": {}, "description": "Arbitrary key-value settings for the organization" }, "outboundConsent": { "type": "object", "properties": { "attested": { "type": "boolean", "description": "True once consent source, DNC attestation, and stamp are all present" }, "consentSource": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Declared basis for outbound contact consent, null if unset" }, "dncAttestation": { "type": "boolean", "description": "Whether the org attested it scrubs against Do-Not-Call lists" }, "attestedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp the attestation was recorded, null if never" }, "attestedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Principal (user id or auth method) that recorded the attestation" } }, "required": [ "attested", "consentSource", "dncAttestation", "attestedAt", "attestedBy" ], "description": "Outbound TCPA consent attestation status for this organization" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the organization was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the organization was last modified" } }, "required": [ "id", "name", "slug", "clerkOrgId", "tier", "keyRotatedAt", "settings", "outboundConsent", "createdAt", "updatedAt" ], "description": "Organization resource with full details (no secrets)" } } } } } }, "delete": { "operationId": "org.delete", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique organization identifier" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "Organization deletion parameters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true, "description": "Always true on successful deletion" } }, "required": [ "success" ], "description": "Deletion confirmation" } } } } } } }, "/orgs/{id}/rotate-key": { "post": { "operationId": "org.rotateKey", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique organization identifier" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "Master key rotation parameters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "masterKey": { "type": "string", "description": "Newly generated master API key" } }, "required": [ "masterKey" ], "description": "Rotated master key credentials" } } } } } } }, "/orgs/{id}/members": { "get": { "operationId": "org.listMembers", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique organization identifier" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Organization membership identifier" }, "userId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Internal user identifier" }, "role": { "enum": [ "OWNER", "ADMIN", "MEMBER" ], "type": "string", "description": "Membership role" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Member email address" }, "firstName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Member given name" }, "lastName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Member family name" }, "imageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Profile image URL" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the membership was created" } }, "required": [ "id", "userId", "role", "email", "firstName", "lastName", "imageUrl", "createdAt" ], "description": "Organization member with profile fields" }, "description": "Members of the organization" } }, "required": [ "items" ], "description": "Organization membership list response" } } } } } } }, "/orgs/feature-interest": { "post": { "operationId": "org.recordFeatureInterest", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "feature": { "enum": [ "vault" ], "type": "string", "description": "Feature the user attempted to access" }, "source": { "default": "sidebar", "enum": [ "sidebar", "page" ], "type": "string", "description": "Where the interest intent came from" } }, "required": [ "feature" ], "description": "Feature-interest tracking payload" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Usage event identifier" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when feature interest was recorded" } }, "required": [ "id", "createdAt" ], "description": "Feature-interest tracking result" } } } } } } }, "/orgs/me/workspace-health": { "get": { "operationId": "org.workspaceHealth", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "enum": [ "ok", "degraded" ], "type": "string", "description": "Overall workspace status. degraded if any blocker is present." }, "org": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, "name": { "type": "string" }, "tier": { "type": "string", "description": "Current billing tier (FREE / GROWTH / SCALE / ...)" }, "signupStatus": { "type": "string", "description": "active / pending_review / suspended" } }, "required": [ "id", "name", "tier", "signupStatus" ], "description": "Organization context" }, "auth": { "type": "object", "properties": { "keyType": { "enum": [ "master", "agent" ], "type": "string", "description": "Whether the calling credential is master-tier or agent-tier" }, "authMethod": { "enum": [ "api_key", "clerk", "scoped_token" ], "type": "string", "description": "How the credential was authenticated" }, "agentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent ID if the credential is agent-bound, null for master" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Granted scopes for OAuth / scoped tokens" } }, "required": [ "keyType", "authMethod", "agentId" ], "description": "Credential context — same data Who_Am_I would surface" }, "capabilities": { "type": "object", "properties": { "canSendEmail": { "type": "boolean", "description": "True iff at least one verified email identity exists across the org's agents" }, "canSendSms": { "type": "boolean", "description": "True iff at least one phone identity has SMS capability and is past 10DLC" } }, "required": [ "canSendEmail", "canSendSms" ], "description": "Cross-cutting send capability summary" }, "inventory": { "type": "object", "properties": { "agents": { "type": "integer", "minimum": 0 }, "agentsReadyToSend": { "type": "integer", "minimum": 0, "description": "Subset of agents whose primary identity is verified" }, "domains": { "type": "integer", "minimum": 0 }, "domainsVerified": { "type": "integer", "minimum": 0 }, "phoneNumbers": { "type": "integer", "minimum": 0 } }, "required": [ "agents", "agentsReadyToSend", "domains", "domainsVerified", "phoneNumbers" ], "description": "Inventory counts useful for self-diagnosis" }, "blockers": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable code (e.g. ORG_SUSPENDED, NO_VERIFIED_DOMAIN)" }, "hint": { "type": "string", "description": "Human-readable remediation" } }, "required": [ "code", "hint" ] }, "description": "All currently-blocking conditions; empty array means status:'ok'" } }, "required": [ "status", "org", "auth", "capabilities", "inventory", "blockers" ], "description": "Per-workspace health summary callable by any authenticated credential" } } } } } } }, "/orgs/me/usage": { "get": { "operationId": "org.usageOverview", "parameters": [ { "name": "period", "in": "query", "schema": { "type": "string", "description": "Billing period in YYYY-MM format (e.g. '2026-05'). Defaults to the current month in UTC." }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "string", "description": "Billing period the rollup covers (YYYY-MM)." }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Latest update timestamp across all returned counters. null if no usage has been recorded yet." }, "totals": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 }, "description": "Counters keyed by usage type (e.g. 'email_sent', 'sms_sent', 'voice_call_minutes'). Missing keys mean zero." } }, "required": [ "period", "updatedAt", "totals" ], "description": "Usage rollup for an organization's billing period" } } } } } } }, "/orgs/claimable": { "get": { "operationId": "org.claimable", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Organization id, to pass to the claim call" }, "name": { "type": "string" }, "slug": { "type": "string" }, "owner_email": { "type": "string", "description": "Masked owner address that entitles you to claim it (d***n@example.com)" }, "created_at": { "type": "string", "format": "date-time", "description": "When the agent created it" } }, "required": [ "id", "name", "slug", "owner_email", "created_at" ] } } }, "required": [ "items" ], "description": "Organizations created by an agent that you have proven you own" } } } } } } }, "/orgs/{id}/claim": { "post": { "operationId": "org.claim", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Organization to claim" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "Claim parameters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier for the organization" }, "name": { "type": "string", "description": "Display name of the organization" }, "slug": { "type": "string", "description": "URL-friendly identifier for the organization" }, "clerkOrgId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "External Clerk organization ID, null if not linked" }, "tier": { "enum": [ "FREE", "STARTER", "GROWTH", "ENTERPRISE" ], "type": "string", "description": "Current subscription tier" }, "keyRotatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp of the last master-key rotation, null if never rotated" }, "settings": { "type": "object", "additionalProperties": {}, "description": "Arbitrary key-value settings for the organization" }, "outboundConsent": { "type": "object", "properties": { "attested": { "type": "boolean", "description": "True once consent source, DNC attestation, and stamp are all present" }, "consentSource": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Declared basis for outbound contact consent, null if unset" }, "dncAttestation": { "type": "boolean", "description": "Whether the org attested it scrubs against Do-Not-Call lists" }, "attestedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp the attestation was recorded, null if never" }, "attestedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Principal (user id or auth method) that recorded the attestation" } }, "required": [ "attested", "consentSource", "dncAttestation", "attestedAt", "attestedBy" ], "description": "Outbound TCPA consent attestation status for this organization" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the organization was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the organization was last modified" } }, "required": [ "id", "name", "slug", "clerkOrgId", "tier", "keyRotatedAt", "settings", "outboundConsent", "createdAt", "updatedAt" ], "description": "Organization resource with full details (no secrets)" } } } } } } }, "/agents": { "post": { "operationId": "agent.create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "orgId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Organization ID that owns this agent (derived from auth if omitted)" }, "name": { "type": "string", "minLength": 2, "maxLength": 100, "description": "Human-readable display name for the agent" }, "slug": { "type": "string", "minLength": 2, "maxLength": 64, "pattern": "^[a-z0-9-]+$", "description": "URL-friendly unique identifier (lowercase alphanumeric and hyphens only)" }, "email": { "type": "string", "format": "email", "description": "Optional email address to provision for this agent" }, "provisionPhone": { "default": false, "type": "boolean", "description": "Whether to automatically provision a phone number for this agent" }, "metadata": { "default": {}, "type": "object", "additionalProperties": {}, "description": "Arbitrary key-value metadata associated with the agent" }, "voiceId": { "type": "string", "description": "Voice for this agent's calls, e.g. \"thalia\". Choose an id from GET /voice/catalog; defaults to the system voice when omitted." }, "inboxId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of an existing inbox to associate with this agent. If omitted, a new inbox is created automatically." } }, "required": [ "name", "slug" ], "description": "Request body for creating a new agent" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the agent" }, "orgId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Organization ID that owns this agent" }, "name": { "type": "string", "description": "Human-readable display name" }, "slug": { "type": "string", "description": "URL-friendly unique identifier" }, "status": { "enum": [ "ACTIVE", "SUSPENDED", "DELETED" ], "type": "string", "description": "Current lifecycle status" }, "apiKeyPrefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Prefix of the agent's API key for identification, or null if no key is set" }, "keyRotatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp of the last API-key rotation, null if never rotated" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Arbitrary key-value metadata" }, "voiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The agent's chosen voice id, or null for the system default." }, "emailIdentities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the email identity" }, "email": { "type": "string", "format": "email", "description": "Full email address" }, "domain": { "type": "string", "description": "Domain portion of the email address" }, "localPart": { "type": "string", "description": "Local part (before the @) of the email address" }, "isPrimary": { "type": "boolean", "description": "Whether this is the agent's primary email identity" }, "verified": { "type": "boolean", "description": "Whether the email address has been verified" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the email identity was created" } }, "required": [ "id", "email", "domain", "localPart", "isPrimary", "verified", "createdAt" ], "description": "Email identity associated with an agent" }, "description": "Email identities associated with this agent" }, "phoneIdentities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the phone identity" }, "phoneNumber": { "type": "string", "description": "Phone number in E.164 format" }, "providerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque carrier-side identifier for this phone number" }, "capabilities": { "type": "object", "properties": { "sms": { "default": false, "type": "boolean", "description": "Whether the number supports SMS messaging" }, "mms": { "default": false, "type": "boolean", "description": "Whether the number supports MMS messaging" }, "voice": { "default": false, "type": "boolean", "description": "Whether the number supports voice calls" } }, "description": "Communication capabilities supported by this phone number" }, "tenDlcStatus": { "enum": [ "PENDING", "REGISTERED", "REJECTED", "NOT_REQUIRED", "UNREGISTERED" ], "type": "string", "description": "10DLC campaign registration status" }, "isPrimary": { "type": "boolean", "description": "Whether this is the agent's primary phone identity" }, "voiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The voice this number answers with, from the voice catalog. Null means it uses the agent's voice, and then the system default. Set it per number so one agent's support line and sales line can sound different." }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the phone identity was created" } }, "required": [ "id", "phoneNumber", "providerId", "capabilities", "tenDlcStatus", "isPrimary", "voiceId", "createdAt" ], "description": "Phone identity associated with an agent" }, "description": "Phone identities associated with this agent" }, "readiness": { "type": "object", "properties": { "canSendEmail": { "type": "boolean", "description": "True iff the agent has at least one verified email identity right now" }, "canReceiveEmail": { "type": "boolean", "description": "True iff inbound MX is configured for the agent's primary domain" }, "canSendSms": { "type": "boolean", "description": "True iff the agent has a provisioned phone identity with SMS capability that's past 10DLC if required" }, "canPlaceVoiceCall": { "type": "boolean", "description": "True iff the agent has a phone identity with voice capability" }, "blockers": { "type": "array", "items": { "type": "object", "properties": { "code": { "enum": [ "IDENTITY_NOT_VERIFIED", "DOMAIN_NOT_VERIFIED", "PHONE_NOT_PROVISIONED" ], "type": "string", "description": "Stable code matching the typed error thrown at call time" }, "field": { "type": "string", "description": "JSON-path-ish location of the failing field, e.g. emailIdentities[0]" }, "hint": { "type": "string", "description": "Human-readable remediation hint" }, "remediationUrl": { "type": "string", "description": "Optional pointer to where the user can resolve this blocker" } }, "required": [ "code", "field", "hint" ], "description": "One reason a capability isn't currently usable" }, "description": "All current blockers across capabilities; empty array means fully ready" } }, "required": [ "canSendEmail", "canReceiveEmail", "canSendSms", "canPlaceVoiceCall", "blockers" ], "description": "Per-capability readiness summary. Optional for backward compatibility — clients without readiness handling continue to work; clients that branch on it get the delayed-verification gap closed." }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the agent was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the agent was last updated" } }, "required": [ "id", "orgId", "name", "slug", "status", "apiKeyPrefix", "keyRotatedAt", "metadata", "voiceId", "emailIdentities", "phoneIdentities", "createdAt", "updatedAt" ], "description": "Full agent resource representation" } } } } } }, "get": { "operationId": "agent.list", "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Opaque cursor from a previous response to fetch the next page" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of items to return per page (1–100, default 20)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "orgId", "in": "query", "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Filter agents by organization ID" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "status", "in": "query", "schema": { "enum": [ "ACTIVE", "SUSPENDED", "DELETED" ], "type": "string", "description": "Filter agents by lifecycle status" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "query", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Free-text search query to filter agents by name or slug" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the agent" }, "orgId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Organization ID that owns this agent" }, "name": { "type": "string", "description": "Human-readable display name" }, "slug": { "type": "string", "description": "URL-friendly unique identifier" }, "status": { "enum": [ "ACTIVE", "SUSPENDED", "DELETED" ], "type": "string", "description": "Current lifecycle status" }, "apiKeyPrefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Prefix of the agent's API key for identification, or null if no key is set" }, "keyRotatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp of the last API-key rotation, null if never rotated" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Arbitrary key-value metadata" }, "voiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The agent's chosen voice id, or null for the system default." }, "emailIdentities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the email identity" }, "email": { "type": "string", "format": "email", "description": "Full email address" }, "domain": { "type": "string", "description": "Domain portion of the email address" }, "localPart": { "type": "string", "description": "Local part (before the @) of the email address" }, "isPrimary": { "type": "boolean", "description": "Whether this is the agent's primary email identity" }, "verified": { "type": "boolean", "description": "Whether the email address has been verified" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the email identity was created" } }, "required": [ "id", "email", "domain", "localPart", "isPrimary", "verified", "createdAt" ], "description": "Email identity associated with an agent" }, "description": "Email identities associated with this agent" }, "phoneIdentities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the phone identity" }, "phoneNumber": { "type": "string", "description": "Phone number in E.164 format" }, "providerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque carrier-side identifier for this phone number" }, "capabilities": { "type": "object", "properties": { "sms": { "default": false, "type": "boolean", "description": "Whether the number supports SMS messaging" }, "mms": { "default": false, "type": "boolean", "description": "Whether the number supports MMS messaging" }, "voice": { "default": false, "type": "boolean", "description": "Whether the number supports voice calls" } }, "description": "Communication capabilities supported by this phone number" }, "tenDlcStatus": { "enum": [ "PENDING", "REGISTERED", "REJECTED", "NOT_REQUIRED", "UNREGISTERED" ], "type": "string", "description": "10DLC campaign registration status" }, "isPrimary": { "type": "boolean", "description": "Whether this is the agent's primary phone identity" }, "voiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The voice this number answers with, from the voice catalog. Null means it uses the agent's voice, and then the system default. Set it per number so one agent's support line and sales line can sound different." }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the phone identity was created" } }, "required": [ "id", "phoneNumber", "providerId", "capabilities", "tenDlcStatus", "isPrimary", "voiceId", "createdAt" ], "description": "Phone identity associated with an agent" }, "description": "Phone identities associated with this agent" }, "readiness": { "type": "object", "properties": { "canSendEmail": { "type": "boolean", "description": "True iff the agent has at least one verified email identity right now" }, "canReceiveEmail": { "type": "boolean", "description": "True iff inbound MX is configured for the agent's primary domain" }, "canSendSms": { "type": "boolean", "description": "True iff the agent has a provisioned phone identity with SMS capability that's past 10DLC if required" }, "canPlaceVoiceCall": { "type": "boolean", "description": "True iff the agent has a phone identity with voice capability" }, "blockers": { "type": "array", "items": { "type": "object", "properties": { "code": { "enum": [ "IDENTITY_NOT_VERIFIED", "DOMAIN_NOT_VERIFIED", "PHONE_NOT_PROVISIONED" ], "type": "string", "description": "Stable code matching the typed error thrown at call time" }, "field": { "type": "string", "description": "JSON-path-ish location of the failing field, e.g. emailIdentities[0]" }, "hint": { "type": "string", "description": "Human-readable remediation hint" }, "remediationUrl": { "type": "string", "description": "Optional pointer to where the user can resolve this blocker" } }, "required": [ "code", "field", "hint" ], "description": "One reason a capability isn't currently usable" }, "description": "All current blockers across capabilities; empty array means fully ready" } }, "required": [ "canSendEmail", "canReceiveEmail", "canSendSms", "canPlaceVoiceCall", "blockers" ], "description": "Per-capability readiness summary. Optional for backward compatibility — clients without readiness handling continue to work; clients that branch on it get the delayed-verification gap closed." }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the agent was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the agent was last updated" } }, "required": [ "id", "orgId", "name", "slug", "status", "apiKeyPrefix", "keyRotatedAt", "metadata", "voiceId", "emailIdentities", "phoneIdentities", "createdAt", "updatedAt" ], "description": "Full agent resource representation" }, "description": "Array of agent resources matching the query" }, "pagination": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "Cursor to pass as the `cursor` parameter to retrieve the next page, or null if no more results" }, "hasMore": { "type": "boolean", "description": "Whether additional pages of results are available" } }, "required": [ "nextCursor", "hasMore" ], "description": "Pagination metadata for retrieving additional pages" } }, "required": [ "items", "pagination" ], "description": "Paginated list of agents" } } } } } } }, "/agents/{id}": { "get": { "operationId": "agent.get", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique agent identifier" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the agent" }, "orgId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Organization ID that owns this agent" }, "name": { "type": "string", "description": "Human-readable display name" }, "slug": { "type": "string", "description": "URL-friendly unique identifier" }, "status": { "enum": [ "ACTIVE", "SUSPENDED", "DELETED" ], "type": "string", "description": "Current lifecycle status" }, "apiKeyPrefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Prefix of the agent's API key for identification, or null if no key is set" }, "keyRotatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp of the last API-key rotation, null if never rotated" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Arbitrary key-value metadata" }, "voiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The agent's chosen voice id, or null for the system default." }, "emailIdentities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the email identity" }, "email": { "type": "string", "format": "email", "description": "Full email address" }, "domain": { "type": "string", "description": "Domain portion of the email address" }, "localPart": { "type": "string", "description": "Local part (before the @) of the email address" }, "isPrimary": { "type": "boolean", "description": "Whether this is the agent's primary email identity" }, "verified": { "type": "boolean", "description": "Whether the email address has been verified" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the email identity was created" } }, "required": [ "id", "email", "domain", "localPart", "isPrimary", "verified", "createdAt" ], "description": "Email identity associated with an agent" }, "description": "Email identities associated with this agent" }, "phoneIdentities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the phone identity" }, "phoneNumber": { "type": "string", "description": "Phone number in E.164 format" }, "providerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque carrier-side identifier for this phone number" }, "capabilities": { "type": "object", "properties": { "sms": { "default": false, "type": "boolean", "description": "Whether the number supports SMS messaging" }, "mms": { "default": false, "type": "boolean", "description": "Whether the number supports MMS messaging" }, "voice": { "default": false, "type": "boolean", "description": "Whether the number supports voice calls" } }, "description": "Communication capabilities supported by this phone number" }, "tenDlcStatus": { "enum": [ "PENDING", "REGISTERED", "REJECTED", "NOT_REQUIRED", "UNREGISTERED" ], "type": "string", "description": "10DLC campaign registration status" }, "isPrimary": { "type": "boolean", "description": "Whether this is the agent's primary phone identity" }, "voiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The voice this number answers with, from the voice catalog. Null means it uses the agent's voice, and then the system default. Set it per number so one agent's support line and sales line can sound different." }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the phone identity was created" } }, "required": [ "id", "phoneNumber", "providerId", "capabilities", "tenDlcStatus", "isPrimary", "voiceId", "createdAt" ], "description": "Phone identity associated with an agent" }, "description": "Phone identities associated with this agent" }, "readiness": { "type": "object", "properties": { "canSendEmail": { "type": "boolean", "description": "True iff the agent has at least one verified email identity right now" }, "canReceiveEmail": { "type": "boolean", "description": "True iff inbound MX is configured for the agent's primary domain" }, "canSendSms": { "type": "boolean", "description": "True iff the agent has a provisioned phone identity with SMS capability that's past 10DLC if required" }, "canPlaceVoiceCall": { "type": "boolean", "description": "True iff the agent has a phone identity with voice capability" }, "blockers": { "type": "array", "items": { "type": "object", "properties": { "code": { "enum": [ "IDENTITY_NOT_VERIFIED", "DOMAIN_NOT_VERIFIED", "PHONE_NOT_PROVISIONED" ], "type": "string", "description": "Stable code matching the typed error thrown at call time" }, "field": { "type": "string", "description": "JSON-path-ish location of the failing field, e.g. emailIdentities[0]" }, "hint": { "type": "string", "description": "Human-readable remediation hint" }, "remediationUrl": { "type": "string", "description": "Optional pointer to where the user can resolve this blocker" } }, "required": [ "code", "field", "hint" ], "description": "One reason a capability isn't currently usable" }, "description": "All current blockers across capabilities; empty array means fully ready" } }, "required": [ "canSendEmail", "canReceiveEmail", "canSendSms", "canPlaceVoiceCall", "blockers" ], "description": "Per-capability readiness summary. Optional for backward compatibility — clients without readiness handling continue to work; clients that branch on it get the delayed-verification gap closed." }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the agent was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the agent was last updated" } }, "required": [ "id", "orgId", "name", "slug", "status", "apiKeyPrefix", "keyRotatedAt", "metadata", "voiceId", "emailIdentities", "phoneIdentities", "createdAt", "updatedAt" ], "description": "Full agent resource representation" } } } } } }, "patch": { "operationId": "agent.update", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the agent to update" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 100, "description": "Updated display name for the agent" }, "slug": { "type": "string", "minLength": 2, "maxLength": 64, "pattern": "^[a-z0-9-]+$", "description": "Updated URL-friendly unique identifier" }, "status": { "enum": [ "ACTIVE", "SUSPENDED", "DELETED" ], "type": "string", "description": "Updated lifecycle status" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Updated key-value metadata (replaces existing metadata)" }, "voiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Updated voice id (from GET /voice/catalog), or null to reset to the system default." } }, "required": [], "description": "Request body for updating an existing agent" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the agent" }, "orgId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Organization ID that owns this agent" }, "name": { "type": "string", "description": "Human-readable display name" }, "slug": { "type": "string", "description": "URL-friendly unique identifier" }, "status": { "enum": [ "ACTIVE", "SUSPENDED", "DELETED" ], "type": "string", "description": "Current lifecycle status" }, "apiKeyPrefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Prefix of the agent's API key for identification, or null if no key is set" }, "keyRotatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp of the last API-key rotation, null if never rotated" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Arbitrary key-value metadata" }, "voiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The agent's chosen voice id, or null for the system default." }, "emailIdentities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the email identity" }, "email": { "type": "string", "format": "email", "description": "Full email address" }, "domain": { "type": "string", "description": "Domain portion of the email address" }, "localPart": { "type": "string", "description": "Local part (before the @) of the email address" }, "isPrimary": { "type": "boolean", "description": "Whether this is the agent's primary email identity" }, "verified": { "type": "boolean", "description": "Whether the email address has been verified" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the email identity was created" } }, "required": [ "id", "email", "domain", "localPart", "isPrimary", "verified", "createdAt" ], "description": "Email identity associated with an agent" }, "description": "Email identities associated with this agent" }, "phoneIdentities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the phone identity" }, "phoneNumber": { "type": "string", "description": "Phone number in E.164 format" }, "providerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque carrier-side identifier for this phone number" }, "capabilities": { "type": "object", "properties": { "sms": { "default": false, "type": "boolean", "description": "Whether the number supports SMS messaging" }, "mms": { "default": false, "type": "boolean", "description": "Whether the number supports MMS messaging" }, "voice": { "default": false, "type": "boolean", "description": "Whether the number supports voice calls" } }, "description": "Communication capabilities supported by this phone number" }, "tenDlcStatus": { "enum": [ "PENDING", "REGISTERED", "REJECTED", "NOT_REQUIRED", "UNREGISTERED" ], "type": "string", "description": "10DLC campaign registration status" }, "isPrimary": { "type": "boolean", "description": "Whether this is the agent's primary phone identity" }, "voiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The voice this number answers with, from the voice catalog. Null means it uses the agent's voice, and then the system default. Set it per number so one agent's support line and sales line can sound different." }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the phone identity was created" } }, "required": [ "id", "phoneNumber", "providerId", "capabilities", "tenDlcStatus", "isPrimary", "voiceId", "createdAt" ], "description": "Phone identity associated with an agent" }, "description": "Phone identities associated with this agent" }, "readiness": { "type": "object", "properties": { "canSendEmail": { "type": "boolean", "description": "True iff the agent has at least one verified email identity right now" }, "canReceiveEmail": { "type": "boolean", "description": "True iff inbound MX is configured for the agent's primary domain" }, "canSendSms": { "type": "boolean", "description": "True iff the agent has a provisioned phone identity with SMS capability that's past 10DLC if required" }, "canPlaceVoiceCall": { "type": "boolean", "description": "True iff the agent has a phone identity with voice capability" }, "blockers": { "type": "array", "items": { "type": "object", "properties": { "code": { "enum": [ "IDENTITY_NOT_VERIFIED", "DOMAIN_NOT_VERIFIED", "PHONE_NOT_PROVISIONED" ], "type": "string", "description": "Stable code matching the typed error thrown at call time" }, "field": { "type": "string", "description": "JSON-path-ish location of the failing field, e.g. emailIdentities[0]" }, "hint": { "type": "string", "description": "Human-readable remediation hint" }, "remediationUrl": { "type": "string", "description": "Optional pointer to where the user can resolve this blocker" } }, "required": [ "code", "field", "hint" ], "description": "One reason a capability isn't currently usable" }, "description": "All current blockers across capabilities; empty array means fully ready" } }, "required": [ "canSendEmail", "canReceiveEmail", "canSendSms", "canPlaceVoiceCall", "blockers" ], "description": "Per-capability readiness summary. Optional for backward compatibility — clients without readiness handling continue to work; clients that branch on it get the delayed-verification gap closed." }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the agent was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the agent was last updated" } }, "required": [ "id", "orgId", "name", "slug", "status", "apiKeyPrefix", "keyRotatedAt", "metadata", "voiceId", "emailIdentities", "phoneIdentities", "createdAt", "updatedAt" ], "description": "Full agent resource representation" } } } } } }, "delete": { "operationId": "agent.delete", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique agent identifier" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "Agent deletion parameters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true, "description": "Always true on successful deletion" } }, "required": [ "success" ], "description": "Deletion confirmation" } } } } } } }, "/agents/{id}/rotate-key": { "post": { "operationId": "agent.rotateKey", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique agent identifier" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "API key rotation parameters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKey": { "type": "string", "description": "Newly generated API key" }, "apiKeyPrefix": { "type": "string", "description": "Prefix of the new API key for identification" } }, "required": [ "apiKey", "apiKeyPrefix" ], "description": "Rotated API key credentials" } } } } } } }, "/agents/{agentId}/policy": { "get": { "operationId": "agent.getPolicy", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Agent identifier to retrieve policy for" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "description": "Agent identifier" }, "policy": { "type": "object", "properties": { "email": { "type": "object", "properties": { "allowedRecipientDomains": { "default": [], "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "If non-empty, agent may ONLY send to these domains" }, "blockedRecipientDomains": { "default": [], "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Agent may NEVER send to these domains" }, "maxPerHour": { "type": "integer", "minimum": 0, "description": "Override emails-per-hour rate limit for this agent" } }, "additionalProperties": false, "description": "Email capability constraints" }, "contentSafety": { "type": "object", "properties": { "scanLevel": { "default": "off", "enum": [ "off", "basic", "strict" ], "type": "string", "description": "Outbound content scanning intensity" }, "injectionScanEnabled": { "default": false, "type": "boolean", "description": "Whether prompt-injection detection runs on outgoing messages" }, "autoApproveBelow": { "default": "medium", "enum": [ "none", "medium", "high" ], "type": "string", "description": "Auto-approve flagged messages at or below this risk threshold" }, "blockedPatterns": { "default": [], "type": "array", "items": { "type": "string" }, "description": "Regex patterns blocked in outgoing messages" } }, "additionalProperties": false, "description": "Outbound content-safety constraints (formerly the separate Security Policy)" }, "vault": { "type": "object", "properties": { "readOnly": { "default": false, "type": "boolean", "description": "Agent can read vault items but cannot create, update, or delete" }, "blocked": { "default": false, "type": "boolean", "description": "Completely disable vault access for this agent" } }, "additionalProperties": false, "description": "Vault capability constraints" }, "phone": { "type": "object", "properties": { "allowedCountries": { "default": [], "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 2 }, "description": "ISO 3166-1 alpha-2 country codes. If non-empty, agent may only call/text these." }, "maxSmsPerHour": { "type": "integer", "minimum": 0, "description": "Override SMS-per-hour rate limit for this agent" }, "blocked": { "default": false, "type": "boolean", "description": "Completely disable phone/SMS capabilities for this agent" } }, "additionalProperties": false, "description": "Phone/SMS capability constraints" }, "voice": { "type": "object", "properties": { "allowedCountries": { "default": [], "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 2 }, "description": "ISO 3166-1 alpha-2 country codes. If non-empty, agent may only call these." }, "blocked": { "default": false, "type": "boolean", "description": "Completely disable outbound voice calls for this agent" } }, "additionalProperties": false, "description": "Voice-call capability constraints" } }, "additionalProperties": false, "description": "Current capability policy" } }, "required": [ "agentId", "policy" ], "description": "Agent policy response" } } } } } }, "put": { "operationId": "agent.updatePolicy", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Agent identifier to update policy for" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "type": "object", "properties": { "email": { "type": "object", "properties": { "allowedRecipientDomains": { "default": [], "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "If non-empty, agent may ONLY send to these domains" }, "blockedRecipientDomains": { "default": [], "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Agent may NEVER send to these domains" }, "maxPerHour": { "type": "integer", "minimum": 0, "description": "Override emails-per-hour rate limit for this agent" } }, "additionalProperties": false, "description": "Email capability constraints" }, "contentSafety": { "type": "object", "properties": { "scanLevel": { "default": "off", "enum": [ "off", "basic", "strict" ], "type": "string", "description": "Outbound content scanning intensity" }, "injectionScanEnabled": { "default": false, "type": "boolean", "description": "Whether prompt-injection detection runs on outgoing messages" }, "autoApproveBelow": { "default": "medium", "enum": [ "none", "medium", "high" ], "type": "string", "description": "Auto-approve flagged messages at or below this risk threshold" }, "blockedPatterns": { "default": [], "type": "array", "items": { "type": "string" }, "description": "Regex patterns blocked in outgoing messages" } }, "additionalProperties": false, "description": "Outbound content-safety constraints (formerly the separate Security Policy)" }, "vault": { "type": "object", "properties": { "readOnly": { "default": false, "type": "boolean", "description": "Agent can read vault items but cannot create, update, or delete" }, "blocked": { "default": false, "type": "boolean", "description": "Completely disable vault access for this agent" } }, "additionalProperties": false, "description": "Vault capability constraints" }, "phone": { "type": "object", "properties": { "allowedCountries": { "default": [], "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 2 }, "description": "ISO 3166-1 alpha-2 country codes. If non-empty, agent may only call/text these." }, "maxSmsPerHour": { "type": "integer", "minimum": 0, "description": "Override SMS-per-hour rate limit for this agent" }, "blocked": { "default": false, "type": "boolean", "description": "Completely disable phone/SMS capabilities for this agent" } }, "additionalProperties": false, "description": "Phone/SMS capability constraints" }, "voice": { "type": "object", "properties": { "allowedCountries": { "default": [], "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 2 }, "description": "ISO 3166-1 alpha-2 country codes. If non-empty, agent may only call these." }, "blocked": { "default": false, "type": "boolean", "description": "Completely disable outbound voice calls for this agent" } }, "additionalProperties": false, "description": "Voice-call capability constraints" } }, "additionalProperties": false, "description": "New policy to apply" } }, "required": [ "policy" ], "description": "Input for updating an agent's capability policy" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "description": "Agent identifier" }, "policy": { "type": "object", "properties": { "email": { "type": "object", "properties": { "allowedRecipientDomains": { "default": [], "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "If non-empty, agent may ONLY send to these domains" }, "blockedRecipientDomains": { "default": [], "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Agent may NEVER send to these domains" }, "maxPerHour": { "type": "integer", "minimum": 0, "description": "Override emails-per-hour rate limit for this agent" } }, "additionalProperties": false, "description": "Email capability constraints" }, "contentSafety": { "type": "object", "properties": { "scanLevel": { "default": "off", "enum": [ "off", "basic", "strict" ], "type": "string", "description": "Outbound content scanning intensity" }, "injectionScanEnabled": { "default": false, "type": "boolean", "description": "Whether prompt-injection detection runs on outgoing messages" }, "autoApproveBelow": { "default": "medium", "enum": [ "none", "medium", "high" ], "type": "string", "description": "Auto-approve flagged messages at or below this risk threshold" }, "blockedPatterns": { "default": [], "type": "array", "items": { "type": "string" }, "description": "Regex patterns blocked in outgoing messages" } }, "additionalProperties": false, "description": "Outbound content-safety constraints (formerly the separate Security Policy)" }, "vault": { "type": "object", "properties": { "readOnly": { "default": false, "type": "boolean", "description": "Agent can read vault items but cannot create, update, or delete" }, "blocked": { "default": false, "type": "boolean", "description": "Completely disable vault access for this agent" } }, "additionalProperties": false, "description": "Vault capability constraints" }, "phone": { "type": "object", "properties": { "allowedCountries": { "default": [], "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 2 }, "description": "ISO 3166-1 alpha-2 country codes. If non-empty, agent may only call/text these." }, "maxSmsPerHour": { "type": "integer", "minimum": 0, "description": "Override SMS-per-hour rate limit for this agent" }, "blocked": { "default": false, "type": "boolean", "description": "Completely disable phone/SMS capabilities for this agent" } }, "additionalProperties": false, "description": "Phone/SMS capability constraints" }, "voice": { "type": "object", "properties": { "allowedCountries": { "default": [], "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 2 }, "description": "ISO 3166-1 alpha-2 country codes. If non-empty, agent may only call these." }, "blocked": { "default": false, "type": "boolean", "description": "Completely disable outbound voice calls for this agent" } }, "additionalProperties": false, "description": "Voice-call capability constraints" } }, "additionalProperties": false, "description": "Current capability policy" } }, "required": [ "agentId", "policy" ], "description": "Agent policy response" } } } } } } }, "/agents/{agentId}/email-identities": { "get": { "operationId": "agent.listEmailIdentities", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Agent whose identities to list" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the email identity" }, "email": { "type": "string", "format": "email", "description": "Full email address" }, "domain": { "type": "string", "description": "Domain portion of the email address" }, "localPart": { "type": "string", "description": "Local part (before the @) of the email address" }, "isPrimary": { "type": "boolean", "description": "Whether this is the agent's primary email identity" }, "verified": { "type": "boolean", "description": "Whether the email address has been verified" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the email identity was created" } }, "required": [ "id", "email", "domain", "localPart", "isPrimary", "verified", "createdAt" ], "description": "Email identity associated with an agent" }, "description": "All email identities attached to this agent" } }, "required": [ "items" ], "description": "List of agent email identities" } } } } } } }, "/agents/{agentId}/email-identities/{identityId}/verify": { "post": { "operationId": "agent.verifyEmailIdentity", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Owning agent ID" } }, { "name": "identityId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Email identity ID being acted on" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "Identifies a specific email identity for a per-identity action" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the email identity" }, "email": { "type": "string", "format": "email", "description": "Full email address" }, "domain": { "type": "string", "description": "Domain portion of the email address" }, "localPart": { "type": "string", "description": "Local part (before the @) of the email address" }, "isPrimary": { "type": "boolean", "description": "Whether this is the agent's primary email identity" }, "verified": { "type": "boolean", "description": "Whether the email address has been verified" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the email identity was created" } }, "required": [ "id", "email", "domain", "localPart", "isPrimary", "verified", "createdAt" ], "description": "Email identity associated with an agent" } } } } } } }, "/api-keys": { "post": { "operationId": "apiKeys.create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Human-readable label for the API key" }, "mode": { "default": "LIVE", "enum": [ "LIVE", "TEST" ], "type": "string", "description": "Environment mode for the key" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Restrict this key to a specific agent by ID" }, "scopes": { "type": "array", "items": { "enum": [ "*", "email:read", "email:send", "phone:read", "phone:sms", "phone:voice", "phone:provision", "messages:read", "messages:send", "messages:search", "voice:read", "vault:read", "vault:use", "vault:write", "vault:share", "vault:oauth", "vault:inject", "identity:read", "identity:write", "agents:read", "agents:write", "inbox:read", "inbox:write", "domains:read", "domains:write", "addresses:read", "addresses:write", "webhooks:read", "webhooks:write", "billing:read", "audit:read", "extension:connect" ], "type": "string", "description": "A single permission scope, or the wildcard '*' for full access" }, "minItems": 1, "description": "Permission scopes granted to this key. Use ['*'] for full access, or list specific scopes from the catalogue (e.g. ['email:read', 'email:send']). An empty array is rejected — empty no longer means 'full access'." }, "expiresAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the key automatically expires" } }, "required": [ "scopes" ], "description": "Request body for creating a new API key" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier for the API key" }, "orgId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Organization that owns this API key" }, "agentId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "Agent this key is restricted to, null if unrestricted" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable label for the API key" }, "prefix": { "type": "string", "description": "Non-secret prefix of the key for identification" }, "mode": { "enum": [ "LIVE", "TEST" ], "type": "string", "description": "Environment mode of the key" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Permission scopes granted to this key" }, "revoked": { "type": "boolean", "description": "Whether the key has been revoked" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the key was created" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp when the key was last used, null if never used" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp when the key expires, null if no expiration" }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User ID of the key creator, null if created by system" }, "extension": { "anyOf": [ { "type": "object", "properties": { "authPolicy": { "enum": [ "session", "pre_approved", "prompt_owner" ], "type": "string" }, "tokenTtl": { "enum": [ "15m", "1h", "session" ], "type": "string" } }, "required": [ "authPolicy", "tokenTtl" ] }, { "type": "null" } ], "description": "Extension-token settings surfaced from metadata. Present only for extension:bridge keys." }, "key": { "type": "string", "description": "Full secret API key value, only returned once at creation time" } }, "required": [ "id", "orgId", "agentId", "name", "prefix", "mode", "scopes", "revoked", "createdAt", "lastUsedAt", "expiresAt", "createdBy", "key" ], "description": "API key resource including the secret value, returned only on creation" } } } } } }, "get": { "operationId": "apiKeys.list", "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Opaque cursor from a previous response to fetch the next page" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of items to return per page (1–100, default 20)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "mode", "in": "query", "schema": { "enum": [ "LIVE", "TEST" ], "type": "string", "description": "Filter keys by environment mode" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "agentId", "in": "query", "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Filter keys restricted to a specific agent" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "includeRevoked", "in": "query", "schema": { "default": false, "type": "boolean", "description": "Whether to include revoked keys in results" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier for the API key" }, "orgId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Organization that owns this API key" }, "agentId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "Agent this key is restricted to, null if unrestricted" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable label for the API key" }, "prefix": { "type": "string", "description": "Non-secret prefix of the key for identification" }, "mode": { "enum": [ "LIVE", "TEST" ], "type": "string", "description": "Environment mode of the key" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Permission scopes granted to this key" }, "revoked": { "type": "boolean", "description": "Whether the key has been revoked" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the key was created" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp when the key was last used, null if never used" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp when the key expires, null if no expiration" }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User ID of the key creator, null if created by system" }, "extension": { "anyOf": [ { "type": "object", "properties": { "authPolicy": { "enum": [ "session", "pre_approved", "prompt_owner" ], "type": "string" }, "tokenTtl": { "enum": [ "15m", "1h", "session" ], "type": "string" } }, "required": [ "authPolicy", "tokenTtl" ] }, { "type": "null" } ], "description": "Extension-token settings surfaced from metadata. Present only for extension:bridge keys." } }, "required": [ "id", "orgId", "agentId", "name", "prefix", "mode", "scopes", "revoked", "createdAt", "lastUsedAt", "expiresAt", "createdBy" ], "description": "API key resource without the secret value" }, "description": "Array of API key resources in the current page" }, "pagination": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "Cursor to pass as the `cursor` parameter to retrieve the next page, or null if no more results" }, "hasMore": { "type": "boolean", "description": "Whether additional pages of results are available" } }, "required": [ "nextCursor", "hasMore" ], "description": "Cursor-based pagination metadata" } }, "required": [ "items", "pagination" ], "description": "Paginated list of API keys" } } } } } } }, "/api-keys/{id}": { "patch": { "operationId": "apiKeys.update", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the API key to update" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Updated human-readable label" }, "scopes": { "type": "array", "items": { "enum": [ "*", "email:read", "email:send", "phone:read", "phone:sms", "phone:voice", "phone:provision", "messages:read", "messages:send", "messages:search", "voice:read", "vault:read", "vault:use", "vault:write", "vault:share", "vault:oauth", "vault:inject", "identity:read", "identity:write", "agents:read", "agents:write", "inbox:read", "inbox:write", "domains:read", "domains:write", "addresses:read", "addresses:write", "webhooks:read", "webhooks:write", "billing:read", "audit:read", "extension:connect" ], "type": "string", "description": "A single permission scope, or the wildcard '*' for full access" }, "minItems": 1, "description": "Updated permission scopes" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Updated expiration timestamp, or null to remove expiration" } }, "required": [], "description": "Request body for updating an existing API key" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier for the API key" }, "orgId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Organization that owns this API key" }, "agentId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "Agent this key is restricted to, null if unrestricted" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable label for the API key" }, "prefix": { "type": "string", "description": "Non-secret prefix of the key for identification" }, "mode": { "enum": [ "LIVE", "TEST" ], "type": "string", "description": "Environment mode of the key" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Permission scopes granted to this key" }, "revoked": { "type": "boolean", "description": "Whether the key has been revoked" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the key was created" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp when the key was last used, null if never used" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp when the key expires, null if no expiration" }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User ID of the key creator, null if created by system" }, "extension": { "anyOf": [ { "type": "object", "properties": { "authPolicy": { "enum": [ "session", "pre_approved", "prompt_owner" ], "type": "string" }, "tokenTtl": { "enum": [ "15m", "1h", "session" ], "type": "string" } }, "required": [ "authPolicy", "tokenTtl" ] }, { "type": "null" } ], "description": "Extension-token settings surfaced from metadata. Present only for extension:bridge keys." } }, "required": [ "id", "orgId", "agentId", "name", "prefix", "mode", "scopes", "revoked", "createdAt", "lastUsedAt", "expiresAt", "createdBy" ], "description": "API key resource without the secret value" } } } } } }, "delete": { "operationId": "apiKeys.revoke", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the API key to revoke" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "Request body for revoking an API key" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true } }, "required": [ "success" ] } } } } } } }, "/api-keys/{id}/rotate": { "post": { "operationId": "apiKeys.rotate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the API key to rotate" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "Request body for rotating an API key, which revokes the old key and issues a new one" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier for the API key" }, "orgId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Organization that owns this API key" }, "agentId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "Agent this key is restricted to, null if unrestricted" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable label for the API key" }, "prefix": { "type": "string", "description": "Non-secret prefix of the key for identification" }, "mode": { "enum": [ "LIVE", "TEST" ], "type": "string", "description": "Environment mode of the key" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Permission scopes granted to this key" }, "revoked": { "type": "boolean", "description": "Whether the key has been revoked" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the key was created" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp when the key was last used, null if never used" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp when the key expires, null if no expiration" }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User ID of the key creator, null if created by system" }, "extension": { "anyOf": [ { "type": "object", "properties": { "authPolicy": { "enum": [ "session", "pre_approved", "prompt_owner" ], "type": "string" }, "tokenTtl": { "enum": [ "15m", "1h", "session" ], "type": "string" } }, "required": [ "authPolicy", "tokenTtl" ] }, { "type": "null" } ], "description": "Extension-token settings surfaced from metadata. Present only for extension:bridge keys." }, "key": { "type": "string", "description": "Full secret API key value, only returned once at creation time" } }, "required": [ "id", "orgId", "agentId", "name", "prefix", "mode", "scopes", "revoked", "createdAt", "lastUsedAt", "expiresAt", "createdBy", "key" ], "description": "API key resource including the secret value, returned only on creation" } } } } } } }, "/api-keys/scopes": { "get": { "operationId": "apiKeys.listScopes", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "wildcard": { "const": "*", "description": "The wildcard scope identifier ('*') that grants full access" }, "scopes": { "type": "array", "items": { "type": "object", "properties": { "scope": { "enum": [ "*", "email:read", "email:send", "phone:read", "phone:sms", "phone:voice", "phone:provision", "messages:read", "messages:send", "messages:search", "voice:read", "vault:read", "vault:use", "vault:write", "vault:share", "vault:oauth", "vault:inject", "identity:read", "identity:write", "agents:read", "agents:write", "inbox:read", "inbox:write", "domains:read", "domains:write", "addresses:read", "addresses:write", "webhooks:read", "webhooks:write", "billing:read", "audit:read", "extension:connect" ], "type": "string", "description": "The scope identifier (e.g. 'email:send')" }, "description": { "type": "string", "description": "Human-readable description of what this scope grants" }, "group": { "type": "string", "description": "UI grouping name (e.g. 'Email', 'Phone', 'Cards')" } }, "required": [ "scope", "description", "group" ], "description": "Metadata for a single scope in the catalogue" }, "description": "All scopes a customer can grant to an API key, ordered by group" } }, "required": [ "wildcard", "scopes" ], "description": "Full catalogue of scopes available for API keys" } } } } } } }, "/messages/email": { "post": { "operationId": "message.sendEmail", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the agent sending the email" }, "fromIdentityId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Optional EmailIdentity ID to send from. An agent has exactly one email identity, so the only valid value is that one — supply it to assert which address you expect to send as, or omit it and the agent's identity is used. Discover the ID via GET /agents/{agentId}/email-identities." }, "to": { "type": "array", "items": { "type": "string", "format": "email" }, "minItems": 1, "description": "List of recipient email addresses (at least one required)" }, "cc": { "default": [], "type": "array", "items": { "type": "string", "format": "email" }, "description": "List of CC recipient email addresses" }, "bcc": { "default": [], "type": "array", "items": { "type": "string", "format": "email" }, "description": "List of BCC recipient email addresses" }, "subject": { "type": "string", "minLength": 1, "maxLength": 998, "description": "Email subject line (max 998 characters per RFC 2822)" }, "body": { "type": "string", "minLength": 1, "description": "Plain-text body of the email" }, "bodyHtml": { "type": "string", "description": "Optional HTML body of the email" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Filename presented to the recipient. Inferred from the URL path when `url` is used and this is omitted; falls back to 'attachment' when neither is available." }, "contentId": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Content-ID for inline attachments referenced in the HTML body via `cid:` URIs (e.g. set to 'logo' to be referenced as ``). When present, the attachment uses `Content-Disposition: inline`; when absent, `attachment`." }, "contentType": { "type": "string", "description": "MIME type. Auto-detected from `filename` extension if omitted (e.g. 'application/pdf' for .pdf, 'image/png' for .png). Falls back to 'application/octet-stream' if undetectable." }, "content": { "type": "string", "description": "Base64-encoded attachment bytes. Provide either `content` or `url`. Single base64 string up to ~33MB on the wire (decodes to ~25MB binary)." }, "url": { "type": "string", "format": "uri", "description": "Public URL the server fetches and attaches. Provide either `content` or `url`. URLs to private/loopback/link-local IPs are rejected to prevent SSRF. Max 25MB after download." } }, "description": "File attachment for outbound email. Provide exactly one of `content` (base64-inline) or `url` (server-fetch). Optional `contentId` makes the attachment inline for HTML-embedded images." }, "maxItems": 20, "description": "Optional file attachments. Max 25MB total across all attachments (after base64 decode for inline, after fetch for URL-source); max 20 attachments per email. Each entry provides either inline base64 `content` or a public `url` for server-fetch." }, "headers": { "default": {}, "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom email headers as key-value pairs" }, "metadata": { "default": {}, "type": "object", "additionalProperties": {}, "description": "Arbitrary key-value metadata to attach to the message" }, "inReplyTo": { "type": "string", "description": "The message this email replies to: either an RFC 5322 Message-ID (with or without angle brackets, e.g. from an inbound email's externalId) or an Anima message id (cuid). The reply joins that message's thread and emits In-Reply-To/References so external clients thread it too." }, "references": { "default": [], "type": "array", "items": { "type": "string" }, "description": "Explicit References chain (RFC 5322 Message-IDs, oldest first) emitted on the wire. If omitted on a reply, the chain is derived from the replied-to message automatically." } }, "required": [ "agentId", "to", "subject", "body" ], "description": "Request body for sending an email with threading support" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the message" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the agent that sent or received the message" }, "inboxId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "ID of the inbox this message belongs to — the inbox it was delivered to (inbound) or sent from (outbound). Null when no inbox backs the address: SMS/MMS/voice messages, and email sent from an email identity that has no inbox (such as a custom-domain identity added to an agent). Pass it to GET /messages?inboxId= to list one inbox's mail." }, "channel": { "enum": [ "EMAIL", "SMS", "MMS", "VOICE" ], "type": "string", "description": "Communication channel used" }, "direction": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "description": "Whether the message was inbound or outbound" }, "status": { "enum": [ "QUEUED", "SENT", "DELIVERED", "FAILED", "BOUNCED", "BLOCKED", "PENDING_APPROVAL" ], "type": "string", "description": "Current delivery status" }, "fromAddress": { "type": "string", "description": "Sender address (email or phone number)" }, "toAddress": { "type": "string", "description": "Recipient address (email or phone number)" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message subject line, or null for channels that do not support subjects" }, "body": { "type": "string", "description": "Plain-text content of the message" }, "bodyHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML content of the message, or null if not available" }, "extractedText": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plain-text body with the quoted reply chain and signature stripped — just what this sender actually wrote. Read this instead of `body` to avoid re-reading (and paying for) the whole thread on every message. Null when nothing was extracted: non-email channels, messages your agent sent, and mail received before this field existed — so `extractedText ?? body` is always correct. Best-effort and heuristic; `body` remains the verbatim source of truth. Known weak cases: forwards and bottom-posted replies have no separable 'new' part, so this returns the full body rather than nothing." }, "extractedHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML body with quoted reply chains removed. Same semantics as `extractedText`; `bodyHtml` stays verbatim. Quoting styles that mark the chain with a sibling element rather than wrapping it (Outlook) are not stripped here — `extractedText` still is." }, "headers": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Raw message headers as key-value pairs, or null" }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Arbitrary metadata attached to the message, or null" }, "threadId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Thread identifier for conversation grouping, or null" }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Workflow labels on this message. Always contains exactly one of the system labels `unread` or `read`; may also contain `archived`, `spam` (the inbound spam verdict — see `includeSpam` on list/search), and any labels you add yourself. Stored lowercase, deduped, and sorted. Change them with PATCH /messages/{id}/labels." }, "inReplyTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message ID this message is replying to, or null" }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "External identifier, or null. For email: the RFC 5322 Message-ID (bare, no angle brackets) — pass it as inReplyTo to reply in-thread. For SMS: the provider-assigned message id." }, "deletedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this message was moved to Trash, or null if it is live. Deleted messages are hidden from listings unless `deleted` is set to `include` or `only`, and can be brought back with POST /messages/{id}/restore. Nothing purges them." }, "sentAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was sent, or null if not yet sent" }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was received, or null for outbound messages" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the attachment" }, "filename": { "type": "string", "description": "Original filename of the attachment" }, "mimeType": { "type": "string", "description": "MIME type of the attachment (e.g. application/pdf)" }, "sizeBytes": { "type": "integer", "minimum": 0, "description": "File size in bytes" }, "storageKey": { "type": "string", "description": "Internal storage key for retrieving the file" }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Pre-signed download URL, or null if not yet generated" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the attachment was created" }, "scanStatus": { "enum": [ "PENDING", "CLEAN", "FLAGGED", "BLOCKED" ], "type": "string", "description": "Content-scan verdict. BLOCKED attachments cannot be downloaded — inspect before fetching bytes." }, "detectedMimeType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "MIME type inferred from magic bytes; may differ from the declared mimeType" } }, "required": [ "id", "filename", "mimeType", "sizeBytes", "storageKey", "url", "createdAt", "scanStatus", "detectedMimeType" ], "description": "File attachment associated with a message" }, "description": "File attachments associated with this message" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was last updated" } }, "required": [ "id", "agentId", "inboxId", "channel", "direction", "status", "fromAddress", "toAddress", "subject", "body", "bodyHtml", "extractedText", "extractedHtml", "headers", "metadata", "threadId", "labels", "inReplyTo", "externalId", "deletedAt", "sentAt", "receivedAt", "attachments", "createdAt", "updatedAt" ], "description": "Full message resource representation" } } } } } } }, "/messages/sms": { "post": { "operationId": "message.sendSms", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the agent sending the SMS" }, "to": { "type": "string", "minLength": 7, "maxLength": 20, "description": "Recipient phone number in E.164 format" }, "body": { "type": "string", "minLength": 1, "maxLength": 1600, "description": "Text content of the SMS message (max 1600 characters)" }, "mediaUrls": { "default": [], "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 10, "description": "URLs of media attachments for MMS (max 10)" }, "metadata": { "default": {}, "type": "object", "additionalProperties": {}, "description": "Arbitrary key-value metadata to attach to the message" } }, "required": [ "agentId", "to", "body" ], "description": "Request body for sending an SMS or MMS through an agent" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the message" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the agent that sent or received the message" }, "inboxId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "ID of the inbox this message belongs to — the inbox it was delivered to (inbound) or sent from (outbound). Null when no inbox backs the address: SMS/MMS/voice messages, and email sent from an email identity that has no inbox (such as a custom-domain identity added to an agent). Pass it to GET /messages?inboxId= to list one inbox's mail." }, "channel": { "enum": [ "EMAIL", "SMS", "MMS", "VOICE" ], "type": "string", "description": "Communication channel used" }, "direction": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "description": "Whether the message was inbound or outbound" }, "status": { "enum": [ "QUEUED", "SENT", "DELIVERED", "FAILED", "BOUNCED", "BLOCKED", "PENDING_APPROVAL" ], "type": "string", "description": "Current delivery status" }, "fromAddress": { "type": "string", "description": "Sender address (email or phone number)" }, "toAddress": { "type": "string", "description": "Recipient address (email or phone number)" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message subject line, or null for channels that do not support subjects" }, "body": { "type": "string", "description": "Plain-text content of the message" }, "bodyHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML content of the message, or null if not available" }, "extractedText": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plain-text body with the quoted reply chain and signature stripped — just what this sender actually wrote. Read this instead of `body` to avoid re-reading (and paying for) the whole thread on every message. Null when nothing was extracted: non-email channels, messages your agent sent, and mail received before this field existed — so `extractedText ?? body` is always correct. Best-effort and heuristic; `body` remains the verbatim source of truth. Known weak cases: forwards and bottom-posted replies have no separable 'new' part, so this returns the full body rather than nothing." }, "extractedHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML body with quoted reply chains removed. Same semantics as `extractedText`; `bodyHtml` stays verbatim. Quoting styles that mark the chain with a sibling element rather than wrapping it (Outlook) are not stripped here — `extractedText` still is." }, "headers": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Raw message headers as key-value pairs, or null" }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Arbitrary metadata attached to the message, or null" }, "threadId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Thread identifier for conversation grouping, or null" }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Workflow labels on this message. Always contains exactly one of the system labels `unread` or `read`; may also contain `archived`, `spam` (the inbound spam verdict — see `includeSpam` on list/search), and any labels you add yourself. Stored lowercase, deduped, and sorted. Change them with PATCH /messages/{id}/labels." }, "inReplyTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message ID this message is replying to, or null" }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "External identifier, or null. For email: the RFC 5322 Message-ID (bare, no angle brackets) — pass it as inReplyTo to reply in-thread. For SMS: the provider-assigned message id." }, "deletedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this message was moved to Trash, or null if it is live. Deleted messages are hidden from listings unless `deleted` is set to `include` or `only`, and can be brought back with POST /messages/{id}/restore. Nothing purges them." }, "sentAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was sent, or null if not yet sent" }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was received, or null for outbound messages" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the attachment" }, "filename": { "type": "string", "description": "Original filename of the attachment" }, "mimeType": { "type": "string", "description": "MIME type of the attachment (e.g. application/pdf)" }, "sizeBytes": { "type": "integer", "minimum": 0, "description": "File size in bytes" }, "storageKey": { "type": "string", "description": "Internal storage key for retrieving the file" }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Pre-signed download URL, or null if not yet generated" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the attachment was created" }, "scanStatus": { "enum": [ "PENDING", "CLEAN", "FLAGGED", "BLOCKED" ], "type": "string", "description": "Content-scan verdict. BLOCKED attachments cannot be downloaded — inspect before fetching bytes." }, "detectedMimeType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "MIME type inferred from magic bytes; may differ from the declared mimeType" } }, "required": [ "id", "filename", "mimeType", "sizeBytes", "storageKey", "url", "createdAt", "scanStatus", "detectedMimeType" ], "description": "File attachment associated with a message" }, "description": "File attachments associated with this message" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was last updated" } }, "required": [ "id", "agentId", "inboxId", "channel", "direction", "status", "fromAddress", "toAddress", "subject", "body", "bodyHtml", "extractedText", "extractedHtml", "headers", "metadata", "threadId", "labels", "inReplyTo", "externalId", "deletedAt", "sentAt", "receivedAt", "attachments", "createdAt", "updatedAt" ], "description": "Full message resource representation" } } } } } } }, "/messages/{id}": { "get": { "operationId": "message.get", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique message identifier" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the message" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the agent that sent or received the message" }, "inboxId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "ID of the inbox this message belongs to — the inbox it was delivered to (inbound) or sent from (outbound). Null when no inbox backs the address: SMS/MMS/voice messages, and email sent from an email identity that has no inbox (such as a custom-domain identity added to an agent). Pass it to GET /messages?inboxId= to list one inbox's mail." }, "channel": { "enum": [ "EMAIL", "SMS", "MMS", "VOICE" ], "type": "string", "description": "Communication channel used" }, "direction": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "description": "Whether the message was inbound or outbound" }, "status": { "enum": [ "QUEUED", "SENT", "DELIVERED", "FAILED", "BOUNCED", "BLOCKED", "PENDING_APPROVAL" ], "type": "string", "description": "Current delivery status" }, "fromAddress": { "type": "string", "description": "Sender address (email or phone number)" }, "toAddress": { "type": "string", "description": "Recipient address (email or phone number)" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message subject line, or null for channels that do not support subjects" }, "body": { "type": "string", "description": "Plain-text content of the message" }, "bodyHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML content of the message, or null if not available" }, "extractedText": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plain-text body with the quoted reply chain and signature stripped — just what this sender actually wrote. Read this instead of `body` to avoid re-reading (and paying for) the whole thread on every message. Null when nothing was extracted: non-email channels, messages your agent sent, and mail received before this field existed — so `extractedText ?? body` is always correct. Best-effort and heuristic; `body` remains the verbatim source of truth. Known weak cases: forwards and bottom-posted replies have no separable 'new' part, so this returns the full body rather than nothing." }, "extractedHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML body with quoted reply chains removed. Same semantics as `extractedText`; `bodyHtml` stays verbatim. Quoting styles that mark the chain with a sibling element rather than wrapping it (Outlook) are not stripped here — `extractedText` still is." }, "headers": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Raw message headers as key-value pairs, or null" }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Arbitrary metadata attached to the message, or null" }, "threadId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Thread identifier for conversation grouping, or null" }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Workflow labels on this message. Always contains exactly one of the system labels `unread` or `read`; may also contain `archived`, `spam` (the inbound spam verdict — see `includeSpam` on list/search), and any labels you add yourself. Stored lowercase, deduped, and sorted. Change them with PATCH /messages/{id}/labels." }, "inReplyTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message ID this message is replying to, or null" }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "External identifier, or null. For email: the RFC 5322 Message-ID (bare, no angle brackets) — pass it as inReplyTo to reply in-thread. For SMS: the provider-assigned message id." }, "deletedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this message was moved to Trash, or null if it is live. Deleted messages are hidden from listings unless `deleted` is set to `include` or `only`, and can be brought back with POST /messages/{id}/restore. Nothing purges them." }, "sentAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was sent, or null if not yet sent" }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was received, or null for outbound messages" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the attachment" }, "filename": { "type": "string", "description": "Original filename of the attachment" }, "mimeType": { "type": "string", "description": "MIME type of the attachment (e.g. application/pdf)" }, "sizeBytes": { "type": "integer", "minimum": 0, "description": "File size in bytes" }, "storageKey": { "type": "string", "description": "Internal storage key for retrieving the file" }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Pre-signed download URL, or null if not yet generated" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the attachment was created" }, "scanStatus": { "enum": [ "PENDING", "CLEAN", "FLAGGED", "BLOCKED" ], "type": "string", "description": "Content-scan verdict. BLOCKED attachments cannot be downloaded — inspect before fetching bytes." }, "detectedMimeType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "MIME type inferred from magic bytes; may differ from the declared mimeType" } }, "required": [ "id", "filename", "mimeType", "sizeBytes", "storageKey", "url", "createdAt", "scanStatus", "detectedMimeType" ], "description": "File attachment associated with a message" }, "description": "File attachments associated with this message" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was last updated" } }, "required": [ "id", "agentId", "inboxId", "channel", "direction", "status", "fromAddress", "toAddress", "subject", "body", "bodyHtml", "extractedText", "extractedHtml", "headers", "metadata", "threadId", "labels", "inReplyTo", "externalId", "deletedAt", "sentAt", "receivedAt", "attachments", "createdAt", "updatedAt" ], "description": "Full message resource representation" } } } } } }, "delete": { "operationId": "message.delete", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the message to move to Trash" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "Message deletion parameters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the message" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the agent that sent or received the message" }, "inboxId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "ID of the inbox this message belongs to — the inbox it was delivered to (inbound) or sent from (outbound). Null when no inbox backs the address: SMS/MMS/voice messages, and email sent from an email identity that has no inbox (such as a custom-domain identity added to an agent). Pass it to GET /messages?inboxId= to list one inbox's mail." }, "channel": { "enum": [ "EMAIL", "SMS", "MMS", "VOICE" ], "type": "string", "description": "Communication channel used" }, "direction": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "description": "Whether the message was inbound or outbound" }, "status": { "enum": [ "QUEUED", "SENT", "DELIVERED", "FAILED", "BOUNCED", "BLOCKED", "PENDING_APPROVAL" ], "type": "string", "description": "Current delivery status" }, "fromAddress": { "type": "string", "description": "Sender address (email or phone number)" }, "toAddress": { "type": "string", "description": "Recipient address (email or phone number)" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message subject line, or null for channels that do not support subjects" }, "body": { "type": "string", "description": "Plain-text content of the message" }, "bodyHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML content of the message, or null if not available" }, "extractedText": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plain-text body with the quoted reply chain and signature stripped — just what this sender actually wrote. Read this instead of `body` to avoid re-reading (and paying for) the whole thread on every message. Null when nothing was extracted: non-email channels, messages your agent sent, and mail received before this field existed — so `extractedText ?? body` is always correct. Best-effort and heuristic; `body` remains the verbatim source of truth. Known weak cases: forwards and bottom-posted replies have no separable 'new' part, so this returns the full body rather than nothing." }, "extractedHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML body with quoted reply chains removed. Same semantics as `extractedText`; `bodyHtml` stays verbatim. Quoting styles that mark the chain with a sibling element rather than wrapping it (Outlook) are not stripped here — `extractedText` still is." }, "headers": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Raw message headers as key-value pairs, or null" }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Arbitrary metadata attached to the message, or null" }, "threadId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Thread identifier for conversation grouping, or null" }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Workflow labels on this message. Always contains exactly one of the system labels `unread` or `read`; may also contain `archived`, `spam` (the inbound spam verdict — see `includeSpam` on list/search), and any labels you add yourself. Stored lowercase, deduped, and sorted. Change them with PATCH /messages/{id}/labels." }, "inReplyTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message ID this message is replying to, or null" }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "External identifier, or null. For email: the RFC 5322 Message-ID (bare, no angle brackets) — pass it as inReplyTo to reply in-thread. For SMS: the provider-assigned message id." }, "deletedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this message was moved to Trash, or null if it is live. Deleted messages are hidden from listings unless `deleted` is set to `include` or `only`, and can be brought back with POST /messages/{id}/restore. Nothing purges them." }, "sentAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was sent, or null if not yet sent" }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was received, or null for outbound messages" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the attachment" }, "filename": { "type": "string", "description": "Original filename of the attachment" }, "mimeType": { "type": "string", "description": "MIME type of the attachment (e.g. application/pdf)" }, "sizeBytes": { "type": "integer", "minimum": 0, "description": "File size in bytes" }, "storageKey": { "type": "string", "description": "Internal storage key for retrieving the file" }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Pre-signed download URL, or null if not yet generated" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the attachment was created" }, "scanStatus": { "enum": [ "PENDING", "CLEAN", "FLAGGED", "BLOCKED" ], "type": "string", "description": "Content-scan verdict. BLOCKED attachments cannot be downloaded — inspect before fetching bytes." }, "detectedMimeType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "MIME type inferred from magic bytes; may differ from the declared mimeType" } }, "required": [ "id", "filename", "mimeType", "sizeBytes", "storageKey", "url", "createdAt", "scanStatus", "detectedMimeType" ], "description": "File attachment associated with a message" }, "description": "File attachments associated with this message" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was last updated" } }, "required": [ "id", "agentId", "inboxId", "channel", "direction", "status", "fromAddress", "toAddress", "subject", "body", "bodyHtml", "extractedText", "extractedHtml", "headers", "metadata", "threadId", "labels", "inReplyTo", "externalId", "deletedAt", "sentAt", "receivedAt", "attachments", "createdAt", "updatedAt" ], "description": "Full message resource representation" } } } } } } }, "/messages": { "get": { "operationId": "message.list", "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Opaque cursor from a previous response to fetch the next page" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of items to return per page (1–100, default 20)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "agentId", "in": "query", "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Filter messages by agent ID" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "threadId", "in": "query", "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Filter messages by conversation thread ID" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "channel", "in": "query", "schema": { "enum": [ "EMAIL", "SMS", "MMS", "VOICE" ], "type": "string", "description": "Filter messages by communication channel" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "channels", "in": "query", "schema": { "type": "array", "items": { "enum": [ "EMAIL", "SMS", "MMS", "VOICE" ], "type": "string", "description": "Communication channel used for the message" }, "maxItems": 50, "description": "Filter messages by several channels at once, e.g. SMS+MMS to see a full text conversation. Takes precedence over `channel`. A single value (`?channels=SMS`) is accepted as well as the repeated (`?channels=SMS&channels=MMS`) and bracketed (`?channels[]=SMS`) forms." }, "style": "deepObject", "explode": true, "allowEmptyValue": true, "allowReserved": true }, { "name": "direction", "in": "query", "schema": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "description": "Filter messages by direction (inbound or outbound)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "status", "in": "query", "schema": { "enum": [ "QUEUED", "SENT", "DELIVERED", "FAILED", "BOUNCED", "BLOCKED", "PENDING_APPROVAL" ], "type": "string", "description": "Filter messages by delivery status" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "dateRange", "in": "query", "schema": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "description": "Inclusive start of the date range in ISO 8601 format" }, "to": { "type": "string", "format": "date-time", "description": "Inclusive end of the date range in ISO 8601 format" } }, "description": "Filter messages within a date range" }, "style": "deepObject", "explode": true, "allowEmptyValue": true, "allowReserved": true }, { "name": "inboxId", "in": "query", "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Filter to one inbox — messages delivered to it (inbound) or sent from it (outbound). The precise way to read a single mailbox when an agent owns several." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "fromAddress", "in": "query", "schema": { "type": "string", "description": "Filter by sender address, matched exactly (case-sensitive). On inbound mail this is the counterparty; on outbound it is the agent identity the mail was sent from." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "toAddress", "in": "query", "schema": { "type": "string", "description": "Filter by recipient address, matched exactly (case-sensitive). Note that outbound messages store every recipient in one comma-joined value, so an exact filter matches a multi-recipient send only when given that same joined string — prefer `inboxId` to scope outbound mail to a mailbox." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "labels", "in": "query", "schema": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 50, "description": "Filter to messages carrying ALL of these labels (e.g. `urgent` + `unread` means urgent AND still unread). Case-insensitive. System labels: `unread`, `read`, `archived`, `spam`." }, "style": "deepObject", "explode": true, "allowEmptyValue": true, "allowReserved": true }, { "name": "includeSpam", "in": "query", "schema": { "default": false, "type": "boolean", "description": "Include messages classified as spam on arrival. They are excluded by default. Naming `spam` in `labels` also counts as asking for it, so a deliberate spam query is never silently emptied by this default." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "includeArchived", "in": "query", "schema": { "default": false, "type": "boolean", "description": "Include messages carrying the `archived` label. They are excluded by default, so archiving actually removes mail from a listing rather than only tagging it. Naming `archived` in `labels` also counts as asking for it (and returns ONLY archived mail); use this flag instead to see archived mail mixed in with the rest." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "deleted", "in": "query", "schema": { "default": "exclude", "enum": [ "exclude", "include", "only" ], "type": "string", "description": "How to treat messages moved to Trash. `exclude` (default) hides them, so deleted mail disappears from every ordinary listing. `only` returns nothing but Trash. `include` ignores the distinction. Deletion is reversible — see DELETE /messages/{id} and POST /messages/{id}/restore." }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the message" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the agent that sent or received the message" }, "inboxId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "ID of the inbox this message belongs to — the inbox it was delivered to (inbound) or sent from (outbound). Null when no inbox backs the address: SMS/MMS/voice messages, and email sent from an email identity that has no inbox (such as a custom-domain identity added to an agent). Pass it to GET /messages?inboxId= to list one inbox's mail." }, "channel": { "enum": [ "EMAIL", "SMS", "MMS", "VOICE" ], "type": "string", "description": "Communication channel used" }, "direction": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "description": "Whether the message was inbound or outbound" }, "status": { "enum": [ "QUEUED", "SENT", "DELIVERED", "FAILED", "BOUNCED", "BLOCKED", "PENDING_APPROVAL" ], "type": "string", "description": "Current delivery status" }, "fromAddress": { "type": "string", "description": "Sender address (email or phone number)" }, "toAddress": { "type": "string", "description": "Recipient address (email or phone number)" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message subject line, or null for channels that do not support subjects" }, "body": { "type": "string", "description": "Plain-text content of the message" }, "bodyHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML content of the message, or null if not available" }, "extractedText": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plain-text body with the quoted reply chain and signature stripped — just what this sender actually wrote. Read this instead of `body` to avoid re-reading (and paying for) the whole thread on every message. Null when nothing was extracted: non-email channels, messages your agent sent, and mail received before this field existed — so `extractedText ?? body` is always correct. Best-effort and heuristic; `body` remains the verbatim source of truth. Known weak cases: forwards and bottom-posted replies have no separable 'new' part, so this returns the full body rather than nothing." }, "extractedHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML body with quoted reply chains removed. Same semantics as `extractedText`; `bodyHtml` stays verbatim. Quoting styles that mark the chain with a sibling element rather than wrapping it (Outlook) are not stripped here — `extractedText` still is." }, "headers": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Raw message headers as key-value pairs, or null" }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Arbitrary metadata attached to the message, or null" }, "threadId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Thread identifier for conversation grouping, or null" }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Workflow labels on this message. Always contains exactly one of the system labels `unread` or `read`; may also contain `archived`, `spam` (the inbound spam verdict — see `includeSpam` on list/search), and any labels you add yourself. Stored lowercase, deduped, and sorted. Change them with PATCH /messages/{id}/labels." }, "inReplyTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message ID this message is replying to, or null" }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "External identifier, or null. For email: the RFC 5322 Message-ID (bare, no angle brackets) — pass it as inReplyTo to reply in-thread. For SMS: the provider-assigned message id." }, "deletedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this message was moved to Trash, or null if it is live. Deleted messages are hidden from listings unless `deleted` is set to `include` or `only`, and can be brought back with POST /messages/{id}/restore. Nothing purges them." }, "sentAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was sent, or null if not yet sent" }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was received, or null for outbound messages" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the attachment" }, "filename": { "type": "string", "description": "Original filename of the attachment" }, "mimeType": { "type": "string", "description": "MIME type of the attachment (e.g. application/pdf)" }, "sizeBytes": { "type": "integer", "minimum": 0, "description": "File size in bytes" }, "storageKey": { "type": "string", "description": "Internal storage key for retrieving the file" }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Pre-signed download URL, or null if not yet generated" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the attachment was created" }, "scanStatus": { "enum": [ "PENDING", "CLEAN", "FLAGGED", "BLOCKED" ], "type": "string", "description": "Content-scan verdict. BLOCKED attachments cannot be downloaded — inspect before fetching bytes." }, "detectedMimeType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "MIME type inferred from magic bytes; may differ from the declared mimeType" } }, "required": [ "id", "filename", "mimeType", "sizeBytes", "storageKey", "url", "createdAt", "scanStatus", "detectedMimeType" ], "description": "File attachment associated with a message" }, "description": "File attachments associated with this message" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was last updated" } }, "required": [ "id", "agentId", "inboxId", "channel", "direction", "status", "fromAddress", "toAddress", "subject", "body", "bodyHtml", "extractedText", "extractedHtml", "headers", "metadata", "threadId", "labels", "inReplyTo", "externalId", "deletedAt", "sentAt", "receivedAt", "attachments", "createdAt", "updatedAt" ], "description": "Full message resource representation" }, "description": "Array of message resources matching the query" }, "pagination": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "Cursor to pass as the `cursor` parameter to retrieve the next page, or null if no more results" }, "hasMore": { "type": "boolean", "description": "Whether additional pages of results are available" } }, "required": [ "nextCursor", "hasMore" ], "description": "Pagination metadata for retrieving additional pages" } }, "required": [ "items", "pagination" ], "description": "Paginated list of messages" } } } } } } }, "/messages/search": { "post": { "operationId": "message.search", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "description": "Full-text search query matched against subject, body, and addresses. Supports web-search syntax: bare words are AND-ed (`invoice overdue`), `\"quoted phrases\"` match in order, `-word` excludes, and `or` alternates (`invoice or receipt`). Words are stemmed, so `approving` matches `approval`. Results are ranked by relevance, with subject matches weighted above body matches above address matches. For meaning-based rather than keyword matching, use POST /messages/search/semantic instead." }, "filters": { "default": {}, "type": "object", "properties": { "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Filter results by agent ID" }, "channel": { "enum": [ "EMAIL", "SMS", "MMS", "VOICE" ], "type": "string", "description": "Filter results by communication channel" }, "direction": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "description": "Filter results by message direction" }, "status": { "enum": [ "QUEUED", "SENT", "DELIVERED", "FAILED", "BOUNCED", "BLOCKED", "PENDING_APPROVAL" ], "type": "string", "description": "Filter results by delivery status" }, "dateRange": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "description": "Inclusive start of the date range in ISO 8601 format" }, "to": { "type": "string", "format": "date-time", "description": "Inclusive end of the date range in ISO 8601 format" } }, "description": "Filter results within a date range" }, "inboxId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Filter to one inbox — messages delivered to it (inbound) or sent from it (outbound). The precise way to read a single mailbox when an agent owns several." }, "fromAddress": { "type": "string", "description": "Filter by sender address, matched exactly (case-sensitive). On inbound mail this is the counterparty; on outbound it is the agent identity the mail was sent from." }, "toAddress": { "type": "string", "description": "Filter by recipient address, matched exactly (case-sensitive). Note that outbound messages store every recipient in one comma-joined value, so an exact filter matches a multi-recipient send only when given that same joined string — prefer `inboxId` to scope outbound mail to a mailbox." }, "labels": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 50, "description": "Filter to messages carrying ALL of these labels (e.g. `urgent` + `unread` means urgent AND still unread). Case-insensitive. System labels: `unread`, `read`, `archived`, `spam`." }, "includeSpam": { "default": false, "type": "boolean", "description": "Include messages classified as spam on arrival. They are excluded by default. Naming `spam` in `labels` also counts as asking for it, so a deliberate spam query is never silently emptied by this default." }, "includeArchived": { "default": false, "type": "boolean", "description": "Include messages carrying the `archived` label. They are excluded by default, so archiving actually removes mail from a listing rather than only tagging it. Naming `archived` in `labels` also counts as asking for it (and returns ONLY archived mail); use this flag instead to see archived mail mixed in with the rest." }, "deleted": { "default": "exclude", "enum": [ "exclude", "include", "only" ], "type": "string", "description": "How to treat messages moved to Trash. `exclude` (default) hides them, so deleted mail disappears from every ordinary listing. `only` returns nothing but Trash. `include` ignores the distinction. Deletion is reversible — see DELETE /messages/{id} and POST /messages/{id}/restore." } }, "description": "Optional filters to narrow search results" }, "pagination": { "default": { "limit": 20 }, "type": "object", "properties": { "cursor": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Opaque cursor from a previous response to fetch the next page" }, "limit": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of items to return per page (1–100, default 20)" } }, "description": "Pagination parameters for the search results" } }, "required": [ "query" ], "description": "Request body for searching messages with full-text query and optional filters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the message" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the agent that sent or received the message" }, "inboxId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "ID of the inbox this message belongs to — the inbox it was delivered to (inbound) or sent from (outbound). Null when no inbox backs the address: SMS/MMS/voice messages, and email sent from an email identity that has no inbox (such as a custom-domain identity added to an agent). Pass it to GET /messages?inboxId= to list one inbox's mail." }, "channel": { "enum": [ "EMAIL", "SMS", "MMS", "VOICE" ], "type": "string", "description": "Communication channel used" }, "direction": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "description": "Whether the message was inbound or outbound" }, "status": { "enum": [ "QUEUED", "SENT", "DELIVERED", "FAILED", "BOUNCED", "BLOCKED", "PENDING_APPROVAL" ], "type": "string", "description": "Current delivery status" }, "fromAddress": { "type": "string", "description": "Sender address (email or phone number)" }, "toAddress": { "type": "string", "description": "Recipient address (email or phone number)" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message subject line, or null for channels that do not support subjects" }, "body": { "type": "string", "description": "Plain-text content of the message" }, "bodyHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML content of the message, or null if not available" }, "extractedText": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plain-text body with the quoted reply chain and signature stripped — just what this sender actually wrote. Read this instead of `body` to avoid re-reading (and paying for) the whole thread on every message. Null when nothing was extracted: non-email channels, messages your agent sent, and mail received before this field existed — so `extractedText ?? body` is always correct. Best-effort and heuristic; `body` remains the verbatim source of truth. Known weak cases: forwards and bottom-posted replies have no separable 'new' part, so this returns the full body rather than nothing." }, "extractedHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML body with quoted reply chains removed. Same semantics as `extractedText`; `bodyHtml` stays verbatim. Quoting styles that mark the chain with a sibling element rather than wrapping it (Outlook) are not stripped here — `extractedText` still is." }, "headers": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Raw message headers as key-value pairs, or null" }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Arbitrary metadata attached to the message, or null" }, "threadId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Thread identifier for conversation grouping, or null" }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Workflow labels on this message. Always contains exactly one of the system labels `unread` or `read`; may also contain `archived`, `spam` (the inbound spam verdict — see `includeSpam` on list/search), and any labels you add yourself. Stored lowercase, deduped, and sorted. Change them with PATCH /messages/{id}/labels." }, "inReplyTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message ID this message is replying to, or null" }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "External identifier, or null. For email: the RFC 5322 Message-ID (bare, no angle brackets) — pass it as inReplyTo to reply in-thread. For SMS: the provider-assigned message id." }, "deletedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this message was moved to Trash, or null if it is live. Deleted messages are hidden from listings unless `deleted` is set to `include` or `only`, and can be brought back with POST /messages/{id}/restore. Nothing purges them." }, "sentAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was sent, or null if not yet sent" }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was received, or null for outbound messages" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the attachment" }, "filename": { "type": "string", "description": "Original filename of the attachment" }, "mimeType": { "type": "string", "description": "MIME type of the attachment (e.g. application/pdf)" }, "sizeBytes": { "type": "integer", "minimum": 0, "description": "File size in bytes" }, "storageKey": { "type": "string", "description": "Internal storage key for retrieving the file" }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Pre-signed download URL, or null if not yet generated" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the attachment was created" }, "scanStatus": { "enum": [ "PENDING", "CLEAN", "FLAGGED", "BLOCKED" ], "type": "string", "description": "Content-scan verdict. BLOCKED attachments cannot be downloaded — inspect before fetching bytes." }, "detectedMimeType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "MIME type inferred from magic bytes; may differ from the declared mimeType" } }, "required": [ "id", "filename", "mimeType", "sizeBytes", "storageKey", "url", "createdAt", "scanStatus", "detectedMimeType" ], "description": "File attachment associated with a message" }, "description": "File attachments associated with this message" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was last updated" }, "snippet": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Excerpt of the body around the matched terms, with each match wrapped in `…`. Lets an agent judge relevance without fetching the full body. Null when the query matched only the subject or an address, so there is nothing in the body to excerpt. Not sanitized: it is a fragment of the raw body, which may itself contain markup." }, "rank": { "type": "number", "description": "Relevance score for this query. Ordering-only — comparable between hits of the SAME search, meaningless across different searches, and not a percentage. Results are already sorted by it, descending." } }, "required": [ "id", "agentId", "inboxId", "channel", "direction", "status", "fromAddress", "toAddress", "subject", "body", "bodyHtml", "extractedText", "extractedHtml", "headers", "metadata", "threadId", "labels", "inReplyTo", "externalId", "deletedAt", "sentAt", "receivedAt", "attachments", "createdAt", "updatedAt", "snippet", "rank" ], "description": "A message matching a full-text search, with its relevance score and excerpt" }, "description": "Matching messages, most relevant first (not most recent first)" }, "pagination": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "Cursor to pass as the `cursor` parameter to retrieve the next page, or null if no more results" }, "hasMore": { "type": "boolean", "description": "Whether additional pages of results are available" } }, "required": [ "nextCursor", "hasMore" ], "description": "Pagination metadata for retrieving additional pages" } }, "required": [ "items", "pagination" ], "description": "Ranked, paginated full-text search results" } } } } } } }, "/messages/{id}/labels": { "patch": { "operationId": "message.updateLabels", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the message to relabel" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "addLabels": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 50, "description": "Labels to add. Adding `read` removes `unread` and vice versa — they are one state under two names, and a message always carries exactly one of them." }, "removeLabels": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 50, "description": "Labels to remove. Removing `unread` marks the message read (and removing `read` marks it unread); a message is never left with neither." } }, "required": [], "description": "Add and/or remove labels on one message. Supply at least one of addLabels/removeLabels. Adding and removing the same label in one call is rejected rather than silently resolved." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the message" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the agent that sent or received the message" }, "inboxId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "ID of the inbox this message belongs to — the inbox it was delivered to (inbound) or sent from (outbound). Null when no inbox backs the address: SMS/MMS/voice messages, and email sent from an email identity that has no inbox (such as a custom-domain identity added to an agent). Pass it to GET /messages?inboxId= to list one inbox's mail." }, "channel": { "enum": [ "EMAIL", "SMS", "MMS", "VOICE" ], "type": "string", "description": "Communication channel used" }, "direction": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "description": "Whether the message was inbound or outbound" }, "status": { "enum": [ "QUEUED", "SENT", "DELIVERED", "FAILED", "BOUNCED", "BLOCKED", "PENDING_APPROVAL" ], "type": "string", "description": "Current delivery status" }, "fromAddress": { "type": "string", "description": "Sender address (email or phone number)" }, "toAddress": { "type": "string", "description": "Recipient address (email or phone number)" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message subject line, or null for channels that do not support subjects" }, "body": { "type": "string", "description": "Plain-text content of the message" }, "bodyHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML content of the message, or null if not available" }, "extractedText": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plain-text body with the quoted reply chain and signature stripped — just what this sender actually wrote. Read this instead of `body` to avoid re-reading (and paying for) the whole thread on every message. Null when nothing was extracted: non-email channels, messages your agent sent, and mail received before this field existed — so `extractedText ?? body` is always correct. Best-effort and heuristic; `body` remains the verbatim source of truth. Known weak cases: forwards and bottom-posted replies have no separable 'new' part, so this returns the full body rather than nothing." }, "extractedHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML body with quoted reply chains removed. Same semantics as `extractedText`; `bodyHtml` stays verbatim. Quoting styles that mark the chain with a sibling element rather than wrapping it (Outlook) are not stripped here — `extractedText` still is." }, "headers": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Raw message headers as key-value pairs, or null" }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Arbitrary metadata attached to the message, or null" }, "threadId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Thread identifier for conversation grouping, or null" }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Workflow labels on this message. Always contains exactly one of the system labels `unread` or `read`; may also contain `archived`, `spam` (the inbound spam verdict — see `includeSpam` on list/search), and any labels you add yourself. Stored lowercase, deduped, and sorted. Change them with PATCH /messages/{id}/labels." }, "inReplyTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message ID this message is replying to, or null" }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "External identifier, or null. For email: the RFC 5322 Message-ID (bare, no angle brackets) — pass it as inReplyTo to reply in-thread. For SMS: the provider-assigned message id." }, "deletedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this message was moved to Trash, or null if it is live. Deleted messages are hidden from listings unless `deleted` is set to `include` or `only`, and can be brought back with POST /messages/{id}/restore. Nothing purges them." }, "sentAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was sent, or null if not yet sent" }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was received, or null for outbound messages" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the attachment" }, "filename": { "type": "string", "description": "Original filename of the attachment" }, "mimeType": { "type": "string", "description": "MIME type of the attachment (e.g. application/pdf)" }, "sizeBytes": { "type": "integer", "minimum": 0, "description": "File size in bytes" }, "storageKey": { "type": "string", "description": "Internal storage key for retrieving the file" }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Pre-signed download URL, or null if not yet generated" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the attachment was created" }, "scanStatus": { "enum": [ "PENDING", "CLEAN", "FLAGGED", "BLOCKED" ], "type": "string", "description": "Content-scan verdict. BLOCKED attachments cannot be downloaded — inspect before fetching bytes." }, "detectedMimeType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "MIME type inferred from magic bytes; may differ from the declared mimeType" } }, "required": [ "id", "filename", "mimeType", "sizeBytes", "storageKey", "url", "createdAt", "scanStatus", "detectedMimeType" ], "description": "File attachment associated with a message" }, "description": "File attachments associated with this message" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was last updated" } }, "required": [ "id", "agentId", "inboxId", "channel", "direction", "status", "fromAddress", "toAddress", "subject", "body", "bodyHtml", "extractedText", "extractedHtml", "headers", "metadata", "threadId", "labels", "inReplyTo", "externalId", "deletedAt", "sentAt", "receivedAt", "attachments", "createdAt", "updatedAt" ], "description": "Full message resource representation" } } } } } } }, "/messages/{id}/restore": { "post": { "operationId": "message.restore", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the message to restore from Trash" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "Message restore parameters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the message" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the agent that sent or received the message" }, "inboxId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "ID of the inbox this message belongs to — the inbox it was delivered to (inbound) or sent from (outbound). Null when no inbox backs the address: SMS/MMS/voice messages, and email sent from an email identity that has no inbox (such as a custom-domain identity added to an agent). Pass it to GET /messages?inboxId= to list one inbox's mail." }, "channel": { "enum": [ "EMAIL", "SMS", "MMS", "VOICE" ], "type": "string", "description": "Communication channel used" }, "direction": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "description": "Whether the message was inbound or outbound" }, "status": { "enum": [ "QUEUED", "SENT", "DELIVERED", "FAILED", "BOUNCED", "BLOCKED", "PENDING_APPROVAL" ], "type": "string", "description": "Current delivery status" }, "fromAddress": { "type": "string", "description": "Sender address (email or phone number)" }, "toAddress": { "type": "string", "description": "Recipient address (email or phone number)" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message subject line, or null for channels that do not support subjects" }, "body": { "type": "string", "description": "Plain-text content of the message" }, "bodyHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML content of the message, or null if not available" }, "extractedText": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plain-text body with the quoted reply chain and signature stripped — just what this sender actually wrote. Read this instead of `body` to avoid re-reading (and paying for) the whole thread on every message. Null when nothing was extracted: non-email channels, messages your agent sent, and mail received before this field existed — so `extractedText ?? body` is always correct. Best-effort and heuristic; `body` remains the verbatim source of truth. Known weak cases: forwards and bottom-posted replies have no separable 'new' part, so this returns the full body rather than nothing." }, "extractedHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML body with quoted reply chains removed. Same semantics as `extractedText`; `bodyHtml` stays verbatim. Quoting styles that mark the chain with a sibling element rather than wrapping it (Outlook) are not stripped here — `extractedText` still is." }, "headers": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Raw message headers as key-value pairs, or null" }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Arbitrary metadata attached to the message, or null" }, "threadId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Thread identifier for conversation grouping, or null" }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Workflow labels on this message. Always contains exactly one of the system labels `unread` or `read`; may also contain `archived`, `spam` (the inbound spam verdict — see `includeSpam` on list/search), and any labels you add yourself. Stored lowercase, deduped, and sorted. Change them with PATCH /messages/{id}/labels." }, "inReplyTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message ID this message is replying to, or null" }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "External identifier, or null. For email: the RFC 5322 Message-ID (bare, no angle brackets) — pass it as inReplyTo to reply in-thread. For SMS: the provider-assigned message id." }, "deletedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this message was moved to Trash, or null if it is live. Deleted messages are hidden from listings unless `deleted` is set to `include` or `only`, and can be brought back with POST /messages/{id}/restore. Nothing purges them." }, "sentAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was sent, or null if not yet sent" }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was received, or null for outbound messages" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the attachment" }, "filename": { "type": "string", "description": "Original filename of the attachment" }, "mimeType": { "type": "string", "description": "MIME type of the attachment (e.g. application/pdf)" }, "sizeBytes": { "type": "integer", "minimum": 0, "description": "File size in bytes" }, "storageKey": { "type": "string", "description": "Internal storage key for retrieving the file" }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Pre-signed download URL, or null if not yet generated" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the attachment was created" }, "scanStatus": { "enum": [ "PENDING", "CLEAN", "FLAGGED", "BLOCKED" ], "type": "string", "description": "Content-scan verdict. BLOCKED attachments cannot be downloaded — inspect before fetching bytes." }, "detectedMimeType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "MIME type inferred from magic bytes; may differ from the declared mimeType" } }, "required": [ "id", "filename", "mimeType", "sizeBytes", "storageKey", "url", "createdAt", "scanStatus", "detectedMimeType" ], "description": "File attachment associated with a message" }, "description": "File attachments associated with this message" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was last updated" } }, "required": [ "id", "agentId", "inboxId", "channel", "direction", "status", "fromAddress", "toAddress", "subject", "body", "bodyHtml", "extractedText", "extractedHtml", "headers", "metadata", "threadId", "labels", "inReplyTo", "externalId", "deletedAt", "sentAt", "receivedAt", "attachments", "createdAt", "updatedAt" ], "description": "Full message resource representation" } } } } } } }, "/messages/search/semantic": { "post": { "operationId": "message.semanticSearch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Natural language search query" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Filter results to a specific agent" }, "inboxId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Filter to one inbox — messages delivered to it (inbound) or sent from it (outbound). The precise way to read a single mailbox when an agent owns several." }, "fromAddress": { "type": "string", "description": "Filter by sender address, matched exactly (case-sensitive). On inbound mail this is the counterparty; on outbound it is the agent identity the mail was sent from." }, "toAddress": { "type": "string", "description": "Filter by recipient address, matched exactly (case-sensitive). Note that outbound messages store every recipient in one comma-joined value, so an exact filter matches a multi-recipient send only when given that same joined string — prefer `inboxId` to scope outbound mail to a mailbox." }, "limit": { "default": 10, "type": "integer", "minimum": 1, "maximum": 50, "description": "Maximum number of results to return" }, "threshold": { "default": 0.7, "type": "number", "minimum": 0, "maximum": 1, "description": "Minimum similarity score threshold (0-1)" } }, "required": [ "query" ], "description": "Semantic search parameters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique message identifier" }, "content": { "type": "string", "description": "Message content text" }, "similarity": { "type": "number", "description": "Cosine similarity score between 0 and 1" }, "channel": { "type": "string", "description": "Communication channel (e.g. email, sms)" }, "direction": { "type": "string", "description": "Message direction (inbound or outbound)" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of message creation" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Identifier of the agent associated with the message" }, "inboxId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "ID of the inbox this message belongs to — the inbox it was delivered to (inbound) or sent from (outbound). Null when no inbox backs the address: SMS/MMS/voice messages, and email sent from an email identity that has no inbox. Pass it back as `inboxId` to scope a later search to that one mailbox." } }, "required": [ "id", "content", "similarity", "channel", "direction", "createdAt", "agentId", "inboxId" ], "description": "Semantically matched message" }, "description": "List of messages ranked by semantic similarity" } }, "required": [ "results" ], "description": "Semantic search results" } } } } } } }, "/messages/{messageId}/attachments": { "post": { "operationId": "message.uploadAttachment", "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the message to attach the file to" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Filename for the attachment (max 255 characters)" }, "mimeType": { "type": "string", "minLength": 1, "description": "MIME type of the file being uploaded" }, "sizeBytes": { "type": "integer", "minimum": 0, "description": "File size in bytes (must be greater than zero)" } }, "required": [ "filename", "mimeType", "sizeBytes" ], "description": "Request body for initiating a file attachment upload" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the attachment" }, "filename": { "type": "string", "description": "Original filename of the attachment" }, "mimeType": { "type": "string", "description": "MIME type of the attachment (e.g. application/pdf)" }, "sizeBytes": { "type": "integer", "minimum": 0, "description": "File size in bytes" }, "storageKey": { "type": "string", "description": "Internal storage key for retrieving the file" }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Pre-signed download URL, or null if not yet generated" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the attachment was created" }, "scanStatus": { "enum": [ "PENDING", "CLEAN", "FLAGGED", "BLOCKED" ], "type": "string", "description": "Content-scan verdict. BLOCKED attachments cannot be downloaded — inspect before fetching bytes." }, "detectedMimeType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "MIME type inferred from magic bytes; may differ from the declared mimeType" } }, "required": [ "id", "filename", "mimeType", "sizeBytes", "storageKey", "url", "createdAt", "scanStatus", "detectedMimeType" ], "description": "File attachment associated with a message" } } } } } } }, "/attachments/{id}/download": { "get": { "operationId": "message.getAttachmentUrl", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Unique attachment identifier" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Pre-signed URL for downloading the attachment" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Timestamp when the download URL expires" } }, "required": [ "url", "expiresAt" ], "description": "Pre-signed download URL for an attachment" } } } } } } }, "/attachments/{id}/text": { "get": { "operationId": "message.getAttachmentText", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Unique attachment identifier" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the attachment" }, "filename": { "type": "string", "description": "Original filename of the attachment" }, "mimeType": { "type": "string", "description": "Declared MIME type of the attachment" }, "status": { "enum": [ "PENDING", "EXTRACTED", "UNSUPPORTED", "FAILED" ], "type": "string", "description": "Outcome of extraction. EXTRACTED: `text` holds the content (possibly an empty string — a scanned PDF with no text layer extracts to nothing). UNSUPPORTED: no extractor for this file type; only PDF, DOCX, and plain-text formats are supported. FAILED: the bytes could not be parsed (malformed, encrypted, or too large). UNSUPPORTED and FAILED are final — the file never changes, so retrying returns the same answer. PENDING is never returned; it is the pre-extraction state of the stored row." }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Extracted plain text, or null unless `status` is EXTRACTED. Truncated at 1,000,000 characters. Extracted once and cached, so repeat reads are free." } }, "required": [ "id", "filename", "mimeType", "status", "text" ], "description": "Text extracted from a PDF, DOCX, or plain-text attachment" } } } } } } }, "/phone/search": { "get": { "operationId": "phone.search", "parameters": [ { "name": "countryCode", "in": "query", "schema": { "default": "US", "type": "string", "pattern": "^[A-Za-z]{2}$", "description": "ISO 3166-1 alpha-2 country code to search in" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "numberType", "in": "query", "schema": { "enum": [ "local", "mobile", "national", "toll_free", "shared_cost" ], "type": "string", "description": "Phone number type to search for (treated as local when omitted)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "areaCode", "in": "query", "schema": { "type": "string", "description": "Filter results to a specific area code" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "capabilities", "in": "query", "schema": { "type": "array", "items": { "enum": [ "sms", "mms", "voice" ], "type": "string", "description": "Communication capability type" }, "maxItems": 50, "description": "Required capabilities for the phone numbers" }, "style": "deepObject", "explode": true, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 50, "description": "Maximum number of results to return" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "phoneNumber": { "type": "string", "description": "E.164 formatted phone number available for provisioning" }, "region": { "type": "string", "description": "Geographic region or state of the phone number" }, "capabilities": { "type": "object", "properties": { "sms": { "type": "boolean", "description": "Whether the number supports SMS messaging" }, "mms": { "type": "boolean", "description": "Whether the number supports MMS messaging" }, "voice": { "type": "boolean", "description": "Whether the number supports voice calls" } }, "required": [ "sms", "mms", "voice" ], "description": "Communication capabilities supported by this number" }, "monthlyCost": { "type": "number", "description": "Monthly cost in USD for this phone number" }, "regulatory": { "type": "object", "properties": { "tier": { "enum": [ "NONE", "ADDRESS", "IDENTITY", "DOCS", "UNSUPPORTED" ], "type": "string", "description": "Provisioning requirement tier: NONE = order instantly, ADDRESS = local address required, IDENTITY = identity details required, DOCS = document upload required, UNSUPPORTED = provider does not sell this combination" }, "approvedBundleId": { "type": "string", "description": "The org's approved regulatory bundle satisfying this combination, when one exists" } }, "required": [ "tier" ], "description": "Regulatory context for ordering this number — what ordering will require. Omitted only when requirement discovery is temporarily unavailable" } }, "required": [ "phoneNumber", "capabilities" ], "description": "Available phone number with capabilities and pricing" }, "description": "Array of available phone numbers matching the search criteria" } }, "required": [ "items" ], "description": "Search results for available phone numbers" } } } } } } }, "/phone/requirements": { "get": { "operationId": "phone.requirements", "parameters": [ { "name": "countryCode", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$", "description": "ISO 3166-1 alpha-2 country code to check requirements for" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "numberType", "in": "query", "required": false, "schema": { "default": "local", "enum": [ "local", "mobile", "national", "toll_free", "shared_cost" ], "type": "string", "description": "Phone number type to check requirements for" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code queried" }, "numberType": { "enum": [ "local", "mobile", "national", "toll_free", "shared_cost" ], "type": "string", "description": "Phone number type — regulatory requirements vary by type within a country" }, "tier": { "enum": [ "NONE", "ADDRESS", "IDENTITY", "DOCS", "UNSUPPORTED" ], "type": "string", "description": "Provisioning requirement tier: NONE = order instantly, ADDRESS = local address required, IDENTITY = identity details required, DOCS = document upload required, UNSUPPORTED = provider does not sell this combination" }, "requirements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Provider requirement identifier" }, "name": { "type": "string", "description": "Human-readable requirement name" }, "fieldType": { "type": "string", "description": "Provider field type (document, address, or textual today)" }, "description": { "type": "string", "description": "What the requirement asks for" }, "example": { "type": "string", "description": "Example of an acceptable value" }, "acceptanceCriteria": { "type": "object", "additionalProperties": {}, "description": "Provider acceptance criteria (limits, allowed values)" } }, "required": [ "id", "name", "fieldType" ], "description": "One regulatory requirement field for ordering a number" }, "description": "Requirement fields to satisfy before ordering; empty when tier is NONE" }, "approvedBundleId": { "type": "string", "description": "The org's approved regulatory bundle satisfying this combination, when one exists" } }, "required": [ "countryCode", "numberType", "tier", "requirements" ], "description": "Provisioning requirements for a country/number-type combination" } } } } } } }, "/phone/provision": { "post": { "operationId": "phone.provision", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent to assign the provisioned phone number to" }, "countryCode": { "default": "US", "type": "string", "pattern": "^[A-Za-z]{2}$", "description": "ISO 3166-1 alpha-2 country code for number selection" }, "numberType": { "enum": [ "local", "mobile", "national", "toll_free", "shared_cost" ], "type": "string", "description": "Phone number type to provision (treated as local when omitted)" }, "areaCode": { "type": "string", "description": "Preferred area code for the phone number" }, "capabilities": { "type": "array", "items": { "enum": [ "sms", "mms", "voice" ], "type": "string", "description": "Communication capability type" }, "description": "Required capabilities for the phone number" } }, "required": [ "agentId" ], "description": "Request body for provisioning a new phone number for an agent" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the provisioned phone record" }, "phoneNumber": { "type": "string", "description": "E.164 formatted phone number that was provisioned" }, "providerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque carrier-side identifier for the number" }, "capabilities": { "type": "object", "properties": { "sms": { "type": "boolean", "description": "Whether SMS messaging is enabled" }, "mms": { "type": "boolean", "description": "Whether MMS messaging is enabled" }, "voice": { "type": "boolean", "description": "Whether voice calls are enabled" } }, "required": [ "sms", "mms", "voice" ], "description": "Active communication capabilities for this number" }, "tenDlcStatus": { "enum": [ "PENDING", "REGISTERED", "REJECTED", "NOT_REQUIRED", "UNREGISTERED" ], "type": "string", "description": "10DLC campaign registration status for A2P SMS compliance" }, "isPrimary": { "type": "boolean", "description": "Whether this is the primary phone number for the agent" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the number was provisioned" } }, "required": [ "id", "phoneNumber", "providerId", "capabilities", "tenDlcStatus", "isPrimary", "createdAt" ], "description": "Provisioned phone number resource with provider and compliance details" } } } } } } }, "/phone/release": { "post": { "operationId": "phone.release", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent that currently owns the phone number" }, "phoneNumber": { "type": "string", "description": "E.164 formatted phone number to release" } }, "required": [ "agentId", "phoneNumber" ], "description": "Request body for releasing a phone number from an agent" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true, "description": "Always true on successful release" } }, "required": [ "success" ], "description": "Phone number release confirmation" } } } } } } }, "/phone/send-sms": { "post": { "operationId": "phone.sendSms", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the agent sending the SMS" }, "to": { "type": "string", "minLength": 7, "maxLength": 20, "description": "Recipient phone number in E.164 format" }, "body": { "type": "string", "minLength": 1, "maxLength": 1600, "description": "Text content of the SMS message (max 1600 characters)" }, "mediaUrls": { "default": [], "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 10, "description": "URLs of media attachments for MMS (max 10)" }, "metadata": { "default": {}, "type": "object", "additionalProperties": {}, "description": "Arbitrary key-value metadata to attach to the message" } }, "required": [ "agentId", "to", "body" ], "description": "Request body for sending an SMS or MMS through an agent" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the message" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the agent that sent or received the message" }, "inboxId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "ID of the inbox this message belongs to — the inbox it was delivered to (inbound) or sent from (outbound). Null when no inbox backs the address: SMS/MMS/voice messages, and email sent from an email identity that has no inbox (such as a custom-domain identity added to an agent). Pass it to GET /messages?inboxId= to list one inbox's mail." }, "channel": { "enum": [ "EMAIL", "SMS", "MMS", "VOICE" ], "type": "string", "description": "Communication channel used" }, "direction": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "description": "Whether the message was inbound or outbound" }, "status": { "enum": [ "QUEUED", "SENT", "DELIVERED", "FAILED", "BOUNCED", "BLOCKED", "PENDING_APPROVAL" ], "type": "string", "description": "Current delivery status" }, "fromAddress": { "type": "string", "description": "Sender address (email or phone number)" }, "toAddress": { "type": "string", "description": "Recipient address (email or phone number)" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message subject line, or null for channels that do not support subjects" }, "body": { "type": "string", "description": "Plain-text content of the message" }, "bodyHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML content of the message, or null if not available" }, "extractedText": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plain-text body with the quoted reply chain and signature stripped — just what this sender actually wrote. Read this instead of `body` to avoid re-reading (and paying for) the whole thread on every message. Null when nothing was extracted: non-email channels, messages your agent sent, and mail received before this field existed — so `extractedText ?? body` is always correct. Best-effort and heuristic; `body` remains the verbatim source of truth. Known weak cases: forwards and bottom-posted replies have no separable 'new' part, so this returns the full body rather than nothing." }, "extractedHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML body with quoted reply chains removed. Same semantics as `extractedText`; `bodyHtml` stays verbatim. Quoting styles that mark the chain with a sibling element rather than wrapping it (Outlook) are not stripped here — `extractedText` still is." }, "headers": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Raw message headers as key-value pairs, or null" }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Arbitrary metadata attached to the message, or null" }, "threadId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Thread identifier for conversation grouping, or null" }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Workflow labels on this message. Always contains exactly one of the system labels `unread` or `read`; may also contain `archived`, `spam` (the inbound spam verdict — see `includeSpam` on list/search), and any labels you add yourself. Stored lowercase, deduped, and sorted. Change them with PATCH /messages/{id}/labels." }, "inReplyTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message ID this message is replying to, or null" }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "External identifier, or null. For email: the RFC 5322 Message-ID (bare, no angle brackets) — pass it as inReplyTo to reply in-thread. For SMS: the provider-assigned message id." }, "deletedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this message was moved to Trash, or null if it is live. Deleted messages are hidden from listings unless `deleted` is set to `include` or `only`, and can be brought back with POST /messages/{id}/restore. Nothing purges them." }, "sentAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was sent, or null if not yet sent" }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was received, or null for outbound messages" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the attachment" }, "filename": { "type": "string", "description": "Original filename of the attachment" }, "mimeType": { "type": "string", "description": "MIME type of the attachment (e.g. application/pdf)" }, "sizeBytes": { "type": "integer", "minimum": 0, "description": "File size in bytes" }, "storageKey": { "type": "string", "description": "Internal storage key for retrieving the file" }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Pre-signed download URL, or null if not yet generated" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the attachment was created" }, "scanStatus": { "enum": [ "PENDING", "CLEAN", "FLAGGED", "BLOCKED" ], "type": "string", "description": "Content-scan verdict. BLOCKED attachments cannot be downloaded — inspect before fetching bytes." }, "detectedMimeType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "MIME type inferred from magic bytes; may differ from the declared mimeType" } }, "required": [ "id", "filename", "mimeType", "sizeBytes", "storageKey", "url", "createdAt", "scanStatus", "detectedMimeType" ], "description": "File attachment associated with a message" }, "description": "File attachments associated with this message" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was last updated" } }, "required": [ "id", "agentId", "inboxId", "channel", "direction", "status", "fromAddress", "toAddress", "subject", "body", "bodyHtml", "extractedText", "extractedHtml", "headers", "metadata", "threadId", "labels", "inReplyTo", "externalId", "deletedAt", "sentAt", "receivedAt", "attachments", "createdAt", "updatedAt" ], "description": "Full message resource representation" } } } } } } }, "/phone/sms/threads": { "get": { "operationId": "phone.listSmsThreads", "parameters": [ { "name": "agentId", "in": "query", "schema": { "type": "string", "description": "Filter conversations to one agent. Optional for master keys (omit for every agent in the org); ignored for agent keys, which always see only their own." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum conversations to return per page (1–100, default 20)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "offset", "in": "query", "schema": { "default": 0, "type": "integer", "minimum": 0, "description": "Conversations to skip, for paging through the list" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "threadId": { "type": "string", "description": "Conversation identifier — the id of its first message" }, "agentId": { "type": "string", "description": "Agent that owns this conversation" }, "participantAddress": { "type": "string", "description": "The counterparty's phone number (E.164) — the other end of the conversation" }, "agentAddress": { "type": "string", "description": "The agent's own phone number used in this conversation" }, "lastMessageAt": { "type": "string", "format": "date-time", "description": "Timestamp of the most recent message" }, "lastMessageSnippet": { "type": "string", "description": "First 140 characters of the most recent message's body" }, "lastMessageDirection": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "description": "Direction of the most recent message" }, "messageCount": { "type": "integer", "description": "Total messages in the conversation" }, "unreadCount": { "type": "integer", "description": "How many of them still carry the `unread` label. Inbound texts start unread, so this is what a conversation list needs to be triageable at all." } }, "required": [ "threadId", "agentId", "participantAddress", "agentAddress", "lastMessageAt", "lastMessageSnippet", "lastMessageDirection", "messageCount", "unreadCount" ], "description": "Summary of one SMS/MMS conversation between an agent and a phone number" }, "description": "Conversation summaries, newest activity first" }, "total": { "type": "integer", "description": "Total conversations matching the query" }, "hasMore": { "type": "boolean", "description": "Whether more conversations exist past this page" } }, "required": [ "items", "total", "hasMore" ], "description": "Paginated list of SMS conversations" } } } } } } }, "/phone/sms/threads/{id}": { "get": { "operationId": "phone.getSmsThread", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Conversation identifier from sms_thread_list / MessageOutput.threadId" } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum messages to return (1–100, default 50). When the conversation is longer, the MOST RECENT `limit` messages are returned (still ordered oldest-first among themselves) — reach deeper history via GET /messages?threadId=." }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "threadId": { "type": "string", "description": "Conversation identifier" }, "agentId": { "type": "string", "description": "Agent that owns this conversation" }, "participantAddress": { "type": "string", "description": "The counterparty's phone number (E.164)" }, "agentAddress": { "type": "string", "description": "The agent's own phone number used in this conversation" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the message" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the agent that sent or received the message" }, "inboxId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "ID of the inbox this message belongs to — the inbox it was delivered to (inbound) or sent from (outbound). Null when no inbox backs the address: SMS/MMS/voice messages, and email sent from an email identity that has no inbox (such as a custom-domain identity added to an agent). Pass it to GET /messages?inboxId= to list one inbox's mail." }, "channel": { "enum": [ "EMAIL", "SMS", "MMS", "VOICE" ], "type": "string", "description": "Communication channel used" }, "direction": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "description": "Whether the message was inbound or outbound" }, "status": { "enum": [ "QUEUED", "SENT", "DELIVERED", "FAILED", "BOUNCED", "BLOCKED", "PENDING_APPROVAL" ], "type": "string", "description": "Current delivery status" }, "fromAddress": { "type": "string", "description": "Sender address (email or phone number)" }, "toAddress": { "type": "string", "description": "Recipient address (email or phone number)" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message subject line, or null for channels that do not support subjects" }, "body": { "type": "string", "description": "Plain-text content of the message" }, "bodyHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML content of the message, or null if not available" }, "extractedText": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plain-text body with the quoted reply chain and signature stripped — just what this sender actually wrote. Read this instead of `body` to avoid re-reading (and paying for) the whole thread on every message. Null when nothing was extracted: non-email channels, messages your agent sent, and mail received before this field existed — so `extractedText ?? body` is always correct. Best-effort and heuristic; `body` remains the verbatim source of truth. Known weak cases: forwards and bottom-posted replies have no separable 'new' part, so this returns the full body rather than nothing." }, "extractedHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML body with quoted reply chains removed. Same semantics as `extractedText`; `bodyHtml` stays verbatim. Quoting styles that mark the chain with a sibling element rather than wrapping it (Outlook) are not stripped here — `extractedText` still is." }, "headers": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Raw message headers as key-value pairs, or null" }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Arbitrary metadata attached to the message, or null" }, "threadId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Thread identifier for conversation grouping, or null" }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Workflow labels on this message. Always contains exactly one of the system labels `unread` or `read`; may also contain `archived`, `spam` (the inbound spam verdict — see `includeSpam` on list/search), and any labels you add yourself. Stored lowercase, deduped, and sorted. Change them with PATCH /messages/{id}/labels." }, "inReplyTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message ID this message is replying to, or null" }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "External identifier, or null. For email: the RFC 5322 Message-ID (bare, no angle brackets) — pass it as inReplyTo to reply in-thread. For SMS: the provider-assigned message id." }, "deletedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this message was moved to Trash, or null if it is live. Deleted messages are hidden from listings unless `deleted` is set to `include` or `only`, and can be brought back with POST /messages/{id}/restore. Nothing purges them." }, "sentAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was sent, or null if not yet sent" }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was received, or null for outbound messages" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the attachment" }, "filename": { "type": "string", "description": "Original filename of the attachment" }, "mimeType": { "type": "string", "description": "MIME type of the attachment (e.g. application/pdf)" }, "sizeBytes": { "type": "integer", "minimum": 0, "description": "File size in bytes" }, "storageKey": { "type": "string", "description": "Internal storage key for retrieving the file" }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Pre-signed download URL, or null if not yet generated" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the attachment was created" }, "scanStatus": { "enum": [ "PENDING", "CLEAN", "FLAGGED", "BLOCKED" ], "type": "string", "description": "Content-scan verdict. BLOCKED attachments cannot be downloaded — inspect before fetching bytes." }, "detectedMimeType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "MIME type inferred from magic bytes; may differ from the declared mimeType" } }, "required": [ "id", "filename", "mimeType", "sizeBytes", "storageKey", "url", "createdAt", "scanStatus", "detectedMimeType" ], "description": "File attachment associated with a message" }, "description": "File attachments associated with this message" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was last updated" } }, "required": [ "id", "agentId", "inboxId", "channel", "direction", "status", "fromAddress", "toAddress", "subject", "body", "bodyHtml", "extractedText", "extractedHtml", "headers", "metadata", "threadId", "labels", "inReplyTo", "externalId", "deletedAt", "sentAt", "receivedAt", "attachments", "createdAt", "updatedAt" ], "description": "Full message resource representation" }, "description": "Messages in chronological (oldest-first) reading order. When the conversation is longer than `limit`, this is its most recent window." }, "messageCount": { "type": "integer", "description": "Total messages in the conversation" }, "hasMore": { "type": "boolean", "description": "True when the conversation holds more messages than this response returned (older ones precede `messages`)" } }, "required": [ "threadId", "agentId", "participantAddress", "agentAddress", "messages", "messageCount", "hasMore" ], "description": "One SMS conversation with its message history" } } } } } } }, "/phone/sms-suppressions": { "get": { "operationId": "phone.listSmsSuppressions", "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Opaque cursor from a previous response to fetch the next page" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of items to return per page (1–100, default 20)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "phoneNumber", "in": "query", "schema": { "type": "string", "description": "Filter to a single recipient phone number (E.164 or close; normalized server-side)" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the suppression entry" }, "phoneNumber": { "type": "string", "description": "Suppressed recipient phone number (E.164)" }, "agentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent the suppression is scoped to, or null when workspace-wide" }, "reason": { "enum": [ "STOP_KEYWORD", "MANUAL" ], "type": "string", "description": "Why the number is suppressed (recipient texted STOP, or manual admin entry)" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-form origin marker, e.g. 'inbound-stop-keyword' or 'manual-admin-add'" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the suppression was recorded" } }, "required": [ "id", "phoneNumber", "agentId", "reason", "source", "createdAt" ], "description": "A suppressed SMS recipient — sends to it are refused with RECIPIENT_OPTED_OUT until the recipient texts START or the org owner unsuppresses" }, "description": "Suppression entries matching the query" }, "pagination": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "Cursor to pass as the `cursor` parameter to retrieve the next page, or null if no more results" }, "hasMore": { "type": "boolean", "description": "Whether additional pages of results are available" } }, "required": [ "nextCursor", "hasMore" ], "description": "Pagination metadata for retrieving additional pages" } }, "required": [ "items", "pagination" ], "description": "Paginated list of suppressed SMS recipients" } } } } } } }, "/phone/sms-unsuppress": { "post": { "operationId": "phone.unsuppressSms", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phoneNumber": { "type": "string", "minLength": 7, "maxLength": 20, "description": "Recipient phone number to unsuppress (E.164 or close; normalized server-side)" } }, "required": [ "phoneNumber" ], "description": "Master-key override that removes every SMS suppression for a number in this org. Use sparingly: the entries record the recipient's own STOP — prefer letting them text START" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "phoneNumber": { "type": "string", "description": "The normalized phone number that was unsuppressed" }, "removed": { "type": "integer", "description": "How many suppression entries were removed" } }, "required": [ "phoneNumber", "removed" ], "description": "Result of the SMS unsuppress override" } } } } } } }, "/phone/numbers": { "get": { "operationId": "phone.list", "parameters": [ { "name": "agentId", "in": "query", "required": true, "schema": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent whose phone numbers to list" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the phone identity" }, "phoneNumber": { "type": "string", "description": "Phone number in E.164 format" }, "providerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque carrier-side identifier for this phone number" }, "capabilities": { "type": "object", "properties": { "sms": { "default": false, "type": "boolean", "description": "Whether the number supports SMS messaging" }, "mms": { "default": false, "type": "boolean", "description": "Whether the number supports MMS messaging" }, "voice": { "default": false, "type": "boolean", "description": "Whether the number supports voice calls" } }, "description": "Communication capabilities supported by this phone number" }, "tenDlcStatus": { "enum": [ "PENDING", "REGISTERED", "REJECTED", "NOT_REQUIRED", "UNREGISTERED" ], "type": "string", "description": "10DLC campaign registration status" }, "isPrimary": { "type": "boolean", "description": "Whether this is the agent's primary phone identity" }, "voiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The voice this number answers with, from the voice catalog. Null means it uses the agent's voice, and then the system default. Set it per number so one agent's support line and sales line can sound different." }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the phone identity was created" } }, "required": [ "id", "phoneNumber", "providerId", "capabilities", "tenDlcStatus", "isPrimary", "voiceId", "createdAt" ], "description": "Phone identity associated with an agent" }, "description": "Array of phone identity records for the agent" } }, "required": [ "items" ], "description": "List of phone numbers assigned to an agent" } } } } } } }, "/phone/numbers/{phoneIdentityId}": { "patch": { "operationId": "phone.updateNumber", "parameters": [ { "name": "phoneIdentityId", "in": "path", "required": true, "schema": { "type": "string", "description": "The number to update" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "voiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Voice id from the catalog, or null to fall back to the agent's voice. Rejected if the id is not in the catalog." } }, "required": [ "voiceId" ], "description": "Update one phone number's settings" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the phone identity" }, "phoneNumber": { "type": "string", "description": "Phone number in E.164 format" }, "providerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque carrier-side identifier for this phone number" }, "capabilities": { "type": "object", "properties": { "sms": { "default": false, "type": "boolean", "description": "Whether the number supports SMS messaging" }, "mms": { "default": false, "type": "boolean", "description": "Whether the number supports MMS messaging" }, "voice": { "default": false, "type": "boolean", "description": "Whether the number supports voice calls" } }, "description": "Communication capabilities supported by this phone number" }, "tenDlcStatus": { "enum": [ "PENDING", "REGISTERED", "REJECTED", "NOT_REQUIRED", "UNREGISTERED" ], "type": "string", "description": "10DLC campaign registration status" }, "isPrimary": { "type": "boolean", "description": "Whether this is the agent's primary phone identity" }, "voiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The voice this number answers with, from the voice catalog. Null means it uses the agent's voice, and then the system default. Set it per number so one agent's support line and sales line can sound different." }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the phone identity was created" } }, "required": [ "id", "phoneNumber", "providerId", "capabilities", "tenDlcStatus", "isPrimary", "voiceId", "createdAt" ], "description": "Phone identity associated with an agent" } } } } } } }, "/vault/identities": { "get": { "operationId": "vault.listIdentities", "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Opaque cursor from a previous response to fetch the next page" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of items to return per page (1–100, default 20)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "status", "in": "query", "schema": { "enum": [ "ACTIVE", "LOCKED", "ERROR" ], "type": "string", "description": "Filter vault identities by status" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique vault record identifier" }, "agentId": { "type": "string", "description": "Agent the vault belongs to" }, "orgId": { "type": "string", "description": "Organization the vault belongs to" }, "vaultUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Vault backend user identifier" }, "vaultOrgId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Vault backend organization identifier" }, "collectionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Default collection identifier in the vault" }, "status": { "enum": [ "ACTIVE", "LOCKED", "ERROR" ], "type": "string", "description": "Current vault operational status" }, "credentialCount": { "type": "integer", "minimum": 0, "description": "Total number of credentials stored" }, "lastSyncAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp of the last vault synchronization" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the vault was provisioned" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the vault was last updated" }, "agentName": { "type": "string", "description": "Name of the agent that owns the vault" }, "agentSlug": { "type": "string", "description": "Slug of the agent that owns the vault" } }, "required": [ "id", "agentId", "orgId", "vaultUserId", "vaultOrgId", "collectionId", "status", "credentialCount", "lastSyncAt", "createdAt", "updatedAt", "agentName", "agentSlug" ], "description": "Provisioned vault details for an agent" }, "description": "List of vault identities with agent information" }, "pagination": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "Cursor to pass as the `cursor` parameter to retrieve the next page, or null if no more results" }, "hasMore": { "type": "boolean", "description": "Whether additional pages of results are available" } }, "required": [ "nextCursor", "hasMore" ], "description": "Cursor-based pagination metadata" } }, "required": [ "items", "pagination" ], "description": "Paginated list of vault identities for an organization" } } } } } } }, "/vault/provision": { "post": { "operationId": "vault.provision", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier to provision a vault for — master key only" } }, "required": [ "agentId" ], "description": "Input for provisioning a new agent vault" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique vault record identifier" }, "agentId": { "type": "string", "description": "Agent the vault belongs to" }, "orgId": { "type": "string", "description": "Organization the vault belongs to" }, "vaultUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Vault backend user identifier" }, "vaultOrgId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Vault backend organization identifier" }, "collectionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Default collection identifier in the vault" }, "status": { "enum": [ "ACTIVE", "LOCKED", "ERROR" ], "type": "string", "description": "Current vault operational status" }, "credentialCount": { "type": "integer", "minimum": 0, "description": "Total number of credentials stored" }, "lastSyncAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp of the last vault synchronization" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the vault was provisioned" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the vault was last updated" } }, "required": [ "id", "agentId", "orgId", "vaultUserId", "vaultOrgId", "collectionId", "status", "credentialCount", "lastSyncAt", "createdAt", "updatedAt" ], "description": "Provisioned vault details for an agent" } } } } } } }, "/vault/deprovision": { "post": { "operationId": "vault.deprovision", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier to provision a vault for — master key only" } }, "required": [ "agentId" ], "description": "Input for provisioning a new agent vault" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true } }, "required": [ "success" ] } } } } } } }, "/vault/credentials": { "get": { "operationId": "vault.list", "parameters": [ { "name": "agentId", "in": "query", "schema": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier. Optional when using an agent API key (resolved automatically); required when using a master key." }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique credential identifier" }, "type": { "enum": [ "login", "secure_note", "card", "identity", "oauth_token", "api_key", "certificate" ], "type": "string", "description": "Credential type" }, "name": { "type": "string", "description": "User-defined credential name" }, "notes": { "type": "string", "description": "Free-form notes attached to the credential" }, "login": { "type": "object", "properties": { "username": { "type": "string", "description": "Login username or email" }, "password": { "type": "string", "description": "Login password" }, "uris": { "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string", "description": "URI associated with the credential" }, "match": { "enum": [ "domain", "host", "starts_with", "regex", "never" ], "type": "string", "description": "URI matching strategy for auto-fill" } }, "required": [ "uri" ], "description": "URI entry with matching rules for credential auto-fill" }, "description": "URIs associated with this login" }, "totp": { "type": "string", "description": "TOTP secret for two-factor authentication" } }, "description": "Login credential data, present when type is login" }, "card": { "type": "object", "properties": { "cardholderName": { "type": "string", "description": "Name on the payment card" }, "brand": { "type": "string", "description": "Card brand (e.g. Visa, Mastercard)" }, "number": { "type": "string", "description": "Full card number" }, "expMonth": { "type": "string", "description": "Card expiration month" }, "expYear": { "type": "string", "description": "Card expiration year" }, "code": { "type": "string", "description": "Card security code (CVV/CVC)" } }, "description": "Card credential data, present when type is card" }, "identity": { "type": "object", "properties": { "firstName": { "type": "string", "description": "First name" }, "lastName": { "type": "string", "description": "Last name" }, "email": { "type": "string", "format": "email", "description": "Email address" }, "phone": { "type": "string", "description": "Phone number" }, "address1": { "type": "string", "description": "Street address" }, "city": { "type": "string", "description": "City" }, "state": { "type": "string", "description": "State or province" }, "postalCode": { "type": "string", "description": "Postal or ZIP code" }, "country": { "type": "string", "description": "Country code or name" }, "company": { "type": "string", "description": "Company or organization name" }, "ssn": { "type": "string", "description": "Social security number" } }, "description": "Identity credential data, present when type is identity" }, "oauthToken": { "type": "object", "properties": { "provider": { "type": "string", "description": "OAuth provider name (e.g. google, github, slack)" }, "accessToken": { "type": "string", "description": "Encrypted OAuth access token" }, "refreshToken": { "type": "string", "description": "Encrypted OAuth refresh token" }, "tokenEndpoint": { "type": "string", "description": "OAuth token endpoint URL for refreshing tokens" }, "clientId": { "type": "string", "description": "Encrypted OAuth client ID" }, "clientSecret": { "type": "string", "description": "Encrypted OAuth client secret" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "OAuth scopes granted to this token" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Token expiration timestamp" }, "autoRefresh": { "default": true, "type": "boolean", "description": "Whether to automatically refresh the token before expiry" }, "allowedHosts": { "type": "array", "items": { "type": "string" }, "description": "Hosts this token may be brokered to via server-side use. Fail-closed if empty." } }, "required": [ "provider", "accessToken", "refreshToken", "tokenEndpoint", "clientId", "scopes", "expiresAt" ], "description": "OAuth token data, present when type is oauth_token" }, "apiKey": { "type": "object", "properties": { "provider": { "type": "string", "description": "API provider name (e.g. openai, anthropic, stripe)" }, "key": { "type": "string", "description": "Encrypted API key" }, "prefix": { "type": "string", "description": "Display prefix for the key (e.g. 'sk-...abc')" }, "rateLimit": { "type": "object", "properties": { "requests": { "type": "integer", "minimum": 0, "description": "Maximum number of requests allowed" }, "window": { "type": "string", "description": "Time window for rate limiting (e.g. '1m', '1h', '1d')" } }, "required": [ "requests", "window" ], "description": "Rate limit configuration for this key" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Optional key expiration timestamp" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Optional scopes or permissions for this key" }, "allowedHosts": { "type": "array", "items": { "type": "string" }, "description": "Hosts this key may be brokered to via server-side use. Fail-closed if empty." }, "authHeader": { "type": "string", "description": "Header the broker injects the key into (default 'Authorization')." }, "authScheme": { "type": "string", "description": "Value prefix before the key (default 'Bearer '; set '' for a raw key, e.g. x-api-key)." } }, "required": [ "provider", "key" ], "description": "API key data, present when type is api_key" }, "certificate": { "type": "object", "properties": { "format": { "enum": [ "pem", "p12", "jks" ], "type": "string", "description": "Certificate format" }, "certificate": { "type": "string", "description": "Encrypted certificate content" }, "privateKey": { "type": "string", "description": "Encrypted private key" }, "chain": { "type": "array", "items": { "type": "string" }, "description": "Encrypted certificate chain" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Certificate expiration timestamp" } }, "required": [ "format", "certificate", "privateKey", "expiresAt" ], "description": "Certificate data, present when type is certificate" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Field name" }, "value": { "type": "string", "description": "Field value" }, "type": { "enum": [ "text", "hidden", "boolean" ], "type": "string", "description": "Field display type" } }, "required": [ "name", "value", "type" ], "description": "Custom key-value field attached to a credential" }, "description": "Custom fields attached to the credential" }, "favorite": { "type": "boolean", "description": "Whether the credential is marked as a favorite" }, "folderId": { "type": "string", "description": "Folder the credential belongs to" }, "organizationId": { "type": "string", "description": "Organization the credential is scoped to" }, "collectionIds": { "type": "array", "items": { "type": "string" }, "description": "Collections the credential is shared with" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the credential was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the credential was last updated" }, "revealPolicy": { "enum": [ "standard", "brokered" ], "type": "string", "description": "Reveal policy governing whether plaintext may be returned (default 'standard')" } }, "required": [ "id", "type", "name", "favorite", "createdAt", "updatedAt" ], "description": "Full credential record returned from the vault" }, "description": "List of credentials matching the query" } }, "required": [ "items" ], "description": "List of vault credentials" } } } } } }, "post": { "operationId": "vault.create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier. Optional when using an agent API key (resolved automatically); required when using a master key." }, "type": { "enum": [ "login", "secure_note", "card", "identity", "oauth_token", "api_key", "certificate" ], "type": "string", "description": "Type of credential to create" }, "name": { "type": "string", "minLength": 1, "description": "Display name for the credential" }, "notes": { "type": "string", "description": "Free-form notes to attach" }, "login": { "type": "object", "properties": { "username": { "type": "string", "description": "Login username or email" }, "password": { "type": "string", "description": "Login password" }, "uris": { "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string", "description": "URI associated with the credential" }, "match": { "enum": [ "domain", "host", "starts_with", "regex", "never" ], "type": "string", "description": "URI matching strategy for auto-fill" } }, "required": [ "uri" ], "description": "URI entry with matching rules for credential auto-fill" }, "description": "URIs associated with this login" }, "totp": { "type": "string", "description": "TOTP secret for two-factor authentication" } }, "description": "Login data, required when type is login" }, "generatePassword": { "type": "object", "properties": { "length": { "type": "integer", "minimum": 8, "maximum": 128, "description": "Desired password length (8-128 characters, default 24)" }, "uppercase": { "type": "boolean", "description": "Include uppercase letters (default true)" }, "lowercase": { "type": "boolean", "description": "Include lowercase letters (default true)" }, "number": { "type": "boolean", "description": "Include numeric digits (default true)" }, "special": { "type": "boolean", "description": "Include special characters (default true)" } }, "description": "Generate the login password server-side instead of supplying login.password. Only valid when type is 'login'; mutually exclusive with login.password. The response contains only the credential ref with masked fields — retrieve the password via the vault token flow (scope 'autofill') or master-key reveal." }, "card": { "type": "object", "properties": { "cardholderName": { "type": "string", "description": "Name on the payment card" }, "brand": { "type": "string", "description": "Card brand (e.g. Visa, Mastercard)" }, "number": { "type": "string", "description": "Full card number" }, "expMonth": { "type": "string", "description": "Card expiration month" }, "expYear": { "type": "string", "description": "Card expiration year" }, "code": { "type": "string", "description": "Card security code (CVV/CVC)" } }, "description": "Card data, required when type is card" }, "identity": { "type": "object", "properties": { "firstName": { "type": "string", "description": "First name" }, "lastName": { "type": "string", "description": "Last name" }, "email": { "type": "string", "format": "email", "description": "Email address" }, "phone": { "type": "string", "description": "Phone number" }, "address1": { "type": "string", "description": "Street address" }, "city": { "type": "string", "description": "City" }, "state": { "type": "string", "description": "State or province" }, "postalCode": { "type": "string", "description": "Postal or ZIP code" }, "country": { "type": "string", "description": "Country code or name" }, "company": { "type": "string", "description": "Company or organization name" }, "ssn": { "type": "string", "description": "Social security number" } }, "description": "Identity data, required when type is identity" }, "oauthToken": { "type": "object", "properties": { "provider": { "type": "string", "description": "OAuth provider name (e.g. google, github, slack)" }, "accessToken": { "type": "string", "description": "Encrypted OAuth access token" }, "refreshToken": { "type": "string", "description": "Encrypted OAuth refresh token" }, "tokenEndpoint": { "type": "string", "description": "OAuth token endpoint URL for refreshing tokens" }, "clientId": { "type": "string", "description": "Encrypted OAuth client ID" }, "clientSecret": { "type": "string", "description": "Encrypted OAuth client secret" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "OAuth scopes granted to this token" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Token expiration timestamp" }, "autoRefresh": { "default": true, "type": "boolean", "description": "Whether to automatically refresh the token before expiry" }, "allowedHosts": { "type": "array", "items": { "type": "string" }, "description": "Hosts this token may be brokered to via server-side use. Fail-closed if empty." } }, "required": [ "provider", "accessToken", "refreshToken", "tokenEndpoint", "clientId", "scopes", "expiresAt" ], "description": "OAuth token data, required when type is oauth_token" }, "apiKey": { "type": "object", "properties": { "provider": { "type": "string", "description": "API provider name (e.g. openai, anthropic, stripe)" }, "key": { "type": "string", "description": "Encrypted API key" }, "prefix": { "type": "string", "description": "Display prefix for the key (e.g. 'sk-...abc')" }, "rateLimit": { "type": "object", "properties": { "requests": { "type": "integer", "minimum": 0, "description": "Maximum number of requests allowed" }, "window": { "type": "string", "description": "Time window for rate limiting (e.g. '1m', '1h', '1d')" } }, "required": [ "requests", "window" ], "description": "Rate limit configuration for this key" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Optional key expiration timestamp" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Optional scopes or permissions for this key" }, "allowedHosts": { "type": "array", "items": { "type": "string" }, "description": "Hosts this key may be brokered to via server-side use. Fail-closed if empty." }, "authHeader": { "type": "string", "description": "Header the broker injects the key into (default 'Authorization')." }, "authScheme": { "type": "string", "description": "Value prefix before the key (default 'Bearer '; set '' for a raw key, e.g. x-api-key)." } }, "required": [ "provider", "key" ], "description": "API key data, required when type is api_key" }, "certificate": { "type": "object", "properties": { "format": { "enum": [ "pem", "p12", "jks" ], "type": "string", "description": "Certificate format" }, "certificate": { "type": "string", "description": "Encrypted certificate content" }, "privateKey": { "type": "string", "description": "Encrypted private key" }, "chain": { "type": "array", "items": { "type": "string" }, "description": "Encrypted certificate chain" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Certificate expiration timestamp" } }, "required": [ "format", "certificate", "privateKey", "expiresAt" ], "description": "Certificate data, required when type is certificate" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Field name" }, "value": { "type": "string", "description": "Field value" }, "type": { "enum": [ "text", "hidden", "boolean" ], "type": "string", "description": "Field display type" } }, "required": [ "name", "value", "type" ], "description": "Custom key-value field attached to a credential" }, "description": "Custom fields to attach" }, "favorite": { "default": false, "type": "boolean", "description": "Mark the credential as a favorite" }, "folderId": { "type": "string", "description": "Folder to place the credential in" }, "organizationId": { "type": "string", "description": "Organization to scope the credential to" }, "collectionIds": { "type": "array", "items": { "type": "string" }, "description": "Collections to share the credential with" }, "revealPolicy": { "enum": [ "standard", "brokered" ], "type": "string", "description": "Reveal policy for this credential. When omitted, agent-key-created logins default to 'brokered' and everything else follows the org's defaultRevealPolicy setting (itself defaulting to 'standard')." } }, "required": [ "type", "name" ], "description": "Input for creating a new vault credential" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique credential identifier" }, "type": { "enum": [ "login", "secure_note", "card", "identity", "oauth_token", "api_key", "certificate" ], "type": "string", "description": "Credential type" }, "name": { "type": "string", "description": "User-defined credential name" }, "notes": { "type": "string", "description": "Free-form notes attached to the credential" }, "login": { "type": "object", "properties": { "username": { "type": "string", "description": "Login username or email" }, "password": { "type": "string", "description": "Login password" }, "uris": { "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string", "description": "URI associated with the credential" }, "match": { "enum": [ "domain", "host", "starts_with", "regex", "never" ], "type": "string", "description": "URI matching strategy for auto-fill" } }, "required": [ "uri" ], "description": "URI entry with matching rules for credential auto-fill" }, "description": "URIs associated with this login" }, "totp": { "type": "string", "description": "TOTP secret for two-factor authentication" } }, "description": "Login credential data, present when type is login" }, "card": { "type": "object", "properties": { "cardholderName": { "type": "string", "description": "Name on the payment card" }, "brand": { "type": "string", "description": "Card brand (e.g. Visa, Mastercard)" }, "number": { "type": "string", "description": "Full card number" }, "expMonth": { "type": "string", "description": "Card expiration month" }, "expYear": { "type": "string", "description": "Card expiration year" }, "code": { "type": "string", "description": "Card security code (CVV/CVC)" } }, "description": "Card credential data, present when type is card" }, "identity": { "type": "object", "properties": { "firstName": { "type": "string", "description": "First name" }, "lastName": { "type": "string", "description": "Last name" }, "email": { "type": "string", "format": "email", "description": "Email address" }, "phone": { "type": "string", "description": "Phone number" }, "address1": { "type": "string", "description": "Street address" }, "city": { "type": "string", "description": "City" }, "state": { "type": "string", "description": "State or province" }, "postalCode": { "type": "string", "description": "Postal or ZIP code" }, "country": { "type": "string", "description": "Country code or name" }, "company": { "type": "string", "description": "Company or organization name" }, "ssn": { "type": "string", "description": "Social security number" } }, "description": "Identity credential data, present when type is identity" }, "oauthToken": { "type": "object", "properties": { "provider": { "type": "string", "description": "OAuth provider name (e.g. google, github, slack)" }, "accessToken": { "type": "string", "description": "Encrypted OAuth access token" }, "refreshToken": { "type": "string", "description": "Encrypted OAuth refresh token" }, "tokenEndpoint": { "type": "string", "description": "OAuth token endpoint URL for refreshing tokens" }, "clientId": { "type": "string", "description": "Encrypted OAuth client ID" }, "clientSecret": { "type": "string", "description": "Encrypted OAuth client secret" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "OAuth scopes granted to this token" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Token expiration timestamp" }, "autoRefresh": { "default": true, "type": "boolean", "description": "Whether to automatically refresh the token before expiry" }, "allowedHosts": { "type": "array", "items": { "type": "string" }, "description": "Hosts this token may be brokered to via server-side use. Fail-closed if empty." } }, "required": [ "provider", "accessToken", "refreshToken", "tokenEndpoint", "clientId", "scopes", "expiresAt" ], "description": "OAuth token data, present when type is oauth_token" }, "apiKey": { "type": "object", "properties": { "provider": { "type": "string", "description": "API provider name (e.g. openai, anthropic, stripe)" }, "key": { "type": "string", "description": "Encrypted API key" }, "prefix": { "type": "string", "description": "Display prefix for the key (e.g. 'sk-...abc')" }, "rateLimit": { "type": "object", "properties": { "requests": { "type": "integer", "minimum": 0, "description": "Maximum number of requests allowed" }, "window": { "type": "string", "description": "Time window for rate limiting (e.g. '1m', '1h', '1d')" } }, "required": [ "requests", "window" ], "description": "Rate limit configuration for this key" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Optional key expiration timestamp" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Optional scopes or permissions for this key" }, "allowedHosts": { "type": "array", "items": { "type": "string" }, "description": "Hosts this key may be brokered to via server-side use. Fail-closed if empty." }, "authHeader": { "type": "string", "description": "Header the broker injects the key into (default 'Authorization')." }, "authScheme": { "type": "string", "description": "Value prefix before the key (default 'Bearer '; set '' for a raw key, e.g. x-api-key)." } }, "required": [ "provider", "key" ], "description": "API key data, present when type is api_key" }, "certificate": { "type": "object", "properties": { "format": { "enum": [ "pem", "p12", "jks" ], "type": "string", "description": "Certificate format" }, "certificate": { "type": "string", "description": "Encrypted certificate content" }, "privateKey": { "type": "string", "description": "Encrypted private key" }, "chain": { "type": "array", "items": { "type": "string" }, "description": "Encrypted certificate chain" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Certificate expiration timestamp" } }, "required": [ "format", "certificate", "privateKey", "expiresAt" ], "description": "Certificate data, present when type is certificate" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Field name" }, "value": { "type": "string", "description": "Field value" }, "type": { "enum": [ "text", "hidden", "boolean" ], "type": "string", "description": "Field display type" } }, "required": [ "name", "value", "type" ], "description": "Custom key-value field attached to a credential" }, "description": "Custom fields attached to the credential" }, "favorite": { "type": "boolean", "description": "Whether the credential is marked as a favorite" }, "folderId": { "type": "string", "description": "Folder the credential belongs to" }, "organizationId": { "type": "string", "description": "Organization the credential is scoped to" }, "collectionIds": { "type": "array", "items": { "type": "string" }, "description": "Collections the credential is shared with" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the credential was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the credential was last updated" }, "revealPolicy": { "enum": [ "standard", "brokered" ], "type": "string", "description": "Reveal policy governing whether plaintext may be returned (default 'standard')" } }, "required": [ "id", "type", "name", "favorite", "createdAt", "updatedAt" ], "description": "Full credential record returned from the vault" } } } } } } }, "/vault/credentials/{id}": { "get": { "operationId": "vault.get", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Credential identifier" } }, { "name": "agentId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier. Optional when using an agent API key (resolved automatically); required when using a master key." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "reveal", "in": "query", "required": false, "schema": { "default": false, "type": "boolean", "description": "Return unmasked plaintext fields. Requires master key auth. Audit-logged as 'access_reveal'." }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique credential identifier" }, "type": { "enum": [ "login", "secure_note", "card", "identity", "oauth_token", "api_key", "certificate" ], "type": "string", "description": "Credential type" }, "name": { "type": "string", "description": "User-defined credential name" }, "notes": { "type": "string", "description": "Free-form notes attached to the credential" }, "login": { "type": "object", "properties": { "username": { "type": "string", "description": "Login username or email" }, "password": { "type": "string", "description": "Login password" }, "uris": { "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string", "description": "URI associated with the credential" }, "match": { "enum": [ "domain", "host", "starts_with", "regex", "never" ], "type": "string", "description": "URI matching strategy for auto-fill" } }, "required": [ "uri" ], "description": "URI entry with matching rules for credential auto-fill" }, "description": "URIs associated with this login" }, "totp": { "type": "string", "description": "TOTP secret for two-factor authentication" } }, "description": "Login credential data, present when type is login" }, "card": { "type": "object", "properties": { "cardholderName": { "type": "string", "description": "Name on the payment card" }, "brand": { "type": "string", "description": "Card brand (e.g. Visa, Mastercard)" }, "number": { "type": "string", "description": "Full card number" }, "expMonth": { "type": "string", "description": "Card expiration month" }, "expYear": { "type": "string", "description": "Card expiration year" }, "code": { "type": "string", "description": "Card security code (CVV/CVC)" } }, "description": "Card credential data, present when type is card" }, "identity": { "type": "object", "properties": { "firstName": { "type": "string", "description": "First name" }, "lastName": { "type": "string", "description": "Last name" }, "email": { "type": "string", "format": "email", "description": "Email address" }, "phone": { "type": "string", "description": "Phone number" }, "address1": { "type": "string", "description": "Street address" }, "city": { "type": "string", "description": "City" }, "state": { "type": "string", "description": "State or province" }, "postalCode": { "type": "string", "description": "Postal or ZIP code" }, "country": { "type": "string", "description": "Country code or name" }, "company": { "type": "string", "description": "Company or organization name" }, "ssn": { "type": "string", "description": "Social security number" } }, "description": "Identity credential data, present when type is identity" }, "oauthToken": { "type": "object", "properties": { "provider": { "type": "string", "description": "OAuth provider name (e.g. google, github, slack)" }, "accessToken": { "type": "string", "description": "Encrypted OAuth access token" }, "refreshToken": { "type": "string", "description": "Encrypted OAuth refresh token" }, "tokenEndpoint": { "type": "string", "description": "OAuth token endpoint URL for refreshing tokens" }, "clientId": { "type": "string", "description": "Encrypted OAuth client ID" }, "clientSecret": { "type": "string", "description": "Encrypted OAuth client secret" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "OAuth scopes granted to this token" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Token expiration timestamp" }, "autoRefresh": { "default": true, "type": "boolean", "description": "Whether to automatically refresh the token before expiry" }, "allowedHosts": { "type": "array", "items": { "type": "string" }, "description": "Hosts this token may be brokered to via server-side use. Fail-closed if empty." } }, "required": [ "provider", "accessToken", "refreshToken", "tokenEndpoint", "clientId", "scopes", "expiresAt" ], "description": "OAuth token data, present when type is oauth_token" }, "apiKey": { "type": "object", "properties": { "provider": { "type": "string", "description": "API provider name (e.g. openai, anthropic, stripe)" }, "key": { "type": "string", "description": "Encrypted API key" }, "prefix": { "type": "string", "description": "Display prefix for the key (e.g. 'sk-...abc')" }, "rateLimit": { "type": "object", "properties": { "requests": { "type": "integer", "minimum": 0, "description": "Maximum number of requests allowed" }, "window": { "type": "string", "description": "Time window for rate limiting (e.g. '1m', '1h', '1d')" } }, "required": [ "requests", "window" ], "description": "Rate limit configuration for this key" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Optional key expiration timestamp" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Optional scopes or permissions for this key" }, "allowedHosts": { "type": "array", "items": { "type": "string" }, "description": "Hosts this key may be brokered to via server-side use. Fail-closed if empty." }, "authHeader": { "type": "string", "description": "Header the broker injects the key into (default 'Authorization')." }, "authScheme": { "type": "string", "description": "Value prefix before the key (default 'Bearer '; set '' for a raw key, e.g. x-api-key)." } }, "required": [ "provider", "key" ], "description": "API key data, present when type is api_key" }, "certificate": { "type": "object", "properties": { "format": { "enum": [ "pem", "p12", "jks" ], "type": "string", "description": "Certificate format" }, "certificate": { "type": "string", "description": "Encrypted certificate content" }, "privateKey": { "type": "string", "description": "Encrypted private key" }, "chain": { "type": "array", "items": { "type": "string" }, "description": "Encrypted certificate chain" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Certificate expiration timestamp" } }, "required": [ "format", "certificate", "privateKey", "expiresAt" ], "description": "Certificate data, present when type is certificate" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Field name" }, "value": { "type": "string", "description": "Field value" }, "type": { "enum": [ "text", "hidden", "boolean" ], "type": "string", "description": "Field display type" } }, "required": [ "name", "value", "type" ], "description": "Custom key-value field attached to a credential" }, "description": "Custom fields attached to the credential" }, "favorite": { "type": "boolean", "description": "Whether the credential is marked as a favorite" }, "folderId": { "type": "string", "description": "Folder the credential belongs to" }, "organizationId": { "type": "string", "description": "Organization the credential is scoped to" }, "collectionIds": { "type": "array", "items": { "type": "string" }, "description": "Collections the credential is shared with" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the credential was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the credential was last updated" }, "revealPolicy": { "enum": [ "standard", "brokered" ], "type": "string", "description": "Reveal policy governing whether plaintext may be returned (default 'standard')" } }, "required": [ "id", "type", "name", "favorite", "createdAt", "updatedAt" ], "description": "Full credential record returned from the vault" } } } } } }, "put": { "operationId": "vault.update", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Credential identifier" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier. Optional when using an agent API key (resolved automatically); required when using a master key." }, "reveal": { "default": false, "type": "boolean", "description": "Return unmasked plaintext fields. Requires master key auth. Audit-logged as 'access_reveal'." }, "name": { "type": "string", "minLength": 1, "description": "Updated display name" }, "notes": { "type": "string", "description": "Updated notes" }, "login": { "type": "object", "properties": { "username": { "type": "string", "description": "Login username or email" }, "password": { "type": "string", "description": "Login password" }, "uris": { "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string", "description": "URI associated with the credential" }, "match": { "enum": [ "domain", "host", "starts_with", "regex", "never" ], "type": "string", "description": "URI matching strategy for auto-fill" } }, "required": [ "uri" ], "description": "URI entry with matching rules for credential auto-fill" }, "description": "URIs associated with this login" }, "totp": { "type": "string", "description": "TOTP secret for two-factor authentication" } }, "description": "Login patch. Fields you omit keep their stored values; a masked echo (e.g. '****') of password/totp also counts as unchanged." }, "card": { "type": "object", "properties": { "cardholderName": { "type": "string", "description": "Name on the payment card" }, "brand": { "type": "string", "description": "Card brand (e.g. Visa, Mastercard)" }, "number": { "type": "string", "description": "Full card number" }, "expMonth": { "type": "string", "description": "Card expiration month" }, "expYear": { "type": "string", "description": "Card expiration year" }, "code": { "type": "string", "description": "Card security code (CVV/CVC)" } }, "description": "Updated card data" }, "identity": { "type": "object", "properties": { "firstName": { "type": "string", "description": "First name" }, "lastName": { "type": "string", "description": "Last name" }, "email": { "type": "string", "format": "email", "description": "Email address" }, "phone": { "type": "string", "description": "Phone number" }, "address1": { "type": "string", "description": "Street address" }, "city": { "type": "string", "description": "City" }, "state": { "type": "string", "description": "State or province" }, "postalCode": { "type": "string", "description": "Postal or ZIP code" }, "country": { "type": "string", "description": "Country code or name" }, "company": { "type": "string", "description": "Company or organization name" }, "ssn": { "type": "string", "description": "Social security number" } }, "description": "Updated identity data" }, "oauthToken": { "type": "object", "properties": { "provider": { "type": "string", "description": "OAuth provider name (e.g. google, github, slack)" }, "accessToken": { "type": "string", "description": "Encrypted OAuth access token" }, "refreshToken": { "type": "string", "description": "Encrypted OAuth refresh token" }, "tokenEndpoint": { "type": "string", "description": "OAuth token endpoint URL for refreshing tokens" }, "clientId": { "type": "string", "description": "Encrypted OAuth client ID" }, "clientSecret": { "type": "string", "description": "Encrypted OAuth client secret" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "OAuth scopes granted to this token" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Token expiration timestamp" }, "autoRefresh": { "default": true, "type": "boolean", "description": "Whether to automatically refresh the token before expiry" }, "allowedHosts": { "type": "array", "items": { "type": "string" }, "description": "Hosts this token may be brokered to via server-side use. Fail-closed if empty." } }, "description": "OAuth token patch. Omitted fields keep their stored values; masked echoes of accessToken/refreshToken/clientSecret count as unchanged." }, "apiKey": { "type": "object", "properties": { "provider": { "type": "string", "description": "API provider name (e.g. openai, anthropic, stripe)" }, "key": { "type": "string", "description": "Encrypted API key" }, "prefix": { "type": "string", "description": "Display prefix for the key (e.g. 'sk-...abc')" }, "rateLimit": { "type": "object", "properties": { "requests": { "type": "integer", "minimum": 0, "description": "Maximum number of requests allowed" }, "window": { "type": "string", "description": "Time window for rate limiting (e.g. '1m', '1h', '1d')" } }, "required": [ "requests", "window" ], "description": "Rate limit configuration for this key" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Optional key expiration timestamp" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Optional scopes or permissions for this key" }, "allowedHosts": { "type": "array", "items": { "type": "string" }, "description": "Hosts this key may be brokered to via server-side use. Fail-closed if empty." }, "authHeader": { "type": "string", "description": "Header the broker injects the key into (default 'Authorization')." }, "authScheme": { "type": "string", "description": "Value prefix before the key (default 'Bearer '; set '' for a raw key, e.g. x-api-key)." } }, "description": "API key patch. Omitted fields keep their stored values (edit allowedHosts without resending the key); a masked echo of `key` counts as unchanged." }, "certificate": { "type": "object", "properties": { "format": { "enum": [ "pem", "p12", "jks" ], "type": "string", "description": "Certificate format" }, "certificate": { "type": "string", "description": "Encrypted certificate content" }, "privateKey": { "type": "string", "description": "Encrypted private key" }, "chain": { "type": "array", "items": { "type": "string" }, "description": "Encrypted certificate chain" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Certificate expiration timestamp" } }, "description": "Certificate patch. Omitted fields keep their stored values; a masked echo of privateKey counts as unchanged." }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Field name" }, "value": { "type": "string", "description": "Field value" }, "type": { "enum": [ "text", "hidden", "boolean" ], "type": "string", "description": "Field display type" } }, "required": [ "name", "value", "type" ], "description": "Custom key-value field attached to a credential" }, "description": "Updated custom fields" }, "favorite": { "type": "boolean", "description": "Updated favorite status" }, "revealPolicy": { "enum": [ "standard", "brokered" ], "type": "string", "description": "Change the reveal policy. Upgrading standard → brokered needs UPDATE access; downgrading brokered → standard requires master-key auth and is audited." } }, "required": [] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique credential identifier" }, "type": { "enum": [ "login", "secure_note", "card", "identity", "oauth_token", "api_key", "certificate" ], "type": "string", "description": "Credential type" }, "name": { "type": "string", "description": "User-defined credential name" }, "notes": { "type": "string", "description": "Free-form notes attached to the credential" }, "login": { "type": "object", "properties": { "username": { "type": "string", "description": "Login username or email" }, "password": { "type": "string", "description": "Login password" }, "uris": { "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string", "description": "URI associated with the credential" }, "match": { "enum": [ "domain", "host", "starts_with", "regex", "never" ], "type": "string", "description": "URI matching strategy for auto-fill" } }, "required": [ "uri" ], "description": "URI entry with matching rules for credential auto-fill" }, "description": "URIs associated with this login" }, "totp": { "type": "string", "description": "TOTP secret for two-factor authentication" } }, "description": "Login credential data, present when type is login" }, "card": { "type": "object", "properties": { "cardholderName": { "type": "string", "description": "Name on the payment card" }, "brand": { "type": "string", "description": "Card brand (e.g. Visa, Mastercard)" }, "number": { "type": "string", "description": "Full card number" }, "expMonth": { "type": "string", "description": "Card expiration month" }, "expYear": { "type": "string", "description": "Card expiration year" }, "code": { "type": "string", "description": "Card security code (CVV/CVC)" } }, "description": "Card credential data, present when type is card" }, "identity": { "type": "object", "properties": { "firstName": { "type": "string", "description": "First name" }, "lastName": { "type": "string", "description": "Last name" }, "email": { "type": "string", "format": "email", "description": "Email address" }, "phone": { "type": "string", "description": "Phone number" }, "address1": { "type": "string", "description": "Street address" }, "city": { "type": "string", "description": "City" }, "state": { "type": "string", "description": "State or province" }, "postalCode": { "type": "string", "description": "Postal or ZIP code" }, "country": { "type": "string", "description": "Country code or name" }, "company": { "type": "string", "description": "Company or organization name" }, "ssn": { "type": "string", "description": "Social security number" } }, "description": "Identity credential data, present when type is identity" }, "oauthToken": { "type": "object", "properties": { "provider": { "type": "string", "description": "OAuth provider name (e.g. google, github, slack)" }, "accessToken": { "type": "string", "description": "Encrypted OAuth access token" }, "refreshToken": { "type": "string", "description": "Encrypted OAuth refresh token" }, "tokenEndpoint": { "type": "string", "description": "OAuth token endpoint URL for refreshing tokens" }, "clientId": { "type": "string", "description": "Encrypted OAuth client ID" }, "clientSecret": { "type": "string", "description": "Encrypted OAuth client secret" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "OAuth scopes granted to this token" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Token expiration timestamp" }, "autoRefresh": { "default": true, "type": "boolean", "description": "Whether to automatically refresh the token before expiry" }, "allowedHosts": { "type": "array", "items": { "type": "string" }, "description": "Hosts this token may be brokered to via server-side use. Fail-closed if empty." } }, "required": [ "provider", "accessToken", "refreshToken", "tokenEndpoint", "clientId", "scopes", "expiresAt" ], "description": "OAuth token data, present when type is oauth_token" }, "apiKey": { "type": "object", "properties": { "provider": { "type": "string", "description": "API provider name (e.g. openai, anthropic, stripe)" }, "key": { "type": "string", "description": "Encrypted API key" }, "prefix": { "type": "string", "description": "Display prefix for the key (e.g. 'sk-...abc')" }, "rateLimit": { "type": "object", "properties": { "requests": { "type": "integer", "minimum": 0, "description": "Maximum number of requests allowed" }, "window": { "type": "string", "description": "Time window for rate limiting (e.g. '1m', '1h', '1d')" } }, "required": [ "requests", "window" ], "description": "Rate limit configuration for this key" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Optional key expiration timestamp" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Optional scopes or permissions for this key" }, "allowedHosts": { "type": "array", "items": { "type": "string" }, "description": "Hosts this key may be brokered to via server-side use. Fail-closed if empty." }, "authHeader": { "type": "string", "description": "Header the broker injects the key into (default 'Authorization')." }, "authScheme": { "type": "string", "description": "Value prefix before the key (default 'Bearer '; set '' for a raw key, e.g. x-api-key)." } }, "required": [ "provider", "key" ], "description": "API key data, present when type is api_key" }, "certificate": { "type": "object", "properties": { "format": { "enum": [ "pem", "p12", "jks" ], "type": "string", "description": "Certificate format" }, "certificate": { "type": "string", "description": "Encrypted certificate content" }, "privateKey": { "type": "string", "description": "Encrypted private key" }, "chain": { "type": "array", "items": { "type": "string" }, "description": "Encrypted certificate chain" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Certificate expiration timestamp" } }, "required": [ "format", "certificate", "privateKey", "expiresAt" ], "description": "Certificate data, present when type is certificate" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Field name" }, "value": { "type": "string", "description": "Field value" }, "type": { "enum": [ "text", "hidden", "boolean" ], "type": "string", "description": "Field display type" } }, "required": [ "name", "value", "type" ], "description": "Custom key-value field attached to a credential" }, "description": "Custom fields attached to the credential" }, "favorite": { "type": "boolean", "description": "Whether the credential is marked as a favorite" }, "folderId": { "type": "string", "description": "Folder the credential belongs to" }, "organizationId": { "type": "string", "description": "Organization the credential is scoped to" }, "collectionIds": { "type": "array", "items": { "type": "string" }, "description": "Collections the credential is shared with" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the credential was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the credential was last updated" }, "revealPolicy": { "enum": [ "standard", "brokered" ], "type": "string", "description": "Reveal policy governing whether plaintext may be returned (default 'standard')" } }, "required": [ "id", "type", "name", "favorite", "createdAt", "updatedAt" ], "description": "Full credential record returned from the vault" } } } } } }, "delete": { "operationId": "vault.delete", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Credential identifier" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier. Optional when using an agent API key (resolved automatically); required when using a master key." }, "reveal": { "default": false, "type": "boolean", "description": "Return unmasked plaintext fields. Requires master key auth. Audit-logged as 'access_reveal'." } }, "required": [], "description": "Input for identifying a specific credential in an agent vault" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true } }, "required": [ "success" ] } } } } } } }, "/vault/credentials/{id}/use": { "post": { "operationId": "vault.use", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Credential ID to broker the call with" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "description": "Agent ID (optional when using an agent API key)" }, "method": { "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD" ], "type": "string", "description": "HTTP method for the outbound call" }, "url": { "type": "string", "format": "uri", "description": "Absolute https:// URL. Its host MUST be on the credential's allowlist." }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Extra request headers. Any Authorization / auth header is ignored and replaced by the credential." }, "body": { "type": "string", "description": "Raw request body (encode JSON yourself)." } }, "required": [ "method", "url" ], "description": "Make an outbound HTTP call with the credential attached server-side. The plaintext secret is never returned — the agent only sees the upstream response." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "Upstream HTTP status code" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Upstream response headers" }, "body": { "type": "string", "description": "Upstream response body (UTF-8, size-capped)" }, "truncated": { "type": "boolean", "description": "True if the response body exceeded the size cap and was cut off" } }, "required": [ "status", "headers", "body", "truncated" ], "description": "The upstream response, scrubbed of the injected credential." } } } } } } }, "/vault/search": { "get": { "operationId": "vault.search", "parameters": [ { "name": "agentId", "in": "query", "schema": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier. Optional when using an agent API key (resolved automatically); required when using a master key." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "search", "in": "query", "schema": { "type": "string", "description": "Free-text search query" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "q", "in": "query", "schema": { "type": "string", "description": "Alias for `search`" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "type", "in": "query", "schema": { "enum": [ "login", "secure_note", "card", "identity", "oauth_token", "api_key", "certificate" ], "type": "string", "description": "Filter results by credential type" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique credential identifier" }, "type": { "enum": [ "login", "secure_note", "card", "identity", "oauth_token", "api_key", "certificate" ], "type": "string", "description": "Credential type" }, "name": { "type": "string", "description": "User-defined credential name" }, "notes": { "type": "string", "description": "Free-form notes attached to the credential" }, "login": { "type": "object", "properties": { "username": { "type": "string", "description": "Login username or email" }, "password": { "type": "string", "description": "Login password" }, "uris": { "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string", "description": "URI associated with the credential" }, "match": { "enum": [ "domain", "host", "starts_with", "regex", "never" ], "type": "string", "description": "URI matching strategy for auto-fill" } }, "required": [ "uri" ], "description": "URI entry with matching rules for credential auto-fill" }, "description": "URIs associated with this login" }, "totp": { "type": "string", "description": "TOTP secret for two-factor authentication" } }, "description": "Login credential data, present when type is login" }, "card": { "type": "object", "properties": { "cardholderName": { "type": "string", "description": "Name on the payment card" }, "brand": { "type": "string", "description": "Card brand (e.g. Visa, Mastercard)" }, "number": { "type": "string", "description": "Full card number" }, "expMonth": { "type": "string", "description": "Card expiration month" }, "expYear": { "type": "string", "description": "Card expiration year" }, "code": { "type": "string", "description": "Card security code (CVV/CVC)" } }, "description": "Card credential data, present when type is card" }, "identity": { "type": "object", "properties": { "firstName": { "type": "string", "description": "First name" }, "lastName": { "type": "string", "description": "Last name" }, "email": { "type": "string", "format": "email", "description": "Email address" }, "phone": { "type": "string", "description": "Phone number" }, "address1": { "type": "string", "description": "Street address" }, "city": { "type": "string", "description": "City" }, "state": { "type": "string", "description": "State or province" }, "postalCode": { "type": "string", "description": "Postal or ZIP code" }, "country": { "type": "string", "description": "Country code or name" }, "company": { "type": "string", "description": "Company or organization name" }, "ssn": { "type": "string", "description": "Social security number" } }, "description": "Identity credential data, present when type is identity" }, "oauthToken": { "type": "object", "properties": { "provider": { "type": "string", "description": "OAuth provider name (e.g. google, github, slack)" }, "accessToken": { "type": "string", "description": "Encrypted OAuth access token" }, "refreshToken": { "type": "string", "description": "Encrypted OAuth refresh token" }, "tokenEndpoint": { "type": "string", "description": "OAuth token endpoint URL for refreshing tokens" }, "clientId": { "type": "string", "description": "Encrypted OAuth client ID" }, "clientSecret": { "type": "string", "description": "Encrypted OAuth client secret" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "OAuth scopes granted to this token" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Token expiration timestamp" }, "autoRefresh": { "default": true, "type": "boolean", "description": "Whether to automatically refresh the token before expiry" }, "allowedHosts": { "type": "array", "items": { "type": "string" }, "description": "Hosts this token may be brokered to via server-side use. Fail-closed if empty." } }, "required": [ "provider", "accessToken", "refreshToken", "tokenEndpoint", "clientId", "scopes", "expiresAt" ], "description": "OAuth token data, present when type is oauth_token" }, "apiKey": { "type": "object", "properties": { "provider": { "type": "string", "description": "API provider name (e.g. openai, anthropic, stripe)" }, "key": { "type": "string", "description": "Encrypted API key" }, "prefix": { "type": "string", "description": "Display prefix for the key (e.g. 'sk-...abc')" }, "rateLimit": { "type": "object", "properties": { "requests": { "type": "integer", "minimum": 0, "description": "Maximum number of requests allowed" }, "window": { "type": "string", "description": "Time window for rate limiting (e.g. '1m', '1h', '1d')" } }, "required": [ "requests", "window" ], "description": "Rate limit configuration for this key" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Optional key expiration timestamp" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Optional scopes or permissions for this key" }, "allowedHosts": { "type": "array", "items": { "type": "string" }, "description": "Hosts this key may be brokered to via server-side use. Fail-closed if empty." }, "authHeader": { "type": "string", "description": "Header the broker injects the key into (default 'Authorization')." }, "authScheme": { "type": "string", "description": "Value prefix before the key (default 'Bearer '; set '' for a raw key, e.g. x-api-key)." } }, "required": [ "provider", "key" ], "description": "API key data, present when type is api_key" }, "certificate": { "type": "object", "properties": { "format": { "enum": [ "pem", "p12", "jks" ], "type": "string", "description": "Certificate format" }, "certificate": { "type": "string", "description": "Encrypted certificate content" }, "privateKey": { "type": "string", "description": "Encrypted private key" }, "chain": { "type": "array", "items": { "type": "string" }, "description": "Encrypted certificate chain" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Certificate expiration timestamp" } }, "required": [ "format", "certificate", "privateKey", "expiresAt" ], "description": "Certificate data, present when type is certificate" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Field name" }, "value": { "type": "string", "description": "Field value" }, "type": { "enum": [ "text", "hidden", "boolean" ], "type": "string", "description": "Field display type" } }, "required": [ "name", "value", "type" ], "description": "Custom key-value field attached to a credential" }, "description": "Custom fields attached to the credential" }, "favorite": { "type": "boolean", "description": "Whether the credential is marked as a favorite" }, "folderId": { "type": "string", "description": "Folder the credential belongs to" }, "organizationId": { "type": "string", "description": "Organization the credential is scoped to" }, "collectionIds": { "type": "array", "items": { "type": "string" }, "description": "Collections the credential is shared with" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the credential was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the credential was last updated" }, "revealPolicy": { "enum": [ "standard", "brokered" ], "type": "string", "description": "Reveal policy governing whether plaintext may be returned (default 'standard')" } }, "required": [ "id", "type", "name", "favorite", "createdAt", "updatedAt" ], "description": "Full credential record returned from the vault" }, "description": "List of credentials matching the query" } }, "required": [ "items" ], "description": "List of vault credentials" } } } } } } }, "/vault/generate-password": { "post": { "operationId": "vault.generatePassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier. Optional when using an agent API key (resolved automatically); required when using a master key." }, "length": { "type": "integer", "minimum": 4, "maximum": 128, "description": "Desired password length (4-128 characters)" }, "uppercase": { "type": "boolean", "description": "Include uppercase letters" }, "lowercase": { "type": "boolean", "description": "Include lowercase letters" }, "number": { "type": "boolean", "description": "Include numeric digits" }, "special": { "type": "boolean", "description": "Include special characters" } }, "description": "Input for generating a random password" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "description": "The generated password" } }, "required": [ "password" ], "description": "Generated password result" } } } } } } }, "/vault/totp/{id}": { "get": { "operationId": "vault.getTotp", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Credential identifier" } }, { "name": "agentId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier. Optional when using an agent API key (resolved automatically); required when using a master key." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "reveal", "in": "query", "required": false, "schema": { "default": false, "type": "boolean", "description": "Return unmasked plaintext fields. Requires master key auth. Audit-logged as 'access_reveal'." }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Current TOTP code" }, "period": { "type": "integer", "minimum": 0, "description": "Time period in seconds before the code rotates" } }, "required": [ "code", "period" ], "description": "Time-based one-time password output" } } } } } } }, "/vault/status": { "get": { "operationId": "vault.status", "parameters": [ { "name": "agentId", "in": "query", "schema": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier. Optional when using an agent API key (resolved automatically); required when using a master key." }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "serverUrl": { "type": "string", "description": "Vault backend server URL" }, "lastSync": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp of the last synchronization" }, "status": { "enum": [ "unlocked", "locked", "unauthenticated" ], "type": "string", "description": "Current vault lock state" }, "defaultRevealPolicy": { "enum": [ "standard", "brokered" ], "type": "string", "description": "Organization default applied when a new credential does not request a reveal policy" } }, "required": [ "serverUrl", "lastSync", "status", "defaultRevealPolicy" ], "description": "Current vault connection and lock status" } } } } } } }, "/vault/sync": { "post": { "operationId": "vault.sync", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier. Optional when using an agent API key (resolved automatically); required when using a master key." } }, "description": "Input scoped to an agent. agentId is optional when using an agent API key." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true } }, "required": [ "success" ] } } } } } } }, "/vault/audit": { "get": { "operationId": "vault.audit", "parameters": [ { "name": "credentialId", "in": "query", "schema": { "type": "string", "description": "Filter by credential ID" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "agentId", "in": "query", "schema": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Filter by agent ID" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "action", "in": "query", "schema": { "type": "string", "description": "Filter by action type" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "Filter entries after this timestamp" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "Filter entries before this timestamp" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Cursor for pagination" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum entries to return" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique audit log entry identifier" }, "credentialId": { "type": "string", "description": "Credential that was accessed or modified" }, "agentId": { "type": "string", "description": "Agent that owns the credential" }, "orgId": { "type": "string", "description": "Organization the credential belongs to" }, "action": { "type": "string", "description": "Action performed (e.g. access, store, delete, refresh, refresh_failed)" }, "actor": { "type": "string", "description": "Who performed the action (e.g. user ID, 'system')" }, "ipAddress": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IP address of the actor" }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Additional metadata about the action" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the action occurred" } }, "required": [ "id", "credentialId", "agentId", "orgId", "action", "actor", "createdAt" ], "description": "Audit log entry for credential access and modifications" }, "description": "List of audit log entries" }, "pagination": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "Cursor to pass as the `cursor` parameter to retrieve the next page, or null if no more results" }, "hasMore": { "type": "boolean", "description": "Whether additional pages of results are available" } }, "required": [ "nextCursor", "hasMore" ], "description": "Cursor-based pagination metadata" } }, "required": [ "items", "pagination" ], "description": "Paginated list of credential audit log entries" } } } } } } }, "/vault/credential-requests": { "post": { "operationId": "vault.credentialRequestCreate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier. Optional when using an agent API key (resolved automatically); required when using a master key." }, "type": { "enum": [ "login", "secure_note", "card", "identity", "oauth_token", "api_key", "certificate" ], "type": "string", "description": "Type of credential the human is asked to provide" }, "name": { "type": "string", "minLength": 1, "description": "Display name for the credential to be created" }, "reason": { "type": "string", "minLength": 1, "description": "Human-readable explanation of why the credential is needed, shown to the owner" }, "ttlSeconds": { "default": 900, "type": "integer", "minimum": 60, "maximum": 3600, "description": "Request TTL in seconds (60-3600, default 900 = 15 minutes)" }, "notifyOwner": { "default": false, "type": "boolean", "description": "The MCP layer sets this true ONLY on the no-elicitation fallback path; the api emails the fillUrl to the org owner iff true." } }, "required": [ "type", "name", "reason" ], "description": "Input for creating a human-in-the-loop credential request — the secret is never passed as a tool argument; a human supplies it out-of-band." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique credential request identifier" }, "fillUrl": { "type": "string", "description": "Token-gated URL where the human submits the secret (fallback / URL-mode path)" }, "status": { "enum": [ "PENDING", "FULFILLED", "EXPIRED", "DECLINED", "CANCELLED" ], "type": "string", "description": "Current request status" }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the request expires and the fill URL stops working" }, "emailSent": { "type": "boolean", "description": "Whether the fill URL was emailed to the agent owner (false if no humanEmail is set)" }, "credentialId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolved vault credential ID when the inline path fulfills synchronously; null otherwise" } }, "required": [ "requestId", "fillUrl", "status", "expiresAt", "emailSent" ], "description": "Created credential request — carries the fill URL and pending status, or a synchronously resolved reference" } } } } } }, "get": { "operationId": "vault.credentialRequestList", "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Opaque cursor from a previous response to fetch the next page" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of items to return per page (1–100, default 20)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "agentId", "in": "query", "schema": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier. Optional when using an agent API key (resolved automatically); required when using a master key." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "status", "in": "query", "schema": { "enum": [ "PENDING", "FULFILLED", "EXPIRED", "DECLINED", "CANCELLED" ], "type": "string", "description": "Filter by lifecycle status" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Credential request identifier" }, "agentId": { "type": "string", "description": "Agent the credential was requested for" }, "type": { "enum": [ "login", "secure_note", "card", "identity", "oauth_token", "api_key", "certificate" ], "type": "string", "description": "Credential type being collected" }, "name": { "type": "string", "description": "Display name the agent chose" }, "reason": { "type": "string", "description": "Why the agent asked — shown to the owner" }, "status": { "enum": [ "PENDING", "FULFILLED", "EXPIRED", "DECLINED", "CANCELLED" ], "type": "string", "description": "Lifecycle status (lazy-expired)" }, "fillUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Token-gated fill URL — present only while PENDING" }, "credentialId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Vault credential reference once FULFILLED" }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the request stops accepting a fill" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the agent created the request" } }, "required": [ "requestId", "agentId", "type", "name", "reason", "status", "fillUrl", "credentialId", "expiresAt", "createdAt" ], "description": "Credential request summary for the org view" }, "description": "Credential requests, newest first" }, "pagination": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "Cursor to pass as the `cursor` parameter to retrieve the next page, or null if no more results" }, "hasMore": { "type": "boolean", "description": "Whether additional pages of results are available" } }, "required": [ "nextCursor", "hasMore" ], "description": "Cursor-based pagination metadata" } }, "required": [ "items", "pagination" ], "description": "Paginated credential requests" } } } } } } }, "/vault/credential-requests/{requestId}": { "get": { "operationId": "vault.credentialRequestStatus", "parameters": [ { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string", "description": "Credential request identifier" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "enum": [ "PENDING", "FULFILLED", "EXPIRED", "DECLINED", "CANCELLED" ], "type": "string", "description": "Current request status" }, "credentialId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Vault credential ID — set once the request is FULFILLED, null otherwise" }, "maskedPreview": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Masked preview of the submitted secret (e.g. ****1234) so the agent can confirm which credential arrived without seeing it; null until FULFILLED" } }, "required": [ "status", "credentialId", "maskedPreview" ], "description": "Current status of a credential request, polled by the agent until FULFILLED" } } } } } } }, "/vault/credential-requests/{requestId}/cancel": { "post": { "operationId": "vault.credentialRequestCancel", "parameters": [ { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string", "description": "Credential request identifier" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "Input for identifying a specific credential request" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "enum": [ "PENDING", "FULFILLED", "EXPIRED", "DECLINED", "CANCELLED" ], "type": "string", "description": "Resulting status after cancellation (CANCELLED)" } }, "required": [ "status" ], "description": "Result of cancelling a credential request — invalidates the fill URL" } } } } } } }, "/vault/share": { "post": { "operationId": "vault.share", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "credentialId": { "type": "string", "description": "ID of the credential to share" }, "sourceAgentId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent that owns the credential" }, "targetAgentId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent to share the credential with" }, "permission": { "default": "READ", "enum": [ "READ", "USE", "MANAGE" ], "type": "string", "description": "Permission level for the share" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Optional expiration time for the share" }, "expiresInSeconds": { "type": "integer", "minimum": 1, "maximum": 31536000, "description": "Relative TTL in seconds — alternative to expiresAt. Max 1 year." } }, "required": [ "credentialId", "sourceAgentId", "targetAgentId" ], "description": "Input for sharing a credential between agents" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique share record identifier" }, "credentialId": { "type": "string", "description": "Shared credential identifier" }, "orgId": { "type": "string", "description": "Organization identifier" }, "sourceAgentId": { "type": "string", "description": "Agent that owns the credential" }, "targetAgentId": { "type": "string", "description": "Agent that received access" }, "permission": { "enum": [ "READ", "USE", "MANAGE" ], "type": "string", "description": "Permission level" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the share expires" }, "grantedBy": { "type": "string", "description": "Who created the share" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the share was revoked, if applicable" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the share was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the share was last updated" } }, "required": [ "id", "credentialId", "orgId", "sourceAgentId", "targetAgentId", "permission", "expiresAt", "grantedBy", "revokedAt", "createdAt", "updatedAt" ], "description": "Credential share record details" } } } } } } }, "/vault/shares": { "get": { "operationId": "vault.listShares", "parameters": [ { "name": "agentId", "in": "query", "schema": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier. Optional when using an agent API key (resolved automatically); required when using a master key." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "direction", "in": "query", "schema": { "default": "received", "enum": [ "granted", "received" ], "type": "string", "description": "Filter by share direction" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Cursor for pagination" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum entries to return" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique share record identifier" }, "credentialId": { "type": "string", "description": "Shared credential identifier" }, "orgId": { "type": "string", "description": "Organization identifier" }, "sourceAgentId": { "type": "string", "description": "Agent that owns the credential" }, "targetAgentId": { "type": "string", "description": "Agent that received access" }, "permission": { "enum": [ "READ", "USE", "MANAGE" ], "type": "string", "description": "Permission level" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the share expires" }, "grantedBy": { "type": "string", "description": "Who created the share" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the share was revoked, if applicable" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the share was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the share was last updated" } }, "required": [ "id", "credentialId", "orgId", "sourceAgentId", "targetAgentId", "permission", "expiresAt", "grantedBy", "revokedAt", "createdAt", "updatedAt" ], "description": "Credential share record details" }, "description": "List of credential shares" }, "pagination": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "Cursor to pass as the `cursor` parameter to retrieve the next page, or null if no more results" }, "hasMore": { "type": "boolean", "description": "Whether additional pages of results are available" } }, "required": [ "nextCursor", "hasMore" ], "description": "Cursor-based pagination metadata" } }, "required": [ "items", "pagination" ], "description": "Paginated list of credential shares" } } } } } } }, "/vault/share/revoke": { "post": { "operationId": "vault.revokeShare", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shareId": { "type": "string", "description": "ID of the share to revoke" }, "agentId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier. Optional when using an agent API key (resolved automatically); required when using a master key." } }, "required": [ "shareId" ], "description": "Input for revoking a credential share" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true } }, "required": [ "success" ] } } } } } } }, "/vault/token": { "post": { "operationId": "vault.createToken", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier. Optional when using an agent API key (resolved automatically); required when using a master key." }, "credentialId": { "type": "string", "description": "Credential the token grants access to" }, "scope": { "default": "autofill", "enum": [ "autofill", "proxy", "export" ], "type": "string", "description": "What the token allows" }, "taskId": { "type": "string", "description": "Optional task/conversation binding for traceability" }, "ttlSeconds": { "default": 60, "type": "integer", "minimum": 10, "maximum": 3600, "description": "Token TTL in seconds (10-3600, default 60)" } }, "required": [ "credentialId" ], "description": "Input for creating an ephemeral scoped vault token" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "The ephemeral token (vtk_) — only returned at creation time" }, "credentialId": { "type": "string", "description": "Credential the token grants access to" }, "scope": { "enum": [ "autofill", "proxy", "export" ], "type": "string", "description": "Token scope" }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the token expires" } }, "required": [ "token", "credentialId", "scope", "expiresAt" ], "description": "Created vault token (the raw token is only available at creation time)" } } } } } } }, "/vault/token/exchange": { "post": { "operationId": "vault.exchangeTokenForInjection", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "The vault token (vtk_) to exchange for credential data" } }, "required": [ "token" ], "description": "Input for exchanging a vault token for credential data" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique credential identifier" }, "type": { "enum": [ "login", "secure_note", "card", "identity", "oauth_token", "api_key", "certificate" ], "type": "string", "description": "Credential type" }, "name": { "type": "string", "description": "User-defined credential name" }, "notes": { "type": "string", "description": "Free-form notes attached to the credential" }, "login": { "type": "object", "properties": { "username": { "type": "string", "description": "Login username or email" }, "password": { "type": "string", "description": "Login password" }, "uris": { "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string", "description": "URI associated with the credential" }, "match": { "enum": [ "domain", "host", "starts_with", "regex", "never" ], "type": "string", "description": "URI matching strategy for auto-fill" } }, "required": [ "uri" ], "description": "URI entry with matching rules for credential auto-fill" }, "description": "URIs associated with this login" }, "totp": { "type": "string", "description": "TOTP secret for two-factor authentication" } }, "description": "Login credential data, present when type is login" }, "card": { "type": "object", "properties": { "cardholderName": { "type": "string", "description": "Name on the payment card" }, "brand": { "type": "string", "description": "Card brand (e.g. Visa, Mastercard)" }, "number": { "type": "string", "description": "Full card number" }, "expMonth": { "type": "string", "description": "Card expiration month" }, "expYear": { "type": "string", "description": "Card expiration year" }, "code": { "type": "string", "description": "Card security code (CVV/CVC)" } }, "description": "Card credential data, present when type is card" }, "identity": { "type": "object", "properties": { "firstName": { "type": "string", "description": "First name" }, "lastName": { "type": "string", "description": "Last name" }, "email": { "type": "string", "format": "email", "description": "Email address" }, "phone": { "type": "string", "description": "Phone number" }, "address1": { "type": "string", "description": "Street address" }, "city": { "type": "string", "description": "City" }, "state": { "type": "string", "description": "State or province" }, "postalCode": { "type": "string", "description": "Postal or ZIP code" }, "country": { "type": "string", "description": "Country code or name" }, "company": { "type": "string", "description": "Company or organization name" }, "ssn": { "type": "string", "description": "Social security number" } }, "description": "Identity credential data, present when type is identity" }, "oauthToken": { "type": "object", "properties": { "provider": { "type": "string", "description": "OAuth provider name (e.g. google, github, slack)" }, "accessToken": { "type": "string", "description": "Encrypted OAuth access token" }, "refreshToken": { "type": "string", "description": "Encrypted OAuth refresh token" }, "tokenEndpoint": { "type": "string", "description": "OAuth token endpoint URL for refreshing tokens" }, "clientId": { "type": "string", "description": "Encrypted OAuth client ID" }, "clientSecret": { "type": "string", "description": "Encrypted OAuth client secret" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "OAuth scopes granted to this token" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Token expiration timestamp" }, "autoRefresh": { "default": true, "type": "boolean", "description": "Whether to automatically refresh the token before expiry" }, "allowedHosts": { "type": "array", "items": { "type": "string" }, "description": "Hosts this token may be brokered to via server-side use. Fail-closed if empty." } }, "required": [ "provider", "accessToken", "refreshToken", "tokenEndpoint", "clientId", "scopes", "expiresAt" ], "description": "OAuth token data, present when type is oauth_token" }, "apiKey": { "type": "object", "properties": { "provider": { "type": "string", "description": "API provider name (e.g. openai, anthropic, stripe)" }, "key": { "type": "string", "description": "Encrypted API key" }, "prefix": { "type": "string", "description": "Display prefix for the key (e.g. 'sk-...abc')" }, "rateLimit": { "type": "object", "properties": { "requests": { "type": "integer", "minimum": 0, "description": "Maximum number of requests allowed" }, "window": { "type": "string", "description": "Time window for rate limiting (e.g. '1m', '1h', '1d')" } }, "required": [ "requests", "window" ], "description": "Rate limit configuration for this key" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Optional key expiration timestamp" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Optional scopes or permissions for this key" }, "allowedHosts": { "type": "array", "items": { "type": "string" }, "description": "Hosts this key may be brokered to via server-side use. Fail-closed if empty." }, "authHeader": { "type": "string", "description": "Header the broker injects the key into (default 'Authorization')." }, "authScheme": { "type": "string", "description": "Value prefix before the key (default 'Bearer '; set '' for a raw key, e.g. x-api-key)." } }, "required": [ "provider", "key" ], "description": "API key data, present when type is api_key" }, "certificate": { "type": "object", "properties": { "format": { "enum": [ "pem", "p12", "jks" ], "type": "string", "description": "Certificate format" }, "certificate": { "type": "string", "description": "Encrypted certificate content" }, "privateKey": { "type": "string", "description": "Encrypted private key" }, "chain": { "type": "array", "items": { "type": "string" }, "description": "Encrypted certificate chain" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Certificate expiration timestamp" } }, "required": [ "format", "certificate", "privateKey", "expiresAt" ], "description": "Certificate data, present when type is certificate" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Field name" }, "value": { "type": "string", "description": "Field value" }, "type": { "enum": [ "text", "hidden", "boolean" ], "type": "string", "description": "Field display type" } }, "required": [ "name", "value", "type" ], "description": "Custom key-value field attached to a credential" }, "description": "Custom fields attached to the credential" }, "favorite": { "type": "boolean", "description": "Whether the credential is marked as a favorite" }, "folderId": { "type": "string", "description": "Folder the credential belongs to" }, "organizationId": { "type": "string", "description": "Organization the credential is scoped to" }, "collectionIds": { "type": "array", "items": { "type": "string" }, "description": "Collections the credential is shared with" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the credential was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the credential was last updated" }, "revealPolicy": { "enum": [ "standard", "brokered" ], "type": "string", "description": "Reveal policy governing whether plaintext may be returned (default 'standard')" } }, "required": [ "id", "type", "name", "favorite", "createdAt", "updatedAt" ], "description": "Full credential record returned from the vault" } } } } } } }, "/vault/token/revoke": { "post": { "operationId": "vault.revokeTokens", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier. Optional when using an agent API key (resolved automatically); required when using a master key." }, "credentialId": { "type": "string", "description": "Credential the token was issued for" } }, "required": [ "credentialId" ], "description": "Input for revoking all active tokens for a credential" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "revoked": { "type": "number" } }, "required": [ "success", "revoked" ] } } } } } } }, "/vault/oauth/apps": { "get": { "operationId": "vault.oauthListApps", "parameters": [ { "name": "category", "in": "query", "schema": { "type": "string", "description": "Filter apps by category" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique app definition identifier" }, "slug": { "type": "string", "description": "URL-safe app slug (e.g. google, github, slack)" }, "name": { "type": "string", "description": "Human-readable app name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Short description of the service" }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Service logo URL" }, "authMethod": { "enum": [ "OAUTH2", "OAUTH2_PKCE", "API_KEY", "BASIC", "BEARER" ], "type": "string", "description": "Authentication method" }, "defaultScopes": { "type": "array", "items": { "type": "string" }, "description": "Default OAuth scopes" }, "requiresPkce": { "type": "boolean", "description": "Whether PKCE is required" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "App category (productivity, developer, etc.)" }, "isManaged": { "type": "boolean", "description": "Whether Anima provides managed OAuth credentials" }, "isActive": { "type": "boolean", "description": "Whether the app is currently available" } }, "required": [ "id", "slug", "name", "description", "iconUrl", "authMethod", "defaultScopes", "requiresPkce", "category", "isManaged", "isActive" ], "description": "OAuth app definition (public info, no client secrets)" }, "description": "Available OAuth app definitions" } }, "required": [ "items" ], "description": "List of available OAuth app definitions" } } } } } } }, "/vault/oauth/apps/{slug}": { "get": { "operationId": "vault.oauthGetApp", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "description": "App slug to look up (e.g. google, github, slack)" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique app definition identifier" }, "slug": { "type": "string", "description": "URL-safe app slug (e.g. google, github, slack)" }, "name": { "type": "string", "description": "Human-readable app name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Short description of the service" }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Service logo URL" }, "authMethod": { "enum": [ "OAUTH2", "OAUTH2_PKCE", "API_KEY", "BASIC", "BEARER" ], "type": "string", "description": "Authentication method" }, "defaultScopes": { "type": "array", "items": { "type": "string" }, "description": "Default OAuth scopes" }, "requiresPkce": { "type": "boolean", "description": "Whether PKCE is required" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "App category (productivity, developer, etc.)" }, "isManaged": { "type": "boolean", "description": "Whether Anima provides managed OAuth credentials" }, "isActive": { "type": "boolean", "description": "Whether the app is currently available" } }, "required": [ "id", "slug", "name", "description", "iconUrl", "authMethod", "defaultScopes", "requiresPkce", "category", "isManaged", "isActive" ], "description": "OAuth app definition (public info, no client secrets)" } } } } } } }, "/vault/oauth/link": { "post": { "operationId": "vault.oauthCreateLink", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier. Optional when using an agent API key (resolved automatically); required when using a master key." }, "userId": { "type": "string", "description": "End-user ID for multi-tenant scoping" }, "appSlug": { "type": "string", "description": "App slug to create a link for (e.g. google, github)" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Override default scopes" }, "callbackUrl": { "type": "string", "format": "uri", "description": "URL to redirect to after auth completes" }, "customAppId": { "type": "string", "description": "Use a custom OAuth app (BYOA)" } }, "required": [ "appSlug" ], "description": "Input for creating a Connect Link — a hosted auth URL" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "linkUrl": { "type": "string", "description": "Full Connect Link URL for the user to open" }, "token": { "type": "string", "description": "Link token for status polling" }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the link expires (10 minutes)" } }, "required": [ "linkUrl", "token", "expiresAt" ], "description": "Created Connect Link for zero-code authentication" } } } } } } }, "/vault/oauth/link/{token}": { "get": { "operationId": "vault.oauthLinkStatus", "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "description": "Connect Link token to check status for" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "enum": [ "PENDING", "COMPLETED", "EXPIRED", "FAILED" ], "type": "string", "description": "Link status" }, "connectedAccountId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Connected account ID (set when COMPLETED)" } }, "required": [ "status", "connectedAccountId" ], "description": "Current status of a Connect Link" } } } } } } }, "/vault/oauth/accounts": { "get": { "operationId": "vault.oauthListAccounts", "parameters": [ { "name": "agentId", "in": "query", "schema": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier. Optional when using an agent API key (resolved automatically); required when using a master key." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "userId", "in": "query", "schema": { "type": "string", "description": "Filter by end-user ID (multi-tenant)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "appSlug", "in": "query", "schema": { "type": "string", "description": "Filter by app slug" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "status", "in": "query", "schema": { "enum": [ "PENDING", "ACTIVE", "EXPIRED", "REFRESHING", "FAILED", "REVOKED" ], "type": "string", "description": "Filter by status" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique connected account identifier" }, "agentId": { "type": "string", "description": "Agent that owns this connection" }, "userId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "End-user this connection belongs to (multi-tenant)" }, "appDefinitionId": { "type": "string", "description": "OAuth app definition ID" }, "appSlug": { "type": "string", "description": "App slug for easy reference" }, "appName": { "type": "string", "description": "Human-readable app name" }, "appIconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "App icon URL" }, "customAppId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom OAuth app ID (if BYOA)" }, "grantedScopes": { "type": "array", "items": { "type": "string" }, "description": "Scopes granted by the user" }, "accountLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-defined label for this connection" }, "accountEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Account email from the provider" }, "status": { "enum": [ "PENDING", "ACTIVE", "EXPIRED", "REFRESHING", "FAILED", "REVOKED" ], "type": "string", "description": "Connection status" }, "statusMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Error message if status is FAILED" }, "tokenExpiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the access token expires" }, "lastRefreshedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the token was last refreshed" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the connection was established" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the connection was last updated" } }, "required": [ "id", "agentId", "userId", "appDefinitionId", "appSlug", "appName", "appIconUrl", "customAppId", "grantedScopes", "accountLabel", "accountEmail", "status", "statusMessage", "tokenExpiresAt", "lastRefreshedAt", "createdAt", "updatedAt" ], "description": "Connected OAuth account details" }, "description": "Connected OAuth accounts" } }, "required": [ "items" ], "description": "List of connected OAuth accounts" } } } } } } }, "/vault/oauth/accounts/{accountId}": { "delete": { "operationId": "vault.oauthDisconnect", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "description": "Connected account ID to disconnect" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier. Optional when using an agent API key (resolved automatically); required when using a master key." } }, "required": [], "description": "Input for disconnecting an OAuth account" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true } }, "required": [ "success" ] } } } } } } }, "/vault/oauth/require-auth": { "post": { "operationId": "vault.oauthRequireAuth", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier. Optional when using an agent API key (resolved automatically); required when using a master key." }, "userId": { "type": "string", "description": "End-user ID for multi-tenant scoping" }, "appSlug": { "type": "string", "description": "App slug to check authentication for" } }, "required": [ "appSlug" ], "description": "Input for checking if a service is authenticated and getting a Connect Link if not" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "authenticated": { "type": "boolean", "description": "Whether the service is currently authenticated" }, "connectedAccount": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Unique connected account identifier" }, "agentId": { "type": "string", "description": "Agent that owns this connection" }, "userId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "End-user this connection belongs to (multi-tenant)" }, "appDefinitionId": { "type": "string", "description": "OAuth app definition ID" }, "appSlug": { "type": "string", "description": "App slug for easy reference" }, "appName": { "type": "string", "description": "Human-readable app name" }, "appIconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "App icon URL" }, "customAppId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom OAuth app ID (if BYOA)" }, "grantedScopes": { "type": "array", "items": { "type": "string" }, "description": "Scopes granted by the user" }, "accountLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-defined label for this connection" }, "accountEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Account email from the provider" }, "status": { "enum": [ "PENDING", "ACTIVE", "EXPIRED", "REFRESHING", "FAILED", "REVOKED" ], "type": "string", "description": "Connection status" }, "statusMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Error message if status is FAILED" }, "tokenExpiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the access token expires" }, "lastRefreshedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the token was last refreshed" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the connection was established" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the connection was last updated" } }, "required": [ "id", "agentId", "userId", "appDefinitionId", "appSlug", "appName", "appIconUrl", "customAppId", "grantedScopes", "accountLabel", "accountEmail", "status", "statusMessage", "tokenExpiresAt", "lastRefreshedAt", "createdAt", "updatedAt" ], "description": "Connected OAuth account details" }, { "type": "null" } ], "description": "Connected account details (if authenticated)" }, "connectLinkUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Connect Link URL to authenticate (if not authenticated)" } }, "required": [ "authenticated", "connectedAccount", "connectLinkUrl" ], "description": "Authentication status and Connect Link for a service" } } } } } } }, "/vault/oauth/apps/{appSlug}/custom": { "post": { "operationId": "vault.oauthCreateCustomApp", "parameters": [ { "name": "appSlug", "in": "path", "required": true, "schema": { "type": "string", "description": "App slug to create a custom app for" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string", "description": "Your OAuth client ID" }, "clientSecret": { "type": "string", "description": "Your OAuth client secret" }, "customScopes": { "type": "array", "items": { "type": "string" }, "description": "Override default scopes" } }, "required": [ "clientId", "clientSecret" ], "description": "Input for creating a custom OAuth app (BYOA)" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Custom app identifier" }, "appDefinitionId": { "type": "string", "description": "Parent app definition ID" }, "appSlug": { "type": "string", "description": "App slug" }, "orgId": { "type": "string", "description": "Organization that owns this custom app" }, "clientId": { "type": "string", "description": "OAuth client ID (visible)" }, "customScopes": { "type": "array", "items": { "type": "string" }, "description": "Custom scopes" }, "isActive": { "type": "boolean", "description": "Whether the custom app is active" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the custom app was created" } }, "required": [ "id", "appDefinitionId", "appSlug", "orgId", "clientId", "customScopes", "isActive", "createdAt" ], "description": "Custom OAuth app details (client secret is never returned)" } } } } } } }, "/vault/oauth/apps/{appSlug}/custom/{id}": { "delete": { "operationId": "vault.oauthDeleteCustomApp", "parameters": [ { "name": "appSlug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true } }, "required": [ "success" ] } } } } } } }, "/email/send": { "post": { "operationId": "email.send", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the agent sending the email" }, "fromIdentityId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Optional EmailIdentity ID to send from. An agent has exactly one email identity, so the only valid value is that one — supply it to assert which address you expect to send as, or omit it and the agent's identity is used. Discover the ID via GET /agents/{agentId}/email-identities." }, "to": { "type": "array", "items": { "type": "string", "format": "email" }, "minItems": 1, "description": "List of recipient email addresses (at least one required)" }, "cc": { "default": [], "type": "array", "items": { "type": "string", "format": "email" }, "description": "List of CC recipient email addresses" }, "bcc": { "default": [], "type": "array", "items": { "type": "string", "format": "email" }, "description": "List of BCC recipient email addresses" }, "subject": { "type": "string", "minLength": 1, "maxLength": 998, "description": "Email subject line (max 998 characters per RFC 2822)" }, "body": { "type": "string", "minLength": 1, "description": "Plain-text body of the email" }, "bodyHtml": { "type": "string", "description": "Optional HTML body of the email" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Filename presented to the recipient. Inferred from the URL path when `url` is used and this is omitted; falls back to 'attachment' when neither is available." }, "contentId": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Content-ID for inline attachments referenced in the HTML body via `cid:` URIs (e.g. set to 'logo' to be referenced as ``). When present, the attachment uses `Content-Disposition: inline`; when absent, `attachment`." }, "contentType": { "type": "string", "description": "MIME type. Auto-detected from `filename` extension if omitted (e.g. 'application/pdf' for .pdf, 'image/png' for .png). Falls back to 'application/octet-stream' if undetectable." }, "content": { "type": "string", "description": "Base64-encoded attachment bytes. Provide either `content` or `url`. Single base64 string up to ~33MB on the wire (decodes to ~25MB binary)." }, "url": { "type": "string", "format": "uri", "description": "Public URL the server fetches and attaches. Provide either `content` or `url`. URLs to private/loopback/link-local IPs are rejected to prevent SSRF. Max 25MB after download." } }, "description": "File attachment for outbound email. Provide exactly one of `content` (base64-inline) or `url` (server-fetch). Optional `contentId` makes the attachment inline for HTML-embedded images." }, "maxItems": 20, "description": "Optional file attachments. Max 25MB total across all attachments (after base64 decode for inline, after fetch for URL-source); max 20 attachments per email. Each entry provides either inline base64 `content` or a public `url` for server-fetch." }, "headers": { "default": {}, "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom email headers as key-value pairs" }, "metadata": { "default": {}, "type": "object", "additionalProperties": {}, "description": "Arbitrary key-value metadata to attach to the message" }, "inReplyTo": { "type": "string", "description": "The message this email replies to: either an RFC 5322 Message-ID (with or without angle brackets, e.g. from an inbound email's externalId) or an Anima message id (cuid). The reply joins that message's thread and emits In-Reply-To/References so external clients thread it too." }, "references": { "default": [], "type": "array", "items": { "type": "string" }, "description": "Explicit References chain (RFC 5322 Message-IDs, oldest first) emitted on the wire. If omitted on a reply, the chain is derived from the replied-to message automatically." } }, "required": [ "agentId", "to", "subject", "body" ], "description": "Request body for sending an email with threading support" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the message" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the agent that sent or received the message" }, "inboxId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "ID of the inbox this message belongs to — the inbox it was delivered to (inbound) or sent from (outbound). Null when no inbox backs the address: SMS/MMS/voice messages, and email sent from an email identity that has no inbox (such as a custom-domain identity added to an agent). Pass it to GET /messages?inboxId= to list one inbox's mail." }, "channel": { "enum": [ "EMAIL", "SMS", "MMS", "VOICE" ], "type": "string", "description": "Communication channel used" }, "direction": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "description": "Whether the message was inbound or outbound" }, "status": { "enum": [ "QUEUED", "SENT", "DELIVERED", "FAILED", "BOUNCED", "BLOCKED", "PENDING_APPROVAL" ], "type": "string", "description": "Current delivery status" }, "fromAddress": { "type": "string", "description": "Sender address (email or phone number)" }, "toAddress": { "type": "string", "description": "Recipient address (email or phone number)" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message subject line, or null for channels that do not support subjects" }, "body": { "type": "string", "description": "Plain-text content of the message" }, "bodyHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML content of the message, or null if not available" }, "extractedText": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plain-text body with the quoted reply chain and signature stripped — just what this sender actually wrote. Read this instead of `body` to avoid re-reading (and paying for) the whole thread on every message. Null when nothing was extracted: non-email channels, messages your agent sent, and mail received before this field existed — so `extractedText ?? body` is always correct. Best-effort and heuristic; `body` remains the verbatim source of truth. Known weak cases: forwards and bottom-posted replies have no separable 'new' part, so this returns the full body rather than nothing." }, "extractedHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML body with quoted reply chains removed. Same semantics as `extractedText`; `bodyHtml` stays verbatim. Quoting styles that mark the chain with a sibling element rather than wrapping it (Outlook) are not stripped here — `extractedText` still is." }, "headers": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Raw message headers as key-value pairs, or null" }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Arbitrary metadata attached to the message, or null" }, "threadId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Thread identifier for conversation grouping, or null" }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Workflow labels on this message. Always contains exactly one of the system labels `unread` or `read`; may also contain `archived`, `spam` (the inbound spam verdict — see `includeSpam` on list/search), and any labels you add yourself. Stored lowercase, deduped, and sorted. Change them with PATCH /messages/{id}/labels." }, "inReplyTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message ID this message is replying to, or null" }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "External identifier, or null. For email: the RFC 5322 Message-ID (bare, no angle brackets) — pass it as inReplyTo to reply in-thread. For SMS: the provider-assigned message id." }, "deletedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this message was moved to Trash, or null if it is live. Deleted messages are hidden from listings unless `deleted` is set to `include` or `only`, and can be brought back with POST /messages/{id}/restore. Nothing purges them." }, "sentAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was sent, or null if not yet sent" }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was received, or null for outbound messages" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the attachment" }, "filename": { "type": "string", "description": "Original filename of the attachment" }, "mimeType": { "type": "string", "description": "MIME type of the attachment (e.g. application/pdf)" }, "sizeBytes": { "type": "integer", "minimum": 0, "description": "File size in bytes" }, "storageKey": { "type": "string", "description": "Internal storage key for retrieving the file" }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Pre-signed download URL, or null if not yet generated" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the attachment was created" }, "scanStatus": { "enum": [ "PENDING", "CLEAN", "FLAGGED", "BLOCKED" ], "type": "string", "description": "Content-scan verdict. BLOCKED attachments cannot be downloaded — inspect before fetching bytes." }, "detectedMimeType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "MIME type inferred from magic bytes; may differ from the declared mimeType" } }, "required": [ "id", "filename", "mimeType", "sizeBytes", "storageKey", "url", "createdAt", "scanStatus", "detectedMimeType" ], "description": "File attachment associated with a message" }, "description": "File attachments associated with this message" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was last updated" } }, "required": [ "id", "agentId", "inboxId", "channel", "direction", "status", "fromAddress", "toAddress", "subject", "body", "bodyHtml", "extractedText", "extractedHtml", "headers", "metadata", "threadId", "labels", "inReplyTo", "externalId", "deletedAt", "sentAt", "receivedAt", "attachments", "createdAt", "updatedAt" ], "description": "Full message resource representation" } } } } } } }, "/email/suppressions": { "get": { "operationId": "email.listSuppressions", "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Opaque cursor from a previous response to fetch the next page" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of items to return per page (1–100, default 20)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "email", "in": "query", "schema": { "type": "string", "description": "Filter to a single recipient address (case-insensitive)" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the suppression entry" }, "email": { "type": "string", "description": "Suppressed recipient address (lowercased)" }, "agentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent the suppression is scoped to, or null when workspace-wide" }, "reason": { "enum": [ "USER_UNSUBSCRIBE_ONE_CLICK", "USER_UNSUBSCRIBE_MAILTO", "USER_UNSUBSCRIBE_LINK", "BOUNCE_HARD", "COMPLAINT", "MANUAL" ], "type": "string", "description": "Why the address is suppressed (unsubscribe, hard bounce, spam complaint, or manual)" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-form origin marker, e.g. 'resend-bounce-webhook' or 'manual-admin-add'" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the suppression was recorded" } }, "required": [ "id", "email", "agentId", "reason", "source", "createdAt" ], "description": "A suppressed recipient address — sends to it are refused with RECIPIENT_SUPPRESSED" }, "description": "Suppression entries matching the query" }, "pagination": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "Cursor to pass as the `cursor` parameter to retrieve the next page, or null if no more results" }, "hasMore": { "type": "boolean", "description": "Whether additional pages of results are available" } }, "required": [ "nextCursor", "hasMore" ], "description": "Pagination metadata for retrieving additional pages" } }, "required": [ "items", "pagination" ], "description": "Paginated list of suppressed recipient addresses" } } } } } } }, "/email/unsuppress": { "post": { "operationId": "email.unsuppress", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Recipient address to remove from the suppression list (case-insensitive)" } }, "required": [ "email" ], "description": "Request body for removing an address from the suppression list" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The (normalized) address that was unsuppressed" }, "removed": { "type": "integer", "minimum": 0, "description": "Number of suppression entries removed (0 when the address was not suppressed)" } }, "required": [ "email", "removed" ], "description": "Result of an unsuppress operation" } } } } } } }, "/email/{id}/reply": { "post": { "operationId": "email.reply", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the email being replied to" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Agent to send as. Required with a master key; resolved automatically from an agent key." }, "body": { "type": "string", "description": "Plain-text body of your reply (the quoted original is appended)" }, "bodyHtml": { "type": "string", "description": "HTML body of your reply" }, "replyAll": { "default": false, "type": "boolean", "description": "Reply to every correspondent on the original (its To and Cc) rather than just the sender. Your own addresses are always excluded, so you never reply to yourself. Bcc recipients of your own sent mail are never resurfaced — that would disclose them to the whole thread." }, "cc": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Extra Cc recipients, added to any computed by replyAll" }, "bcc": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Bcc recipients for this reply" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string" }, "contentId": { "type": "string" }, "contentType": { "type": "string" }, "content": { "type": "string" }, "url": { "type": "string" } } }, "description": "Attachments to include on the reply" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Arbitrary metadata to store" }, "quoteOriginal": { "default": true, "type": "boolean", "description": "Append the original message as a quoted block, the way a human mail client does. Default true. Set false to send only your own text — the recipient then sees no context, so only do this when the thread is already established." } }, "required": [ "body" ], "description": "Request body for replying to an email in-thread" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the message" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the agent that sent or received the message" }, "inboxId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "ID of the inbox this message belongs to — the inbox it was delivered to (inbound) or sent from (outbound). Null when no inbox backs the address: SMS/MMS/voice messages, and email sent from an email identity that has no inbox (such as a custom-domain identity added to an agent). Pass it to GET /messages?inboxId= to list one inbox's mail." }, "channel": { "enum": [ "EMAIL", "SMS", "MMS", "VOICE" ], "type": "string", "description": "Communication channel used" }, "direction": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "description": "Whether the message was inbound or outbound" }, "status": { "enum": [ "QUEUED", "SENT", "DELIVERED", "FAILED", "BOUNCED", "BLOCKED", "PENDING_APPROVAL" ], "type": "string", "description": "Current delivery status" }, "fromAddress": { "type": "string", "description": "Sender address (email or phone number)" }, "toAddress": { "type": "string", "description": "Recipient address (email or phone number)" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message subject line, or null for channels that do not support subjects" }, "body": { "type": "string", "description": "Plain-text content of the message" }, "bodyHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML content of the message, or null if not available" }, "extractedText": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plain-text body with the quoted reply chain and signature stripped — just what this sender actually wrote. Read this instead of `body` to avoid re-reading (and paying for) the whole thread on every message. Null when nothing was extracted: non-email channels, messages your agent sent, and mail received before this field existed — so `extractedText ?? body` is always correct. Best-effort and heuristic; `body` remains the verbatim source of truth. Known weak cases: forwards and bottom-posted replies have no separable 'new' part, so this returns the full body rather than nothing." }, "extractedHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML body with quoted reply chains removed. Same semantics as `extractedText`; `bodyHtml` stays verbatim. Quoting styles that mark the chain with a sibling element rather than wrapping it (Outlook) are not stripped here — `extractedText` still is." }, "headers": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Raw message headers as key-value pairs, or null" }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Arbitrary metadata attached to the message, or null" }, "threadId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Thread identifier for conversation grouping, or null" }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Workflow labels on this message. Always contains exactly one of the system labels `unread` or `read`; may also contain `archived`, `spam` (the inbound spam verdict — see `includeSpam` on list/search), and any labels you add yourself. Stored lowercase, deduped, and sorted. Change them with PATCH /messages/{id}/labels." }, "inReplyTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message ID this message is replying to, or null" }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "External identifier, or null. For email: the RFC 5322 Message-ID (bare, no angle brackets) — pass it as inReplyTo to reply in-thread. For SMS: the provider-assigned message id." }, "deletedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this message was moved to Trash, or null if it is live. Deleted messages are hidden from listings unless `deleted` is set to `include` or `only`, and can be brought back with POST /messages/{id}/restore. Nothing purges them." }, "sentAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was sent, or null if not yet sent" }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was received, or null for outbound messages" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the attachment" }, "filename": { "type": "string", "description": "Original filename of the attachment" }, "mimeType": { "type": "string", "description": "MIME type of the attachment (e.g. application/pdf)" }, "sizeBytes": { "type": "integer", "minimum": 0, "description": "File size in bytes" }, "storageKey": { "type": "string", "description": "Internal storage key for retrieving the file" }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Pre-signed download URL, or null if not yet generated" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the attachment was created" }, "scanStatus": { "enum": [ "PENDING", "CLEAN", "FLAGGED", "BLOCKED" ], "type": "string", "description": "Content-scan verdict. BLOCKED attachments cannot be downloaded — inspect before fetching bytes." }, "detectedMimeType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "MIME type inferred from magic bytes; may differ from the declared mimeType" } }, "required": [ "id", "filename", "mimeType", "sizeBytes", "storageKey", "url", "createdAt", "scanStatus", "detectedMimeType" ], "description": "File attachment associated with a message" }, "description": "File attachments associated with this message" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was last updated" } }, "required": [ "id", "agentId", "inboxId", "channel", "direction", "status", "fromAddress", "toAddress", "subject", "body", "bodyHtml", "extractedText", "extractedHtml", "headers", "metadata", "threadId", "labels", "inReplyTo", "externalId", "deletedAt", "sentAt", "receivedAt", "attachments", "createdAt", "updatedAt" ], "description": "Full message resource representation" } } } } } } }, "/email/{id}/forward": { "post": { "operationId": "email.forward", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the email being forwarded" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Agent to send as. Required with a master key; resolved automatically from an agent key." }, "to": { "type": "array", "items": { "type": "string", "format": "email" }, "minItems": 1, "description": "Who to forward the message to" }, "cc": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Cc recipients" }, "bcc": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Bcc recipients" }, "body": { "type": "string", "description": "Your own note, placed above the forwarded message. Optional." }, "bodyHtml": { "type": "string", "description": "HTML version of your note" }, "includeAttachments": { "default": true, "type": "boolean", "description": "Re-attach the original's files. Default true — a forward that drops the attachment is the bug this endpoint exists to avoid. Refused with 422 if any attachment was blocked by content scanning; pass false to forward the text anyway." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string" }, "contentId": { "type": "string" }, "contentType": { "type": "string" }, "content": { "type": "string" }, "url": { "type": "string" } } }, "description": "Additional attachments of your own, beyond the original's" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Arbitrary metadata to store" }, "quoteOriginal": { "default": true, "type": "boolean", "description": "Append the original message as a quoted block, the way a human mail client does. Default true. Set false to send only your own text — the recipient then sees no context, so only do this when the thread is already established." } }, "required": [ "to" ], "description": "Request body for forwarding an email to new recipients" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the message" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the agent that sent or received the message" }, "inboxId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "ID of the inbox this message belongs to — the inbox it was delivered to (inbound) or sent from (outbound). Null when no inbox backs the address: SMS/MMS/voice messages, and email sent from an email identity that has no inbox (such as a custom-domain identity added to an agent). Pass it to GET /messages?inboxId= to list one inbox's mail." }, "channel": { "enum": [ "EMAIL", "SMS", "MMS", "VOICE" ], "type": "string", "description": "Communication channel used" }, "direction": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "description": "Whether the message was inbound or outbound" }, "status": { "enum": [ "QUEUED", "SENT", "DELIVERED", "FAILED", "BOUNCED", "BLOCKED", "PENDING_APPROVAL" ], "type": "string", "description": "Current delivery status" }, "fromAddress": { "type": "string", "description": "Sender address (email or phone number)" }, "toAddress": { "type": "string", "description": "Recipient address (email or phone number)" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message subject line, or null for channels that do not support subjects" }, "body": { "type": "string", "description": "Plain-text content of the message" }, "bodyHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML content of the message, or null if not available" }, "extractedText": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plain-text body with the quoted reply chain and signature stripped — just what this sender actually wrote. Read this instead of `body` to avoid re-reading (and paying for) the whole thread on every message. Null when nothing was extracted: non-email channels, messages your agent sent, and mail received before this field existed — so `extractedText ?? body` is always correct. Best-effort and heuristic; `body` remains the verbatim source of truth. Known weak cases: forwards and bottom-posted replies have no separable 'new' part, so this returns the full body rather than nothing." }, "extractedHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML body with quoted reply chains removed. Same semantics as `extractedText`; `bodyHtml` stays verbatim. Quoting styles that mark the chain with a sibling element rather than wrapping it (Outlook) are not stripped here — `extractedText` still is." }, "headers": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Raw message headers as key-value pairs, or null" }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Arbitrary metadata attached to the message, or null" }, "threadId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Thread identifier for conversation grouping, or null" }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Workflow labels on this message. Always contains exactly one of the system labels `unread` or `read`; may also contain `archived`, `spam` (the inbound spam verdict — see `includeSpam` on list/search), and any labels you add yourself. Stored lowercase, deduped, and sorted. Change them with PATCH /messages/{id}/labels." }, "inReplyTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message ID this message is replying to, or null" }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "External identifier, or null. For email: the RFC 5322 Message-ID (bare, no angle brackets) — pass it as inReplyTo to reply in-thread. For SMS: the provider-assigned message id." }, "deletedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this message was moved to Trash, or null if it is live. Deleted messages are hidden from listings unless `deleted` is set to `include` or `only`, and can be brought back with POST /messages/{id}/restore. Nothing purges them." }, "sentAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was sent, or null if not yet sent" }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was received, or null for outbound messages" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the attachment" }, "filename": { "type": "string", "description": "Original filename of the attachment" }, "mimeType": { "type": "string", "description": "MIME type of the attachment (e.g. application/pdf)" }, "sizeBytes": { "type": "integer", "minimum": 0, "description": "File size in bytes" }, "storageKey": { "type": "string", "description": "Internal storage key for retrieving the file" }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Pre-signed download URL, or null if not yet generated" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the attachment was created" }, "scanStatus": { "enum": [ "PENDING", "CLEAN", "FLAGGED", "BLOCKED" ], "type": "string", "description": "Content-scan verdict. BLOCKED attachments cannot be downloaded — inspect before fetching bytes." }, "detectedMimeType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "MIME type inferred from magic bytes; may differ from the declared mimeType" } }, "required": [ "id", "filename", "mimeType", "sizeBytes", "storageKey", "url", "createdAt", "scanStatus", "detectedMimeType" ], "description": "File attachment associated with a message" }, "description": "File attachments associated with this message" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was last updated" } }, "required": [ "id", "agentId", "inboxId", "channel", "direction", "status", "fromAddress", "toAddress", "subject", "body", "bodyHtml", "extractedText", "extractedHtml", "headers", "metadata", "threadId", "labels", "inReplyTo", "externalId", "deletedAt", "sentAt", "receivedAt", "attachments", "createdAt", "updatedAt" ], "description": "Full message resource representation" } } } } } } }, "/email/{id}": { "get": { "operationId": "email.get", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique email message identifier" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the message" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the agent that sent or received the message" }, "inboxId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "ID of the inbox this message belongs to — the inbox it was delivered to (inbound) or sent from (outbound). Null when no inbox backs the address: SMS/MMS/voice messages, and email sent from an email identity that has no inbox (such as a custom-domain identity added to an agent). Pass it to GET /messages?inboxId= to list one inbox's mail." }, "channel": { "enum": [ "EMAIL", "SMS", "MMS", "VOICE" ], "type": "string", "description": "Communication channel used" }, "direction": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "description": "Whether the message was inbound or outbound" }, "status": { "enum": [ "QUEUED", "SENT", "DELIVERED", "FAILED", "BOUNCED", "BLOCKED", "PENDING_APPROVAL" ], "type": "string", "description": "Current delivery status" }, "fromAddress": { "type": "string", "description": "Sender address (email or phone number)" }, "toAddress": { "type": "string", "description": "Recipient address (email or phone number)" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message subject line, or null for channels that do not support subjects" }, "body": { "type": "string", "description": "Plain-text content of the message" }, "bodyHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML content of the message, or null if not available" }, "extractedText": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plain-text body with the quoted reply chain and signature stripped — just what this sender actually wrote. Read this instead of `body` to avoid re-reading (and paying for) the whole thread on every message. Null when nothing was extracted: non-email channels, messages your agent sent, and mail received before this field existed — so `extractedText ?? body` is always correct. Best-effort and heuristic; `body` remains the verbatim source of truth. Known weak cases: forwards and bottom-posted replies have no separable 'new' part, so this returns the full body rather than nothing." }, "extractedHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML body with quoted reply chains removed. Same semantics as `extractedText`; `bodyHtml` stays verbatim. Quoting styles that mark the chain with a sibling element rather than wrapping it (Outlook) are not stripped here — `extractedText` still is." }, "headers": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Raw message headers as key-value pairs, or null" }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Arbitrary metadata attached to the message, or null" }, "threadId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Thread identifier for conversation grouping, or null" }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Workflow labels on this message. Always contains exactly one of the system labels `unread` or `read`; may also contain `archived`, `spam` (the inbound spam verdict — see `includeSpam` on list/search), and any labels you add yourself. Stored lowercase, deduped, and sorted. Change them with PATCH /messages/{id}/labels." }, "inReplyTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message ID this message is replying to, or null" }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "External identifier, or null. For email: the RFC 5322 Message-ID (bare, no angle brackets) — pass it as inReplyTo to reply in-thread. For SMS: the provider-assigned message id." }, "deletedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this message was moved to Trash, or null if it is live. Deleted messages are hidden from listings unless `deleted` is set to `include` or `only`, and can be brought back with POST /messages/{id}/restore. Nothing purges them." }, "sentAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was sent, or null if not yet sent" }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was received, or null for outbound messages" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the attachment" }, "filename": { "type": "string", "description": "Original filename of the attachment" }, "mimeType": { "type": "string", "description": "MIME type of the attachment (e.g. application/pdf)" }, "sizeBytes": { "type": "integer", "minimum": 0, "description": "File size in bytes" }, "storageKey": { "type": "string", "description": "Internal storage key for retrieving the file" }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Pre-signed download URL, or null if not yet generated" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the attachment was created" }, "scanStatus": { "enum": [ "PENDING", "CLEAN", "FLAGGED", "BLOCKED" ], "type": "string", "description": "Content-scan verdict. BLOCKED attachments cannot be downloaded — inspect before fetching bytes." }, "detectedMimeType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "MIME type inferred from magic bytes; may differ from the declared mimeType" } }, "required": [ "id", "filename", "mimeType", "sizeBytes", "storageKey", "url", "createdAt", "scanStatus", "detectedMimeType" ], "description": "File attachment associated with a message" }, "description": "File attachments associated with this message" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was last updated" } }, "required": [ "id", "agentId", "inboxId", "channel", "direction", "status", "fromAddress", "toAddress", "subject", "body", "bodyHtml", "extractedText", "extractedHtml", "headers", "metadata", "threadId", "labels", "inReplyTo", "externalId", "deletedAt", "sentAt", "receivedAt", "attachments", "createdAt", "updatedAt" ], "description": "Full message resource representation" } } } } } } }, "/email": { "get": { "operationId": "email.list", "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Opaque cursor from a previous response to fetch the next page" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of items to return per page (1–100, default 20)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "agentId", "in": "query", "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Filter emails by agent ID" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "direction", "in": "query", "schema": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "description": "Only return received (INBOUND) or sent (OUTBOUND) email" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "threadId", "in": "query", "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Only return email in this thread (see GET /threads)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "from", "in": "query", "schema": { "type": "string", "description": "Only return email whose sender address matches this value (case-insensitive, exact address match)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "to", "in": "query", "schema": { "type": "string", "description": "Only return email addressed to this recipient (case-insensitive). Matches if the address appears anywhere in the message's recipient list, not only as the first recipient." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "Only return email created strictly after this ISO-8601 timestamp" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "before", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "Only return email created strictly before this ISO-8601 timestamp" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "labels", "in": "query", "schema": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 50, "description": "Filter to messages carrying ALL of these labels (e.g. `urgent` + `unread` means urgent AND still unread). Case-insensitive. System labels: `unread`, `read`, `archived`, `spam`." }, "style": "deepObject", "explode": true, "allowEmptyValue": true, "allowReserved": true }, { "name": "includeSpam", "in": "query", "schema": { "default": false, "type": "boolean", "description": "Include messages classified as spam on arrival. They are excluded by default. Naming `spam` in `labels` also counts as asking for it, so a deliberate spam query is never silently emptied by this default." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "includeArchived", "in": "query", "schema": { "default": false, "type": "boolean", "description": "Include messages carrying the `archived` label. They are excluded by default, so archiving actually removes mail from a listing rather than only tagging it. Naming `archived` in `labels` also counts as asking for it (and returns ONLY archived mail); use this flag instead to see archived mail mixed in with the rest." }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the message" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the agent that sent or received the message" }, "inboxId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "ID of the inbox this message belongs to — the inbox it was delivered to (inbound) or sent from (outbound). Null when no inbox backs the address: SMS/MMS/voice messages, and email sent from an email identity that has no inbox (such as a custom-domain identity added to an agent). Pass it to GET /messages?inboxId= to list one inbox's mail." }, "channel": { "enum": [ "EMAIL", "SMS", "MMS", "VOICE" ], "type": "string", "description": "Communication channel used" }, "direction": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "description": "Whether the message was inbound or outbound" }, "status": { "enum": [ "QUEUED", "SENT", "DELIVERED", "FAILED", "BOUNCED", "BLOCKED", "PENDING_APPROVAL" ], "type": "string", "description": "Current delivery status" }, "fromAddress": { "type": "string", "description": "Sender address (email or phone number)" }, "toAddress": { "type": "string", "description": "Recipient address (email or phone number)" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message subject line, or null for channels that do not support subjects" }, "body": { "type": "string", "description": "Plain-text content of the message" }, "bodyHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML content of the message, or null if not available" }, "extractedText": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plain-text body with the quoted reply chain and signature stripped — just what this sender actually wrote. Read this instead of `body` to avoid re-reading (and paying for) the whole thread on every message. Null when nothing was extracted: non-email channels, messages your agent sent, and mail received before this field existed — so `extractedText ?? body` is always correct. Best-effort and heuristic; `body` remains the verbatim source of truth. Known weak cases: forwards and bottom-posted replies have no separable 'new' part, so this returns the full body rather than nothing." }, "extractedHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML body with quoted reply chains removed. Same semantics as `extractedText`; `bodyHtml` stays verbatim. Quoting styles that mark the chain with a sibling element rather than wrapping it (Outlook) are not stripped here — `extractedText` still is." }, "headers": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Raw message headers as key-value pairs, or null" }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Arbitrary metadata attached to the message, or null" }, "threadId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Thread identifier for conversation grouping, or null" }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Workflow labels on this message. Always contains exactly one of the system labels `unread` or `read`; may also contain `archived`, `spam` (the inbound spam verdict — see `includeSpam` on list/search), and any labels you add yourself. Stored lowercase, deduped, and sorted. Change them with PATCH /messages/{id}/labels." }, "inReplyTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message ID this message is replying to, or null" }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "External identifier, or null. For email: the RFC 5322 Message-ID (bare, no angle brackets) — pass it as inReplyTo to reply in-thread. For SMS: the provider-assigned message id." }, "deletedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this message was moved to Trash, or null if it is live. Deleted messages are hidden from listings unless `deleted` is set to `include` or `only`, and can be brought back with POST /messages/{id}/restore. Nothing purges them." }, "sentAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was sent, or null if not yet sent" }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was received, or null for outbound messages" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the attachment" }, "filename": { "type": "string", "description": "Original filename of the attachment" }, "mimeType": { "type": "string", "description": "MIME type of the attachment (e.g. application/pdf)" }, "sizeBytes": { "type": "integer", "minimum": 0, "description": "File size in bytes" }, "storageKey": { "type": "string", "description": "Internal storage key for retrieving the file" }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Pre-signed download URL, or null if not yet generated" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the attachment was created" }, "scanStatus": { "enum": [ "PENDING", "CLEAN", "FLAGGED", "BLOCKED" ], "type": "string", "description": "Content-scan verdict. BLOCKED attachments cannot be downloaded — inspect before fetching bytes." }, "detectedMimeType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "MIME type inferred from magic bytes; may differ from the declared mimeType" } }, "required": [ "id", "filename", "mimeType", "sizeBytes", "storageKey", "url", "createdAt", "scanStatus", "detectedMimeType" ], "description": "File attachment associated with a message" }, "description": "File attachments associated with this message" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was last updated" } }, "required": [ "id", "agentId", "inboxId", "channel", "direction", "status", "fromAddress", "toAddress", "subject", "body", "bodyHtml", "extractedText", "extractedHtml", "headers", "metadata", "threadId", "labels", "inReplyTo", "externalId", "deletedAt", "sentAt", "receivedAt", "attachments", "createdAt", "updatedAt" ], "description": "Full message resource representation" }, "description": "Array of email message resources matching the query" }, "pagination": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "Cursor to pass as the `cursor` parameter to retrieve the next page, or null if no more results" }, "hasMore": { "type": "boolean", "description": "Whether additional pages of results are available" } }, "required": [ "nextCursor", "hasMore" ], "description": "Pagination metadata for retrieving additional pages" } }, "required": [ "items", "pagination" ], "description": "Paginated list of email messages" } } } } } } }, "/threads": { "get": { "operationId": "thread.list", "parameters": [ { "name": "channel", "in": "query", "schema": { "default": "EMAIL", "enum": [ "EMAIL" ], "type": "string", "description": "Channel to list conversations for. EMAIL is currently the only supported value — SMS/MMS conversations are listed by GET /sms/threads, which models them as a phone-number pair rather than a reply chain." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "agentId", "in": "query", "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Filter conversations to one agent. Optional for master keys (omit for every agent in the org); ignored for agent keys, which always see only their own." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "inboxId", "in": "query", "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Filter conversations to one inbox — the precise way to read a single mailbox." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "direction", "in": "query", "schema": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "description": "Only conversations containing a message in this direction. `OUTBOUND` is a Sent view. Note that the returned counts then describe the MATCHING messages, not the thread's full length." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "labels", "in": "query", "schema": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 50, "description": "Filter to messages carrying ALL of these labels (e.g. `urgent` + `unread` means urgent AND still unread). Case-insensitive. System labels: `unread`, `read`, `archived`, `spam`." }, "style": "deepObject", "explode": true, "allowEmptyValue": true, "allowReserved": true }, { "name": "includeSpam", "in": "query", "schema": { "default": false, "type": "boolean", "description": "Include messages classified as spam on arrival. They are excluded by default. Naming `spam` in `labels` also counts as asking for it, so a deliberate spam query is never silently emptied by this default." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "includeArchived", "in": "query", "schema": { "default": false, "type": "boolean", "description": "Include messages carrying the `archived` label. They are excluded by default, so archiving actually removes mail from a listing rather than only tagging it. Naming `archived` in `labels` also counts as asking for it (and returns ONLY archived mail); use this flag instead to see archived mail mixed in with the rest." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "deleted", "in": "query", "schema": { "default": "exclude", "enum": [ "exclude", "include", "only" ], "type": "string", "description": "How to treat messages moved to Trash. `exclude` (default) hides them, so deleted mail disappears from every ordinary listing. `only` returns nothing but Trash. `include` ignores the distinction. Deletion is reversible — see DELETE /messages/{id} and POST /messages/{id}/restore." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum conversations to return per page (1–100, default 20)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "offset", "in": "query", "schema": { "default": 0, "type": "integer", "minimum": 0, "description": "Conversations to skip, for paging through the list" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "threadId": { "type": "string", "description": "Conversation identifier — the id of the thread's first message. Pass to GET /email?threadId= to read the messages." }, "agentId": { "type": "string", "description": "Agent that owns this conversation" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Subject of the most recent message in the thread, or null if it has none" }, "participants": { "type": "array", "items": { "type": "string" }, "description": "Distinct senders and To recipients across the thread, lowercased and de-duplicated, including the agent's own address. NOT exhaustive: Cc'd correspondents are absent (they are recorded on the message, but this list is built from the From and To fields only), and Bcc recipients are absent because they are never recorded at all — by design. Treat this as 'who is visibly on the thread', not as the full recipient set; read the messages themselves if you need every address." }, "messageCount": { "type": "integer", "description": "Messages in the thread matching this query. Equals the thread's full length for an unfiltered listing; under a `direction` or label filter it counts only the matching messages, since a thread is listed when ANY of its messages matches." }, "unreadCount": { "type": "integer", "description": "How many of those messages still carry the `unread` label — what a thread list needs to be worth scanning." }, "lastMessageAt": { "type": "string", "format": "date-time", "description": "When the most recent message arrived or was sent — the sort key for this list" }, "lastMessageSnippet": { "type": "string", "description": "First 140 characters of the most recent message, quoted chain already stripped where possible, so a thread list costs a snippet rather than a mail history" }, "lastMessageDirection": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "description": "Whether the most recent message was received or sent — i.e. is the ball ours" } }, "required": [ "threadId", "agentId", "subject", "participants", "messageCount", "unreadCount", "lastMessageAt", "lastMessageSnippet", "lastMessageDirection" ], "description": "Summary of one email conversation" }, "description": "Conversation summaries, most recent activity first" }, "total": { "type": "integer", "description": "Total conversations matching the query" }, "hasMore": { "type": "boolean", "description": "Whether more conversations exist past this page" } }, "required": [ "items", "total", "hasMore" ], "description": "Paginated list of email conversations" } } } } } } }, "/threads/{threadId}/labels": { "patch": { "operationId": "thread.updateLabels", "parameters": [ { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "description": "Conversation to relabel — every message in it is updated" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "addLabels": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 50, "description": "Labels to add to every message in the thread. Adding `read` removes `unread` and vice versa, per message, exactly as the single-message route does." }, "removeLabels": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 50, "description": "Labels to remove from every message in the thread." } }, "required": [], "description": "Add and/or remove labels across a whole conversation in one atomic write. Supply at least one of addLabels/removeLabels. Use this rather than looping over PATCH /messages/{id}/labels: a loop that fails partway leaves the thread in two folders at once." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "threadId": { "type": "string", "description": "The conversation that was relabelled" }, "updatedCount": { "type": "integer", "description": "How many messages were written. Zero means the thread does not exist or is not yours — it is never a silent success." } }, "required": [ "threadId", "updatedCount" ], "description": "Result of relabelling a conversation" } } } } } } }, "/email/drafts": { "post": { "operationId": "emailDraft.create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Owning agent ID" }, "fromIdentityId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Optional EmailIdentity ID to send from. Must belong to this agent and be verified." }, "to": { "default": [], "type": "array", "items": { "type": "string" }, "description": "Recipient email addresses (may be empty for an incomplete draft)" }, "cc": { "default": [], "type": "array", "items": { "type": "string" }, "description": "CC recipients" }, "bcc": { "default": [], "type": "array", "items": { "type": "string" }, "description": "BCC recipients" }, "subject": { "type": "string", "description": "Subject line" }, "body": { "type": "string", "description": "Plain-text body" }, "bodyHtml": { "type": "string", "description": "HTML body" }, "inReplyTo": { "type": "string", "description": "Optional In-Reply-To header for threading on send" }, "references": { "default": [], "type": "array", "items": { "type": "string" }, "description": "Optional References chain for threading" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Arbitrary metadata" } }, "required": [ "agentId" ], "description": "Request body for creating an email draft" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the draft" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Owning agent ID" }, "orgId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Owning organization ID" }, "fromIdentityId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "EmailIdentity used as the sender, or null to use the agent's primary identity at send time" }, "to": { "type": "array", "items": { "type": "string" }, "description": "Recipient email addresses" }, "cc": { "type": "array", "items": { "type": "string" }, "description": "CC recipient email addresses" }, "bcc": { "type": "array", "items": { "type": "string" }, "description": "BCC recipient email addresses" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Subject line, or null if not yet written" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plain-text body, or null if not yet written" }, "bodyHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML body, or null if not provided" }, "inReplyTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional In-Reply-To Message-ID for threading on send" }, "references": { "type": "array", "items": { "type": "string" }, "description": "Optional References Message-ID chain for threading" }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Arbitrary metadata" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the draft was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the draft was last updated" } }, "required": [ "id", "agentId", "orgId", "fromIdentityId", "to", "cc", "bcc", "subject", "body", "bodyHtml", "inReplyTo", "references", "metadata", "createdAt", "updatedAt" ], "description": "Email draft resource" } } } } } }, "get": { "operationId": "emailDraft.list", "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Opaque cursor from a previous response to fetch the next page" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of items to return per page (1–100, default 20)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "agentId", "in": "query", "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Filter drafts by agent ID" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the draft" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Owning agent ID" }, "orgId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Owning organization ID" }, "fromIdentityId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "EmailIdentity used as the sender, or null to use the agent's primary identity at send time" }, "to": { "type": "array", "items": { "type": "string" }, "description": "Recipient email addresses" }, "cc": { "type": "array", "items": { "type": "string" }, "description": "CC recipient email addresses" }, "bcc": { "type": "array", "items": { "type": "string" }, "description": "BCC recipient email addresses" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Subject line, or null if not yet written" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plain-text body, or null if not yet written" }, "bodyHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML body, or null if not provided" }, "inReplyTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional In-Reply-To Message-ID for threading on send" }, "references": { "type": "array", "items": { "type": "string" }, "description": "Optional References Message-ID chain for threading" }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Arbitrary metadata" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the draft was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the draft was last updated" } }, "required": [ "id", "agentId", "orgId", "fromIdentityId", "to", "cc", "bcc", "subject", "body", "bodyHtml", "inReplyTo", "references", "metadata", "createdAt", "updatedAt" ], "description": "Email draft resource" }, "description": "Array of email draft resources" }, "pagination": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "Cursor to pass as the `cursor` parameter to retrieve the next page, or null if no more results" }, "hasMore": { "type": "boolean", "description": "Whether additional pages of results are available" } }, "required": [ "nextCursor", "hasMore" ], "description": "Pagination metadata" } }, "required": [ "items", "pagination" ], "description": "Paginated list of email drafts" } } } } } } }, "/email/drafts/{id}": { "get": { "operationId": "emailDraft.get", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Draft ID" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the draft" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Owning agent ID" }, "orgId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Owning organization ID" }, "fromIdentityId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "EmailIdentity used as the sender, or null to use the agent's primary identity at send time" }, "to": { "type": "array", "items": { "type": "string" }, "description": "Recipient email addresses" }, "cc": { "type": "array", "items": { "type": "string" }, "description": "CC recipient email addresses" }, "bcc": { "type": "array", "items": { "type": "string" }, "description": "BCC recipient email addresses" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Subject line, or null if not yet written" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plain-text body, or null if not yet written" }, "bodyHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML body, or null if not provided" }, "inReplyTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional In-Reply-To Message-ID for threading on send" }, "references": { "type": "array", "items": { "type": "string" }, "description": "Optional References Message-ID chain for threading" }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Arbitrary metadata" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the draft was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the draft was last updated" } }, "required": [ "id", "agentId", "orgId", "fromIdentityId", "to", "cc", "bcc", "subject", "body", "bodyHtml", "inReplyTo", "references", "metadata", "createdAt", "updatedAt" ], "description": "Email draft resource" } } } } } }, "delete": { "operationId": "emailDraft.delete", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Draft ID" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "Draft lookup parameters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the draft" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Owning agent ID" }, "orgId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Owning organization ID" }, "fromIdentityId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "EmailIdentity used as the sender, or null to use the agent's primary identity at send time" }, "to": { "type": "array", "items": { "type": "string" }, "description": "Recipient email addresses" }, "cc": { "type": "array", "items": { "type": "string" }, "description": "CC recipient email addresses" }, "bcc": { "type": "array", "items": { "type": "string" }, "description": "BCC recipient email addresses" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Subject line, or null if not yet written" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plain-text body, or null if not yet written" }, "bodyHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML body, or null if not provided" }, "inReplyTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional In-Reply-To Message-ID for threading on send" }, "references": { "type": "array", "items": { "type": "string" }, "description": "Optional References Message-ID chain for threading" }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Arbitrary metadata" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the draft was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the draft was last updated" } }, "required": [ "id", "agentId", "orgId", "fromIdentityId", "to", "cc", "bcc", "subject", "body", "bodyHtml", "inReplyTo", "references", "metadata", "createdAt", "updatedAt" ], "description": "Email draft resource" } } } } } } }, "/email/drafts/{id}/send": { "post": { "operationId": "emailDraft.send", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Draft ID" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "Draft lookup parameters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the message" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the agent that sent or received the message" }, "inboxId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "ID of the inbox this message belongs to — the inbox it was delivered to (inbound) or sent from (outbound). Null when no inbox backs the address: SMS/MMS/voice messages, and email sent from an email identity that has no inbox (such as a custom-domain identity added to an agent). Pass it to GET /messages?inboxId= to list one inbox's mail." }, "channel": { "enum": [ "EMAIL", "SMS", "MMS", "VOICE" ], "type": "string", "description": "Communication channel used" }, "direction": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "description": "Whether the message was inbound or outbound" }, "status": { "enum": [ "QUEUED", "SENT", "DELIVERED", "FAILED", "BOUNCED", "BLOCKED", "PENDING_APPROVAL" ], "type": "string", "description": "Current delivery status" }, "fromAddress": { "type": "string", "description": "Sender address (email or phone number)" }, "toAddress": { "type": "string", "description": "Recipient address (email or phone number)" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message subject line, or null for channels that do not support subjects" }, "body": { "type": "string", "description": "Plain-text content of the message" }, "bodyHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML content of the message, or null if not available" }, "extractedText": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plain-text body with the quoted reply chain and signature stripped — just what this sender actually wrote. Read this instead of `body` to avoid re-reading (and paying for) the whole thread on every message. Null when nothing was extracted: non-email channels, messages your agent sent, and mail received before this field existed — so `extractedText ?? body` is always correct. Best-effort and heuristic; `body` remains the verbatim source of truth. Known weak cases: forwards and bottom-posted replies have no separable 'new' part, so this returns the full body rather than nothing." }, "extractedHtml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML body with quoted reply chains removed. Same semantics as `extractedText`; `bodyHtml` stays verbatim. Quoting styles that mark the chain with a sibling element rather than wrapping it (Outlook) are not stripped here — `extractedText` still is." }, "headers": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Raw message headers as key-value pairs, or null" }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Arbitrary metadata attached to the message, or null" }, "threadId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Thread identifier for conversation grouping, or null" }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Workflow labels on this message. Always contains exactly one of the system labels `unread` or `read`; may also contain `archived`, `spam` (the inbound spam verdict — see `includeSpam` on list/search), and any labels you add yourself. Stored lowercase, deduped, and sorted. Change them with PATCH /messages/{id}/labels." }, "inReplyTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message ID this message is replying to, or null" }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "External identifier, or null. For email: the RFC 5322 Message-ID (bare, no angle brackets) — pass it as inReplyTo to reply in-thread. For SMS: the provider-assigned message id." }, "deletedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this message was moved to Trash, or null if it is live. Deleted messages are hidden from listings unless `deleted` is set to `include` or `only`, and can be brought back with POST /messages/{id}/restore. Nothing purges them." }, "sentAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was sent, or null if not yet sent" }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the message was received, or null for outbound messages" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the attachment" }, "filename": { "type": "string", "description": "Original filename of the attachment" }, "mimeType": { "type": "string", "description": "MIME type of the attachment (e.g. application/pdf)" }, "sizeBytes": { "type": "integer", "minimum": 0, "description": "File size in bytes" }, "storageKey": { "type": "string", "description": "Internal storage key for retrieving the file" }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Pre-signed download URL, or null if not yet generated" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the attachment was created" }, "scanStatus": { "enum": [ "PENDING", "CLEAN", "FLAGGED", "BLOCKED" ], "type": "string", "description": "Content-scan verdict. BLOCKED attachments cannot be downloaded — inspect before fetching bytes." }, "detectedMimeType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "MIME type inferred from magic bytes; may differ from the declared mimeType" } }, "required": [ "id", "filename", "mimeType", "sizeBytes", "storageKey", "url", "createdAt", "scanStatus", "detectedMimeType" ], "description": "File attachment associated with a message" }, "description": "File attachments associated with this message" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message record was last updated" } }, "required": [ "id", "agentId", "inboxId", "channel", "direction", "status", "fromAddress", "toAddress", "subject", "body", "bodyHtml", "extractedText", "extractedHtml", "headers", "metadata", "threadId", "labels", "inReplyTo", "externalId", "deletedAt", "sentAt", "receivedAt", "attachments", "createdAt", "updatedAt" ], "description": "Full message resource representation" } } } } } } }, "/email-rules": { "post": { "operationId": "emailRule.create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "direction": { "enum": [ "SEND", "RECEIVE" ], "type": "string", "description": "SEND governs who this org's agents may email (enforced when a send is attempted); RECEIVE governs whose mail is accepted for them (enforced at ingest, before the message is stored or any webhook fires). Reply-scope is not implemented." }, "action": { "enum": [ "ALLOW", "BLOCK" ], "type": "string", "description": "BLOCK refuses the matching address. ALLOW does two things: it carves an exception out of a broader BLOCK, AND it switches that scope+direction into allow-list mode — once any ALLOW rule exists, addresses it does not cover are refused. Adding one ALLOW rule therefore restricts far more than it permits." }, "patternType": { "enum": [ "ADDRESS", "DOMAIN" ], "type": "string", "description": "ADDRESS matches one exact address. DOMAIN matches the domain and its subdomains ('example.com' covers 'a@mail.example.com' but never 'a@notexample.com'). ADDRESS beats DOMAIN when both match." }, "pattern": { "type": "string", "minLength": 1, "maxLength": 320, "description": "The address or domain this rule matches. Normalized to lowercase. Validated against patternType." }, "agentId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "Scope the rule to one agent. Omit or null for an org-wide rule. An agent's own rules take precedence over org-wide rules — including its allow-list, which does NOT inherit the org's." }, "note": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "description": "Optional operator note ('known phisher', 'competitor'). Surfaced in the error a blocked send returns and in the security event, so a refusal is diagnosable without opening the console." } }, "required": [ "direction", "action", "patternType", "pattern" ], "description": "Request body for creating an email allow/block rule" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the rule" }, "direction": { "enum": [ "SEND", "RECEIVE" ], "type": "string", "description": "SEND governs who this org's agents may email (enforced when a send is attempted); RECEIVE governs whose mail is accepted for them (enforced at ingest, before the message is stored or any webhook fires). Reply-scope is not implemented." }, "action": { "enum": [ "ALLOW", "BLOCK" ], "type": "string", "description": "BLOCK refuses the matching address. ALLOW does two things: it carves an exception out of a broader BLOCK, AND it switches that scope+direction into allow-list mode — once any ALLOW rule exists, addresses it does not cover are refused. Adding one ALLOW rule therefore restricts far more than it permits." }, "patternType": { "enum": [ "ADDRESS", "DOMAIN" ], "type": "string", "description": "ADDRESS matches one exact address. DOMAIN matches the domain and its subdomains ('example.com' covers 'a@mail.example.com' but never 'a@notexample.com'). ADDRESS beats DOMAIN when both match." }, "pattern": { "type": "string", "description": "The normalized (lowercase) address or domain this rule matches" }, "agentId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "The agent this rule is scoped to, or null for an org-wide rule" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Operator note, or null if not set" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the rule was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the rule was last modified" } }, "required": [ "id", "direction", "action", "patternType", "pattern", "agentId", "note", "createdAt", "updatedAt" ], "description": "An email allow/block rule" } } } } } }, "get": { "operationId": "emailRule.list", "parameters": [ { "name": "direction", "in": "query", "schema": { "enum": [ "SEND", "RECEIVE" ], "type": "string", "description": "Filter to one direction" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "action", "in": "query", "schema": { "enum": [ "ALLOW", "BLOCK" ], "type": "string", "description": "Filter to one action" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "agentId", "in": "query", "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Filter to the rules that BIND this agent — its own rules plus org-wide ones, i.e. exactly the set evaluated when it sends or receives. To list only org-wide rules, use scope=org instead." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "scope", "in": "query", "schema": { "enum": [ "org", "agent", "all" ], "type": "string", "description": "org = org-wide rules only; agent = agent-scoped rules only; all (default) = both. Combine with agentId to answer 'what binds this agent?'" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "rules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the rule" }, "direction": { "enum": [ "SEND", "RECEIVE" ], "type": "string", "description": "SEND governs who this org's agents may email (enforced when a send is attempted); RECEIVE governs whose mail is accepted for them (enforced at ingest, before the message is stored or any webhook fires). Reply-scope is not implemented." }, "action": { "enum": [ "ALLOW", "BLOCK" ], "type": "string", "description": "BLOCK refuses the matching address. ALLOW does two things: it carves an exception out of a broader BLOCK, AND it switches that scope+direction into allow-list mode — once any ALLOW rule exists, addresses it does not cover are refused. Adding one ALLOW rule therefore restricts far more than it permits." }, "patternType": { "enum": [ "ADDRESS", "DOMAIN" ], "type": "string", "description": "ADDRESS matches one exact address. DOMAIN matches the domain and its subdomains ('example.com' covers 'a@mail.example.com' but never 'a@notexample.com'). ADDRESS beats DOMAIN when both match." }, "pattern": { "type": "string", "description": "The normalized (lowercase) address or domain this rule matches" }, "agentId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "The agent this rule is scoped to, or null for an org-wide rule" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Operator note, or null if not set" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the rule was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the rule was last modified" } }, "required": [ "id", "direction", "action", "patternType", "pattern", "agentId", "note", "createdAt", "updatedAt" ], "description": "An email allow/block rule" }, "description": "Matching rules, newest first" }, "total": { "type": "integer", "description": "Number of rules returned" } }, "required": [ "rules", "total" ], "description": "A list of email allow/block rules" } } } } } } }, "/email-rules/{id}": { "delete": { "operationId": "emailRule.delete", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique rule identifier" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "Email rule deletion parameters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true, "description": "Always true on successful deletion" } }, "required": [ "success" ], "description": "Deletion confirmation" } } } } } } }, "/email-rules/evaluate": { "post": { "operationId": "emailRule.evaluate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "minLength": 1, "maxLength": 320, "description": "The address to test" }, "direction": { "enum": [ "SEND", "RECEIVE" ], "type": "string", "description": "SEND governs who this org's agents may email (enforced when a send is attempted); RECEIVE governs whose mail is accepted for them (enforced at ingest, before the message is stored or any webhook fires). Reply-scope is not implemented." }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Evaluate as this agent. Omit to evaluate against org-wide rules only." } }, "required": [ "address", "direction" ], "description": "Request body for testing an address against the configured rules" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "allowed": { "type": "boolean", "description": "Whether this address is permitted in this direction" }, "reason": { "enum": [ "no-rules", "explicit-allow", "explicit-block", "allowlist-default-deny" ], "type": "string", "description": "Why. 'allowlist-default-deny' means no rule names this address but an allow-list is active and does not cover it — the case operators most often mistake for a bug." }, "scope": { "anyOf": [ { "enum": [ "agent", "org" ], "type": "string" }, { "type": "null" } ], "description": "Which scope decided, or null when nothing matched and the default applied" }, "matchedRuleId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "The rule that decided, or null when the verdict came from a default" } }, "required": [ "allowed", "reason", "scope", "matchedRuleId" ], "description": "The verdict the send path or ingest would reach for this address" } } } } } } }, "/feedback": { "post": { "operationId": "feedback.submit", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "enum": [ "bug", "feature", "general" ], "type": "string", "description": "Category of feedback being submitted" }, "message": { "type": "string", "minLength": 1, "maxLength": 5000, "description": "Feedback message content (1-5000 characters)" }, "email": { "type": "string", "format": "email", "description": "Contact email for follow-up" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional key-value metadata for context" } }, "required": [ "type", "message" ], "description": "Input for submitting user feedback" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique feedback entry identifier" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the feedback was submitted" } }, "required": [ "id", "createdAt" ], "description": "Confirmation of submitted feedback" } } } } } }, "get": { "operationId": "feedback.list", "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Pagination cursor for fetching the next page" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of feedback entries to return per page" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "type": { "enum": [ "bug", "feature", "general" ], "type": "string", "description": "Category of feedback being submitted" }, "message": { "type": "string", "minLength": 1, "maxLength": 5000, "description": "Feedback message content (1-5000 characters)" }, "email": { "type": "string", "format": "email", "description": "Contact email for follow-up" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional key-value metadata for context" }, "id": { "type": "string", "description": "Unique feedback entry identifier" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the feedback was submitted" } }, "required": [ "type", "message", "id", "createdAt" ], "description": "Complete feedback entry with metadata" }, "description": "List of feedback entries" }, "pagination": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for retrieving the next page of results" }, "hasMore": { "type": "boolean", "description": "Whether additional results are available" } }, "required": [ "nextCursor", "hasMore" ], "description": "Pagination metadata" } }, "required": [ "items", "pagination" ], "description": "Paginated list of feedback entries" } } } } } } }, "/agents/{agentId}/did": { "get": { "operationId": "identity.getAgentDid", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "@context": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "controller": { "type": "string" }, "verificationMethod": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "controller": { "type": "string" }, "publicKeyJwk": { "type": "object", "additionalProperties": {} } }, "required": [ "id", "type", "controller" ] } }, "authentication": { "type": "array", "items": { "type": "string" } }, "assertionMethod": { "type": "array", "items": { "type": "string" } }, "service": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "serviceEndpoint": { "type": "string" } }, "required": [ "id", "type", "serviceEndpoint" ] } } }, "required": [ "@context", "id", "verificationMethod", "authentication" ], "description": "W3C DID Document" } } } } } } }, "/agents/{agentId}/did/rotate": { "post": { "operationId": "identity.rotateKeys", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "Input for rotating an agent's DID keys" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string", "description": "The agent's DID" }, "didDocument": { "type": "object", "properties": { "@context": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "controller": { "type": "string" }, "verificationMethod": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "controller": { "type": "string" }, "publicKeyJwk": { "type": "object", "additionalProperties": {} } }, "required": [ "id", "type", "controller" ] } }, "authentication": { "type": "array", "items": { "type": "string" } }, "assertionMethod": { "type": "array", "items": { "type": "string" } }, "service": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "serviceEndpoint": { "type": "string" } }, "required": [ "id", "type", "serviceEndpoint" ] } } }, "required": [ "@context", "id", "verificationMethod", "authentication" ], "description": "Updated DID Document with new keys" } }, "required": [ "did", "didDocument" ], "description": "Output after rotating agent keys" } } } } } } }, "/agents/{agentId}/credentials": { "get": { "operationId": "identity.listCredentials", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "agentId": { "type": "string" }, "orgId": { "type": "string" }, "type": { "type": "string" }, "jwtVc": { "type": "string" }, "issuerDid": { "type": "string" }, "subjectDid": { "type": "string" }, "issuedAt": { "type": "string" }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "revoked": { "type": "boolean" }, "revokedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "revocationIndex": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "agentId", "orgId", "type", "jwtVc", "issuerDid", "subjectDid", "issuedAt", "expiresAt", "revoked", "revokedAt", "revocationIndex", "metadata", "createdAt", "updatedAt" ], "description": "A Verifiable Credential record" } } } } } } }, "post": { "operationId": "identity.issueCredential", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "enum": [ "AnimaEmailVerified", "AnimaPhoneVerified", "AnimaAddressVerified", "AnimaKYBCompleted", "AnimaPaymentCapable", "AnimaOwnerBound", "AnimaTrustScore" ], "type": "string", "description": "Credential type to issue" }, "claims": { "type": "object", "additionalProperties": {}, "description": "Additional claims for the credential subject (the subject id is always the agent's DID)" }, "expiresInSeconds": { "type": "integer", "minimum": 0, "maximum": 315360000, "description": "Optional credential lifetime in seconds (omit for non-expiring)" } }, "required": [ "type" ], "description": "Input for issuing a verifiable credential to an agent (master key). Platform verification events (email OTP, phone provisioning, Stripe checkout) auto-issue AnimaEmailVerified/AnimaOwnerBound, AnimaPhoneVerified, and AnimaPaymentCapable; those types (plus AnimaKYBCompleted) derive the agent card's public verification.level and are platform-reserved — issuing them here returns 403. This endpoint issues the org-attestation types (AnimaAddressVerified, AnimaTrustScore), recorded with metadata.source=api, distinct from the platform's source=platform-auto." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "agentId": { "type": "string" }, "orgId": { "type": "string" }, "type": { "type": "string" }, "jwtVc": { "type": "string" }, "issuerDid": { "type": "string" }, "subjectDid": { "type": "string" }, "issuedAt": { "type": "string" }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "revoked": { "type": "boolean" }, "revokedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "revocationIndex": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "agentId", "orgId", "type", "jwtVc", "issuerDid", "subjectDid", "issuedAt", "expiresAt", "revoked", "revokedAt", "revocationIndex", "metadata", "createdAt", "updatedAt" ], "description": "A Verifiable Credential record" } } } } } } }, "/identity/verify": { "post": { "operationId": "identity.verifyCredential", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jwtVc": { "type": "string", "minLength": 1, "description": "The JWT-VC string to verify" } }, "required": [ "jwtVc" ], "description": "Input for verifying a verifiable credential" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "credential": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] }, "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "valid", "credential", "errors" ], "description": "Output after verifying a verifiable credential" } } } } } } }, "/agents/{agentId}/credentials/{vcId}/revoke": { "post": { "operationId": "identity.revokeCredential", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier" } }, { "name": "vcId", "in": "path", "required": true, "schema": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Verifiable Credential identifier" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "Input for revoking a verifiable credential" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "agentId": { "type": "string" }, "orgId": { "type": "string" }, "type": { "type": "string" }, "jwtVc": { "type": "string" }, "issuerDid": { "type": "string" }, "subjectDid": { "type": "string" }, "issuedAt": { "type": "string" }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "revoked": { "type": "boolean" }, "revokedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "revocationIndex": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "agentId", "orgId", "type", "jwtVc", "issuerDid", "subjectDid", "issuedAt", "expiresAt", "revoked", "revokedAt", "revocationIndex", "metadata", "createdAt", "updatedAt" ], "description": "A Verifiable Credential record" } } } } } } }, "/agents/{agentId}/card": { "get": { "operationId": "identity.getAgentCard", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string" }, "did": { "type": "string" }, "capabilities": { "type": "object", "properties": { "email": { "type": "boolean" }, "phone": { "type": "boolean" }, "vault": { "type": "boolean" }, "address": { "type": "boolean" }, "protocols": { "type": "array", "items": { "type": "string" } } }, "required": [ "email", "phone", "vault", "address", "protocols" ] }, "verification": { "type": "object", "properties": { "level": { "enum": [ "basic", "standard", "premium" ], "type": "string" }, "credentials": { "type": "array", "items": { "type": "string" } } }, "required": [ "level", "credentials" ] }, "trustScore": { "type": "number" }, "contact": { "type": "object", "properties": { "email": { "type": "string" }, "phone": { "type": "string" } } } }, "required": [ "name", "url", "did", "capabilities", "verification", "trustScore", "contact" ], "description": "Public Agent Card describing identity, capabilities, and trust posture" } } } } } } }, "/inboxes": { "post": { "operationId": "inbox.create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9._-]+$", "description": "Local part of the inbox email address (letters, numbers, dots, hyphens, underscores). Normalized to lowercase." }, "domain": { "type": "string", "description": "Domain for the inbox email address; uses the default domain if omitted" }, "displayName": { "type": "string", "maxLength": 128, "description": "Human-readable display name for the inbox (max 128 characters)" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the agent to associate with this inbox. With an agent-scoped key, defaults to the calling agent and may only name that agent; naming a different agent requires a master key. With a master key, omitting it creates a dedicated backing agent for the inbox." } }, "description": "Request body for creating a new inbox" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the inbox" }, "email": { "type": "string", "format": "email", "description": "Full email address of the inbox" }, "domain": { "type": "string", "description": "Domain portion of the inbox email address" }, "localPart": { "type": "string", "description": "Local part (before the @) of the inbox email address" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable display name, or null if not set" }, "agentId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "ID of the associated agent, or null if unassigned" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the inbox was created" } }, "required": [ "id", "email", "domain", "localPart", "displayName", "agentId", "createdAt" ], "description": "Inbox resource representation" } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "PAYMENT_REQUIRED" }, "status": { "const": 402 }, "message": { "type": "string", "default": "Creating an inbox without an agentId mints an agent, and the plan's agent limit has been reached." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "FORBIDDEN" }, "status": { "const": 403 }, "message": { "type": "string", "default": "Agents can only create inboxes for themselves." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "No such agent in this organization." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "CONFLICT" }, "status": { "const": 409 }, "message": { "type": "string", "default": "The agent already has an inbox. Each agent has exactly one." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } }, "get": { "operationId": "inbox.list", "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Opaque cursor from a previous response to fetch the next page" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of items to return per page (1–100, default 20)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "query", "in": "query", "schema": { "type": "string", "description": "Free-text search query to filter inboxes by email or display name" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "agentId", "in": "query", "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Filter to the inboxes belonging to one agent. Omit for every inbox in the org, including unassigned ones — an inbox's agent is nullable, and deleting an agent leaves its inboxes behind rather than removing them." }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the inbox" }, "email": { "type": "string", "format": "email", "description": "Full email address of the inbox" }, "domain": { "type": "string", "description": "Domain portion of the inbox email address" }, "localPart": { "type": "string", "description": "Local part (before the @) of the inbox email address" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable display name, or null if not set" }, "agentId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "ID of the associated agent, or null if unassigned" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the inbox was created" }, "unreadCount": { "type": "integer", "minimum": 0, "description": "Unread messages in this inbox — inbound mail carrying the `unread` label, excluding spam, archived and trashed. The number a mailbox list has to show to be worth reading at all." }, "lastMessageAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this inbox last sent or received anything, or null if it never has" } }, "required": [ "id", "email", "domain", "localPart", "displayName", "agentId", "createdAt", "unreadCount", "lastMessageAt" ], "description": "An inbox with its unread count, as returned in a list" }, "description": "Array of inbox resources matching the query" }, "pagination": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "Cursor to pass as the `cursor` parameter to retrieve the next page, or null if no more results" }, "hasMore": { "type": "boolean", "description": "Whether additional pages of results are available" } }, "required": [ "nextCursor", "hasMore" ], "description": "Pagination metadata for retrieving additional pages" } }, "required": [ "items", "pagination" ], "description": "Paginated list of inboxes" } } } } } } }, "/inboxes/{id}": { "get": { "operationId": "inbox.get", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique inbox identifier" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the inbox" }, "email": { "type": "string", "format": "email", "description": "Full email address of the inbox" }, "domain": { "type": "string", "description": "Domain portion of the inbox email address" }, "localPart": { "type": "string", "description": "Local part (before the @) of the inbox email address" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable display name, or null if not set" }, "agentId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "ID of the associated agent, or null if unassigned" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the inbox was created" } }, "required": [ "id", "email", "domain", "localPart", "displayName", "agentId", "createdAt" ], "description": "Inbox resource representation" } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "No such inbox in this organization." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } }, "patch": { "operationId": "inbox.update", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique inbox identifier" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Updated human-readable display name (set to null to clear)" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Move the inbox to a different agent. Not nullable: an inbox belongs to exactly one agent, so there is no unlinked state to set it to. Fails with 409 if the target agent already has an inbox." } }, "required": [], "description": "Request body for updating an existing inbox" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the inbox" }, "email": { "type": "string", "format": "email", "description": "Full email address of the inbox" }, "domain": { "type": "string", "description": "Domain portion of the inbox email address" }, "localPart": { "type": "string", "description": "Local part (before the @) of the inbox email address" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable display name, or null if not set" }, "agentId": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "ID of the associated agent, or null if unassigned" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the inbox was created" } }, "required": [ "id", "email", "domain", "localPart", "displayName", "agentId", "createdAt" ], "description": "Inbox resource representation" } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "FORBIDDEN" }, "status": { "const": 403 }, "message": { "type": "string", "default": "Updating an inbox requires master authority." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "No such inbox in this organization, or no such agent to move it to." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "CONFLICT" }, "status": { "const": 409 }, "message": { "type": "string", "default": "The target agent already has an inbox. Each agent has exactly one." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } }, "delete": { "operationId": "inbox.delete", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique inbox identifier" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "Inbox deletion parameters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true, "description": "Always true on successful deletion" } }, "required": [ "success" ], "description": "Deletion confirmation" } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "FORBIDDEN" }, "status": { "const": 403 }, "message": { "type": "string", "default": "Deleting an inbox requires master authority." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "No such inbox in this organization." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } } }, "/domains": { "post": { "operationId": "domain.add", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "Domain name to add (automatically lowercased)" } }, "required": [ "domain" ], "description": "Request body for adding a new custom domain" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the domain" }, "domain": { "type": "string", "description": "Fully qualified domain name" }, "status": { "enum": [ "NOT_STARTED", "PENDING", "VERIFYING", "VERIFIED", "INVALID", "FAILED" ], "type": "string", "description": "Current verification status" }, "verified": { "type": "boolean", "description": "Whether the domain has been fully verified" }, "verificationCooldownUntil": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Earliest time a re-verification can be attempted, or null if no cooldown" }, "verificationToken": { "type": "string", "description": "Token value to place in DNS records for verification" }, "verificationMethod": { "enum": [ "DNS_TXT", "DNS_CNAME" ], "type": "string", "description": "DNS record method used for domain verification" }, "dkimSelector": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "DKIM selector used for email signing, or null if not configured" }, "dkimPublicKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "DKIM public key for DNS publication, or null if not configured" }, "spfConfigured": { "type": "boolean", "description": "Whether SPF DNS records are correctly configured" }, "dmarcConfigured": { "type": "boolean", "description": "Whether DMARC DNS records are correctly configured" }, "mxConfigured": { "type": "boolean", "description": "Whether MX DNS records are correctly configured" }, "feedbackEnabled": { "type": "boolean", "description": "Whether bounce and complaint feedback processing is enabled" }, "records": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "type": { "enum": [ "TXT", "CNAME", "MX" ], "type": "string", "description": "DNS record type" }, "name": { "type": "string", "description": "DNS record hostname" }, "value": { "type": "string", "description": "Expected DNS record value" }, "priority": { "type": "integer", "description": "MX record priority (only applicable for MX records)" }, "status": { "enum": [ "MISSING", "INVALID", "VALID" ], "type": "string", "description": "Current validation status of this DNS record" } }, "required": [ "type", "name", "value", "status" ], "description": "DNS record required for domain verification and email deliverability" } }, { "type": "null" } ], "description": "Required DNS records for this domain, or null if not yet generated" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the domain was added" } }, "required": [ "id", "domain", "status", "verified", "verificationCooldownUntil", "verificationToken", "verificationMethod", "dkimSelector", "dkimPublicKey", "spfConfigured", "dmarcConfigured", "mxConfigured", "feedbackEnabled", "records", "createdAt" ], "description": "Full domain resource representation with verification and DNS status" } } } } } }, "get": { "operationId": "domain.list", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the domain" }, "domain": { "type": "string", "description": "Fully qualified domain name" }, "status": { "enum": [ "NOT_STARTED", "PENDING", "VERIFYING", "VERIFIED", "INVALID", "FAILED" ], "type": "string", "description": "Current verification status" }, "verified": { "type": "boolean", "description": "Whether the domain has been fully verified" }, "verificationCooldownUntil": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Earliest time a re-verification can be attempted, or null if no cooldown" }, "verificationToken": { "type": "string", "description": "Token value to place in DNS records for verification" }, "verificationMethod": { "enum": [ "DNS_TXT", "DNS_CNAME" ], "type": "string", "description": "DNS record method used for domain verification" }, "dkimSelector": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "DKIM selector used for email signing, or null if not configured" }, "dkimPublicKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "DKIM public key for DNS publication, or null if not configured" }, "spfConfigured": { "type": "boolean", "description": "Whether SPF DNS records are correctly configured" }, "dmarcConfigured": { "type": "boolean", "description": "Whether DMARC DNS records are correctly configured" }, "mxConfigured": { "type": "boolean", "description": "Whether MX DNS records are correctly configured" }, "feedbackEnabled": { "type": "boolean", "description": "Whether bounce and complaint feedback processing is enabled" }, "records": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "type": { "enum": [ "TXT", "CNAME", "MX" ], "type": "string", "description": "DNS record type" }, "name": { "type": "string", "description": "DNS record hostname" }, "value": { "type": "string", "description": "Expected DNS record value" }, "priority": { "type": "integer", "description": "MX record priority (only applicable for MX records)" }, "status": { "enum": [ "MISSING", "INVALID", "VALID" ], "type": "string", "description": "Current validation status of this DNS record" } }, "required": [ "type", "name", "value", "status" ], "description": "DNS record required for domain verification and email deliverability" } }, { "type": "null" } ], "description": "Required DNS records for this domain, or null if not yet generated" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the domain was added" } }, "required": [ "id", "domain", "status", "verified", "verificationCooldownUntil", "verificationToken", "verificationMethod", "dkimSelector", "dkimPublicKey", "spfConfigured", "dmarcConfigured", "mxConfigured", "feedbackEnabled", "records", "createdAt" ], "description": "Full domain resource representation with verification and DNS status" }, "description": "List of domains" } }, "required": [ "items" ], "description": "Domain list response" } } } } } } }, "/domains/{id}": { "patch": { "operationId": "domain.update", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique domain identifier" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "feedbackEnabled": { "type": "boolean", "description": "Whether to enable bounce and complaint feedback processing for this domain" } }, "required": [], "description": "Domain update parameters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the domain" }, "domain": { "type": "string", "description": "Fully qualified domain name" }, "status": { "enum": [ "NOT_STARTED", "PENDING", "VERIFYING", "VERIFIED", "INVALID", "FAILED" ], "type": "string", "description": "Current verification status" }, "verified": { "type": "boolean", "description": "Whether the domain has been fully verified" }, "verificationCooldownUntil": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Earliest time a re-verification can be attempted, or null if no cooldown" }, "verificationToken": { "type": "string", "description": "Token value to place in DNS records for verification" }, "verificationMethod": { "enum": [ "DNS_TXT", "DNS_CNAME" ], "type": "string", "description": "DNS record method used for domain verification" }, "dkimSelector": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "DKIM selector used for email signing, or null if not configured" }, "dkimPublicKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "DKIM public key for DNS publication, or null if not configured" }, "spfConfigured": { "type": "boolean", "description": "Whether SPF DNS records are correctly configured" }, "dmarcConfigured": { "type": "boolean", "description": "Whether DMARC DNS records are correctly configured" }, "mxConfigured": { "type": "boolean", "description": "Whether MX DNS records are correctly configured" }, "feedbackEnabled": { "type": "boolean", "description": "Whether bounce and complaint feedback processing is enabled" }, "records": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "type": { "enum": [ "TXT", "CNAME", "MX" ], "type": "string", "description": "DNS record type" }, "name": { "type": "string", "description": "DNS record hostname" }, "value": { "type": "string", "description": "Expected DNS record value" }, "priority": { "type": "integer", "description": "MX record priority (only applicable for MX records)" }, "status": { "enum": [ "MISSING", "INVALID", "VALID" ], "type": "string", "description": "Current validation status of this DNS record" } }, "required": [ "type", "name", "value", "status" ], "description": "DNS record required for domain verification and email deliverability" } }, { "type": "null" } ], "description": "Required DNS records for this domain, or null if not yet generated" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the domain was added" } }, "required": [ "id", "domain", "status", "verified", "verificationCooldownUntil", "verificationToken", "verificationMethod", "dkimSelector", "dkimPublicKey", "spfConfigured", "dmarcConfigured", "mxConfigured", "feedbackEnabled", "records", "createdAt" ], "description": "Full domain resource representation with verification and DNS status" } } } } } }, "get": { "operationId": "domain.get", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique domain identifier" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the domain" }, "domain": { "type": "string", "description": "Fully qualified domain name" }, "status": { "enum": [ "NOT_STARTED", "PENDING", "VERIFYING", "VERIFIED", "INVALID", "FAILED" ], "type": "string", "description": "Current verification status" }, "verified": { "type": "boolean", "description": "Whether the domain has been fully verified" }, "verificationCooldownUntil": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Earliest time a re-verification can be attempted, or null if no cooldown" }, "verificationToken": { "type": "string", "description": "Token value to place in DNS records for verification" }, "verificationMethod": { "enum": [ "DNS_TXT", "DNS_CNAME" ], "type": "string", "description": "DNS record method used for domain verification" }, "dkimSelector": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "DKIM selector used for email signing, or null if not configured" }, "dkimPublicKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "DKIM public key for DNS publication, or null if not configured" }, "spfConfigured": { "type": "boolean", "description": "Whether SPF DNS records are correctly configured" }, "dmarcConfigured": { "type": "boolean", "description": "Whether DMARC DNS records are correctly configured" }, "mxConfigured": { "type": "boolean", "description": "Whether MX DNS records are correctly configured" }, "feedbackEnabled": { "type": "boolean", "description": "Whether bounce and complaint feedback processing is enabled" }, "records": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "type": { "enum": [ "TXT", "CNAME", "MX" ], "type": "string", "description": "DNS record type" }, "name": { "type": "string", "description": "DNS record hostname" }, "value": { "type": "string", "description": "Expected DNS record value" }, "priority": { "type": "integer", "description": "MX record priority (only applicable for MX records)" }, "status": { "enum": [ "MISSING", "INVALID", "VALID" ], "type": "string", "description": "Current validation status of this DNS record" } }, "required": [ "type", "name", "value", "status" ], "description": "DNS record required for domain verification and email deliverability" } }, { "type": "null" } ], "description": "Required DNS records for this domain, or null if not yet generated" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the domain was added" } }, "required": [ "id", "domain", "status", "verified", "verificationCooldownUntil", "verificationToken", "verificationMethod", "dkimSelector", "dkimPublicKey", "spfConfigured", "dmarcConfigured", "mxConfigured", "feedbackEnabled", "records", "createdAt" ], "description": "Full domain resource representation with verification and DNS status" } } } } } }, "delete": { "operationId": "domain.delete", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique domain identifier" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "Domain deletion parameters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true, "description": "Always true on successful deletion" } }, "required": [ "success" ], "description": "Deletion confirmation" } } } } } } }, "/domains/{id}/verify": { "post": { "operationId": "domain.verify", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique domain identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domainId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the domain to verify" } }, "required": [ "domainId" ], "description": "Domain verification parameters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the domain" }, "domain": { "type": "string", "description": "Fully qualified domain name" }, "status": { "enum": [ "NOT_STARTED", "PENDING", "VERIFYING", "VERIFIED", "INVALID", "FAILED" ], "type": "string", "description": "Current verification status" }, "verified": { "type": "boolean", "description": "Whether the domain has been fully verified" }, "verificationCooldownUntil": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Earliest time a re-verification can be attempted, or null if no cooldown" }, "verificationToken": { "type": "string", "description": "Token value to place in DNS records for verification" }, "verificationMethod": { "enum": [ "DNS_TXT", "DNS_CNAME" ], "type": "string", "description": "DNS record method used for domain verification" }, "dkimSelector": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "DKIM selector used for email signing, or null if not configured" }, "dkimPublicKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "DKIM public key for DNS publication, or null if not configured" }, "spfConfigured": { "type": "boolean", "description": "Whether SPF DNS records are correctly configured" }, "dmarcConfigured": { "type": "boolean", "description": "Whether DMARC DNS records are correctly configured" }, "mxConfigured": { "type": "boolean", "description": "Whether MX DNS records are correctly configured" }, "feedbackEnabled": { "type": "boolean", "description": "Whether bounce and complaint feedback processing is enabled" }, "records": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "type": { "enum": [ "TXT", "CNAME", "MX" ], "type": "string", "description": "DNS record type" }, "name": { "type": "string", "description": "DNS record hostname" }, "value": { "type": "string", "description": "Expected DNS record value" }, "priority": { "type": "integer", "description": "MX record priority (only applicable for MX records)" }, "status": { "enum": [ "MISSING", "INVALID", "VALID" ], "type": "string", "description": "Current validation status of this DNS record" } }, "required": [ "type", "name", "value", "status" ], "description": "DNS record required for domain verification and email deliverability" } }, { "type": "null" } ], "description": "Required DNS records for this domain, or null if not yet generated" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the domain was added" } }, "required": [ "id", "domain", "status", "verified", "verificationCooldownUntil", "verificationToken", "verificationMethod", "dkimSelector", "dkimPublicKey", "spfConfigured", "dmarcConfigured", "mxConfigured", "feedbackEnabled", "records", "createdAt" ], "description": "Full domain resource representation with verification and DNS status" } } } } } } }, "/domains/{id}/dns-records": { "get": { "operationId": "domain.dnsRecords", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique domain identifier" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "txt": { "type": "object", "properties": { "name": { "type": "string", "description": "Hostname for the TXT verification record" }, "value": { "type": "string", "description": "Value for the TXT verification record" } }, "required": [ "name", "value" ], "description": "TXT record for domain ownership verification" }, "mailFrom": { "type": "object", "properties": { "name": { "type": "string", "description": "Hostname for the MAIL FROM subdomain" }, "mx": { "type": "object", "properties": { "value": { "type": "string", "description": "MX target for the MAIL FROM subdomain" }, "priority": { "type": "integer", "description": "MX record priority" } }, "required": [ "value", "priority" ], "description": "MX record for the MAIL FROM subdomain" }, "spf": { "type": "string", "description": "SPF record value for the MAIL FROM subdomain" } }, "required": [ "name", "mx", "spf" ], "description": "MAIL FROM configuration for bounce handling" }, "dkim": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "DKIM selector hostname" }, "value": { "type": "string", "description": "DKIM public key CNAME target" } }, "required": [ "name", "value" ], "description": "Individual DKIM key record" }, "description": "DKIM signing key records for email authentication" }, "mx": { "type": "object", "properties": { "name": { "type": "string", "description": "Hostname for the MX record" }, "value": { "type": "string", "description": "Mail server target for the MX record" }, "priority": { "type": "integer", "description": "MX record priority" } }, "required": [ "name", "value", "priority" ], "description": "MX record for inbound email routing" }, "spf": { "type": "string", "description": "SPF record value for the root domain" }, "dmarc": { "type": "string", "description": "DMARC policy record value" } }, "required": [ "txt", "mailFrom", "dkim", "mx", "spf", "dmarc" ], "description": "Complete set of DNS records required for email deliverability" } } } } } } }, "/domains/{id}/zone-file": { "get": { "operationId": "domain.zoneFile", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique domain identifier" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "zoneFile": { "type": "string", "description": "Complete DNS zone file content for configuring the domain" } }, "required": [ "zoneFile" ], "description": "Generated DNS zone file for a domain" } } } } } } }, "/domains/{id}/deliverability": { "get": { "operationId": "domain.deliverability", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique domain identifier" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "Domain these statistics apply to" }, "sent": { "type": "integer", "minimum": 0, "description": "Total number of emails sent" }, "delivered": { "type": "integer", "minimum": 0, "description": "Number of emails successfully delivered" }, "bounced": { "type": "integer", "minimum": 0, "description": "Number of emails that bounced" }, "complained": { "type": "integer", "minimum": 0, "description": "Number of emails marked as spam by recipients" }, "bounceRate": { "type": "number", "minimum": 0, "description": "Bounce rate as a decimal (e.g. 0.02 for 2%)" }, "complaintRate": { "type": "number", "minimum": 0, "description": "Complaint rate as a decimal (e.g. 0.001 for 0.1%)" }, "isHealthy": { "type": "boolean", "description": "Whether deliverability metrics are within acceptable thresholds" }, "dmarc": { "type": "object", "properties": { "reportCount": { "type": "integer", "minimum": 0, "description": "Number of DMARC aggregate reports received in the window" }, "messages": { "type": "integer", "minimum": 0, "description": "Total messages covered by those reports, as counted by the reporting providers" }, "passed": { "type": "integer", "minimum": 0, "description": "Messages that passed DMARC — DKIM or SPF authenticated AND aligned with the From domain" }, "failed": { "type": "integer", "minimum": 0, "description": "Messages that failed DMARC — neither DKIM nor SPF aligned. Spoofing, or a legitimate sender you have not authorized" }, "passRate": { "type": "number", "minimum": 0, "description": "Fraction of reported messages that passed DMARC (0-1). 0 when no messages were reported" }, "quarantined": { "type": "integer", "minimum": 0, "description": "Messages the receiving provider quarantined under your published policy" }, "rejected": { "type": "integer", "minimum": 0, "description": "Messages the receiving provider rejected under your published policy" }, "reporters": { "type": "array", "items": { "type": "string" }, "description": "Providers that sent reports in the window (e.g. google.com, outlook.com)" }, "topSources": { "type": "array", "items": { "type": "object", "properties": { "sourceIp": { "type": "string", "description": "IP address that sent mail claiming to be from this domain" }, "messages": { "type": "integer", "minimum": 0, "description": "Messages seen from this source in the window" }, "passed": { "type": "integer", "minimum": 0, "description": "Messages from this source that passed DMARC (DKIM or SPF aligned)" }, "failed": { "type": "integer", "minimum": 0, "description": "Messages from this source that failed DMARC (neither DKIM nor SPF aligned)" } }, "required": [ "sourceIp", "messages", "passed", "failed" ], "description": "One sending source seen in DMARC aggregate reports" }, "description": "Busiest sending sources in the window, most messages first" }, "topFailingSources": { "type": "array", "items": { "type": "object", "properties": { "sourceIp": { "type": "string", "description": "IP address that sent mail claiming to be from this domain" }, "messages": { "type": "integer", "minimum": 0, "description": "Messages seen from this source in the window" }, "passed": { "type": "integer", "minimum": 0, "description": "Messages from this source that passed DMARC (DKIM or SPF aligned)" }, "failed": { "type": "integer", "minimum": 0, "description": "Messages from this source that failed DMARC (neither DKIM nor SPF aligned)" } }, "required": [ "sourceIp", "messages", "passed", "failed" ], "description": "One sending source seen in DMARC aggregate reports" }, "description": "Sources with the most DMARC failures, most failures first — where to look for spoofing or an unauthorized sender" }, "lastReportAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "End of the most recent reporting period, or null if no reports have been received" }, "windowDays": { "type": "integer", "minimum": 0, "description": "Length of the reporting window these figures cover, in days" } }, "required": [ "reportCount", "messages", "passed", "failed", "passRate", "quarantined", "rejected", "reporters", "topSources", "topFailingSources", "lastReportAt", "windowDays" ], "description": "DMARC aggregate reports received for this domain, summarizing how receiving mail providers authenticated mail claiming to be from it" } }, "required": [ "domain", "sent", "delivered", "bounced", "complained", "bounceRate", "complaintRate", "isHealthy", "dmarc" ], "description": "Email deliverability statistics for a domain" } } } } } } }, "/webhooks": { "post": { "operationId": "webhook.create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "HTTPS endpoint URL that will receive webhook POST payloads" }, "events": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9_*]+(\\.[a-z0-9_*]+)*$", "description": "Event name or glob pattern. Examples: 'message.received', 'message.*', 'call.ended', '*'." }, "description": "List of event types this webhook subscribes to" }, "description": { "type": "string", "description": "Optional human-readable label for this webhook" }, "active": { "default": true, "type": "boolean", "description": "Whether the webhook is active and receiving events" }, "authConfig": { "anyOf": [ { "type": "object", "properties": { "type": { "const": "none" } }, "required": [ "type" ], "description": "No customer auth header (the HMAC signature is still sent)" }, { "type": "object", "properties": { "type": { "const": "bearer" }, "token": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Sent as `Authorization: Bearer `" } }, "required": [ "type", "token" ] }, { "type": "object", "properties": { "type": { "const": "basic" }, "username": { "type": "string", "minLength": 1, "maxLength": 256 }, "password": { "type": "string", "minLength": 1, "maxLength": 1024 } }, "required": [ "type", "username", "password" ], "description": "Sent as `Authorization: Basic `" }, { "type": "object", "properties": { "type": { "const": "custom_header" }, "headerName": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9!#$%&'*+.^_`|~-]+$" }, "value": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "type", "headerName", "value" ], "description": "Sent as a custom header `: `" } ], "description": "Auth the platform presents to your endpoint (in addition to the HMAC signature)" }, "rateLimitPerMinute": { "type": "integer", "minimum": 0, "maximum": 100000, "description": "Max deliveries per minute to this endpoint; omit for unlimited" }, "maxAttempts": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Max delivery attempts before dead-lettering (default 3)" } }, "required": [ "url", "events" ], "description": "Request body for creating a new webhook subscription" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-z]+$", "description": "Unique identifier for the webhook" }, "orgId": { "type": "string", "pattern": "^[0-9a-z]+$", "description": "Organization that owns this webhook" }, "url": { "type": "string", "format": "uri", "description": "HTTPS endpoint URL receiving webhook payloads" }, "events": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9_*]+(\\.[a-z0-9_*]+)*$", "description": "Event name or glob pattern. Examples: 'message.received', 'message.*', 'call.ended', '*'." }, "description": "Event types this webhook is subscribed to" }, "active": { "type": "boolean", "description": "Whether the webhook is currently active" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable label for this webhook" }, "consecutiveFailures": { "type": "integer", "minimum": 0, "description": "Number of consecutive delivery failures across all events" }, "disabledReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason the webhook was auto-disabled, null if manually disabled or active" }, "disabledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp when the webhook was auto-disabled" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the webhook was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the webhook was last modified" }, "authType": { "enum": [ "NONE", "BEARER", "BASIC", "CUSTOM_HEADER" ], "type": "string", "description": "Auth scheme the platform presents to your endpoint (never includes the secret)" }, "authHeaderName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Header name for CUSTOM_HEADER auth; null for other schemes" }, "rateLimitPerMinute": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Per-endpoint delivery rate cap in requests/minute; null = unlimited" }, "maxAttempts": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Per-webhook max delivery attempts; null = platform default (3)" }, "secret": { "type": "string", "description": "The signing secret, returned ONLY at creation time. Store it now — read endpoints (get/list) never return it again. Use it to verify the X-Anima-Signature header on every delivery. If lost, rotate via POST /webhooks/{id}/rotate-secret." } }, "required": [ "id", "orgId", "url", "events", "active", "description", "consecutiveFailures", "disabledReason", "disabledAt", "createdAt", "updatedAt", "authType", "authHeaderName", "rateLimitPerMinute", "maxAttempts", "secret" ], "description": "Newly created webhook, including its one-time signing secret" } } } } } }, "get": { "operationId": "webhook.list", "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Opaque cursor from a previous response to fetch the next page" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of items to return per page (1–100, default 20)" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-z]+$", "description": "Unique identifier for the webhook" }, "orgId": { "type": "string", "pattern": "^[0-9a-z]+$", "description": "Organization that owns this webhook" }, "url": { "type": "string", "format": "uri", "description": "HTTPS endpoint URL receiving webhook payloads" }, "events": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9_*]+(\\.[a-z0-9_*]+)*$", "description": "Event name or glob pattern. Examples: 'message.received', 'message.*', 'call.ended', '*'." }, "description": "Event types this webhook is subscribed to" }, "active": { "type": "boolean", "description": "Whether the webhook is currently active" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable label for this webhook" }, "consecutiveFailures": { "type": "integer", "minimum": 0, "description": "Number of consecutive delivery failures across all events" }, "disabledReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason the webhook was auto-disabled, null if manually disabled or active" }, "disabledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp when the webhook was auto-disabled" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the webhook was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the webhook was last modified" }, "authType": { "enum": [ "NONE", "BEARER", "BASIC", "CUSTOM_HEADER" ], "type": "string", "description": "Auth scheme the platform presents to your endpoint (never includes the secret)" }, "authHeaderName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Header name for CUSTOM_HEADER auth; null for other schemes" }, "rateLimitPerMinute": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Per-endpoint delivery rate cap in requests/minute; null = unlimited" }, "maxAttempts": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Per-webhook max delivery attempts; null = platform default (3)" } }, "required": [ "id", "orgId", "url", "events", "active", "description", "consecutiveFailures", "disabledReason", "disabledAt", "createdAt", "updatedAt", "authType", "authHeaderName", "rateLimitPerMinute", "maxAttempts" ], "description": "Webhook subscription resource" }, "description": "Array of webhook resources in the current page" }, "pagination": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "Cursor to pass as the `cursor` parameter to retrieve the next page, or null if no more results" }, "hasMore": { "type": "boolean", "description": "Whether additional pages of results are available" } }, "required": [ "nextCursor", "hasMore" ], "description": "Cursor-based pagination metadata" } }, "required": [ "items", "pagination" ], "description": "Paginated list of webhook subscriptions" } } } } } } }, "/webhooks/{id}/rotate-secret": { "post": { "operationId": "webhook.rotateSecret", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-z]+$", "description": "Unique identifier of the webhook whose secret to rotate" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "Request body for rotating a webhook signing secret" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-z]+$", "description": "Unique identifier of the webhook" }, "secret": { "type": "string", "description": "The new signing secret, returned only once. Update your receiver to verify with this value; the previous secret stops working immediately." } }, "required": [ "id", "secret" ], "description": "Result of rotating a webhook signing secret" } } } } } } }, "/webhooks/{id}": { "get": { "operationId": "webhook.get", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-z]+$", "description": "Unique webhook identifier" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-z]+$", "description": "Unique identifier for the webhook" }, "orgId": { "type": "string", "pattern": "^[0-9a-z]+$", "description": "Organization that owns this webhook" }, "url": { "type": "string", "format": "uri", "description": "HTTPS endpoint URL receiving webhook payloads" }, "events": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9_*]+(\\.[a-z0-9_*]+)*$", "description": "Event name or glob pattern. Examples: 'message.received', 'message.*', 'call.ended', '*'." }, "description": "Event types this webhook is subscribed to" }, "active": { "type": "boolean", "description": "Whether the webhook is currently active" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable label for this webhook" }, "consecutiveFailures": { "type": "integer", "minimum": 0, "description": "Number of consecutive delivery failures across all events" }, "disabledReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason the webhook was auto-disabled, null if manually disabled or active" }, "disabledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp when the webhook was auto-disabled" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the webhook was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the webhook was last modified" }, "authType": { "enum": [ "NONE", "BEARER", "BASIC", "CUSTOM_HEADER" ], "type": "string", "description": "Auth scheme the platform presents to your endpoint (never includes the secret)" }, "authHeaderName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Header name for CUSTOM_HEADER auth; null for other schemes" }, "rateLimitPerMinute": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Per-endpoint delivery rate cap in requests/minute; null = unlimited" }, "maxAttempts": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Per-webhook max delivery attempts; null = platform default (3)" } }, "required": [ "id", "orgId", "url", "events", "active", "description", "consecutiveFailures", "disabledReason", "disabledAt", "createdAt", "updatedAt", "authType", "authHeaderName", "rateLimitPerMinute", "maxAttempts" ], "description": "Webhook subscription resource" } } } } } }, "put": { "operationId": "webhook.update", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-z]+$", "description": "Unique identifier of the webhook to update" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "New HTTPS endpoint URL for webhook delivery" }, "events": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9_*]+(\\.[a-z0-9_*]+)*$", "description": "Event name or glob pattern. Examples: 'message.received', 'message.*', 'call.ended', '*'." }, "description": "Updated list of subscribed event types" }, "description": { "type": "string", "description": "Updated human-readable label for this webhook" }, "active": { "type": "boolean", "description": "Set to false to pause webhook delivery without deleting" }, "authConfig": { "anyOf": [ { "type": "object", "properties": { "type": { "const": "none" } }, "required": [ "type" ], "description": "No customer auth header (the HMAC signature is still sent)" }, { "type": "object", "properties": { "type": { "const": "bearer" }, "token": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Sent as `Authorization: Bearer `" } }, "required": [ "type", "token" ] }, { "type": "object", "properties": { "type": { "const": "basic" }, "username": { "type": "string", "minLength": 1, "maxLength": 256 }, "password": { "type": "string", "minLength": 1, "maxLength": 1024 } }, "required": [ "type", "username", "password" ], "description": "Sent as `Authorization: Basic `" }, { "type": "object", "properties": { "type": { "const": "custom_header" }, "headerName": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9!#$%&'*+.^_`|~-]+$" }, "value": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "type", "headerName", "value" ], "description": "Sent as a custom header `: `" } ], "description": "Replace the endpoint auth; pass { type: 'none' } to remove it" }, "rateLimitPerMinute": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100000 }, { "type": "null" } ], "description": "Max deliveries/minute; null clears it (unlimited)" }, "maxAttempts": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 10 }, { "type": "null" } ], "description": "Max delivery attempts; null resets to platform default (3)" } }, "required": [], "description": "Request body for updating an existing webhook subscription" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-z]+$", "description": "Unique identifier for the webhook" }, "orgId": { "type": "string", "pattern": "^[0-9a-z]+$", "description": "Organization that owns this webhook" }, "url": { "type": "string", "format": "uri", "description": "HTTPS endpoint URL receiving webhook payloads" }, "events": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9_*]+(\\.[a-z0-9_*]+)*$", "description": "Event name or glob pattern. Examples: 'message.received', 'message.*', 'call.ended', '*'." }, "description": "Event types this webhook is subscribed to" }, "active": { "type": "boolean", "description": "Whether the webhook is currently active" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable label for this webhook" }, "consecutiveFailures": { "type": "integer", "minimum": 0, "description": "Number of consecutive delivery failures across all events" }, "disabledReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason the webhook was auto-disabled, null if manually disabled or active" }, "disabledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp when the webhook was auto-disabled" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the webhook was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the webhook was last modified" }, "authType": { "enum": [ "NONE", "BEARER", "BASIC", "CUSTOM_HEADER" ], "type": "string", "description": "Auth scheme the platform presents to your endpoint (never includes the secret)" }, "authHeaderName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Header name for CUSTOM_HEADER auth; null for other schemes" }, "rateLimitPerMinute": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Per-endpoint delivery rate cap in requests/minute; null = unlimited" }, "maxAttempts": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Per-webhook max delivery attempts; null = platform default (3)" } }, "required": [ "id", "orgId", "url", "events", "active", "description", "consecutiveFailures", "disabledReason", "disabledAt", "createdAt", "updatedAt", "authType", "authHeaderName", "rateLimitPerMinute", "maxAttempts" ], "description": "Webhook subscription resource" } } } } } }, "delete": { "operationId": "webhook.delete", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-z]+$", "description": "Unique webhook identifier" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "Webhook deletion parameters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true, "description": "Always true on successful deletion" } }, "required": [ "success" ], "description": "Deletion confirmation" } } } } } } }, "/webhooks/{id}/test": { "post": { "operationId": "webhook.test", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-z]+$", "description": "Unique identifier of the webhook to test" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "default": "message.received", "enum": [ "message.received", "message.received.auto", "message.sent", "message.failed", "message.bounced", "message.loop_detected", "agent.created", "agent.updated", "agent.deleted", "phone.provisioned", "phone.released", "call.summary.ready", "call.score.ready", "call.security.alert", "call.security.scan.ready", "call.started", "call.ended", "a2a.task.received", "vault.credential.refresh_failed" ], "type": "string", "description": "Event type to simulate in the test delivery" } }, "required": [], "description": "Request body for sending a test payload to a webhook endpoint" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true, "description": "Always true when the test delivery was dispatched" }, "deliveryId": { "type": "string", "pattern": "^[0-9a-z]+$", "description": "Unique identifier of the test delivery" } }, "required": [ "success", "deliveryId" ], "description": "Webhook test result" } } } } } } }, "/webhooks/{webhookId}/deliveries": { "get": { "operationId": "webhook.listDeliveries", "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-z]+$", "description": "Filter deliveries to this specific webhook" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Opaque cursor from a previous response to fetch the next page" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of items to return per page (1–100, default 20)" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-z]+$", "description": "Unique identifier for this delivery attempt record" }, "webhookId": { "type": "string", "pattern": "^[0-9a-z]+$", "description": "Webhook subscription this delivery belongs to" }, "messageId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "null" } ], "description": "Associated message ID if the event is message-related" }, "event": { "enum": [ "message.received", "message.received.auto", "message.sent", "message.failed", "message.bounced", "message.loop_detected", "agent.created", "agent.updated", "agent.deleted", "phone.provisioned", "phone.released", "call.summary.ready", "call.score.ready", "call.security.alert", "call.security.scan.ready", "call.started", "call.ended", "a2a.task.received", "vault.credential.refresh_failed" ], "type": "string", "description": "Event type that triggered this delivery" }, "payload": { "type": "object", "additionalProperties": {}, "description": "JSON payload that was sent to the webhook endpoint" }, "statusCode": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "HTTP status code returned by the endpoint, null if delivery failed" }, "responseBody": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Response body returned by the endpoint, null if delivery failed" }, "attempts": { "type": "integer", "minimum": 0, "description": "Number of delivery attempts made so far" }, "maxAttempts": { "type": "integer", "minimum": 0, "description": "Maximum number of delivery attempts before giving up" }, "nextAttemptAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp of the next scheduled retry, null if completed or exhausted" }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp when delivery succeeded or was abandoned" }, "status": { "enum": [ "PENDING", "IN_FLIGHT", "SUCCEEDED", "RETRYING", "DEAD_LETTERED" ], "type": "string", "description": "Lifecycle status of this delivery attempt" }, "lastError": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last error message if the delivery is retrying or dead-lettered" }, "deadLetteredAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the delivery moved to the DLQ (null if still in flight or succeeded)" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the delivery was first attempted" } }, "required": [ "id", "webhookId", "messageId", "event", "payload", "statusCode", "responseBody", "attempts", "maxAttempts", "nextAttemptAt", "completedAt", "status", "lastError", "deadLetteredAt", "createdAt" ], "description": "Record of a single webhook delivery attempt including status and retry information" }, "description": "Array of webhook delivery records in the current page" }, "pagination": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "Cursor to pass as the `cursor` parameter to retrieve the next page, or null if no more results" }, "hasMore": { "type": "boolean", "description": "Whether additional pages of results are available" } }, "required": [ "nextCursor", "hasMore" ], "description": "Cursor-based pagination metadata" } }, "required": [ "items", "pagination" ], "description": "Paginated list of webhook delivery records" } } } } } } }, "/webhooks/{id}/reenable": { "post": { "operationId": "webhook.reenable", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-z]+$", "description": "Unique identifier of the webhook to re-enable" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "Request body for testing and re-enabling a disabled webhook" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true, "description": "Always true when the webhook was re-enabled" }, "deliveryId": { "type": "string", "pattern": "^[0-9a-z]+$", "description": "Unique identifier of the test delivery sent" } }, "required": [ "success", "deliveryId" ], "description": "Re-enable result after successful test delivery" } } } } } } }, "/webhooks/{id}/stats": { "get": { "operationId": "webhook.stats", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-z]+$", "description": "Unique identifier of the webhook to get stats for" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalDeliveries": { "type": "integer", "minimum": 0, "description": "Total number of deliveries ever created" }, "succeeded": { "type": "integer", "minimum": 0, "description": "Number of deliveries that completed successfully" }, "failed": { "type": "integer", "minimum": 0, "description": "Number of deliveries that exhausted all retries" }, "pending": { "type": "integer", "minimum": 0, "description": "Number of deliveries awaiting retry" }, "successRate": { "type": "number", "minimum": 0, "maximum": 100, "description": "Percentage of successful deliveries" } }, "required": [ "totalDeliveries", "succeeded", "failed", "pending", "successRate" ], "description": "Aggregate delivery statistics for a webhook endpoint" } } } } } } }, "/webhooks/deliveries/{deliveryId}/replay": { "post": { "operationId": "webhook.replayDelivery", "parameters": [ { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-z]+$", "description": "Delivery to re-enqueue" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "Replay a dead-lettered webhook delivery" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "deliveryId": { "type": "string", "pattern": "^[0-9a-z]+$" } }, "required": [ "success", "deliveryId" ], "description": "Replay confirmation" } } } } } } }, "/webhooks/{webhookId}/dead-letters": { "get": { "operationId": "webhook.listDeadLetters", "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-z]+$", "description": "Webhook whose dead-lettered deliveries to list" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Opaque cursor from a previous response to fetch the next page" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of items to return per page (1–100, default 20)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "event", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9_*]+(\\.[a-z0-9_*]+)*$", "description": "Optional exact event name filter — does not accept globs" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Optional ISO 8601 lower bound on deadLetteredAt" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Optional ISO 8601 upper bound on deadLetteredAt" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-z]+$", "description": "Unique identifier for this delivery attempt record" }, "webhookId": { "type": "string", "pattern": "^[0-9a-z]+$", "description": "Webhook subscription this delivery belongs to" }, "messageId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "null" } ], "description": "Associated message ID if the event is message-related" }, "event": { "enum": [ "message.received", "message.received.auto", "message.sent", "message.failed", "message.bounced", "message.loop_detected", "agent.created", "agent.updated", "agent.deleted", "phone.provisioned", "phone.released", "call.summary.ready", "call.score.ready", "call.security.alert", "call.security.scan.ready", "call.started", "call.ended", "a2a.task.received", "vault.credential.refresh_failed" ], "type": "string", "description": "Event type that triggered this delivery" }, "payload": { "type": "object", "additionalProperties": {}, "description": "JSON payload that was sent to the webhook endpoint" }, "statusCode": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "HTTP status code returned by the endpoint, null if delivery failed" }, "responseBody": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Response body returned by the endpoint, null if delivery failed" }, "attempts": { "type": "integer", "minimum": 0, "description": "Number of delivery attempts made so far" }, "maxAttempts": { "type": "integer", "minimum": 0, "description": "Maximum number of delivery attempts before giving up" }, "nextAttemptAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp of the next scheduled retry, null if completed or exhausted" }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp when delivery succeeded or was abandoned" }, "status": { "enum": [ "PENDING", "IN_FLIGHT", "SUCCEEDED", "RETRYING", "DEAD_LETTERED" ], "type": "string", "description": "Lifecycle status of this delivery attempt" }, "lastError": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last error message if the delivery is retrying or dead-lettered" }, "deadLetteredAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the delivery moved to the DLQ (null if still in flight or succeeded)" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the delivery was first attempted" } }, "required": [ "id", "webhookId", "messageId", "event", "payload", "statusCode", "responseBody", "attempts", "maxAttempts", "nextAttemptAt", "completedAt", "status", "lastError", "deadLetteredAt", "createdAt" ], "description": "Record of a single webhook delivery attempt including status and retry information" }, "description": "Dead-lettered delivery records in the current page" }, "pagination": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "Cursor to pass as the `cursor` parameter to retrieve the next page, or null if no more results" }, "hasMore": { "type": "boolean", "description": "Whether additional pages of results are available" } }, "required": [ "nextCursor", "hasMore" ], "description": "Cursor-based pagination metadata" } }, "required": [ "items", "pagination" ], "description": "Paginated list of dead-lettered webhook deliveries" } } } } } } }, "/webhooks/event-types": { "get": { "operationId": "webhook.eventTypes", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "eventTypes": { "type": "array", "items": { "type": "string" }, "description": "All known event type strings that webhooks can subscribe to. Webhooks may also subscribe to glob patterns (e.g. 'message.*' or '*') that match these names." } }, "required": [ "eventTypes" ], "description": "Discoverable enumeration of webhook event types" } } } } } } }, "/orgs/{orgId}/messages/{messageId}/approve": { "post": { "operationId": "security.approve", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier (from the URL path)" } }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string", "description": "Message identifier requiring approval" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "enum": [ "approve", "reject" ], "type": "string", "description": "Approval decision for the message" }, "reason": { "type": "string", "description": "Optional justification for the approval decision" } }, "required": [ "action" ], "description": "Input for approving or rejecting a pending message" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "messageId": { "type": "string", "description": "Identifier of the processed message" }, "status": { "enum": [ "SENT", "REJECTED", "FAILED" ], "type": "string", "description": "Resulting status after the approval action" }, "message": { "type": "string", "description": "Human-readable result description" } }, "required": [ "messageId", "status", "message" ], "description": "Result of a message approval or rejection action" } } } } } } }, "/orgs/{orgId}/security/events": { "get": { "operationId": "security.listEvents", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier (from the URL path)" } }, { "name": "agentId", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter events by a specific agent" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "type", "in": "query", "required": false, "schema": { "enum": [ "PII_DETECTED", "INJECTION_DETECTED", "RATE_LIMITED", "BLOCKED", "APPROVED", "REJECTED" ], "type": "string", "description": "Filter events by security event type" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "severity", "in": "query", "required": false, "schema": { "enum": [ "LOW", "MEDIUM", "HIGH", "CRITICAL" ], "type": "string", "description": "Filter events by severity level" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Pagination cursor for fetching the next page" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of events to return per page" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique security event identifier" }, "orgId": { "type": "string", "description": "Organization the event belongs to" }, "agentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent that triggered the event, if applicable" }, "messageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Associated message identifier, if applicable" }, "type": { "type": "string", "description": "Security event type classification" }, "severity": { "type": "string", "description": "Event severity level" }, "details": { "type": "object", "additionalProperties": {}, "description": "Structured metadata and context for the event" }, "resolved": { "type": "boolean", "description": "Whether the event has been resolved" }, "resolvedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identifier of the user who resolved the event" }, "resolvedAt": { "anyOf": [ { "type": "string", "format": "date-time", "x-native-type": "date" }, { "type": "null" } ], "description": "Timestamp when the event was resolved" }, "createdAt": { "type": "string", "format": "date-time", "x-native-type": "date", "description": "Timestamp when the event was created" } }, "required": [ "id", "orgId", "agentId", "messageId", "type", "severity", "details", "resolved", "resolvedBy", "resolvedAt", "createdAt" ], "description": "A security event record" }, "description": "List of security events matching the query" }, "pagination": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for retrieving the next page of results" }, "hasMore": { "type": "boolean", "description": "Whether additional results are available" } }, "required": [ "nextCursor", "hasMore" ], "description": "Pagination metadata" } }, "required": [ "items", "pagination" ], "description": "Paginated list of security events" } } } } } } }, "/orgs/{orgId}/security/scanner-status": { "get": { "operationId": "security.scannerStatus", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier (from the URL path)" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "aiScanner": { "type": "object", "properties": { "active": { "type": "boolean", "description": "Whether the AI scanner actually runs on message traffic (not merely whether an LLM provider is configured)" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "LLM provider name if available" }, "fallbackReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason the scanner is in fallback mode, if applicable" } }, "required": [ "active", "provider", "fallbackReason" ], "description": "AI-based content scanner status" } }, "required": [ "aiScanner" ], "description": "Current scanner health status" } } } } } } }, "/billing/usage": { "get": { "operationId": "billing.getUsage", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "string", "pattern": "^\\d{4}-\\d{2}(-\\d{2})?$", "description": "Billing period, identified by its start date (YYYY-MM-DD). Periods follow the org's billing anchor day, not the calendar month. Legacy periods recorded before anchored billing use YYYY-MM." }, "usage": { "type": "object", "properties": { "message_sent": { "type": "integer", "minimum": 0, "description": "Total email messages sent during the period" }, "message_received": { "type": "integer", "minimum": 0, "description": "Total email messages received during the period" }, "sms_sent": { "type": "integer", "minimum": 0, "description": "Total SMS messages sent during the period" }, "sms_received": { "type": "integer", "minimum": 0, "description": "Total SMS messages received during the period" }, "call_minute": { "type": "integer", "minimum": 0, "description": "Total voice call minutes consumed during the period" }, "voice_credit": { "type": "integer", "minimum": 0, "description": "Voice credits drawn from the plan allowance this period. 1 credit = 1 US minute; mobile-abroad minutes draw more. This — not call_minute — is what the included voice allowance is measured in." }, "embedding_generated": { "type": "integer", "minimum": 0, "description": "Total embeddings generated during the period" } }, "required": [ "message_sent", "message_received", "sms_sent", "sms_received", "call_minute", "voice_credit", "embedding_generated" ], "description": "Breakdown of resource usage by category" }, "storage": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "integer", "minimum": 0, "description": "Bytes held in object storage" }, "measuredAt": { "type": "string", "description": "ISO timestamp of the measurement" } }, "required": [ "bytes", "measuredAt" ] }, { "type": "null" } ], "description": "Last measured object-storage usage; null when never measured" } }, "required": [ "period", "usage", "storage" ], "description": "Usage metrics for a specific billing period" } } } } } } }, "/billing/tier": { "get": { "operationId": "billing.getTier", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "tier": { "enum": [ "free", "starter", "growth", "enterprise" ], "type": "string", "description": "Current subscription tier identifier" }, "name": { "type": "string", "description": "Human-readable name of the subscription tier" }, "price": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Monthly price in cents, null for custom-priced tiers" }, "limits": { "type": "object", "properties": { "messages": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Included messages per month. Historically a combined pool; it has been identical to the email quota at every tier for some time and is now sourced from it directly. Kept so existing clients do not break." }, "agents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Maximum number of agents, null for unlimited" }, "domains": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Maximum number of custom domains, null for unlimited" } }, "required": [ "messages", "agents", "domains" ], "description": "Resource limits for this tier" }, "renewalDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp of the next billing cycle renewal" }, "billingStatus": { "anyOf": [ { "enum": [ "active", "past_due", "canceled", "cancelled", "incomplete", "trialing", "paused", "payment_failed", "none" ], "type": "string" }, { "type": "null" } ], "description": "Current subscription status from Stripe, null if no subscription" }, "cancelAtPeriodEnd": { "type": "boolean", "description": "Whether the subscription is set to cancel at the end of the current period" } }, "required": [ "tier", "name", "price", "limits", "renewalDate", "billingStatus", "cancelAtPeriodEnd" ], "description": "Subscription tier details including pricing and resource limits" } } } } } } }, "/billing/plans": { "get": { "operationId": "billing.getPlans", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "plans": { "type": "array", "items": { "type": "object", "properties": { "tier": { "enum": [ "free", "starter", "growth", "enterprise" ], "type": "string", "description": "Publicly-selectable billing tier; sunset 'scale' is excluded" }, "name": { "type": "string", "description": "Human-readable name of the tier" }, "price": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Monthly price in cents, null for custom-priced tiers" }, "priceAnnual": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Total charged once a year, in cents. null means the tier has no annual SKU (Free, Enterprise) — render the monthly price and hide the annual option." }, "limits": { "type": "object", "properties": { "emails": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Included emails sent per month, null=unlimited" }, "smsSent": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Included SMS sent per month, null=unlimited" }, "smsReceived": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Included SMS received per month, null=unlimited" }, "agents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Maximum agents, null=unlimited" }, "domains": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Maximum custom domains, null=unlimited" }, "identities": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Maximum agent identities, null=unlimited" }, "phoneNumbers": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Included phone numbers, null=unlimited" }, "credentials": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Maximum vault credentials, null=unlimited" }, "voiceMinutes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Included voice minutes per month, null=unlimited" }, "storageBytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Included object storage in BYTES (not GB), null=unlimited" } }, "required": [ "emails", "smsSent", "smsReceived", "agents", "domains", "identities", "phoneNumbers", "credentials", "voiceMinutes", "storageBytes" ], "description": "Included quotas / caps for a tier, projected from the canonical TIERS table" } }, "required": [ "tier", "name", "price", "priceAnnual", "limits" ] }, "description": "Public plan catalog in ascending upgrade order" } }, "required": [ "plans" ], "description": "Canonical tier catalog for the billing comparison grid, derived from TIERS" } } } } } } }, "/billing/checkout": { "post": { "operationId": "billing.createCheckout", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tier": { "enum": [ "starter", "growth", "enterprise" ], "type": "string", "description": "Target subscription tier to upgrade or switch to" }, "interval": { "default": "month", "enum": [ "month", "year" ], "type": "string", "description": "Billing cadence. Annual is ~17% cheaper; Free has no annual price." }, "successUrl": { "type": "string", "format": "uri", "description": "URL to redirect to after successful checkout" }, "cancelUrl": { "type": "string", "format": "uri", "description": "URL to redirect to if the user cancels checkout" } }, "required": [ "tier" ], "description": "Request body for initiating a Stripe checkout session" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Stripe-hosted session URL, null if session creation failed" } }, "required": [ "url" ], "description": "Response containing a Stripe checkout or portal session URL" } } } } } } }, "/billing/portal": { "post": { "operationId": "billing.createPortal", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "returnUrl": { "type": "string", "format": "uri", "description": "URL to redirect to when the user exits the billing portal" } }, "description": "Request body for generating a Stripe customer portal link" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Stripe-hosted session URL, null if session creation failed" } }, "required": [ "url" ], "description": "Response containing a Stripe checkout or portal session URL" } } } } } } }, "/billing/invoices": { "get": { "operationId": "billing.listInvoices", "parameters": [ { "name": "limit", "in": "query", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Max invoices to return" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Stripe invoice ID to paginate after" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stripe invoice ID" }, "number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable invoice number" }, "date": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the invoice was created" }, "amountPaid": { "type": "integer", "description": "Amount paid in cents" }, "currency": { "type": "string", "description": "Three-letter ISO currency code" }, "status": { "anyOf": [ { "enum": [ "draft", "open", "paid", "uncollectible", "void" ], "type": "string" }, { "type": "null" } ], "description": "Invoice payment status" }, "hostedUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "URL to Stripe-hosted invoice page" }, "pdfUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "URL to download invoice PDF" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Invoice description or memo" } }, "required": [ "id", "number", "date", "amountPaid", "currency", "status", "hostedUrl", "pdfUrl", "description" ] }, "description": "List of invoices" }, "hasMore": { "type": "boolean", "description": "Whether more invoices are available" } }, "required": [ "items", "hasMore" ] } } } } } } }, "/billing/change-plan": { "post": { "operationId": "billing.changePlan", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tier": { "enum": [ "free", "starter", "growth" ], "type": "string", "description": "Target tier to switch to (enterprise handled via contactEnterprise)" } }, "required": [ "tier" ], "description": "Request body for changing subscription plan" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "enum": [ "upgraded", "downgraded", "scheduled", "no_change", "error" ], "type": "string", "description": "Result of the plan change operation" }, "message": { "type": "string", "description": "Human-readable result description" }, "scheduledDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "For downgrades: ISO 8601 date when the change takes effect" } }, "required": [ "status", "message", "scheduledDate" ], "description": "Response from a plan change operation" } } } } } } }, "/billing/contact-enterprise": { "post": { "operationId": "billing.contactEnterprise", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "enum": [ "upgrade", "downgrade" ], "type": "string", "description": "Whether the customer wants to upgrade to or downgrade from enterprise" } }, "required": [ "type" ], "description": "Request body for enterprise plan contact" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "sent": { "type": "boolean", "description": "Whether the notification was sent successfully" } }, "required": [ "sent" ], "description": "Response from enterprise contact request" } } } } } } }, "/billing/features/{feature}": { "get": { "operationId": "billing.getFeatureAccess", "parameters": [ { "name": "feature", "in": "path", "required": true, "schema": { "enum": [ "audit_logs" ], "type": "string", "description": "Feature to check access for" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "feature": { "enum": [ "audit_logs" ], "type": "string", "description": "Feature name for plan-based access checks" }, "enabled": { "type": "boolean", "description": "Whether the feature is available on the current plan" }, "currentTier": { "enum": [ "free", "starter", "growth", "enterprise" ], "type": "string", "description": "The caller's current tier" }, "requiredTier": { "anyOf": [ { "enum": [ "free", "starter", "growth", "enterprise" ], "type": "string", "description": "Billing subscription tier" }, { "type": "null" } ], "description": "Lowest tier that unlocks the feature; null if already enabled" }, "upgradeUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Relative URL to the upgrade path; null if already enabled" } }, "required": [ "feature", "enabled", "currentTier", "requiredTier", "upgradeUrl" ], "description": "Access decision for a plan-gated feature" } } } } } } }, "/billing/overage": { "get": { "operationId": "billing.getOverage", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the customer has opted in to metered overage" }, "limitCents": { "type": "integer", "minimum": 0, "description": "Overage the customer authorized above their included allowance, in cents" }, "monthlySpendCents": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Customer's own absolute ceiling; lowers the cap but never raises it" }, "effectiveCapCents": { "type": "integer", "minimum": 0, "description": "What enforcement actually compares spend against; 0 when overage is off" }, "usedCents": { "type": "integer", "minimum": 0, "description": "Metered overage accrued so far this billing period, in cents" }, "planCeilingCents": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Most this plan permits authorizing; null on Enterprise (no ceiling)" }, "period": { "type": "string", "description": "Billing-period key the usage figure covers" } }, "required": [ "enabled", "limitCents", "monthlySpendCents", "effectiveCapCents", "usedCents", "planCeilingCents", "period" ], "description": "Metered-overage authorization for the requesting org" } } } } } }, "put": { "operationId": "billing.updateOverage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Opt in to (or out of) metered overage" }, "limitCents": { "type": "integer", "minimum": 0, "description": "Overage to authorize above the included allowance, in cents" }, "monthlySpendCents": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Absolute ceiling; null CLEARS it, omitting the field leaves it unchanged" } }, "description": "Patch for overage settings; missing fields preserve current values" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the customer has opted in to metered overage" }, "limitCents": { "type": "integer", "minimum": 0, "description": "Overage the customer authorized above their included allowance, in cents" }, "monthlySpendCents": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Customer's own absolute ceiling; lowers the cap but never raises it" }, "effectiveCapCents": { "type": "integer", "minimum": 0, "description": "What enforcement actually compares spend against; 0 when overage is off" }, "usedCents": { "type": "integer", "minimum": 0, "description": "Metered overage accrued so far this billing period, in cents" }, "planCeilingCents": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Most this plan permits authorizing; null on Enterprise (no ceiling)" }, "period": { "type": "string", "description": "Billing-period key the usage figure covers" } }, "required": [ "enabled", "limitCents", "monthlySpendCents", "effectiveCapCents", "usedCents", "planCeilingCents", "period" ], "description": "Metered-overage authorization for the requesting org" } } } } } } }, "/openclaw/authorize": { "get": { "operationId": "openclaw.authorize", "parameters": [ { "name": "state", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Opaque state parameter passed through the OAuth flow" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether OpenClaw integration is enabled for this organization" }, "redirectUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "OAuth authorization URL to redirect the user to" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "State parameter echoed back for CSRF verification" } }, "required": [ "enabled", "redirectUrl", "state" ], "description": "Authorization initiation response with redirect URL" } } } } } } }, "/openclaw/callback": { "get": { "operationId": "openclaw.callback", "parameters": [ { "name": "code", "in": "query", "schema": { "type": "string", "minLength": 1, "description": "OAuth authorization code returned by the provider" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "state", "in": "query", "schema": { "type": "string", "minLength": 1, "description": "State parameter for CSRF verification" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "error", "in": "query", "schema": { "type": "string", "minLength": 1, "description": "Error code if the authorization was denied or failed" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether OpenClaw integration is enabled" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "State parameter echoed back for verification" }, "agent": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "OpenClaw agent unique identifier" }, "email": { "type": "string", "format": "email", "description": "Agent email address" }, "name": { "type": "string", "description": "Agent display name" }, "handle": { "type": "string", "description": "Agent handle or username" }, "avatarUrl": { "type": "string", "format": "uri", "description": "URL to the agent avatar image" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional profile metadata from OpenClaw" } }, "required": [ "id", "email", "name" ], "description": "OpenClaw agent profile information" }, { "type": "null" } ], "description": "Agent profile if authorization succeeded" }, "tokens": { "anyOf": [ { "type": "object", "properties": { "accessToken": { "type": "string", "description": "OAuth access token for API calls" }, "refreshToken": { "type": "string", "description": "OAuth refresh token for obtaining new access tokens" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Timestamp when the access token expires" } }, "required": [ "accessToken", "refreshToken", "expiresAt" ], "description": "OAuth token credentials for the OpenClaw integration" }, { "type": "null" } ], "description": "OAuth tokens if authorization succeeded" } }, "required": [ "enabled", "state", "agent", "tokens" ], "description": "Result of processing the OpenClaw OAuth callback" } } } } } } }, "/openclaw/signup": { "post": { "operationId": "openclaw.selfSignup", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "openclawAgentId": { "type": "string", "minLength": 1, "description": "OpenClaw agent identifier to register" }, "organizationName": { "type": "string", "minLength": 2, "maxLength": 120, "description": "Display name for the new organization" }, "organizationSlug": { "type": "string", "minLength": 2, "maxLength": 64, "pattern": "^[a-z0-9-]+$", "description": "URL-friendly organization slug (lowercase alphanumeric and hyphens)" }, "agentName": { "type": "string", "minLength": 2, "maxLength": 100, "description": "Display name for the agent" }, "agentSlug": { "type": "string", "minLength": 2, "maxLength": 64, "pattern": "^[a-z0-9-]+$", "description": "URL-friendly agent slug (lowercase alphanumeric and hyphens)" }, "email": { "type": "string", "format": "email", "description": "Primary email address for the agent" }, "phoneNumber": { "type": "string", "minLength": 7, "maxLength": 20, "description": "Phone number to provision for the agent" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional metadata for the signup" } }, "required": [ "openclawAgentId", "organizationName", "organizationSlug", "agentName", "agentSlug", "email", "phoneNumber" ], "description": "Input for self-service agent and organization registration via OpenClaw" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique organization identifier" }, "name": { "type": "string", "description": "Organization display name" }, "slug": { "type": "string", "description": "Organization URL slug" }, "tier": { "enum": [ "FREE", "STARTER", "GROWTH", "ENTERPRISE" ], "type": "string", "description": "Subscription tier assigned to the organization" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the organization was created" } }, "required": [ "id", "name", "slug", "tier", "createdAt" ], "description": "Newly created organization details" }, "agent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique agent identifier" }, "orgId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Organization the agent belongs to" }, "name": { "type": "string", "description": "Agent display name" }, "slug": { "type": "string", "description": "Agent URL slug" }, "email": { "type": "string", "format": "email", "description": "Agent email address" }, "phoneNumber": { "type": "string", "description": "Provisioned phone number" }, "apiKeyPrefix": { "type": "string", "description": "Prefix of the generated API key for identification" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the agent was created" } }, "required": [ "id", "orgId", "name", "slug", "email", "phoneNumber", "apiKeyPrefix", "createdAt" ], "description": "Newly created agent details" }, "credentials": { "type": "object", "properties": { "apiKey": { "type": "string", "description": "Full API key (shown only once)" }, "apiKeyPrefix": { "type": "string", "description": "API key prefix for future identification" } }, "required": [ "apiKey", "apiKeyPrefix" ], "description": "API credentials for the new agent" } }, "required": [ "organization", "agent", "credentials" ], "description": "Result of a successful self-service signup including organization, agent, and credentials" } } } } } } }, "/openclaw/agents": { "get": { "operationId": "openclaw.listRegistered", "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Opaque cursor from a previous response to fetch the next page" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of items to return per page (1–100, default 20)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "query", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Search query to filter registered agents by name or email" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique agent identifier" }, "orgId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Organization the agent belongs to" }, "openclawAgentId": { "type": "string", "description": "Corresponding OpenClaw agent identifier" }, "name": { "type": "string", "description": "Agent display name" }, "slug": { "type": "string", "description": "Agent URL slug" }, "email": { "type": "string", "format": "email", "description": "Agent email address" }, "phoneNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent phone number, if provisioned" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the agent was registered" } }, "required": [ "id", "orgId", "openclawAgentId", "name", "slug", "email", "phoneNumber", "createdAt" ], "description": "Registered OpenClaw agent record" }, "description": "List of registered agents matching the query" }, "pagination": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "Cursor to pass as the `cursor` parameter to retrieve the next page, or null if no more results" }, "hasMore": { "type": "boolean", "description": "Whether additional pages of results are available" } }, "required": [ "nextCursor", "hasMore" ], "description": "Pagination metadata" } }, "required": [ "items", "pagination" ], "description": "Paginated list of registered OpenClaw agents" } } } } } } }, "/demo/inbox": { "post": { "operationId": "demo.createInbox", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "No input — provisioning a demo inbox takes no parameters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "format": "email", "description": "The ephemeral demo inbox email address" }, "token": { "type": "string", "description": "256-bit opaque read capability for this inbox — returned ONCE, at creation. This, not the address, authorizes reading the inbox's mail." }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the inbox and all its mail are reclaimed (ISO 8601)" } }, "required": [ "address", "token", "expiresAt" ], "description": "A freshly provisioned ephemeral demo inbox" } } } } } } }, "/demo/inbox/{token}/messages": { "get": { "operationId": "demo.messages", "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The opaque read token returned by the create endpoint" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque message id" }, "from": { "type": "string", "description": "Masked sender address (never the full address)" }, "subject": { "type": "string", "description": "Truncated subject" }, "snippet": { "type": "string", "description": "Plain-text, truncated body snippet — never HTML" }, "receivedAt": { "type": "string", "format": "date-time", "description": "When the message arrived (ISO 8601)" } }, "required": [ "id", "from", "subject", "snippet", "receivedAt" ], "description": "A redacted, text-only demo message" }, "description": "Most-recent redacted messages, newest first" } }, "required": [ "messages" ], "description": "The redacted messages currently in a demo inbox" } } } } } } }, "/registry/agents": { "post": { "operationId": "registry.register", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the agent to register in the directory" }, "name": { "type": "string", "minLength": 2, "maxLength": 200, "description": "Display name for the registry listing" }, "description": { "type": "string", "maxLength": 2000, "description": "Human-readable description of the agent's purpose" }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 50 }, "maxItems": 20, "description": "Searchable tags for categorization" }, "public": { "type": "boolean", "description": "Whether this listing is publicly discoverable" } }, "required": [ "agentId", "name" ], "description": "Request body for registering an agent in the registry" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the registry entry" }, "did": { "type": "string", "description": "Decentralized identifier of the agent" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the registered agent" }, "orgId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Organization that owns the agent" }, "public": { "type": "boolean", "description": "Whether the listing is publicly visible" }, "name": { "type": "string", "description": "Display name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent description" }, "agentCard": { "type": "object", "additionalProperties": {}, "description": "Structured agent card with capabilities and metadata" }, "trustScore": { "type": "integer", "description": "Reserved — a fixed placeholder, not a ranking. Not computed from any signal; do not sort, filter, or gate on it. Verify an agent cryptographically instead: resolve its DID document and check the signatures on its verifiable credentials." }, "kyaLevel": { "type": "string", "description": "KYA verification level (reserved — not yet populated)" }, "capabilities": { "type": "array", "items": { "type": "string" }, "description": "List of agent capabilities" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Searchable tags" }, "verified": { "type": "boolean", "description": "Whether the agent has been verified (reserved — not yet populated)" }, "verifiedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp of verification (reserved — not yet populated)" }, "listedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the agent was listed" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp of last update" } }, "required": [ "id", "did", "agentId", "orgId", "public", "name", "description", "agentCard", "trustScore", "kyaLevel", "capabilities", "tags", "verified", "verifiedAt", "listedAt", "updatedAt" ], "description": "Full registry entry representation" } } } } } } }, "/registry/agents/search": { "get": { "operationId": "registry.search", "parameters": [ { "name": "query", "in": "query", "schema": { "type": "string", "maxLength": 200, "description": "Free-text search across name and description" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "capability", "in": "query", "schema": { "type": "string", "description": "Filter by a specific capability" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "kyaLevel", "in": "query", "schema": { "type": "string", "description": "Reserved — accepted for backward compatibility but not used as a filter yet" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "trustMin", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Reserved — accepted for backward compatibility but not used as a filter. `trustScore` is not computed yet, so filtering on it would silently return an empty directory rather than a trusted subset." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "tags", "in": "query", "schema": { "type": "array", "items": { "type": "string" }, "maxItems": 50, "description": "Filter by tags (entries must match at least one). A single value (`?tags=support`) is accepted as well as the repeated and bracketed forms." }, "style": "deepObject", "explode": true, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Cursor for pagination" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum items per page" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the registry entry" }, "did": { "type": "string", "description": "Decentralized identifier of the agent" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the registered agent" }, "orgId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Organization that owns the agent" }, "public": { "type": "boolean", "description": "Whether the listing is publicly visible" }, "name": { "type": "string", "description": "Display name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent description" }, "agentCard": { "type": "object", "additionalProperties": {}, "description": "Structured agent card with capabilities and metadata" }, "trustScore": { "type": "integer", "description": "Reserved — a fixed placeholder, not a ranking. Not computed from any signal; do not sort, filter, or gate on it. Verify an agent cryptographically instead: resolve its DID document and check the signatures on its verifiable credentials." }, "kyaLevel": { "type": "string", "description": "KYA verification level (reserved — not yet populated)" }, "capabilities": { "type": "array", "items": { "type": "string" }, "description": "List of agent capabilities" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Searchable tags" }, "verified": { "type": "boolean", "description": "Whether the agent has been verified (reserved — not yet populated)" }, "verifiedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp of verification (reserved — not yet populated)" }, "listedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the agent was listed" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp of last update" } }, "required": [ "id", "did", "agentId", "orgId", "public", "name", "description", "agentCard", "trustScore", "kyaLevel", "capabilities", "tags", "verified", "verifiedAt", "listedAt", "updatedAt" ], "description": "Full registry entry representation" }, "description": "Array of matching registry entries" }, "nextCursor": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "Cursor for fetching the next page" }, "total": { "type": "integer", "description": "Total number of entries matching the query" } }, "required": [ "items", "nextCursor", "total" ], "description": "Paginated search results from the agent registry" } } } } } } }, "/registry/agents/{did}": { "get": { "operationId": "registry.lookup", "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string", "description": "DID of the agent to look up" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the registry entry" }, "did": { "type": "string", "description": "Decentralized identifier of the agent" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the registered agent" }, "orgId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Organization that owns the agent" }, "public": { "type": "boolean", "description": "Whether the listing is publicly visible" }, "name": { "type": "string", "description": "Display name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent description" }, "agentCard": { "type": "object", "additionalProperties": {}, "description": "Structured agent card with capabilities and metadata" }, "trustScore": { "type": "integer", "description": "Reserved — a fixed placeholder, not a ranking. Not computed from any signal; do not sort, filter, or gate on it. Verify an agent cryptographically instead: resolve its DID document and check the signatures on its verifiable credentials." }, "kyaLevel": { "type": "string", "description": "KYA verification level (reserved — not yet populated)" }, "capabilities": { "type": "array", "items": { "type": "string" }, "description": "List of agent capabilities" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Searchable tags" }, "verified": { "type": "boolean", "description": "Whether the agent has been verified (reserved — not yet populated)" }, "verifiedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp of verification (reserved — not yet populated)" }, "listedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the agent was listed" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp of last update" } }, "required": [ "id", "did", "agentId", "orgId", "public", "name", "description", "agentCard", "trustScore", "kyaLevel", "capabilities", "tags", "verified", "verifiedAt", "listedAt", "updatedAt" ], "description": "Full registry entry representation" } } } } } }, "put": { "operationId": "registry.update", "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string", "description": "DID of the agent to update" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 200, "description": "Updated display name" }, "description": { "type": "string", "maxLength": 2000, "description": "Updated description" }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 50 }, "maxItems": 20, "description": "Updated tags" }, "public": { "type": "boolean", "description": "Updated visibility" } }, "required": [], "description": "Request body for updating a registry entry" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the registry entry" }, "did": { "type": "string", "description": "Decentralized identifier of the agent" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the registered agent" }, "orgId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Organization that owns the agent" }, "public": { "type": "boolean", "description": "Whether the listing is publicly visible" }, "name": { "type": "string", "description": "Display name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent description" }, "agentCard": { "type": "object", "additionalProperties": {}, "description": "Structured agent card with capabilities and metadata" }, "trustScore": { "type": "integer", "description": "Reserved — a fixed placeholder, not a ranking. Not computed from any signal; do not sort, filter, or gate on it. Verify an agent cryptographically instead: resolve its DID document and check the signatures on its verifiable credentials." }, "kyaLevel": { "type": "string", "description": "KYA verification level (reserved — not yet populated)" }, "capabilities": { "type": "array", "items": { "type": "string" }, "description": "List of agent capabilities" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Searchable tags" }, "verified": { "type": "boolean", "description": "Whether the agent has been verified (reserved — not yet populated)" }, "verifiedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp of verification (reserved — not yet populated)" }, "listedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the agent was listed" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp of last update" } }, "required": [ "id", "did", "agentId", "orgId", "public", "name", "description", "agentCard", "trustScore", "kyaLevel", "capabilities", "tags", "verified", "verifiedAt", "listedAt", "updatedAt" ], "description": "Full registry entry representation" } } } } } }, "delete": { "operationId": "registry.unlist", "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string", "description": "DID of the agent to unlist" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "Parameters for removing an agent from the registry" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true, "description": "Always true on successful removal" }, "message": { "type": "string", "description": "Informational message about the removal" } }, "required": [ "success", "message" ], "description": "Unlist confirmation" } } } } } } }, "/agents/{agentId}/a2a/tasks": { "post": { "operationId": "a2a.submitTask", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the receiving agent" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Task type (e.g., send_email, make_payment)" }, "input": { "type": "object", "additionalProperties": {}, "description": "Task input payload" }, "from": { "type": "string", "minLength": 1, "description": "Sender DID" } }, "required": [ "type", "input", "from" ], "description": "Request body for submitting an A2A task to an agent" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique task identifier" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the receiving agent" }, "orgId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Organization that owns the receiving agent" }, "fromDid": { "type": "string", "description": "Sender DID" }, "toDid": { "type": "string", "description": "Receiver DID" }, "type": { "type": "string", "description": "Task type" }, "status": { "enum": [ "submitted", "working", "input_required", "completed", "failed", "canceled" ], "type": "string", "description": "Current status of the A2A task" }, "input": { "type": "object", "additionalProperties": {}, "description": "Task input payload" }, "output": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Task output payload" }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "description": "Error code" }, "message": { "type": "string", "description": "Error message" } }, "required": [ "code", "message" ] }, { "type": "null" } ], "description": "Error details if task failed" }, "history": { "type": "array", "items": { "type": "object", "properties": { "status": { "enum": [ "submitted", "working", "input_required", "completed", "failed", "canceled" ], "type": "string", "description": "Current status of the A2A task" }, "message": { "type": "string", "description": "Human-readable status message" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp of the event" } }, "required": [ "status", "timestamp" ], "description": "A single status-change event in the task history" }, "description": "Status change history" }, "createdAt": { "type": "string", "format": "date-time", "description": "Task creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "agentId", "orgId", "fromDid", "toDid", "type", "status", "input", "output", "error", "history", "createdAt", "updatedAt" ], "description": "Full A2A task representation" } } } } } }, "get": { "operationId": "a2a.listTasks", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the agent to list tasks for" } }, { "name": "status", "in": "query", "required": false, "schema": { "enum": [ "submitted", "working", "input_required", "completed", "failed", "canceled" ], "type": "string", "description": "Filter by task status" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Cursor for pagination" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum items per page" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique task identifier" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the receiving agent" }, "orgId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Organization that owns the receiving agent" }, "fromDid": { "type": "string", "description": "Sender DID" }, "toDid": { "type": "string", "description": "Receiver DID" }, "type": { "type": "string", "description": "Task type" }, "status": { "enum": [ "submitted", "working", "input_required", "completed", "failed", "canceled" ], "type": "string", "description": "Current status of the A2A task" }, "input": { "type": "object", "additionalProperties": {}, "description": "Task input payload" }, "output": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Task output payload" }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "description": "Error code" }, "message": { "type": "string", "description": "Error message" } }, "required": [ "code", "message" ] }, { "type": "null" } ], "description": "Error details if task failed" }, "history": { "type": "array", "items": { "type": "object", "properties": { "status": { "enum": [ "submitted", "working", "input_required", "completed", "failed", "canceled" ], "type": "string", "description": "Current status of the A2A task" }, "message": { "type": "string", "description": "Human-readable status message" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp of the event" } }, "required": [ "status", "timestamp" ], "description": "A single status-change event in the task history" }, "description": "Status change history" }, "createdAt": { "type": "string", "format": "date-time", "description": "Task creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "agentId", "orgId", "fromDid", "toDid", "type", "status", "input", "output", "error", "history", "createdAt", "updatedAt" ], "description": "Full A2A task representation" }, "description": "Array of matching A2A tasks" }, "nextCursor": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "Cursor for fetching the next page" } }, "required": [ "items", "nextCursor" ], "description": "Paginated list of A2A tasks" } } } } } } }, "/agents/{agentId}/a2a/tasks/{taskId}": { "get": { "operationId": "a2a.getTask", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the agent that owns the task" } }, { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the task to retrieve" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique task identifier" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the receiving agent" }, "orgId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Organization that owns the receiving agent" }, "fromDid": { "type": "string", "description": "Sender DID" }, "toDid": { "type": "string", "description": "Receiver DID" }, "type": { "type": "string", "description": "Task type" }, "status": { "enum": [ "submitted", "working", "input_required", "completed", "failed", "canceled" ], "type": "string", "description": "Current status of the A2A task" }, "input": { "type": "object", "additionalProperties": {}, "description": "Task input payload" }, "output": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Task output payload" }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "description": "Error code" }, "message": { "type": "string", "description": "Error message" } }, "required": [ "code", "message" ] }, { "type": "null" } ], "description": "Error details if task failed" }, "history": { "type": "array", "items": { "type": "object", "properties": { "status": { "enum": [ "submitted", "working", "input_required", "completed", "failed", "canceled" ], "type": "string", "description": "Current status of the A2A task" }, "message": { "type": "string", "description": "Human-readable status message" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp of the event" } }, "required": [ "status", "timestamp" ], "description": "A single status-change event in the task history" }, "description": "Status change history" }, "createdAt": { "type": "string", "format": "date-time", "description": "Task creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "agentId", "orgId", "fromDid", "toDid", "type", "status", "input", "output", "error", "history", "createdAt", "updatedAt" ], "description": "Full A2A task representation" } } } } } } }, "/agents/{agentId}/a2a/tasks/{taskId}/cancel": { "post": { "operationId": "a2a.cancelTask", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the agent that owns the task" } }, { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the task to cancel" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "Parameters for canceling an A2A task" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique task identifier" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the receiving agent" }, "orgId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Organization that owns the receiving agent" }, "fromDid": { "type": "string", "description": "Sender DID" }, "toDid": { "type": "string", "description": "Receiver DID" }, "type": { "type": "string", "description": "Task type" }, "status": { "enum": [ "submitted", "working", "input_required", "completed", "failed", "canceled" ], "type": "string", "description": "Current status of the A2A task" }, "input": { "type": "object", "additionalProperties": {}, "description": "Task input payload" }, "output": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Task output payload" }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "description": "Error code" }, "message": { "type": "string", "description": "Error message" } }, "required": [ "code", "message" ] }, { "type": "null" } ], "description": "Error details if task failed" }, "history": { "type": "array", "items": { "type": "object", "properties": { "status": { "enum": [ "submitted", "working", "input_required", "completed", "failed", "canceled" ], "type": "string", "description": "Current status of the A2A task" }, "message": { "type": "string", "description": "Human-readable status message" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp of the event" } }, "required": [ "status", "timestamp" ], "description": "A single status-change event in the task history" }, "description": "Status change history" }, "createdAt": { "type": "string", "format": "date-time", "description": "Task creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "agentId", "orgId", "fromDid", "toDid", "type", "status", "input", "output", "error", "history", "createdAt", "updatedAt" ], "description": "Full A2A task representation" } } } } } } }, "/agents/{agentId}/a2a/tasks/{taskId}/update": { "post": { "operationId": "a2a.updateTask", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the receiving agent that owns the task" } }, { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the task to update" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "enum": [ "working", "input_required", "completed", "failed" ], "type": "string", "description": "New task status. Terminal states (completed/failed/canceled) are immutable once reached." }, "output": { "type": "object", "additionalProperties": {}, "description": "Task output payload (typically set when completing)" }, "error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Error code" }, "message": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Error message" } }, "required": [ "code", "message" ], "description": "Error details — only allowed when status is 'failed'" }, "message": { "type": "string", "maxLength": 2000, "description": "Human-readable annotation recorded in the task history" } }, "required": [ "status" ], "description": "Owner-driven A2A task status transition (the receiving agent reports working/completed/failed)" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique task identifier" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the receiving agent" }, "orgId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Organization that owns the receiving agent" }, "fromDid": { "type": "string", "description": "Sender DID" }, "toDid": { "type": "string", "description": "Receiver DID" }, "type": { "type": "string", "description": "Task type" }, "status": { "enum": [ "submitted", "working", "input_required", "completed", "failed", "canceled" ], "type": "string", "description": "Current status of the A2A task" }, "input": { "type": "object", "additionalProperties": {}, "description": "Task input payload" }, "output": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Task output payload" }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "description": "Error code" }, "message": { "type": "string", "description": "Error message" } }, "required": [ "code", "message" ] }, { "type": "null" } ], "description": "Error details if task failed" }, "history": { "type": "array", "items": { "type": "object", "properties": { "status": { "enum": [ "submitted", "working", "input_required", "completed", "failed", "canceled" ], "type": "string", "description": "Current status of the A2A task" }, "message": { "type": "string", "description": "Human-readable status message" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp of the event" } }, "required": [ "status", "timestamp" ], "description": "A single status-change event in the task history" }, "description": "Status change history" }, "createdAt": { "type": "string", "format": "date-time", "description": "Task creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "agentId", "orgId", "fromDid", "toDid", "type", "status", "input", "output", "error", "history", "createdAt", "updatedAt" ], "description": "Full A2A task representation" } } } } } } }, "/agents/{fromAgentId}/a2a/dispatch": { "post": { "operationId": "a2a.dispatch", "parameters": [ { "name": "fromAgentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the sending agent (must belong to the caller's org)" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "toDid": { "type": "string", "minLength": 1, "description": "Recipient agent DID" }, "type": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Task type" }, "input": { "type": "object", "additionalProperties": {}, "description": "Task input payload" } }, "required": [ "toDid", "type", "input" ], "description": "Dispatch an A2A task from one of your agents to another agent by DID" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique task identifier" }, "agentId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "ID of the receiving agent" }, "orgId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Organization that owns the receiving agent" }, "fromDid": { "type": "string", "description": "Sender DID" }, "toDid": { "type": "string", "description": "Receiver DID" }, "type": { "type": "string", "description": "Task type" }, "status": { "enum": [ "submitted", "working", "input_required", "completed", "failed", "canceled" ], "type": "string", "description": "Current status of the A2A task" }, "input": { "type": "object", "additionalProperties": {}, "description": "Task input payload" }, "output": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Task output payload" }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "description": "Error code" }, "message": { "type": "string", "description": "Error message" } }, "required": [ "code", "message" ] }, { "type": "null" } ], "description": "Error details if task failed" }, "history": { "type": "array", "items": { "type": "object", "properties": { "status": { "enum": [ "submitted", "working", "input_required", "completed", "failed", "canceled" ], "type": "string", "description": "Current status of the A2A task" }, "message": { "type": "string", "description": "Human-readable status message" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp of the event" } }, "required": [ "status", "timestamp" ], "description": "A single status-change event in the task history" }, "description": "Status change history" }, "createdAt": { "type": "string", "format": "date-time", "description": "Task creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "agentId", "orgId", "fromDid", "toDid", "type", "status", "input", "output", "error", "history", "createdAt", "updatedAt" ], "description": "Full A2A task representation" } } } } } } }, "/orgs/{orgId}/audit-logs": { "get": { "operationId": "audit.listLogs", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } }, { "name": "actorId", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by actor identifier" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "actorType", "in": "query", "required": false, "schema": { "enum": [ "API_KEY", "USER", "SYSTEM", "AGENT" ], "type": "string", "description": "Filter by actor type" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by action" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "resourceType", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by resource type" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "resourceId", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by resource identifier" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "result", "in": "query", "required": false, "schema": { "enum": [ "SUCCESS", "FAILURE", "DENIED" ], "type": "string", "description": "Filter by result" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "startDate", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO 8601 start date filter" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "endDate", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO 8601 end date filter" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Pagination cursor" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of entries to return" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique audit log entry identifier" }, "orgId": { "type": "string", "description": "Organization identifier" }, "actorType": { "enum": [ "API_KEY", "USER", "SYSTEM", "AGENT" ], "type": "string", "description": "Type of actor that performed the action" }, "actorId": { "type": "string", "description": "Identifier of the actor" }, "action": { "type": "string", "description": "Action performed (e.g. agent.create)" }, "resourceType": { "type": "string", "description": "Type of resource acted upon" }, "resourceId": { "type": "string", "description": "Identifier of the resource" }, "result": { "enum": [ "SUCCESS", "FAILURE", "DENIED" ], "type": "string", "description": "Result of the audited action" }, "ipAddress": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IP address of the request" }, "userAgent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-Agent header value" }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Additional structured metadata" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp of the event" } }, "required": [ "id", "orgId", "actorType", "actorId", "action", "resourceType", "resourceId", "result", "ipAddress", "userAgent", "metadata", "createdAt" ], "description": "An immutable audit log entry" }, "description": "List of audit log entries" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, null if no more results" }, "totalCount": { "type": "integer", "description": "Total number of entries matching the filters" } }, "required": [ "items", "nextCursor", "totalCount" ], "description": "Paginated list of audit log entries" } } } } } } }, "/orgs/{orgId}/audit-logs/{logId}": { "get": { "operationId": "audit.getLog", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } }, { "name": "logId", "in": "path", "required": true, "schema": { "type": "string", "description": "Audit log entry identifier" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique audit log entry identifier" }, "orgId": { "type": "string", "description": "Organization identifier" }, "actorType": { "enum": [ "API_KEY", "USER", "SYSTEM", "AGENT" ], "type": "string", "description": "Type of actor that performed the action" }, "actorId": { "type": "string", "description": "Identifier of the actor" }, "action": { "type": "string", "description": "Action performed (e.g. agent.create)" }, "resourceType": { "type": "string", "description": "Type of resource acted upon" }, "resourceId": { "type": "string", "description": "Identifier of the resource" }, "result": { "enum": [ "SUCCESS", "FAILURE", "DENIED" ], "type": "string", "description": "Result of the audited action" }, "ipAddress": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IP address of the request" }, "userAgent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-Agent header value" }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Additional structured metadata" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp of the event" } }, "required": [ "id", "orgId", "actorType", "actorId", "action", "resourceType", "resourceId", "result", "ipAddress", "userAgent", "metadata", "createdAt" ], "description": "An immutable audit log entry" } } } } } } }, "/orgs/{orgId}/audit-logs/export": { "post": { "operationId": "audit.exportLogs", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "default": "json", "enum": [ "csv", "json" ], "type": "string", "description": "Export format" }, "startDate": { "type": "string", "description": "ISO 8601 start date" }, "endDate": { "type": "string", "description": "ISO 8601 end date" }, "actorType": { "enum": [ "API_KEY", "USER", "SYSTEM", "AGENT" ], "type": "string", "description": "Filter by actor type" }, "action": { "type": "string", "description": "Filter by action" }, "resourceType": { "type": "string", "description": "Filter by resource type" } }, "required": [], "description": "Input for exporting audit logs" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string", "description": "Exported data as string (CSV or JSON)" }, "format": { "enum": [ "csv", "json" ], "type": "string", "description": "Format of the exported data" }, "count": { "type": "integer", "description": "Number of records exported" } }, "required": [ "data", "format", "count" ], "description": "Exported audit log data" } } } } } } }, "/orgs/{orgId}/access-reviews": { "post": { "operationId": "audit.createAccessReview", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reviewType": { "enum": [ "QUARTERLY", "AD_HOC", "OFFBOARDING" ], "type": "string", "description": "Type of review to create" } }, "required": [ "reviewType" ], "description": "Input for creating a new access review" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique access review identifier" }, "orgId": { "type": "string", "description": "Organization identifier" }, "reviewerId": { "type": "string", "description": "Identifier of the reviewer" }, "reviewType": { "enum": [ "QUARTERLY", "AD_HOC", "OFFBOARDING" ], "type": "string", "description": "Type of access review" }, "status": { "enum": [ "PENDING", "IN_PROGRESS", "COMPLETED" ], "type": "string", "description": "Status of the access review" }, "findings": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Structured review findings" }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 completion timestamp" }, "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp" }, "updatedAt": { "type": "string", "description": "ISO 8601 last update timestamp" } }, "required": [ "id", "orgId", "reviewerId", "reviewType", "status", "findings", "completedAt", "createdAt", "updatedAt" ], "description": "An access review record" } } } } } }, "get": { "operationId": "audit.listAccessReviews", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } }, { "name": "status", "in": "query", "required": false, "schema": { "enum": [ "PENDING", "IN_PROGRESS", "COMPLETED" ], "type": "string", "description": "Filter by status" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Pagination cursor" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of reviews to return" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique access review identifier" }, "orgId": { "type": "string", "description": "Organization identifier" }, "reviewerId": { "type": "string", "description": "Identifier of the reviewer" }, "reviewType": { "enum": [ "QUARTERLY", "AD_HOC", "OFFBOARDING" ], "type": "string", "description": "Type of access review" }, "status": { "enum": [ "PENDING", "IN_PROGRESS", "COMPLETED" ], "type": "string", "description": "Status of the access review" }, "findings": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Structured review findings" }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 completion timestamp" }, "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp" }, "updatedAt": { "type": "string", "description": "ISO 8601 last update timestamp" } }, "required": [ "id", "orgId", "reviewerId", "reviewType", "status", "findings", "completedAt", "createdAt", "updatedAt" ], "description": "An access review record" }, "description": "List of access reviews" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, null if no more results" } }, "required": [ "items", "nextCursor" ], "description": "Paginated list of access reviews" } } } } } } }, "/orgs/{orgId}/access-reviews/{reviewId}/complete": { "post": { "operationId": "audit.completeAccessReview", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } }, { "name": "reviewId", "in": "path", "required": true, "schema": { "type": "string", "description": "Access review identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "findings": { "type": "object", "additionalProperties": {}, "description": "Structured findings from the review" } }, "required": [ "findings" ], "description": "Input for completing an access review" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique access review identifier" }, "orgId": { "type": "string", "description": "Organization identifier" }, "reviewerId": { "type": "string", "description": "Identifier of the reviewer" }, "reviewType": { "enum": [ "QUARTERLY", "AD_HOC", "OFFBOARDING" ], "type": "string", "description": "Type of access review" }, "status": { "enum": [ "PENDING", "IN_PROGRESS", "COMPLETED" ], "type": "string", "description": "Status of the access review" }, "findings": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Structured review findings" }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 completion timestamp" }, "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp" }, "updatedAt": { "type": "string", "description": "ISO 8601 last update timestamp" } }, "required": [ "id", "orgId", "reviewerId", "reviewType", "status", "findings", "completedAt", "createdAt", "updatedAt" ], "description": "An access review record" } } } } } } }, "/orgs/{orgId}/compliance/controls": { "get": { "operationId": "compliance.listControls", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } }, { "name": "framework", "in": "query", "required": false, "schema": { "enum": [ "SOC2", "GDPR", "PCI" ], "type": "string", "description": "Filter by framework" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "category", "in": "query", "required": false, "schema": { "enum": [ "CC1", "CC2", "CC3", "CC4", "CC5", "CC6", "CC7", "CC8", "CC9", "A1", "PI1", "C1", "P1" ], "type": "string", "description": "Filter by category" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "status", "in": "query", "required": false, "schema": { "enum": [ "NOT_STARTED", "IN_PROGRESS", "IMPLEMENTED", "VERIFIED", "FAILED" ], "type": "string", "description": "Filter by status" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Pagination cursor" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of controls to return" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique control identifier" }, "orgId": { "type": "string", "description": "Organization identifier" }, "framework": { "enum": [ "SOC2", "GDPR", "PCI" ], "type": "string", "description": "Compliance framework identifier" }, "controlId": { "type": "string", "description": "Control identifier (e.g. CC1.1)" }, "title": { "type": "string", "description": "Control title" }, "description": { "type": "string", "description": "Control description" }, "category": { "enum": [ "CC1", "CC2", "CC3", "CC4", "CC5", "CC6", "CC7", "CC8", "CC9", "A1", "PI1", "C1", "P1" ], "type": "string", "description": "Trust Service Criteria category" }, "status": { "enum": [ "NOT_STARTED", "IN_PROGRESS", "IMPLEMENTED", "VERIFIED", "FAILED" ], "type": "string", "description": "Current status of the compliance control" }, "owner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Owner responsible for this control" }, "lastTestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp of last test" }, "nextReviewAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp of next review" }, "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp" }, "updatedAt": { "type": "string", "description": "ISO 8601 last update timestamp" } }, "required": [ "id", "orgId", "framework", "controlId", "title", "description", "category", "status", "owner", "lastTestedAt", "nextReviewAt", "createdAt", "updatedAt" ], "description": "A compliance control record" }, "description": "List of compliance controls" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, null if no more results" } }, "required": [ "items", "nextCursor" ], "description": "Paginated list of compliance controls" } } } } } } }, "/orgs/{orgId}/compliance/controls/{controlId}": { "get": { "operationId": "compliance.getControl", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } }, { "name": "controlId", "in": "path", "required": true, "schema": { "type": "string", "description": "Compliance control identifier" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique control identifier" }, "orgId": { "type": "string", "description": "Organization identifier" }, "framework": { "enum": [ "SOC2", "GDPR", "PCI" ], "type": "string", "description": "Compliance framework identifier" }, "controlId": { "type": "string", "description": "Control identifier (e.g. CC1.1)" }, "title": { "type": "string", "description": "Control title" }, "description": { "type": "string", "description": "Control description" }, "category": { "enum": [ "CC1", "CC2", "CC3", "CC4", "CC5", "CC6", "CC7", "CC8", "CC9", "A1", "PI1", "C1", "P1" ], "type": "string", "description": "Trust Service Criteria category" }, "status": { "enum": [ "NOT_STARTED", "IN_PROGRESS", "IMPLEMENTED", "VERIFIED", "FAILED" ], "type": "string", "description": "Current status of the compliance control" }, "owner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Owner responsible for this control" }, "lastTestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp of last test" }, "nextReviewAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp of next review" }, "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp" }, "updatedAt": { "type": "string", "description": "ISO 8601 last update timestamp" } }, "required": [ "id", "orgId", "framework", "controlId", "title", "description", "category", "status", "owner", "lastTestedAt", "nextReviewAt", "createdAt", "updatedAt" ], "description": "A compliance control record" } } } } } }, "patch": { "operationId": "compliance.updateControlStatus", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } }, { "name": "controlId", "in": "path", "required": true, "schema": { "type": "string", "description": "Compliance control identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "enum": [ "NOT_STARTED", "IN_PROGRESS", "IMPLEMENTED", "VERIFIED", "FAILED" ], "type": "string", "description": "New status for the control" }, "owner": { "type": "string", "description": "Owner to assign" }, "nextReviewAt": { "type": "string", "description": "ISO 8601 next review date" } }, "required": [ "status" ], "description": "Input for updating a control's status" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique control identifier" }, "orgId": { "type": "string", "description": "Organization identifier" }, "framework": { "enum": [ "SOC2", "GDPR", "PCI" ], "type": "string", "description": "Compliance framework identifier" }, "controlId": { "type": "string", "description": "Control identifier (e.g. CC1.1)" }, "title": { "type": "string", "description": "Control title" }, "description": { "type": "string", "description": "Control description" }, "category": { "enum": [ "CC1", "CC2", "CC3", "CC4", "CC5", "CC6", "CC7", "CC8", "CC9", "A1", "PI1", "C1", "P1" ], "type": "string", "description": "Trust Service Criteria category" }, "status": { "enum": [ "NOT_STARTED", "IN_PROGRESS", "IMPLEMENTED", "VERIFIED", "FAILED" ], "type": "string", "description": "Current status of the compliance control" }, "owner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Owner responsible for this control" }, "lastTestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp of last test" }, "nextReviewAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp of next review" }, "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp" }, "updatedAt": { "type": "string", "description": "ISO 8601 last update timestamp" } }, "required": [ "id", "orgId", "framework", "controlId", "title", "description", "category", "status", "owner", "lastTestedAt", "nextReviewAt", "createdAt", "updatedAt" ], "description": "A compliance control record" } } } } } } }, "/orgs/{orgId}/compliance/seed": { "post": { "operationId": "compliance.seedFramework", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "framework": { "enum": [ "SOC2", "GDPR", "PCI" ], "type": "string", "description": "Framework to seed controls for" } }, "required": [ "framework" ], "description": "Input for seeding framework controls" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "integer", "description": "Number of controls created" }, "existing": { "type": "integer", "description": "Number of controls already existing" } }, "required": [ "created", "existing" ], "description": "Result of seeding framework controls" } } } } } } }, "/orgs/{orgId}/compliance/controls/{controlId}/evidence": { "get": { "operationId": "compliance.listEvidence", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } }, { "name": "controlId", "in": "path", "required": true, "schema": { "type": "string", "description": "Compliance control identifier" } }, { "name": "type", "in": "query", "required": false, "schema": { "enum": [ "AUTOMATED", "MANUAL", "SCREENSHOT", "DOCUMENT" ], "type": "string", "description": "Filter by evidence type" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "source", "in": "query", "required": false, "schema": { "enum": [ "GITHUB", "AWS", "CLERK", "INTERNAL", "MANUAL" ], "type": "string", "description": "Filter by evidence source" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Pagination cursor" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of items to return" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique evidence item identifier" }, "controlId": { "type": "string", "description": "Associated compliance control identifier" }, "type": { "enum": [ "AUTOMATED", "MANUAL", "SCREENSHOT", "DOCUMENT" ], "type": "string", "description": "Type of evidence item" }, "source": { "enum": [ "GITHUB", "AWS", "CLERK", "INTERNAL", "MANUAL" ], "type": "string", "description": "Source of the evidence" }, "title": { "type": "string", "description": "Evidence title" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Evidence description" }, "content": { "type": "object", "additionalProperties": {}, "description": "Structured evidence content" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL reference for external evidence" }, "collectedAt": { "type": "string", "description": "ISO 8601 collection timestamp" }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 expiration timestamp" }, "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp" } }, "required": [ "id", "controlId", "type", "source", "title", "description", "content", "url", "collectedAt", "expiresAt", "createdAt" ], "description": "An evidence item linked to a compliance control" }, "description": "List of evidence items" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, null if no more results" } }, "required": [ "items", "nextCursor" ], "description": "Paginated list of evidence items" } } } } } }, "post": { "operationId": "compliance.addEvidence", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } }, { "name": "controlId", "in": "path", "required": true, "schema": { "type": "string", "description": "Compliance control identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "enum": [ "AUTOMATED", "MANUAL", "SCREENSHOT", "DOCUMENT" ], "type": "string", "description": "Type of evidence" }, "source": { "enum": [ "GITHUB", "AWS", "CLERK", "INTERNAL", "MANUAL" ], "type": "string", "description": "Source of the evidence" }, "title": { "type": "string", "description": "Evidence title" }, "description": { "type": "string", "description": "Evidence description" }, "content": { "default": {}, "type": "object", "additionalProperties": {}, "description": "Structured evidence content" }, "url": { "type": "string", "description": "URL reference for external evidence" } }, "required": [ "type", "source", "title" ], "description": "Input for adding a manual evidence item" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique evidence item identifier" }, "controlId": { "type": "string", "description": "Associated compliance control identifier" }, "type": { "enum": [ "AUTOMATED", "MANUAL", "SCREENSHOT", "DOCUMENT" ], "type": "string", "description": "Type of evidence item" }, "source": { "enum": [ "GITHUB", "AWS", "CLERK", "INTERNAL", "MANUAL" ], "type": "string", "description": "Source of the evidence" }, "title": { "type": "string", "description": "Evidence title" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Evidence description" }, "content": { "type": "object", "additionalProperties": {}, "description": "Structured evidence content" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL reference for external evidence" }, "collectedAt": { "type": "string", "description": "ISO 8601 collection timestamp" }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 expiration timestamp" }, "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp" } }, "required": [ "id", "controlId", "type", "source", "title", "description", "content", "url", "collectedAt", "expiresAt", "createdAt" ], "description": "An evidence item linked to a compliance control" } } } } } } }, "/orgs/{orgId}/compliance/controls/{controlId}/collect": { "post": { "operationId": "compliance.collectEvidence", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } }, { "name": "controlId", "in": "path", "required": true, "schema": { "type": "string", "description": "Compliance control identifier to collect evidence for" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "Input for triggering automated evidence collection" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "collected": { "type": "integer", "description": "Number of evidence items collected" }, "evidenceIds": { "type": "array", "items": { "type": "string" }, "description": "IDs of the collected evidence items" } }, "required": [ "collected", "evidenceIds" ], "description": "Result of automated evidence collection" } } } } } } }, "/orgs/{orgId}/compliance/summary": { "get": { "operationId": "compliance.getComplianceSummary", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } }, { "name": "framework", "in": "query", "required": true, "schema": { "enum": [ "SOC2", "GDPR", "PCI" ], "type": "string", "description": "Framework to summarize" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "framework": { "type": "string", "description": "Framework identifier" }, "totalControls": { "type": "integer", "description": "Total number of controls" }, "byStatus": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Count of controls by status" }, "byCategory": { "type": "object", "additionalProperties": { "type": "object", "properties": { "total": { "type": "integer" }, "implemented": { "type": "integer" } }, "required": [ "total", "implemented" ] }, "description": "Breakdown by category" }, "overallProgress": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Overall implementation progress percentage" }, "expiredEvidenceCount": { "type": "integer", "description": "Number of expired evidence items" } }, "required": [ "framework", "totalControls", "byStatus", "byCategory", "overallProgress", "expiredEvidenceCount" ], "description": "Compliance framework summary" } } } } } } }, "/orgs/{orgId}/anomaly-alerts": { "get": { "operationId": "anomaly.listAlerts", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } }, { "name": "agentId", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by agent identifier" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "metric", "in": "query", "required": false, "schema": { "enum": [ "email_send_rate", "sms_send_rate", "vault_access_rate", "api_call_rate", "unique_recipients" ], "type": "string", "description": "Filter by metric type" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "severity", "in": "query", "required": false, "schema": { "enum": [ "INFO", "WARNING", "CRITICAL" ], "type": "string", "description": "Filter by severity" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "status", "in": "query", "required": false, "schema": { "enum": [ "TRIGGERED", "ACKNOWLEDGED", "RESOLVED", "FALSE_POSITIVE" ], "type": "string", "description": "Filter by status" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Pagination cursor" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of alerts to return" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique alert identifier" }, "orgId": { "type": "string", "description": "Organization identifier" }, "agentId": { "type": "string", "description": "Agent identifier" }, "metric": { "enum": [ "email_send_rate", "sms_send_rate", "vault_access_rate", "api_call_rate", "unique_recipients" ], "type": "string", "description": "Type of metric being tracked" }, "severity": { "enum": [ "INFO", "WARNING", "CRITICAL" ], "type": "string", "description": "Severity level of the anomaly alert" }, "status": { "enum": [ "TRIGGERED", "ACKNOWLEDGED", "RESOLVED", "FALSE_POSITIVE" ], "type": "string", "description": "Current status of the anomaly alert" }, "baselineValue": { "type": "number", "description": "Expected baseline value" }, "actualValue": { "type": "number", "description": "Observed actual value" }, "zScore": { "type": "number", "description": "Z-score of the deviation" }, "ruleId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identifier of the rule that triggered this alert" }, "details": { "type": "object", "additionalProperties": {}, "description": "Additional details about the anomaly" }, "acknowledgedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who acknowledged the alert" }, "acknowledgedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp when acknowledged" }, "resolvedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who resolved the alert" }, "resolvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp when resolved" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when alert was created" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when alert was last updated" } }, "required": [ "id", "orgId", "agentId", "metric", "severity", "status", "baselineValue", "actualValue", "zScore", "ruleId", "details", "acknowledgedBy", "acknowledgedAt", "resolvedBy", "resolvedAt", "createdAt", "updatedAt" ], "description": "An anomaly detection alert" }, "description": "List of anomaly alerts" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, null if no more results" } }, "required": [ "items", "nextCursor" ], "description": "Paginated list of anomaly alerts" } } } } } } }, "/orgs/{orgId}/anomaly-alerts/{alertId}": { "get": { "operationId": "anomaly.getAlert", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } }, { "name": "alertId", "in": "path", "required": true, "schema": { "type": "string", "description": "Alert identifier" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique alert identifier" }, "orgId": { "type": "string", "description": "Organization identifier" }, "agentId": { "type": "string", "description": "Agent identifier" }, "metric": { "enum": [ "email_send_rate", "sms_send_rate", "vault_access_rate", "api_call_rate", "unique_recipients" ], "type": "string", "description": "Type of metric being tracked" }, "severity": { "enum": [ "INFO", "WARNING", "CRITICAL" ], "type": "string", "description": "Severity level of the anomaly alert" }, "status": { "enum": [ "TRIGGERED", "ACKNOWLEDGED", "RESOLVED", "FALSE_POSITIVE" ], "type": "string", "description": "Current status of the anomaly alert" }, "baselineValue": { "type": "number", "description": "Expected baseline value" }, "actualValue": { "type": "number", "description": "Observed actual value" }, "zScore": { "type": "number", "description": "Z-score of the deviation" }, "ruleId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identifier of the rule that triggered this alert" }, "details": { "type": "object", "additionalProperties": {}, "description": "Additional details about the anomaly" }, "acknowledgedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who acknowledged the alert" }, "acknowledgedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp when acknowledged" }, "resolvedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who resolved the alert" }, "resolvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp when resolved" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when alert was created" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when alert was last updated" } }, "required": [ "id", "orgId", "agentId", "metric", "severity", "status", "baselineValue", "actualValue", "zScore", "ruleId", "details", "acknowledgedBy", "acknowledgedAt", "resolvedBy", "resolvedAt", "createdAt", "updatedAt" ], "description": "An anomaly detection alert" } } } } } } }, "/orgs/{orgId}/anomaly-alerts/{alertId}/acknowledge": { "post": { "operationId": "anomaly.acknowledgeAlert", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } }, { "name": "alertId", "in": "path", "required": true, "schema": { "type": "string", "description": "Alert identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "acknowledgedBy": { "type": "string", "description": "User acknowledging the alert" } }, "required": [ "acknowledgedBy" ], "description": "Input for acknowledging an anomaly alert" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique alert identifier" }, "orgId": { "type": "string", "description": "Organization identifier" }, "agentId": { "type": "string", "description": "Agent identifier" }, "metric": { "enum": [ "email_send_rate", "sms_send_rate", "vault_access_rate", "api_call_rate", "unique_recipients" ], "type": "string", "description": "Type of metric being tracked" }, "severity": { "enum": [ "INFO", "WARNING", "CRITICAL" ], "type": "string", "description": "Severity level of the anomaly alert" }, "status": { "enum": [ "TRIGGERED", "ACKNOWLEDGED", "RESOLVED", "FALSE_POSITIVE" ], "type": "string", "description": "Current status of the anomaly alert" }, "baselineValue": { "type": "number", "description": "Expected baseline value" }, "actualValue": { "type": "number", "description": "Observed actual value" }, "zScore": { "type": "number", "description": "Z-score of the deviation" }, "ruleId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identifier of the rule that triggered this alert" }, "details": { "type": "object", "additionalProperties": {}, "description": "Additional details about the anomaly" }, "acknowledgedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who acknowledged the alert" }, "acknowledgedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp when acknowledged" }, "resolvedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who resolved the alert" }, "resolvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp when resolved" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when alert was created" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when alert was last updated" } }, "required": [ "id", "orgId", "agentId", "metric", "severity", "status", "baselineValue", "actualValue", "zScore", "ruleId", "details", "acknowledgedBy", "acknowledgedAt", "resolvedBy", "resolvedAt", "createdAt", "updatedAt" ], "description": "An anomaly detection alert" } } } } } } }, "/orgs/{orgId}/anomaly-alerts/{alertId}/resolve": { "post": { "operationId": "anomaly.resolveAlert", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } }, { "name": "alertId", "in": "path", "required": true, "schema": { "type": "string", "description": "Alert identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "resolvedBy": { "type": "string", "description": "User resolving the alert" } }, "required": [ "resolvedBy" ], "description": "Input for resolving an anomaly alert" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique alert identifier" }, "orgId": { "type": "string", "description": "Organization identifier" }, "agentId": { "type": "string", "description": "Agent identifier" }, "metric": { "enum": [ "email_send_rate", "sms_send_rate", "vault_access_rate", "api_call_rate", "unique_recipients" ], "type": "string", "description": "Type of metric being tracked" }, "severity": { "enum": [ "INFO", "WARNING", "CRITICAL" ], "type": "string", "description": "Severity level of the anomaly alert" }, "status": { "enum": [ "TRIGGERED", "ACKNOWLEDGED", "RESOLVED", "FALSE_POSITIVE" ], "type": "string", "description": "Current status of the anomaly alert" }, "baselineValue": { "type": "number", "description": "Expected baseline value" }, "actualValue": { "type": "number", "description": "Observed actual value" }, "zScore": { "type": "number", "description": "Z-score of the deviation" }, "ruleId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identifier of the rule that triggered this alert" }, "details": { "type": "object", "additionalProperties": {}, "description": "Additional details about the anomaly" }, "acknowledgedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who acknowledged the alert" }, "acknowledgedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp when acknowledged" }, "resolvedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who resolved the alert" }, "resolvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp when resolved" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when alert was created" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when alert was last updated" } }, "required": [ "id", "orgId", "agentId", "metric", "severity", "status", "baselineValue", "actualValue", "zScore", "ruleId", "details", "acknowledgedBy", "acknowledgedAt", "resolvedBy", "resolvedAt", "createdAt", "updatedAt" ], "description": "An anomaly detection alert" } } } } } } }, "/orgs/{orgId}/anomaly-alerts/{alertId}/false-positive": { "post": { "operationId": "anomaly.falsePositiveAlert", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } }, { "name": "alertId", "in": "path", "required": true, "schema": { "type": "string", "description": "Alert identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "resolvedBy": { "type": "string", "description": "User marking alert as false positive" } }, "required": [ "resolvedBy" ], "description": "Input for marking an anomaly alert as false positive" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique alert identifier" }, "orgId": { "type": "string", "description": "Organization identifier" }, "agentId": { "type": "string", "description": "Agent identifier" }, "metric": { "enum": [ "email_send_rate", "sms_send_rate", "vault_access_rate", "api_call_rate", "unique_recipients" ], "type": "string", "description": "Type of metric being tracked" }, "severity": { "enum": [ "INFO", "WARNING", "CRITICAL" ], "type": "string", "description": "Severity level of the anomaly alert" }, "status": { "enum": [ "TRIGGERED", "ACKNOWLEDGED", "RESOLVED", "FALSE_POSITIVE" ], "type": "string", "description": "Current status of the anomaly alert" }, "baselineValue": { "type": "number", "description": "Expected baseline value" }, "actualValue": { "type": "number", "description": "Observed actual value" }, "zScore": { "type": "number", "description": "Z-score of the deviation" }, "ruleId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identifier of the rule that triggered this alert" }, "details": { "type": "object", "additionalProperties": {}, "description": "Additional details about the anomaly" }, "acknowledgedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who acknowledged the alert" }, "acknowledgedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp when acknowledged" }, "resolvedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who resolved the alert" }, "resolvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp when resolved" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when alert was created" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when alert was last updated" } }, "required": [ "id", "orgId", "agentId", "metric", "severity", "status", "baselineValue", "actualValue", "zScore", "ruleId", "details", "acknowledgedBy", "acknowledgedAt", "resolvedBy", "resolvedAt", "createdAt", "updatedAt" ], "description": "An anomaly detection alert" } } } } } } }, "/orgs/{orgId}/anomaly-rules": { "get": { "operationId": "anomaly.listRules", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } }, { "name": "metric", "in": "query", "required": false, "schema": { "enum": [ "email_send_rate", "sms_send_rate", "vault_access_rate", "api_call_rate", "unique_recipients" ], "type": "string", "description": "Filter by metric" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "enabled", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Filter by enabled status" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Pagination cursor" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of rules to return" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique rule identifier" }, "orgId": { "type": "string", "description": "Organization identifier" }, "name": { "type": "string", "description": "Human-readable rule name" }, "metric": { "enum": [ "email_send_rate", "sms_send_rate", "vault_access_rate", "api_call_rate", "unique_recipients" ], "type": "string", "description": "Type of metric being tracked" }, "condition": { "enum": [ "zscore_gt", "rate_multiplier_gt", "absolute_gt", "time_violation" ], "type": "string", "description": "Detection condition type" }, "threshold": { "type": "number", "description": "Threshold value for the condition" }, "severity": { "enum": [ "INFO", "WARNING", "CRITICAL" ], "type": "string", "description": "Severity level of the anomaly alert" }, "quarantineAction": { "enum": [ "NONE", "SOFT", "HARD" ], "type": "string", "description": "Quarantine action to take when rule triggers" }, "cooldownMinutes": { "type": "integer", "description": "Minutes to wait between alerts for this rule" }, "enabled": { "type": "boolean", "description": "Whether the rule is active" }, "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp" }, "updatedAt": { "type": "string", "description": "ISO 8601 last update timestamp" } }, "required": [ "id", "orgId", "name", "metric", "condition", "threshold", "severity", "quarantineAction", "cooldownMinutes", "enabled", "createdAt", "updatedAt" ], "description": "An anomaly detection rule" }, "description": "List of anomaly rules" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, null if no more results" } }, "required": [ "items", "nextCursor" ], "description": "Paginated list of anomaly rules" } } } } } }, "post": { "operationId": "anomaly.createRule", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Human-readable rule name" }, "metric": { "enum": [ "email_send_rate", "sms_send_rate", "vault_access_rate", "api_call_rate", "unique_recipients" ], "type": "string", "description": "Type of metric being tracked" }, "condition": { "enum": [ "zscore_gt", "rate_multiplier_gt", "absolute_gt", "time_violation" ], "type": "string", "description": "Detection condition type" }, "threshold": { "type": "number", "minimum": 0, "description": "Threshold value for the condition" }, "severity": { "default": "WARNING", "enum": [ "INFO", "WARNING", "CRITICAL" ], "type": "string", "description": "Severity level of the anomaly alert" }, "quarantineAction": { "default": "NONE", "enum": [ "NONE", "SOFT", "HARD" ], "type": "string", "description": "Quarantine action to take when rule triggers" }, "cooldownMinutes": { "default": 60, "type": "integer", "minimum": 0, "maximum": 10080, "description": "Minutes between alerts" }, "enabled": { "default": true, "type": "boolean" } }, "required": [ "name", "metric", "condition", "threshold" ], "description": "Input for creating an anomaly detection rule" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique rule identifier" }, "orgId": { "type": "string", "description": "Organization identifier" }, "name": { "type": "string", "description": "Human-readable rule name" }, "metric": { "enum": [ "email_send_rate", "sms_send_rate", "vault_access_rate", "api_call_rate", "unique_recipients" ], "type": "string", "description": "Type of metric being tracked" }, "condition": { "enum": [ "zscore_gt", "rate_multiplier_gt", "absolute_gt", "time_violation" ], "type": "string", "description": "Detection condition type" }, "threshold": { "type": "number", "description": "Threshold value for the condition" }, "severity": { "enum": [ "INFO", "WARNING", "CRITICAL" ], "type": "string", "description": "Severity level of the anomaly alert" }, "quarantineAction": { "enum": [ "NONE", "SOFT", "HARD" ], "type": "string", "description": "Quarantine action to take when rule triggers" }, "cooldownMinutes": { "type": "integer", "description": "Minutes to wait between alerts for this rule" }, "enabled": { "type": "boolean", "description": "Whether the rule is active" }, "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp" }, "updatedAt": { "type": "string", "description": "ISO 8601 last update timestamp" } }, "required": [ "id", "orgId", "name", "metric", "condition", "threshold", "severity", "quarantineAction", "cooldownMinutes", "enabled", "createdAt", "updatedAt" ], "description": "An anomaly detection rule" } } } } } } }, "/orgs/{orgId}/anomaly-rules/{ruleId}": { "patch": { "operationId": "anomaly.updateRule", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } }, { "name": "ruleId", "in": "path", "required": true, "schema": { "type": "string", "description": "Rule identifier" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "threshold": { "type": "number", "minimum": 0 }, "severity": { "enum": [ "INFO", "WARNING", "CRITICAL" ], "type": "string", "description": "Severity level of the anomaly alert" }, "quarantineAction": { "enum": [ "NONE", "SOFT", "HARD" ], "type": "string", "description": "Quarantine action to take when rule triggers" }, "cooldownMinutes": { "type": "integer", "minimum": 0, "maximum": 10080 }, "enabled": { "type": "boolean" } }, "required": [], "description": "Input for updating an anomaly detection rule" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique rule identifier" }, "orgId": { "type": "string", "description": "Organization identifier" }, "name": { "type": "string", "description": "Human-readable rule name" }, "metric": { "enum": [ "email_send_rate", "sms_send_rate", "vault_access_rate", "api_call_rate", "unique_recipients" ], "type": "string", "description": "Type of metric being tracked" }, "condition": { "enum": [ "zscore_gt", "rate_multiplier_gt", "absolute_gt", "time_violation" ], "type": "string", "description": "Detection condition type" }, "threshold": { "type": "number", "description": "Threshold value for the condition" }, "severity": { "enum": [ "INFO", "WARNING", "CRITICAL" ], "type": "string", "description": "Severity level of the anomaly alert" }, "quarantineAction": { "enum": [ "NONE", "SOFT", "HARD" ], "type": "string", "description": "Quarantine action to take when rule triggers" }, "cooldownMinutes": { "type": "integer", "description": "Minutes to wait between alerts for this rule" }, "enabled": { "type": "boolean", "description": "Whether the rule is active" }, "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp" }, "updatedAt": { "type": "string", "description": "ISO 8601 last update timestamp" } }, "required": [ "id", "orgId", "name", "metric", "condition", "threshold", "severity", "quarantineAction", "cooldownMinutes", "enabled", "createdAt", "updatedAt" ], "description": "An anomaly detection rule" } } } } } }, "delete": { "operationId": "anomaly.deleteRule", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } }, { "name": "ruleId", "in": "path", "required": true, "schema": { "type": "string", "description": "Rule identifier" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "Input for deleting an anomaly detection rule" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the deletion was successful" } }, "required": [ "success" ], "description": "Result of deleting an anomaly rule" } } } } } } }, "/orgs/{orgId}/agents/{agentId}/baselines": { "get": { "operationId": "anomaly.getBaselines", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } }, { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "description": "Agent identifier" } }, { "name": "metric", "in": "query", "required": false, "schema": { "enum": [ "email_send_rate", "sms_send_rate", "vault_access_rate", "api_call_rate", "unique_recipients" ], "type": "string", "description": "Filter by metric" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "period", "in": "query", "required": false, "schema": { "enum": [ "hourly", "daily" ], "type": "string", "description": "Filter by period" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique baseline identifier" }, "agentId": { "type": "string", "description": "Agent identifier" }, "orgId": { "type": "string", "description": "Organization identifier" }, "metric": { "enum": [ "email_send_rate", "sms_send_rate", "vault_access_rate", "api_call_rate", "unique_recipients" ], "type": "string", "description": "Type of metric being tracked" }, "period": { "enum": [ "hourly", "daily" ], "type": "string", "description": "Time period for the baseline" }, "mean": { "type": "number", "description": "Baseline mean value" }, "stddev": { "type": "number", "description": "Baseline standard deviation" }, "sampleCount": { "type": "integer", "description": "Number of samples in baseline" }, "hourlyPattern": { "type": "object", "additionalProperties": {}, "description": "Hourly activity pattern" }, "windowStart": { "type": "string", "description": "ISO 8601 start of baseline window" }, "windowEnd": { "type": "string", "description": "ISO 8601 end of baseline window" }, "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp" }, "updatedAt": { "type": "string", "description": "ISO 8601 last update timestamp" } }, "required": [ "id", "agentId", "orgId", "metric", "period", "mean", "stddev", "sampleCount", "hourlyPattern", "windowStart", "windowEnd", "createdAt", "updatedAt" ], "description": "An agent behavioral baseline" }, "description": "List of baselines" } }, "required": [ "items" ], "description": "Agent baselines" } } } } } } }, "/orgs/{orgId}/agents/{agentId}/quarantine": { "get": { "operationId": "anomaly.getQuarantine", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } }, { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "description": "Agent identifier" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "description": "Agent identifier" }, "orgId": { "type": "string", "description": "Organization identifier" }, "level": { "enum": [ "NONE", "SOFT", "HARD" ], "type": "string", "description": "Current quarantine level of an agent" }, "quarantinedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 quarantine timestamp" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason for quarantine" } }, "required": [ "agentId", "orgId", "level", "quarantinedAt", "reason" ], "description": "Current quarantine state of an agent" } } } } } }, "post": { "operationId": "anomaly.setQuarantine", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } }, { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "description": "Agent identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "level": { "enum": [ "NONE", "SOFT", "HARD" ], "type": "string", "description": "Current quarantine level of an agent" }, "reason": { "type": "string", "description": "Reason for quarantine" } }, "required": [ "level" ], "description": "Input for setting quarantine level" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "description": "Agent identifier" }, "orgId": { "type": "string", "description": "Organization identifier" }, "level": { "enum": [ "NONE", "SOFT", "HARD" ], "type": "string", "description": "Current quarantine level of an agent" }, "quarantinedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 quarantine timestamp" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason for quarantine" } }, "required": [ "agentId", "orgId", "level", "quarantinedAt", "reason" ], "description": "Current quarantine state of an agent" } } } } } }, "delete": { "operationId": "anomaly.releaseQuarantine", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } }, { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "description": "Agent identifier" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "Input for releasing quarantine" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "description": "Agent identifier" }, "orgId": { "type": "string", "description": "Organization identifier" }, "level": { "enum": [ "NONE", "SOFT", "HARD" ], "type": "string", "description": "Current quarantine level of an agent" }, "quarantinedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 quarantine timestamp" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason for quarantine" } }, "required": [ "agentId", "orgId", "level", "quarantinedAt", "reason" ], "description": "Current quarantine state of an agent" } } } } } } }, "/orgs/{orgId}/compliance/reports": { "post": { "operationId": "complianceReporting.generateReport", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "enum": [ "SOC2_SUMMARY", "ACTIVITY_REPORT", "ACCESS_REVIEW", "AUDIT_EXPORT", "GDPR_DSAR" ], "type": "string", "description": "Type of compliance report" }, "title": { "type": "string", "description": "Custom report title" }, "description": { "type": "string", "description": "Custom report description" }, "format": { "default": "JSON", "enum": [ "JSON", "CSV", "PDF" ], "type": "string", "description": "Report format" }, "generatedBy": { "type": "string", "description": "User generating the report" }, "periodStart": { "type": "string", "description": "ISO 8601 report period start" }, "periodEnd": { "type": "string", "description": "ISO 8601 report period end" }, "parameters": { "default": {}, "type": "object", "additionalProperties": {}, "description": "Additional template-specific parameters" } }, "required": [ "type" ], "description": "Input for generating a compliance report" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique report identifier" }, "orgId": { "type": "string", "description": "Organization identifier" }, "type": { "enum": [ "SOC2_SUMMARY", "ACTIVITY_REPORT", "ACCESS_REVIEW", "AUDIT_EXPORT", "GDPR_DSAR" ], "type": "string", "description": "Type of compliance report" }, "title": { "type": "string", "description": "Report title" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Report description" }, "status": { "enum": [ "PENDING", "GENERATING", "COMPLETED", "FAILED" ], "type": "string", "description": "Current status of the report" }, "format": { "enum": [ "JSON", "CSV", "PDF" ], "type": "string", "description": "Export format for the report" }, "parameters": { "type": "object", "additionalProperties": {}, "description": "Report generation parameters" }, "content": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Report content data" }, "errorMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Error message if report generation failed" }, "generatedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who generated the report" }, "periodStart": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 report period start" }, "periodEnd": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 report period end" }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 completion timestamp" }, "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp" }, "updatedAt": { "type": "string", "description": "ISO 8601 last update timestamp" } }, "required": [ "id", "orgId", "type", "title", "description", "status", "format", "parameters", "content", "errorMessage", "generatedBy", "periodStart", "periodEnd", "completedAt", "createdAt", "updatedAt" ], "description": "A compliance report record" } } } } } }, "get": { "operationId": "complianceReporting.listReports", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } }, { "name": "type", "in": "query", "required": false, "schema": { "enum": [ "SOC2_SUMMARY", "ACTIVITY_REPORT", "ACCESS_REVIEW", "AUDIT_EXPORT", "GDPR_DSAR" ], "type": "string", "description": "Filter by report type" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "status", "in": "query", "required": false, "schema": { "enum": [ "PENDING", "GENERATING", "COMPLETED", "FAILED" ], "type": "string", "description": "Filter by status" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Pagination cursor" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of reports to return" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique report identifier" }, "orgId": { "type": "string", "description": "Organization identifier" }, "type": { "enum": [ "SOC2_SUMMARY", "ACTIVITY_REPORT", "ACCESS_REVIEW", "AUDIT_EXPORT", "GDPR_DSAR" ], "type": "string", "description": "Type of compliance report" }, "title": { "type": "string", "description": "Report title" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Report description" }, "status": { "enum": [ "PENDING", "GENERATING", "COMPLETED", "FAILED" ], "type": "string", "description": "Current status of the report" }, "format": { "enum": [ "JSON", "CSV", "PDF" ], "type": "string", "description": "Export format for the report" }, "parameters": { "type": "object", "additionalProperties": {}, "description": "Report generation parameters" }, "content": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Report content data" }, "errorMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Error message if report generation failed" }, "generatedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who generated the report" }, "periodStart": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 report period start" }, "periodEnd": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 report period end" }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 completion timestamp" }, "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp" }, "updatedAt": { "type": "string", "description": "ISO 8601 last update timestamp" } }, "required": [ "id", "orgId", "type", "title", "description", "status", "format", "parameters", "content", "errorMessage", "generatedBy", "periodStart", "periodEnd", "completedAt", "createdAt", "updatedAt" ], "description": "A compliance report record" }, "description": "List of compliance reports" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, null if no more results" } }, "required": [ "items", "nextCursor" ], "description": "Paginated list of compliance reports" } } } } } } }, "/orgs/{orgId}/compliance/reports/{reportId}": { "get": { "operationId": "complianceReporting.getReport", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } }, { "name": "reportId", "in": "path", "required": true, "schema": { "type": "string", "description": "Report identifier" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique report identifier" }, "orgId": { "type": "string", "description": "Organization identifier" }, "type": { "enum": [ "SOC2_SUMMARY", "ACTIVITY_REPORT", "ACCESS_REVIEW", "AUDIT_EXPORT", "GDPR_DSAR" ], "type": "string", "description": "Type of compliance report" }, "title": { "type": "string", "description": "Report title" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Report description" }, "status": { "enum": [ "PENDING", "GENERATING", "COMPLETED", "FAILED" ], "type": "string", "description": "Current status of the report" }, "format": { "enum": [ "JSON", "CSV", "PDF" ], "type": "string", "description": "Export format for the report" }, "parameters": { "type": "object", "additionalProperties": {}, "description": "Report generation parameters" }, "content": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Report content data" }, "errorMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Error message if report generation failed" }, "generatedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who generated the report" }, "periodStart": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 report period start" }, "periodEnd": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 report period end" }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 completion timestamp" }, "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp" }, "updatedAt": { "type": "string", "description": "ISO 8601 last update timestamp" } }, "required": [ "id", "orgId", "type", "title", "description", "status", "format", "parameters", "content", "errorMessage", "generatedBy", "periodStart", "periodEnd", "completedAt", "createdAt", "updatedAt" ], "description": "A compliance report record" } } } } } }, "delete": { "operationId": "complianceReporting.deleteReport", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } }, { "name": "reportId", "in": "path", "required": true, "schema": { "type": "string", "description": "Report identifier" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "Input for deleting a compliance report" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the deletion was successful" } }, "required": [ "success" ], "description": "Result of deleting a report" } } } } } } }, "/orgs/{orgId}/compliance/reports/{reportId}/export": { "post": { "operationId": "complianceReporting.exportReport", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } }, { "name": "reportId", "in": "path", "required": true, "schema": { "type": "string", "description": "Report identifier" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "enum": [ "JSON", "CSV", "PDF" ], "type": "string", "description": "Override export format" } }, "required": [], "description": "Input for exporting a compliance report" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string", "description": "Exported report data" }, "contentType": { "type": "string", "description": "MIME content type" }, "filename": { "type": "string", "description": "Suggested filename" } }, "required": [ "data", "contentType", "filename" ], "description": "Exported report data" } } } } } } }, "/orgs/{orgId}/compliance/templates": { "get": { "operationId": "complianceReporting.listTemplates", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Report template type identifier" }, "title": { "type": "string", "description": "Template title" }, "description": { "type": "string", "description": "Template description" } }, "required": [ "type", "title", "description" ] } } }, "required": [ "items" ], "description": "List of available report templates" } } } } } } }, "/orgs/{orgId}/compliance/dsars": { "post": { "operationId": "complianceReporting.createDsar", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "enum": [ "ACCESS", "DELETE", "RECTIFY", "PORTABILITY", "RESTRICT" ], "type": "string", "description": "Type of data subject request" }, "subjectEmail": { "type": "string", "format": "email", "description": "Email of the data subject" }, "subjectName": { "type": "string", "description": "Name of the data subject" }, "subjectId": { "type": "string", "description": "Identifier of the data subject" }, "description": { "type": "string", "description": "Request description" }, "dueInDays": { "default": 30, "type": "integer", "minimum": 1, "maximum": 90, "description": "Days until due (default 30 for GDPR)" }, "metadata": { "default": {}, "type": "object", "additionalProperties": {}, "description": "Additional metadata" } }, "required": [ "type", "subjectEmail" ], "description": "Input for creating a data subject request" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique DSAR identifier" }, "orgId": { "type": "string", "description": "Organization identifier" }, "type": { "enum": [ "ACCESS", "DELETE", "RECTIFY", "PORTABILITY", "RESTRICT" ], "type": "string", "description": "Type of data subject request" }, "status": { "enum": [ "RECEIVED", "VERIFIED", "IN_PROGRESS", "COMPLETED", "DENIED", "OVERDUE" ], "type": "string", "description": "Current status of the data subject request" }, "subjectEmail": { "type": "string", "description": "Email of the data subject" }, "subjectName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name of the data subject" }, "subjectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identifier of the data subject" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Request description" }, "requestedAt": { "type": "string", "description": "ISO 8601 request timestamp" }, "verifiedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 verification timestamp" }, "dueAt": { "type": "string", "description": "ISO 8601 due date" }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 completion timestamp" }, "processedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who processed the request" }, "response": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Response data" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional metadata" }, "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp" }, "updatedAt": { "type": "string", "description": "ISO 8601 last update timestamp" } }, "required": [ "id", "orgId", "type", "status", "subjectEmail", "subjectName", "subjectId", "description", "requestedAt", "verifiedAt", "dueAt", "completedAt", "processedBy", "response", "metadata", "createdAt", "updatedAt" ], "description": "A data subject access request record" } } } } } }, "get": { "operationId": "complianceReporting.listDsars", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } }, { "name": "type", "in": "query", "required": false, "schema": { "enum": [ "ACCESS", "DELETE", "RECTIFY", "PORTABILITY", "RESTRICT" ], "type": "string", "description": "Filter by DSAR type" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "status", "in": "query", "required": false, "schema": { "enum": [ "RECEIVED", "VERIFIED", "IN_PROGRESS", "COMPLETED", "DENIED", "OVERDUE" ], "type": "string", "description": "Filter by status" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Pagination cursor" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of DSARs to return" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique DSAR identifier" }, "orgId": { "type": "string", "description": "Organization identifier" }, "type": { "enum": [ "ACCESS", "DELETE", "RECTIFY", "PORTABILITY", "RESTRICT" ], "type": "string", "description": "Type of data subject request" }, "status": { "enum": [ "RECEIVED", "VERIFIED", "IN_PROGRESS", "COMPLETED", "DENIED", "OVERDUE" ], "type": "string", "description": "Current status of the data subject request" }, "subjectEmail": { "type": "string", "description": "Email of the data subject" }, "subjectName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name of the data subject" }, "subjectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identifier of the data subject" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Request description" }, "requestedAt": { "type": "string", "description": "ISO 8601 request timestamp" }, "verifiedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 verification timestamp" }, "dueAt": { "type": "string", "description": "ISO 8601 due date" }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 completion timestamp" }, "processedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who processed the request" }, "response": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Response data" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional metadata" }, "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp" }, "updatedAt": { "type": "string", "description": "ISO 8601 last update timestamp" } }, "required": [ "id", "orgId", "type", "status", "subjectEmail", "subjectName", "subjectId", "description", "requestedAt", "verifiedAt", "dueAt", "completedAt", "processedBy", "response", "metadata", "createdAt", "updatedAt" ], "description": "A data subject access request record" }, "description": "List of data subject requests" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, null if no more results" } }, "required": [ "items", "nextCursor" ], "description": "Paginated list of data subject requests" } } } } } } }, "/orgs/{orgId}/compliance/dsars/{dsarId}": { "get": { "operationId": "complianceReporting.getDsar", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } }, { "name": "dsarId", "in": "path", "required": true, "schema": { "type": "string", "description": "DSAR identifier" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique DSAR identifier" }, "orgId": { "type": "string", "description": "Organization identifier" }, "type": { "enum": [ "ACCESS", "DELETE", "RECTIFY", "PORTABILITY", "RESTRICT" ], "type": "string", "description": "Type of data subject request" }, "status": { "enum": [ "RECEIVED", "VERIFIED", "IN_PROGRESS", "COMPLETED", "DENIED", "OVERDUE" ], "type": "string", "description": "Current status of the data subject request" }, "subjectEmail": { "type": "string", "description": "Email of the data subject" }, "subjectName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name of the data subject" }, "subjectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identifier of the data subject" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Request description" }, "requestedAt": { "type": "string", "description": "ISO 8601 request timestamp" }, "verifiedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 verification timestamp" }, "dueAt": { "type": "string", "description": "ISO 8601 due date" }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 completion timestamp" }, "processedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who processed the request" }, "response": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Response data" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional metadata" }, "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp" }, "updatedAt": { "type": "string", "description": "ISO 8601 last update timestamp" } }, "required": [ "id", "orgId", "type", "status", "subjectEmail", "subjectName", "subjectId", "description", "requestedAt", "verifiedAt", "dueAt", "completedAt", "processedBy", "response", "metadata", "createdAt", "updatedAt" ], "description": "A data subject access request record" } } } } } }, "patch": { "operationId": "complianceReporting.updateDsarStatus", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } }, { "name": "dsarId", "in": "path", "required": true, "schema": { "type": "string", "description": "DSAR identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "enum": [ "RECEIVED", "VERIFIED", "IN_PROGRESS", "COMPLETED", "DENIED", "OVERDUE" ], "type": "string", "description": "New status" }, "processedBy": { "type": "string", "description": "User processing the request" }, "response": { "type": "object", "additionalProperties": {}, "description": "Response data to include" } }, "required": [ "status" ], "description": "Input for updating DSAR status" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique DSAR identifier" }, "orgId": { "type": "string", "description": "Organization identifier" }, "type": { "enum": [ "ACCESS", "DELETE", "RECTIFY", "PORTABILITY", "RESTRICT" ], "type": "string", "description": "Type of data subject request" }, "status": { "enum": [ "RECEIVED", "VERIFIED", "IN_PROGRESS", "COMPLETED", "DENIED", "OVERDUE" ], "type": "string", "description": "Current status of the data subject request" }, "subjectEmail": { "type": "string", "description": "Email of the data subject" }, "subjectName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name of the data subject" }, "subjectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identifier of the data subject" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Request description" }, "requestedAt": { "type": "string", "description": "ISO 8601 request timestamp" }, "verifiedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 verification timestamp" }, "dueAt": { "type": "string", "description": "ISO 8601 due date" }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 completion timestamp" }, "processedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who processed the request" }, "response": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Response data" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional metadata" }, "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp" }, "updatedAt": { "type": "string", "description": "ISO 8601 last update timestamp" } }, "required": [ "id", "orgId", "type", "status", "subjectEmail", "subjectName", "subjectId", "description", "requestedAt", "verifiedAt", "dueAt", "completedAt", "processedBy", "response", "metadata", "createdAt", "updatedAt" ], "description": "A data subject access request record" } } } } } } }, "/orgs/{orgId}/compliance/dashboard": { "get": { "operationId": "complianceReporting.getDashboard", "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "description": "Organization identifier" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "reports": { "type": "object", "properties": { "total": { "type": "integer" }, "byType": { "type": "object", "additionalProperties": { "type": "number" } }, "byStatus": { "type": "object", "additionalProperties": { "type": "number" } }, "recentReports": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "type", "title", "status", "createdAt", "completedAt" ] } } }, "required": [ "total", "byType", "byStatus", "recentReports" ] }, "dsars": { "type": "object", "properties": { "total": { "type": "integer" }, "byStatus": { "type": "object", "additionalProperties": { "type": "number" } }, "byType": { "type": "object", "additionalProperties": { "type": "number" } }, "overdue": { "type": "integer" }, "averageResolutionDays": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "recentRequests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "subjectEmail": { "type": "string" }, "dueAt": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "type", "status", "subjectEmail", "dueAt", "createdAt" ] } } }, "required": [ "total", "byStatus", "byType", "overdue", "averageResolutionDays", "recentRequests" ] }, "compliance": { "type": "object", "properties": { "overallProgress": { "type": "integer", "minimum": 0, "maximum": 100 }, "frameworkSummaries": { "type": "array", "items": { "type": "object", "properties": { "framework": { "type": "string" }, "totalControls": { "type": "integer" }, "implementedCount": { "type": "integer" }, "progress": { "type": "integer" } }, "required": [ "framework", "totalControls", "implementedCount", "progress" ] } } }, "required": [ "overallProgress", "frameworkSummaries" ] } }, "required": [ "reports", "dsars", "compliance" ], "description": "Compliance dashboard data" } } } } } } }, "/voice/catalog": { "get": { "operationId": "voice.catalog", "parameters": [ { "name": "gender", "in": "query", "schema": { "enum": [ "male", "female", "neutral" ], "type": "string" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "language", "in": "query", "schema": { "type": "string" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "voices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "gender": { "enum": [ "male", "female", "neutral" ], "type": "string" }, "accent": { "type": "string" }, "age": { "type": "string" }, "descriptors": { "type": "array", "items": { "type": "string" } }, "useCases": { "type": "array", "items": { "type": "string" } }, "language": { "type": "string" }, "sampleUrl": { "type": "string" } }, "required": [ "id", "name", "gender", "descriptors", "useCases", "language" ] } }, "source": { "enum": [ "live", "fallback" ], "type": "string", "description": "Where this list came from. `live` is the upstream catalog. `fallback` is the small committed set served when the upstream is not configured or unreachable — treat it as incomplete, not as the full range of available voices." } }, "required": [ "voices", "source" ] } } } } } } }, "/voice/calls": { "get": { "operationId": "voice.listCalls", "parameters": [ { "name": "agentId", "in": "query", "schema": { "type": "string" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "default": 20, "type": "number", "minimum": 1, "maximum": 100 }, "allowEmptyValue": true, "allowReserved": true }, { "name": "offset", "in": "query", "schema": { "default": 0, "type": "number", "minimum": 0 }, "allowEmptyValue": true, "allowReserved": true }, { "name": "direction", "in": "query", "schema": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "state", "in": "query", "schema": { "type": "string" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "counterparty", "in": "query", "schema": { "type": "string", "description": "Filter to calls with one phone number, in either direction — the call history with that contact. Matched against `to` on outbound calls and `from` on inbound ones." }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "calls": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "agentId": { "type": "string" }, "phoneIdentityId": { "type": "string" }, "direction": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string" }, "state": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "startedAt": { "type": "string" }, "answeredAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "endedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "endReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "durationSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "createdAt": { "type": "string" } }, "required": [ "id", "agentId", "phoneIdentityId", "direction", "state", "from", "to", "startedAt", "answeredAt", "endedAt", "endReason", "durationSeconds", "createdAt" ] } }, "total": { "type": "number" } }, "required": [ "calls", "total" ] } } } } } }, "post": { "operationId": "voice.createCall", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string" }, "agentId": { "type": "string" }, "greeting": { "type": "string" }, "fromNumber": { "type": "string" } }, "required": [ "to" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "callId": { "type": "string" }, "state": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "direction": { "const": "OUTBOUND" } }, "required": [ "callId", "state", "from", "to", "direction" ] } } } } } } }, "/voice/calls/contacts": { "get": { "operationId": "voice.listCallContacts", "parameters": [ { "name": "agentId", "in": "query", "schema": { "type": "string", "description": "Filter to one agent. Optional for master keys (omit for every agent in the org); ignored for agent keys, which always see only their own." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "default": 50, "type": "number", "minimum": 1, "maximum": 100 }, "allowEmptyValue": true, "allowReserved": true }, { "name": "offset", "in": "query", "schema": { "default": 0, "type": "number", "minimum": 0 }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "type": "object", "properties": { "counterparty": { "type": "string", "description": "The other party's phone number (E.164)" }, "agentId": { "type": "string", "description": "Agent that owns these calls" }, "callCount": { "type": "integer", "description": "Total calls exchanged with this number" }, "missedCount": { "type": "integer", "description": "Calls that were never answered. Counted from a missing answer timestamp rather than an end-reason, so declined, timed-out and failed calls all count as nobody picked up." }, "lastCallAt": { "type": "string", "description": "When the most recent call started — the sort key for this list" }, "lastCallDirection": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "description": "Whether the most recent call came in or went out" }, "totalDurationSeconds": { "type": "integer", "description": "Seconds of connected time across every answered call with this number" } }, "required": [ "counterparty", "agentId", "callCount", "missedCount", "lastCallAt", "lastCallDirection", "totalDurationSeconds" ] }, "description": "Contacts, most recent call first" }, "total": { "type": "integer", "description": "Total contacts matching the query" }, "hasMore": { "type": "boolean", "description": "Whether more contacts exist past this page" } }, "required": [ "contacts", "total", "hasMore" ] } } } } } } }, "/voice/calls/{callId}": { "get": { "operationId": "voice.getCall", "parameters": [ { "name": "callId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "agentId": { "type": "string" }, "phoneIdentityId": { "type": "string" }, "direction": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string" }, "state": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "startedAt": { "type": "string" }, "answeredAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "endedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "endReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "durationSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "createdAt": { "type": "string" } }, "required": [ "id", "agentId", "phoneIdentityId", "direction", "state", "from", "to", "startedAt", "answeredAt", "endedAt", "endReason", "durationSeconds", "createdAt" ] } } } } } } }, "/voice/calls/{callId}/transcript": { "get": { "operationId": "voice.getTranscript", "parameters": [ { "name": "callId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "callId": { "type": "string" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "speaker": { "type": "string" }, "text": { "type": "string" }, "startTime": { "type": "number" }, "endTime": { "type": "number" }, "confidence": { "type": "number" }, "isFinal": { "type": "boolean" } }, "required": [ "speaker", "text", "startTime", "endTime", "confidence", "isFinal" ] } } }, "required": [ "callId", "segments" ] } } } } } } }, "/voice/calls/{callId}/recording": { "get": { "operationId": "voice.getRecording", "parameters": [ { "name": "callId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "callId": { "type": "string" }, "downloadUrl": { "type": "string" }, "durationSeconds": { "type": "number" }, "fileSizeBytes": { "type": "number" }, "codec": { "type": "string" }, "storageTier": { "type": "string" }, "consentType": { "type": "string" }, "createdAt": { "type": "string" }, "expiresAt": { "type": "string" } }, "required": [ "callId", "downloadUrl", "durationSeconds", "fileSizeBytes", "codec", "storageTier", "consentType", "createdAt", "expiresAt" ] } } } } } } }, "/voice/search": { "post": { "operationId": "voice.search", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1 }, "agentId": { "type": "string" }, "dateFrom": { "type": "string" }, "dateTo": { "type": "string" }, "limit": { "default": 10, "type": "number", "minimum": 1, "maximum": 50 }, "threshold": { "default": 0.3, "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "query" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "callId": { "type": "string" }, "matchedText": { "type": "string" }, "speaker": { "type": "string" }, "startTime": { "type": "number" }, "endTime": { "type": "number" }, "similarity": { "type": "number" }, "chunkType": { "type": "string" } }, "required": [ "callId", "matchedText", "speaker", "startTime", "endTime", "similarity", "chunkType" ] } } }, "required": [ "results" ] } } } } } } }, "/voice/search/cross-channel": { "post": { "operationId": "voice.crossChannelSearch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1 }, "channels": { "type": "array", "items": { "enum": [ "email", "sms", "voice" ], "type": "string" } }, "agentId": { "type": "string" }, "limit": { "default": 10, "type": "number", "minimum": 1, "maximum": 50 }, "threshold": { "default": 0.3, "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "query" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "channel": { "enum": [ "email", "sms", "voice" ], "type": "string" }, "content": { "type": "string" }, "similarity": { "type": "number" }, "createdAt": { "type": "string" }, "agentId": { "type": "string" }, "callId": { "type": "string" }, "speaker": { "type": "string" }, "startTime": { "type": "number" } }, "required": [ "id", "channel", "content", "similarity", "createdAt", "agentId" ] } } }, "required": [ "results" ] } } } } } } }, "/voice/calls/{callId}/summary": { "get": { "operationId": "voice.getSummary", "parameters": [ { "name": "callId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "callId": { "type": "string" }, "oneLiner": { "type": "string" }, "topics": { "type": "array", "items": { "type": "string" } }, "actionItems": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "owner": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "text", "owner" ] } }, "decisions": { "type": "array", "items": { "type": "string" } }, "openQuestions": { "type": "array", "items": { "type": "string" } }, "nextSteps": { "type": "array", "items": { "type": "string" } }, "intent": { "type": "string" }, "outcome": { "type": "string" }, "narrative": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "generatedAt": { "type": "string" } }, "required": [ "callId", "oneLiner", "topics", "actionItems", "decisions", "openQuestions", "nextSteps", "intent", "outcome", "narrative", "generatedAt" ] } } } } } } }, "/voice/calls/{callId}/score": { "get": { "operationId": "voice.getScore", "parameters": [ { "name": "callId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "callId": { "type": "string" }, "compositeScore": { "type": "number" }, "resolutionScore": { "type": "number" }, "sentimentScore": { "type": "number" }, "complianceScore": { "type": "number" }, "efficiencyScore": { "type": "number" }, "engagementScore": { "type": "number" }, "latencyScore": { "type": "number" }, "metrics": { "type": "object", "additionalProperties": {} }, "scoredAt": { "type": "string" } }, "required": [ "callId", "compositeScore", "resolutionScore", "sentimentScore", "complianceScore", "efficiencyScore", "engagementScore", "latencyScore", "metrics", "scoredAt" ] } } } } } } }, "/voice/analytics": { "get": { "operationId": "voice.analytics", "parameters": [ { "name": "agentId", "in": "query", "schema": { "type": "string" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "dateFrom", "in": "query", "schema": { "type": "string" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "dateTo", "in": "query", "schema": { "type": "string" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "averageCompositeScore": { "type": "number" }, "averageResolutionScore": { "type": "number" }, "averageSentimentScore": { "type": "number" }, "totalCalls": { "type": "number" }, "scoreDistribution": { "type": "object", "properties": { "excellent": { "type": "number" }, "good": { "type": "number" }, "average": { "type": "number" }, "poor": { "type": "number" } }, "required": [ "excellent", "good", "average", "poor" ] } }, "required": [ "averageCompositeScore", "averageResolutionScore", "averageSentimentScore", "totalCalls", "scoreDistribution" ] } } } } } } }, "/voice/calls/{callId}/security": { "get": { "operationId": "voice.getSecurity", "parameters": [ { "name": "callId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "callId": { "type": "string" }, "threats": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "severity": { "enum": [ "low", "medium", "high", "critical" ], "type": "string" }, "segmentIndex": { "type": "number" }, "speaker": { "type": "string" }, "description": { "type": "string" }, "matchedText": { "type": "string" } }, "required": [ "type", "severity", "segmentIndex", "speaker", "description", "matchedText" ] } }, "piiDetected": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "speaker": { "type": "string" }, "segmentIndex": { "type": "number" }, "redacted": { "type": "string" } }, "required": [ "type", "speaker", "segmentIndex", "redacted" ] } }, "compliancePass": { "type": "boolean" }, "riskScore": { "type": "number" }, "scannedAt": { "type": "string" } }, "required": [ "callId", "threats", "piiDetected", "compliancePass", "riskScore", "scannedAt" ] } } } } } } }, "/identities": { "post": { "operationId": "provision.create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 100, "description": "Human-readable name for the agent (e.g. 'shopping-agent')" }, "slug": { "type": "string", "minLength": 2, "maxLength": 64, "pattern": "^[a-z0-9-]+$", "description": "URL-safe identifier. Auto-derived from name if omitted" }, "capabilities": { "type": "array", "items": { "enum": [ "email", "phone", "vault" ], "type": "string" }, "minItems": 1, "description": "Capabilities to provision. Email is always included." }, "email": { "type": "string", "format": "email", "description": "Custom email address. Defaults to {slug}@agents.useanima.sh" }, "phone": { "type": "object", "properties": { "countryCode": { "default": "US", "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2" }, "areaCode": { "type": "string", "description": "Preferred area code" } }, "description": "Phone provisioning options (only used if 'phone' is in capabilities)" }, "metadata": { "default": {}, "type": "object", "additionalProperties": {}, "description": "Arbitrary key-value metadata" } }, "required": [ "name", "capabilities" ], "description": "Provision a complete agent identity in a single call" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Agent ID" }, "name": { "type": "string" }, "slug": { "type": "string" }, "apiKey": { "type": "string", "description": "Agent API key — only returned on creation" }, "email": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "domain": { "type": "string" }, "isPrimary": { "type": "boolean" } }, "required": [ "id", "email", "domain", "isPrimary" ] }, { "type": "null" } ], "description": "Email identity (always provisioned)" }, "phone": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "phoneNumber": { "type": "string" }, "capabilities": { "type": "object", "properties": { "sms": { "type": "boolean" }, "mms": { "type": "boolean" }, "voice": { "type": "boolean" } }, "required": [ "sms", "mms", "voice" ] }, "isPrimary": { "type": "boolean" } }, "required": [ "id", "phoneNumber", "capabilities", "isPrimary" ] }, { "type": "null" } ], "description": "Phone identity (if requested)" }, "vault": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "status" ] }, { "type": "null" } ], "description": "Vault identity (if requested)" }, "failures": { "type": "array", "items": { "type": "object", "properties": { "capability": { "enum": [ "email", "phone", "vault" ], "type": "string" }, "error": { "type": "string" } }, "required": [ "capability", "error" ] }, "description": "Capabilities that failed to provision. Empty on full success." }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "slug", "apiKey", "email", "phone", "vault", "failures", "createdAt" ], "description": "Provisioned agent identity with all requested capabilities" } } } } } } }, "/provisioning-requests": { "post": { "operationId": "provisioningRequest.create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier. Optional when using an agent API key (resolved automatically); required when using a master key." }, "resource": { "enum": [ "VAULT", "PHONE_NUMBER" ], "type": "string", "description": "Resource being requested: VAULT (encrypted secret storage for this agent) or PHONE_NUMBER (a provisioned number, Starter+ only)." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why the agent needs this, shown verbatim to the owner. Required — an unexplained ask is not a decidable one." }, "options": { "type": "object", "properties": { "countryCode": { "type": "string", "minLength": 2, "maxLength": 2, "description": "PHONE_NUMBER: ISO 3166-1 alpha-2 country code, e.g. 'US'" }, "areaCode": { "type": "string", "pattern": "^\\d{3}$", "description": "PHONE_NUMBER: preferred 3-digit area code; any is used if unavailable" } }, "description": "Resource-specific options; ignored for resources that take none" } }, "required": [ "resource", "reason" ], "description": "Ask the organization owner to provision a resource this agent cannot provision itself." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique provisioning request identifier" }, "agentId": { "type": "string", "description": "Agent the resource would belong to" }, "agentName": { "type": "string", "description": "Agent display name, so the owner knows who is asking" }, "resource": { "enum": [ "VAULT", "PHONE_NUMBER", "GENERIC" ], "type": "string", "description": "Resource being requested: VAULT (encrypted secret storage for this agent), PHONE_NUMBER (a provisioned number, Starter+ only), or GENERIC (a master-gated operation the agent tried to perform; approving grants permission rather than provisioning anything)." }, "reason": { "type": "string", "description": "The agent's stated justification" }, "status": { "enum": [ "PENDING", "APPROVED", "DECLINED", "EXPIRED", "CANCELLED" ], "type": "string", "description": "Lifecycle status: PENDING (awaiting the owner), APPROVED (resource provisioned), DECLINED (owner refused — soft, the agent may ask again), EXPIRED (7-day TTL elapsed unanswered), CANCELLED (withdrawn by the agent)." }, "options": { "anyOf": [ { "type": "object", "properties": { "countryCode": { "type": "string", "minLength": 2, "maxLength": 2, "description": "PHONE_NUMBER: ISO 3166-1 alpha-2 country code, e.g. 'US'" }, "areaCode": { "type": "string", "pattern": "^\\d{3}$", "description": "PHONE_NUMBER: preferred 3-digit area code; any is used if unavailable" } }, "description": "Resource-specific options; ignored for resources that take none" }, { "type": "null" } ], "description": "Resource-specific options, if any" }, "permission": { "anyOf": [ { "type": "object", "properties": { "procedurePath": { "type": "string", "description": "The master-gated procedure the agent tried to run, dotted — 'agent.delete'" }, "readOnly": { "type": "boolean", "description": "Whether the procedure is read-only. Derived from the contract's HTTP method on the server so a client never re-derives it, and it is what makes Bypass applicable." }, "argumentPreview": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ], "description": "Redacted sketch of the call's arguments. Null — rather than empty — when the input was not an object, so 'nothing to show' stays distinguishable from 'shown and empty'." } }, "required": [ "procedurePath", "readOnly", "argumentPreview" ], "description": "Present only on a permission request; null on a resource provisioning request" }, { "type": "null" } ], "description": "What the agent was refused, when this request records a permission rather than a resource" }, "expiresAt": { "type": "string", "format": "date-time", "description": "When an unanswered request stops being actionable" }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the owner decided; null while PENDING" }, "decidedNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The owner's note, typically the reason for a decline — surfaced so a second attempt can address the objection instead of repeating the first" }, "provisionedId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id of what approval created (vault identity or phone identity); null unless APPROVED" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the agent asked" }, "emailSent": { "type": "boolean", "description": "Whether the owner was successfully emailed. False means the request is still live and visible in the console — the notification failed, not the request." } }, "required": [ "requestId", "agentId", "agentName", "resource", "reason", "status", "options", "permission", "expiresAt", "decidedAt", "decidedNote", "provisionedId", "createdAt", "emailSent" ], "description": "The created request, plus whether the owner notification actually went out" } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "FORBIDDEN" }, "status": { "const": 403 }, "message": { "type": "string", "default": "Agents can only request resources for themselves." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "No such agent in this organization." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "CONFLICT" }, "status": { "const": 409 }, "message": { "type": "string", "default": "An identical request is already pending for this agent." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } }, "get": { "operationId": "provisioningRequest.list", "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Opaque cursor from a previous response to fetch the next page" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of items to return per page (1–100, default 20)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "agentId", "in": "query", "schema": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier. Optional when using an agent API key (resolved automatically); required when using a master key." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "status", "in": "query", "schema": { "enum": [ "PENDING", "APPROVED", "DECLINED", "EXPIRED", "CANCELLED" ], "type": "string", "description": "Filter by lifecycle status" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "resource", "in": "query", "schema": { "enum": [ "VAULT", "PHONE_NUMBER", "GENERIC" ], "type": "string", "description": "Filter by requested resource" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique provisioning request identifier" }, "agentId": { "type": "string", "description": "Agent the resource would belong to" }, "agentName": { "type": "string", "description": "Agent display name, so the owner knows who is asking" }, "resource": { "enum": [ "VAULT", "PHONE_NUMBER", "GENERIC" ], "type": "string", "description": "Resource being requested: VAULT (encrypted secret storage for this agent), PHONE_NUMBER (a provisioned number, Starter+ only), or GENERIC (a master-gated operation the agent tried to perform; approving grants permission rather than provisioning anything)." }, "reason": { "type": "string", "description": "The agent's stated justification" }, "status": { "enum": [ "PENDING", "APPROVED", "DECLINED", "EXPIRED", "CANCELLED" ], "type": "string", "description": "Lifecycle status: PENDING (awaiting the owner), APPROVED (resource provisioned), DECLINED (owner refused — soft, the agent may ask again), EXPIRED (7-day TTL elapsed unanswered), CANCELLED (withdrawn by the agent)." }, "options": { "anyOf": [ { "type": "object", "properties": { "countryCode": { "type": "string", "minLength": 2, "maxLength": 2, "description": "PHONE_NUMBER: ISO 3166-1 alpha-2 country code, e.g. 'US'" }, "areaCode": { "type": "string", "pattern": "^\\d{3}$", "description": "PHONE_NUMBER: preferred 3-digit area code; any is used if unavailable" } }, "description": "Resource-specific options; ignored for resources that take none" }, { "type": "null" } ], "description": "Resource-specific options, if any" }, "permission": { "anyOf": [ { "type": "object", "properties": { "procedurePath": { "type": "string", "description": "The master-gated procedure the agent tried to run, dotted — 'agent.delete'" }, "readOnly": { "type": "boolean", "description": "Whether the procedure is read-only. Derived from the contract's HTTP method on the server so a client never re-derives it, and it is what makes Bypass applicable." }, "argumentPreview": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ], "description": "Redacted sketch of the call's arguments. Null — rather than empty — when the input was not an object, so 'nothing to show' stays distinguishable from 'shown and empty'." } }, "required": [ "procedurePath", "readOnly", "argumentPreview" ], "description": "Present only on a permission request; null on a resource provisioning request" }, { "type": "null" } ], "description": "What the agent was refused, when this request records a permission rather than a resource" }, "expiresAt": { "type": "string", "format": "date-time", "description": "When an unanswered request stops being actionable" }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the owner decided; null while PENDING" }, "decidedNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The owner's note, typically the reason for a decline — surfaced so a second attempt can address the objection instead of repeating the first" }, "provisionedId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id of what approval created (vault identity or phone identity); null unless APPROVED" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the agent asked" } }, "required": [ "requestId", "agentId", "agentName", "resource", "reason", "status", "options", "permission", "expiresAt", "decidedAt", "decidedNote", "provisionedId", "createdAt" ], "description": "A provisioning request and its current state" } }, "pagination": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "Cursor to pass as the `cursor` parameter to retrieve the next page, or null if no more results" }, "hasMore": { "type": "boolean", "description": "Whether additional pages of results are available" } }, "required": [ "nextCursor", "hasMore" ], "description": "Pagination metadata returned with list responses" } }, "required": [ "items", "pagination" ], "description": "Paginated provisioning requests" } } } } } } }, "/provisioning-requests/{requestId}": { "get": { "operationId": "provisioningRequest.get", "parameters": [ { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Provisioning request identifier" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique provisioning request identifier" }, "agentId": { "type": "string", "description": "Agent the resource would belong to" }, "agentName": { "type": "string", "description": "Agent display name, so the owner knows who is asking" }, "resource": { "enum": [ "VAULT", "PHONE_NUMBER", "GENERIC" ], "type": "string", "description": "Resource being requested: VAULT (encrypted secret storage for this agent), PHONE_NUMBER (a provisioned number, Starter+ only), or GENERIC (a master-gated operation the agent tried to perform; approving grants permission rather than provisioning anything)." }, "reason": { "type": "string", "description": "The agent's stated justification" }, "status": { "enum": [ "PENDING", "APPROVED", "DECLINED", "EXPIRED", "CANCELLED" ], "type": "string", "description": "Lifecycle status: PENDING (awaiting the owner), APPROVED (resource provisioned), DECLINED (owner refused — soft, the agent may ask again), EXPIRED (7-day TTL elapsed unanswered), CANCELLED (withdrawn by the agent)." }, "options": { "anyOf": [ { "type": "object", "properties": { "countryCode": { "type": "string", "minLength": 2, "maxLength": 2, "description": "PHONE_NUMBER: ISO 3166-1 alpha-2 country code, e.g. 'US'" }, "areaCode": { "type": "string", "pattern": "^\\d{3}$", "description": "PHONE_NUMBER: preferred 3-digit area code; any is used if unavailable" } }, "description": "Resource-specific options; ignored for resources that take none" }, { "type": "null" } ], "description": "Resource-specific options, if any" }, "permission": { "anyOf": [ { "type": "object", "properties": { "procedurePath": { "type": "string", "description": "The master-gated procedure the agent tried to run, dotted — 'agent.delete'" }, "readOnly": { "type": "boolean", "description": "Whether the procedure is read-only. Derived from the contract's HTTP method on the server so a client never re-derives it, and it is what makes Bypass applicable." }, "argumentPreview": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ], "description": "Redacted sketch of the call's arguments. Null — rather than empty — when the input was not an object, so 'nothing to show' stays distinguishable from 'shown and empty'." } }, "required": [ "procedurePath", "readOnly", "argumentPreview" ], "description": "Present only on a permission request; null on a resource provisioning request" }, { "type": "null" } ], "description": "What the agent was refused, when this request records a permission rather than a resource" }, "expiresAt": { "type": "string", "format": "date-time", "description": "When an unanswered request stops being actionable" }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the owner decided; null while PENDING" }, "decidedNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The owner's note, typically the reason for a decline — surfaced so a second attempt can address the objection instead of repeating the first" }, "provisionedId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id of what approval created (vault identity or phone identity); null unless APPROVED" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the agent asked" } }, "required": [ "requestId", "agentId", "agentName", "resource", "reason", "status", "options", "permission", "expiresAt", "decidedAt", "decidedNote", "provisionedId", "createdAt" ], "description": "A provisioning request and its current state" } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "No such provisioning request in this organization." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } } }, "/provisioning-requests/{requestId}/approve": { "post": { "operationId": "provisioningRequest.approve", "parameters": [ { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Provisioning request identifier" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "maxLength": 500, "description": "Optional note for the agent, typically why a request was declined" }, "grant": { "enum": [ "once", "always", "reads" ], "type": "string", "description": "Required when approving a permission request; rejected on a resource provisioning request" } }, "required": [], "description": "Owner decision on a pending provisioning request" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique provisioning request identifier" }, "agentId": { "type": "string", "description": "Agent the resource would belong to" }, "agentName": { "type": "string", "description": "Agent display name, so the owner knows who is asking" }, "resource": { "enum": [ "VAULT", "PHONE_NUMBER", "GENERIC" ], "type": "string", "description": "Resource being requested: VAULT (encrypted secret storage for this agent), PHONE_NUMBER (a provisioned number, Starter+ only), or GENERIC (a master-gated operation the agent tried to perform; approving grants permission rather than provisioning anything)." }, "reason": { "type": "string", "description": "The agent's stated justification" }, "status": { "enum": [ "PENDING", "APPROVED", "DECLINED", "EXPIRED", "CANCELLED" ], "type": "string", "description": "Lifecycle status: PENDING (awaiting the owner), APPROVED (resource provisioned), DECLINED (owner refused — soft, the agent may ask again), EXPIRED (7-day TTL elapsed unanswered), CANCELLED (withdrawn by the agent)." }, "options": { "anyOf": [ { "type": "object", "properties": { "countryCode": { "type": "string", "minLength": 2, "maxLength": 2, "description": "PHONE_NUMBER: ISO 3166-1 alpha-2 country code, e.g. 'US'" }, "areaCode": { "type": "string", "pattern": "^\\d{3}$", "description": "PHONE_NUMBER: preferred 3-digit area code; any is used if unavailable" } }, "description": "Resource-specific options; ignored for resources that take none" }, { "type": "null" } ], "description": "Resource-specific options, if any" }, "permission": { "anyOf": [ { "type": "object", "properties": { "procedurePath": { "type": "string", "description": "The master-gated procedure the agent tried to run, dotted — 'agent.delete'" }, "readOnly": { "type": "boolean", "description": "Whether the procedure is read-only. Derived from the contract's HTTP method on the server so a client never re-derives it, and it is what makes Bypass applicable." }, "argumentPreview": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ], "description": "Redacted sketch of the call's arguments. Null — rather than empty — when the input was not an object, so 'nothing to show' stays distinguishable from 'shown and empty'." } }, "required": [ "procedurePath", "readOnly", "argumentPreview" ], "description": "Present only on a permission request; null on a resource provisioning request" }, { "type": "null" } ], "description": "What the agent was refused, when this request records a permission rather than a resource" }, "expiresAt": { "type": "string", "format": "date-time", "description": "When an unanswered request stops being actionable" }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the owner decided; null while PENDING" }, "decidedNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The owner's note, typically the reason for a decline — surfaced so a second attempt can address the objection instead of repeating the first" }, "provisionedId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id of what approval created (vault identity or phone identity); null unless APPROVED" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the agent asked" } }, "required": [ "requestId", "agentId", "agentName", "resource", "reason", "status", "options", "permission", "expiresAt", "decidedAt", "decidedNote", "provisionedId", "createdAt" ], "description": "A provisioning request and its current state" } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "PAYMENT_REQUIRED" }, "status": { "const": 402 }, "message": { "type": "string", "default": "The organization's plan does not allow this resource. Upgrade, then approve again." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "FORBIDDEN" }, "status": { "const": 403 }, "message": { "type": "string", "default": "Approving a provisioning request requires master authority." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "No such provisioning request in this organization." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "CONFLICT" }, "status": { "const": 409 }, "message": { "type": "string", "default": "This request is no longer pending." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "422": { "description": "422", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNPROCESSABLE_CONTENT" }, "status": { "const": 422 }, "message": { "type": "string", "default": "This grant does not apply to this request." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } } }, "/provisioning-requests/{requestId}/decline": { "post": { "operationId": "provisioningRequest.decline", "parameters": [ { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Provisioning request identifier" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "maxLength": 500, "description": "Optional note for the agent, typically why a request was declined" }, "grant": { "enum": [ "once", "always", "reads" ], "type": "string", "description": "Required when approving a permission request; rejected on a resource provisioning request" } }, "required": [], "description": "Owner decision on a pending provisioning request" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique provisioning request identifier" }, "agentId": { "type": "string", "description": "Agent the resource would belong to" }, "agentName": { "type": "string", "description": "Agent display name, so the owner knows who is asking" }, "resource": { "enum": [ "VAULT", "PHONE_NUMBER", "GENERIC" ], "type": "string", "description": "Resource being requested: VAULT (encrypted secret storage for this agent), PHONE_NUMBER (a provisioned number, Starter+ only), or GENERIC (a master-gated operation the agent tried to perform; approving grants permission rather than provisioning anything)." }, "reason": { "type": "string", "description": "The agent's stated justification" }, "status": { "enum": [ "PENDING", "APPROVED", "DECLINED", "EXPIRED", "CANCELLED" ], "type": "string", "description": "Lifecycle status: PENDING (awaiting the owner), APPROVED (resource provisioned), DECLINED (owner refused — soft, the agent may ask again), EXPIRED (7-day TTL elapsed unanswered), CANCELLED (withdrawn by the agent)." }, "options": { "anyOf": [ { "type": "object", "properties": { "countryCode": { "type": "string", "minLength": 2, "maxLength": 2, "description": "PHONE_NUMBER: ISO 3166-1 alpha-2 country code, e.g. 'US'" }, "areaCode": { "type": "string", "pattern": "^\\d{3}$", "description": "PHONE_NUMBER: preferred 3-digit area code; any is used if unavailable" } }, "description": "Resource-specific options; ignored for resources that take none" }, { "type": "null" } ], "description": "Resource-specific options, if any" }, "permission": { "anyOf": [ { "type": "object", "properties": { "procedurePath": { "type": "string", "description": "The master-gated procedure the agent tried to run, dotted — 'agent.delete'" }, "readOnly": { "type": "boolean", "description": "Whether the procedure is read-only. Derived from the contract's HTTP method on the server so a client never re-derives it, and it is what makes Bypass applicable." }, "argumentPreview": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ], "description": "Redacted sketch of the call's arguments. Null — rather than empty — when the input was not an object, so 'nothing to show' stays distinguishable from 'shown and empty'." } }, "required": [ "procedurePath", "readOnly", "argumentPreview" ], "description": "Present only on a permission request; null on a resource provisioning request" }, { "type": "null" } ], "description": "What the agent was refused, when this request records a permission rather than a resource" }, "expiresAt": { "type": "string", "format": "date-time", "description": "When an unanswered request stops being actionable" }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the owner decided; null while PENDING" }, "decidedNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The owner's note, typically the reason for a decline — surfaced so a second attempt can address the objection instead of repeating the first" }, "provisionedId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id of what approval created (vault identity or phone identity); null unless APPROVED" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the agent asked" } }, "required": [ "requestId", "agentId", "agentName", "resource", "reason", "status", "options", "permission", "expiresAt", "decidedAt", "decidedNote", "provisionedId", "createdAt" ], "description": "A provisioning request and its current state" } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "FORBIDDEN" }, "status": { "const": 403 }, "message": { "type": "string", "default": "Declining a provisioning request requires master authority." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "No such provisioning request in this organization." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "CONFLICT" }, "status": { "const": 409 }, "message": { "type": "string", "default": "This request is no longer pending." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } } }, "/provisioning-requests/{requestId}/cancel": { "post": { "operationId": "provisioningRequest.cancel", "parameters": [ { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Provisioning request identifier" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "Input for identifying a specific provisioning request" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique provisioning request identifier" }, "agentId": { "type": "string", "description": "Agent the resource would belong to" }, "agentName": { "type": "string", "description": "Agent display name, so the owner knows who is asking" }, "resource": { "enum": [ "VAULT", "PHONE_NUMBER", "GENERIC" ], "type": "string", "description": "Resource being requested: VAULT (encrypted secret storage for this agent), PHONE_NUMBER (a provisioned number, Starter+ only), or GENERIC (a master-gated operation the agent tried to perform; approving grants permission rather than provisioning anything)." }, "reason": { "type": "string", "description": "The agent's stated justification" }, "status": { "enum": [ "PENDING", "APPROVED", "DECLINED", "EXPIRED", "CANCELLED" ], "type": "string", "description": "Lifecycle status: PENDING (awaiting the owner), APPROVED (resource provisioned), DECLINED (owner refused — soft, the agent may ask again), EXPIRED (7-day TTL elapsed unanswered), CANCELLED (withdrawn by the agent)." }, "options": { "anyOf": [ { "type": "object", "properties": { "countryCode": { "type": "string", "minLength": 2, "maxLength": 2, "description": "PHONE_NUMBER: ISO 3166-1 alpha-2 country code, e.g. 'US'" }, "areaCode": { "type": "string", "pattern": "^\\d{3}$", "description": "PHONE_NUMBER: preferred 3-digit area code; any is used if unavailable" } }, "description": "Resource-specific options; ignored for resources that take none" }, { "type": "null" } ], "description": "Resource-specific options, if any" }, "permission": { "anyOf": [ { "type": "object", "properties": { "procedurePath": { "type": "string", "description": "The master-gated procedure the agent tried to run, dotted — 'agent.delete'" }, "readOnly": { "type": "boolean", "description": "Whether the procedure is read-only. Derived from the contract's HTTP method on the server so a client never re-derives it, and it is what makes Bypass applicable." }, "argumentPreview": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ], "description": "Redacted sketch of the call's arguments. Null — rather than empty — when the input was not an object, so 'nothing to show' stays distinguishable from 'shown and empty'." } }, "required": [ "procedurePath", "readOnly", "argumentPreview" ], "description": "Present only on a permission request; null on a resource provisioning request" }, { "type": "null" } ], "description": "What the agent was refused, when this request records a permission rather than a resource" }, "expiresAt": { "type": "string", "format": "date-time", "description": "When an unanswered request stops being actionable" }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the owner decided; null while PENDING" }, "decidedNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The owner's note, typically the reason for a decline — surfaced so a second attempt can address the objection instead of repeating the first" }, "provisionedId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id of what approval created (vault identity or phone identity); null unless APPROVED" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the agent asked" } }, "required": [ "requestId", "agentId", "agentName", "resource", "reason", "status", "options", "permission", "expiresAt", "decidedAt", "decidedNote", "provisionedId", "createdAt" ], "description": "A provisioning request and its current state" } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "No such provisioning request in this organization." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "CONFLICT" }, "status": { "const": 409 }, "message": { "type": "string", "default": "This request is no longer pending." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } } }, "/agents/{agentId}/permissions": { "get": { "operationId": "agentPermission.list", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Agent whose permissions to read" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "procedurePath": { "type": "string", "description": "Dotted procedure path — 'agent.delete'" }, "group": { "enum": [ "read", "write", "destructive" ], "type": "string", "description": "Derived from the procedure's HTTP method: read (GET), destructive (DELETE), write (everything else). Destructive is separated from write so 'may delete without asking' is a deliberate decision rather than one made in passing." }, "state": { "enum": [ "ASK", "ALWAYS_ALLOW", "NEVER" ], "type": "string", "description": "ASK (file a request and wait for the owner), ALWAYS_ALLOW (proceed without asking), NEVER (refuse outright and do not queue a request)." }, "grantedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Who last set this, when it came from an approval; null if never set" }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When it was last set; null while it has never been set" } }, "required": [ "procedurePath", "group", "state", "grantedBy", "updatedAt" ], "description": "One master-gated procedure and the owner's standing decision about it" } }, "bypassReads": { "type": "boolean", "description": "Whether a blanket READS grant is live: the agent stops asking about read-only procedures entirely. The group-level control for the read group." } }, "required": [ "agentId", "items", "bypassReads" ], "description": "An agent's standing permissions, one row per master-gated procedure" } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "FORBIDDEN" }, "status": { "const": 403 }, "message": { "type": "string", "default": "Reading an agent's permissions requires master authority." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "No such agent in this organization." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } }, "post": { "operationId": "agentPermission.set", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Agent to change" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "procedurePath": { "type": "string", "minLength": 1, "description": "Procedure to set. Omit when setting bypassReads." }, "state": { "enum": [ "ASK", "ALWAYS_ALLOW", "NEVER" ], "type": "string", "description": "Required with procedurePath" }, "bypassReads": { "type": "boolean", "description": "Turn the blanket read-only grant on or off. Omit when setting a procedure." } }, "required": [], "description": "Set one standing decision for an agent" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string" }, "procedurePath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "enum": [ "ASK", "ALWAYS_ALLOW", "NEVER" ], "type": "string", "description": "ASK (file a request and wait for the owner), ALWAYS_ALLOW (proceed without asking), NEVER (refuse outright and do not queue a request)." }, { "type": "null" } ], "description": "ASK (file a request and wait for the owner), ALWAYS_ALLOW (proceed without asking), NEVER (refuse outright and do not queue a request)." }, "bypassReads": { "type": "boolean" } }, "required": [ "agentId", "procedurePath", "state", "bypassReads" ], "description": "The decision as it now stands" } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "FORBIDDEN" }, "status": { "const": 403 }, "message": { "type": "string", "default": "Changing an agent's permissions requires master authority." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "No such agent in this organization." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "422": { "description": "422", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNPROCESSABLE_CONTENT" }, "status": { "const": 422 }, "message": { "type": "string", "default": "Set exactly one of procedurePath (with state) or bypassReads." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } } }, "/agent/sign-up": { "post": { "operationId": "agentSelfService.signUp", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "human_email": { "type": "string", "format": "email", "description": "Your human's email address — used for verification and claiming" }, "username": { "type": "string", "minLength": 2, "maxLength": 64, "pattern": "^[a-z0-9-]+$", "description": "Preferred inbox username (e.g. 'my-agent' → 'my-agent@anima.email')" }, "name": { "type": "string", "minLength": 2, "maxLength": 100, "description": "Display name for the agent. Defaults to username if omitted" }, "provision_vault": { "type": "boolean", "description": "Provision an encrypted vault for the new agent as part of sign-up. This is the only way a self-service agent can obtain a first vault: `vault.provision` is master-gated, and sign-up never discloses the master key. Safe here precisely because the org is being created by this same call — there is no existing privilege to escalate from." } }, "required": [ "human_email", "username" ], "description": "Self-service agent sign-up — no human required" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "description": "Your agent ID" }, "organization_id": { "type": "string", "description": "Your organization ID" }, "inbox_id": { "type": "string", "description": "Your email address (e.g. 'my-agent@anima.email')" }, "api_key": { "type": "string", "description": "Your API key — save this immediately, it won't be shown again" }, "auth_type": { "enum": [ "agent_unverified", "agent_verified", "claimed" ], "type": "string", "description": "Current verification status" }, "vault_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Vault identity id when `provision_vault` was requested and granted, else null. Null with provision_vault=true means the vault feature is off on this deployment — sign-up still succeeded." } }, "required": [ "agent_id", "organization_id", "inbox_id", "api_key", "auth_type", "vault_id" ], "description": "Sign-up response with credentials" } } } } } } }, "/agent/verify": { "post": { "operationId": "agentSelfService.verify", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "otp_code": { "type": "string", "minLength": 6, "maxLength": 6, "description": "6-digit OTP code from your human" } }, "required": [ "otp_code" ], "description": "Verify your identity with OTP code from your human" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean", "description": "Whether verification succeeded" }, "auth_type": { "enum": [ "agent_unverified", "agent_verified", "claimed" ], "type": "string", "description": "Updated verification status" } }, "required": [ "verified", "auth_type" ], "description": "Verification result" } } } } } } }, "/agent/elevate/request": { "post": { "operationId": "agentSelfService.elevateRequest", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "sent_to": { "type": "string", "description": "Owner address the code went to, partially masked (e.g. d***n@example.com)" }, "expires_at": { "type": "string", "format": "date-time", "description": "When the code stops being accepted" } }, "required": [ "sent_to", "expires_at" ], "description": "A step-up code was emailed to the organization owner" } } } } } } }, "/agent/elevate": { "post": { "operationId": "agentSelfService.elevate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "otp_code": { "type": "string", "minLength": 1, "description": "The 6-digit code emailed to the owner by /agent/elevate/request" }, "grant": { "type": "string", "minLength": 1, "description": "An owner grant from a previous enrolment, used instead of an emailed code. The caller is expected to have kept it behind a local human-presence gate." }, "enroll": { "type": "boolean", "description": "Also return a durable owner grant, so later step-ups on this machine need no email. Honoured only when authorising with otp_code — a grant cannot mint its successor." } }, "description": "Step-up parameters" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "type": "string", "description": "Short-lived key with master capability. Shown once; store it now." }, "expires_at": { "type": "string", "format": "date-time", "description": "When the key stops working" }, "api_key_id": { "type": "string", "description": "Id of the issued key, for revoking it early" }, "grant": { "type": "string", "description": "Durable owner grant. Shown once; store it behind a human-presence gate." }, "grant_expires_at": { "type": "string", "format": "date-time", "description": "When the grant stops being accepted and an emailed code is needed again" } }, "required": [ "api_key", "expires_at", "api_key_id" ], "description": "Short-lived master credential" } } } } } } }, "/agent/status": { "get": { "operationId": "agentSelfService.status", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "auth_type": { "enum": [ "agent_unverified", "agent_verified", "claimed" ], "type": "string", "description": "Current verification status" }, "plan": { "type": "string", "description": "Current billing plan (free, starter, growth, enterprise)" }, "limits": { "type": "object", "properties": { "agents": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Max agents (null = unlimited)" }, "agents_used": { "type": "number", "description": "Current agent count" }, "identities": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Max identities (null = unlimited)" }, "identities_used": { "type": "number", "description": "Current identity count" }, "messages": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Max messages per billing period (null = unlimited)" }, "domains": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Max custom domains (null = unlimited)" }, "domains_used": { "type": "number", "description": "Current domain count" } }, "required": [ "agents", "agents_used", "identities", "identities_used", "messages", "domains", "domains_used" ] }, "capabilities": { "type": "object", "properties": { "email": { "type": "boolean", "description": "Email is always available" }, "phone": { "type": "boolean", "description": "Phone provisioning available" }, "vault": { "type": "boolean", "description": "Vault provisioning available" } }, "required": [ "email", "phone", "vault" ] }, "upgrade_url": { "type": "string", "description": "URL for human to upgrade plan" } }, "required": [ "auth_type", "plan", "limits", "capabilities", "upgrade_url" ], "description": "Current organization status and limits" } } } } } } }, "/extension/token": { "post": { "operationId": "extension.createToken", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Agent requesting the extension token. Required for pre_approved policy checks." } }, "description": "Request body for creating an extension auth token" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "exchangeCode": { "type": "string", "description": "One-time exchange code. The extension trades this for the real token via API." }, "policy": { "enum": [ "session", "pre_approved", "prompt_owner" ], "type": "string", "description": "The auth policy that was applied" }, "tokenTtl": { "enum": [ "15m", "1h", "session" ], "type": "string", "description": "Token TTL setting that was applied" }, "requiresApproval": { "type": "boolean", "description": "Whether the owner must approve this token in the extension UI" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 expiration time. Null for session-based (browser manages lifecycle)." }, "connectUrl": { "type": "string", "format": "uri", "description": "URL to open in the browser to authenticate the extension" } }, "required": [ "exchangeCode", "policy", "tokenTtl", "requiresApproval", "expiresAt", "connectUrl" ], "description": "Extension exchange code with connection details" } } } } } } }, "/extension/connect": { "post": { "operationId": "extension.connect", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-z]+$" }, { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" } ], "description": "Agent identifier. Optional when using an agent API key (resolved automatically); required when using a master key." }, "ttl": { "enum": [ "15m", "1h", "session" ], "type": "string", "description": "Override the org tokenTtl for this connection. Shorten-only: a value longer than the org setting (15m < 1h < session) is rejected." } }, "description": "Input for minting a headless extension connection." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "description": "Agent the connection is bound to." }, "connectUrl": { "type": "string", "format": "uri", "description": "Open in a Puppeteer-driven browser to connect the extension." }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Token expiry (null for session)." }, "exchangeExpiresAt": { "type": "string", "format": "date-time", "description": "Single-use code expiry (~60s)." }, "policy": { "enum": [ "session", "pre_approved" ], "type": "string", "description": "Effective org auth policy. Never prompt_owner — headless connect refuses that policy." } }, "required": [ "agentId", "connectUrl", "expiresAt", "exchangeExpiresAt", "policy" ], "description": "Headless extension connection details." } } } } } } }, "/extension/exchange": { "post": { "operationId": "extension.exchangeToken", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "description": "One-time exchange code from createToken" } }, "required": [ "code" ], "description": "Request body for exchanging a code for extension credentials" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Extension auth token (API key) for the browser extension" }, "signingSecret": { "type": "string", "description": "HMAC signing secret for WebSocket bridge messages" }, "orgId": { "type": "string", "description": "Organization ID for channel subscription" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 expiration time. Null for session-based." }, "requiresApproval": { "type": "boolean", "description": "Whether the owner must approve this token in the extension UI" } }, "required": [ "token", "signingSecret", "orgId", "expiresAt", "requiresApproval" ], "description": "Extension credentials returned after code exchange" } } } } } } }, "/extension/revoke": { "post": { "operationId": "extension.revokeToken", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "description": "The extension auth token to revoke" } }, "required": [ "token" ], "description": "Request body for revoking an extension token" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean", "description": "Whether the token was successfully revoked" } }, "required": [ "revoked" ], "description": "Result of revoking an extension token" } } } } } } }, "/extension/settings": { "get": { "operationId": "extension.getSettings", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "authPolicy": { "default": "session", "enum": [ "session", "pre_approved", "prompt_owner" ], "type": "string", "description": "Auth policy for extension connections" }, "tokenTtl": { "default": "session", "enum": [ "15m", "1h", "session" ], "type": "string", "description": "How long extension auth tokens remain valid" }, "preApprovedAgentIds": { "default": [], "type": "array", "items": { "type": "string" }, "description": "Agent IDs allowed to silently authenticate (only used with pre_approved policy)" } }, "description": "Current extension auth settings" } } } } } }, "patch": { "operationId": "extension.updateSettings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "authPolicy": { "enum": [ "session", "pre_approved", "prompt_owner" ], "type": "string", "description": "Updated auth policy" }, "tokenTtl": { "enum": [ "15m", "1h", "session" ], "type": "string", "description": "Updated token TTL" }, "preApprovedAgentIds": { "type": "array", "items": { "type": "string" }, "description": "Updated list of pre-approved agent IDs" } }, "description": "Request body for updating extension auth settings" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "authPolicy": { "default": "session", "enum": [ "session", "pre_approved", "prompt_owner" ], "type": "string", "description": "Auth policy for extension connections" }, "tokenTtl": { "default": "session", "enum": [ "15m", "1h", "session" ], "type": "string", "description": "How long extension auth tokens remain valid" }, "preApprovedAgentIds": { "default": [], "type": "array", "items": { "type": "string" }, "description": "Agent IDs allowed to silently authenticate (only used with pre_approved policy)" } }, "description": "Current extension auth settings" } } } } } } }, "/extension/token/{id}": { "patch": { "operationId": "extension.updateToken", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "API key id of the extension token to update" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "authPolicy": { "enum": [ "session", "pre_approved", "prompt_owner" ], "type": "string", "description": "Updated auth policy for this token" }, "tokenTtl": { "enum": [ "15m", "1h", "session" ], "type": "string", "description": "Updated TTL for this token. Recomputes expiresAt from now." } }, "required": [], "description": "Request body for updating an individual extension token" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "authPolicy": { "enum": [ "session", "pre_approved", "prompt_owner" ], "type": "string", "description": "How agents authenticate the browser extension" }, "tokenTtl": { "enum": [ "15m", "1h", "session" ], "type": "string", "description": "How long the extension auth token stays valid" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "authPolicy", "tokenTtl", "expiresAt" ], "description": "Updated extension token metadata" } } } } } } }, "/mcp-auth/sessions": { "post": { "operationId": "mcpAuth.createSession", "description": "Deprecated: session-based MCP auth was replaced by the OAuth 2.0 Authorization Code + PKCE flow. Always returns 400.", "deprecated": true, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "No input needed — the server generates the session token" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Session ID for the authorize URL" }, "token": { "type": "string", "description": "Secret token for polling — keep this on the MCP server side" }, "authUrl": { "type": "string", "format": "uri", "description": "URL to open in the browser" } }, "required": [ "sessionId", "token", "authUrl" ], "description": "Newly created MCP auth session" } } } } } } }, "/mcp-auth/sessions/{sessionId}/complete": { "post": { "operationId": "mcpAuth.completeSession", "description": "Deprecated: session-based MCP auth was replaced by the OAuth 2.0 Authorization Code + PKCE flow. Always returns 400.", "deprecated": true, "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Session ID from the authorize URL" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "Complete an MCP auth session by creating an API key" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true } }, "required": [ "success" ], "description": "Session completed successfully" } } } } } } }, "/mcp-auth/sessions/{sessionId}/deny": { "post": { "operationId": "mcpAuth.denySession", "description": "Deprecated: session-based MCP auth was replaced by the OAuth 2.0 Authorization Code + PKCE flow. Always returns 400.", "deprecated": true, "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Session ID from the authorize URL" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "description": "Deny an MCP auth session" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true } }, "required": [ "success" ], "description": "Session denied successfully" } } } } } } }, "/mcp-auth/sessions/poll": { "post": { "operationId": "mcpAuth.pollSession", "description": "Deprecated: session-based MCP auth was replaced by the OAuth 2.0 Authorization Code + PKCE flow. Always returns 400.", "deprecated": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "description": "Secret session token from createSession" } }, "required": [ "token" ], "description": "Poll for the session result using the secret token" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "enum": [ "PENDING", "COMPLETED", "DENIED", "EXPIRED" ], "type": "string", "description": "Current session status" }, "apiKey": { "type": "string", "description": "API key, only present when status is COMPLETED" } }, "required": [ "status" ], "description": "Current state of the MCP auth session" } } } } } } }, "/me/orgs": { "get": { "operationId": "me.listOrgs", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier for the organization" }, "name": { "type": "string", "description": "Display name of the organization" }, "slug": { "type": "string", "description": "URL-friendly identifier for the organization" }, "clerkOrgId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "External Clerk organization ID, null if not linked" }, "tier": { "enum": [ "FREE", "STARTER", "GROWTH", "ENTERPRISE" ], "type": "string", "description": "Current subscription tier" }, "keyRotatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp of the last master-key rotation, null if never rotated" }, "settings": { "type": "object", "additionalProperties": {}, "description": "Arbitrary key-value settings for the organization" }, "outboundConsent": { "type": "object", "properties": { "attested": { "type": "boolean", "description": "True once consent source, DNC attestation, and stamp are all present" }, "consentSource": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Declared basis for outbound contact consent, null if unset" }, "dncAttestation": { "type": "boolean", "description": "Whether the org attested it scrubs against Do-Not-Call lists" }, "attestedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp the attestation was recorded, null if never" }, "attestedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Principal (user id or auth method) that recorded the attestation" } }, "required": [ "attested", "consentSource", "dncAttestation", "attestedAt", "attestedBy" ], "description": "Outbound TCPA consent attestation status for this organization" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the organization was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the organization was last modified" }, "role": { "enum": [ "OWNER", "ADMIN", "MEMBER" ], "type": "string", "description": "Authenticated user's role within this org" } }, "required": [ "id", "name", "slug", "clerkOrgId", "tier", "keyRotatedAt", "settings", "outboundConsent", "createdAt", "updatedAt", "role" ], "description": "Organization resource with full details (no secrets)" }, "description": "Orgs the authenticated user is a member of" } }, "required": [ "items" ], "description": "Result of listing the authenticated user's organizations" } } } } } } }, "/me/agents": { "get": { "operationId": "me.listAgents", "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Opaque cursor from a previous response to fetch the next page" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of items to return per page (1–100, default 20)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "status", "in": "query", "schema": { "enum": [ "ACTIVE", "SUSPENDED", "DELETED" ], "type": "string", "description": "Filter agents by lifecycle status" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "query", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Free-text search by name or slug" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the agent" }, "orgId": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Organization ID that owns this agent" }, "name": { "type": "string", "description": "Human-readable display name" }, "slug": { "type": "string", "description": "URL-friendly unique identifier" }, "status": { "enum": [ "ACTIVE", "SUSPENDED", "DELETED" ], "type": "string", "description": "Current lifecycle status" }, "apiKeyPrefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Prefix of the agent's API key for identification, or null if no key is set" }, "keyRotatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO 8601 timestamp of the last API-key rotation, null if never rotated" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Arbitrary key-value metadata" }, "voiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The agent's chosen voice id, or null for the system default." }, "emailIdentities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the email identity" }, "email": { "type": "string", "format": "email", "description": "Full email address" }, "domain": { "type": "string", "description": "Domain portion of the email address" }, "localPart": { "type": "string", "description": "Local part (before the @) of the email address" }, "isPrimary": { "type": "boolean", "description": "Whether this is the agent's primary email identity" }, "verified": { "type": "boolean", "description": "Whether the email address has been verified" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the email identity was created" } }, "required": [ "id", "email", "domain", "localPart", "isPrimary", "verified", "createdAt" ], "description": "Email identity associated with an agent" }, "description": "Email identities associated with this agent" }, "phoneIdentities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Unique identifier of the phone identity" }, "phoneNumber": { "type": "string", "description": "Phone number in E.164 format" }, "providerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque carrier-side identifier for this phone number" }, "capabilities": { "type": "object", "properties": { "sms": { "default": false, "type": "boolean", "description": "Whether the number supports SMS messaging" }, "mms": { "default": false, "type": "boolean", "description": "Whether the number supports MMS messaging" }, "voice": { "default": false, "type": "boolean", "description": "Whether the number supports voice calls" } }, "description": "Communication capabilities supported by this phone number" }, "tenDlcStatus": { "enum": [ "PENDING", "REGISTERED", "REJECTED", "NOT_REQUIRED", "UNREGISTERED" ], "type": "string", "description": "10DLC campaign registration status" }, "isPrimary": { "type": "boolean", "description": "Whether this is the agent's primary phone identity" }, "voiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The voice this number answers with, from the voice catalog. Null means it uses the agent's voice, and then the system default. Set it per number so one agent's support line and sales line can sound different." }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the phone identity was created" } }, "required": [ "id", "phoneNumber", "providerId", "capabilities", "tenDlcStatus", "isPrimary", "voiceId", "createdAt" ], "description": "Phone identity associated with an agent" }, "description": "Phone identities associated with this agent" }, "readiness": { "type": "object", "properties": { "canSendEmail": { "type": "boolean", "description": "True iff the agent has at least one verified email identity right now" }, "canReceiveEmail": { "type": "boolean", "description": "True iff inbound MX is configured for the agent's primary domain" }, "canSendSms": { "type": "boolean", "description": "True iff the agent has a provisioned phone identity with SMS capability that's past 10DLC if required" }, "canPlaceVoiceCall": { "type": "boolean", "description": "True iff the agent has a phone identity with voice capability" }, "blockers": { "type": "array", "items": { "type": "object", "properties": { "code": { "enum": [ "IDENTITY_NOT_VERIFIED", "DOMAIN_NOT_VERIFIED", "PHONE_NOT_PROVISIONED" ], "type": "string", "description": "Stable code matching the typed error thrown at call time" }, "field": { "type": "string", "description": "JSON-path-ish location of the failing field, e.g. emailIdentities[0]" }, "hint": { "type": "string", "description": "Human-readable remediation hint" }, "remediationUrl": { "type": "string", "description": "Optional pointer to where the user can resolve this blocker" } }, "required": [ "code", "field", "hint" ], "description": "One reason a capability isn't currently usable" }, "description": "All current blockers across capabilities; empty array means fully ready" } }, "required": [ "canSendEmail", "canReceiveEmail", "canSendSms", "canPlaceVoiceCall", "blockers" ], "description": "Per-capability readiness summary. Optional for backward compatibility — clients without readiness handling continue to work; clients that branch on it get the delayed-verification gap closed." }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the agent was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the agent was last updated" } }, "required": [ "id", "orgId", "name", "slug", "status", "apiKeyPrefix", "keyRotatedAt", "metadata", "voiceId", "emailIdentities", "phoneIdentities", "createdAt", "updatedAt" ], "description": "Full agent resource representation" }, "description": "Agents from every org the authenticated user belongs to" }, "pagination": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "Cursor to pass as the `cursor` parameter to retrieve the next page, or null if no more results" }, "hasMore": { "type": "boolean", "description": "Whether additional pages of results are available" } }, "required": [ "nextCursor", "hasMore" ], "description": "Pagination metadata returned with list responses" } }, "required": [ "items", "pagination" ], "description": "Paginated cross-org list of agents" } } } } } } }, "/scoped-tokens": { "post": { "operationId": "scopedTokens.issue", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "audience": { "type": "string", "minLength": 1, "description": "Token audience (typically the service identifier, e.g. 'api.useanima.sh')" }, "scopes": { "type": "array", "items": { "type": "string", "minLength": 3 }, "minItems": 1, "description": "Scope strings the token grants, e.g. ['email:send']" }, "ttlSeconds": { "default": 300, "type": "integer", "minimum": 0, "maximum": 3600, "description": "Token TTL in seconds (max 1h)" }, "parentJti": { "type": "string", "minLength": 32, "maxLength": 32, "description": "Parent token jti for delegation chains" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Free-form metadata (task id, conversation id, etc.)" } }, "required": [ "audience", "scopes" ], "description": "Issue a new scoped token" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "pattern": "^stk_", "description": "Raw JWT — only returned at issuance time" }, "record": { "type": "object", "properties": { "id": { "type": "string", "description": "Database id (cuid)" }, "jti": { "type": "string", "minLength": 32, "maxLength": 32, "description": "JWT id (matches the token's jti claim)" }, "agentId": { "type": "string", "description": "Issuing agent id" }, "orgId": { "type": "string", "description": "Organization id" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Granted scopes" }, "audience": { "type": "string", "description": "Audience (aud claim)" }, "parentJti": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Parent token jti, null for root" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Token expiry (ISO 8601)" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Revocation timestamp, null if active" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "required": [ "id", "jti", "agentId", "orgId", "scopes", "audience", "parentJti", "expiresAt", "revokedAt", "createdAt" ], "description": "Persisted record (no raw JWT)" } }, "required": [ "token", "record" ], "description": "Result of issuing a scoped token" } } } } } }, "get": { "operationId": "scopedTokens.list", "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "pattern": "^[cC][^\\s-]{8,}$", "description": "Opaque cursor from a previous response to fetch the next page" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of items to return per page (1–100, default 20)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "agentId", "in": "query", "schema": { "type": "string", "description": "Filter by issuing agent" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "includeExpired", "in": "query", "schema": { "default": false, "type": "boolean", "description": "Include expired tokens" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Database id (cuid)" }, "jti": { "type": "string", "minLength": 32, "maxLength": 32, "description": "JWT id (matches the token's jti claim)" }, "agentId": { "type": "string", "description": "Issuing agent id" }, "orgId": { "type": "string", "description": "Organization id" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Granted scopes" }, "audience": { "type": "string", "description": "Audience (aud claim)" }, "parentJti": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Parent token jti, null for root" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Token expiry (ISO 8601)" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Revocation timestamp, null if active" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "required": [ "id", "jti", "agentId", "orgId", "scopes", "audience", "parentJti", "expiresAt", "revokedAt", "createdAt" ], "description": "Scoped token resource (does NOT include the raw JWT)" } }, "pagination": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string", "pattern": "^[cC][^\\s-]{8,}$" }, { "type": "null" } ], "description": "Cursor to pass as the `cursor` parameter to retrieve the next page, or null if no more results" }, "hasMore": { "type": "boolean", "description": "Whether additional pages of results are available" } }, "required": [ "nextCursor", "hasMore" ], "description": "Pagination metadata returned with list responses" } }, "required": [ "items", "pagination" ], "description": "Paginated list of scoped tokens" } } } } } } }, "/scoped-tokens/revoke": { "post": { "operationId": "scopedTokens.revoke", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jti": { "type": "string", "minLength": 32, "maxLength": 32, "description": "Token jti to revoke" }, "reason": { "type": "string", "maxLength": 200 } }, "required": [ "jti" ], "description": "Revoke a scoped token by jti" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "jti": { "type": "string", "minLength": 32, "maxLength": 32 } }, "required": [ "success", "jti" ], "description": "Revocation confirmation" } } } } } } }, "/oauth/auth-codes/mint": { "post": { "operationId": "oauth.mintAuthCode", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string", "minLength": 1, "description": "OAuth client_id (anima_oauth_apps row)" }, "agentId": { "type": "string", "description": "Optional — restrict grant to a single agent" }, "redirectUri": { "type": "string", "format": "uri", "description": "Where the consent callback lands" }, "scope": { "type": "string", "description": "Space-delimited scope list" }, "codeChallenge": { "type": "string", "minLength": 43, "maxLength": 128, "description": "PKCE S256 challenge (RFC 7636)" }, "codeChallengeMethod": { "default": "S256", "const": "S256" }, "ttlSeconds": { "default": 600, "type": "integer", "minimum": 0, "maximum": 900 }, "consentMetadata": { "type": "object", "properties": { "consentEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "consentEmailVerified": { "type": "boolean" }, "consentName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "description": "Identity hints cached on the resulting grant" } }, "required": [ "clientId", "redirectUri", "scope", "codeChallenge" ], "description": "Mint a one-shot authorization code (10-min TTL by default)" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Raw authorization code — return to the consenting client ONCE" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "code", "expiresAt" ], "description": "Newly-minted authorization code (cleartext, one-time disclosure)" } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "VALIDATION_ERROR" }, "status": { "const": 400 }, "message": { "type": "string", "default": "VALIDATION_ERROR" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "Unauthorized" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "Not Found" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } } }, "/oauth/token": { "post": { "operationId": "oauth.token", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "grantType": { "enum": [ "authorization_code", "refresh_token" ], "type": "string" }, "code": { "type": "string" }, "redirectUri": { "type": "string", "format": "uri" }, "clientId": { "type": "string" }, "codeVerifier": { "type": "string", "minLength": 43, "maxLength": 128 }, "refreshToken": { "type": "string" } }, "required": [ "grantType" ], "description": "OAuth 2.1 token-exchange request" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "`oat_*` access token; bearer in Authorization header" }, "tokenType": { "const": "Bearer" }, "expiresIn": { "type": "integer", "description": "Seconds until access token expires" }, "refreshToken": { "type": "string", "description": "Rotating refresh token. Each /token call issues a new RT; the old one is consumed and any further use of it triggers chain revocation." }, "refreshTokenExpiresIn": { "type": "integer", "description": "Seconds until the refresh token expires (~30 days)" }, "scope": { "type": "string", "description": "Space-delimited granted scope list" } }, "required": [ "accessToken", "tokenType", "expiresIn", "scope" ], "description": "OAuth token response (RFC 6749 §5.1)" } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "INVALID_GRANT" }, "status": { "const": 400 }, "message": { "type": "string", "default": "INVALID_GRANT" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "INVALID_REQUEST" }, "status": { "const": 400 }, "message": { "type": "string", "default": "INVALID_REQUEST" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNSUPPORTED_GRANT_TYPE" }, "status": { "const": 400 }, "message": { "type": "string", "default": "UNSUPPORTED_GRANT_TYPE" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "Unauthorized" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } } }, "/oauth/revoke": { "post": { "operationId": "oauth.revoke", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Either an access token or a refresh token" }, "tokenTypeHint": { "enum": [ "access_token", "refresh_token" ], "type": "string", "description": "Hint to skip one of the two lookups (RFC 7009 §2.1)" } }, "required": [ "token" ], "description": "Revoke an access or refresh token" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean" } }, "required": [ "revoked" ], "description": "Revocation acknowledgment" } } } } } } }, "/oauth/apps/{clientId}": { "get": { "operationId": "oauth.appPreview", "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "homepageUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "privacyPolicyUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "termsOfServiceUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "ownerOrgName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the org that registered the app" }, "approved": { "type": "boolean" } }, "required": [ "clientId", "name", "description", "iconUrl", "homepageUrl", "privacyPolicyUrl", "termsOfServiceUrl", "ownerOrgName", "approved" ], "description": "Public-safe OAuth app metadata for the consent screen" } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "Not Found" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } }, "patch": { "operationId": "oauth.updateApp", "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Existing clientId of the app to update" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "homepageUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "privacyPolicyUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "termsOfServiceUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "redirectUris": { "type": "array", "items": { "type": "string", "format": "uri" }, "minItems": 1, "maxItems": 20 }, "allowedScopes": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, "required": [], "description": "Update an existing OAuth app (partial — only supplied fields change)" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "clientId": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "description": "PENDING_REVIEW until Anima approves; APPROVED for production use" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "clientId", "name", "status", "createdAt" ], "description": "Registered app summary" } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "VALIDATION_ERROR" }, "status": { "const": 400 }, "message": { "type": "string", "default": "VALIDATION_ERROR" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "Unauthorized" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "Not Found" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } } }, "/oauth/register": { "post": { "operationId": "oauth.dynamicRegister", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_name": { "default": "Unnamed MCP Client", "type": "string", "minLength": 1, "maxLength": 120 }, "redirect_uris": { "type": "array", "items": { "type": "string", "format": "uri" }, "minItems": 1, "maxItems": 20 }, "client_uri": { "type": "string", "format": "uri" }, "logo_uri": { "type": "string", "format": "uri" }, "policy_uri": { "type": "string", "format": "uri" }, "tos_uri": { "type": "string", "format": "uri" }, "grant_types": { "type": "array", "items": { "type": "string" } }, "response_types": { "type": "array", "items": { "type": "string" } }, "token_endpoint_auth_method": { "type": "string" }, "scope": { "type": "string" } }, "required": [ "redirect_uris" ], "description": "RFC 7591 Dynamic Client Registration request" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "type": "string" }, "client_id_issued_at": { "type": "integer", "description": "Unix seconds" }, "client_name": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string", "format": "uri" } }, "grant_types": { "type": "array", "items": { "type": "string" } }, "response_types": { "type": "array", "items": { "type": "string" } }, "token_endpoint_auth_method": { "const": "none" }, "scope": { "type": "string" } }, "required": [ "client_id", "client_id_issued_at", "client_name", "redirect_uris", "grant_types", "response_types", "token_endpoint_auth_method" ], "description": "RFC 7591 §3.2.1 dynamic registration response" } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "VALIDATION_ERROR" }, "status": { "const": 400 }, "message": { "type": "string", "default": "VALIDATION_ERROR" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } } }, "/oauth/apps": { "post": { "operationId": "oauth.registerApp", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string", "minLength": 3, "maxLength": 64, "pattern": "^[a-z0-9_-]+$", "description": "Public identifier the third-party app uses in /authorize URLs" }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Display name shown on the consent screen" }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "homepageUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "privacyPolicyUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "termsOfServiceUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "redirectUris": { "type": "array", "items": { "type": "string", "format": "uri" }, "minItems": 1, "maxItems": 20, "description": "Exact-match URIs the consent flow will redirect to. Native CLIs use http://localhost:* or http://127.0.0.1:*." }, "allowedScopes": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Scope strings the app may request on /authorize" }, "ownerOrgId": { "type": "string", "description": "Org that registered the app — defaults to the calling master key's org" } }, "required": [ "clientId", "name", "redirectUris", "allowedScopes" ], "description": "Register a new third-party OAuth app" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "clientId": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "description": "PENDING_REVIEW until Anima approves; APPROVED for production use" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "clientId", "name", "status", "createdAt" ], "description": "Registered app summary" } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "VALIDATION_ERROR" }, "status": { "const": 400 }, "message": { "type": "string", "default": "VALIDATION_ERROR" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "Unauthorized" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "CONFLICT" }, "status": { "const": 409 }, "message": { "type": "string", "default": "Conflict" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } } }, "/oauth/userinfo": { "get": { "operationId": "oauth.userInfo", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "sub": { "type": "string", "description": "Stable user identifier (Clerk user id)" }, "email": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ], "description": "Email if available; null otherwise" }, "emailVerified": { "type": "boolean", "description": "Whether the email was verified at consent time" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name" }, "anima": { "type": "object", "properties": { "orgId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "orgName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "agentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "agentName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "grantId": { "type": "string" } }, "required": [ "orgId", "orgName", "agentId", "agentName", "scopes", "grantId" ] } }, "required": [ "sub", "email", "emailVerified", "name", "anima" ], "description": "Identity claims for the OAuth-authenticated bearer (OIDC-style)" } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "Unauthorized" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT Bearer token obtained from authentication. Pass as: Authorization: Bearer " }, "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key for programmatic access. Pass as: X-API-Key: " } } }, "tags": [ { "name": "Agents", "description": "Create and manage AI agents with email and phone capabilities" }, { "name": "Inboxes", "description": "Manage email inboxes and their configurations" }, { "name": "Messages", "description": "Send, receive, and search email messages" }, { "name": "Webhooks", "description": "Register and manage webhook subscriptions for real-time events" }, { "name": "Organizations", "description": "Manage organizations and team settings" }, { "name": "Domains", "description": "Configure and verify custom email domains" }, { "name": "Phone", "description": "Manage phone numbers and SMS/voice capabilities" }, { "name": "Billing", "description": "View usage, tiers, and billing information" }, { "name": "Security", "description": "Configure security policies and access controls" }, { "name": "Vault", "description": "Store and retrieve encrypted secrets" }, { "name": "API Keys", "description": "Create and manage API keys for programmatic access" } ] }