{ "components": { "schemas": { "AccountIntegration_Details": { "properties": { "config": { "additionalProperties": true, "description": "Versioned integration config. Secrets such as the Slack webhook URL are redacted.", "example": { "_version": 1, "enabled_events": [ "agent_created" ], "webhook_url": { "$sensitive": "string", "labels": [ "authentication_and_secrets" ] } }, "type": "object" }, "id": { "$ref": "#/components/schemas/AccountIntegration_Id" }, "integration_type": { "description": "Integration type key for this account", "example": "slack", "type": "string" }, "status": { "description": "Whether this integration is active or paused", "enum": [ "active", "paused" ], "example": "active", "type": "string" }, "type": { "description": "Type of resource (always 'account_integration')", "enum": [ "account_integration" ], "example": "account_integration", "type": "string" } }, "required": [ "config", "id", "integration_type", "status", "type" ], "title": "AccountIntegration_Details", "type": "object" }, "AccountIntegration_DetailsForCreate": { "properties": { "config": { "additionalProperties": true, "description": "Versioned integration config, including any required secrets", "example": { "_version": 1, "webhook_url": "https://hooks.slack.com/services/T123/B456/secret" }, "type": "object" }, "integration_type": { "description": "Integration type key", "example": "slack", "type": "string" }, "status": { "description": "Whether this integration is active or paused", "enum": [ "active", "paused" ], "example": "active", "type": "string" } }, "required": [ "config", "integration_type", "status" ], "title": "AccountIntegration_DetailsForCreate", "type": "object" }, "AccountIntegration_DetailsForUpdate": { "description": "Parameters for updating an account integration", "properties": { "config": { "additionalProperties": true, "description": "Replacement integration config (omit to keep current)", "example": { "_version": 1, "webhook_url": "https://hooks.slack.com/services/T123/B456/secret" }, "type": "object" }, "status": { "description": "Whether this integration is active or paused (omit to keep current)", "enum": [ "active", "paused" ], "example": "active", "type": "string" } }, "title": "AccountIntegration_DetailsForUpdate", "type": "object" }, "AccountIntegration_Id": { "description": "A valid account integration ID", "example": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "title": "AccountIntegration_Id", "type": "string" }, "AccountIntegration_Summary": { "properties": { "id": { "$ref": "#/components/schemas/AccountIntegration_Id" }, "integration_type": { "description": "Integration type key for this account", "example": "slack", "type": "string" }, "status": { "description": "Whether this integration is active or paused", "enum": [ "active", "paused" ], "example": "active", "type": "string" }, "type": { "description": "Type of resource (always 'account_integration')", "enum": [ "account_integration" ], "example": "account_integration", "type": "string" } }, "required": [ "id", "integration_type", "status", "type" ], "title": "AccountIntegration_Summary", "type": "object" }, "Account_Details": { "properties": { "id": { "$ref": "#/components/schemas/Account_Id" }, "inserted_at": { "description": "When the account was created", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "name": { "description": "Account name", "example": "My Account", "type": "string" }, "organisation_name": { "oneOf": [ { "description": "Organisation name (when purpose is not personal)", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "promo_code": { "oneOf": [ { "description": "Promo code", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "purpose": { "description": "Account purpose", "enum": [ "business", "personal", "nonprofit", "education", "government" ], "example": "business", "type": "string" }, "type": { "description": "Type of resource (always 'account')", "enum": [ "account" ], "example": "account", "type": "string" }, "website": { "oneOf": [ { "description": "Website URL", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] } }, "required": [ "id", "inserted_at", "name", "organisation_name", "promo_code", "purpose", "type", "website" ], "title": "Account_Details", "type": "object" }, "Account_DetailsForUpdate": { "properties": { "name": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "organisation_name": { "oneOf": [ { "description": "Organisation name (required when purpose is not personal)", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "purpose": { "oneOf": [ { "enum": [ "business", "personal", "nonprofit", "education", "government" ], "example": "business", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "website": { "oneOf": [ { "description": "Website URL", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] } }, "title": "Account_DetailsForUpdate", "type": "object" }, "Account_Id": { "description": "A valid account ID", "example": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "title": "Account_Id", "type": "string" }, "Account_Summary": { "properties": { "id": { "$ref": "#/components/schemas/Account_Id" }, "name": { "description": "Account name", "example": "My Account", "type": "string" }, "type": { "description": "Type of resource (always 'account')", "enum": [ "account" ], "example": "account", "type": "string" } }, "required": [ "id", "name", "type" ], "title": "Account_Summary", "type": "object" }, "ActionProfile": { "properties": { "create_data": { "description": "Creates data", "enum": [ "unknown", "allowed", "disallowed" ], "example": "unknown", "type": "string" }, "destroy_data": { "description": "Destroys data", "enum": [ "unknown", "allowed", "disallowed" ], "example": "unknown", "type": "string" }, "external_communication": { "description": "Sends external communications", "enum": [ "unknown", "allowed", "disallowed" ], "example": "unknown", "type": "string" }, "financial_transactions": { "description": "Performs financial transactions", "enum": [ "unknown", "allowed", "disallowed" ], "example": "unknown", "type": "string" }, "read_data": { "description": "Reads data", "enum": [ "unknown", "allowed", "disallowed" ], "example": "unknown", "type": "string" }, "update_data": { "description": "Updates data", "enum": [ "unknown", "allowed", "disallowed" ], "example": "unknown", "type": "string" } }, "required": [ "create_data", "destroy_data", "external_communication", "financial_transactions", "read_data", "update_data" ], "title": "ActionProfile", "type": "object" }, "AdminUserInvite_Details": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "email": { "description": "Email address the invite was sent to", "example": "user@example.com", "type": "string" }, "id": { "$ref": "#/components/schemas/AdminUserInvite_Id" }, "inserted_at": { "description": "When the invite was created", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "invite_url": { "description": "URL to accept the invite", "example": "https://example.com", "format": "uri", "title": "Uri", "type": "string" }, "role": { "description": "Access role the invited admin user will receive", "enum": [ "read_only", "full_access" ], "example": "read_only", "type": "string" }, "status": { "description": "Current status of the invite", "enum": [ "pending", "used", "revoked" ], "example": "pending", "type": "string" }, "token": { "description": "Unique token for the invite", "example": "abc123def456...", "type": "string" }, "type": { "description": "Type of resource (always 'admin_user_invite')", "enum": [ "admin_user_invite" ], "example": "admin_user_invite", "type": "string" }, "updated_at": { "description": "When the invite was last updated", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" } }, "required": [ "account_id", "email", "id", "inserted_at", "invite_url", "role", "status", "token", "type", "updated_at" ], "title": "AdminUserInvite_Details", "type": "object" }, "AdminUserInvite_DetailsForCreate": { "properties": { "account_id": { "description": "Account ID (defaults to token's account if not provided)", "oneOf": [ { "$ref": "#/components/schemas/Account_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "email": { "description": "Email address to send the invite to", "example": "user@example.com", "type": "string" }, "role": { "description": "Access role the invited admin user will receive (optional; defaults to full_access if omitted)", "oneOf": [ { "enum": [ "read_only", "full_access" ], "example": "read_only", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] } }, "title": "AdminUserInvite_DetailsForCreate", "type": "object" }, "AdminUserInvite_Id": { "description": "A valid admin user invite ID", "example": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "title": "AdminUserInvite_Id", "type": "string" }, "AdminUserInvite_Summary": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "email": { "description": "Email address the invite was sent to", "example": "user@example.com", "type": "string" }, "id": { "$ref": "#/components/schemas/AdminUserInvite_Id" }, "inserted_at": { "description": "When the invite was created", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "invite_url": { "description": "URL to accept the invite", "example": "https://example.com", "format": "uri", "title": "Uri", "type": "string" }, "role": { "description": "Access role the invited admin user will receive", "enum": [ "read_only", "full_access" ], "example": "read_only", "type": "string" }, "status": { "description": "Current status of the invite", "enum": [ "pending", "used", "revoked" ], "example": "pending", "type": "string" }, "type": { "description": "Type of resource (always 'admin_user_invite')", "enum": [ "admin_user_invite" ], "example": "admin_user_invite", "type": "string" }, "updated_at": { "description": "When the invite was last updated", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" } }, "required": [ "account_id", "email", "id", "inserted_at", "invite_url", "role", "status", "type", "updated_at" ], "title": "AdminUserInvite_Summary", "type": "object" }, "AdminUser_Details": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "email": { "description": "Admin user email", "example": "john@example.com", "type": "string" }, "id": { "$ref": "#/components/schemas/AdminUser_Id" }, "inserted_at": { "description": "When the admin user was created", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "job_title": { "oneOf": [ { "description": "Job title within the account", "example": "Developer", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "last_active_at": { "oneOf": [ { "description": "When the admin user was last active; nil means no recorded activity", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "name": { "oneOf": [ { "description": "Admin user name", "example": "John Doe", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "profile_completed_at": { "oneOf": [ { "description": "When the user completed their profile (set on profile completion)", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "role": { "description": "Access role of the admin user", "enum": [ "read_only", "full_access" ], "example": "read_only", "type": "string" }, "switchable_account_summaries": { "description": "Accounts this admin user can switch to", "items": { "$ref": "#/components/schemas/Account_Summary" }, "type": "array" }, "type": { "description": "Type of resource (always 'admin_user')", "enum": [ "admin_user" ], "example": "admin_user", "type": "string" }, "updated_at": { "description": "When the admin user was last updated", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" } }, "required": [ "account_id", "email", "id", "inserted_at", "job_title", "last_active_at", "name", "profile_completed_at", "role", "switchable_account_summaries", "type", "updated_at" ], "title": "AdminUser_Details", "type": "object" }, "AdminUser_DetailsForUpdate": { "properties": { "job_title": { "oneOf": [ { "description": "Job title within the account", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "name": { "description": "Admin user name", "type": "string" }, "profile_completed_at": { "oneOf": [ { "description": "When the user completed their profile (set on profile completion)", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] } }, "title": "AdminUser_DetailsForUpdate", "type": "object" }, "AdminUser_DetailsForUpdateRole": { "properties": { "role": { "description": "Access role of the admin user", "enum": [ "read_only", "full_access" ], "example": "read_only", "type": "string" } }, "required": [ "role" ], "title": "AdminUser_DetailsForUpdateRole", "type": "object" }, "AdminUser_Id": { "description": "A valid admin user ID", "example": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "title": "AdminUser_Id", "type": "string" }, "AdminUser_Summary": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "email": { "description": "Admin user email", "example": "john@example.com", "type": "string" }, "id": { "$ref": "#/components/schemas/AdminUser_Id" }, "inserted_at": { "description": "When the admin user was created", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "job_title": { "oneOf": [ { "description": "Job title within the account", "example": "Developer", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "last_active_at": { "oneOf": [ { "description": "When the admin user was last active; nil means no recorded activity", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "name": { "oneOf": [ { "description": "Admin user name", "example": "John Doe", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "profile_completed_at": { "oneOf": [ { "description": "When the user completed their profile (set on profile completion)", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "role": { "description": "Access role of the admin user", "enum": [ "read_only", "full_access" ], "example": "read_only", "type": "string" }, "type": { "description": "Type of resource (always 'admin_user')", "enum": [ "admin_user" ], "example": "admin_user", "type": "string" }, "updated_at": { "description": "When the admin user was last updated", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" } }, "required": [ "account_id", "email", "id", "inserted_at", "job_title", "last_active_at", "name", "profile_completed_at", "role", "type", "updated_at" ], "title": "AdminUser_Summary", "type": "object" }, "AgentDeployment_Details": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "current_version_id": { "description": "Pinned current version for this deployment, if any.", "oneOf": [ { "$ref": "#/components/schemas/AgentVersion_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "environment_id": { "$ref": "#/components/schemas/Environment_Id" }, "id": { "$ref": "#/components/schemas/AgentDeployment_Id" }, "inserted_at": { "description": "When the deployment was created", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "type": { "description": "Type of resource (always 'agent_deployment')", "enum": [ "agent_deployment" ], "example": "agent_deployment", "type": "string" }, "updated_at": { "description": "When the deployment was last updated", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" } }, "required": [ "account_id", "agent_id", "current_version_id", "environment_id", "id", "inserted_at", "type", "updated_at" ], "title": "AgentDeployment_Details", "type": "object" }, "AgentDeployment_DetailsForCreate": { "properties": { "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "current_version_id": { "description": "Optional pinned version for this deployment; omit if none.", "oneOf": [ { "$ref": "#/components/schemas/AgentVersion_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "environment_id": { "$ref": "#/components/schemas/Environment_Id" }, "id": { "description": "Optional deployment id. If omitted, a generated id is used (partition matches account). Its embedded timestamp must not be more than 7 days in the past.", "oneOf": [ { "$ref": "#/components/schemas/AgentDeployment_Id" }, { "$ref": "#/components/schemas/Null" } ] } }, "required": [ "agent_id", "environment_id" ], "title": "AgentDeployment_DetailsForCreate", "type": "object" }, "AgentDeployment_DetailsForUpdate": { "properties": { "current_version_id": { "description": "Current agent version for this deployment.", "oneOf": [ { "$ref": "#/components/schemas/AgentVersion_Id" }, { "$ref": "#/components/schemas/Null" } ] } }, "title": "AgentDeployment_DetailsForUpdate", "type": "object" }, "AgentDeployment_Id": { "description": "A valid agent deployment ID", "example": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "title": "AgentDeployment_Id", "type": "string" }, "AgentDeployment_Summary": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "current_version_id": { "description": "Pinned current version for this deployment, if any.", "oneOf": [ { "$ref": "#/components/schemas/AgentVersion_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "environment_id": { "$ref": "#/components/schemas/Environment_Id" }, "id": { "$ref": "#/components/schemas/AgentDeployment_Id" }, "inserted_at": { "description": "When the deployment was created", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "type": { "description": "Type of resource (always 'agent_deployment')", "enum": [ "agent_deployment" ], "example": "agent_deployment", "type": "string" }, "updated_at": { "description": "When the deployment was last updated", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" } }, "required": [ "account_id", "agent_id", "current_version_id", "environment_id", "id", "inserted_at", "type", "updated_at" ], "title": "AgentDeployment_Summary", "type": "object" }, "AgentInstance_AgentContext": { "properties": { "body": { "additionalProperties": true, "description": "Minimal JSON context with agent_instance, agent, and spans", "type": "object" }, "generated_at": { "description": "When this context was generated", "format": "date-time", "type": "string" }, "span_count": { "description": "Number of spans on the main agent instance", "minimum": 0, "type": "integer" } }, "required": [ "body", "generated_at", "span_count" ], "title": "AgentInstance_AgentContext", "type": "object" }, "AgentInstance_CostBreakdown": { "properties": { "cache_read": { "description": "Total cache-read tokens across all models", "example": 0, "minimum": 0, "type": "integer" }, "cache_read_cost": { "oneOf": [ { "description": "Estimated total USD cost for cache-read tokens", "example": 0.0, "type": "number" }, { "$ref": "#/components/schemas/Null" } ] }, "groups": { "description": "Per-model breakdown", "items": { "$ref": "#/components/schemas/AgentInstance_CostBreakdown_Group" }, "type": "array" }, "input": { "description": "Total input tokens across all models", "example": 10000, "minimum": 0, "type": "integer" }, "input_cost": { "oneOf": [ { "description": "Estimated total USD cost for input tokens", "example": 0.025, "type": "number" }, { "$ref": "#/components/schemas/Null" } ] }, "output": { "description": "Total output tokens across all models", "example": 5000, "minimum": 0, "type": "integer" }, "output_cost": { "oneOf": [ { "description": "Estimated total USD cost for output tokens", "example": 0.05, "type": "number" }, { "$ref": "#/components/schemas/Null" } ] }, "total_cost": { "oneOf": [ { "description": "Estimated total USD cost", "example": 0.075, "type": "number" }, { "$ref": "#/components/schemas/Null" } ] } }, "required": [ "cache_read", "cache_read_cost", "groups", "input", "input_cost", "output", "output_cost", "total_cost" ], "title": "AgentInstance_CostBreakdown", "type": "object" }, "AgentInstance_CostBreakdown_Group": { "properties": { "cache_read": { "description": "Total cache-read tokens for this model", "example": 0, "minimum": 0, "type": "integer" }, "cache_read_cost": { "oneOf": [ { "description": "Estimated USD cost for cache-read tokens", "example": 0.0, "type": "number" }, { "$ref": "#/components/schemas/Null" } ] }, "context_limit": { "oneOf": [ { "description": "Context window size from models.dev pricing, when known", "example": 128000, "type": "integer" }, { "$ref": "#/components/schemas/Null" } ] }, "input": { "description": "Total input tokens for this model", "example": 1000, "minimum": 0, "type": "integer" }, "input_cost": { "oneOf": [ { "description": "Estimated USD cost for input tokens", "example": 0.0025, "type": "number" }, { "$ref": "#/components/schemas/Null" } ] }, "model_name": { "description": "Model identifier from span payloads", "example": "openai/gpt-4o", "type": "string" }, "output": { "description": "Total output tokens for this model", "example": 500, "minimum": 0, "type": "integer" }, "output_cost": { "oneOf": [ { "description": "Estimated USD cost for output tokens", "example": 0.01, "type": "number" }, { "$ref": "#/components/schemas/Null" } ] }, "provider": { "oneOf": [ { "description": "Provider identifier from span payloads", "example": "openrouter", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "total_cost": { "oneOf": [ { "description": "Estimated total USD cost for this model", "example": 0.0125, "type": "number" }, { "$ref": "#/components/schemas/Null" } ] } }, "required": [ "cache_read", "cache_read_cost", "context_limit", "input", "input_cost", "model_name", "output", "output_cost", "provider", "total_cost" ], "title": "AgentInstance_CostBreakdown_Group", "type": "object" }, "AgentInstance_Details": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "agent_deployment_id": { "$ref": "#/components/schemas/AgentDeployment_Id" }, "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "agent_runtime_engine_id": { "description": "The engine running this instance, present only when a hosted instance has an engine", "oneOf": [ { "$ref": "#/components/schemas/AgentRuntimeEngine_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "agent_version_id": { "$ref": "#/components/schemas/AgentVersion_Id" }, "cost_breakdown": { "description": "LLM token usage and estimated USD costs. Null when the request omits `include_costs`, when costs do not apply, or when there is no token usage.", "oneOf": [ { "$ref": "#/components/schemas/AgentInstance_CostBreakdown" }, { "$ref": "#/components/schemas/Null" } ] }, "environment_id": { "$ref": "#/components/schemas/Environment_Id" }, "execution_mode": { "description": "Whether Prefactor executes this instance (hosted) or an external agent reports telemetry (remote)", "enum": [ "hosted", "remote" ], "example": "hosted", "type": "string" }, "external_identifier": { "oneOf": [ { "description": "External identifier for this agent instance in an external system (unique per agent)", "example": "run-abc123", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "finished_at": { "oneOf": [ { "description": "When the agent instance finished (null if still in progress)", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "id": { "$ref": "#/components/schemas/AgentInstance_Id" }, "inserted_at": { "description": "When the agent instance was created", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "last_activity_span_at": { "description": "When this agent instance last had an activity span, quantised to the nearest 30 seconds, or null if none yet", "oneOf": [ { "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "metadata": { "description": "Metadata recorded when the instance was registered, validated against the agent schema version's instance_metadata_schema when present. Values marked $sensitive were stored securely, separate from the rest of the payload, and are returned encoded with $sensitive markers.", "oneOf": [ { "additionalProperties": true, "type": "object" }, { "$ref": "#/components/schemas/Null" } ] }, "params_payload": { "description": "Input payload recorded when the instance was registered, validated against the agent schema version's instance_params_payload_schema when present. Values marked $sensitive were stored securely, separate from the rest of the payload, and are returned encoded with $sensitive markers.", "oneOf": [ { "additionalProperties": true, "type": "object" }, { "$ref": "#/components/schemas/Null" } ] }, "purpose": { "description": "Why this instance ran: 'live' for an actual agent run, 'smoke_test' for a pipeline check, or 'eval' for an evaluation run", "enum": [ "live", "smoke_test", "eval" ], "example": "live", "type": "string" }, "quality_payloads": { "additionalProperties": { "additionalProperties": true, "type": "object" }, "description": "Map of quality schema name to evaluation payload for this instance", "type": "object" }, "quality_summaries": { "additionalProperties": { "description": "Human-readable quality summary rendered from the quality schema template using the matching quality payload", "type": "string" }, "description": "Map of quality schema name to rendered summary (only names whose template renders)", "type": "object" }, "raised_alert_count": { "description": "Number of raised alerts for this instance. Null when the request omits `include_alert_count`.", "oneOf": [ { "minimum": 0, "type": "integer" }, { "$ref": "#/components/schemas/Null" } ] }, "result_payload": { "description": "Result payload recorded when the instance finished as complete or failed, validated against the agent schema version's instance_result_payload_schema when present. Null when the instance has not finished or finished as cancelled or terminated. Values marked $sensitive were stored securely, separate from the rest of the payload, and are returned encoded with $sensitive markers.", "oneOf": [ { "additionalProperties": true, "type": "object" }, { "$ref": "#/components/schemas/Null" } ] }, "risk_score": { "description": "Computed risk score for this instance. Null when the request omits `include_risk_score`, when the agent has no risk profile, or when scoring inputs are unavailable.", "oneOf": [ { "$ref": "#/components/schemas/AgentInstance_RiskScore" }, { "$ref": "#/components/schemas/Null" } ] }, "span_counts": { "$ref": "#/components/schemas/AgentSpan_SpanCounts" }, "span_schema_counts": { "oneOf": [ { "$ref": "#/components/schemas/AgentSpan_SpanSchemaCounts" }, { "$ref": "#/components/schemas/Null" } ] }, "started_at": { "oneOf": [ { "description": "When the agent instance started (null if not started yet)", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "status": { "description": "Status of the agent instance: 'pending' (not started yet), 'active' (started but not finished), 'complete' (finished successfully), 'failed' (ended with failure), 'cancelled' (never started, cancelled), or 'terminated' (externally terminated)", "enum": [ "pending", "active", "complete", "failed", "cancelled", "terminated" ], "example": "active", "type": "string" }, "termination_reason": { "oneOf": [ { "description": "Reason for termination (only present when status is 'terminated')", "example": "User requested termination", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "type": { "description": "Type of resource (always 'agent_instance')", "enum": [ "agent_instance" ], "example": "agent_instance", "type": "string" }, "updated_at": { "description": "When the agent instance was last updated", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" } }, "required": [ "account_id", "agent_deployment_id", "agent_id", "agent_version_id", "cost_breakdown", "environment_id", "execution_mode", "external_identifier", "finished_at", "id", "inserted_at", "last_activity_span_at", "metadata", "params_payload", "purpose", "quality_payloads", "quality_summaries", "raised_alert_count", "result_payload", "risk_score", "span_counts", "span_schema_counts", "started_at", "status", "termination_reason", "type", "updated_at" ], "title": "AgentInstance_Details", "type": "object" }, "AgentInstance_Id": { "description": "A valid agent instance ID", "example": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "title": "AgentInstance_Id", "type": "string" }, "AgentInstance_RiskScore": { "properties": { "all_data_categories": { "description": "Unique included data categories across params and results of span types that ran, in canonical order", "items": { "description": "Included data category from an observed span type", "enum": [ "personal_identifiers", "contact_information", "financial_information", "health_and_medical", "criminal_justice", "authentication_and_secrets", "organisational_confidential", "minors_data", "location_and_tracking", "behavioural_and_inferred", "gdpr_racial_or_ethnic_origin", "gdpr_political_opinions", "gdpr_religious_or_philosophical_beliefs", "gdpr_trade_union_membership", "gdpr_genetic_data", "gdpr_biometric_for_identification", "gdpr_sex_life_or_sexual_orientation" ], "example": "personal_identifiers", "type": "string" }, "type": "array" }, "allowed_actions": { "description": "Actions allowed by at least one span type that ran in this instance, in canonical order", "items": { "description": "Action allowed by at least one observed span type", "enum": [ "create_data", "read_data", "update_data", "destroy_data", "financial_transactions", "external_communication" ], "example": "create_data", "type": "string" }, "type": "array" }, "any_assessable": { "description": "Whether the instance has at least one span type with scoreable data_risk", "type": "boolean" }, "critical_threshold": { "description": "Critical threshold from the agent's risk profile ruleset", "example": 100.0, "type": "number" }, "peak_classification": { "oneOf": [ { "description": "Peak observed data risk classification across all spans in this instance. null if no spans have executed.", "enum": [ "unknown", "public", "internal", "confidential", "restricted", "secret" ], "example": "confidential", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "per_type": { "description": "Per-schema-type score breakdown", "items": { "$ref": "#/components/schemas/AgentInstance_RiskScore_PerType" }, "type": "array" }, "risk_level": { "oneOf": [ { "description": "Overall risk level bucket for this instance, or null when not assessable", "enum": [ "low", "medium", "high", "critical" ], "example": "low", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "total_score": { "description": "Total risk score across all span types for this instance", "example": 90.0, "type": "number" } }, "required": [ "all_data_categories", "allowed_actions", "any_assessable", "critical_threshold", "peak_classification", "per_type", "risk_level", "total_score" ], "title": "AgentInstance_RiskScore", "type": "object" }, "AgentInstance_RiskScore_PerType": { "properties": { "count": { "description": "Number of span invocations for this schema type", "example": 3, "minimum": 0, "type": "integer" }, "risk_level": { "description": "Risk level bucket for this schema type's per-invocation score", "enum": [ "low", "medium", "high", "critical" ], "example": "low", "type": "string" }, "schema_name": { "description": "Span type schema name", "example": "process_payment", "type": "string" }, "total_contribution": { "description": "type_score multiplied by count", "example": 90.0, "type": "number" }, "type_score": { "description": "Risk score for a single invocation of this schema type", "example": 30.0, "type": "number" } }, "required": [ "count", "risk_level", "schema_name", "total_contribution", "type_score" ], "title": "AgentInstance_RiskScore_PerType", "type": "object" }, "AgentInstance_Summary": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "agent_version_id": { "$ref": "#/components/schemas/AgentVersion_Id" }, "environment_id": { "$ref": "#/components/schemas/Environment_Id" }, "execution_mode": { "description": "Whether Prefactor executes this instance (hosted) or an external agent reports telemetry (remote)", "enum": [ "hosted", "remote" ], "example": "hosted", "type": "string" }, "external_identifier": { "oneOf": [ { "description": "External identifier for this agent instance in an external system (unique per agent)", "example": "run-abc123", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "finished_at": { "oneOf": [ { "description": "When the agent instance finished (null if still in progress)", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "id": { "$ref": "#/components/schemas/AgentInstance_Id" }, "inserted_at": { "description": "When the agent instance was created", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "last_activity_span_at": { "description": "When this agent instance last had an activity span, quantised to the nearest 30 seconds, or null if none yet", "oneOf": [ { "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "purpose": { "description": "Why this instance ran: 'live' for an actual agent run, 'smoke_test' for a pipeline check, or 'eval' for an evaluation run", "enum": [ "live", "smoke_test", "eval" ], "example": "live", "type": "string" }, "raised_alert_count": { "description": "Number of raised alerts for this instance. Null when the request omits `include_alert_count`.", "oneOf": [ { "minimum": 0, "type": "integer" }, { "$ref": "#/components/schemas/Null" } ] }, "risk_score": { "description": "Computed risk score for this instance. Null when the request omits `include_risk_score`, when the agent has no risk profile, or when scoring inputs are unavailable.", "oneOf": [ { "$ref": "#/components/schemas/AgentInstance_RiskScore" }, { "$ref": "#/components/schemas/Null" } ] }, "started_at": { "oneOf": [ { "description": "When the agent instance started (null if not started yet)", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "status": { "description": "Status of the agent instance: 'pending' (not started yet), 'active' (started but not finished), 'complete' (finished successfully), 'failed' (ended with failure), 'cancelled' (never started, cancelled), or 'terminated' (externally terminated)", "enum": [ "pending", "active", "complete", "failed", "cancelled", "terminated" ], "example": "active", "type": "string" }, "termination_reason": { "oneOf": [ { "description": "Reason for termination (only present when status is 'terminated')", "example": "User requested termination", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "type": { "description": "Type of resource (always 'agent_instance')", "enum": [ "agent_instance" ], "example": "agent_instance", "type": "string" }, "updated_at": { "description": "When the agent instance was last updated", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" } }, "required": [ "account_id", "agent_id", "agent_version_id", "environment_id", "execution_mode", "external_identifier", "finished_at", "id", "inserted_at", "last_activity_span_at", "purpose", "raised_alert_count", "risk_score", "started_at", "status", "termination_reason", "type", "updated_at" ], "title": "AgentInstance_Summary", "type": "object" }, "AgentRuntimeEngine_Id": { "description": "A valid agent runtime engine ID", "example": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "title": "AgentRuntimeEngine_Id", "type": "string" }, "AgentSchemaVersionForRegister": { "properties": { "alert_schemas": { "oneOf": [ { "description": "Array of alert schemas with name, schema and optional title, description, template and data_risk.", "items": { "$ref": "#/components/schemas/SchemaDetails_ForCreate" }, "type": "array" }, { "$ref": "#/components/schemas/Null" } ] }, "external_identifier": { "type": "string" }, "instance_metadata_schema": { "description": "Single JSON schema validating each agent instance's metadata registered against this schema version. Omit or null for no metadata schema.", "oneOf": [ { "$ref": "#/components/schemas/SingleSchemaDetails_ForCreate" }, { "$ref": "#/components/schemas/Null" } ] }, "instance_params_payload_schema": { "description": "Single JSON schema validating each agent instance's params_payload registered against this schema version. Omit or null for no params payload schema.", "oneOf": [ { "$ref": "#/components/schemas/SingleSchemaDetails_ForCreate" }, { "$ref": "#/components/schemas/Null" } ] }, "instance_result_payload_schema": { "description": "Single JSON schema validating each agent instance's result_payload recorded on finish against this schema version. Omit or null for no result payload schema.", "oneOf": [ { "$ref": "#/components/schemas/SingleSchemaDetails_ForCreate" }, { "$ref": "#/components/schemas/Null" } ] }, "quality_schemas": { "oneOf": [ { "description": "Array of quality schemas with name, schema and optional title, description, template and data_risk.", "items": { "$ref": "#/components/schemas/SchemaDetails_ForCreate" }, "type": "array" }, { "$ref": "#/components/schemas/Null" } ] }, "span_result_schemas": { "deprecated": true, "description": "Deprecated. Use span_type_schemas instead. Optional map of span type names to their result payload JSON schemas. Only used when span_schemas is provided; keys may be a subset of span_schemas; missing keys default to a schema requiring empty object.", "oneOf": [ { "additionalProperties": { "additionalProperties": true, "type": "object" }, "type": "object" }, { "$ref": "#/components/schemas/Null" } ] }, "span_schemas": { "deprecated": true, "description": "Deprecated. Use span_type_schemas instead. Map of span type names to their JSON schemas.", "oneOf": [ { "additionalProperties": { "additionalProperties": true, "type": "object" }, "type": "object" }, { "$ref": "#/components/schemas/Null" } ] }, "span_type_schemas": { "oneOf": [ { "description": "Array of span types with name, params_schema and optional result_schema.", "items": { "$ref": "#/components/schemas/SpanTypeSchemaDetails_ForCreate" }, "type": "array" }, { "$ref": "#/components/schemas/Null" } ] } }, "title": "AgentSchemaVersionForRegister", "type": "object" }, "AgentSchemaVersion_Details": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "alert_schemas": { "additionalProperties": { "$ref": "#/components/schemas/SchemaDetails" }, "description": "Map of alert schema names to their schemas and optional title, description, template and data_risk", "type": "object" }, "current_agent_deployment_refs": { "description": "Agent deployments whose current version uses this schema version (empty if none).", "items": { "$ref": "#/components/schemas/AgentDeployment_Id" }, "type": "array" }, "external_identifier": { "description": "External identifier for the agent schema version", "example": "v0", "type": "string" }, "external_identifier_repeats": { "description": "Count of rows sharing this external identifier (helps distinguish duplicates).", "minimum": 0, "type": "integer" }, "id": { "$ref": "#/components/schemas/AgentSchemaVersion_Id" }, "inserted_at": { "description": "When the agent schema version was created", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "instance_metadata_schema": { "description": "Single JSON schema validating each agent instance's metadata registered against this schema version. Null when no metadata schema is set.", "oneOf": [ { "$ref": "#/components/schemas/SingleSchemaDetails" }, { "$ref": "#/components/schemas/Null" } ] }, "instance_params_payload_schema": { "description": "Single JSON schema validating each agent instance's params_payload registered against this schema version. Null when no params payload schema is set.", "oneOf": [ { "$ref": "#/components/schemas/SingleSchemaDetails" }, { "$ref": "#/components/schemas/Null" } ] }, "instance_result_payload_schema": { "description": "Single JSON schema validating each agent instance's result_payload recorded on finish against this schema version. Null when no result payload schema is set.", "oneOf": [ { "$ref": "#/components/schemas/SingleSchemaDetails" }, { "$ref": "#/components/schemas/Null" } ] }, "quality_schemas": { "additionalProperties": { "$ref": "#/components/schemas/SchemaDetails" }, "description": "Map of quality schema names to their schemas and optional title, description, template and data_risk", "type": "object" }, "span_type_schemas": { "additionalProperties": { "$ref": "#/components/schemas/SpanTypeSchemaDetails" }, "description": "Map of span type names to their params and result JSON schemas", "example": { "llm": { "name": "llm", "params_schema": { "properties": { "max_tokens": { "type": "integer" }, "model": { "type": "string" }, "temperature": { "type": "number" } }, "type": "object" }, "result_schema": { "properties": { "tokens": { "type": "integer" } }, "type": "object" } }, "tool": { "name": "tool", "params_schema": { "properties": { "input": { "type": "object" }, "name": { "type": "string" } }, "type": "object" }, "result_schema": { "additionalProperties": false, "type": "object" } } }, "type": "object" }, "type": { "description": "Type of resource (always 'agent_schema_version')", "enum": [ "agent_schema_version" ], "example": "agent_schema_version", "type": "string" }, "updated_at": { "description": "When the agent schema version was last updated", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" } }, "required": [ "account_id", "agent_id", "alert_schemas", "current_agent_deployment_refs", "external_identifier", "external_identifier_repeats", "id", "inserted_at", "instance_metadata_schema", "instance_params_payload_schema", "instance_result_payload_schema", "quality_schemas", "span_type_schemas", "type", "updated_at" ], "title": "AgentSchemaVersion_Details", "type": "object" }, "AgentSchemaVersion_DetailsForCreate": { "properties": { "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "alert_schemas": { "oneOf": [ { "description": "Array of alert schemas with name, schema and optional title, description, template and data_risk.", "items": { "$ref": "#/components/schemas/SchemaDetails_ForCreate" }, "type": "array" }, { "$ref": "#/components/schemas/Null" } ] }, "external_identifier": { "type": "string" }, "id": { "description": "Optional ID for the agent schema version. Used only when creating a new row; ignored if a matching schema version already exists. If not provided, a new ID will be generated. The ID must be a valid PFID with a partition matching the account. Its embedded timestamp must not be more than 7 days in the past.", "oneOf": [ { "$ref": "#/components/schemas/AgentSchemaVersion_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "instance_metadata_schema": { "description": "Single JSON schema validating each agent instance's metadata registered against this schema version. Omit or null for no metadata schema.", "oneOf": [ { "$ref": "#/components/schemas/SingleSchemaDetails_ForCreate" }, { "$ref": "#/components/schemas/Null" } ] }, "instance_params_payload_schema": { "description": "Single JSON schema validating each agent instance's params_payload registered against this schema version. Omit or null for no params payload schema.", "oneOf": [ { "$ref": "#/components/schemas/SingleSchemaDetails_ForCreate" }, { "$ref": "#/components/schemas/Null" } ] }, "instance_result_payload_schema": { "description": "Single JSON schema validating each agent instance's result_payload recorded on finish against this schema version. Omit or null for no result payload schema.", "oneOf": [ { "$ref": "#/components/schemas/SingleSchemaDetails_ForCreate" }, { "$ref": "#/components/schemas/Null" } ] }, "quality_schemas": { "oneOf": [ { "description": "Array of quality schemas with name, schema and optional title, description, template and data_risk.", "items": { "$ref": "#/components/schemas/SchemaDetails_ForCreate" }, "type": "array" }, { "$ref": "#/components/schemas/Null" } ] }, "span_result_schemas": { "deprecated": true, "description": "Deprecated. Use span_type_schemas instead. Optional map of span type names to their result payload JSON schemas. Keys may be a subset of span_schemas; missing keys default to a schema requiring empty object. Only used when span_schemas is provided.", "oneOf": [ { "additionalProperties": { "additionalProperties": true, "type": "object" }, "type": "object" }, { "$ref": "#/components/schemas/Null" } ] }, "span_schemas": { "deprecated": true, "description": "Deprecated. Use span_type_schemas instead. Map of span type names to their JSON schemas.", "oneOf": [ { "additionalProperties": { "additionalProperties": true, "type": "object" }, "type": "object" }, { "$ref": "#/components/schemas/Null" } ] }, "span_type_schemas": { "oneOf": [ { "description": "Array of span types with name, params_schema and optional result_schema.", "items": { "$ref": "#/components/schemas/SpanTypeSchemaDetails_ForCreate" }, "type": "array" }, { "$ref": "#/components/schemas/Null" } ] } }, "title": "AgentSchemaVersion_DetailsForCreate", "type": "object" }, "AgentSchemaVersion_Id": { "description": "A valid agent schema version ID", "example": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "title": "AgentSchemaVersion_Id", "type": "string" }, "AgentSchemaVersion_Summary": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "current_agent_deployment_refs": { "description": "Agent deployments whose current version uses this schema version (empty if none).", "items": { "$ref": "#/components/schemas/AgentDeployment_Id" }, "type": "array" }, "external_identifier": { "description": "External identifier for the agent schema version", "example": "v0", "type": "string" }, "external_identifier_repeats": { "description": "Count of rows sharing this external identifier (helps distinguish duplicates).", "minimum": 0, "type": "integer" }, "id": { "$ref": "#/components/schemas/AgentSchemaVersion_Id" }, "inserted_at": { "description": "When the agent schema version was created", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "span_schemas_count": { "description": "Number of span schemas in this schema version", "example": 3, "minimum": 0, "type": "integer" }, "type": { "description": "Type of resource (always 'agent_schema_version')", "enum": [ "agent_schema_version" ], "example": "agent_schema_version", "type": "string" }, "updated_at": { "description": "When the agent schema version was last updated", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" } }, "required": [ "account_id", "agent_id", "current_agent_deployment_refs", "external_identifier", "external_identifier_repeats", "id", "inserted_at", "span_schemas_count", "type", "updated_at" ], "title": "AgentSchemaVersion_Summary", "type": "object" }, "AgentSpan_Control": { "additionalProperties": false, "properties": { "reason": { "type": "string" }, "terminate": { "type": "boolean" } }, "required": [ "reason", "terminate" ], "title": "AgentSpan_Control", "type": "object" }, "AgentSpan_Details": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "agent_instance_id": { "$ref": "#/components/schemas/AgentInstance_Id" }, "data_risk": { "description": "Data risk for this span from its schema. Only populated for activity-purpose spans.", "oneOf": [ { "$ref": "#/components/schemas/DataRisk" }, { "$ref": "#/components/schemas/Null" } ] }, "finished_at": { "oneOf": [ { "description": "When the span finished (null if still in progress)", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "id": { "$ref": "#/components/schemas/AgentSpan_Id" }, "parent_span_id": { "description": "ID of the parent span (null if this is a root span)", "oneOf": [ { "$ref": "#/components/schemas/AgentSpan_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "payload": { "additionalProperties": true, "description": "Span payload data (arbitrary JSON object)", "type": "object" }, "payload_byte_size_estimate": { "description": "Approximate JSON-encoded byte size of the span's stored payload columns. This is an estimate, not an exact on-disk size.", "minimum": 0, "type": "integer" }, "purpose": { "description": "Purpose of the span: 'activity' (normal agent activity), 'quality' (system-written span recording an agent instance quality payload update), or 'alert' (system-written span recording an alert lifecycle event). Quality-purpose and alert-purpose spans are excluded from standard span metrics.", "enum": [ "activity", "quality", "alert" ], "example": "activity", "type": "string" }, "result_payload": { "oneOf": [ { "additionalProperties": true, "description": "Result payload (arbitrary JSON), only present when span is finished", "type": "object" }, { "$ref": "#/components/schemas/Null" } ] }, "schema_name": { "description": "Name of the schema for this span", "example": "llm", "type": "string" }, "schema_title": { "description": "Human-readable title for the schema (from JSON schema, defaults to schema_name)", "example": "LLM", "type": "string" }, "sensitive_encoding": { "description": "When true, both payload and result_payload should be interpreted as containing sensitive markers as per the specification", "type": "boolean" }, "started_at": { "description": "When the span started", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "status": { "description": "Status of the span: 'active' (started but not finished), 'complete' (finished successfully), 'failed' (ended with failure), or 'cancelled' (started but cancelled before completion)", "enum": [ "active", "complete", "failed", "cancelled" ], "example": "active", "type": "string" }, "summary": { "oneOf": [ { "description": "Human-readable summary rendered from the schema template using payload and result_payload (null when template is missing). When the request sets `redacted` to true, sensitive values in the summary are replaced with redaction labels.", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "type": { "description": "Type of resource (always 'agent_span')", "enum": [ "agent_span" ], "example": "agent_span", "type": "string" } }, "required": [ "account_id", "agent_id", "agent_instance_id", "data_risk", "finished_at", "id", "parent_span_id", "payload", "payload_byte_size_estimate", "purpose", "result_payload", "schema_name", "schema_title", "sensitive_encoding", "started_at", "status", "summary", "type" ], "title": "AgentSpan_Details", "type": "object" }, "AgentSpan_DetailsForCreate": { "properties": { "agent_instance_id": { "$ref": "#/components/schemas/AgentInstance_Id" }, "finished_at": { "oneOf": [ { "description": "When the span finished (ISO 8601 format). Omit or null for active spans. For complete, failed, or cancelled, omit to use the current time. When provided, must not be more than 7 days in the past.", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "id": { "description": "Optional ID for the span. If not provided, a new ID will be generated. The ID must be a valid PFID with a partition matching the account. Its embedded timestamp must not be more than 7 days in the past.", "oneOf": [ { "$ref": "#/components/schemas/AgentSpan_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "parent_span_id": { "description": "ID of the parent span (null if this is a root span)", "oneOf": [ { "$ref": "#/components/schemas/AgentSpan_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "payload": { "additionalProperties": true, "description": "Span payload data (arbitrary JSON object)", "type": "object" }, "result_payload": { "oneOf": [ { "additionalProperties": true, "description": "Result payload (arbitrary JSON). Only valid when status is complete, failed, or cancelled.", "type": "object" }, { "$ref": "#/components/schemas/Null" } ] }, "schema_name": { "description": "Name of the schema for this span", "example": "llm", "type": "string" }, "sensitive_encoding": { "default": false, "description": "When true, payload and result_payload are parsed as sensitive-encoded JSON; values marked with $sensitive are extracted and stored securely, separate from the rest of the payload. Defaults to false.", "type": "boolean" }, "started_at": { "oneOf": [ { "description": "When the span started (ISO 8601 format). If not provided, current time is used. Must not be more than 7 days in the past.", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "status": { "description": "Status of the span (required)", "enum": [ "active", "complete", "failed", "cancelled" ], "example": "active", "type": "string" } }, "required": [ "agent_instance_id", "schema_name", "status", "payload" ], "title": "AgentSpan_DetailsForCreate", "type": "object" }, "AgentSpan_Id": { "description": "A valid agent span ID", "example": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "title": "AgentSpan_Id", "type": "string" }, "AgentSpan_SpanCounts": { "properties": { "active": { "description": "Number of spans with status active (running)", "example": 2, "minimum": 0, "type": "integer" }, "cancelled": { "description": "Number of spans with status cancelled", "example": 0, "minimum": 0, "type": "integer" }, "complete": { "description": "Number of spans with status complete", "example": 5, "minimum": 0, "type": "integer" }, "failed": { "description": "Number of spans with status failed", "example": 0, "minimum": 0, "type": "integer" }, "finished": { "description": "Number of spans in a finished state (complete + failed + cancelled)", "example": 5, "minimum": 0, "type": "integer" }, "pending": { "deprecated": true, "description": "Deprecated and always zero; span pending status no longer exists", "example": 0, "minimum": 0, "type": "integer" }, "total": { "description": "Total number of agent spans", "example": 10, "minimum": 0, "type": "integer" } }, "required": [ "active", "cancelled", "complete", "failed", "finished", "pending", "total" ], "title": "AgentSpan_SpanCounts", "type": "object" }, "AgentSpan_SpanSchemaCounts": { "properties": { "by_name": { "additionalProperties": { "minimum": 0, "type": "integer" }, "description": "Invocation count keyed by span schema name", "type": "object" } }, "required": [ "by_name" ], "title": "AgentSpan_SpanSchemaCounts", "type": "object" }, "AgentSpan_Summary": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "agent_instance_id": { "$ref": "#/components/schemas/AgentInstance_Id" }, "data_risk": { "description": "Data risk for this span from its schema. Only populated for activity-purpose spans.", "oneOf": [ { "$ref": "#/components/schemas/DataRisk" }, { "$ref": "#/components/schemas/Null" } ] }, "finished_at": { "oneOf": [ { "description": "When the span finished (null if still in progress)", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "id": { "$ref": "#/components/schemas/AgentSpan_Id" }, "parent_span_id": { "description": "ID of the parent span (null if this is a root span)", "oneOf": [ { "$ref": "#/components/schemas/AgentSpan_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "payload": { "additionalProperties": true, "description": "Span payload data (arbitrary JSON object)", "type": "object" }, "payload_byte_size_estimate": { "description": "Approximate JSON-encoded byte size of the span's stored payload columns. This is an estimate, not an exact on-disk size.", "minimum": 0, "type": "integer" }, "purpose": { "description": "Purpose of the span: 'activity' (normal agent activity), 'quality' (system-written span recording an agent instance quality payload update), or 'alert' (system-written span recording an alert lifecycle event). Quality-purpose and alert-purpose spans are excluded from standard span metrics.", "enum": [ "activity", "quality", "alert" ], "example": "activity", "type": "string" }, "result_payload": { "oneOf": [ { "additionalProperties": true, "description": "Result payload (arbitrary JSON), only present when span is finished", "type": "object" }, { "$ref": "#/components/schemas/Null" } ] }, "risk_level": { "oneOf": [ { "description": "Risk level for this span based on its schema's data_risk and the agent's risk profile. Only populated for activity-purpose spans when the request includes `include_risk_level`, the agent has a risk profile, and the span's schema has scoreable data_risk.", "enum": [ "low", "medium", "high", "critical" ], "example": "low", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "risk_score": { "oneOf": [ { "description": "Numeric risk score for this span based on its schema's data_risk and the agent's risk profile. Only populated for activity-purpose spans, together with `risk_level`, when the request includes `include_risk_level`.", "example": 40.0, "type": "number" }, { "$ref": "#/components/schemas/Null" } ] }, "schema_name": { "description": "Name of the schema for this span", "example": "llm", "type": "string" }, "schema_title": { "description": "Human-readable title for the schema (from JSON schema, defaults to schema_name)", "example": "LLM", "type": "string" }, "sensitive_encoding": { "description": "When true, both payload and result_payload should be interpreted as containing sensitive markers as per the specification", "type": "boolean" }, "started_at": { "description": "When the span started", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "status": { "description": "Status of the span: 'active' (started but not finished), 'complete' (finished successfully), 'failed' (ended with failure), or 'cancelled' (started but cancelled before completion)", "enum": [ "active", "complete", "failed", "cancelled" ], "example": "active", "type": "string" }, "summary": { "oneOf": [ { "description": "Human-readable summary rendered from the schema template using payload and result_payload (null when template is missing). When the request sets `redacted` to true, sensitive values in the summary are replaced with redaction labels.", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "type": { "description": "Type of resource (always 'agent_span')", "enum": [ "agent_span" ], "example": "agent_span", "type": "string" } }, "required": [ "account_id", "agent_id", "agent_instance_id", "data_risk", "finished_at", "id", "parent_span_id", "payload", "payload_byte_size_estimate", "purpose", "result_payload", "risk_level", "risk_score", "schema_name", "schema_title", "sensitive_encoding", "started_at", "status", "summary", "type" ], "title": "AgentSpan_Summary", "type": "object" }, "AgentVersionForRegister": { "properties": { "description": { "oneOf": [ { "deprecated": true, "description": "Deprecated. Accepted for backward compatibility; ignored. Use agents/update to set the agent description.", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "external_identifier": { "type": "string" }, "name": { "oneOf": [ { "deprecated": true, "description": "Deprecated. Accepted for backward compatibility; ignored. Use agents/update to set the agent name.", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "runtime_environment": { "description": "Runtime environment metadata (SDK version, harness version, etc.)", "oneOf": [ { "$ref": "#/components/schemas/AgentVersion_RuntimeEnvironment" }, { "$ref": "#/components/schemas/Null" } ] } }, "title": "AgentVersionForRegister", "type": "object" }, "AgentVersion_Details": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "agent_schema_version_id": { "$ref": "#/components/schemas/AgentSchemaVersion_Id" }, "current_agent_deployment_refs": { "description": "Agent deployments that pin this version as their current version (empty if none).", "items": { "$ref": "#/components/schemas/AgentDeployment_Id" }, "type": "array" }, "execution_mode": { "description": "Whether Prefactor executes this version (hosted) or an external agent reports telemetry (remote)", "enum": [ "hosted", "remote" ], "example": "hosted", "type": "string" }, "external_identifier": { "description": "External identifier for the agent version", "example": "v1.0.0", "type": "string" }, "external_identifier_repeats": { "description": "Count of rows sharing this external identifier (helps distinguish duplicates).", "minimum": 0, "type": "integer" }, "hosted_llm_provider_model_id": { "description": "LLM provider model used when execution_mode is hosted", "oneOf": [ { "$ref": "#/components/schemas/LlmProviderModel_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "hosted_max_tokens": { "description": "Maximum tokens used when execution_mode is hosted", "example": 1024, "minimum": 1, "type": "integer" }, "hosted_mode": { "description": "Hosted run mode: one model turn, or a conversation", "enum": [ "single_turn", "conversation" ], "example": "conversation", "type": "string" }, "hosted_system_prompt": { "description": "System prompt used when execution_mode is hosted", "example": "You are a helpful assistant.", "type": "string" }, "id": { "$ref": "#/components/schemas/AgentVersion_Id" }, "inserted_at": { "description": "When the agent version was created", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "runtime_environment": { "description": "Runtime environment metadata (Prefactor SDK packages, agent SDK packages, language runtime, OS, etc.)", "oneOf": [ { "$ref": "#/components/schemas/AgentVersion_RuntimeEnvironment" }, { "$ref": "#/components/schemas/Null" } ] }, "type": { "description": "Type of resource (always 'agent_version')", "enum": [ "agent_version" ], "example": "agent_version", "type": "string" }, "updated_at": { "description": "When the agent version was last updated", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" } }, "required": [ "account_id", "agent_id", "agent_schema_version_id", "current_agent_deployment_refs", "execution_mode", "external_identifier", "external_identifier_repeats", "id", "inserted_at", "runtime_environment", "type", "updated_at" ], "title": "AgentVersion_Details", "type": "object" }, "AgentVersion_DetailsForCreate": { "properties": { "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "agent_schema_version_id": { "description": "A valid agent schema version ID, required when execution_mode is remote (optional; omit when execution_mode is hosted to find or create the canonical AgentRuntime span schema)", "oneOf": [ { "$ref": "#/components/schemas/AgentSchemaVersion_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "description": { "oneOf": [ { "deprecated": true, "description": "Deprecated. Accepted for backward compatibility; ignored. Use agents/update to set the agent description.", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "execution_mode": { "description": "Whether Prefactor executes this version (hosted) or an external agent reports telemetry (remote) (optional; defaults to remote if omitted)", "oneOf": [ { "enum": [ "hosted", "remote" ], "example": "hosted", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "external_identifier": { "type": "string" }, "hosted_llm_provider_model_id": { "description": "LLM provider model used when execution_mode is hosted (optional; omit with the other hosted fields for a remote version)", "oneOf": [ { "$ref": "#/components/schemas/LlmProviderModel_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "hosted_max_tokens": { "description": "Maximum tokens used when execution_mode is hosted (optional; omit with the other hosted fields for a remote version)", "oneOf": [ { "example": 1024, "minimum": 1, "type": "integer" }, { "$ref": "#/components/schemas/Null" } ] }, "hosted_mode": { "description": "Hosted run mode: one model turn, or a conversation (optional; omit with the other hosted fields for a remote version)", "oneOf": [ { "enum": [ "single_turn", "conversation" ], "example": "conversation", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "hosted_system_prompt": { "description": "System prompt used when execution_mode is hosted (optional; omit with the other hosted fields for a remote version)", "oneOf": [ { "example": "You are a helpful assistant.", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "id": { "description": "Optional ID for the agent version. Used only when creating a new row; ignored if a matching version already exists. If not provided, a new ID will be generated. The ID must be a valid PFID with a partition matching the account. Its embedded timestamp must not be more than 7 days in the past.", "oneOf": [ { "$ref": "#/components/schemas/AgentVersion_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "name": { "oneOf": [ { "deprecated": true, "description": "Deprecated. Accepted for backward compatibility; ignored. Use agents/update to set the agent name.", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "runtime_environment": { "description": "Runtime environment metadata (Prefactor SDK packages, agent SDK packages, language runtime, OS, etc.)", "oneOf": [ { "$ref": "#/components/schemas/AgentVersion_RuntimeEnvironment" }, { "$ref": "#/components/schemas/Null" } ] } }, "title": "AgentVersion_DetailsForCreate", "type": "object" }, "AgentVersion_Id": { "description": "A valid agent version ID", "example": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "title": "AgentVersion_Id", "type": "string" }, "AgentVersion_RuntimeEnvironment": { "properties": { "agent_sdk": { "description": "Agent framework/SDK packages (e.g. [\"langchain@4.0.0\"])", "oneOf": [ { "description": "List of package name and version strings (e.g. \"package@1.0.0\")", "items": { "type": "string" }, "type": "array" }, { "$ref": "#/components/schemas/Null" } ] }, "os": { "oneOf": [ { "description": "Operating system (e.g. \"linux\")", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "prefactor_sdk": { "description": "Prefactor SDK packages and versions (e.g. [\"prefactor-core@1.0.0\", \"prefactor-langchain@1.1.0\"])", "oneOf": [ { "description": "List of package name and version strings (e.g. \"package@1.0.0\")", "items": { "type": "string" }, "type": "array" }, { "$ref": "#/components/schemas/Null" } ] }, "runtime": { "oneOf": [ { "description": "Language runtime version (e.g. \"python@3.12\")", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] } }, "title": "AgentVersion_RuntimeEnvironment", "type": "object" }, "AgentVersion_Summary": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "agent_schema_version_id": { "$ref": "#/components/schemas/AgentSchemaVersion_Id" }, "current_agent_deployment_refs": { "description": "Agent deployments that pin this version as their current version (empty if none).", "items": { "$ref": "#/components/schemas/AgentDeployment_Id" }, "type": "array" }, "execution_mode": { "description": "Whether Prefactor executes this version (hosted) or an external agent reports telemetry (remote)", "enum": [ "hosted", "remote" ], "example": "hosted", "type": "string" }, "external_identifier": { "description": "External identifier for the agent version", "example": "v1.0.0", "type": "string" }, "external_identifier_repeats": { "description": "Count of rows sharing this external identifier (helps distinguish duplicates).", "minimum": 0, "type": "integer" }, "id": { "$ref": "#/components/schemas/AgentVersion_Id" }, "inserted_at": { "description": "When the agent version was created", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "observed_classification": { "oneOf": [ { "description": "Observed highest classification level from actual executed spans (null if no spans have executed).", "enum": [ "unknown", "public", "internal", "confidential", "restricted", "secret" ], "example": "internal", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "theoretical_classification": { "oneOf": [ { "description": "Theoretical highest classification level based on schema-defined scope and data categories (null if not assessed).", "enum": [ "unknown", "public", "internal", "confidential", "restricted", "secret" ], "example": "confidential", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "type": { "description": "Type of resource (always 'agent_version')", "enum": [ "agent_version" ], "example": "agent_version", "type": "string" }, "updated_at": { "description": "When the agent version was last updated", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" } }, "required": [ "account_id", "agent_id", "agent_schema_version_id", "current_agent_deployment_refs", "execution_mode", "external_identifier", "external_identifier_repeats", "id", "inserted_at", "type", "updated_at" ], "title": "AgentVersion_Summary", "type": "object" }, "Agent_AvailableActions": { "description": "Available actions for this agent based on its status and instance counts", "properties": { "delete": { "description": "Whether the agent can be deleted", "type": "boolean" }, "reinstate": { "description": "Whether the agent can be reinstated from retired", "type": "boolean" }, "retire": { "description": "Whether the agent can be retired", "type": "boolean" }, "update": { "description": "Whether the agent can be updated", "type": "boolean" } }, "required": [ "delete", "reinstate", "retire", "update" ], "title": "Agent_AvailableActions", "type": "object" }, "Agent_Details": { "properties": { "available_actions": { "description": "Available actions for this agent based on its status and instance counts", "properties": { "delete": { "description": "Whether the agent can be deleted", "type": "boolean" }, "reinstate": { "description": "Whether the agent can be reinstated from retired", "type": "boolean" }, "retire": { "description": "Whether the agent can be retired", "type": "boolean" }, "update": { "description": "Whether the agent can be updated", "type": "boolean" } }, "required": [ "delete", "reinstate", "retire", "update" ], "title": "Agent_AvailableActions", "type": "object" }, "description": { "oneOf": [ { "description": "Agent description", "example": "Agent description", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "external_identifier": { "oneOf": [ { "description": "External identifier for this agent in an external system (unique per account)", "example": "workflow-abc123", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "id": { "$ref": "#/components/schemas/Agent_Id" }, "inserted_at": { "description": "When the agent was created", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "instance_counts": { "properties": { "active": { "description": "Number of instances with status active (running)", "example": 2, "minimum": 0, "type": "integer" }, "cancelled": { "description": "Number of instances with status cancelled", "example": 0, "minimum": 0, "type": "integer" }, "complete": { "description": "Number of instances with status complete", "example": 5, "minimum": 0, "type": "integer" }, "failed": { "description": "Number of instances with status failed", "example": 0, "minimum": 0, "type": "integer" }, "finished": { "description": "Number of instances in a finished state (complete + failed + cancelled + terminated)", "example": 5, "minimum": 0, "type": "integer" }, "pending": { "description": "Number of instances with status pending", "example": 0, "minimum": 0, "type": "integer" }, "terminated": { "description": "Number of instances with status terminated", "example": 0, "minimum": 0, "type": "integer" }, "total": { "description": "Total number of agent instances", "example": 10, "minimum": 0, "type": "integer" } }, "required": [ "active", "cancelled", "complete", "failed", "finished", "pending", "terminated", "total" ], "title": "Agent_InstanceCounts", "type": "object" }, "last_activity_span_at": { "description": "When this agent last had an activity span, quantised to the nearest 30 seconds, or null if none yet", "oneOf": [ { "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "name": { "description": "Agent name", "example": "My Agent", "type": "string" }, "owner_person_id": { "description": "The owner of this agent (if any)", "oneOf": [ { "$ref": "#/components/schemas/Person_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "risk_profile_id": { "description": "The risk profile assigned to this agent (if any). Used to calculate risk scores.", "oneOf": [ { "$ref": "#/components/schemas/RiskProfile_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "status": { "description": "Agent status", "enum": [ "pending", "active", "dormant", "retired" ], "example": "pending", "type": "string" }, "team_id": { "description": "The team this agent belongs to (if any)", "oneOf": [ { "$ref": "#/components/schemas/Team_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "type": { "description": "Type of resource (always 'agent')", "enum": [ "agent" ], "example": "agent", "type": "string" }, "updated_at": { "description": "When the agent was last updated", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" } }, "required": [ "available_actions", "description", "external_identifier", "id", "inserted_at", "instance_counts", "last_activity_span_at", "name", "owner_person_id", "risk_profile_id", "status", "team_id", "type", "updated_at" ], "title": "Agent_Details", "type": "object" }, "Agent_DetailsForCreate": { "properties": { "description": { "description": "Optional agent description", "example": "Handles tier-1 support requests", "type": "string" }, "external_identifier": { "description": "Optional external identifier for this agent in an external system (unique per account)", "example": "workflow-abc123", "type": "string" }, "id": { "description": "Optional ID for the agent. If not provided, a new ID will be generated. The ID must be a valid PFID with a partition matching the account. Its embedded timestamp must not be more than 7 days in the past.", "oneOf": [ { "$ref": "#/components/schemas/Agent_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "name": { "description": "Agent name", "example": "Support bot", "type": "string" }, "owner_person_id": { "description": "The owner of this agent (optional)", "oneOf": [ { "$ref": "#/components/schemas/Person_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "risk_profile_id": { "description": "The risk profile assigned to this agent (optional). Used to calculate risk scores.", "oneOf": [ { "$ref": "#/components/schemas/RiskProfile_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "team_id": { "description": "The team this agent belongs to (optional)", "oneOf": [ { "$ref": "#/components/schemas/Team_Id" }, { "$ref": "#/components/schemas/Null" } ] } }, "title": "Agent_DetailsForCreate", "type": "object" }, "Agent_DetailsForUpdate": { "properties": { "description": { "type": "string" }, "name": { "type": "string" }, "owner_person_id": { "description": "The owner of this agent (omit to keep current; null to clear)", "oneOf": [ { "$ref": "#/components/schemas/Person_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "risk_profile_id": { "description": "The risk profile assigned to this agent (omit to keep current; null to clear)", "oneOf": [ { "$ref": "#/components/schemas/RiskProfile_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "team_id": { "description": "The team this agent belongs to (omit to keep current; null to clear)", "oneOf": [ { "$ref": "#/components/schemas/Team_Id" }, { "$ref": "#/components/schemas/Null" } ] } }, "title": "Agent_DetailsForUpdate", "type": "object" }, "Agent_GetDetailsOutput": { "properties": { "details": { "$ref": "#/components/schemas/Agent_Details" }, "risk_rollup": { "$ref": "#/components/schemas/Agent_RiskRollup" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "title": "Agent_GetDetailsOutput", "type": "object" }, "Agent_Id": { "description": "A valid agent ID", "example": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "title": "Agent_Id", "type": "string" }, "Agent_InstanceCounts": { "properties": { "active": { "description": "Number of instances with status active (running)", "example": 2, "minimum": 0, "type": "integer" }, "cancelled": { "description": "Number of instances with status cancelled", "example": 0, "minimum": 0, "type": "integer" }, "complete": { "description": "Number of instances with status complete", "example": 5, "minimum": 0, "type": "integer" }, "failed": { "description": "Number of instances with status failed", "example": 0, "minimum": 0, "type": "integer" }, "finished": { "description": "Number of instances in a finished state (complete + failed + cancelled + terminated)", "example": 5, "minimum": 0, "type": "integer" }, "pending": { "description": "Number of instances with status pending", "example": 0, "minimum": 0, "type": "integer" }, "terminated": { "description": "Number of instances with status terminated", "example": 0, "minimum": 0, "type": "integer" }, "total": { "description": "Total number of agent instances", "example": 10, "minimum": 0, "type": "integer" } }, "required": [ "active", "cancelled", "complete", "failed", "finished", "pending", "terminated", "total" ], "title": "Agent_InstanceCounts", "type": "object" }, "Agent_RiskRollup": { "properties": { "observed_risk": { "description": "Risk profile from actual span executions (what the agent has done). null if no spans executed.", "oneOf": [ { "properties": { "all_data_categories": { "description": "List of all data categories included across span types", "items": { "description": "Data category name", "type": "string" }, "maxItems": 18, "type": "array" }, "assessed_span_types": { "description": "Number of span types with risk data", "minimum": 0, "type": "integer" }, "classification_counts": { "description": "Count of span types at each classification level", "properties": { "confidential": { "minimum": 0, "type": "integer" }, "internal": { "minimum": 0, "type": "integer" }, "public": { "minimum": 0, "type": "integer" }, "restricted": { "minimum": 0, "type": "integer" }, "secret": { "minimum": 0, "type": "integer" }, "unknown": { "minimum": 0, "type": "integer" } }, "type": "object" }, "external_communication_count": { "description": "Number of span types with external communication allowed", "minimum": 0, "type": "integer" }, "highest_classification": { "description": "Highest classification level across all span types", "enum": [ "unknown", "public", "internal", "confidential", "restricted", "secret" ], "example": "unknown", "type": "string" }, "total_span_types": { "description": "Total number of span types", "minimum": 0, "type": "integer" }, "unassessed_span_types": { "description": "Number of span types without risk data", "minimum": 0, "type": "integer" } }, "required": [ "all_data_categories", "assessed_span_types", "classification_counts", "external_communication_count", "highest_classification", "total_span_types", "unassessed_span_types" ], "title": "Agent_RiskSummary", "type": "object" }, { "$ref": "#/components/schemas/Null" } ] }, "theoretical_risk": { "description": "Risk profile from the schema definition (what the agent could do)", "oneOf": [ { "properties": { "all_data_categories": { "description": "List of all data categories included across span types", "items": { "description": "Data category name", "type": "string" }, "maxItems": 18, "type": "array" }, "assessed_span_types": { "description": "Number of span types with risk data", "minimum": 0, "type": "integer" }, "classification_counts": { "description": "Count of span types at each classification level", "properties": { "confidential": { "minimum": 0, "type": "integer" }, "internal": { "minimum": 0, "type": "integer" }, "public": { "minimum": 0, "type": "integer" }, "restricted": { "minimum": 0, "type": "integer" }, "secret": { "minimum": 0, "type": "integer" }, "unknown": { "minimum": 0, "type": "integer" } }, "type": "object" }, "external_communication_count": { "description": "Number of span types with external communication allowed", "minimum": 0, "type": "integer" }, "highest_classification": { "description": "Highest classification level across all span types", "enum": [ "unknown", "public", "internal", "confidential", "restricted", "secret" ], "example": "unknown", "type": "string" }, "total_span_types": { "description": "Total number of span types", "minimum": 0, "type": "integer" }, "unassessed_span_types": { "description": "Number of span types without risk data", "minimum": 0, "type": "integer" } }, "required": [ "all_data_categories", "assessed_span_types", "classification_counts", "external_communication_count", "highest_classification", "total_span_types", "unassessed_span_types" ], "title": "Agent_RiskSummary", "type": "object" }, { "$ref": "#/components/schemas/Null" } ] } }, "required": [ "observed_risk", "theoretical_risk" ], "title": "Agent_RiskRollup", "type": "object" }, "Agent_RiskSummary": { "properties": { "all_data_categories": { "description": "List of all data categories included across span types", "items": { "description": "Data category name", "type": "string" }, "maxItems": 18, "type": "array" }, "assessed_span_types": { "description": "Number of span types with risk data", "minimum": 0, "type": "integer" }, "classification_counts": { "description": "Count of span types at each classification level", "properties": { "confidential": { "minimum": 0, "type": "integer" }, "internal": { "minimum": 0, "type": "integer" }, "public": { "minimum": 0, "type": "integer" }, "restricted": { "minimum": 0, "type": "integer" }, "secret": { "minimum": 0, "type": "integer" }, "unknown": { "minimum": 0, "type": "integer" } }, "type": "object" }, "external_communication_count": { "description": "Number of span types with external communication allowed", "minimum": 0, "type": "integer" }, "highest_classification": { "description": "Highest classification level across all span types", "enum": [ "unknown", "public", "internal", "confidential", "restricted", "secret" ], "example": "unknown", "type": "string" }, "total_span_types": { "description": "Total number of span types", "minimum": 0, "type": "integer" }, "unassessed_span_types": { "description": "Number of span types without risk data", "minimum": 0, "type": "integer" } }, "required": [ "all_data_categories", "assessed_span_types", "classification_counts", "external_communication_count", "highest_classification", "total_span_types", "unassessed_span_types" ], "title": "Agent_RiskSummary", "type": "object" }, "Agent_Summary": { "properties": { "available_actions": { "description": "Available actions for this agent based on its status and instance counts", "properties": { "delete": { "description": "Whether the agent can be deleted", "type": "boolean" }, "reinstate": { "description": "Whether the agent can be reinstated from retired", "type": "boolean" }, "retire": { "description": "Whether the agent can be retired", "type": "boolean" }, "update": { "description": "Whether the agent can be updated", "type": "boolean" } }, "required": [ "delete", "reinstate", "retire", "update" ], "title": "Agent_AvailableActions", "type": "object" }, "description": { "oneOf": [ { "description": "Agent description", "example": "Agent description", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "external_identifier": { "oneOf": [ { "description": "External identifier for this agent in an external system (unique per account)", "example": "workflow-abc123", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "id": { "$ref": "#/components/schemas/Agent_Id" }, "inserted_at": { "description": "When the agent was created", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "instance_counts": { "properties": { "active": { "description": "Number of instances with status active (running)", "example": 2, "minimum": 0, "type": "integer" }, "cancelled": { "description": "Number of instances with status cancelled", "example": 0, "minimum": 0, "type": "integer" }, "complete": { "description": "Number of instances with status complete", "example": 5, "minimum": 0, "type": "integer" }, "failed": { "description": "Number of instances with status failed", "example": 0, "minimum": 0, "type": "integer" }, "finished": { "description": "Number of instances in a finished state (complete + failed + cancelled + terminated)", "example": 5, "minimum": 0, "type": "integer" }, "pending": { "description": "Number of instances with status pending", "example": 0, "minimum": 0, "type": "integer" }, "terminated": { "description": "Number of instances with status terminated", "example": 0, "minimum": 0, "type": "integer" }, "total": { "description": "Total number of agent instances", "example": 10, "minimum": 0, "type": "integer" } }, "required": [ "active", "cancelled", "complete", "failed", "finished", "pending", "terminated", "total" ], "title": "Agent_InstanceCounts", "type": "object" }, "last_activity_span_at": { "description": "When this agent last had an activity span, quantised to the nearest 30 seconds, or null if none yet", "oneOf": [ { "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "name": { "description": "Agent name", "example": "My Agent", "type": "string" }, "owner_person_id": { "description": "The owner of this agent (if any)", "oneOf": [ { "$ref": "#/components/schemas/Person_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "status": { "description": "Agent status", "enum": [ "pending", "active", "dormant", "retired" ], "example": "pending", "type": "string" }, "team_id": { "description": "The team this agent belongs to (if any)", "oneOf": [ { "$ref": "#/components/schemas/Team_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "type": { "description": "Type of resource (always 'agent')", "enum": [ "agent" ], "example": "agent", "type": "string" }, "updated_at": { "description": "When the agent was last updated", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" } }, "required": [ "available_actions", "description", "external_identifier", "id", "inserted_at", "instance_counts", "last_activity_span_at", "name", "owner_person_id", "status", "team_id", "type", "updated_at" ], "title": "Agent_Summary", "type": "object" }, "Alert_Details": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "agent_instance_id": { "$ref": "#/components/schemas/AgentInstance_Id" }, "cleared_at": { "oneOf": [ { "description": "When the alert was cleared (null while raised)", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "environment_id": { "$ref": "#/components/schemas/Environment_Id" }, "id": { "$ref": "#/components/schemas/Alert_Id" }, "inserted_at": { "description": "When the alert row was created", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "name": { "description": "Name of the alert (key in the agent schema version alert_schemas)", "example": "high_error_rate", "type": "string" }, "payload": { "additionalProperties": true, "description": "Alert payload data (arbitrary JSON object)", "type": "object" }, "payload_sensitive_encoding": { "description": "When true, payload should be interpreted as containing sensitive markers as per the specification", "type": "boolean" }, "raised_at": { "description": "When the alert was raised", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "severity": { "description": "Severity of the alert", "enum": [ "critical", "error", "warning", "info" ], "example": "warning", "type": "string" }, "status": { "description": "Lifecycle status of the alert: 'raised' or 'cleared'", "enum": [ "raised", "cleared" ], "example": "raised", "type": "string" }, "summary": { "oneOf": [ { "description": "Short display text for the alert, rendered from the alert schema template (null when the schema has no template).", "example": "Error rate exceeded threshold", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "title": { "description": "Human-readable title from the alert schema (defaults to name when the schema has no title)", "example": "High error rate", "type": "string" }, "type": { "description": "Type of resource (always 'alert')", "enum": [ "alert" ], "example": "alert", "type": "string" }, "updated_at": { "description": "When the alert row was last updated", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "version": { "description": "Monotonic version of this alert row. Starts at 1 and increments on each real update.", "example": 1, "minimum": 1, "type": "integer" } }, "required": [ "account_id", "agent_id", "agent_instance_id", "cleared_at", "environment_id", "id", "inserted_at", "name", "payload", "payload_sensitive_encoding", "raised_at", "severity", "status", "summary", "title", "type", "updated_at", "version" ], "title": "Alert_Details", "type": "object" }, "Alert_Id": { "description": "A valid alert ID", "example": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "title": "Alert_Id", "type": "string" }, "Alert_Summary": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "agent_instance_id": { "$ref": "#/components/schemas/AgentInstance_Id" }, "cleared_at": { "oneOf": [ { "description": "When the alert was cleared (null while raised)", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "environment_id": { "$ref": "#/components/schemas/Environment_Id" }, "id": { "$ref": "#/components/schemas/Alert_Id" }, "inserted_at": { "description": "When the alert row was created", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "name": { "description": "Name of the alert (key in the agent schema version alert_schemas)", "example": "high_error_rate", "type": "string" }, "raised_at": { "description": "When the alert was raised", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "severity": { "description": "Severity of the alert", "enum": [ "critical", "error", "warning", "info" ], "example": "warning", "type": "string" }, "status": { "description": "Lifecycle status of the alert: 'raised' or 'cleared'", "enum": [ "raised", "cleared" ], "example": "raised", "type": "string" }, "summary": { "oneOf": [ { "description": "Short display text for the alert, rendered from the alert schema template (null when the schema has no template).", "example": "Error rate exceeded threshold", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "title": { "description": "Human-readable title from the alert schema (defaults to name when the schema has no title)", "example": "High error rate", "type": "string" }, "type": { "description": "Type of resource (always 'alert')", "enum": [ "alert" ], "example": "alert", "type": "string" }, "updated_at": { "description": "When the alert row was last updated", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "version": { "description": "Monotonic version of this alert row. Starts at 1 and increments on each real update.", "example": 1, "minimum": 1, "type": "integer" } }, "required": [ "account_id", "agent_id", "agent_instance_id", "cleared_at", "environment_id", "id", "inserted_at", "name", "raised_at", "severity", "status", "summary", "title", "type", "updated_at", "version" ], "title": "Alert_Summary", "type": "object" }, "ApiError": { "description": "An error response from the API. The conflict status code means another request updated the record. The client may retry.", "oneOf": [ { "properties": { "code": { "enum": [ "bad_request", "bad_authtoken", "not_authenticated", "not_permitted", "not_implemented", "unknown", "not_found", "unexpected_ref_type", "unexpected", "invalid_action", "alert_unknown", "alert_already_cleared", "invalid_value", "required_value", "idempotency_key_already_used", "temporarily_unavailable", "conflict" ], "example": "bad_request", "type": "string" }, "message": { "type": "string" }, "status": { "enum": [ "error" ], "example": "error", "type": "string" } }, "required": [ "code", "message", "status" ], "type": "object" }, { "properties": { "code": { "enum": [ "validation_errors" ], "example": "validation_errors", "type": "string" }, "errors": { "additionalProperties": { "$ref": "#/components/schemas/ApiError" }, "type": "object" }, "message": { "type": "string" }, "status": { "enum": [ "error" ], "example": "error", "type": "string" } }, "required": [ "code", "errors", "message", "status" ], "type": "object" }, { "properties": { "code": { "enum": [ "rate_limited" ], "example": "rate_limited", "type": "string" }, "message": { "type": "string" }, "retry_after_ms": { "description": "Milliseconds until the client may retry.", "minimum": 0, "type": "integer" }, "status": { "enum": [ "error" ], "example": "error", "type": "string" } }, "required": [ "code", "message", "retry_after_ms", "status" ], "type": "object" } ], "title": "ApiError" }, "ApiToken_AvailableActions": { "description": "Available actions for this token based on its status", "properties": { "activate": { "description": "Whether the token can be activated", "type": "boolean" }, "delete": { "description": "Whether the token can be deleted", "type": "boolean" }, "revoke": { "description": "Whether the token can be revoked", "type": "boolean" }, "suspend": { "description": "Whether the token can be suspended", "type": "boolean" } }, "required": [ "activate", "delete", "revoke", "suspend" ], "title": "ApiToken_AvailableActions", "type": "object" }, "ApiToken_Details": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "agent_deployment_id": { "description": "Set when token_scope is agent_deployment", "oneOf": [ { "$ref": "#/components/schemas/AgentDeployment_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "agent_id": { "description": "Set when token_scope is agent_deployment (deployment's agent)", "oneOf": [ { "$ref": "#/components/schemas/Agent_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "available_actions": { "description": "Available actions for this token based on its status", "properties": { "activate": { "description": "Whether the token can be activated", "type": "boolean" }, "delete": { "description": "Whether the token can be deleted", "type": "boolean" }, "revoke": { "description": "Whether the token can be revoked", "type": "boolean" }, "suspend": { "description": "Whether the token can be suspended", "type": "boolean" } }, "required": [ "activate", "delete", "revoke", "suspend" ], "title": "ApiToken_AvailableActions", "type": "object" }, "created_by_admin_user_id": { "description": "ID of the admin user who created this token", "oneOf": [ { "$ref": "#/components/schemas/AdminUser_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "environment_id": { "description": "Set when token_scope is agent_deployment (deployment's environment)", "oneOf": [ { "$ref": "#/components/schemas/Environment_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "expires_at": { "description": "When the token expires", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "id": { "$ref": "#/components/schemas/ApiToken_Id" }, "inserted_at": { "description": "When the token was created", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "last_used_at": { "oneOf": [ { "description": "When the token was last used for authentication", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "role": { "description": "Access role of the token", "enum": [ "read_only", "full_access" ], "example": "read_only", "type": "string" }, "status": { "description": "Current status of the token", "enum": [ "active", "suspended", "revoked" ], "example": "active", "type": "string" }, "token_scope": { "description": "Scope of the token", "enum": [ "account", "agent_deployment" ], "example": "account", "type": "string" }, "type": { "description": "Type of resource (always 'api_token')", "enum": [ "api_token" ], "example": "api_token", "type": "string" }, "updated_at": { "description": "When the token was last updated", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" } }, "required": [ "account_id", "agent_deployment_id", "agent_id", "available_actions", "created_by_admin_user_id", "environment_id", "expires_at", "id", "inserted_at", "last_used_at", "role", "status", "token_scope", "type", "updated_at" ], "title": "ApiToken_Details", "type": "object" }, "ApiToken_DetailsForCreate": { "properties": { "account_id": { "description": "Account ID (defaults to token's account if not provided)", "oneOf": [ { "$ref": "#/components/schemas/Account_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "agent_id": { "description": "Required when token_scope is agent_deployment; must be omitted for account scope", "oneOf": [ { "$ref": "#/components/schemas/Agent_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "environment_id": { "description": "Required when token_scope is agent_deployment; must be omitted for account scope", "oneOf": [ { "$ref": "#/components/schemas/Environment_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "expires_at": { "oneOf": [ { "description": "When the token expires (defaults to 2 years from now)", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "role": { "description": "Access role of the token (optional; defaults to full_access if omitted)", "oneOf": [ { "enum": [ "read_only", "full_access" ], "example": "read_only", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "token_scope": { "description": "Token scope", "enum": [ "account", "agent_deployment" ], "example": "account", "type": "string" } }, "title": "ApiToken_DetailsForCreate", "type": "object" }, "ApiToken_DetailsForUpdate": { "properties": { "role": { "description": "Access role of the token (omit or null to keep the current value)", "oneOf": [ { "enum": [ "read_only", "full_access" ], "example": "read_only", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] } }, "title": "ApiToken_DetailsForUpdate", "type": "object" }, "ApiToken_Id": { "description": "A valid API token ID", "example": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "title": "ApiToken_Id", "type": "string" }, "ApiToken_Summary": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "agent_deployment_id": { "description": "Set when token_scope is agent_deployment", "oneOf": [ { "$ref": "#/components/schemas/AgentDeployment_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "agent_id": { "description": "Set when token_scope is agent_deployment (deployment's agent)", "oneOf": [ { "$ref": "#/components/schemas/Agent_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "created_by_admin_user_id": { "description": "ID of the admin user who created this token", "oneOf": [ { "$ref": "#/components/schemas/AdminUser_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "environment_id": { "description": "Set when token_scope is agent_deployment (deployment's environment)", "oneOf": [ { "$ref": "#/components/schemas/Environment_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "expires_at": { "description": "When the token expires", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "id": { "$ref": "#/components/schemas/ApiToken_Id" }, "inserted_at": { "description": "When the token was created", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "last_used_at": { "oneOf": [ { "description": "When the token was last used for authentication", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "role": { "description": "Access role of the token", "enum": [ "read_only", "full_access" ], "example": "read_only", "type": "string" }, "status": { "description": "Current status of the token", "enum": [ "active", "suspended", "revoked" ], "example": "active", "type": "string" }, "token_scope": { "description": "Scope of the token", "enum": [ "account", "agent_deployment" ], "example": "account", "type": "string" }, "type": { "description": "Type of resource (always 'api_token')", "enum": [ "api_token" ], "example": "api_token", "type": "string" }, "updated_at": { "description": "When the token was last updated", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" } }, "required": [ "account_id", "agent_deployment_id", "agent_id", "created_by_admin_user_id", "environment_id", "expires_at", "id", "inserted_at", "last_used_at", "role", "status", "token_scope", "type", "updated_at" ], "title": "ApiToken_Summary", "type": "object" }, "BulkItem": { "additionalProperties": true, "description": "A single item in a bulk request. Each item must include `_type` and `idempotency_key`, plus any additional parameters required by the specific query/action type (e.g., `details` for agents/create, `agent_id` for agents/show).", "example": { "_type": "agents/create", "details": { "description": "Handles customer support inquiries", "name": "Customer Support Bot" }, "idempotency_key": "create-agent-2024-01-15-001" }, "properties": { "_type": { "description": "The type of query/action to execute (e.g., 'agents/list', 'agents/create')", "example": "agents/list", "title": "Type", "type": "string" }, "idempotency_key": { "description": "Required unique idempotency key for this item. Must be 8–128 characters and unique within the request. Used to identify the result in the response map.", "example": "create-agent-2024-01-15-001", "maxLength": 128, "minLength": 8, "title": "IdempotencyKey", "type": "string" } }, "required": [ "_type", "idempotency_key" ], "title": "BulkItem", "type": "object" }, "BulkRequest": { "description": "Request body for bulk query/action operations. Allows executing multiple API operations in a single request. Each item runs in its own transaction, processing stops at the first error, and any items after the failing item are omitted from the response.", "example": { "items": [ { "_type": "agents/list", "idempotency_key": "list-agents-2024-01-15-001" }, { "_type": "agents/create", "details": { "description": "Handles customer support inquiries", "name": "Customer Support Bot" }, "idempotency_key": "create-agent-2024-01-15-002" }, { "_type": "agents/show", "agent_id": "agent_xyz789ghi012", "idempotency_key": "show-agent-2024-01-15-003" } ] }, "properties": { "items": { "description": "List of items to process in bulk. Each item is processed sequentially in its own database transaction. Processing stops immediately on the first error: the failing item is included in the response as an error entry, and any items after it are not processed and are omitted from the response.", "items": { "additionalProperties": true, "description": "A single item in a bulk request. Each item must include `_type` and `idempotency_key`, plus any additional parameters required by the specific query/action type (e.g., `details` for agents/create, `agent_id` for agents/show).", "example": { "_type": "agents/create", "details": { "description": "Handles customer support inquiries", "name": "Customer Support Bot" }, "idempotency_key": "create-agent-2024-01-15-001" }, "properties": { "_type": { "description": "The type of query/action to execute (e.g., 'agents/list', 'agents/create')", "example": "agents/list", "title": "Type", "type": "string" }, "idempotency_key": { "description": "Required unique idempotency key for this item. Must be 8–128 characters and unique within the request. Used to identify the result in the response map.", "example": "create-agent-2024-01-15-001", "maxLength": 128, "minLength": 8, "title": "IdempotencyKey", "type": "string" } }, "required": [ "_type", "idempotency_key" ], "title": "BulkItem", "type": "object" }, "minItems": 1, "title": "Items", "type": "array" } }, "required": [ "items" ], "title": "BulkRequest", "type": "object" }, "BulkResponse": { "description": "Response from bulk query/action operations. Contains a map of results keyed by the idempotency_key from each request item. Processing stops on the first error, so the map includes successful items up to the error plus an error entry for the failing item; items after the failing item are omitted because they were not processed.", "example": { "outputs": { "create-agent-2024-01-15-002": { "code": "bad_request", "message": "Invalid agent details", "status": "error" }, "list-agents-2024-01-15-001": { "status": "success", "summaries": [ { "environment_id": "env_abc123def456", "id": "agent_xyz789ghi012", "name": "Existing Agent", "type": "agent" } ] } }, "status": "success" }, "properties": { "outputs": { "additionalProperties": { "additionalProperties": true, "description": "Output from a query or action. Contains either a success response (with 'status': 'success' and operation-specific data) or an error response (with 'status': 'error', 'code', 'message', and optionally 'errors').", "properties": {}, "title": "Output", "type": "object" }, "description": "Map where keys are the idempotency_key values from the request, and values are the corresponding query/action outputs or error responses. Each item is executed in its own transaction and processing stops immediately on the first error: outputs include successful items up to the error plus an error entry for the failing idempotency_key, and items after the failing item are not processed and are omitted from this map.", "title": "Outputs", "type": "object" }, "status": { "description": "Response status, always 'success' when the request is processed", "enum": [ "success" ], "example": "success", "title": "Status", "type": "string" } }, "required": [ "outputs", "status" ], "title": "BulkResponse", "type": "object" }, "DataCategories": { "properties": { "authentication_and_secrets": { "description": "Authentication and secrets present", "enum": [ "unknown", "included", "excluded" ], "example": "unknown", "type": "string" }, "behavioural_and_inferred": { "description": "Behavioural and inferred data present", "enum": [ "unknown", "included", "excluded" ], "example": "unknown", "type": "string" }, "classification": { "description": "Classification level", "enum": [ "unknown", "public", "internal", "confidential", "restricted", "secret" ], "example": "unknown", "type": "string" }, "contact_information": { "description": "Contact information present", "enum": [ "unknown", "included", "excluded" ], "example": "unknown", "type": "string" }, "criminal_justice": { "description": "Criminal justice data present", "enum": [ "unknown", "included", "excluded" ], "example": "unknown", "type": "string" }, "financial_information": { "description": "Financial information present", "enum": [ "unknown", "included", "excluded" ], "example": "unknown", "type": "string" }, "gdpr_biometric_for_identification": { "description": "GDPR: biometric data for identification", "enum": [ "unknown", "included", "excluded" ], "example": "unknown", "type": "string" }, "gdpr_genetic_data": { "description": "GDPR: genetic data", "enum": [ "unknown", "included", "excluded" ], "example": "unknown", "type": "string" }, "gdpr_political_opinions": { "description": "GDPR: political opinions", "enum": [ "unknown", "included", "excluded" ], "example": "unknown", "type": "string" }, "gdpr_racial_or_ethnic_origin": { "description": "GDPR: racial or ethnic origin", "enum": [ "unknown", "included", "excluded" ], "example": "unknown", "type": "string" }, "gdpr_religious_or_philosophical_beliefs": { "description": "GDPR: religious or philosophical beliefs", "enum": [ "unknown", "included", "excluded" ], "example": "unknown", "type": "string" }, "gdpr_sex_life_or_sexual_orientation": { "description": "GDPR: sex life or sexual orientation", "enum": [ "unknown", "included", "excluded" ], "example": "unknown", "type": "string" }, "gdpr_trade_union_membership": { "description": "GDPR: trade union membership", "enum": [ "unknown", "included", "excluded" ], "example": "unknown", "type": "string" }, "health_and_medical": { "description": "Health and medical data present", "enum": [ "unknown", "included", "excluded" ], "example": "unknown", "type": "string" }, "location_and_tracking": { "description": "Location and tracking data present", "enum": [ "unknown", "included", "excluded" ], "example": "unknown", "type": "string" }, "minors_data": { "description": "Minors data present", "enum": [ "unknown", "included", "excluded" ], "example": "unknown", "type": "string" }, "organisational_confidential": { "description": "Organisational confidential data present", "enum": [ "unknown", "included", "excluded" ], "example": "unknown", "type": "string" }, "personal_identifiers": { "description": "Personal identifiers present", "enum": [ "unknown", "included", "excluded" ], "example": "unknown", "type": "string" } }, "required": [ "authentication_and_secrets", "behavioural_and_inferred", "classification", "contact_information", "criminal_justice", "financial_information", "gdpr_biometric_for_identification", "gdpr_genetic_data", "gdpr_political_opinions", "gdpr_racial_or_ethnic_origin", "gdpr_religious_or_philosophical_beliefs", "gdpr_sex_life_or_sexual_orientation", "gdpr_trade_union_membership", "health_and_medical", "location_and_tracking", "minors_data", "organisational_confidential", "personal_identifiers" ], "title": "DataCategories", "type": "object" }, "DataRisk": { "properties": { "action_profile": { "$ref": "#/components/schemas/ActionProfile" }, "params_data_categories": { "$ref": "#/components/schemas/DataCategories" }, "result_data_categories": { "$ref": "#/components/schemas/DataCategories" } }, "required": [ "action_profile", "params_data_categories", "result_data_categories" ], "title": "DataRisk", "type": "object" }, "Environment_Details": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "description": { "oneOf": [ { "description": "Optional free-form description", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "external_identifier": { "oneOf": [ { "description": "External identifier for this environment in an external system (unique per account)", "example": "env-abc123", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "id": { "$ref": "#/components/schemas/Environment_Id" }, "name": { "description": "Environment name", "example": "Development", "type": "string" }, "purpose": { "description": "Environment purpose", "enum": [ "development", "staging", "testing", "production" ], "example": "development", "type": "string" }, "type": { "description": "Type of resource (always 'environment')", "enum": [ "environment" ], "example": "environment", "type": "string" } }, "required": [ "account_id", "description", "external_identifier", "id", "name", "purpose", "type" ], "title": "Environment_Details", "type": "object" }, "Environment_DetailsForCreate": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "description": { "oneOf": [ { "description": "Optional free-form description", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "external_identifier": { "oneOf": [ { "description": "Optional external identifier for this environment in an external system (unique per account)", "example": "env-abc123", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "id": { "description": "Optional ID for the environment. If not provided, a new ID will be generated. The ID must be a valid PFID with a partition matching the account. Its embedded timestamp must not be more than 7 days in the past.", "oneOf": [ { "$ref": "#/components/schemas/Environment_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "name": { "type": "string" }, "purpose": { "description": "Environment purpose", "enum": [ "development", "staging", "testing", "production" ], "example": "development", "type": "string" } }, "title": "Environment_DetailsForCreate", "type": "object" }, "Environment_DetailsForUpdate": { "properties": { "description": { "oneOf": [ { "description": "Optional free-form description", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "external_identifier": { "oneOf": [ { "description": "External identifier for this environment in an external system (omit to keep current)", "example": "env-abc123", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "name": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "purpose": { "oneOf": [ { "description": "Environment purpose", "enum": [ "development", "staging", "testing", "production" ], "example": "development", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] } }, "title": "Environment_DetailsForUpdate", "type": "object" }, "Environment_Id": { "description": "A valid environment ID", "example": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "title": "Environment_Id", "type": "string" }, "Environment_Summary": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "description": { "oneOf": [ { "description": "Optional free-form description", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "external_identifier": { "oneOf": [ { "description": "External identifier for this environment in an external system (unique per account)", "example": "env-abc123", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "id": { "$ref": "#/components/schemas/Environment_Id" }, "name": { "description": "Environment name", "example": "Development", "type": "string" }, "purpose": { "description": "Environment purpose", "enum": [ "development", "staging", "testing", "production" ], "example": "development", "type": "string" }, "type": { "description": "Type of resource (always 'environment')", "enum": [ "environment" ], "example": "environment", "type": "string" } }, "required": [ "account_id", "description", "external_identifier", "id", "name", "purpose", "type" ], "title": "Environment_Summary", "type": "object" }, "IdempotencyKey": { "description": "Required unique idempotency key for this item. Must be 8–128 characters and unique within the request. Used to identify the result in the response map.", "example": "create-agent-2024-01-15-001", "maxLength": 128, "minLength": 8, "title": "IdempotencyKey", "type": "string" }, "IdempotencyKeyOrNull": { "oneOf": [ { "description": "Optional idempotency key for ensuring request idempotency", "type": "string" }, { "$ref": "#/components/schemas/Null" } ], "title": "IdempotencyKeyOrNull" }, "Items": { "description": "List of items to process in bulk. Each item is processed sequentially in its own database transaction. Processing stops immediately on the first error: the failing item is included in the response as an error entry, and any items after it are not processed and are omitted from the response.", "items": { "additionalProperties": true, "description": "A single item in a bulk request. Each item must include `_type` and `idempotency_key`, plus any additional parameters required by the specific query/action type (e.g., `details` for agents/create, `agent_id` for agents/show).", "example": { "_type": "agents/create", "details": { "description": "Handles customer support inquiries", "name": "Customer Support Bot" }, "idempotency_key": "create-agent-2024-01-15-001" }, "properties": { "_type": { "description": "The type of query/action to execute (e.g., 'agents/list', 'agents/create')", "example": "agents/list", "title": "Type", "type": "string" }, "idempotency_key": { "description": "Required unique idempotency key for this item. Must be 8–128 characters and unique within the request. Used to identify the result in the response map.", "example": "create-agent-2024-01-15-001", "maxLength": 128, "minLength": 8, "title": "IdempotencyKey", "type": "string" } }, "required": [ "_type", "idempotency_key" ], "title": "BulkItem", "type": "object" }, "minItems": 1, "title": "Items", "type": "array" }, "LlmProviderModel_Details": { "properties": { "api_name": { "description": "API model name, unique within the provider ignoring case", "example": "claude-haiku-4-5", "type": "string" }, "id": { "$ref": "#/components/schemas/LlmProviderModel_Id" }, "llm_provider_id": { "$ref": "#/components/schemas/LlmProvider_Id" }, "models_dev_name": { "description": "models.dev identifier. Null when the model is not listed on models.dev", "oneOf": [ { "example": "anthropic/claude-haiku-4-5", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "name": { "description": "Model display name, unique within the provider ignoring case", "example": "Claude Haiku 4.5", "type": "string" }, "type": { "description": "Type of resource (always 'llm_provider_model')", "enum": [ "llm_provider_model" ], "example": "llm_provider_model", "type": "string" } }, "required": [ "api_name", "id", "llm_provider_id", "models_dev_name", "name", "type" ], "title": "LlmProviderModel_Details", "type": "object" }, "LlmProviderModel_DetailsForCreate": { "properties": { "api_name": { "description": "API model name, unique within the provider ignoring case", "example": "claude-haiku-4-5", "type": "string" }, "id": { "description": "LLM provider model ID. Must be a valid PFID whose partition matches the account, with an embedded timestamp no more than 7 days in the past (optional; a new ID is generated if omitted)", "oneOf": [ { "$ref": "#/components/schemas/LlmProviderModel_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "llm_provider_id": { "$ref": "#/components/schemas/LlmProvider_Id" }, "models_dev_name": { "description": "models.dev identifier. Derived from api_name for managed providers (optional)", "oneOf": [ { "example": "anthropic/claude-haiku-4-5", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "name": { "description": "Model display name, unique within the provider ignoring case. Derived from api_name for managed providers. Must be present when provider is custom_openai", "oneOf": [ { "example": "Claude Haiku 4.5", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] } }, "required": [ "api_name", "llm_provider_id" ], "title": "LlmProviderModel_DetailsForCreate", "type": "object" }, "LlmProviderModel_DetailsForUpdate": { "description": "Parameters for updating an LLM provider model", "properties": { "api_name": { "description": "API model name, unique within the provider ignoring case (omit to keep current)", "example": "claude-haiku-4-5", "type": "string" }, "models_dev_name": { "description": "models.dev identifier. Derived from api_name for managed providers (omit to keep current; null to clear)", "oneOf": [ { "example": "anthropic/claude-haiku-4-5", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "name": { "description": "Model display name, unique within the provider ignoring case. Derived from api_name for managed providers. Required for custom_openai (omit to keep current)", "example": "Claude Haiku 4.5", "type": "string" } }, "title": "LlmProviderModel_DetailsForUpdate", "type": "object" }, "LlmProviderModel_Id": { "description": "A valid LLM provider model ID", "example": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "title": "LlmProviderModel_Id", "type": "string" }, "LlmProviderModel_Summary": { "properties": { "api_name": { "description": "API model name, unique within the provider ignoring case", "example": "claude-haiku-4-5", "type": "string" }, "id": { "$ref": "#/components/schemas/LlmProviderModel_Id" }, "llm_provider_id": { "$ref": "#/components/schemas/LlmProvider_Id" }, "models_dev_name": { "description": "models.dev identifier. Null when the model is not listed on models.dev", "oneOf": [ { "example": "anthropic/claude-haiku-4-5", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "name": { "description": "Model display name, unique within the provider ignoring case", "example": "Claude Haiku 4.5", "type": "string" }, "type": { "description": "Type of resource (always 'llm_provider_model')", "enum": [ "llm_provider_model" ], "example": "llm_provider_model", "type": "string" } }, "required": [ "api_name", "id", "llm_provider_id", "models_dev_name", "name", "type" ], "title": "LlmProviderModel_Summary", "type": "object" }, "LlmProvider_Details": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "api_base_url": { "description": "Base URL for the provider API. Present for custom_openai and null otherwise", "oneOf": [ { "example": "https://api.example.com/v1", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "api_type": { "description": "API dialect derived from the provider kind", "enum": [ "claude", "openai" ], "example": "claude", "type": "string" }, "id": { "$ref": "#/components/schemas/LlmProvider_Id" }, "name": { "description": "Provider name, unique within the account ignoring case", "example": "Anthropic production", "type": "string" }, "provider": { "description": "LLM provider kind", "enum": [ "anthropic", "openai", "ollama_cloud", "together", "custom_openai" ], "example": "anthropic", "type": "string" }, "type": { "description": "Type of resource (always 'llm_provider')", "enum": [ "llm_provider" ], "example": "llm_provider", "type": "string" } }, "required": [ "account_id", "api_base_url", "api_type", "id", "name", "provider", "type" ], "title": "LlmProvider_Details", "type": "object" }, "LlmProvider_DetailsForCreate": { "properties": { "account_id": { "description": "Account ID (defaults to token's account if not provided)", "oneOf": [ { "$ref": "#/components/schemas/Account_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "api_base_url": { "description": "Base URL for the provider API. Must be present when provider is custom_openai and must be absent otherwise", "oneOf": [ { "example": "https://api.example.com/v1", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "api_key": { "description": "API key for this provider. Stored encrypted and never returned in API responses", "example": "sk-test-key", "type": "string" }, "id": { "description": "LLM provider ID. Must be a valid PFID whose partition matches the account, with an embedded timestamp no more than 7 days in the past (optional; a new ID is generated if omitted)", "oneOf": [ { "$ref": "#/components/schemas/LlmProvider_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "name": { "description": "Provider name, unique within the account ignoring case", "example": "Anthropic production", "type": "string" }, "provider": { "description": "LLM provider kind", "enum": [ "anthropic", "openai", "ollama_cloud", "together", "custom_openai" ], "example": "anthropic", "type": "string" } }, "required": [ "api_key", "name", "provider" ], "title": "LlmProvider_DetailsForCreate", "type": "object" }, "LlmProvider_DetailsForUpdate": { "description": "Parameters for updating an LLM provider", "properties": { "api_base_url": { "description": "Base URL for the provider API. Required when provider is custom_openai and must be absent otherwise (omit to keep current; null to clear)", "oneOf": [ { "example": "https://api.example.com/v1", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "api_key": { "description": "API key for this provider. Stored encrypted and never returned in API responses (omit to keep current)", "example": "sk-test-key", "type": "string" }, "name": { "description": "Provider name, unique within the account ignoring case (omit to keep current)", "example": "Anthropic production", "type": "string" } }, "title": "LlmProvider_DetailsForUpdate", "type": "object" }, "LlmProvider_Id": { "description": "A valid LLM provider ID", "example": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "title": "LlmProvider_Id", "type": "string" }, "LlmProvider_Summary": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "api_base_url": { "description": "Base URL for the provider API. Present for custom_openai and null otherwise", "oneOf": [ { "example": "https://api.example.com/v1", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "api_type": { "description": "API dialect derived from the provider kind", "enum": [ "claude", "openai" ], "example": "claude", "type": "string" }, "id": { "$ref": "#/components/schemas/LlmProvider_Id" }, "name": { "description": "Provider name, unique within the account ignoring case", "example": "Anthropic production", "type": "string" }, "provider": { "description": "LLM provider kind", "enum": [ "anthropic", "openai", "ollama_cloud", "together", "custom_openai" ], "example": "anthropic", "type": "string" }, "type": { "description": "Type of resource (always 'llm_provider')", "enum": [ "llm_provider" ], "example": "llm_provider", "type": "string" } }, "required": [ "account_id", "api_base_url", "api_type", "id", "name", "provider", "type" ], "title": "LlmProvider_Summary", "type": "object" }, "Null": { "description": "null", "enum": [ null ], "nullable": true, "title": "Null", "type": "string" }, "Output": { "additionalProperties": true, "description": "Output from a query or action. Contains either a success response (with 'status': 'success' and operation-specific data) or an error response (with 'status': 'error', 'code', 'message', and optionally 'errors').", "properties": {}, "title": "Output", "type": "object" }, "Outputs": { "additionalProperties": { "additionalProperties": true, "description": "Output from a query or action. Contains either a success response (with 'status': 'success' and operation-specific data) or an error response (with 'status': 'error', 'code', 'message', and optionally 'errors').", "properties": {}, "title": "Output", "type": "object" }, "description": "Map where keys are the idempotency_key values from the request, and values are the corresponding query/action outputs or error responses. Each item is executed in its own transaction and processing stops immediately on the first error: outputs include successful items up to the error plus an error entry for the failing idempotency_key, and items after the failing item are not processed and are omitted from this map.", "title": "Outputs", "type": "object" }, "PaginationOutput": { "description": "Pagination information", "example": { "item_count": 200, "item_end": 100, "item_start": 91, "next_page_offset": 110, "page_count": 20, "page_index": 10, "page_offset": 90, "page_size": 10, "previous_page_offset": 80 }, "properties": { "item_count": { "description": "The total number of items", "type": "integer" }, "item_end": { "description": "The index of the last item in the page (one-based)", "type": "integer" }, "item_start": { "description": "The index of the first item in the page (one-based)", "type": "integer" }, "next_page_offset": { "oneOf": [ { "description": "The offset of the next page (null if last page)", "type": "integer" }, { "$ref": "#/components/schemas/Null" } ] }, "page_count": { "description": "The total number of pages", "type": "integer" }, "page_index": { "description": "The index of the current page (one-based)", "type": "integer" }, "page_offset": { "description": "The offset of the first item in the page (zero-based)", "type": "integer" }, "page_size": { "description": "The number of items per page", "type": "integer" }, "previous_page_offset": { "oneOf": [ { "description": "The offset of the previous page (null if first page)", "type": "integer" }, { "$ref": "#/components/schemas/Null" } ] } }, "required": [ "item_count", "item_end", "item_start", "next_page_offset", "page_count", "page_index", "page_offset", "page_size", "previous_page_offset" ], "title": "PaginationOutput", "type": "object" }, "Person_Details": { "properties": { "email": { "description": "Person email address", "example": "jane@example.com", "type": "string" }, "id": { "$ref": "#/components/schemas/Person_Id" }, "inserted_at": { "description": "When the person was created", "format": "date-time", "type": "string" }, "name": { "description": "Person name", "example": "Jane Doe", "type": "string" }, "team_ids": { "description": "Team IDs this person belongs to", "items": { "$ref": "#/components/schemas/Team_Id" }, "type": "array" }, "title": { "oneOf": [ { "description": "Optional job title", "example": "Engineer", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "type": { "description": "Type of resource (always 'person')", "enum": [ "person" ], "example": "person", "type": "string" }, "updated_at": { "description": "When the person was last updated", "format": "date-time", "type": "string" } }, "required": [ "email", "id", "inserted_at", "name", "team_ids", "title", "type", "updated_at" ], "title": "Person_Details", "type": "object" }, "Person_ForCreate": { "properties": { "email": { "type": "string" }, "id": { "description": "Optional ID for the person. If not provided, a new ID will be generated. Its embedded timestamp must not be more than 7 days in the past.", "oneOf": [ { "$ref": "#/components/schemas/Person_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "name": { "type": "string" }, "team_ids": { "description": "Team IDs to assign on create (optional)", "items": { "$ref": "#/components/schemas/Team_Id" }, "type": "array" }, "title": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Null" } ] } }, "required": [ "name", "email" ], "title": "Person_ForCreate", "type": "object" }, "Person_ForUpdate": { "description": "Parameters for updating a person", "properties": { "email": { "description": "Person email address (omit to keep current)", "example": "jane@example.com", "type": "string" }, "name": { "description": "Person name (omit to keep current)", "example": "Jane Doe", "type": "string" }, "team_ids": { "description": "Team IDs to assign (omit to keep current; empty array to clear)", "items": { "$ref": "#/components/schemas/Team_Id" }, "type": "array" }, "title": { "description": "Optional job title (omit to keep current; null to clear)", "oneOf": [ { "example": "Engineer", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] } }, "title": "Person_ForUpdate", "type": "object" }, "Person_Id": { "description": "A valid person ID", "example": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "title": "Person_Id", "type": "string" }, "Person_Summary": { "properties": { "email": { "description": "Person email address", "example": "jane@example.com", "type": "string" }, "id": { "$ref": "#/components/schemas/Person_Id" }, "name": { "description": "Person name", "example": "Jane Doe", "type": "string" }, "team_ids": { "description": "Team IDs this person belongs to", "items": { "$ref": "#/components/schemas/Team_Id" }, "type": "array" }, "title": { "oneOf": [ { "description": "Optional job title", "example": "Engineer", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "type": { "description": "Type of resource (always 'person')", "enum": [ "person" ], "example": "person", "type": "string" } }, "required": [ "email", "id", "name", "team_ids", "title", "type" ], "title": "Person_Summary", "type": "object" }, "RiskProfile_Details": { "properties": { "agreed_data_risk": { "$ref": "#/components/schemas/DataRisk" }, "description": { "oneOf": [ { "description": "Risk profile description", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "id": { "$ref": "#/components/schemas/RiskProfile_Id" }, "inserted_at": { "description": "When the risk profile was created", "format": "date-time", "type": "string" }, "name": { "description": "Risk profile name", "example": "High Risk", "type": "string" }, "ruleset": { "$ref": "#/components/schemas/RiskProfile_Ruleset" }, "type": { "description": "Type of resource (always 'risk_profile')", "enum": [ "risk_profile" ], "example": "risk_profile", "type": "string" }, "updated_at": { "description": "When the risk profile was last updated", "format": "date-time", "type": "string" } }, "required": [ "agreed_data_risk", "description", "id", "inserted_at", "name", "ruleset", "type", "updated_at" ], "title": "RiskProfile_Details", "type": "object" }, "RiskProfile_ForCreate": { "properties": { "description": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "id": { "description": "Optional ID for the risk profile. If not provided, a new ID will be generated. Its embedded timestamp must not be more than 7 days in the past.", "oneOf": [ { "$ref": "#/components/schemas/RiskProfile_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "name": { "type": "string" }, "ruleset": { "$ref": "#/components/schemas/RiskProfile_Ruleset" } }, "required": [ "name", "ruleset" ], "title": "RiskProfile_ForCreate", "type": "object" }, "RiskProfile_ForUpdate": { "properties": { "description": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "name": { "type": "string" }, "ruleset": { "oneOf": [ { "$ref": "#/components/schemas/RiskProfile_Ruleset" }, { "$ref": "#/components/schemas/Null" } ] } }, "title": "RiskProfile_ForUpdate", "type": "object" }, "RiskProfile_Id": { "description": "A valid risk profile ID", "example": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "title": "RiskProfile_Id", "type": "string" }, "RiskProfile_Ruleset": { "properties": { "action_multipliers": { "$ref": "#/components/schemas/RiskProfile_Ruleset_ActionMultipliers" }, "category_weights": { "$ref": "#/components/schemas/RiskProfile_Ruleset_CategoryWeights" }, "thresholds": { "$ref": "#/components/schemas/RiskProfile_Ruleset_Thresholds" } }, "required": [ "action_multipliers", "category_weights", "thresholds" ], "title": "RiskProfile_Ruleset", "type": "object" }, "RiskProfile_Ruleset_ActionMultipliers": { "properties": { "create_data": { "oneOf": [ { "description": "Multiplier when the span creates data (null = N/A, valid range 1.0–5.0 in steps of 0.5)", "type": "number" }, { "$ref": "#/components/schemas/Null" } ] }, "destroy_data": { "oneOf": [ { "description": "Multiplier when the span destroys data (null = N/A, valid range 1.0–5.0 in steps of 0.5)", "type": "number" }, { "$ref": "#/components/schemas/Null" } ] }, "external_communication": { "oneOf": [ { "description": "Multiplier for external communication actions (null = N/A, valid range 1.0–5.0 in steps of 0.5)", "type": "number" }, { "$ref": "#/components/schemas/Null" } ] }, "financial_transactions": { "oneOf": [ { "description": "Multiplier for financial transaction actions (null = N/A, valid range 1.0–5.0 in steps of 0.5)", "type": "number" }, { "$ref": "#/components/schemas/Null" } ] }, "read_data": { "oneOf": [ { "description": "Multiplier when the span reads data (null = N/A, valid range 1.0–5.0 in steps of 0.5)", "type": "number" }, { "$ref": "#/components/schemas/Null" } ] }, "update_data": { "oneOf": [ { "description": "Multiplier when the span updates data (null = N/A, valid range 1.0–5.0 in steps of 0.5)", "type": "number" }, { "$ref": "#/components/schemas/Null" } ] } }, "required": [ "create_data", "destroy_data", "external_communication", "financial_transactions", "read_data", "update_data" ], "title": "RiskProfile_Ruleset_ActionMultipliers", "type": "object" }, "RiskProfile_Ruleset_CategoryWeights": { "description": "Weights per sensitive data category; each field is a non-negative integer (included; 0 contributes no score) or null (excluded from this profile)", "properties": { "authentication_and_secrets": { "oneOf": [ { "description": "Non-negative integer weight (0 is included with no contribution) or null if the category is not part of this profile", "minimum": 0, "type": "integer" }, { "$ref": "#/components/schemas/Null" } ] }, "behavioural_and_inferred": { "oneOf": [ { "description": "Non-negative integer weight (0 is included with no contribution) or null if the category is not part of this profile", "minimum": 0, "type": "integer" }, { "$ref": "#/components/schemas/Null" } ] }, "contact_information": { "oneOf": [ { "description": "Non-negative integer weight (0 is included with no contribution) or null if the category is not part of this profile", "minimum": 0, "type": "integer" }, { "$ref": "#/components/schemas/Null" } ] }, "criminal_justice": { "oneOf": [ { "description": "Non-negative integer weight (0 is included with no contribution) or null if the category is not part of this profile", "minimum": 0, "type": "integer" }, { "$ref": "#/components/schemas/Null" } ] }, "financial_information": { "oneOf": [ { "description": "Non-negative integer weight (0 is included with no contribution) or null if the category is not part of this profile", "minimum": 0, "type": "integer" }, { "$ref": "#/components/schemas/Null" } ] }, "gdpr_biometric_for_identification": { "oneOf": [ { "description": "Non-negative integer weight (0 is included with no contribution) or null if the category is not part of this profile", "minimum": 0, "type": "integer" }, { "$ref": "#/components/schemas/Null" } ] }, "gdpr_genetic_data": { "oneOf": [ { "description": "Non-negative integer weight (0 is included with no contribution) or null if the category is not part of this profile", "minimum": 0, "type": "integer" }, { "$ref": "#/components/schemas/Null" } ] }, "gdpr_political_opinions": { "oneOf": [ { "description": "Non-negative integer weight (0 is included with no contribution) or null if the category is not part of this profile", "minimum": 0, "type": "integer" }, { "$ref": "#/components/schemas/Null" } ] }, "gdpr_racial_or_ethnic_origin": { "oneOf": [ { "description": "Non-negative integer weight (0 is included with no contribution) or null if the category is not part of this profile", "minimum": 0, "type": "integer" }, { "$ref": "#/components/schemas/Null" } ] }, "gdpr_religious_or_philosophical_beliefs": { "oneOf": [ { "description": "Non-negative integer weight (0 is included with no contribution) or null if the category is not part of this profile", "minimum": 0, "type": "integer" }, { "$ref": "#/components/schemas/Null" } ] }, "gdpr_sex_life_or_sexual_orientation": { "oneOf": [ { "description": "Non-negative integer weight (0 is included with no contribution) or null if the category is not part of this profile", "minimum": 0, "type": "integer" }, { "$ref": "#/components/schemas/Null" } ] }, "gdpr_trade_union_membership": { "oneOf": [ { "description": "Non-negative integer weight (0 is included with no contribution) or null if the category is not part of this profile", "minimum": 0, "type": "integer" }, { "$ref": "#/components/schemas/Null" } ] }, "health_and_medical": { "oneOf": [ { "description": "Non-negative integer weight (0 is included with no contribution) or null if the category is not part of this profile", "minimum": 0, "type": "integer" }, { "$ref": "#/components/schemas/Null" } ] }, "location_and_tracking": { "oneOf": [ { "description": "Non-negative integer weight (0 is included with no contribution) or null if the category is not part of this profile", "minimum": 0, "type": "integer" }, { "$ref": "#/components/schemas/Null" } ] }, "minors_data": { "oneOf": [ { "description": "Non-negative integer weight (0 is included with no contribution) or null if the category is not part of this profile", "minimum": 0, "type": "integer" }, { "$ref": "#/components/schemas/Null" } ] }, "organisational_confidential": { "oneOf": [ { "description": "Non-negative integer weight (0 is included with no contribution) or null if the category is not part of this profile", "minimum": 0, "type": "integer" }, { "$ref": "#/components/schemas/Null" } ] }, "personal_identifiers": { "oneOf": [ { "description": "Non-negative integer weight (0 is included with no contribution) or null if the category is not part of this profile", "minimum": 0, "type": "integer" }, { "$ref": "#/components/schemas/Null" } ] } }, "required": [ "authentication_and_secrets", "behavioural_and_inferred", "contact_information", "criminal_justice", "financial_information", "gdpr_biometric_for_identification", "gdpr_genetic_data", "gdpr_political_opinions", "gdpr_racial_or_ethnic_origin", "gdpr_religious_or_philosophical_beliefs", "gdpr_sex_life_or_sexual_orientation", "gdpr_trade_union_membership", "health_and_medical", "location_and_tracking", "minors_data", "organisational_confidential", "personal_identifiers" ], "title": "RiskProfile_Ruleset_CategoryWeights", "type": "object" }, "RiskProfile_Ruleset_Thresholds": { "properties": { "critical": { "description": "Scores above this map to critical risk", "type": "integer" }, "high": { "description": "Scores above this map to at least high risk", "type": "integer" }, "medium": { "description": "Scores above this (after medium) map to at least medium risk", "type": "integer" } }, "required": [ "critical", "high", "medium" ], "title": "RiskProfile_Ruleset_Thresholds", "type": "object" }, "RiskProfile_Summary": { "properties": { "description": { "oneOf": [ { "description": "Risk profile description", "example": "Restrictive risk profile for sensitive operations", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "id": { "$ref": "#/components/schemas/RiskProfile_Id" }, "name": { "description": "Risk profile name", "example": "High Risk", "type": "string" }, "type": { "description": "Type of resource (always 'risk_profile')", "enum": [ "risk_profile" ], "example": "risk_profile", "type": "string" } }, "required": [ "description", "id", "name", "type" ], "title": "RiskProfile_Summary", "type": "object" }, "SchemaDetails": { "properties": { "data_risk": { "$ref": "#/components/schemas/DataRisk" }, "description": { "oneOf": [ { "description": "Optional description", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "name": { "description": "Schema name (key)", "type": "string" }, "schema": { "additionalProperties": true, "description": "JSON schema for the payload. Title and description are sibling fields on this object and are not present inside schema.", "type": "object" }, "schema_validation": { "$ref": "#/components/schemas/SchemaValidationResult" }, "template": { "oneOf": [ { "description": "Display template. Use {{field}} to interpolate payload fields.", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "title": { "description": "Human-readable title (defaults to name)", "type": "string" } }, "required": [ "data_risk", "description", "name", "schema", "schema_validation", "template", "title" ], "title": "SchemaDetails", "type": "object" }, "SchemaDetails_ForCreate": { "description": "Named schema with schema and optional title, description, template and data_risk", "properties": { "data_risk": { "oneOf": [ { "$ref": "#/components/schemas/DataRisk" }, { "$ref": "#/components/schemas/Null" } ] }, "description": { "oneOf": [ { "description": "Optional description", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "name": { "description": "Schema name (key)", "type": "string" }, "schema": { "additionalProperties": true, "description": "JSON schema for the payload", "type": "object" }, "template": { "oneOf": [ { "description": "Display template. Use {{field}} to interpolate payload fields.", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "title": { "oneOf": [ { "description": "Human-readable title. Defaults to name when omitted.", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] } }, "required": [ "name", "schema" ], "title": "SchemaDetails_ForCreate", "type": "object" }, "SchemaValidationResult": { "description": "Result of validating a JSON schema", "properties": { "message": { "oneOf": [ { "description": "Validation error message when status is 'error'", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "status": { "description": "Whether the schema is valid", "enum": [ "success", "error" ], "example": "success", "type": "string" } }, "required": [ "message", "status" ], "title": "SchemaValidationResult", "type": "object" }, "SingleSchemaDetails": { "properties": { "data_risk": { "$ref": "#/components/schemas/DataRisk" }, "description": { "description": "Optional description", "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "schema": { "additionalProperties": true, "description": "JSON schema for the payload. Title and description are sibling fields on this object and are not present inside schema.", "type": "object" }, "schema_validation": { "$ref": "#/components/schemas/SchemaValidationResult" }, "template": { "description": "Display template. Use {{field}} to interpolate payload fields.", "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "title": { "description": "Human-readable title", "type": "string" } }, "required": [ "data_risk", "description", "schema", "schema_validation", "template", "title" ], "title": "SingleSchemaDetails", "type": "object" }, "SingleSchemaDetails_ForCreate": { "description": "Single schema with schema and optional title, description, template and data_risk", "properties": { "data_risk": { "oneOf": [ { "$ref": "#/components/schemas/DataRisk" }, { "$ref": "#/components/schemas/Null" } ] }, "description": { "description": "Optional description", "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "schema": { "additionalProperties": true, "description": "JSON schema for the payload", "type": "object" }, "template": { "description": "Display template. Use {{field}} to interpolate payload fields.", "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "title": { "description": "Human-readable title. Defaults to a fixed internal name when omitted.", "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Null" } ] } }, "required": [ "schema" ], "title": "SingleSchemaDetails_ForCreate", "type": "object" }, "Sorting": { "description": "Sorting information", "properties": { "direction": { "description": "The direction to sort by", "enum": [ "asc", "desc" ], "example": "asc", "type": "string" }, "field": { "description": "The field to sort by (values depend on the type of list)", "enum": [ "id", "status", "started_at", "finished_at", "email", "name", "external_identifier", "raised_at", "cleared_at", "severity", "last_active_at", "last_activity_span_at", "last_analyzed_at", "last_used_at", "inserted_at", "mode", "agent_instance_id", "job_title", "pending_clickhouse", "pending_s3", "profile_completed_at", "promo_code", "purpose", "row_count", "size_bytes", "token_scope", "total", "website", "expires_at" ], "example": "id", "type": "string" }, "nulls": { "description": "Where to place null values. `auto` leaves placement to the database default.", "enum": [ "first", "last", "auto" ], "example": "first", "type": "string" } }, "title": "Sorting", "type": "object" }, "SpanTypeSchemaDetails": { "properties": { "data_risk": { "$ref": "#/components/schemas/DataRisk" }, "description": { "oneOf": [ { "description": "Optional description", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "name": { "description": "Span type name", "type": "string" }, "params_schema": { "additionalProperties": true, "description": "JSON schema for the span payload", "type": "object" }, "params_schema_validation": { "$ref": "#/components/schemas/SchemaValidationResult" }, "result_schema": { "additionalProperties": true, "description": "JSON schema for the span result payload (defaults to empty object if omitted when creating)", "type": "object" }, "result_schema_validation": { "$ref": "#/components/schemas/SchemaValidationResult" }, "template": { "oneOf": [ { "description": "Display template describing what happened in the span. Use {{field}} to interpolate params and result fields. Use imperative/command tense for params (e.g. \"Generate {{content}}\") and past tense for result (e.g. \"completed with {{finish_reason}}\").", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "title": { "description": "Human-readable title (defaults to name)", "type": "string" } }, "required": [ "data_risk", "description", "name", "params_schema", "params_schema_validation", "result_schema", "result_schema_validation", "template", "title" ], "title": "SpanTypeSchemaDetails", "type": "object" }, "SpanTypeSchemaDetails_ForCreate": { "description": "One span type with name, params_schema and optional result_schema", "properties": { "data_risk": { "oneOf": [ { "$ref": "#/components/schemas/DataRisk" }, { "$ref": "#/components/schemas/Null" } ] }, "description": { "oneOf": [ { "description": "Optional description", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "name": { "description": "Span type name (e.g. llm, tool)", "type": "string" }, "params_schema": { "additionalProperties": true, "description": "JSON schema for the span payload", "type": "object" }, "result_schema": { "oneOf": [ { "additionalProperties": true, "description": "JSON schema for the span result payload. Defaults to empty object if omitted.", "type": "object" }, { "$ref": "#/components/schemas/Null" } ] }, "template": { "oneOf": [ { "description": "Display template. Use {{field}} to interpolate params and result fields.", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "title": { "oneOf": [ { "description": "Human-readable title. Defaults to name when omitted.", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] } }, "required": [ "name", "params_schema" ], "title": "SpanTypeSchemaDetails_ForCreate", "type": "object" }, "Status": { "description": "Response status, always 'success' when the request is processed", "enum": [ "success" ], "example": "success", "title": "Status", "type": "string" }, "Team_Details": { "description": "Full details of a team", "properties": { "agent_count": { "description": "Number of agents assigned to this team", "example": 2, "minimum": 0, "type": "integer" }, "id": { "$ref": "#/components/schemas/Team_Id" }, "inserted_at": { "description": "When the team was created", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "name": { "description": "Team name", "example": "Sales", "type": "string" }, "people_count": { "description": "Number of people on this team", "example": 3, "minimum": 0, "type": "integer" }, "type": { "description": "Type of resource (always 'team')", "enum": [ "team" ], "example": "team", "type": "string" }, "updated_at": { "description": "When the team was last updated", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" } }, "required": [ "agent_count", "id", "inserted_at", "name", "people_count", "type", "updated_at" ], "title": "Team_Details", "type": "object" }, "Team_ForCreate": { "description": "Parameters for creating a team", "properties": { "id": { "description": "Team ID (optional; a new ID is generated if omitted). Its embedded timestamp must not be more than 7 days in the past.", "oneOf": [ { "$ref": "#/components/schemas/Team_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "name": { "description": "Team name, unique within the account ignoring case", "example": "Sales", "type": "string" } }, "required": [ "name" ], "title": "Team_ForCreate", "type": "object" }, "Team_ForUpdate": { "description": "Parameters for updating a team", "properties": { "name": { "description": "Team name, unique within the account ignoring case (omit to keep current)", "example": "Sales", "type": "string" } }, "title": "Team_ForUpdate", "type": "object" }, "Team_Id": { "description": "A valid team ID", "example": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "title": "Team_Id", "type": "string" }, "Team_Summary": { "description": "Summary of a team for list responses", "properties": { "agent_count": { "description": "Number of agents assigned to this team", "example": 2, "minimum": 0, "type": "integer" }, "id": { "$ref": "#/components/schemas/Team_Id" }, "name": { "description": "Team name", "example": "Sales", "type": "string" }, "people_count": { "description": "Number of people on this team", "example": 3, "minimum": 0, "type": "integer" }, "type": { "description": "Type of resource (always 'team')", "enum": [ "team" ], "example": "team", "type": "string" } }, "required": [ "agent_count", "id", "name", "people_count", "type" ], "title": "Team_Summary", "type": "object" }, "Type": { "description": "The type of query/action to execute (e.g., 'agents/list', 'agents/create')", "example": "agents/list", "title": "Type", "type": "string" }, "Uri": { "description": "URL to accept the invite", "example": "https://example.com", "format": "uri", "title": "Uri", "type": "string" } } }, "info": { "description": "JSON-RPC 2.0 over WebSocket at the server URL below. Method names match the bulk API type strings. HTTP REST details and shared schema components are defined in the OpenAPI spec (see `GET /api/v1/openapi`).", "title": "Prefactor JSON-RPC (WebSocket)", "version": "1.0" }, "methods": [ { "description": null, "name": "account_integrations/create", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "details": { "$ref": "#/components/schemas/AccountIntegration_DetailsForCreate" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "details" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/AccountIntegration_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Create an account integration" }, { "description": null, "name": "account_integrations/delete", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "account_integration_id": { "$ref": "#/components/schemas/AccountIntegration_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "account_integration_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/AccountIntegration_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Delete an account integration" }, { "description": null, "name": "account_integrations/list", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "status": { "enum": [ "success" ], "example": "success", "type": "string" }, "summaries": { "items": { "$ref": "#/components/schemas/AccountIntegration_Summary" }, "type": "array" } }, "required": [ "status", "summaries" ], "type": "object" } }, "summary": "List account integrations" }, { "description": null, "name": "account_integrations/show", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "account_integration_id": { "$ref": "#/components/schemas/AccountIntegration_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "account_integration_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/AccountIntegration_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Get account integration details" }, { "description": null, "name": "account_integrations/test", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "account_integration_id": { "$ref": "#/components/schemas/AccountIntegration_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "account_integration_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "delivered": { "description": "Whether Slack accepted the test notification", "example": true, "type": "boolean" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "delivered", "status" ], "type": "object" } }, "summary": "Send a test notification" }, { "description": null, "name": "account_integrations/update", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "account_integration_id": { "$ref": "#/components/schemas/AccountIntegration_Id" }, "details": { "$ref": "#/components/schemas/AccountIntegration_DetailsForUpdate" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "details", "account_integration_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/AccountIntegration_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Update an account integration" }, { "description": null, "name": "accounts/implode", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "account_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/Account_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Implode (delete) the account you are authenticated as" }, { "description": null, "name": "accounts/list", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "pagination": { "properties": { "offset": { "minimum": 0, "type": "integer" }, "page_size": { "maximum": 100, "minimum": 1, "type": "integer" } }, "type": "object" }, "sorting": { "description": "Sort order; a field name, optionally prefixed with `-` for descending (e.g. `-id`). Supported fields: `id`, `name`.", "type": "string" } }, "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "pagination": { "oneOf": [ { "$ref": "#/components/schemas/PaginationOutput" }, { "$ref": "#/components/schemas/Null" } ] }, "sorting": { "oneOf": [ { "$ref": "#/components/schemas/Sorting" }, { "$ref": "#/components/schemas/Null" } ] }, "status": { "enum": [ "success" ], "example": "success", "type": "string" }, "summaries": { "items": { "$ref": "#/components/schemas/Account_Summary" }, "type": "array" } }, "required": [ "pagination", "sorting", "status", "summaries" ], "type": "object" } }, "summary": "List accounts (internal)" }, { "description": null, "name": "accounts/show", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "account_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/Account_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Fetch account" }, { "description": null, "name": "accounts/update", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "details": { "$ref": "#/components/schemas/Account_DetailsForUpdate" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "details", "account_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/Account_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Update an account" }, { "description": null, "name": "admin_user_invites/create", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "details": { "$ref": "#/components/schemas/AdminUserInvite_DetailsForCreate" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "details" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/AdminUserInvite_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Create a new admin user invite" }, { "description": null, "name": "admin_user_invites/list", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "pagination": { "properties": { "offset": { "minimum": 0, "type": "integer" }, "page_size": { "maximum": 100, "minimum": 1, "type": "integer" } }, "type": "object" }, "sorting": { "description": "Sort order; a field name, optionally prefixed with `-` for descending (e.g. `-id`). Supported fields: `id`, `email`, `status`.", "type": "string" } }, "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "pagination": { "oneOf": [ { "$ref": "#/components/schemas/PaginationOutput" }, { "$ref": "#/components/schemas/Null" } ] }, "sorting": { "oneOf": [ { "$ref": "#/components/schemas/Sorting" }, { "$ref": "#/components/schemas/Null" } ] }, "status": { "enum": [ "success" ], "example": "success", "type": "string" }, "summaries": { "items": { "$ref": "#/components/schemas/AdminUserInvite_Summary" }, "type": "array" } }, "required": [ "pagination", "sorting", "status", "summaries" ], "type": "object" } }, "summary": "List admin user invites for an account" }, { "description": null, "name": "admin_user_invites/revoke", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "admin_user_invite_id": { "$ref": "#/components/schemas/AdminUserInvite_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "admin_user_invite_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/AdminUserInvite_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Revoke an admin user invite" }, { "description": null, "name": "admin_user_invites/show", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "admin_user_invite_id": { "$ref": "#/components/schemas/AdminUserInvite_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "admin_user_invite_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/AdminUserInvite_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Fetch admin user invite details" }, { "description": null, "name": "admin_users/list", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "pagination": { "properties": { "offset": { "minimum": 0, "type": "integer" }, "page_size": { "maximum": 100, "minimum": 1, "type": "integer" } }, "type": "object" }, "sorting": { "description": "Sort order; a field name, optionally prefixed with `-` for descending (e.g. `-id`). Supported fields: `id`, `name`, `email`.", "type": "string" } }, "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "pagination": { "oneOf": [ { "$ref": "#/components/schemas/PaginationOutput" }, { "$ref": "#/components/schemas/Null" } ] }, "sorting": { "oneOf": [ { "$ref": "#/components/schemas/Sorting" }, { "$ref": "#/components/schemas/Null" } ] }, "status": { "enum": [ "success" ], "example": "success", "type": "string" }, "summaries": { "items": { "$ref": "#/components/schemas/AdminUser_Summary" }, "type": "array" } }, "required": [ "pagination", "sorting", "status", "summaries" ], "type": "object" } }, "summary": "List admin users for an account" }, { "description": null, "name": "admin_users/show", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "admin_user_id": { "$ref": "#/components/schemas/AdminUser_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "admin_user_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/AdminUser_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Fetch admin user details" }, { "description": null, "name": "admin_users/update", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "admin_user_id": { "$ref": "#/components/schemas/AdminUser_Id" }, "details": { "$ref": "#/components/schemas/AdminUser_DetailsForUpdate" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "details", "admin_user_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/AdminUser_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Update an admin user (own profile only)" }, { "description": null, "name": "admin_users/update_role", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "admin_user_id": { "$ref": "#/components/schemas/AdminUser_Id" }, "details": { "$ref": "#/components/schemas/AdminUser_DetailsForUpdateRole" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "details", "admin_user_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/AdminUser_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Change an admin user's role" }, { "description": null, "name": "agent_deployments/create", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "details": { "$ref": "#/components/schemas/AgentDeployment_DetailsForCreate" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "details" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/AgentDeployment_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Create an agent deployment" }, { "description": null, "name": "agent_deployments/delete", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_deployment_id": { "$ref": "#/components/schemas/AgentDeployment_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "agent_deployment_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/AgentDeployment_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Delete an agent deployment" }, { "description": null, "name": "agent_deployments/list", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "pagination": { "properties": { "offset": { "minimum": 0, "type": "integer" }, "page_size": { "maximum": 100, "minimum": 1, "type": "integer" } }, "type": "object" }, "sorting": { "description": "Sort order; a field name, optionally prefixed with `-` for descending (e.g. `-id`). Supported fields: `id`.", "type": "string" } }, "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "pagination": { "oneOf": [ { "$ref": "#/components/schemas/PaginationOutput" }, { "$ref": "#/components/schemas/Null" } ] }, "sorting": { "oneOf": [ { "$ref": "#/components/schemas/Sorting" }, { "$ref": "#/components/schemas/Null" } ] }, "status": { "enum": [ "success" ], "example": "success", "type": "string" }, "summaries": { "items": { "$ref": "#/components/schemas/AgentDeployment_Summary" }, "type": "array" } }, "required": [ "pagination", "sorting", "status", "summaries" ], "type": "object" } }, "summary": "List agent deployments" }, { "description": null, "name": "agent_deployments/show", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_deployment_id": { "$ref": "#/components/schemas/AgentDeployment_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "agent_deployment_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/AgentDeployment_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Fetch agent deployment" }, { "description": null, "name": "agent_deployments/update", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_deployment_id": { "$ref": "#/components/schemas/AgentDeployment_Id" }, "details": { "$ref": "#/components/schemas/AgentDeployment_DetailsForUpdate" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "details", "agent_deployment_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/AgentDeployment_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Update an agent deployment" }, { "description": null, "name": "agent_instances/agent_context", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_instance_id": { "$ref": "#/components/schemas/AgentInstance_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "include_risk_level": { "default": false, "description": "Score spans against the agent risk profile (default: false)", "type": "boolean" } }, "required": [ "agent_instance_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "agent_context": { "$ref": "#/components/schemas/AgentInstance_AgentContext" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "agent_context", "status" ], "type": "object" } }, "summary": "Export agent instance context JSON" }, { "description": null, "name": "agent_instances/create", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_version_id": { "$ref": "#/components/schemas/AgentVersion_Id" }, "environment_id": { "$ref": "#/components/schemas/Environment_Id" }, "external_identifier": { "description": "External identifier for this agent instance in an external system, unique per agent (optional; omit or null if none)", "oneOf": [ { "example": "run-abc123", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "id": { "description": "Optional ID for the agent instance. If not provided, a new ID will be generated. The ID must be a valid PFID with a partition matching the account. Its embedded timestamp must not be more than 7 days in the past.", "oneOf": [ { "$ref": "#/components/schemas/AgentInstance_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "purpose": { "description": "Instance purpose. Defaults to live.", "enum": [ "live", "smoke_test", "eval" ], "example": "live", "type": "string" }, "update_current_version": { "default": true, "description": "Whether to set this version as the AgentDeployment's current version. Defaults to true.", "type": "boolean" } }, "required": [ "environment_id", "agent_version_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/AgentInstance_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Create an agent instance from an existing version" }, { "description": null, "name": "agent_instances/discard_sensitive", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_instance_id": { "$ref": "#/components/schemas/AgentInstance_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "agent_instance_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/AgentInstance_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Discard sensitive data for an agent instance" }, { "description": null, "name": "agent_instances/finish", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_instance_id": { "$ref": "#/components/schemas/AgentInstance_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "result_payload": { "description": "Result payload for this agent instance, validated against the agent schema version's instance_result_payload_schema when present. Only recorded when status is complete or failed; ignored for cancelled. Values marked with $sensitive are extracted and stored securely, separate from the rest of the payload.", "oneOf": [ { "additionalProperties": true, "type": "object" }, { "$ref": "#/components/schemas/Null" } ] }, "status": { "description": "Terminal status: 'complete' (default), 'failed', or 'cancelled'. When 'cancelled', instance must be pending and both timestamps are set to the (optional) timestamp. Hosted instances can only be cancelled while pending; they cannot be completed or failed.", "enum": [ "complete", "failed", "cancelled" ], "example": "complete", "type": "string" }, "timestamp": { "oneOf": [ { "description": "Finish timestamp (ISO 8601 format). If not provided, current time is used. Must not be more than 7 days in the past. Hosted instances cannot take a timestamp.", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] } }, "required": [ "agent_instance_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/AgentInstance_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Finish an agent instance" }, { "description": null, "name": "agent_instances/list", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "active_during": { "properties": { "finish_at": { "description": "When set with start_at, only instances whose active range overlaps [start_at, finish_at).", "oneOf": [ { "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "start_at": { "description": "When set with finish_at, only instances whose active range overlaps [start_at, finish_at).", "oneOf": [ { "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] } }, "type": "object" }, "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "agent_version_id": { "$ref": "#/components/schemas/AgentVersion_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "include_alert_count": { "default": false, "description": "Include raised_alert_count in the response (counts only alerts the caller may show)", "type": "boolean" }, "include_risk_score": { "default": false, "description": "Include risk_score in each summary (null when the agent has no risk profile or scoring inputs are unavailable)", "type": "boolean" }, "pagination": { "properties": { "offset": { "minimum": 0, "type": "integer" }, "page_size": { "maximum": 100, "minimum": 1, "type": "integer" }, "page_with_id": { "$ref": "#/components/schemas/AgentInstance_Id" } }, "type": "object" }, "sorting": { "description": "Sort order; a field name, optionally prefixed with `-` for descending (e.g. `-id`). Supported fields: `id`, `status`, `last_activity_span_at`.", "type": "string" } }, "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "pagination": { "oneOf": [ { "$ref": "#/components/schemas/PaginationOutput" }, { "$ref": "#/components/schemas/Null" } ] }, "sorting": { "oneOf": [ { "$ref": "#/components/schemas/Sorting" }, { "$ref": "#/components/schemas/Null" } ] }, "status": { "enum": [ "success" ], "example": "success", "type": "string" }, "summaries": { "items": { "$ref": "#/components/schemas/AgentInstance_Summary" }, "type": "array" } }, "required": [ "pagination", "sorting", "status", "summaries" ], "type": "object" } }, "summary": "List agent instances" }, { "description": null, "name": "agent_instances/record_quality", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_instance_id": { "$ref": "#/components/schemas/AgentInstance_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "name": { "description": "Quality schema name (key in the agent schema version quality_schemas)", "example": "summary_quality", "type": "string" }, "payload": { "description": "Quality payload for this name. Must be a JSON object, or null to remove the recorded payload for this name.", "oneOf": [ { "additionalProperties": true, "type": "object" }, { "$ref": "#/components/schemas/Null" } ] } }, "required": [ "payload", "name", "agent_instance_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/AgentInstance_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Record a quality payload on an agent instance" }, { "description": null, "name": "agent_instances/register", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_id": { "description": "Agent this instance registers against. Omitting agent_id requires an agent-deployment-scoped API token; the server then uses the token's agent.", "oneOf": [ { "$ref": "#/components/schemas/Agent_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "agent_schema_version": { "properties": { "alert_schemas": { "oneOf": [ { "description": "Array of alert schemas with name, schema and optional title, description, template and data_risk.", "items": { "$ref": "#/components/schemas/SchemaDetails_ForCreate" }, "type": "array" }, { "$ref": "#/components/schemas/Null" } ] }, "external_identifier": { "type": "string" }, "instance_metadata_schema": { "description": "Single JSON schema validating each agent instance's metadata registered against this schema version. Omit or null for no metadata schema.", "oneOf": [ { "$ref": "#/components/schemas/SingleSchemaDetails_ForCreate" }, { "$ref": "#/components/schemas/Null" } ] }, "instance_params_payload_schema": { "description": "Single JSON schema validating each agent instance's params_payload registered against this schema version. Omit or null for no params payload schema.", "oneOf": [ { "$ref": "#/components/schemas/SingleSchemaDetails_ForCreate" }, { "$ref": "#/components/schemas/Null" } ] }, "instance_result_payload_schema": { "description": "Single JSON schema validating each agent instance's result_payload recorded on finish against this schema version. Omit or null for no result payload schema.", "oneOf": [ { "$ref": "#/components/schemas/SingleSchemaDetails_ForCreate" }, { "$ref": "#/components/schemas/Null" } ] }, "quality_schemas": { "oneOf": [ { "description": "Array of quality schemas with name, schema and optional title, description, template and data_risk.", "items": { "$ref": "#/components/schemas/SchemaDetails_ForCreate" }, "type": "array" }, { "$ref": "#/components/schemas/Null" } ] }, "span_result_schemas": { "deprecated": true, "description": "Deprecated. Use span_type_schemas instead. Optional map of span type names to their result payload JSON schemas. Only used when span_schemas is provided; keys may be a subset of span_schemas; missing keys default to a schema requiring empty object.", "oneOf": [ { "additionalProperties": { "additionalProperties": true, "type": "object" }, "type": "object" }, { "$ref": "#/components/schemas/Null" } ] }, "span_schemas": { "deprecated": true, "description": "Deprecated. Use span_type_schemas instead. Map of span type names to their JSON schemas.", "oneOf": [ { "additionalProperties": { "additionalProperties": true, "type": "object" }, "type": "object" }, { "$ref": "#/components/schemas/Null" } ] }, "span_type_schemas": { "oneOf": [ { "description": "Array of span types with name, params_schema and optional result_schema.", "items": { "$ref": "#/components/schemas/SpanTypeSchemaDetails_ForCreate" }, "type": "array" }, { "$ref": "#/components/schemas/Null" } ] } }, "title": "AgentSchemaVersionForRegister", "type": "object" }, "agent_version": { "properties": { "description": { "oneOf": [ { "deprecated": true, "description": "Deprecated. Accepted for backward compatibility; ignored. Use agents/update to set the agent description.", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "external_identifier": { "type": "string" }, "name": { "oneOf": [ { "deprecated": true, "description": "Deprecated. Accepted for backward compatibility; ignored. Use agents/update to set the agent name.", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "runtime_environment": { "description": "Runtime environment metadata (SDK version, harness version, etc.)", "oneOf": [ { "$ref": "#/components/schemas/AgentVersion_RuntimeEnvironment" }, { "$ref": "#/components/schemas/Null" } ] } }, "title": "AgentVersionForRegister", "type": "object" }, "environment_id": { "description": "Environment this instance registers against. Send this in all new code. Omitting environment_id requires an agent-deployment-scoped API token; the server then uses the token's environment. When no token is available, omitting it is for backward compatibility only: the server then uses the agent's only deployment, and the request fails if there are zero deployments or more than one.", "oneOf": [ { "$ref": "#/components/schemas/Environment_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "external_identifier": { "oneOf": [ { "description": "Optional external identifier for this agent instance in an external system (unique per agent).", "example": "run-abc123", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "id": { "description": "Optional ID for the agent instance. If not provided, a new ID will be generated. The ID must be a valid PFID with a partition matching the account. Its embedded timestamp must not be more than 7 days in the past.", "oneOf": [ { "$ref": "#/components/schemas/AgentInstance_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "metadata": { "description": "Metadata for this agent instance, validated against the agent schema version's instance_metadata_schema when present. Set at register only. Values marked with $sensitive are extracted and stored securely, separate from the rest of the payload.", "oneOf": [ { "additionalProperties": true, "type": "object" }, { "$ref": "#/components/schemas/Null" } ] }, "params_payload": { "description": "Input payload for this agent instance, validated against the agent schema version's instance_params_payload_schema when present. Set at register only. Values marked with $sensitive are extracted and stored securely, separate from the rest of the payload.", "oneOf": [ { "additionalProperties": true, "type": "object" }, { "$ref": "#/components/schemas/Null" } ] }, "purpose": { "default": "live", "description": "Why this instance ran: 'live' for an actual agent run, 'smoke_test' for a pipeline check, or 'eval' for an evaluation run. Defaults to 'live'.", "enum": [ "live", "smoke_test", "eval" ], "example": "live", "type": "string" }, "update_current_version": { "default": true, "description": "Whether to set this version as the AgentDeployment's current version. Defaults to true.", "type": "boolean" } }, "required": [ "agent_schema_version", "agent_version" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "agent_schema_version": { "$ref": "#/components/schemas/AgentSchemaVersion_Details" }, "agent_version": { "$ref": "#/components/schemas/AgentVersion_Details" }, "details": { "$ref": "#/components/schemas/AgentInstance_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "agent_schema_version", "agent_version", "details", "status" ], "type": "object" } }, "summary": "Register a new agent instance with agent version" }, { "description": null, "name": "agent_instances/send_message", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_instance_id": { "$ref": "#/components/schemas/AgentInstance_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "message": { "description": "User message. Hosted instances only.", "example": "Hello", "type": "string" } }, "required": [ "message", "agent_instance_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/AgentInstance_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Send a user message to a hosted agent instance" }, { "description": null, "name": "agent_instances/show", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_instance_id": { "$ref": "#/components/schemas/AgentInstance_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "include_alert_count": { "default": false, "description": "Include raised_alert_count in the response (counts only alerts the caller may show)", "type": "boolean" }, "include_costs": { "default": false, "description": "Include cost_breakdown in the response (null when costs do not apply or there is no token usage)", "type": "boolean" }, "include_counts": { "default": false, "description": "Include span_counts and span_schema_counts in the response", "type": "boolean" }, "include_risk_score": { "default": false, "description": "Include risk_score in the response (null when the agent has no risk profile or scoring inputs are unavailable)", "type": "boolean" }, "time_range": { "properties": { "finish_at": { "oneOf": [ { "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "start_at": { "oneOf": [ { "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] } }, "type": "object" } }, "required": [ "agent_instance_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/AgentInstance_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Fetch agent instance" }, { "description": null, "name": "agent_instances/start", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_instance_id": { "$ref": "#/components/schemas/AgentInstance_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "timestamp": { "oneOf": [ { "description": "Start timestamp (ISO 8601 format). If not provided, current time is used. Must not be more than 7 days in the past. Hosted instances cannot take a timestamp.", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] } }, "required": [ "agent_instance_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/AgentInstance_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Start an agent instance" }, { "description": null, "name": "agent_instances/terminate", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_instance_id": { "$ref": "#/components/schemas/AgentInstance_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "reason": { "description": "Required reason for termination (e.g. user requested stop, resource limits).", "example": "User requested termination", "type": "string" }, "timestamp": { "oneOf": [ { "description": "Termination timestamp (ISO 8601 format). If not provided, current time is used. Must not be more than 7 days in the past. Hosted instances cannot take a timestamp.", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] } }, "required": [ "reason", "agent_instance_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/AgentInstance_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Terminate an agent instance" }, { "description": "Returns the matching agent schema version if one already exists for this agent with the same external identifier and schema content. Otherwise creates a new version.", "name": "agent_schema_versions/create", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "details": { "$ref": "#/components/schemas/AgentSchemaVersion_DetailsForCreate" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "details" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/AgentSchemaVersion_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Find or create an agent schema version" }, { "description": null, "name": "agent_schema_versions/list", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "pagination": { "properties": { "offset": { "minimum": 0, "type": "integer" }, "page_size": { "maximum": 100, "minimum": 1, "type": "integer" } }, "type": "object" }, "sorting": { "description": "Sort order; a field name, optionally prefixed with `-` for descending (e.g. `-id`). Supported fields: `id`, `external_identifier`.", "type": "string" } }, "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "pagination": { "oneOf": [ { "$ref": "#/components/schemas/PaginationOutput" }, { "$ref": "#/components/schemas/Null" } ] }, "sorting": { "oneOf": [ { "$ref": "#/components/schemas/Sorting" }, { "$ref": "#/components/schemas/Null" } ] }, "status": { "enum": [ "success" ], "example": "success", "type": "string" }, "summaries": { "items": { "$ref": "#/components/schemas/AgentSchemaVersion_Summary" }, "type": "array" } }, "required": [ "pagination", "sorting", "status", "summaries" ], "type": "object" } }, "summary": "List agent schema versions" }, { "description": null, "name": "agent_schema_versions/show", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_schema_version_id": { "$ref": "#/components/schemas/AgentSchemaVersion_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "agent_schema_version_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/AgentSchemaVersion_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Fetch agent schema version" }, { "description": null, "name": "agent_spans/create", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "details": { "$ref": "#/components/schemas/AgentSpan_DetailsForCreate" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "details" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "control": { "$ref": "#/components/schemas/AgentSpan_Control" }, "details": { "$ref": "#/components/schemas/AgentSpan_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Create a new agent span" }, { "description": null, "name": "agent_spans/discard_sensitive", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_span_id": { "$ref": "#/components/schemas/AgentSpan_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "agent_span_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/AgentSpan_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Discard sensitive sidecar for an agent span" }, { "description": null, "name": "agent_spans/finish", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_span_id": { "$ref": "#/components/schemas/AgentSpan_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "result_payload": { "oneOf": [ { "additionalProperties": true, "description": "Optional result payload (arbitrary JSON), only set when finishing the span.", "type": "object" }, { "$ref": "#/components/schemas/Null" } ] }, "sensitive_encoding": { "default": false, "description": "When true, result_payload is parsed as sensitive-encoded JSON; values marked with $sensitive are extracted and stored securely, separate from the rest of the result_payload. Defaults to false.", "type": "boolean" }, "status": { "description": "Terminal status: 'complete' (default), 'failed', or 'cancelled'.", "enum": [ "complete", "failed", "cancelled" ], "example": "complete", "type": "string" }, "timestamp": { "oneOf": [ { "description": "Finish timestamp (ISO 8601 format). If not provided, current time is used. Must not be more than 7 days in the past.", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] } }, "required": [ "agent_span_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "control": { "$ref": "#/components/schemas/AgentSpan_Control" }, "details": { "$ref": "#/components/schemas/AgentSpan_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Finish an agent span" }, { "description": null, "name": "agent_spans/list", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "agent_instance_id": { "$ref": "#/components/schemas/AgentInstance_Id" }, "alert_id": { "description": "When set, only spans for this alert are listed. Typically used with purpose=alert.", "oneOf": [ { "$ref": "#/components/schemas/Alert_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "environment_id": { "description": "When set with agent_id, only spans from agent instances in this environment are listed.", "oneOf": [ { "$ref": "#/components/schemas/Environment_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "include_risk_level": { "default": false, "description": "When true, score each activity-purpose span against the agent's risk profile and populate `risk_level` and `risk_score` on the summary.", "type": "boolean" }, "include_summaries": { "default": false, "description": "Include human-readable summaries from schema templates (default: false for performance)", "type": "boolean" }, "pagination": { "properties": { "offset": { "minimum": 0, "type": "integer" }, "page_size": { "maximum": 100, "minimum": 1, "type": "integer" } }, "type": "object" }, "purpose": { "description": "When set, only spans with this purpose are listed: 'activity' (normal agent activity), 'quality' (system-written quality payload updates), or 'alert' (system-written alert lifecycle events). Omit or null to list spans of every purpose.", "oneOf": [ { "enum": [ "activity", "quality", "alert" ], "example": "activity", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "redacted": { "default": false, "description": "When true, strip sensitive values from payload and result_payload, and render the summary with redaction labels. Defaults to false.", "type": "boolean" }, "sorting": { "description": "Sort order; a field name, optionally prefixed with `-` for descending (e.g. `-id`). Supported fields: `id`, `started_at`, `finished_at`, `status`.", "type": "string" } }, "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "pagination": { "oneOf": [ { "$ref": "#/components/schemas/PaginationOutput" }, { "$ref": "#/components/schemas/Null" } ] }, "sorting": { "oneOf": [ { "$ref": "#/components/schemas/Sorting" }, { "$ref": "#/components/schemas/Null" } ] }, "status": { "enum": [ "success" ], "example": "success", "type": "string" }, "summaries": { "items": { "$ref": "#/components/schemas/AgentSpan_Summary" }, "type": "array" } }, "required": [ "pagination", "sorting", "status", "summaries" ], "type": "object" } }, "summary": "List agent spans" }, { "description": null, "name": "agent_spans/show", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_span_id": { "$ref": "#/components/schemas/AgentSpan_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "redacted": { "default": false, "description": "When true, strip sensitive values from payload and result_payload, and render the summary with redaction labels. Defaults to false.", "type": "boolean" } }, "required": [ "agent_span_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/AgentSpan_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Fetch agent span" }, { "description": "Returns the matching agent version if one already exists for this agent with the same external identifier, schema version, runtime environment, execution mode, and hosted fields. Otherwise creates a new version.", "name": "agent_versions/create", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "details": { "$ref": "#/components/schemas/AgentVersion_DetailsForCreate" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "details" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/AgentVersion_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Find or create an agent version" }, { "description": null, "name": "agent_versions/list", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "pagination": { "properties": { "offset": { "minimum": 0, "type": "integer" }, "page_size": { "maximum": 100, "minimum": 1, "type": "integer" } }, "type": "object" }, "sorting": { "description": "Sort order; a field name, optionally prefixed with `-` for descending (e.g. `-id`). Supported fields: `id`, `external_identifier`.", "type": "string" } }, "required": [ "agent_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "pagination": { "oneOf": [ { "$ref": "#/components/schemas/PaginationOutput" }, { "$ref": "#/components/schemas/Null" } ] }, "sorting": { "oneOf": [ { "$ref": "#/components/schemas/Sorting" }, { "$ref": "#/components/schemas/Null" } ] }, "status": { "enum": [ "success" ], "example": "success", "type": "string" }, "summaries": { "items": { "$ref": "#/components/schemas/AgentVersion_Summary" }, "type": "array" } }, "required": [ "pagination", "sorting", "status", "summaries" ], "type": "object" } }, "summary": "List agent versions" }, { "description": null, "name": "agent_versions/show", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_version_id": { "$ref": "#/components/schemas/AgentVersion_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "agent_version_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/AgentVersion_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Fetch agent version" }, { "description": null, "name": "agents/create", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "details": { "$ref": "#/components/schemas/Agent_DetailsForCreate" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "details" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/Agent_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Create a new agent" }, { "description": null, "name": "agents/delete", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "agent_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/Agent_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Delete an agent" }, { "description": null, "name": "agents/list", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "instances_active_during": { "properties": { "finish_at": { "description": "When set with start_at, instance_counts only include instances whose active range overlaps [start_at, finish_at). Does not filter which agents are listed.", "oneOf": [ { "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "start_at": { "description": "When set with finish_at, instance_counts only include instances whose active range overlaps [start_at, finish_at). Does not filter which agents are listed.", "oneOf": [ { "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] } }, "type": "object" }, "owner_person_id": { "description": "When a person id, return only agents owned by that person. When `null`, return only agents with no owner. When omitted, return all agents (after permission filtering).", "oneOf": [ { "$ref": "#/components/schemas/Person_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "pagination": { "properties": { "offset": { "minimum": 0, "type": "integer" }, "page_size": { "maximum": 100, "minimum": 1, "type": "integer" } }, "type": "object" }, "risk_profile_id": { "description": "When a profile id, return only agents using that risk profile. When `null`, return only agents with no risk profile. When omitted, return all agents (after permission filtering).", "oneOf": [ { "$ref": "#/components/schemas/RiskProfile_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "sorting": { "description": "Sort order; a field name, optionally prefixed with `-` for descending (e.g. `-id`). Supported fields: `id`, `name`, `status`, `last_activity_span_at`.", "type": "string" }, "team_id": { "description": "When a team id, return only agents on that team. When `null`, return only agents with no team. When omitted, return all agents (after permission filtering).", "oneOf": [ { "$ref": "#/components/schemas/Team_Id" }, { "$ref": "#/components/schemas/Null" } ] } }, "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "pagination": { "oneOf": [ { "$ref": "#/components/schemas/PaginationOutput" }, { "$ref": "#/components/schemas/Null" } ] }, "sorting": { "oneOf": [ { "$ref": "#/components/schemas/Sorting" }, { "$ref": "#/components/schemas/Null" } ] }, "status": { "enum": [ "success" ], "example": "success", "type": "string" }, "summaries": { "items": { "$ref": "#/components/schemas/Agent_Summary" }, "type": "array" } }, "required": [ "pagination", "sorting", "status", "summaries" ], "type": "object" } }, "summary": "List agents" }, { "description": null, "name": "agents/reinstate", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "agent_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/Agent_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Reinstate a retired agent" }, { "description": null, "name": "agents/retire", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "agent_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/Agent_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Retire an agent" }, { "description": null, "name": "agents/show", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "environment_id": { "description": "When set, risk rollup uses the deployment current version for this environment. When `include_counts` is true, instance counts are scoped to this environment, and observed risk is scoped to activity spans in this environment.", "oneOf": [ { "$ref": "#/components/schemas/Environment_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "external_identifier": { "description": "External identifier for this agent (exact match). Provide exactly one of agent_id or external_identifier.", "type": "string" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "include_counts": { "default": false, "description": "Include instance counts in the response", "type": "boolean" }, "include_risk_rollup": { "default": false, "description": "Include risk rollup (theoretical and observed risk) in the response", "type": "boolean" }, "instances_active_during": { "properties": { "finish_at": { "description": "Filters instance_counts to instances whose active range overlaps the half-open [start_at, finish_at) range and filters observed risk to activity spans started in the same range. Theoretical risk remains based on the current schema.", "oneOf": [ { "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "start_at": { "description": "Filters instance_counts to instances whose active range overlaps the half-open [start_at, finish_at) range and filters observed risk to activity spans started in the same range. Theoretical risk remains based on the current schema.", "oneOf": [ { "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] } }, "type": "object" } }, "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/Agent_Details" }, "risk_rollup": { "$ref": "#/components/schemas/Agent_RiskRollup" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "title": "Agent_GetDetailsOutput", "type": "object" } }, "summary": "Fetch agent by lookup" }, { "description": null, "name": "agents/update", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "details": { "$ref": "#/components/schemas/Agent_DetailsForUpdate" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "details", "agent_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/Agent_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Update an agent" }, { "description": null, "name": "alerts/clear", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_instance_id": { "$ref": "#/components/schemas/AgentInstance_Id" }, "cleared_at": { "description": "Optional clear timestamp (ISO 8601). Sets cleared_at on the alert row and the alert-purpose span times. Omit to use the current time. When provided, must not be more than 7 days in the past.", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "name": { "description": "Alert name (key in the agent schema version alert_schemas)", "example": "high_error_rate", "type": "string" }, "payload": { "additionalProperties": true, "description": "Optional replacement payload. Omit to leave the stored payload unchanged.", "type": "object" }, "payload_sensitive_encoding": { "default": false, "description": "When true, payload is parsed as sensitive-encoded JSON; values marked with $sensitive are extracted and stored securely. Defaults to false.", "type": "boolean" }, "severity": { "description": "Optional replacement severity. Omit to leave the stored severity unchanged.", "enum": [ "critical", "error", "warning", "info" ], "example": "info", "type": "string" } }, "required": [ "name", "agent_instance_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/Alert_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Clear a raised alert on an agent instance" }, { "description": null, "name": "alerts/count", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "active_during": { "properties": { "finish_at": { "description": "When set with start_at, only alerts active during the range are counted.", "oneOf": [ { "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "start_at": { "description": "When set with finish_at, only alerts active during the range are counted.", "oneOf": [ { "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] } }, "type": "object" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "severity": { "description": "When set, only alerts with this severity are counted.", "oneOf": [ { "enum": [ "critical", "error", "warning", "info" ], "example": "warning", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "status": { "description": "When set, only alerts with this status are counted.", "oneOf": [ { "enum": [ "raised", "cleared" ], "example": "raised", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] } }, "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "count": { "description": "The number of matching alerts", "minimum": 0, "type": "integer" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "count", "status" ], "type": "object" } }, "summary": "Count alerts" }, { "description": null, "name": "alerts/list", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "active_during": { "properties": { "finish_at": { "description": "When set with start_at, only alerts whose raised range overlaps [start_at, finish_at).", "oneOf": [ { "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "start_at": { "description": "When set with finish_at, only alerts whose raised range overlaps [start_at, finish_at).", "oneOf": [ { "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] } }, "type": "object" }, "agent_id": { "description": "When set, only alerts for this agent are listed.", "oneOf": [ { "$ref": "#/components/schemas/Agent_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "agent_instance_id": { "description": "When set, only alerts for this agent instance are listed.", "oneOf": [ { "$ref": "#/components/schemas/AgentInstance_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "environment_id": { "description": "When set, only alerts in this environment are listed.", "oneOf": [ { "$ref": "#/components/schemas/Environment_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "name": { "description": "When set, only alerts with this name (alert schema key) are listed.", "oneOf": [ { "example": "high_error_rate", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "pagination": { "properties": { "offset": { "minimum": 0, "type": "integer" }, "page_size": { "maximum": 100, "minimum": 1, "type": "integer" } }, "type": "object" }, "severity": { "description": "When set, only alerts with this severity are listed.", "oneOf": [ { "enum": [ "critical", "error", "warning", "info" ], "example": "warning", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] }, "sorting": { "description": "Sort order; a field name, optionally prefixed with `-` for descending (e.g. `-id`). Supported fields: `id`, `raised_at`, `cleared_at`, `name`, `severity`. Descending `severity` puts critical first because severity is stored as a magnitude. When omitted, the default order is raised first, then severity descending, then cleared_at descending, then name ascending.", "type": "string" }, "status": { "description": "When set, only alerts with this status are listed.", "oneOf": [ { "enum": [ "raised", "cleared" ], "example": "raised", "type": "string" }, { "$ref": "#/components/schemas/Null" } ] } }, "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "pagination": { "oneOf": [ { "$ref": "#/components/schemas/PaginationOutput" }, { "$ref": "#/components/schemas/Null" } ] }, "sorting": { "oneOf": [ { "$ref": "#/components/schemas/Sorting" }, { "$ref": "#/components/schemas/Null" } ] }, "status": { "enum": [ "success" ], "example": "success", "type": "string" }, "summaries": { "items": { "$ref": "#/components/schemas/Alert_Summary" }, "type": "array" } }, "required": [ "pagination", "sorting", "status", "summaries" ], "type": "object" } }, "summary": "List alerts" }, { "description": null, "name": "alerts/raise", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_instance_id": { "$ref": "#/components/schemas/AgentInstance_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "name": { "description": "Alert name (key in the agent schema version alert_schemas)", "example": "high_error_rate", "type": "string" }, "payload": { "additionalProperties": true, "description": "Alert payload data (arbitrary JSON object)", "type": "object" }, "payload_sensitive_encoding": { "default": false, "description": "When true, payload is parsed as sensitive-encoded JSON; values marked with $sensitive are extracted and stored securely. Defaults to false.", "type": "boolean" }, "raised_at": { "description": "Optional raise timestamp (ISO 8601). Sets raised_at on insert and the alert-purpose span times. Omit to use the current time. Re-raises leave the stored raised_at unchanged but still use this value for the span when given. When provided, must not be more than 7 days in the past.", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "severity": { "description": "Severity of the alert", "enum": [ "critical", "error", "warning", "info" ], "example": "warning", "type": "string" } }, "required": [ "payload", "severity", "name", "agent_instance_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/Alert_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Raise an alert on an agent instance" }, { "description": null, "name": "alerts/show", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "alert_id": { "$ref": "#/components/schemas/Alert_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "alert_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/Alert_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Fetch alert" }, { "description": null, "name": "api_tokens/activate", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "api_token_id": { "$ref": "#/components/schemas/ApiToken_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "api_token_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/ApiToken_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Activate a suspended API token" }, { "description": null, "name": "api_tokens/create", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "details": { "$ref": "#/components/schemas/ApiToken_DetailsForCreate" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "details" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/ApiToken_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" }, "token": { "description": "The JWT token string (only available on creation)", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "type": "string" } }, "required": [ "details", "status", "token" ], "type": "object" } }, "summary": "Create a new API token" }, { "description": null, "name": "api_tokens/delete", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "api_token_id": { "$ref": "#/components/schemas/ApiToken_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "api_token_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/ApiToken_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Delete an API token" }, { "description": null, "name": "api_tokens/list", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "pagination": { "properties": { "offset": { "minimum": 0, "type": "integer" }, "page_size": { "maximum": 100, "minimum": 1, "type": "integer" } }, "type": "object" }, "sorting": { "description": "Sort order; a field name, optionally prefixed with `-` for descending (e.g. `-id`). Supported fields: `id`, `status`.", "type": "string" } }, "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "pagination": { "oneOf": [ { "$ref": "#/components/schemas/PaginationOutput" }, { "$ref": "#/components/schemas/Null" } ] }, "sorting": { "oneOf": [ { "$ref": "#/components/schemas/Sorting" }, { "$ref": "#/components/schemas/Null" } ] }, "status": { "enum": [ "success" ], "example": "success", "type": "string" }, "summaries": { "items": { "$ref": "#/components/schemas/ApiToken_Summary" }, "type": "array" } }, "required": [ "pagination", "sorting", "status", "summaries" ], "type": "object" } }, "summary": "List API tokens" }, { "description": null, "name": "api_tokens/revoke", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "api_token_id": { "$ref": "#/components/schemas/ApiToken_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "api_token_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/ApiToken_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Revoke an API token" }, { "description": null, "name": "api_tokens/show", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "api_token_id": { "$ref": "#/components/schemas/ApiToken_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "api_token_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/ApiToken_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Fetch API token" }, { "description": null, "name": "api_tokens/suspend", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "api_token_id": { "$ref": "#/components/schemas/ApiToken_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "api_token_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/ApiToken_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Suspend an API token" }, { "description": null, "name": "api_tokens/update", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "api_token_id": { "$ref": "#/components/schemas/ApiToken_Id" }, "details": { "$ref": "#/components/schemas/ApiToken_DetailsForUpdate" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "details", "api_token_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/ApiToken_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Update an API token" }, { "description": null, "name": "environments/create", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "details": { "$ref": "#/components/schemas/Environment_DetailsForCreate" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "details" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/Environment_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Create a new environment" }, { "description": null, "name": "environments/delete", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "environment_id": { "$ref": "#/components/schemas/Environment_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "environment_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/Environment_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Delete an environment" }, { "description": null, "name": "environments/list", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "pagination": { "properties": { "offset": { "minimum": 0, "type": "integer" }, "page_size": { "maximum": 100, "minimum": 1, "type": "integer" } }, "type": "object" }, "sorting": { "description": "Sort order; a field name, optionally prefixed with `-` for descending (e.g. `-id`). Supported fields: `id`, `name`.", "type": "string" } }, "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "pagination": { "oneOf": [ { "$ref": "#/components/schemas/PaginationOutput" }, { "$ref": "#/components/schemas/Null" } ] }, "sorting": { "oneOf": [ { "$ref": "#/components/schemas/Sorting" }, { "$ref": "#/components/schemas/Null" } ] }, "status": { "enum": [ "success" ], "example": "success", "type": "string" }, "summaries": { "items": { "$ref": "#/components/schemas/Environment_Summary" }, "type": "array" } }, "required": [ "pagination", "sorting", "status", "summaries" ], "type": "object" } }, "summary": "List environments for an account" }, { "description": null, "name": "environments/show", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "environment_id": { "$ref": "#/components/schemas/Environment_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "environment_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/Environment_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Fetch environment" }, { "description": null, "name": "environments/update", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "details": { "$ref": "#/components/schemas/Environment_DetailsForUpdate" }, "environment_id": { "$ref": "#/components/schemas/Environment_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "details", "environment_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/Environment_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Update an environment" }, { "description": null, "name": "llm_provider_models/create", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "details": { "$ref": "#/components/schemas/LlmProviderModel_DetailsForCreate" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "details" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/LlmProviderModel_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Create a new LLM provider model" }, { "description": null, "name": "llm_provider_models/delete", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "llm_provider_model_id": { "$ref": "#/components/schemas/LlmProviderModel_Id" } }, "required": [ "llm_provider_model_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/LlmProviderModel_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Delete an LLM provider model" }, { "description": null, "name": "llm_provider_models/list", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "llm_provider_id": { "$ref": "#/components/schemas/LlmProvider_Id" }, "pagination": { "properties": { "offset": { "minimum": 0, "type": "integer" }, "page_size": { "maximum": 100, "minimum": 1, "type": "integer" } }, "type": "object" }, "sorting": { "description": "Sort order; a field name, optionally prefixed with `-` for descending (e.g. `-id`). Supported fields: `id`, `name`.", "type": "string" } }, "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "pagination": { "oneOf": [ { "$ref": "#/components/schemas/PaginationOutput" }, { "$ref": "#/components/schemas/Null" } ] }, "sorting": { "oneOf": [ { "$ref": "#/components/schemas/Sorting" }, { "$ref": "#/components/schemas/Null" } ] }, "status": { "enum": [ "success" ], "example": "success", "type": "string" }, "summaries": { "items": { "$ref": "#/components/schemas/LlmProviderModel_Summary" }, "type": "array" } }, "required": [ "pagination", "sorting", "status", "summaries" ], "type": "object" } }, "summary": "List LLM provider models for a provider" }, { "description": null, "name": "llm_provider_models/show", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "llm_provider_model_id": { "$ref": "#/components/schemas/LlmProviderModel_Id" } }, "required": [ "llm_provider_model_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/LlmProviderModel_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Fetch LLM provider model" }, { "description": null, "name": "llm_provider_models/update", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "details": { "$ref": "#/components/schemas/LlmProviderModel_DetailsForUpdate" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "llm_provider_model_id": { "$ref": "#/components/schemas/LlmProviderModel_Id" } }, "required": [ "details", "llm_provider_model_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/LlmProviderModel_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Update an LLM provider model" }, { "description": null, "name": "llm_providers/create", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "details": { "$ref": "#/components/schemas/LlmProvider_DetailsForCreate" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "details" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/LlmProvider_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Create a new LLM provider" }, { "description": null, "name": "llm_providers/delete", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "llm_provider_id": { "$ref": "#/components/schemas/LlmProvider_Id" } }, "required": [ "llm_provider_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/LlmProvider_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Delete an LLM provider" }, { "description": null, "name": "llm_providers/list", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "pagination": { "properties": { "offset": { "minimum": 0, "type": "integer" }, "page_size": { "maximum": 100, "minimum": 1, "type": "integer" } }, "type": "object" }, "sorting": { "description": "Sort order; a field name, optionally prefixed with `-` for descending (e.g. `-id`). Supported fields: `id`, `name`.", "type": "string" } }, "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "pagination": { "oneOf": [ { "$ref": "#/components/schemas/PaginationOutput" }, { "$ref": "#/components/schemas/Null" } ] }, "sorting": { "oneOf": [ { "$ref": "#/components/schemas/Sorting" }, { "$ref": "#/components/schemas/Null" } ] }, "status": { "enum": [ "success" ], "example": "success", "type": "string" }, "summaries": { "items": { "$ref": "#/components/schemas/LlmProvider_Summary" }, "type": "array" } }, "required": [ "pagination", "sorting", "status", "summaries" ], "type": "object" } }, "summary": "List LLM providers for an account" }, { "description": null, "name": "llm_providers/show", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "llm_provider_id": { "$ref": "#/components/schemas/LlmProvider_Id" } }, "required": [ "llm_provider_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/LlmProvider_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Fetch LLM provider" }, { "description": null, "name": "llm_providers/update", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "details": { "$ref": "#/components/schemas/LlmProvider_DetailsForUpdate" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "llm_provider_id": { "$ref": "#/components/schemas/LlmProvider_Id" } }, "required": [ "details", "llm_provider_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/LlmProvider_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Update an LLM provider" }, { "description": null, "name": "people/create", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "details": { "$ref": "#/components/schemas/Person_ForCreate" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "details" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/Person_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Create a new person" }, { "description": null, "name": "people/delete", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "person_id": { "$ref": "#/components/schemas/Person_Id" } }, "required": [ "person_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/Person_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Delete a person" }, { "description": null, "name": "people/list", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "pagination": { "properties": { "offset": { "minimum": 0, "type": "integer" }, "page_size": { "maximum": 100, "minimum": 1, "type": "integer" } }, "type": "object" }, "sorting": { "description": "Sort order; a field name, optionally prefixed with `-` for descending (e.g. `-id`). Supported fields: `id`, `name`, `email`.", "type": "string" }, "team_id": { "description": "When a team id, return only people on that team. When `null`, return only people with no team. When omitted, return all people (after permission filtering).", "oneOf": [ { "$ref": "#/components/schemas/Team_Id" }, { "$ref": "#/components/schemas/Null" } ] } }, "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "pagination": { "oneOf": [ { "$ref": "#/components/schemas/PaginationOutput" }, { "$ref": "#/components/schemas/Null" } ] }, "sorting": { "oneOf": [ { "$ref": "#/components/schemas/Sorting" }, { "$ref": "#/components/schemas/Null" } ] }, "status": { "enum": [ "success" ], "example": "success", "type": "string" }, "summaries": { "items": { "$ref": "#/components/schemas/Person_Summary" }, "type": "array" } }, "required": [ "pagination", "sorting", "status", "summaries" ], "type": "object" } }, "summary": "List people" }, { "description": null, "name": "people/show", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "person_id": { "$ref": "#/components/schemas/Person_Id" } }, "required": [ "person_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/Person_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Get person details" }, { "description": null, "name": "people/update", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "details": { "$ref": "#/components/schemas/Person_ForUpdate" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "person_id": { "$ref": "#/components/schemas/Person_Id" } }, "required": [ "details", "person_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/Person_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Update a person" }, { "description": null, "name": "pfid/generate", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "count": { "description": "Number of PFIDs to generate", "minimum": 1, "type": "integer" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "count" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "account_id": { "$ref": "#/components/schemas/Account_Id" }, "pfids": { "description": "Generated PFIDs with matching partition", "items": { "example": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "type": "string" }, "type": "array" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "account_id", "pfids", "status" ], "type": "object" } }, "summary": "Generate new PFIDs with a partition matching the account" }, { "description": null, "name": "ping", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "properties": { "account_id": { "description": "Account ID", "example": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "type": "string" }, "admin_user_id": { "description": "Admin user ID", "example": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "type": "string" }, "agent_deployment_id": { "description": "Agent deployment ID", "example": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "type": "string" }, "agent_id": { "description": "Agent ID", "example": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "type": "string" }, "api_token_id": { "description": "API token ID", "example": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "type": "string" }, "environment_id": { "description": "Environment ID", "example": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "type": "string" }, "superadmin_user_id": { "description": "Superadmin user ID", "example": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "type": "string" }, "token_type": { "description": "Auth token type", "type": "string" } }, "required": [ "token_type" ], "type": "object" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Return minimal details for the current token" }, { "description": null, "name": "playground/create_customer_support_agent", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "agent": { "$ref": "#/components/schemas/Agent_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "agent", "status" ], "type": "object" } }, "summary": "Create a customer support demo agent" }, { "description": null, "name": "playground/create_first_account_agent", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "environment_id": { "description": "Environment for sample instances. Required when seed_instances_and_spans is true.", "oneOf": [ { "$ref": "#/components/schemas/Environment_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "seed_instances_and_spans": { "default": false, "description": "When true, register and record all five sample scenarios in environment_id. Defaults to false.", "type": "boolean" } }, "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "agent": { "$ref": "#/components/schemas/Agent_Details" }, "agent_instance_ids": { "items": { "$ref": "#/components/schemas/AgentInstance_Id" }, "type": "array" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "agent", "agent_instance_ids", "status" ], "type": "object" } }, "summary": "Create the first-account sample Support Chatbot agent" }, { "description": null, "name": "playground/create_loan_application_review_agent", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "agent": { "$ref": "#/components/schemas/Agent_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "agent", "status" ], "type": "object" } }, "summary": "Create a loan application review playground agent" }, { "description": null, "name": "playground/create_northstar_support_agent", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "agent": { "$ref": "#/components/schemas/Agent_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "agent", "status" ], "type": "object" } }, "summary": "Create a Northstar support sensitive playground agent" }, { "description": null, "name": "playground/create_openclaw_agent", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "agent": { "$ref": "#/components/schemas/Agent_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "agent", "status" ], "type": "object" } }, "summary": "Create an OpenClaw demo agent" }, { "description": null, "name": "playground/create_quality_review_agent", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "agent": { "$ref": "#/components/schemas/Agent_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "agent", "status" ], "type": "object" } }, "summary": "Create an article summary quality playground agent" }, { "description": null, "name": "playground/record_customer_support_spans", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_instance_id": { "$ref": "#/components/schemas/AgentInstance_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "agent_instance_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "ids": { "items": { "$ref": "#/components/schemas/AgentSpan_Id" }, "type": "array" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "ids", "status" ], "type": "object" } }, "summary": "Record a canned multi-span support conversation on an instance" }, { "description": null, "name": "playground/record_first_account_spans", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_instance_id": { "$ref": "#/components/schemas/AgentInstance_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "scenario": { "description": "Which sample run to record: good, mixed, bad, timeout, or active. Must match register.", "enum": [ "good", "mixed", "bad", "timeout", "active" ], "example": "good", "type": "string" } }, "required": [ "scenario", "agent_instance_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "ids": { "items": { "$ref": "#/components/schemas/AgentSpan_Id" }, "type": "array" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "ids", "status" ], "type": "object" } }, "summary": "Record first-account sample spans for a playground scenario" }, { "description": null, "name": "playground/record_loan_application_review_spans", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_instance_id": { "$ref": "#/components/schemas/AgentInstance_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "agent_instance_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "ids": { "items": { "$ref": "#/components/schemas/AgentSpan_Id" }, "type": "array" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "ids", "status" ], "type": "object" } }, "summary": "Record loan application review playground spans on an instance" }, { "description": null, "name": "playground/record_northstar_support_spans", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_instance_id": { "$ref": "#/components/schemas/AgentInstance_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "agent_instance_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "ids": { "items": { "$ref": "#/components/schemas/AgentSpan_Id" }, "type": "array" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "ids", "status" ], "type": "object" } }, "summary": "Record Northstar support sensitive playground spans, quality payloads, and alerts on an instance" }, { "description": null, "name": "playground/record_openclaw_spans", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_instance_id": { "$ref": "#/components/schemas/AgentInstance_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "agent_instance_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "ids": { "items": { "$ref": "#/components/schemas/AgentSpan_Id" }, "type": "array" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "ids", "status" ], "type": "object" } }, "summary": "Record a canned OpenClaw conversation on an instance" }, { "description": null, "name": "playground/record_quality_review_spans", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_instance_id": { "$ref": "#/components/schemas/AgentInstance_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "agent_instance_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "ids": { "items": { "$ref": "#/components/schemas/AgentSpan_Id" }, "type": "array" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "ids", "status" ], "type": "object" } }, "summary": "Record article summary quality playground spans and set the instance quality payloads" }, { "description": null, "name": "playground/register_customer_support_agent_instance", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "environment_id": { "$ref": "#/components/schemas/Environment_Id" }, "id": { "description": "Optional instance id. Its embedded timestamp must not be more than 7 days in the past.", "oneOf": [ { "$ref": "#/components/schemas/AgentInstance_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "environment_id", "agent_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "agent_schema_version": { "$ref": "#/components/schemas/AgentSchemaVersion_Details" }, "agent_version": { "$ref": "#/components/schemas/AgentVersion_Details" }, "details": { "$ref": "#/components/schemas/AgentInstance_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "agent_schema_version", "agent_version", "details", "status" ], "type": "object" } }, "summary": "Register a customer support demo agent instance with support-copilot span schemas" }, { "description": null, "name": "playground/register_first_account_agent_instance", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "environment_id": { "$ref": "#/components/schemas/Environment_Id" }, "id": { "description": "Optional instance id. Its embedded timestamp must not be more than 7 days in the past.", "oneOf": [ { "$ref": "#/components/schemas/AgentInstance_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "scenario": { "description": "Which sample run to register: good, mixed, bad, timeout, or active.", "enum": [ "good", "mixed", "bad", "timeout", "active" ], "example": "good", "type": "string" } }, "required": [ "scenario", "environment_id", "agent_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "agent_schema_version": { "$ref": "#/components/schemas/AgentSchemaVersion_Details" }, "agent_version": { "$ref": "#/components/schemas/AgentVersion_Details" }, "details": { "$ref": "#/components/schemas/AgentInstance_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "agent_schema_version", "agent_version", "details", "status" ], "type": "object" } }, "summary": "Register a first-account sample agent instance for a playground scenario" }, { "description": null, "name": "playground/register_loan_application_review_agent_instance", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "environment_id": { "$ref": "#/components/schemas/Environment_Id" }, "id": { "description": "Optional instance id. Its embedded timestamp must not be more than 7 days in the past.", "oneOf": [ { "$ref": "#/components/schemas/AgentInstance_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "environment_id", "agent_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "agent_schema_version": { "$ref": "#/components/schemas/AgentSchemaVersion_Details" }, "agent_version": { "$ref": "#/components/schemas/AgentVersion_Details" }, "details": { "$ref": "#/components/schemas/AgentInstance_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "agent_schema_version", "agent_version", "details", "status" ], "type": "object" } }, "summary": "Register a loan application review playground agent instance with demo span schemas" }, { "description": null, "name": "playground/register_northstar_support_agent_instance", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "environment_id": { "$ref": "#/components/schemas/Environment_Id" }, "id": { "description": "Optional instance id. Its embedded timestamp must not be more than 7 days in the past.", "oneOf": [ { "$ref": "#/components/schemas/AgentInstance_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "environment_id", "agent_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "agent_schema_version": { "$ref": "#/components/schemas/AgentSchemaVersion_Details" }, "agent_version": { "$ref": "#/components/schemas/AgentVersion_Details" }, "details": { "$ref": "#/components/schemas/AgentInstance_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "agent_schema_version", "agent_version", "details", "status" ], "type": "object" } }, "summary": "Register a Northstar support sensitive playground agent instance with demo span schemas" }, { "description": null, "name": "playground/register_openclaw_agent_instance", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "environment_id": { "$ref": "#/components/schemas/Environment_Id" }, "id": { "description": "Optional instance id. Its embedded timestamp must not be more than 7 days in the past.", "oneOf": [ { "$ref": "#/components/schemas/AgentInstance_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "environment_id", "agent_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "agent_schema_version": { "$ref": "#/components/schemas/AgentSchemaVersion_Details" }, "agent_version": { "$ref": "#/components/schemas/AgentVersion_Details" }, "details": { "$ref": "#/components/schemas/AgentInstance_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "agent_schema_version", "agent_version", "details", "status" ], "type": "object" } }, "summary": "Register an OpenClaw demo agent instance with openclaw span schemas" }, { "description": null, "name": "playground/register_quality_review_agent_instance", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_id": { "$ref": "#/components/schemas/Agent_Id" }, "environment_id": { "$ref": "#/components/schemas/Environment_Id" }, "id": { "description": "Optional instance id. Its embedded timestamp must not be more than 7 days in the past.", "oneOf": [ { "$ref": "#/components/schemas/AgentInstance_Id" }, { "$ref": "#/components/schemas/Null" } ] }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "purpose": { "default": "live", "description": "Why this instance ran: 'live' for an actual agent run, 'smoke_test' for a pipeline check, or 'eval' for an evaluation run. Defaults to 'live'.", "enum": [ "live", "smoke_test", "eval" ], "example": "live", "type": "string" } }, "required": [ "environment_id", "agent_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "agent_schema_version": { "$ref": "#/components/schemas/AgentSchemaVersion_Details" }, "agent_version": { "$ref": "#/components/schemas/AgentVersion_Details" }, "details": { "$ref": "#/components/schemas/AgentInstance_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "agent_schema_version", "agent_version", "details", "status" ], "type": "object" } }, "summary": "Register an article summary quality playground agent instance with demo span and quality schemas" }, { "description": null, "name": "risk_profiles/create", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "details": { "$ref": "#/components/schemas/RiskProfile_ForCreate" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "details" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/RiskProfile_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Create a new risk profile" }, { "description": null, "name": "risk_profiles/delete", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "risk_profile_id": { "$ref": "#/components/schemas/RiskProfile_Id" } }, "required": [ "risk_profile_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/RiskProfile_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Delete a risk profile" }, { "description": null, "name": "risk_profiles/list", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "pagination": { "properties": { "offset": { "minimum": 0, "type": "integer" }, "page_size": { "maximum": 100, "minimum": 1, "type": "integer" } }, "type": "object" }, "sorting": { "description": "Sort order; a field name, optionally prefixed with `-` for descending (e.g. `-id`). Supported fields: `id`, `name`.", "type": "string" } }, "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "pagination": { "oneOf": [ { "$ref": "#/components/schemas/PaginationOutput" }, { "$ref": "#/components/schemas/Null" } ] }, "sorting": { "oneOf": [ { "$ref": "#/components/schemas/Sorting" }, { "$ref": "#/components/schemas/Null" } ] }, "status": { "enum": [ "success" ], "example": "success", "type": "string" }, "summaries": { "items": { "$ref": "#/components/schemas/RiskProfile_Summary" }, "type": "array" } }, "required": [ "pagination", "sorting", "status", "summaries" ], "type": "object" } }, "summary": "List risk profiles" }, { "description": null, "name": "risk_profiles/show", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "risk_profile_id": { "$ref": "#/components/schemas/RiskProfile_Id" } }, "required": [ "risk_profile_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/RiskProfile_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Get risk profile details" }, { "description": null, "name": "risk_profiles/template_ruleset", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "template_name": { "description": "Template name (e.g. Permissive, Standard, Financial, Healthcare, Maximum)", "type": "string" } }, "required": [ "template_name" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "ruleset": { "$ref": "#/components/schemas/RiskProfile_Ruleset" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "ruleset", "status" ], "type": "object" } }, "summary": "Get risk profile template ruleset" }, { "description": null, "name": "risk_profiles/update", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "details": { "$ref": "#/components/schemas/RiskProfile_ForUpdate" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "risk_profile_id": { "$ref": "#/components/schemas/RiskProfile_Id" } }, "required": [ "details", "risk_profile_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/RiskProfile_Details" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Update a risk profile" }, { "description": null, "name": "teams/create", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "details": { "$ref": "#/components/schemas/Team_ForCreate" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "details" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/Team_Details" }, "status": { "description": "Response status when the operation succeeds", "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Create a new team" }, { "description": null, "name": "teams/delete", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "team_id": { "$ref": "#/components/schemas/Team_Id" } }, "required": [ "team_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/Team_Details" }, "status": { "description": "Response status when the operation succeeds", "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Delete a team" }, { "description": null, "name": "teams/list", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "pagination": { "properties": { "offset": { "minimum": 0, "type": "integer" }, "page_size": { "maximum": 100, "minimum": 1, "type": "integer" } }, "type": "object" }, "sorting": { "description": "Sort order; a field name, optionally prefixed with `-` for descending (e.g. `-id`). Supported fields: `id`, `name`.", "type": "string" } }, "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "pagination": { "description": "Pagination metadata when the request included pagination parameters (null when the full list is returned)", "oneOf": [ { "$ref": "#/components/schemas/PaginationOutput" }, { "$ref": "#/components/schemas/Null" } ] }, "sorting": { "oneOf": [ { "$ref": "#/components/schemas/Sorting" }, { "$ref": "#/components/schemas/Null" } ] }, "status": { "description": "Response status when the query succeeds", "enum": [ "success" ], "example": "success", "type": "string" }, "summaries": { "description": "Teams visible to the caller for this account", "items": { "$ref": "#/components/schemas/Team_Summary" }, "type": "array" } }, "required": [ "pagination", "sorting", "status", "summaries" ], "type": "object" } }, "summary": "List teams" }, { "description": null, "name": "teams/show", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "team_id": { "$ref": "#/components/schemas/Team_Id" } }, "required": [ "team_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/Team_Details" }, "status": { "description": "Response status when the query succeeds", "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Get team details" }, { "description": null, "name": "teams/update", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "details": { "$ref": "#/components/schemas/Team_ForUpdate" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" }, "team_id": { "$ref": "#/components/schemas/Team_Id" } }, "required": [ "details", "team_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "details": { "$ref": "#/components/schemas/Team_Details" }, "status": { "description": "Response status when the operation succeeds", "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } }, "summary": "Update a team" }, { "description": "Execute multiple API queries and actions in a single HTTP request. This endpoint allows you to batch multiple operations together, reducing the number of round trips to the API.\n\n**Key Features:**\n- Each item in the request is processed independently in its own database transaction\n- Processing stops early if any item returns an error\n- All successfully processed items up to the error are returned\n- Any unprocessed items (after the first error) are excluded from the result\n- All items must include a unique `idempotency_key` (8–128 characters)\n- Results are returned as a map keyed by `idempotency_key`\n- Each item can be a different type of query or action (e.g., list agents, create agent, show agent)\n\n**Supported Types:**\n- `agents/list` - List agents for the account (no extra parameters beyond `idempotency_key`)\n- `agents/show` - Get agent details (requires `agent_id`)\n- `agents/create` - Create a new agent (requires `details` with `name`, optional `description`)\n- `agents/update` - Update an agent (requires `agent_id` and `details`)\n- `environments/list` - List environments for an account (requires `account_id`)\n- `environments/show` - Get environment details (requires `environment_id`)\n- `environments/create` - Create a new environment (requires `details` with `account_id`, `name`)\n- `environments/update` - Update an environment (requires `environment_id` and `details`)\n- `llm_providers/list` - List LLM providers for an account (requires `account_id`)\n- `llm_providers/show` - Get LLM provider details (requires `llm_provider_id`)\n- `llm_providers/create` - Create a new LLM provider (requires `details` with `account_id`, `name`, `provider`, `api_key`; `custom_openai` also requires `api_base_url`)\n- `llm_providers/update` - Update an LLM provider (requires `llm_provider_id` and `details`)\n- `llm_providers/delete` - Delete an LLM provider (requires `llm_provider_id`)\n- `llm_provider_models/list` - List LLM provider models for a provider (requires `llm_provider_id`)\n- `llm_provider_models/show` - Get LLM provider model details (requires `llm_provider_model_id`)\n- `llm_provider_models/create` - Create a new LLM provider model (requires `details` with `llm_provider_id`, `api_name`; models for `custom_openai` also require `name`)\n- `llm_provider_models/update` - Update an LLM provider model (requires `llm_provider_model_id` and `details`)\n- `llm_provider_models/delete` - Delete an LLM provider model (requires `llm_provider_model_id`)\n- And other query/action types as documented in their respective endpoints\n\n**Example Request:**\n```json\n{\n \"items\": [\n {\n \"_type\": \"agents/list\",\n \"idempotency_key\": \"list-agents-2024-01-15-001\"\n },\n {\n \"_type\": \"agents/create\",\n \"idempotency_key\": \"create-agent-2024-01-15-002\",\n \"details\": {\n \"name\": \"Customer Support Bot\",\n \"description\": \"Handles customer support inquiries\"\n }\n },\n {\n \"_type\": \"agents/show\",\n \"idempotency_key\": \"show-agent-2024-01-15-003\",\n \"agent_id\": \"agent_xyz789\"\n }\n ]\n}\n```\n\n**Example Response:**\n```json\n{\n \"status\": \"success\",\n \"outputs\": {\n \"list-agents-2024-01-15-001\": {\n \"status\": \"success\",\n \"summaries\": [...]\n },\n \"create-agent-2024-01-15-002\": {\n \"status\": \"success\",\n \"details\": {\n \"type\": \"agent\",\n \"id\": \"agent_new123\",\n \"name\": \"Customer Support Bot\",\n \"description\": \"Handles customer support inquiries\",\n \"inserted_at\": \"2024-01-15T10:30:00Z\",\n \"updated_at\": \"2024-01-15T10:30:00Z\"\n }\n },\n \"show-agent-2024-01-15-003\": {\n \"status\": \"success\",\n \"details\": {...}\n }\n }\n}\n```\n", "name": "bulk/execute", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "description": "Request body for bulk query/action operations. Allows executing multiple API operations in a single request. Each item runs in its own transaction, processing stops at the first error, and any items after the failing item are omitted from the response.", "example": { "items": [ { "_type": "agents/list", "idempotency_key": "list-agents-2024-01-15-001" }, { "_type": "agents/create", "details": { "description": "Handles customer support inquiries", "name": "Customer Support Bot" }, "idempotency_key": "create-agent-2024-01-15-002" }, { "_type": "agents/show", "agent_id": "agent_xyz789ghi012", "idempotency_key": "show-agent-2024-01-15-003" } ] }, "properties": { "items": { "description": "List of items to process in bulk. Each item is processed sequentially in its own database transaction. Processing stops immediately on the first error: the failing item is included in the response as an error entry, and any items after it are not processed and are omitted from the response.", "items": { "additionalProperties": true, "description": "A single item in a bulk request. Each item must include `_type` and `idempotency_key`, plus any additional parameters required by the specific query/action type (e.g., `details` for agents/create, `agent_id` for agents/show).", "example": { "_type": "agents/create", "details": { "description": "Handles customer support inquiries", "name": "Customer Support Bot" }, "idempotency_key": "create-agent-2024-01-15-001" }, "properties": { "_type": { "description": "The type of query/action to execute (e.g., 'agents/list', 'agents/create')", "example": "agents/list", "title": "Type", "type": "string" }, "idempotency_key": { "description": "Required unique idempotency key for this item. Must be 8–128 characters and unique within the request. Used to identify the result in the response map.", "example": "create-agent-2024-01-15-001", "maxLength": 128, "minLength": 8, "title": "IdempotencyKey", "type": "string" } }, "required": [ "_type", "idempotency_key" ], "title": "BulkItem", "type": "object" }, "minItems": 1, "title": "Items", "type": "array" } }, "required": [ "items" ], "title": "BulkRequest", "type": "object" } } ], "result": { "name": "result", "schema": { "description": "Response from bulk query/action operations. Contains a map of results keyed by the idempotency_key from each request item. Processing stops on the first error, so the map includes successful items up to the error plus an error entry for the failing item; items after the failing item are omitted because they were not processed.", "example": { "outputs": { "create-agent-2024-01-15-002": { "code": "bad_request", "message": "Invalid agent details", "status": "error" }, "list-agents-2024-01-15-001": { "status": "success", "summaries": [ { "environment_id": "env_abc123def456", "id": "agent_xyz789ghi012", "name": "Existing Agent", "type": "agent" } ] } }, "status": "success" }, "properties": { "outputs": { "additionalProperties": { "additionalProperties": true, "description": "Output from a query or action. Contains either a success response (with 'status': 'success' and operation-specific data) or an error response (with 'status': 'error', 'code', 'message', and optionally 'errors').", "properties": {}, "title": "Output", "type": "object" }, "description": "Map where keys are the idempotency_key values from the request, and values are the corresponding query/action outputs or error responses. Each item is executed in its own transaction and processing stops immediately on the first error: outputs include successful items up to the error plus an error entry for the failing idempotency_key, and items after the failing item are not processed and are omitted from this map.", "title": "Outputs", "type": "object" }, "status": { "description": "Response status, always 'success' when the request is processed", "enum": [ "success" ], "example": "success", "title": "Status", "type": "string" } }, "required": [ "outputs", "status" ], "title": "BulkResponse", "type": "object" } }, "summary": "Execute multiple queries/actions in a single request" }, { "description": "Checks access and returns refs; the WebSocket handler subscribes to those refs. Rejected by HTTP bulk API.", "name": "agent_instances/subscribe", "paramStructure": "by-name", "params": [ { "name": "params", "required": true, "schema": { "properties": { "agent_instance_id": { "$ref": "#/components/schemas/AgentInstance_Id" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKeyOrNull" } }, "required": [ "agent_instance_id" ], "type": "object" } } ], "result": { "name": "result", "schema": { "properties": { "refs": { "description": "Refs subscribed for PubSub updates", "items": { "properties": { "id": { "description": "Resource id", "example": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "type": "string" }, "type": { "description": "Resource type", "example": "agent_instance", "type": "string" } }, "required": [ "id", "type" ], "title": "SubscriptionRef", "type": "object" }, "type": "array" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "refs", "status" ], "type": "object" } }, "summary": "Subscribe to agent instance data-change notifications (WebSocket only)" }, { "description": "JSON-RPC notification (no `id`). Params match the successful notification payload.", "name": "agent_instances/deleted", "params": [ { "name": "params", "required": true, "schema": { "properties": { "id": "Elixir.Prefactor.ApiInternal.SharedSchema.AgentInstanceId", "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "id", "status" ], "type": "object" } } ], "summary": "Server notification: Delete" }, { "description": "JSON-RPC notification (no `id`). Params match the successful notification payload.", "name": "agent_instances/inserted", "params": [ { "name": "params", "required": true, "schema": { "properties": { "details": "Elixir.Prefactor.Api.Types.AgentInstance.Details", "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } } ], "summary": "Server notification: Insert" }, { "description": "JSON-RPC notification (no `id`). Params match the successful notification payload.", "name": "agent_instances/updated", "params": [ { "name": "params", "required": true, "schema": { "properties": { "details": "Elixir.Prefactor.Api.Types.AgentInstance.Details", "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "details", "status" ], "type": "object" } } ], "summary": "Server notification: Update" }, { "description": "JSON-RPC notification (no `id`). Sent before the server closes the connection with code 1008.", "name": "error", "params": [ { "name": "params", "required": true, "schema": { "description": "An error response from the API. The conflict status code means another request updated the record. The client may retry.", "oneOf": [ { "properties": { "code": { "enum": [ "bad_request", "bad_authtoken", "not_authenticated", "not_permitted", "not_implemented", "unknown", "not_found", "unexpected_ref_type", "unexpected", "invalid_action", "alert_unknown", "alert_already_cleared", "invalid_value", "required_value", "idempotency_key_already_used", "temporarily_unavailable", "conflict" ], "example": "bad_request", "type": "string" }, "message": { "type": "string" }, "status": { "enum": [ "error" ], "example": "error", "type": "string" } }, "required": [ "code", "message", "status" ], "type": "object" }, { "properties": { "code": { "enum": [ "validation_errors" ], "example": "validation_errors", "type": "string" }, "errors": { "additionalProperties": "Elixir.Prefactor.Api.ApiError", "type": "object" }, "message": { "type": "string" }, "status": { "enum": [ "error" ], "example": "error", "type": "string" } }, "required": [ "code", "errors", "message", "status" ], "type": "object" }, { "properties": { "code": { "enum": [ "rate_limited" ], "example": "rate_limited", "type": "string" }, "message": { "type": "string" }, "retry_after_ms": { "description": "Milliseconds until the client may retry.", "minimum": 0, "type": "integer" }, "status": { "enum": [ "error" ], "example": "error", "type": "string" } }, "required": [ "code", "message", "retry_after_ms", "status" ], "type": "object" } ], "title": "ApiError" } } ], "summary": "Server-pushed error before connection close (e.g. token invalidated)" } ], "openrpc": "1.3.0", "servers": [ { "description": "WebSocket endpoint; send JSON-RPC frames as text messages.", "name": "websocket", "url": "wss://app.prefactorai.com/api/v1/ws" } ] }