diff --git a/specs/platform-openapi.json b/specs/platform-openapi.json index c336389..3d1bc0d 100644 --- a/specs/platform-openapi.json +++ b/specs/platform-openapi.json @@ -250,37 +250,206 @@ ], "type": "object" }, - "Actor": { - "description": "Schema for a message actor (user or agent).\n\nActors represent the entity that sent a message.\nMaps to the actor format from MessageActorHelper.build_actor/1.\n", + "ActivityFeedEntry": { + "description": "API schema for an activity feed entry.", "properties": { - "alias": { - "description": "Actor alias/handle", - "type": "string" + "agent": { + "description": "Agent (public ID or expanded object when loaded)", + "oneOf": [ + { + "type": "string" + }, + { + "description": "API schema for an agent.", + "properties": { + "acl": { + "description": "Access control list. Contains grants array with principal_type, principal, and actions. Null when no ACL restrictions are applied.", + "properties": { + "add": { + "description": "Patch mode: grants to add or merge into existing", + "items": { + "description": "API schema for a single ACL grant entry.", + "properties": { + "actions": { + "description": "List of allowed actions (e.g. read, write)", + "items": { + "type": "string" + }, + "type": "array" + }, + "principal": { + "description": "Principal identifier (UUID for user/team/org/agent_user, role name for org_role, omit for everyone)", + "type": "string" + }, + "principal_type": { + "description": "Principal type: user, team, org, org_role, agent, or everyone", + "type": "string" + } + }, + "required": [ + "principal_type", + "actions" + ], + "type": "object" + }, + "type": "array" + }, + "grants": { + "description": "Replace mode: full list of grants (replaces all existing). Use [] to clear.", + "items": { + "description": "API schema for a single ACL grant entry.", + "properties": { + "actions": { + "description": "List of allowed actions (e.g. read, write)", + "items": { + "type": "string" + }, + "type": "array" + }, + "principal": { + "description": "Principal identifier (UUID for user/team/org/agent_user, role name for org_role, omit for everyone)", + "type": "string" + }, + "principal_type": { + "description": "Principal type: user, team, org, org_role, agent, or everyone", + "type": "string" + } + }, + "required": [ + "principal_type", + "actions" + ], + "type": "object" + }, + "type": "array" + }, + "remove": { + "description": "Patch mode: principals to remove from existing", + "items": { + "description": "API schema for identifying a principal to remove from an ACL.", + "properties": { + "principal": { + "description": "Principal identifier to remove (omit for everyone)", + "type": "string" + }, + "principal_type": { + "description": "Principal type to remove", + "type": "string" + } + }, + "required": [ + "principal_type" + ], + "type": "object" + }, + "type": "array" + } + }, + "type": "object" + }, + "app": { + "description": "Application", + "type": "string" + }, + "created_at": { + "description": "Creation timestamp", + "format": "date-time", + "type": "string" + }, + "default_model": { + "description": "Default AI model", + "type": "string" + }, + "email": { + "description": "Agent email", + "type": "string" + }, + "id": { + "description": "Agent ID (agi_...)", + "type": "string" + }, + "identity": { + "description": "Identity prompt", + "type": "string" + }, + "last_applied_template_config": { + "description": "Config id of the AgentTemplate this agent was last provisioned/updated from", + "type": "string" + }, + "lookup_key": { + "description": "Unique lookup key", + "type": "string" + }, + "metadata": { + "description": "Arbitrary metadata", + "type": "object" + }, + "name": { + "description": "Agent name", + "type": "string" + }, + "org": { + "description": "Organization", + "type": "string" + }, + "org_name": { + "description": "Organization display name. Null when the agent is not in an org, or when the org association was not preloaded by the caller.", + "type": "string" + }, + "originator": { + "description": "Free-form source or author of the agent", + "type": "string" + }, + "phone_number": { + "description": "Agent phone number", + "type": "string" + }, + "sandbox": { + "description": "Sandbox", + "type": "string" + }, + "team": { + "description": "Owning team", + "type": "string" + }, + "updated_at": { + "description": "Last update timestamp", + "format": "date-time", + "type": "string" + }, + "user": { + "description": "Owning user", + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + } + ] }, - "id": { - "description": "Actor ID (format: user-xxx or agent-xxx)", + "app": { + "description": "Application", "type": "string" }, - "name": { - "description": "Actor display name", + "attachments": { + "description": "Entry attachments", + "items": { + "type": "object" + }, + "type": "array" + }, + "automation_run": { + "description": "Automation run", "type": "string" }, - "profile_picture": { - "$ref": "#/components/schemas/ImageSource", - "description": "Profile picture" - } - }, - "type": "object" - }, - "Agent": { - "description": "API schema for an agent.", - "properties": { - "acl": { - "$ref": "#/components/schemas/Acl", - "description": "Access control list. Contains grants array with principal_type, principal, and actions. Null when no ACL restrictions are applied." + "content": { + "description": "Longer explanation (markdown)", + "type": "string" }, - "app": { - "description": "Application", + "correlation_id": { + "description": "Correlation ID for grouped entries", "type": "string" }, "created_at": { @@ -288,126 +457,107 @@ "format": "date-time", "type": "string" }, - "default_model": { - "description": "Default AI model", - "type": "string" - }, - "email": { - "description": "Agent email", - "type": "string" - }, "id": { - "description": "Agent ID (agi_...)", + "description": "Entry ID (afe_...)", "type": "string" }, - "identity": { - "description": "Identity prompt", + "kind": { + "description": "Entry kind", "type": "string" }, - "lookup_key": { - "description": "Unique lookup key", + "level": { + "description": "Severity level", "type": "string" }, "metadata": { - "description": "Arbitrary metadata", + "description": "Entry metadata", "type": "object" }, - "name": { - "description": "Agent name", - "type": "string" - }, "org": { "description": "Organization", "type": "string" }, - "phone_number": { - "description": "Agent phone number", + "routine_run": { + "description": "Routine run", "type": "string" }, "sandbox": { - "description": "Sandbox", - "type": "string" - }, - "team": { - "description": "Owning team", - "type": "string" - }, - "updated_at": { - "description": "Last update timestamp", - "format": "date-time", - "type": "string" - }, - "user": { - "description": "Owning user", - "type": "string" - } - }, - "required": [ - "id" - ], - "type": "object" - }, - "AgentComputer": { - "description": "API schema for an agent computer.", - "properties": { - "agent": { - "description": "Owning agent", + "description": "Sandbox identifier", "type": "string" }, - "app": { - "description": "Application ID", + "session_record": { + "description": "Agent session", "type": "string" }, - "config": { - "description": "Configuration", - "type": "object" - }, - "created_at": { - "description": "Creation timestamp", - "format": "date-time", + "team": { + "description": "Team", "type": "string" }, - "error_message": { - "description": "Error message", + "thread": { + "description": "Thread", "type": "string" }, - "id": { - "description": "Computer ID (cmp_...)", + "title": { + "description": "One-line summary", "type": "string" }, - "last_active_at": { - "description": "Last active timestamp", + "updated_at": { + "description": "Last update timestamp", "format": "date-time", "type": "string" }, - "lookup_key": { - "description": "Unique lookup key", - "type": "string" - }, - "metadata": { - "description": "Arbitrary metadata", - "type": "object" - }, - "name": { - "description": "Computer name", - "type": "string" - }, - "region": { - "description": "Region", - "type": "string" - }, - "sprite_url": { - "description": "Sprite URL", - "type": "string" - }, - "status": { - "description": "Computer status", - "type": "string" - }, - "updated_at": { - "description": "Last update timestamp", - "format": "date-time", - "type": "string" + "user": { + "description": "User (public ID or expanded object when loaded)", + "oneOf": [ + { + "type": "string" + }, + { + "description": "API schema for a user.", + "properties": { + "alias": { + "description": "User alias/handle", + "type": "string" + }, + "email": { + "description": "User email address", + "type": "string" + }, + "id": { + "description": "User ID", + "type": "string" + }, + "metadata": { + "description": "User metadata", + "type": "object" + }, + "name": { + "description": "User display name. Null when the user has not set a name.", + "type": "string" + }, + "org": { + "description": "Organization", + "type": "string" + }, + "org_name": { + "description": "Organization display name. Null when the user is not in an org, or when the org association was not preloaded by the caller.", + "type": "string" + }, + "org_role": { + "description": "User's role within their org: \"admin\", \"member\", or \"viewer\". Null when the user is not in an org. Used by clients to gate org-admin UI surfaces.", + "type": "string" + }, + "sandbox": { + "description": "Sandbox", + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + } + ] } }, "required": [ @@ -415,100 +565,66 @@ ], "type": "object" }, - "AgentComputerListResponse": { - "description": "List response for agent computers.", - "properties": { - "data": { - "description": "List of agent computers", - "items": { - "$ref": "#/components/schemas/AgentComputer" - }, - "type": "array" - } - }, - "required": [ - "data" - ], - "type": "object" - }, - "AgentExport": { - "description": "API schema for an agent export response.\n\nContains the reconstructed AgentTemplate and all dependent config files\nneeded for a fully self-contained re-deploy.\n", + "ActivityFeedEntryListResponse": { + "description": "Reply payload for the `list_entries` channel message on\n`ApiActivityFeedChannel` — paginated activity feed entries with\ncursor-based pagination.\n", "properties": { - "configs": { - "description": "Dependent config files", + "after_cursor": { + "description": "Cursor for the next page (nil if at the end)", + "type": "string" + }, + "before_cursor": { + "description": "Cursor for the previous page (nil if at the start)", + "type": "string" + }, + "entries": { + "description": "Activity feed entries", "items": { - "$ref": "#/components/schemas/Config" + "$ref": "#/components/schemas/ActivityFeedEntry" }, "type": "array" }, - "template": { - "description": "AgentTemplate config object", - "type": "object" + "has_more": { + "description": "Whether more entries exist beyond this page", + "type": "boolean" } }, "required": [ - "template", - "configs" + "entries", + "has_more" ], "type": "object" }, - "AgentListResponse": { - "description": "Paginated list response for agents.", + "Actor": { + "description": "Schema for a message actor (user or agent).\n\nActors represent the entity that sent a message.\nMaps to the actor format from MessageActorHelper.build_actor/1.\n", "properties": { - "data": { - "description": "List of agents", - "items": { - "$ref": "#/components/schemas/Agent" - }, - "type": "array" - }, - "has_next": { - "description": "Whether a next page exists", - "type": "boolean" - }, - "has_prev": { - "description": "Whether a previous page exists", - "type": "boolean" - }, - "page": { - "description": "Current page number", - "type": "integer" + "alias": { + "description": "Actor alias/handle", + "type": "string" }, - "page_size": { - "description": "Results per page", - "type": "integer" + "id": { + "description": "Actor ID (format: user-xxx or agent-xxx)", + "type": "string" }, - "total_entries": { - "description": "Total number of entries", - "type": "integer" + "name": { + "description": "Actor display name", + "type": "string" }, - "total_pages": { - "description": "Total number of pages", - "type": "integer" + "profile_picture": { + "$ref": "#/components/schemas/ImageSource", + "description": "Profile picture" } }, - "required": [ - "data" - ], "type": "object" }, - "AgentRoutine": { - "description": "API schema for an agent routine.", + "Agent": { + "description": "API schema for an agent.", "properties": { "acl": { "$ref": "#/components/schemas/Acl", "description": "Access control list. Contains grants array with principal_type, principal, and actions. Null when no ACL restrictions are applied." }, - "agent": { - "description": "Owning agent ID", - "type": "string" - }, "app": { - "description": "Application ID", - "type": "string" - }, - "config": { - "description": "Config ID", + "description": "Application", "type": "string" }, "created_at": { @@ -516,24 +632,24 @@ "format": "date-time", "type": "string" }, - "description": { - "description": "Routine description", + "default_model": { + "description": "Default AI model", "type": "string" }, - "event_config": { - "description": "Event configuration", - "type": "object" + "email": { + "description": "Agent email", + "type": "string" }, - "event_type": { - "description": "Event type", + "id": { + "description": "Agent ID (agi_...)", "type": "string" }, - "handler_type": { - "description": "Handler type", + "identity": { + "description": "Identity prompt", "type": "string" }, - "id": { - "description": "Routine ID (arn_...)", + "last_applied_template_config": { + "description": "Config id of the AgentTemplate this agent was last provisioned/updated from", "type": "string" }, "lookup_key": { @@ -545,44 +661,41 @@ "type": "object" }, "name": { - "description": "Routine name", + "description": "Agent name", "type": "string" }, - "preset_config": { - "$ref": "#/components/schemas/PresetConfig", - "description": "Preset configuration" - }, - "preset_name": { - "description": "Preset name", + "org": { + "description": "Organization", "type": "string" }, - "schedule": { - "description": "Schedule expression", + "org_name": { + "description": "Organization display name. Null when the agent is not in an org, or when the org association was not preloaded by the caller.", "type": "string" }, - "script": { - "description": "Script content", + "originator": { + "description": "Free-form source or author of the agent", "type": "string" }, - "status": { - "description": "Routine status", + "phone_number": { + "description": "Agent phone number", "type": "string" }, - "steps": { - "description": "Ordered list of chain steps (present when handler_type is \"chain\"). Each step is a plain map with handler_type, optional body fields (preset_name / preset_config / script / config), and step-local plumbing (name, inputs, output_key, on_error).", - "items": { - "type": "object" - }, - "type": "array" + "sandbox": { + "description": "Sandbox", + "type": "string" }, - "trigger_context": { - "description": "Trigger context", + "team": { + "description": "Owning team", "type": "string" }, "updated_at": { "description": "Last update timestamp", "format": "date-time", "type": "string" + }, + "user": { + "description": "Owning user", + "type": "string" } }, "required": [ @@ -590,86 +703,67 @@ ], "type": "object" }, - "AgentRoutineListResponse": { - "description": "List response for agent routines.", - "properties": { - "data": { - "description": "List of agent routines", - "items": { - "$ref": "#/components/schemas/AgentRoutine" - }, - "type": "array" - } - }, - "required": [ - "data" - ], - "type": "object" - }, - "AgentRoutineRun": { - "description": "API schema for an agent routine run.", + "AgentComputer": { + "description": "API schema for an agent computer.", "properties": { - "acl": { - "$ref": "#/components/schemas/Acl", - "description": "Access control list. Contains grants array with principal_type, principal, and actions. Null when no ACL restrictions are applied." - }, "agent": { - "description": "Agent", + "description": "Owning agent", "type": "string" }, "app": { - "description": "Application", + "description": "Application ID", "type": "string" }, + "config": { + "description": "Configuration", + "type": "object" + }, "created_at": { "description": "Creation timestamp", "format": "date-time", "type": "string" }, - "duration_ms": { - "description": "Duration in milliseconds", - "type": "integer" + "error_message": { + "description": "Error message", + "type": "string" }, - "event_id": { - "description": "Event ID", + "id": { + "description": "Computer ID (cmp_...)", "type": "string" }, - "id": { - "description": "Run ID (arr_...)", + "last_active_at": { + "description": "Last active timestamp", + "format": "date-time", + "type": "string" + }, + "lookup_key": { + "description": "Unique lookup key", "type": "string" }, "metadata": { - "description": "Run metadata", + "description": "Arbitrary metadata", "type": "object" }, - "payload": { - "description": "Event payload", - "type": "object" + "name": { + "description": "Computer name", + "type": "string" }, - "result": { - "description": "Run result", - "type": "object" + "region": { + "description": "Region", + "type": "string" }, - "routine": { - "description": "Routine", + "sprite_url": { + "description": "Sprite URL", "type": "string" }, "status": { - "description": "Run status", + "description": "Computer status", "type": "string" }, - "structured_response": { - "description": "Validated structured response when the run uses an AgentMessageSchema", - "type": "object" - }, "updated_at": { "description": "Last update timestamp", "format": "date-time", "type": "string" - }, - "worker": { - "$ref": "#/components/schemas/WorkerStatus", - "description": "Background worker status. Null when no worker job is associated." } }, "required": [ @@ -677,21 +771,13 @@ ], "type": "object" }, - "AgentRoutineRunListResponse": { - "description": "Cursor-paginated list response for agent routine runs.", + "AgentComputerListResponse": { + "description": "List response for agent computers.", "properties": { - "after_cursor": { - "description": "Cursor for fetching items after this point", - "type": "string" - }, - "before_cursor": { - "description": "Cursor for fetching items before this point", - "type": "string" - }, "data": { - "description": "List of routine runs", + "description": "List of agent computers", "items": { - "$ref": "#/components/schemas/AgentRoutineRun" + "$ref": "#/components/schemas/AgentComputer" }, "type": "array" } @@ -701,15 +787,15 @@ ], "type": "object" }, - "AgentSchedule": { - "description": "API schema for an agent schedule.", + "AgentCreateResponse": { + "description": "Response shape for `POST /api/v1/agents`. Mirrors `AgentSchema` field-\nfor-field, plus an optional `installed_configs` array populated only\nwhen the request supplied `template_bundle`.\n\nField declarations are duplicated rather than imported so the OpenAPI\nspec sees a self-contained schema and the API DSL strict cast finds\nevery field directly on the response object. `from/2` delegates to\n`AgentSchema.from/2` for the agent fields and merges the install\nconfigs on top.\n", "properties": { - "agent": { - "description": "Owning agent ID", - "type": "string" + "acl": { + "$ref": "#/components/schemas/Acl", + "description": "Access control list. Contains grants array with principal_type, principal, and actions. Null when no ACL restrictions are applied." }, "app": { - "description": "Application ID", + "description": "Application", "type": "string" }, "created_at": { @@ -717,65 +803,69 @@ "format": "date-time", "type": "string" }, - "cron_expression": { - "description": "Cron expression (recurring only)", + "default_model": { + "description": "Default AI model", "type": "string" }, - "id": { - "description": "Schedule ID (asc_...)", + "email": { + "description": "Agent email", "type": "string" }, - "instructions": { - "description": "Task instructions", + "id": { + "description": "Agent ID (agi_...)", "type": "string" }, - "last_run_at": { - "description": "Last execution time", - "format": "date-time", + "identity": { + "description": "Identity prompt", "type": "string" }, - "max_runs": { - "description": "Maximum runs (recurring only)", - "type": "integer" + "installed_configs": { + "description": "Present when the request supplied `template_bundle`. One entry per persisted config; `key` echoes the caller-supplied input identifier (original lookup_key for top-level configs; `:` for skill files). Order is stable: sorted by `key`.", + "items": { + "$ref": "#/components/schemas/InstalledConfigEntry" + }, + "type": "array" + }, + "lookup_key": { + "description": "Unique lookup key", + "type": "string" }, "metadata": { "description": "Arbitrary metadata", "type": "object" }, - "next_run_at": { - "description": "Next scheduled execution", - "format": "date-time", + "name": { + "description": "Agent name", "type": "string" }, - "run_count": { - "description": "Number of times executed", - "type": "integer" - }, - "schedule_type": { - "description": "Schedule type (once or recurring)", + "org": { + "description": "Organization", "type": "string" }, - "scheduled_at": { - "description": "One-time execution time", - "format": "date-time", + "originator": { + "description": "Free-form source or author of the agent", "type": "string" }, - "status": { - "description": "Schedule status", + "phone_number": { + "description": "Agent phone number", "type": "string" }, - "thread": { - "description": "Thread ID (if thread-bound)", + "sandbox": { + "description": "Sandbox", "type": "string" }, - "timezone": { - "description": "Schedule timezone", + "team": { + "description": "Owning team", "type": "string" }, "updated_at": { "description": "Last update timestamp", "format": "date-time", "type": "string" + }, + "user": { + "description": "Owning user", + "type": "string" } }, "required": [ @@ -783,96 +873,55 @@ ], "type": "object" }, - "AgentSession": { - "description": "API schema for an agent session.", + "AgentEnvVarMasked": { + "description": "Schema for an agent environment variable response that masks the secret\nvalue. Used for list and show responses.\n", "properties": { "agent": { - "description": "Owning agent ID (agi_...)", - "type": "string" - }, - "completed_at": { - "description": "When the session completed", - "format": "date-time", + "description": "Owning agent ID", "type": "string" }, "created_at": { - "description": "Creation timestamp", + "description": "Created timestamp", "format": "date-time", "type": "string" }, - "error": { - "description": "Error message if failed", + "description": { + "description": "Optional description", "type": "string" }, "id": { - "description": "Agent session ID (ase_...)", + "description": "Agent env var ID (anv_...)", "type": "string" }, - "inbox": { - "description": "Inbox messages", - "items": { - "type": "object" - }, - "type": "array" - }, - "instructions": { - "description": "Task description for the session", + "key": { + "description": "Environment variable key", "type": "string" }, - "is_system_session": { - "description": "Whether this is a system-created session", - "type": "boolean" - }, - "max_runs_per_turn": { - "description": "Max tool runs per turn", - "type": "integer" - }, - "max_tokens": { - "description": "Max tokens", - "type": "integer" - }, - "max_turns": { - "description": "Max turns", - "type": "integer" - }, - "metadata": { - "description": "Arbitrary metadata", - "type": "object" - }, - "name": { - "description": "Optional display name for the session", + "masked_value": { + "description": "Masked environment variable value", "type": "string" }, - "result": { - "description": "Session result", - "type": "object" - }, - "started_at": { - "description": "When the session started running", + "updated_at": { + "description": "Updated timestamp", "format": "date-time", "type": "string" - }, - "status": { - "description": "Session status (pending, running, waiting, completed, failed, cancelled)", - "type": "string" - }, - "trajectory": { - "description": "Trajectory ID for the durable session transcript", - "type": "string" } }, "required": [ - "id" + "id", + "agent", + "key", + "masked_value" ], "type": "object" }, - "AgentSessionListResponse": { - "description": "List response for agent sessions.", + "AgentEnvVarMaskedList": { + "description": "Schema for agent environment variable list responses.", "properties": { "data": { - "description": "List of agent sessions", + "description": "Agent environment variables", "items": { - "$ref": "#/components/schemas/AgentSession" + "$ref": "#/components/schemas/AgentEnvVarMasked" }, "type": "array" } @@ -882,62 +931,213 @@ ], "type": "object" }, - "AgentSkill": { - "description": "API schema for an agent skill.", + "AgentExport": { + "description": "API schema for an agent export response.\n\nContains the reconstructed AgentTemplate and all dependent config files\nneeded for a fully self-contained re-deploy.\n", "properties": { - "agent": { - "description": "Owning agent ID", - "type": "string" + "configs": { + "description": "Dependent config files", + "items": { + "$ref": "#/components/schemas/Config" + }, + "type": "array" }, - "app": { - "description": "Application ID", - "type": "string" + "template": { + "description": "AgentTemplate config object", + "type": "object" + } + }, + "required": [ + "template", + "configs" + ], + "type": "object" + }, + "AgentHealth": { + "description": "Aggregate health profile for an agent.", + "properties": { + "activity": { + "description": "Last and next relevant activity timestamps", + "type": "object" }, - "config": { - "description": "Skill config ID", - "type": "string" + "agent": { + "$ref": "#/components/schemas/Agent", + "description": "Agent this health profile describes" }, - "created_at": { - "description": "Creation timestamp", + "checked_at": { + "description": "Timestamp when the profile was computed", "format": "date-time", "type": "string" }, - "id": { - "description": "Agent skill ID (ask_...)", - "type": "string" + "checks": { + "description": "Renderable health checks with key, label, status, and summary", + "items": { + "type": "object" + }, + "type": "array" }, - "instruction": { - "description": "Instruction override", - "type": "string" + "counts": { + "description": "Counts grouped by dependency area and status", + "type": "object" }, - "metadata": { - "description": "Arbitrary metadata", + "health_actions": { + "description": "All actionable items tracked for this agent — both `source: setup` (post-install checklist) and `source: health` (probe-detected issues). UX uses `params` to construct deep-links that resolve each item (set this env var, install this OAuth integration, run this verifier). Sorted by (source, sort_order, id).", + "items": { + "$ref": "#/components/schemas/AgentHealthAction" + }, + "type": "array" + }, + "recent": { + "description": "Recent activity and failure counts", "type": "object" }, - "status": { - "description": "Skill status", - "type": "string" + "score": { + "description": "Normalized health score from 0 to 100", + "type": "integer" }, - "updated_at": { - "description": "Last update timestamp", - "format": "date-time", + "status": { + "description": "Overall health status: ok, warning, or critical", "type": "string" } }, "required": [ - "id" + "agent", + "checked_at", + "status", + "score", + "counts", + "recent", + "activity", + "checks", + "health_actions" ], "type": "object" }, - "AgentSkillList": { - "description": "API schema for agent skills list response.", + "AgentHealthAction": { + "description": "Wire shape for an agent_health_action row, designed for the UI to\nrender the checklist AND construct deep-links that resolve each item\n(set this env var, install this OAuth integration, run this verifier).\n\n`params` is exposed in full because it carries the structured data\nthe UX needs to build action links — e.g., `key + scope` for env_var\nroutes the user to the right secret-store form with the field\npre-selected; `installation_kind` for install routes to the right\nOAuth flow.\n\n`verify_config` is exposed minus internal resolution details (the\n`script_config_id` the install pipeline computed from a bundle-side\n`script_ref` is server-side only — UX never invokes the script\ndirectly, the platform does). The retained `verify_config.type`\nlets the UX know which kind of \"Verify\" affordance to render.\n", + "properties": { + "agent": { + "description": "Agent the action is scoped to", + "type": "string" + }, + "app": { + "description": "Application", + "type": "string" + }, + "created_at": { + "description": "Creation timestamp", + "format": "date-time", + "type": "string" + }, + "depends_on": { + "description": "Identifiers of other actions that must complete before this one can run", + "items": { + "type": "string" + }, + "type": "array" + }, + "description": { + "description": "Markdown description", + "type": "string" + }, + "id": { + "description": "Action id (aha_...)", + "type": "string" + }, + "kind": { + "description": "Action kind: env_var, install, or custom", + "type": "string" + }, + "last_verified_at": { + "description": "Last time the verifier ran (null until first run)", + "format": "date-time", + "type": "string" + }, + "last_verifier_message": { + "description": "Human-readable message from the last verifier run", + "type": "string" + }, + "org": { + "description": "Organization", + "type": "string" + }, + "params": { + "description": "Kind-specific structured payload the UX uses to build action links (e.g. {key, scope} for env_var, {installation_kind} for install)", + "type": "object" + }, + "required": { + "description": "Whether this action counts toward the blocking checklist progress bar", + "type": "boolean" + }, + "sort_order": { + "description": "Render order; lower values come first within the same source", + "type": "integer" + }, + "source": { + "description": "Lifecycle stage that produced the row: setup or health", + "type": "string" + }, + "status": { + "description": "Current status: pending, completed, skipped, or degraded", + "type": "string" + }, + "title": { + "description": "Short human-readable title", + "type": "string" + }, + "updated_at": { + "description": "Last update timestamp", + "format": "date-time", + "type": "string" + }, + "verify_config": { + "description": "Verifier configuration. The UX reads `type` to render the right verify affordance.", + "type": "object" + } + }, + "required": [ + "id", + "source", + "kind", + "status", + "title", + "required", + "sort_order" + ], + "type": "object" + }, + "AgentListResponse": { + "description": "Paginated list response for agents.", "properties": { "data": { - "description": "List of agent skills", + "description": "List of agents", "items": { - "$ref": "#/components/schemas/AgentSkill" + "$ref": "#/components/schemas/Agent" }, "type": "array" + }, + "has_next": { + "description": "Whether a next page exists", + "type": "boolean" + }, + "has_prev": { + "description": "Whether a previous page exists", + "type": "boolean" + }, + "page": { + "description": "Current page number", + "type": "integer" + }, + "page_size": { + "description": "Results per page", + "type": "integer" + }, + "total_entries": { + "description": "Total number of entries", + "type": "integer" + }, + "total_pages": { + "description": "Total number of pages", + "type": "integer" } }, "required": [ @@ -945,9 +1145,13 @@ ], "type": "object" }, - "AgentTool": { - "description": "API schema for an agent tool.", + "AgentRoutine": { + "description": "API schema for an agent routine.", "properties": { + "acl": { + "$ref": "#/components/schemas/Acl", + "description": "Access control list. Contains grants array with principal_type, principal, and actions. Null when no ACL restrictions are applied." + }, "agent": { "description": "Owning agent ID", "type": "string" @@ -956,14 +1160,6 @@ "description": "Application ID", "type": "string" }, - "builtin_tool_config": { - "description": "Builtin tool configuration", - "type": "object" - }, - "builtin_tool_key": { - "description": "Builtin tool key", - "type": "string" - }, "config": { "description": "Config ID", "type": "string" @@ -974,7 +1170,15 @@ "type": "string" }, "description": { - "description": "Tool description", + "description": "Routine description", + "type": "string" + }, + "event_config": { + "description": "Event configuration", + "type": "object" + }, + "event_type": { + "description": "Event type", "type": "string" }, "handler_type": { @@ -982,15 +1186,11 @@ "type": "string" }, "id": { - "description": "Tool ID (atl_...)", - "type": "string" - }, - "instruction": { - "description": "Tool instruction", + "description": "Routine ID (arn_...)", "type": "string" }, - "kind": { - "description": "Tool kind", + "last_applied_template_config": { + "description": "Config id of the AgentRoutineTemplate this routine was last provisioned/updated from", "type": "string" }, "lookup_key": { @@ -1002,19 +1202,38 @@ "type": "object" }, "name": { - "description": "Tool name", + "description": "Routine name", "type": "string" }, - "parameters": { - "description": "Tool parameters", - "type": "object" + "preset_config": { + "$ref": "#/components/schemas/PresetConfig", + "description": "Preset configuration" }, - "parameters_config": { - "description": "Parameters config ID", + "preset_name": { + "description": "Preset name", + "type": "string" + }, + "schedule": { + "description": "Schedule expression", + "type": "string" + }, + "script": { + "description": "Script content", "type": "string" }, "status": { - "description": "Tool status", + "description": "Routine status", + "type": "string" + }, + "steps": { + "description": "Ordered list of chain steps (present when handler_type is \"chain\"). Each step is a plain map with handler_type, optional body fields (preset_name / preset_config / script / config), and step-local plumbing (name, inputs, output_key, on_error).", + "items": { + "type": "object" + }, + "type": "array" + }, + "trigger_context": { + "description": "Trigger context", "type": "string" }, "updated_at": { @@ -1028,13 +1247,13 @@ ], "type": "object" }, - "AgentToolListResponse": { - "description": "List response for agent tools.", + "AgentRoutineListResponse": { + "description": "List response for agent routines.", "properties": { "data": { - "description": "List of agent tools", + "description": "List of agent routines", "items": { - "$ref": "#/components/schemas/AgentTool" + "$ref": "#/components/schemas/AgentRoutine" }, "type": "array" } @@ -1044,15 +1263,19 @@ ], "type": "object" }, - "Artifact": { - "description": "API schema for an artifact.", + "AgentRoutineRun": { + "description": "API schema for an agent routine run.", "properties": { + "acl": { + "$ref": "#/components/schemas/Acl", + "description": "Access control list. Contains grants array with principal_type, principal, and actions. Null when no ACL restrictions are applied." + }, "agent": { "description": "Agent", "type": "string" }, - "content_type": { - "description": "MIME content type", + "app": { + "description": "Application", "type": "string" }, "created_at": { @@ -1060,66 +1283,50 @@ "format": "date-time", "type": "string" }, - "current_version": { - "description": "Current version ID", - "type": "string" - }, - "description": { - "description": "Artifact description", - "type": "string" - }, - "file": { - "description": "Storage file", - "type": "string" - }, - "file_name": { - "description": "Original filename", - "type": "string" + "duration_ms": { + "description": "Duration in milliseconds", + "type": "integer" }, - "file_url": { - "description": "Signed file URL", + "event_id": { + "description": "Event ID", "type": "string" }, "id": { - "description": "Artifact ID", + "description": "Run ID (arr_...)", "type": "string" }, - "image_source": { - "$ref": "#/components/schemas/ImageSource", - "description": "Image source metadata" + "metadata": { + "description": "Run metadata", + "type": "object" }, - "name": { - "description": "Artifact name", - "type": "string" + "payload": { + "description": "Event payload", + "type": "object" }, - "org": { - "description": "Organization", - "type": "string" + "result": { + "description": "Run result", + "type": "object" }, - "sandbox": { - "description": "Sandbox identifier", + "routine": { + "description": "Routine", "type": "string" }, - "team": { - "description": "Team", + "status": { + "description": "Run status", "type": "string" }, - "thread": { - "description": "Thread", - "type": "string" + "structured_response": { + "description": "Validated structured response when the run uses an AgentMessageSchema", + "type": "object" }, "updated_at": { "description": "Last update timestamp", "format": "date-time", "type": "string" }, - "user": { - "description": "User", - "type": "string" - }, - "version": { - "description": "Current version number", - "type": "integer" + "worker": { + "$ref": "#/components/schemas/WorkerStatus", + "description": "Background worker status. Null when no worker job is associated." } }, "required": [ @@ -1127,587 +1334,579 @@ ], "type": "object" }, - "Attachment": { - "description": "Schema for a message attachment.\n\nAttachments can be of various types (file, scraped_link, artifact, task, media, action).\nFields present depend on the attachment type.\nMaps to format_attachments_for_client/1 output.\n", + "AgentRoutineRunListResponse": { + "description": "Cursor-paginated list response for agent routine runs.", "properties": { - "content_type": { - "description": "MIME content type (file, artifact, media types)", + "after_cursor": { + "description": "Cursor for fetching items after this point", "type": "string" }, - "description": { - "description": "Description (scraped_link, artifact, task types)", + "before_cursor": { + "description": "Cursor for fetching items before this point", "type": "string" }, - "filename": { - "description": "File name (file, artifact, media types)", + "data": { + "description": "List of routine runs", + "items": { + "$ref": "#/components/schemas/AgentRoutineRun" + }, + "type": "array" + } + }, + "required": [ + "data" + ], + "type": "object" + }, + "AgentSchedule": { + "description": "API schema for an agent schedule.", + "properties": { + "agent": { + "description": "Owning agent ID", "type": "string" }, - "height": { - "description": "Media height (media type)", - "type": "integer" - }, - "id": { - "description": "Attachment ID", + "app": { + "description": "Application ID", "type": "string" }, - "image_height": { - "description": "Preview image height (scraped_link type)", - "type": "integer" - }, - "image_source": { - "$ref": "#/components/schemas/ImageSource", - "description": "Image metadata (file, scraped_link, artifact, media types)" - }, - "image_url": { - "description": "Preview image URL (scraped_link type)", + "created_at": { + "description": "Creation timestamp", + "format": "date-time", "type": "string" }, - "image_width": { - "description": "Preview image width (scraped_link type)", - "type": "integer" - }, - "media_type": { - "description": "Media type (media type)", + "cron_expression": { + "description": "Cron expression (recurring only)", "type": "string" }, - "name": { - "description": "Media name (media type)", + "id": { + "description": "Schedule ID (asc_...)", "type": "string" }, - "object": { - "description": "Embedded object (task, action types)", - "type": "object" - }, - "title": { - "description": "Title (scraped_link, artifact, task types)", + "instructions": { + "description": "Task instructions", "type": "string" }, - "type": { - "description": "Attachment type: file, scraped_link, artifact, task, media, action", + "last_run_at": { + "description": "Last execution time", + "format": "date-time", "type": "string" }, - "url": { - "description": "URL to the resource (file, scraped_link, artifact, media types)", - "type": "string" + "max_runs": { + "description": "Maximum runs (recurring only)", + "type": "integer" }, - "variants": { - "description": "Media variants (media type)", - "items": { - "$ref": "#/components/schemas/MediaVariant" - }, - "type": "array" + "metadata": { + "description": "Arbitrary metadata", + "type": "object" }, - "version": { - "description": "Artifact version number (artifact type)", - "type": "integer" + "next_run_at": { + "description": "Next scheduled execution", + "format": "date-time", + "type": "string" }, - "width": { - "description": "Media width (media type)", + "run_count": { + "description": "Number of times executed", "type": "integer" - } - }, - "required": [ - "id", - "type" - ], - "type": "object" - }, - "AuthTokens": { - "description": "API schema for authentication token responses.", - "properties": { - "expires_in": { - "description": "Token TTL in seconds", - "type": "integer", - "x-sdk": "token_expiry" }, - "metadata": { - "description": "Additional metadata (e.g., onboarding_job_id)", - "type": "object" + "schedule_type": { + "description": "Schedule type (once or recurring)", + "type": "string" }, - "refresh_token": { - "description": "Refresh token", - "type": "string", - "x-sdk": "refresh_token" + "scheduled_at": { + "description": "One-time execution time", + "format": "date-time", + "type": "string" }, - "token": { - "description": "Access token (JWT)", - "type": "string", - "x-sdk": "access_token" + "status": { + "description": "Schedule status", + "type": "string" }, - "token_type": { - "description": "Token type (Bearer)", + "thread": { + "description": "Thread ID (if thread-bound)", "type": "string" }, - "user": { - "$ref": "#/components/schemas/User", - "description": "Authenticated user" + "timezone": { + "description": "Schedule timezone", + "type": "string" + }, + "updated_at": { + "description": "Last update timestamp", + "format": "date-time", + "type": "string" } }, "required": [ - "token", - "refresh_token", - "user", - "token_type", - "expires_in" + "id" ], "type": "object" }, - "AutomationRun": { - "description": "Schema for an automation run.\n\nMaps to serialized automation run output from developer portal API.\n", + "AgentSession": { + "description": "API schema for an agent session.", "properties": { - "app": { - "description": "App (dap_...)", + "agent": { + "description": "Owning agent ID (agi_...)", "type": "string" }, - "automation": { - "description": "Automation (aut_...)", + "completed_at": { + "description": "When the session completed", + "format": "date-time", "type": "string" }, "created_at": { - "description": "Created timestamp", + "description": "Creation timestamp", "format": "date-time", "type": "string" }, - "event_id": { - "description": "Triggering event ID", + "error": { + "description": "Error message if failed", "type": "string" }, "id": { - "description": "Public ID (atr_...)", + "description": "Agent session ID (ase_...)", "type": "string" }, - "payload": { - "description": "Event payload", - "type": "object" + "inbox": { + "description": "Inbox messages", + "items": { + "type": "object" + }, + "type": "array" }, - "result": { - "description": "Workflow execution result (payload and output)", + "instructions": { + "description": "Task description for the session", + "type": "string" + }, + "is_system_session": { + "description": "Whether this is a system-created session", + "type": "boolean" + }, + "max_runs_per_turn": { + "description": "Max tool runs per turn", + "type": "integer" + }, + "max_tokens": { + "description": "Max tokens", + "type": "integer" + }, + "max_turns": { + "description": "Max turns", + "type": "integer" + }, + "metadata": { + "description": "Arbitrary metadata", "type": "object" }, - "status": { - "description": "Status: pending, running, completed, failed, cancelled", + "name": { + "description": "Optional display name for the session", "type": "string" }, - "team": { - "description": "Team if team-owned", - "type": "string" + "result": { + "description": "Session result", + "type": "object" }, - "updated_at": { - "description": "Updated timestamp", + "started_at": { + "description": "When the session started running", "format": "date-time", "type": "string" }, - "user": { - "description": "User if user-owned", + "status": { + "description": "Session status (pending, running, waiting, completed, failed, cancelled)", + "type": "string" + }, + "trajectory": { + "description": "Trajectory ID for the durable session transcript", "type": "string" } }, "required": [ - "id", - "app", - "automation", - "status" + "id" ], "type": "object" }, - "BuiltinTool": { - "description": "An individual tool within a builtin tool catalog entry.", + "AgentSessionListResponse": { + "description": "List response for agent sessions.", "properties": { - "description": { - "description": "Tool description", - "type": "string" - }, - "name": { - "description": "Tool name", - "type": "string" + "data": { + "description": "List of agent sessions", + "items": { + "$ref": "#/components/schemas/AgentSession" + }, + "type": "array" } }, "required": [ - "name" + "data" ], "type": "object" }, - "BuiltinToolCatalogEntry": { - "description": "A builtin tool catalog entry describing an available tool category.", + "AgentSkill": { + "description": "API schema for an agent skill.", "properties": { - "config_schema": { - "description": "JSON schema for tool configuration", - "type": "object" + "agent": { + "description": "Owning agent ID", + "type": "string" }, - "description": { - "description": "Tool description", + "app": { + "description": "Application ID", "type": "string" }, - "instruction": { - "description": "Tool instruction", + "config": { + "description": "Skill config ID", "type": "string" }, - "key": { - "description": "Unique tool key", + "created_at": { + "description": "Creation timestamp", + "format": "date-time", "type": "string" }, - "label": { - "description": "Display label", + "id": { + "description": "Agent skill ID (ask_...)", "type": "string" }, - "providers": { - "description": "Supported providers", - "items": { - "type": "string" - }, - "type": "array" + "instruction": { + "description": "Instruction override", + "type": "string" }, - "requires_integration": { - "description": "Whether an integration is required", - "type": "boolean" + "last_applied_template_config": { + "description": "Config id of the AgentTemplate this skill was last provisioned/updated from", + "type": "string" }, - "server_tool_type": { - "description": "Server tool type identifier", + "metadata": { + "description": "Arbitrary metadata", + "type": "object" + }, + "status": { + "description": "Skill status", "type": "string" }, - "tools": { - "description": "List of individual tools", - "items": { - "$ref": "#/components/schemas/BuiltinTool" - }, - "type": "array" + "updated_at": { + "description": "Last update timestamp", + "format": "date-time", + "type": "string" } }, "required": [ - "key" + "id" ], "type": "object" }, - "ComputerExecResult": { - "description": "Result of executing a command on an agent computer.", + "AgentSkillList": { + "description": "API schema for agent skills list response.", "properties": { - "exit_code": { - "description": "Process exit code", - "type": "integer" - }, - "output": { - "description": "Command output", - "type": "string" + "data": { + "description": "List of agent skills", + "items": { + "$ref": "#/components/schemas/AgentSkill" + }, + "type": "array" } }, + "required": [ + "data" + ], "type": "object" }, - "Config": { - "description": "API schema for a config resource.", + "AgentTool": { + "description": "API schema for an agent tool.", "properties": { + "agent": { + "description": "Owning agent ID", + "type": "string" + }, + "app": { + "description": "Application ID", + "type": "string" + }, + "async": { + "description": "Whether the tool executes asynchronously", + "type": "boolean" + }, + "builtin_tool_config": { + "description": "Builtin tool configuration", + "type": "object" + }, + "builtin_tool_key": { + "description": "Builtin tool key", + "type": "string" + }, + "config": { + "description": "Config ID", + "type": "string" + }, "created_at": { "description": "Creation timestamp", "format": "date-time", "type": "string" }, - "current_version": { - "$ref": "#/components/schemas/ConfigVersion", - "description": "Current version" + "description": { + "description": "Tool description", + "type": "string" + }, + "handler_type": { + "description": "Handler type", + "type": "string" }, "id": { - "description": "Config ID (cfg_...)", + "description": "Tool ID (atl_...)", "type": "string" }, - "is_archived": { - "description": "Whether config is archived", - "type": "boolean" + "instruction": { + "description": "Tool instruction", + "type": "string" }, "kind": { - "description": "Config kind (e.g., Agent, APITool)", + "description": "Tool kind", "type": "string" }, - "lookup_key": { - "description": "Optional lookup key", + "last_applied_template_config": { + "description": "Config id of the AgentToolTemplate this tool was last provisioned/updated from", "type": "string" }, - "mime_type": { - "description": "Content mime type", + "lookup_key": { + "description": "Unique lookup key", "type": "string" }, - "org": { - "description": "Organization", - "type": "string" + "metadata": { + "description": "Arbitrary metadata", + "type": "object" }, - "parent": { - "description": "Parent config ID (bundle children only)", + "name": { + "description": "Tool name", "type": "string" }, - "raw_content": { - "description": "Raw file content (system configs only)", + "name_prefix": { + "description": "Per-instance namespace stamped onto LLM-facing tool names for builtin tools that support multiple instances per agent.", "type": "string" }, - "relative_path": { - "description": "Path within parent bundle (bundle children only)", - "type": "string" + "parameters": { + "description": "Tool parameters", + "type": "object" }, - "sandbox": { - "description": "Sandbox identifier", + "parameters_config": { + "description": "Parameters config ID", "type": "string" }, - "team": { - "description": "Team", + "status": { + "description": "Tool status", "type": "string" }, "updated_at": { "description": "Last update timestamp", "format": "date-time", "type": "string" - }, - "user": { - "description": "User", - "type": "string" - }, - "virtual_path": { - "description": "Unique path within the team", - "type": "string" } }, "required": [ - "id", - "kind" + "id" ], "type": "object" }, - "ConfigKindSchema": { - "description": "Schema for a config kind's JSON schema and sample response.\n", + "AgentToolListResponse": { + "description": "List response for agent tools.", "properties": { - "json_schema": { - "description": "JSON Schema for this config kind (can be null if not available)", - "type": "object" - }, - "kind": { - "description": "The config kind name", - "type": "string" - }, - "sample_yaml": { - "description": "Sample YAML content for this config kind (can be null if not available)", - "type": "string" + "data": { + "description": "List of agent tools", + "items": { + "$ref": "#/components/schemas/AgentTool" + }, + "type": "array" } }, "required": [ - "kind" + "data" ], "type": "object" }, - "ConfigVersion": { - "description": "API schema for a config version.", + "AgentUpgradeChange": { + "description": "One child-resource change produced by an agent upgrade.", "properties": { - "change_description": { - "description": "Description of changes", + "action": { "type": "string" }, - "created_at": { - "description": "Creation timestamp", - "format": "date-time", + "id": { "type": "string" }, - "data": { - "description": "Additional structured data", - "type": "object" - }, - "id": { - "description": "Config version ID (cfv_...)", + "key": { "type": "string" }, - "org": { - "description": "Organization", + "name": { "type": "string" }, - "sandbox": { - "description": "Sandbox", + "parent_template_config": { + "$ref": "#/components/schemas/UpgradeTemplateSummary" + }, + "resource_type": { "type": "string" }, - "version_number": { - "description": "Version number", - "type": "integer" + "source_template_config": { + "$ref": "#/components/schemas/UpgradeTemplateSummary" } }, "required": [ - "id", - "version_number" + "resource_type", + "action", + "parent_template_config" ], "type": "object" }, - "CustomObject": { - "description": "API schema for a custom object.", + "AgentUpgradeResponse": { + "description": "Wire shape for `POST /api/v1/agents/:agent/upgrade`.\n", "properties": { - "created_at": { - "description": "Created timestamp", - "format": "date-time", - "type": "string" + "agent": { + "$ref": "#/components/schemas/Agent", + "description": "Updated agent. Null for dry-run responses." }, - "fields": { - "description": "Object field values", - "type": "object" + "solution": { + "$ref": "#/components/schemas/SolutionSummary", + "description": "Source Solution summary" }, - "id": { - "description": "Public ID (cobj_...)", - "type": "string" + "template": { + "$ref": "#/components/schemas/UpgradeTemplateSummary", + "description": "Selected AgentTemplate" }, - "org": { - "description": "Organization", - "type": "string" + "upgrade_result": { + "$ref": "#/components/schemas/AgentUpgradeResult", + "description": "Upgrade diff" + } + }, + "required": [ + "solution", + "template", + "upgrade_result" + ], + "type": "object" + }, + "AgentUpgradeResult": { + "description": "Structured result for `POST /api/v1/agents/:agent/upgrade`.", + "properties": { + "changes": { + "items": { + "$ref": "#/components/schemas/AgentUpgradeChange" + }, + "type": "array" }, - "row_key": { - "description": "Row key", + "dry_run": { + "type": "boolean" + }, + "mode": { "type": "string" }, - "sandbox": { - "description": "Sandbox identifier", + "status": { "type": "string" }, - "schema_type": { - "description": "Schema type (lookup_key)", - "type": "string" - }, - "team": { - "description": "Owning team", - "type": "string" - }, - "updated_at": { - "description": "Updated timestamp", - "format": "date-time", - "type": "string" - }, - "user": { - "description": "Owning user", - "type": "string" - }, - "version": { - "description": "Aggregate version for OCC", - "type": "integer" + "summary": { + "$ref": "#/components/schemas/AgentUpgradeSummary" } }, "required": [ - "id" + "status", + "mode", + "dry_run", + "summary", + "changes" ], "type": "object" }, - "DeviceAuthorizationResponse": { - "description": "API schema for OAuth device authorization responses.", + "AgentUpgradeSummary": { + "description": "Summary counts for an agent upgrade diff.", "properties": { - "device_code": { - "description": "Device verification code", - "type": "string" - }, - "expires_in": { - "description": "TTL in seconds", + "adds": { "type": "integer" }, - "interval": { - "description": "Polling interval in seconds", + "noops": { "type": "integer" }, - "user_code": { - "description": "User-facing verification code", - "type": "string" - }, - "verification_uri": { - "description": "Base verification URI", - "type": "string" + "removes": { + "type": "integer" }, - "verification_uri_complete": { - "description": "Full verification URI with code", - "type": "string" - } - }, - "required": [ - "device_code", - "user_code", - "verification_uri", - "verification_uri_complete", - "expires_in", - "interval" - ], - "type": "object" - }, - "DeviceAuthorizationStatusResponse": { - "description": "API schema for OAuth device authorization approval and denial responses.", - "properties": { - "status": { - "description": "Authorization status (approved or denied)", - "type": "string" + "updates": { + "type": "integer" } }, "required": [ - "status" + "adds", + "updates", + "removes", + "noops" ], "type": "object" }, - "ImageSource": { - "description": "API schema for image source metadata.", + "Artifact": { + "description": "API schema for an artifact.", "properties": { - "file": { - "description": "Storage file", + "agent": { + "description": "Agent", "type": "string" }, - "height": { - "description": "Image height in pixels", - "type": "integer" - }, - "media": { - "description": "Media", + "content_type": { + "description": "MIME content type", "type": "string" }, - "mime_type": { - "description": "Image MIME type", + "created_at": { + "description": "Creation timestamp", + "format": "date-time", "type": "string" }, - "refresh_url": { - "description": "URL to refresh signed URL", + "current_version": { + "description": "Current version ID", "type": "string" }, - "url": { - "description": "Image URL", + "description": { + "description": "Artifact description", "type": "string" }, - "width": { - "description": "Image width in pixels", - "type": "integer" - } - }, - "type": "object" - }, - "Installation": { - "description": "API schema for an installation.", - "properties": { - "agent": { - "description": "Owning agent", + "file": { + "description": "Storage file", "type": "string" }, - "config": { - "description": "Configuration", - "type": "object" + "file_name": { + "description": "Original filename", + "type": "string" }, - "created_at": { - "description": "Creation timestamp", - "format": "date-time", + "file_url": { + "description": "Signed file URL", "type": "string" }, "id": { - "description": "Installation ID (cin_...)", + "description": "Artifact ID", "type": "string" }, - "kind": { - "description": "Installation kind", + "image_source": { + "$ref": "#/components/schemas/ImageSource", + "description": "Image source metadata" + }, + "name": { + "description": "Artifact name", "type": "string" }, - "shared_integration": { - "description": "Bound shared integration", + "org": { + "description": "Organization", "type": "string" }, - "state": { - "description": "Installation state", + "sandbox": { + "description": "Sandbox identifier", "type": "string" }, - "status_payload": { - "description": "Status payload", - "type": "object" + "team": { + "description": "Team", + "type": "string" + }, + "thread": { + "description": "Thread", + "type": "string" }, "updated_at": { "description": "Last update timestamp", "format": "date-time", "type": "string" + }, + "user": { + "description": "User", + "type": "string" + }, + "version": { + "description": "Current version number", + "type": "integer" } }, "required": [ @@ -1715,387 +1914,498 @@ ], "type": "object" }, - "InstallationKind": { - "description": "API schema for an installation kind.", + "Attachment": { + "description": "Schema for a message attachment.\n\nAttachments can be of various types (file, scraped_link, artifact, task, media, action).\nFields present depend on the attachment type.\nMaps to format_attachments_for_client/1 output.\n", "properties": { - "accepts_sources": { - "description": "Whether this kind accepts sources", - "type": "boolean" + "content_type": { + "description": "MIME content type (file, artifact, media types)", + "type": "string" }, - "category": { - "description": "Category", + "description": { + "description": "Description (scraped_link, artifact, task types)", "type": "string" }, - "config_schema": { - "description": "JSON schema for configuration", - "type": "object" + "filename": { + "description": "File name (file, artifact, media types)", + "type": "string" }, - "description": { - "description": "Description", + "height": { + "description": "Media height (media type)", + "type": "integer" + }, + "id": { + "description": "Attachment ID", "type": "string" }, - "kind": { - "description": "Installation kind identifier", + "image_height": { + "description": "Preview image height (scraped_link type)", + "type": "integer" + }, + "image_source": { + "$ref": "#/components/schemas/ImageSource", + "description": "Image metadata (file, scraped_link, artifact, media types)" + }, + "image_url": { + "description": "Preview image URL (scraped_link type)", "type": "string" }, - "label": { - "description": "Display label", + "image_width": { + "description": "Preview image width (scraped_link type)", + "type": "integer" + }, + "media_type": { + "description": "Media type (media type)", "type": "string" }, - "provider": { - "description": "Integration provider", + "name": { + "description": "Media name (media type)", "type": "string" }, - "requires_integration": { - "description": "Whether this kind requires an integration", - "type": "boolean" - } - }, - "required": [ - "kind" - ], - "type": "object" - }, - "InstallationKindListResponse": { - "description": "List response for installation kinds.", - "properties": { - "data": { - "description": "List of installation kinds", + "object": { + "description": "Embedded object (task, action types)", + "type": "object" + }, + "title": { + "description": "Title (scraped_link, artifact, task types)", + "type": "string" + }, + "type": { + "description": "Attachment type: file, scraped_link, artifact, task, media, action", + "type": "string" + }, + "url": { + "description": "URL to the resource (file, scraped_link, artifact, media types)", + "type": "string" + }, + "variants": { + "description": "Media variants (media type)", "items": { - "$ref": "#/components/schemas/InstallationKind" + "$ref": "#/components/schemas/MediaVariant" }, "type": "array" + }, + "version": { + "description": "Artifact version number (artifact type)", + "type": "integer" + }, + "width": { + "description": "Media width (media type)", + "type": "integer" } }, "required": [ - "data" + "id", + "type" ], "type": "object" }, - "InstallationListResponse": { - "description": "List response for installations.", + "AuthTokens": { + "description": "API schema for authentication token responses.", "properties": { - "data": { - "description": "List of installations", - "items": { - "$ref": "#/components/schemas/Installation" - }, - "type": "array" + "expires_in": { + "description": "Token TTL in seconds", + "type": "integer", + "x-sdk": "token_expiry" + }, + "metadata": { + "description": "Additional metadata (e.g., onboarding_job_id)", + "type": "object" + }, + "refresh_token": { + "description": "Refresh token", + "type": "string", + "x-sdk": "refresh_token" + }, + "token": { + "description": "Access token (JWT)", + "type": "string", + "x-sdk": "access_token" + }, + "token_type": { + "description": "Token type (Bearer)", + "type": "string" + }, + "user": { + "$ref": "#/components/schemas/User", + "description": "Authenticated user" } }, "required": [ - "data" + "token", + "refresh_token", + "user", + "token_type", + "expires_in" ], "type": "object" }, - "InstallationSource": { - "description": "API schema for an installation source.", + "AutomationRun": { + "description": "Schema for an automation run.\n\nMaps to serialized automation run output from developer portal API.\n", "properties": { - "agent": { - "description": "Owning agent", + "app": { + "description": "App (dap_...)", "type": "string" }, - "context_installation": { - "description": "Installation ID", + "automation": { + "description": "Automation (aut_...)", "type": "string" }, "created_at": { - "description": "Creation timestamp", + "description": "Created timestamp", "format": "date-time", "type": "string" }, - "id": { - "description": "Source ID (cso_...)", + "event_id": { + "description": "Triggering event ID", "type": "string" }, - "metadata": { - "description": "Arbitrary metadata", - "type": "object" - }, - "parent_source": { - "description": "Parent source ID", + "id": { + "description": "Public ID (atr_...)", "type": "string" }, "payload": { - "description": "Source payload", + "description": "Event payload", "type": "object" }, - "state": { - "description": "Source state", - "type": "string" - }, - "team": { - "description": "Team ID", - "type": "string" + "result": { + "description": "Workflow execution result (payload and output)", + "type": "object" }, - "thread": { - "description": "Thread ID", + "status": { + "description": "Status: pending, running, completed, failed, cancelled", "type": "string" }, - "type": { - "description": "Source type", + "team": { + "description": "Team if team-owned", "type": "string" }, "updated_at": { - "description": "Last update timestamp", + "description": "Updated timestamp", "format": "date-time", "type": "string" }, "user": { - "description": "User ID", + "description": "User if user-owned", "type": "string" } }, "required": [ - "id" - ], - "type": "object" - }, - "InstallationSourceListResponse": { - "description": "List response for installation sources.", - "properties": { - "data": { - "description": "List of installation sources", - "items": { - "$ref": "#/components/schemas/InstallationSource" - }, - "type": "array" - } - }, - "required": [ - "data" + "id", + "app", + "automation", + "status" ], "type": "object" }, - "InviteCreator": { - "description": "Minimal public-safe projection of the user who created an invite.\n\nInvites are fetched by unauthenticated recipients on the `/auth/invites/:id`\nroute, so this schema deliberately exposes only the fields needed to render a\njoin screen — id, display name, and profile picture. Email, org, sandbox, and\nother fields on the full `User` schema are omitted.\n", + "BugReport": { + "description": "API schema for bug reports.", "properties": { - "id": { - "description": "User ID", + "app": { + "description": "App", "type": "string" }, - "name": { - "description": "Display name", + "client": { + "description": "Submitting client", "type": "string" }, - "profile_picture": { - "$ref": "#/components/schemas/ImageSource", - "description": "Profile picture" - } - }, - "required": [ - "id" - ], - "type": "object" - }, - "KeyValueStorageEntry": { - "description": "Schema for a key-value storage entry.\n\nMaps exactly to render_entry/1 output in ApiStorageController.\n", - "properties": { + "client_version": { + "description": "Client version", + "type": "string" + }, + "context": { + "description": "Client-shaped context blob", + "type": "object" + }, "created_at": { "description": "Creation timestamp", "format": "date-time", "type": "string" }, - "key": { - "description": "Storage key", + "description": { + "description": "Freeform report text", "type": "string" }, - "updated_at": { - "description": "Last update timestamp", - "format": "date-time", + "id": { + "description": "Bug report ID", "type": "string" }, - "user": { - "description": "User", + "org": { + "description": "Organization", "type": "string" }, - "value": { - "description": "Stored value", + "sandbox": { + "description": "Sandbox", + "type": "string" + }, + "team": { + "description": "Team", + "type": "string" + }, + "updated_at": { + "description": "Update timestamp", + "format": "date-time", "type": "string" } }, "required": [ - "user", - "key", - "value" + "id", + "description", + "client", + "client_version" ], "type": "object" }, - "KeyValueStorageEntryPage": { - "description": "Response envelope for the dual-mode key-value list endpoint.\n\nUser-JWT callers receive `%{data: [...]}` (no pagination fields).\nDeveloper / S2S callers receive `%{data: [...]}` plus pagination metadata.\n", + "BuiltinTool": { + "description": "An individual tool within a builtin tool catalog entry.", "properties": { - "data": { - "description": "Storage entries on this page", - "items": { - "$ref": "#/components/schemas/KeyValueStorageEntryWithUser" - }, - "type": "array" - }, - "has_next": { - "description": "Whether a next page exists (developer / S2S only)", - "type": "boolean" - }, - "has_prev": { - "description": "Whether a previous page exists (developer / S2S only)", - "type": "boolean" - }, - "page": { - "description": "Current page number (developer / S2S only)", - "type": "integer" - }, - "page_size": { - "description": "Results per page (developer / S2S only)", - "type": "integer" - }, - "total_entries": { - "description": "Total entries matching the filters (developer / S2S only)", - "type": "integer" + "description": { + "description": "Tool description", + "type": "string" }, - "total_pages": { - "description": "Total number of pages (developer / S2S only)", - "type": "integer" + "name": { + "description": "Tool name", + "type": "string" } }, "required": [ - "data" + "name" ], "type": "object" }, - "KeyValueStorageEntryWithUser": { - "description": "Schema for a key-value storage entry, optionally enriched with a summary of\nthe owning user.\n\nUsed by the dual-mode list endpoint: user-JWT callers omit the user_email /\nuser_name fields (they know who they are); developer / S2S callers populate\nthem so the portal can render an owner column without a per-row lookup.\n", + "BuiltinToolCatalogEntry": { + "description": "A builtin tool catalog entry describing an available tool category.", "properties": { - "created_at": { - "description": "Creation timestamp", - "format": "date-time", - "type": "string" + "config_schema": { + "description": "JSON schema for tool configuration", + "type": "object" }, - "key": { - "description": "Storage key", + "description": { + "description": "Tool description", "type": "string" }, - "updated_at": { - "description": "Last update timestamp", - "format": "date-time", + "instruction": { + "description": "Tool instruction", "type": "string" }, - "user": { - "description": "User ID", + "key": { + "description": "Unique tool key", "type": "string" }, - "user_email": { - "description": "User email (developer / S2S only)", + "label": { + "description": "Display label", "type": "string" }, - "user_name": { - "description": "User display name (developer / S2S only)", + "multi_instance_mode": { + "description": "Multi-instance mode: \"namespaced\" (multiple instances allowed, each must carry a name_prefix), \"passthrough\" (multiple instances allowed without a name_prefix — names come from the underlying source), or null (single-instance).", "type": "string" }, - "value": { - "description": "Stored value", + "providers": { + "description": "Supported providers", + "items": { + "type": "string" + }, + "type": "array" + }, + "requires_integration": { + "description": "Whether an integration is required", + "type": "boolean" + }, + "server_tool_type": { + "description": "Server tool type identifier", "type": "string" + }, + "tools": { + "description": "List of individual tools", + "items": { + "$ref": "#/components/schemas/BuiltinTool" + }, + "type": "array" } }, "required": [ - "user", - "key", - "value", - "created_at", - "updated_at" + "key" ], "type": "object" }, - "LLMConfig": { - "description": "API schema for per-routine LLM invocation settings.\n\nMirrors `ArchAstro.Agents.Routines.LLMConfig`. When `model` is present,\nit overrides the agent's `default_model` for the routine (or step).\n", + "ChannelAck": { + "description": "Acknowledgement-only channel reply.\n\nUsed for channel messages whose handler returns `:ok` — the wire envelope\nis `{status: \"ok\", response: {}}`. Declared as a named schema (rather\nthan left implicit) so the OpenAPI spec carries the intent that no\npayload is expected, and the channel DSL can enforce that every\nmessage declares a `returns` type.\n", + "properties": {}, + "type": "object" + }, + "ChatForkThreadResponse": { + "description": "Reply payload for the `api:chat:fork_thread` channel message — the\nnewly-forked thread plus its initial chat-room model snapshot.\n\n`team` is only populated when the original thread was team-scoped.\n`chat_model` carries the same rich snapshot shape as the\n`load_more_messages` reply — `nil` only for transient threads where\nthe room model is suppressed.\n", "properties": { - "model": { - "description": "Model identifier. When set, overrides the agent's default_model.", - "type": "string" + "chat_model": { + "$ref": "#/components/schemas/ChatRoomModel", + "description": "Initial chat-room render model — nil for transient threads" + }, + "team": { + "$ref": "#/components/schemas/Team", + "description": "Owning team — present only when the parent was team-scoped" + }, + "thread": { + "$ref": "#/components/schemas/Thread", + "description": "The newly-forked thread" } }, + "required": [ + "thread" + ], "type": "object" }, - "MediaVariant": { - "description": "API schema for a media variant.", + "ChatLoadMoreMessagesResponse": { + "description": "Reply payload for the `api:chat:load_more_messages` channel message —\nthe refreshed chat-room snapshot after fetching another page of\nmessages. The polymorphic renderer in `ChatChannelImpl` returns a\n`ChatRoomModel` for this code path; older message-chunk shapes only\nappear as inputs to the renderer, never as the wire payload here.\n", "properties": { - "content_type": { - "description": "File content type", - "type": "string" - }, - "created_at": { - "description": "Creation timestamp", - "format": "date-time", - "type": "string" - }, - "file": { - "description": "Storage file", - "type": "string" - }, - "filename": { - "description": "Original filename", - "type": "string" - }, - "height": { - "description": "Height in pixels", - "type": "integer" - }, - "id": { - "description": "Variant ID", - "type": "string" - }, - "image_source": { - "$ref": "#/components/schemas/ImageSource", - "description": "Image source metadata" - }, - "updated_at": { - "description": "Last update timestamp", - "format": "date-time", - "type": "string" + "data": { + "$ref": "#/components/schemas/ChatRoomModel", + "description": "Updated chat-room snapshot including the newly-loaded messages" + } + }, + "required": [ + "data" + ], + "type": "object" + }, + "ChatMarkThreadReadResponse": { + "description": "Reply payload for the `api:chat:mark_thread_read` channel message —\nconfirms the read marker landed.\n", + "properties": { + "success": { + "description": "Always true on a successful mark-as-read", + "type": "boolean" + } + }, + "required": [ + "success" + ], + "type": "object" + }, + "ChatMember": { + "description": "API schema for a chat member (user or agent).", + "properties": { + "agent": { + "$ref": "#/components/schemas/Agent", + "description": "Agent object (for agent members)" }, - "url": { - "description": "Signed download URL", + "membership_type": { + "description": "Membership type", "type": "string" }, - "variant_key": { - "description": "Variant key (original, thumbnail, etc)", + "type": { + "description": "Member type (user or agent)", "type": "string" }, - "width": { - "description": "Width in pixels", - "type": "integer" + "user": { + "$ref": "#/components/schemas/User", + "description": "User object (for user members)" } }, "required": [ - "id" + "type" ], "type": "object" }, - "Message": { - "description": "API schema for a chat message.", + "ChatMessageListResponse": { + "description": "Reply payload for the `api:chat:list_messages` channel message — the\nmessages currently loaded for the joined thread.\n", "properties": { - "actors": { - "description": "Message actors", + "messages": { + "description": "Messages in the thread", "items": { - "$ref": "#/components/schemas/Actor" + "$ref": "#/components/schemas/Message" }, "type": "array" + } + }, + "required": [ + "messages" + ], + "type": "object" + }, + "ChatPostMessageResponse": { + "description": "Reply payload for the `api:chat:post_message` and\n`api:chat:post_simple_message` channel messages — the persisted\nmessage echoed back to the sender.\n", + "properties": { + "message": { + "$ref": "#/components/schemas/Message", + "description": "The newly-persisted message" + } + }, + "required": [ + "message" + ], + "type": "object" + }, + "ChatRoomModel": { + "description": "Rendered snapshot of a chat room — the rich client-side state used to\npaint a thread's message list, member roster, and pagination cursors.\n\nEmitted as the `data` payload of `load_more_messages` and the\n`chat_model` of `fork_thread`. Mirrors the shape produced by\n`ChatChannelImpl.render_chat_room_model/2`, which is the single\nsource of truth for this serialization.\n", + "properties": { + "after_cursor": { + "description": "Cursor for paging later messages (nil when at the head of history)", + "type": "string" }, "agent": { - "description": "Agent if sent by an agent user", + "$ref": "#/components/schemas/Agent", + "description": "Acting agent — reserved; nil today" + }, + "before_cursor": { + "description": "Cursor for paging earlier messages (nil when at the start of history)", "type": "string" }, - "attachments": { - "description": "Message attachments", + "is_transient": { + "description": "Whether this thread is ephemeral (transient threads are not persisted long-term)", + "type": "boolean" + }, + "members": { + "description": "Active members of the chat room", "items": { - "$ref": "#/components/schemas/Attachment" + "$ref": "#/components/schemas/ChatMember" }, "type": "array" }, - "branched_thread": { - "description": "Branched thread (if message spawned a thread)", - "type": "string" + "messages": { + "description": "Messages currently loaded for the thread", + "items": { + "$ref": "#/components/schemas/Message" + }, + "type": "array" }, - "content": { - "description": "Message content", + "messages_loaded_on_last_update": { + "description": "Number of messages added in the most recent update batch", + "type": "integer" + }, + "team": { + "$ref": "#/components/schemas/Team", + "description": "Owning team — nil for user-scoped threads" + }, + "thread": { + "$ref": "#/components/schemas/Thread", + "description": "The thread this snapshot is for" + } + }, + "required": [ + "messages", + "members", + "thread", + "is_transient" + ], + "type": "object" + }, + "ComputerExecResult": { + "description": "Result of executing a command on an agent computer.", + "properties": { + "exit_code": { + "description": "Process exit code", + "type": "integer" + }, + "output": { + "description": "Command output", + "type": "string" + } + }, + "type": "object" + }, + "Config": { + "description": "API schema for a config resource.", + "properties": { + "agent": { + "description": "Agent", "type": "string" }, "created_at": { @@ -2103,63 +2413,49 @@ "format": "date-time", "type": "string" }, - "has_replies": { - "description": "Whether message has replies", - "type": "boolean" + "current_version": { + "$ref": "#/components/schemas/ConfigVersion", + "description": "Current version" }, "id": { - "description": "Message ID (msg_...)", + "description": "Config ID (cfg_...)", "type": "string" }, - "idempotency_key": { - "description": "Client-provided idempotency key", + "is_archived": { + "description": "Whether config is archived", + "type": "boolean" + }, + "kind": { + "description": "Config kind (e.g., Agent, APITool)", "type": "string" }, - "legacy_agent": { - "description": "Legacy agent if sent by legacy chat agent", + "lookup_key": { + "description": "Optional lookup key", "type": "string" }, - "metadata": { - "description": "Message metadata", - "type": "object" + "mime_type": { + "description": "Content mime type", + "type": "string" }, "org": { "description": "Organization", "type": "string" }, - "reactions": { - "description": "Message reactions", - "items": { - "$ref": "#/components/schemas/MessageReaction" - }, - "type": "array" - }, - "rendering_mode": { - "description": "Rendering mode hint", + "parent": { + "description": "Parent config ID (bundle children only)", "type": "string" }, - "replies": { - "description": "Inline replies (if loaded)", - "items": { - "type": "object" - }, - "type": "array" - }, - "replies_after_cursor": { - "description": "Cursor for replies pagination", + "parent_solution": { + "description": "Solution config ID this config was imported with", "type": "string" }, - "replies_before_cursor": { - "description": "Cursor for replies pagination", + "raw_content": { + "description": "Raw file content (system configs only)", "type": "string" }, - "reply_count": { - "description": "Number of replies", - "type": "integer" - }, - "reply_to": { - "description": "Parent message object (if loaded)", - "type": "object" + "relative_path": { + "description": "Path within parent bundle (bundle children only)", + "type": "string" }, "sandbox": { "description": "Sandbox identifier", @@ -2169,242 +2465,202 @@ "description": "Team", "type": "string" }, - "thread": { - "description": "Parent thread", + "updated_at": { + "description": "Last update timestamp", + "format": "date-time", "type": "string" }, "user": { - "description": "Author user (public ID or expanded object when loaded)", + "description": "User", + "type": "string" + }, + "virtual_path": { + "description": "Unique path within the team", "type": "string" } }, "required": [ - "id" + "id", + "kind" ], "type": "object" }, - "MessageReaction": { - "description": "Schema for inline message reactions.\n\nThis is the compact format used in Message.reactions[], which differs from\nthe full Reaction schema used in standalone reaction endpoints.\nMaps to format_reactions_for_client/1 output.\n", + "ConfigFacets": { + "description": "Response shape for the configs and system-configs facets endpoints.\n\nReturns the distinct kinds and leading path-prefixes (with counts) for\nthe viewer's full scoped dataset — independent of any list-endpoint\nfilters — so the filter UI on the developer portal can populate its\ndropdowns with every option the viewer could pick, not just the values\non the current page.\n", "properties": { - "payload": { - "description": "Reaction payload (e.g., {emoji: '👍'})", - "type": "object" - }, - "type": { - "description": "Reaction type (e.g., emoji_reaction)", - "type": "string" + "kinds": { + "description": "Distinct kinds (with counts) the viewer has configs of", + "items": { + "$ref": "#/components/schemas/ConfigKindFacet" + }, + "type": "array" }, - "user": { - "description": "User who added the reaction", - "type": "string" + "path_prefixes": { + "description": "Distinct leading slash-terminated path prefixes (with counts) for the viewer's configs", + "items": { + "$ref": "#/components/schemas/ConfigPathPrefixFacet" + }, + "type": "array" } }, "required": [ - "type" + "kinds", + "path_prefixes" ], "type": "object" }, - "OAuthTokenResponse": { - "description": "API schema for OAuth token endpoint responses.", + "ConfigKindFacet": { + "description": "A single kind facet row: a distinct config `kind` value paired with the\nnumber of configs the viewer has in that kind. Used by the configs and\ntemplates facets endpoints to populate the Kind filter dropdown with\ncounts.\n", "properties": { - "access_token": { - "description": "OAuth access token", - "type": "string", - "x-sdk": "access_token" - }, - "expires_in": { - "description": "Token TTL in seconds", - "type": "integer", - "x-sdk": "token_expiry" - }, - "refresh_token": { - "description": "OAuth refresh token", - "type": "string", - "x-sdk": "refresh_token" - }, - "scope": { - "description": "Granted scopes (space-separated)", - "type": "string" + "count": { + "description": "Number of configs of this kind visible to the viewer (>= 0)", + "type": "integer" }, - "token_type": { - "description": "Token type (Bearer)", + "kind": { + "description": "The config kind name (e.g., `Agent`, `WorkflowGraph`)", "type": "string" - }, - "user": { - "$ref": "#/components/schemas/User", - "description": "Authenticated user" } }, "required": [ - "access_token", - "token_type", - "expires_in" + "kind", + "count" ], "type": "object" }, - "PaginatedReplies": { - "description": "Schema for paginated message replies response.\n\nUsed by message replies list endpoints.\nNote: This response is NOT wrapped in a \"data\" field.\n", + "ConfigKindSchema": { + "description": "Schema for a config kind's JSON schema and sample response.\n", "properties": { - "after_cursor": { - "description": "Cursor for fetching items after this point", - "type": "string" + "json_schema": { + "description": "JSON Schema for this config kind (can be null if not available)", + "type": "object" }, - "before_cursor": { - "description": "Cursor for fetching items before this point", + "kind": { + "description": "The config kind name", "type": "string" }, - "has_more": { - "description": "Whether more replies exist beyond the current page", - "type": "boolean" - }, - "replies": { - "description": "List of reply message objects", - "items": { - "$ref": "#/components/schemas/Message" - }, - "type": "array" - }, - "total_count": { - "description": "Total number of replies", - "type": "integer" + "sample_yaml": { + "description": "Sample YAML content for this config kind (can be null if not available)", + "type": "string" } }, "required": [ - "replies" + "kind" ], "type": "object" }, - "PresetConfig": { - "description": "API schema for preset handler configuration.\n\nMirrors `ArchAstro.Agents.Routines.PresetConfig`. Used wherever a request\nor response carries a preset config — routine-level and chain-step-level.\n\nServer-side validation (length/format rules on `instructions`, enum checks\non `session_mode`/`session_scope`, model lookup against\n`ChatCompletion.models/0`) is authoritative. This schema defines the\nrequest shape and typed response shape so OpenAPI consumers see real\ntypes instead of an opaque object.\n", + "ConfigPathPrefixFacet": { + "description": "A single path-prefix facet row: a distinct leading slash-terminated\nsegment of `virtual_path` (e.g. `agents/`) paired with the number of\nconfigs the viewer has under that prefix. Used by the configs and\ntemplates facets endpoints to populate the Path filter dropdown.\n", "properties": { - "instructions": { - "description": "Custom task or behavior instructions for the preset (max 10,000 chars).", - "type": "string" - }, - "llm": { - "$ref": "#/components/schemas/LLMConfig", - "description": "LLM invocation settings (e.g. a `model` override for this routine/step)." - }, - "session_mode": { - "description": "Session mode: `stateless` (default, new session per trigger) or `session` (find-or-create a persistent session scoped by `session_scope`).", - "type": "string" + "count": { + "description": "Number of configs under this prefix visible to the viewer (>= 0)", + "type": "integer" }, - "session_scope": { - "description": "When `session_mode` is `session`, controls session scoping: `per_user` (default), `per_key`, `per_org`, or `global`.", + "prefix": { + "description": "Leading path segment, slash-terminated (e.g. `agents/`, `__editor/`)", "type": "string" - }, - "structured_message_template_ids": { - "description": "Config IDs of AgentMessageSchema templates that constrain the agent's responses to predefined structured formats.", - "items": { - "type": "string" - }, - "type": "array" } }, + "required": [ + "prefix", + "count" + ], "type": "object" }, - "RoutinePreset": { - "description": "A routine preset entry in the preset listing endpoint. Describes *what*\na preset is, not a per-routine configuration — that's `PresetConfig`.\n", + "ConfigVersion": { + "description": "API schema for a config version.", "properties": { - "applicable_events": { - "description": "Event types this preset accepts. `[\"*\"]` means any event. Other event types are rejected at routine validation time.", - "items": { - "type": "string" - }, - "type": "array" + "change_description": { + "description": "Description of changes", + "type": "string" }, - "chainable": { - "description": "Whether this preset may appear as a step inside a `:chain` routine. Presets with session or async execution models are not chainable.", - "type": "boolean" + "content_hash": { + "description": "sha256: over UTF-8 bytes of raw_content. Same format as the CLI's computeContentHash. Nullable for rows that predate the column.", + "type": "string" }, - "description": { - "description": "Preset description", + "created_at": { + "description": "Creation timestamp", + "format": "date-time", "type": "string" }, - "label": { - "description": "Display label", + "data": { + "description": "Additional structured data", + "type": "object" + }, + "id": { + "description": "Config version ID (cfv_...)", "type": "string" }, - "name": { - "description": "Preset name (e.g. do_task)", + "org": { + "description": "Organization", "type": "string" }, - "sessionable": { - "description": "Whether this preset maintains a persistent chatroom session across turns (e.g. `participate`). Sessionable presets don't expose instructions or session-mode fields at the routine level.", - "type": "boolean" + "sandbox": { + "description": "Sandbox", + "type": "string" }, - "unique": { - "description": "Whether only one routine with this preset may exist per agent. Enforced at the AgentRoutine unique-index layer.", - "type": "boolean" + "version_number": { + "description": "Version number", + "type": "integer" } }, "required": [ - "name", - "label", - "description", - "applicable_events", - "sessionable", - "unique", - "chainable" + "id", + "version_number" ], "type": "object" }, - "Team": { - "description": "API schema for a team.", + "ContextDocument": { + "description": "Schema for a context document (`Context.Doc`).\n\nCarries metadata only — full text is returned by the `/content` endpoint.\n", "properties": { - "acl": { - "$ref": "#/components/schemas/Acl", - "description": "Access control list. Contains grants array with principal_type, principal, and actions. Null when no ACL restrictions are applied." - }, - "app": { - "description": "Application", + "agent": { + "description": "Owning agent user", "type": "string" }, - "badges": { - "description": "Badge counts by category", - "type": "object" - }, "created_at": { - "description": "Creation timestamp", + "description": "Created timestamp", "format": "date-time", "type": "string" }, - "description": { - "description": "Team description", + "file": { + "description": "Backing file ID (`fil_...`) when file-backed; nil for inline", "type": "string" }, "id": { - "description": "Team ID", - "type": "string" - }, - "membership_status": { - "description": "Viewer's membership role (owner, admin, member) or null if not a member", + "description": "Public ID (cdo_...)", "type": "string" }, "metadata": { - "description": "Team metadata", + "description": "Per-doc metadata", "type": "object" }, - "name": { - "description": "Team name", + "source": { + "description": "Source ID (cs_...)", "type": "string" }, - "org": { - "description": "Organization", + "team": { + "description": "Owning team", "type": "string" }, - "sandbox": { - "description": "Sandbox", + "title": { + "description": "Display title", "type": "string" }, - "slug": { - "description": "URL slug", - "type": "string" + "total_lines": { + "description": "Line count of `Doc.content`", + "type": "integer" + }, + "total_size": { + "description": "Byte size of `Doc.content`", + "type": "integer" }, "updated_at": { - "description": "Last update timestamp", + "description": "Updated timestamp", "format": "date-time", "type": "string" + }, + "user": { + "description": "Owning user", + "type": "string" } }, "required": [ @@ -2412,72 +2668,180 @@ ], "type": "object" }, - "TeamInvite": { - "description": "Schema for a team invite response.\n", + "ContextDocumentContent": { + "description": "Response schema for the context document content endpoint.\n\nReturns the full text of a `Context.Doc` (file-backed or inline) — or a\nslice when `offset`/`limit`/`unit` are given. The slice unit is `lines`\n(default) or `bytes`; `start_*`/`end_*` fields are populated only for\nthe matching unit.\n", "properties": { - "code": { - "description": "6-character invite code", + "content": { + "description": "Document text (full or sliced)", + "type": "string" + }, + "end_byte": { + "description": "Last byte returned, exclusive (bytes unit only)", + "type": "integer" + }, + "end_line": { + "description": "Last line returned, exclusive (lines unit only)", + "type": "integer" + }, + "id": { + "description": "Document public ID (cdo_...)", + "type": "string" + }, + "limit": { + "description": "Echoed limit when given", + "type": "integer" + }, + "metadata": { + "description": "Per-doc metadata", + "type": "object" + }, + "offset": { + "description": "Echoed offset when given", + "type": "integer" + }, + "start_byte": { + "description": "First byte returned (bytes unit only)", + "type": "integer" + }, + "start_line": { + "description": "First line returned (lines unit only)", + "type": "integer" + }, + "title": { + "description": "Display title", + "type": "string" + }, + "total_lines": { + "description": "Full line count of the document's content", + "type": "integer" + }, + "total_size": { + "description": "Full byte size of the document's content", + "type": "integer" + }, + "unit": { + "description": "Slice unit when offset/limit was given: `lines` or `bytes`", "type": "string" } }, "required": [ - "code" + "id", + "content", + "total_size", + "total_lines" ], "type": "object" }, - "TeamMembership": { - "description": "API schema for a team membership.", + "ContextIngestion": { + "description": "Schema for a context ingestion (`Context.Ingestion`).\n", "properties": { "agent": { - "$ref": "#/components/schemas/Agent", - "description": "Agent object (when loaded)" + "description": "Agent", + "type": "string" }, - "created_at": { - "description": "Creation timestamp", + "completed_at": { + "description": "Completed timestamp", "format": "date-time", "type": "string" }, - "id": { - "description": "Membership ID", + "created_at": { + "description": "Created timestamp", + "format": "date-time", "type": "string" }, - "joined_at": { - "description": "Join timestamp", - "format": "date-time", + "error": { + "description": "Error details (if failed)", + "type": "object" + }, + "id": { + "description": "Public ID (cig_...)", "type": "string" }, "metadata": { - "description": "Membership metadata", + "description": "Additional metadata", "type": "object" }, - "name": { - "description": "Member name", + "source": { + "description": "Source ID", "type": "string" }, - "profile_picture": { - "$ref": "#/components/schemas/ImageSource", - "description": "Profile picture" + "started_at": { + "description": "Started timestamp", + "format": "date-time", + "type": "string" }, - "role": { - "description": "Role in team", + "status": { + "description": "Status (pending, running, awaiting_callback, succeeded, failed)", "type": "string" }, "team": { - "description": "Team object (when loaded)", - "type": "object" + "description": "Owning team ID", + "type": "string" }, - "type": { - "description": "Member type (user, agent, unknown)", + "updated_at": { + "description": "Updated timestamp", + "format": "date-time", + "type": "string" + }, + "user": { + "description": "Owning user ID", + "type": "string" + } + }, + "required": [ + "id", + "status" + ], + "type": "object" + }, + "CustomObject": { + "description": "API schema for a custom object.", + "properties": { + "created_at": { + "description": "Created timestamp", + "format": "date-time", + "type": "string" + }, + "fields": { + "description": "Object field values", + "type": "object" + }, + "id": { + "description": "Public ID (cobj_...)", + "type": "string" + }, + "org": { + "description": "Organization", + "type": "string" + }, + "row_key": { + "description": "Row key", + "type": "string" + }, + "sandbox": { + "description": "Sandbox identifier", + "type": "string" + }, + "schema_type": { + "description": "Schema type (lookup_key)", + "type": "string" + }, + "team": { + "description": "Owning team", "type": "string" }, "updated_at": { - "description": "Last update timestamp", + "description": "Updated timestamp", "format": "date-time", "type": "string" }, "user": { - "$ref": "#/components/schemas/User", - "description": "User object (when loaded)" + "description": "Owning user", + "type": "string" + }, + "version": { + "description": "Aggregate version for OCC", + "type": "integer" } }, "required": [ @@ -2485,13 +2849,13 @@ ], "type": "object" }, - "TeamMembershipListResponse": { - "description": "Paginated list response for team memberships.", + "CustomObjectListResponse": { + "description": "Paginated list response for custom objects.", "properties": { "data": { - "description": "List of team memberships", + "description": "List of custom objects", "items": { - "$ref": "#/components/schemas/TeamMembership" + "$ref": "#/components/schemas/CustomObject" }, "type": "array" }, @@ -2504,7 +2868,7 @@ "type": "boolean" }, "page": { - "description": "Current page number", + "description": "Current page (1-indexed)", "type": "integer" }, "page_size": { @@ -2512,155 +2876,188 @@ "type": "integer" }, "total_entries": { - "description": "Total number of entries", + "description": "Total matching entries", "type": "integer" }, "total_pages": { - "description": "Total number of pages", + "description": "Total page count", "type": "integer" } }, "required": [ - "data" + "data", + "page", + "page_size", + "total_entries", + "total_pages", + "has_next", + "has_prev" ], "type": "object" }, - "Thread": { - "description": "API schema for a chat thread.", + "CustomObjectUpdateFieldsResponse": { + "description": "Reply payload for the `update_fields` channel message on\n`ApiObjectChannel` — echoes the object's public id and the fields that\nwere merged in.\n", "properties": { - "agent_user": { - "description": "Owning agent user", - "type": "string" - }, - "created_at": { - "description": "Creation timestamp", - "format": "date-time", - "type": "string" - }, - "creator": { - "$ref": "#/components/schemas/User", - "description": "Creator user object" - }, - "description": { - "description": "Thread description", - "type": "string" + "fields": { + "description": "Updated field values keyed by field name", + "type": "object" }, "id": { - "description": "Thread ID (thr_...)", + "description": "Custom object public ID (cob_...)", + "type": "string" + } + }, + "required": [ + "id", + "fields" + ], + "type": "object" + }, + "DeviceAuthorizationResponse": { + "description": "API schema for OAuth device authorization responses.", + "properties": { + "device_code": { + "description": "Device verification code", "type": "string" }, - "is_channel": { - "description": "Whether this is a channel", - "type": "boolean" - }, - "is_default": { - "description": "Whether this is the default thread", - "type": "boolean" - }, - "is_transient": { - "description": "Whether this thread is transient", - "type": "boolean" + "expires_in": { + "description": "TTL in seconds", + "type": "integer" }, - "is_unlisted": { - "description": "Whether this thread is unlisted", - "type": "boolean" + "interval": { + "description": "Polling interval in seconds", + "type": "integer" }, - "key": { - "description": "Thread key", + "user_code": { + "description": "User-facing verification code", "type": "string" }, - "last_activity": { - "description": "Last activity timestamp", - "format": "date-time", + "verification_uri": { + "description": "Base verification URI", "type": "string" }, - "metadata": { - "description": "Thread metadata", - "type": "object" - }, - "org": { - "description": "Organization", + "verification_uri_complete": { + "description": "Full verification URI with code", "type": "string" - }, - "parent_message": { - "$ref": "#/components/schemas/Message", - "description": "Parent message object" - }, - "participant": { - "description": "Participant users", - "items": { - "type": "string" - }, - "type": "array" - }, - "participants": { - "description": "Participant user objects", + } + }, + "required": [ + "device_code", + "user_code", + "verification_uri", + "verification_uri_complete", + "expires_in", + "interval" + ], + "type": "object" + }, + "DeviceAuthorizationStatusResponse": { + "description": "API schema for OAuth device authorization approval and denial responses.", + "properties": { + "status": { + "description": "Authorization status (approved or denied)", + "type": "string" + } + }, + "required": [ + "status" + ], + "type": "object" + }, + "HealthActionListResponse": { + "description": "List response for agent_health_actions.", + "properties": { + "data": { + "description": "List of agent health actions", "items": { - "$ref": "#/components/schemas/User" + "$ref": "#/components/schemas/AgentHealthAction" }, "type": "array" + } + }, + "required": [ + "data" + ], + "type": "object" + }, + "ImageSource": { + "description": "API schema for image source metadata.", + "properties": { + "file": { + "description": "Storage file", + "type": "string" }, - "participating_actor": { - "description": "Actors participating in thread", - "items": { - "type": "string" - }, - "type": "array" + "height": { + "description": "Image height in pixels", + "type": "integer" }, - "participating_agents": { - "description": "Agents participating in thread", - "items": { - "$ref": "#/components/schemas/Agent" - }, - "type": "array" + "media": { + "description": "Media", + "type": "string" }, - "role": { - "description": "User's role in the thread", + "mime_type": { + "description": "Image MIME type", "type": "string" }, - "sandbox": { - "description": "Sandbox identifier", + "refresh_url": { + "description": "URL to refresh signed URL", "type": "string" }, - "settings": { - "$ref": "#/components/schemas/ThreadSettings", - "description": "Thread settings" + "url": { + "description": "Image URL", + "type": "string" }, - "slug": { - "description": "Thread slug", + "width": { + "description": "Image width in pixels", + "type": "integer" + } + }, + "type": "object" + }, + "Installation": { + "description": "API schema for an installation.", + "properties": { + "agent": { + "description": "Owning agent", "type": "string" }, - "sub_threads": { - "description": "Sub-threads", - "items": { - "type": "object" - }, - "type": "array" + "config": { + "description": "Configuration", + "type": "object" }, - "team": { - "description": "Owning team", + "created_at": { + "description": "Creation timestamp", + "format": "date-time", "type": "string" }, - "title": { - "description": "Thread title", + "id": { + "description": "Installation ID (cin_...)", "type": "string" }, - "ttl": { - "description": "Time-to-live in seconds", - "type": "integer" + "kind": { + "description": "Installation kind", + "type": "string" }, - "unread_count": { - "description": "Unread message count", - "type": "integer" + "lookup_key": { + "description": "Optional stable identifier", + "type": "string" + }, + "shared_integration": { + "description": "Bound shared integration", + "type": "string" + }, + "state": { + "description": "Installation state", + "type": "string" + }, + "status_payload": { + "description": "Status payload", + "type": "object" }, "updated_at": { "description": "Last update timestamp", "format": "date-time", "type": "string" - }, - "user": { - "description": "Owning user", - "type": "string" } }, "required": [ @@ -2668,120 +3065,135 @@ ], "type": "object" }, - "ThreadMember": { - "description": "API schema for a thread member.", + "InstallationKind": { + "description": "API schema for an installation kind.", "properties": { - "membership_type": { - "description": "Membership type (owner or member)", + "accepts_sources": { + "description": "Whether this kind accepts sources", + "type": "boolean" + }, + "category": { + "description": "Category", "type": "string" }, - "thread": { - "description": "Thread", + "config_schema": { + "description": "JSON schema for configuration", + "type": "object" + }, + "description": { + "description": "Description", "type": "string" }, - "user": { - "$ref": "#/components/schemas/User", - "description": "User details (when loaded)" + "kind": { + "description": "Installation kind identifier", + "type": "string" + }, + "label": { + "description": "Display label", + "type": "string" + }, + "provider": { + "description": "Integration provider", + "type": "string" + }, + "requires_integration": { + "description": "Whether this kind requires an integration", + "type": "boolean" } }, + "required": [ + "kind" + ], "type": "object" }, - "ThreadReadStatus": { - "description": "Schema for thread read status response.\n", + "InstallationKindListResponse": { + "description": "List response for installation kinds.", "properties": { - "last_read_message": { - "description": "Last read message", - "type": "string" - }, - "thread": { - "description": "Thread", - "type": "string" - }, - "unread_count": { - "description": "Number of unread messages", - "type": "integer" + "data": { + "description": "List of installation kinds", + "items": { + "$ref": "#/components/schemas/InstallationKind" + }, + "type": "array" } }, "required": [ - "thread", - "unread_count" + "data" ], "type": "object" }, - "ThreadSettings": { - "description": "Schema for thread settings response.\n\nUsed by thread settings show/update endpoints.\n", + "InstallationListResponse": { + "description": "List response for installations.", "properties": { - "agent_enabled": { - "description": "Whether the agent is enabled for this thread", - "type": "boolean" + "data": { + "description": "List of installations", + "items": { + "$ref": "#/components/schemas/Installation" + }, + "type": "array" } }, + "required": [ + "data" + ], "type": "object" }, - "User": { - "description": "API schema for a user.", + "InstallationSource": { + "description": "API schema for an installation source.", "properties": { - "alias": { - "description": "User alias/handle", + "agent": { + "description": "Owning agent", "type": "string" }, - "email": { - "description": "User email address", + "context_installation": { + "description": "Installation ID", + "type": "string" + }, + "created_at": { + "description": "Creation timestamp", + "format": "date-time", "type": "string" }, "id": { - "description": "User ID", + "description": "Source ID (cso_...)", "type": "string" }, "metadata": { - "description": "User metadata", + "description": "Arbitrary metadata", "type": "object" }, - "name": { - "description": "User display name", + "parent_source": { + "description": "Parent source ID", "type": "string" }, - "org": { - "description": "Organization", - "type": "string" + "payload": { + "description": "Source payload", + "type": "object" }, - "sandbox": { - "description": "Sandbox", - "type": "string" - } - }, - "required": [ - "id" - ], - "type": "object" - }, - "UserInvite": { - "description": "API schema for a user invite.", - "properties": { - "created_at": { - "description": "Creation timestamp", - "format": "date-time", + "state": { + "description": "Source state", "type": "string" }, - "id": { - "description": "Invite ID (uin_...)", + "team": { + "description": "Team ID", "type": "string" }, - "key": { - "description": "Invite key", + "thread": { + "description": "Thread ID", "type": "string" }, - "metadata": { - "description": "Invite metadata", - "type": "object" + "type": { + "description": "Source type", + "type": "string" }, - "thread": { - "description": "Thread", + "updated_at": { + "description": "Last update timestamp", + "format": "date-time", "type": "string" }, "user": { - "$ref": "#/components/schemas/InviteCreator", - "description": "Invite creator" + "description": "User ID", + "type": "string" } }, "required": [ @@ -2789,79 +3201,80 @@ ], "type": "object" }, - "ValidationResult": { - "description": "Schema for config validation result.\n", + "InstallationSourceListResponse": { + "description": "List response for installation sources.", "properties": { - "errors": { - "description": "List of validation errors", - "items": { - "type": "string" - }, - "type": "array" - }, - "valid": { - "description": "Whether the config is valid", - "type": "boolean" - }, - "warnings": { - "description": "Optional warnings emitted during validation", + "data": { + "description": "List of installation sources", "items": { - "type": "string" + "$ref": "#/components/schemas/InstallationSource" }, "type": "array" } }, "required": [ - "valid" + "data" ], "type": "object" }, - "WorkerStatus": { - "description": "API schema for background worker status on a routine run.", + "InstalledConfigEntry": { + "description": "One entry in `AgentCreateResponse.installed_configs` — a slim summary\nof a config the install transaction created.\n\n`key` is the caller-supplied identifier for the input that produced\nthis config. For top-level configs it's the **original** (pre-suffix)\nlookup_key the caller sent. For skill files it's the composite\n`\":\"` since file children have no\nlookup_key of their own. Use it to correlate each entry back to the\nrequest payload.\n\n`lookup_key` is the **stored** lookup_key (with suffix applied) for\nparent-style configs (Skill, Script, AgentTemplate, generic Config).\nFor File children inside a skill it is `null` — those rows have no\nlookup_key, only `(parent_id, relative_path)` uniqueness.\n", "properties": { - "attempt": { - "description": "Current attempt number (0 = not yet attempted)", - "type": "integer" + "id": { + "description": "Config ID (cfg_...)", + "type": "string" }, - "max_attempts": { - "description": "Maximum allowed attempts", - "type": "integer" + "key": { + "description": "Caller-supplied identifier the entry was produced for.", + "type": "string" }, - "status": { - "description": "Worker state: queued, executing, retrying, completed, discarded, or cancelled", + "kind": { + "description": "Config kind (Skill, File, Script, AgentTemplate, ...)", + "type": "string" + }, + "lookup_key": { + "description": "Stored lookup_key (suffix applied). Null for File children.", "type": "string" } }, "required": [ - "status", - "attempt", - "max_attempts" + "key", + "id", + "kind" ], "type": "object" }, - "WorkingMemoryEntry": { - "description": "API schema for a working memory entry.", + "InviteCreator": { + "description": "Minimal public-safe projection of the user who created an invite.\n\nInvites are fetched by unauthenticated recipients on the `/auth/invites/:id`\nroute, so this schema deliberately exposes only the fields needed to render a\njoin screen — id, display name, and profile picture. Email, org, sandbox, and\nother fields on the full `User` schema are omitted.\n", "properties": { - "agent": { - "description": "Owning agent", + "id": { + "description": "User ID", + "type": "string" + }, + "name": { + "description": "Display name. Null when the inviter has not set a name.", "type": "string" }, + "profile_picture": { + "$ref": "#/components/schemas/ImageSource", + "description": "Profile picture" + } + }, + "required": [ + "id" + ], + "type": "object" + }, + "KeyValueStorageEntry": { + "description": "Schema for a key-value storage entry.\n\nMaps exactly to render_entry/1 output in ApiStorageController.\n", + "properties": { "created_at": { "description": "Creation timestamp", "format": "date-time", "type": "string" }, - "expires_at": { - "description": "Expiration timestamp", - "format": "date-time", - "type": "string" - }, - "id": { - "description": "Memory entry ID (amm_...)", - "type": "string" - }, "key": { - "description": "Memory key", + "description": "Storage key", "type": "string" }, "updated_at": { @@ -2869,48 +3282,54 @@ "format": "date-time", "type": "string" }, + "user": { + "description": "User", + "type": "string" + }, "value": { - "description": "Memory value", + "description": "Stored value", "type": "string" } }, "required": [ - "id" + "user", + "key", + "value" ], "type": "object" }, - "WorkingMemoryEntryListResponse": { - "description": "Paginated list response for working memory entries.", + "KeyValueStorageEntryPage": { + "description": "Response envelope for the dual-mode key-value list endpoint.\n\nUser-JWT callers receive `%{data: [...]}` (no pagination fields).\nDeveloper / S2S callers receive `%{data: [...]}` plus pagination metadata.\n", "properties": { "data": { - "description": "List of working memory entries", + "description": "Storage entries on this page", "items": { - "$ref": "#/components/schemas/WorkingMemoryEntry" + "$ref": "#/components/schemas/KeyValueStorageEntryWithUser" }, "type": "array" }, "has_next": { - "description": "Whether a next page exists", + "description": "Whether a next page exists (developer / S2S only)", "type": "boolean" }, "has_prev": { - "description": "Whether a previous page exists", + "description": "Whether a previous page exists (developer / S2S only)", "type": "boolean" }, "page": { - "description": "Current page number", + "description": "Current page number (developer / S2S only)", "type": "integer" }, "page_size": { - "description": "Results per page", + "description": "Results per page (developer / S2S only)", "type": "integer" }, "total_entries": { - "description": "Total number of entries", + "description": "Total entries matching the filters (developer / S2S only)", "type": "integer" }, "total_pages": { - "description": "Total number of pages", + "description": "Total number of pages (developer / S2S only)", "type": "integer" } }, @@ -2918,143 +3337,2172 @@ "data" ], "type": "object" - } - } - }, - "info": { - "description": "Agent-first API for runtime + developer control-plane operations (users, teams, agents, routines, context, workflows, integrations, and webhooks).", - "title": "ArchAstro Platform API", - "version": "v1" - }, - "openapi": "3.0.0", - "paths": { - "/api/v1/activity_feed": { - "get": { - "operationId": "get_api_v1_activity_feed", - "parameters": [ - { - "description": "Filter by kind (routine_run, automation_run, generic)", - "in": "query", - "name": "kind", - "required": false, - "schema": { - "items": { - "type": "string" - }, - "type": "array" - } + }, + "KeyValueStorageEntryWithUser": { + "description": "Schema for a key-value storage entry, optionally enriched with a summary of\nthe owning user.\n\nUsed by the dual-mode list endpoint: user-JWT callers omit the user_email /\nuser_name fields (they know who they are); developer / S2S callers populate\nthem so the portal can render an owner column without a per-row lookup.\n", + "properties": { + "created_at": { + "description": "Creation timestamp", + "format": "date-time", + "type": "string" }, - { - "description": "Filter by level (debug, info, warn, error, audit)", - "in": "query", - "name": "level", - "required": false, - "schema": { - "items": { - "type": "string" - }, - "type": "array" - } + "key": { + "description": "Storage key", + "type": "string" }, - { - "description": "Filter by agent IDs", - "in": "query", - "name": "agent", - "required": false, - "schema": { - "items": { - "type": "string" - }, - "type": "array" - } + "updated_at": { + "description": "Last update timestamp", + "format": "date-time", + "type": "string" }, - { - "description": "Filter by thread IDs", - "in": "query", - "name": "thread", - "required": false, - "schema": { - "items": { - "type": "string" - }, - "type": "array" - } + "user": { + "description": "User ID", + "type": "string" }, - { - "description": "Filter by organization IDs", - "in": "query", - "name": "org", - "required": false, - "schema": { - "items": { - "type": "string" - }, - "type": "array" - } + "user_email": { + "description": "User email (developer / S2S only)", + "type": "string" }, - { - "description": "Filter by correlation group", - "in": "query", - "name": "correlation_id", - "required": false, - "schema": { - "type": "string" - } + "user_name": { + "description": "User display name (developer / S2S only)", + "type": "string" }, - { - "description": "Maximum number of results (default 50, max 100)", - "in": "query", - "name": "limit", - "required": false, - "schema": { - "type": "integer" - } + "value": { + "description": "Stored value", + "type": "string" + } + }, + "required": [ + "user", + "key", + "value", + "created_at", + "updated_at" + ], + "type": "object" + }, + "KnowledgeSource": { + "description": "Schema for a context source (`Context.Source`).\n", + "properties": { + "agent": { + "description": "Owning agent", + "type": "string" }, - { - "description": "Cursor for fetching older entries", - "in": "query", - "name": "before_cursor", - "required": false, - "schema": { - "type": "string" - } + "context_installation": { + "description": "Associated installation", + "type": "string" }, - { - "description": "Cursor for fetching newer entries", - "in": "query", - "name": "after_cursor", - "required": false, - "schema": { - "type": "string" - } + "created_at": { + "description": "Created timestamp", + "format": "date-time", + "type": "string" + }, + "id": { + "description": "Public ID (cso_...)", + "type": "string" + }, + "metadata": { + "description": "Additional metadata", + "type": "object" + }, + "org": { + "description": "Owning organization", + "type": "string" + }, + "parent_source": { + "description": "Parent source", + "type": "string" + }, + "payload": { + "description": "Type-specific configuration", + "type": "object" + }, + "sandbox": { + "description": "Owning sandbox", + "type": "string" + }, + "state": { + "description": "State: active or paused", + "type": "string" + }, + "team": { + "description": "Owning team", + "type": "string" + }, + "thread": { + "description": "Associated thread", + "type": "string" + }, + "type": { + "description": "Source type (e.g., gmail, github_activity)", + "type": "string" + }, + "updated_at": { + "description": "Updated timestamp", + "format": "date-time", + "type": "string" + }, + "user": { + "description": "Owning user", + "type": "string" } + }, + "required": [ + "id", + "type", + "state" ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "description": "Cursor-paginated list of activity feed entries", - "properties": { - "after_cursor": { - "description": "Cursor for fetching newer entries", - "type": "string" - }, - "before_cursor": { - "description": "Cursor for fetching older entries", - "type": "string" - }, - "data": { - "description": "The entries", - "items": { - "description": "API schema for an activity feed entry.", - "properties": { - "agent": { - "description": "Agent (public ID or expanded object when loaded)", - "oneOf": [ - { - "type": "string" - }, + "type": "object" + }, + "KnowledgeSourceKind": { + "description": "API schema for an allowed knowledge-source kind.", + "properties": { + "description": { + "description": "Description", + "type": "string" + }, + "label": { + "description": "Display label", + "type": "string" + }, + "type": { + "description": "Source type identifier", + "type": "string" + } + }, + "required": [ + "type" + ], + "type": "object" + }, + "KnowledgeSourceKindListResponse": { + "description": "List response for knowledge-source kinds.", + "properties": { + "data": { + "description": "List of knowledge-source kinds creatable via the public API", + "items": { + "$ref": "#/components/schemas/KnowledgeSourceKind" + }, + "type": "array" + } + }, + "required": [ + "data" + ], + "type": "object" + }, + "LLMConfig": { + "description": "API schema for per-routine LLM invocation settings.\n\nMirrors `ArchAstro.Agents.Routines.LLMConfig`. When `model` is present,\nit overrides the agent's `default_model` for the routine (or step).\n", + "properties": { + "model": { + "description": "Model identifier. When set, overrides the agent's default_model.", + "type": "string" + } + }, + "type": "object" + }, + "MediaVariant": { + "description": "API schema for a media variant.", + "properties": { + "content_type": { + "description": "File content type", + "type": "string" + }, + "created_at": { + "description": "Creation timestamp", + "format": "date-time", + "type": "string" + }, + "file": { + "description": "Storage file", + "type": "string" + }, + "filename": { + "description": "Original filename", + "type": "string" + }, + "height": { + "description": "Height in pixels", + "type": "integer" + }, + "id": { + "description": "Variant ID", + "type": "string" + }, + "image_source": { + "$ref": "#/components/schemas/ImageSource", + "description": "Image source metadata" + }, + "updated_at": { + "description": "Last update timestamp", + "format": "date-time", + "type": "string" + }, + "url": { + "description": "Signed download URL", + "type": "string" + }, + "variant_key": { + "description": "Variant key (original, thumbnail, etc)", + "type": "string" + }, + "width": { + "description": "Width in pixels", + "type": "integer" + } + }, + "required": [ + "id" + ], + "type": "object" + }, + "Message": { + "description": "API schema for a chat message.", + "properties": { + "actors": { + "description": "Message actors", + "items": { + "$ref": "#/components/schemas/Actor" + }, + "type": "array" + }, + "agent": { + "description": "Agent if sent by an agent user", + "type": "string" + }, + "attachments": { + "description": "Message attachments", + "items": { + "$ref": "#/components/schemas/Attachment" + }, + "type": "array" + }, + "branched_thread": { + "description": "Branched thread (if message spawned a thread)", + "type": "string" + }, + "content": { + "description": "Message content", + "type": "string" + }, + "created_at": { + "description": "Creation timestamp", + "format": "date-time", + "type": "string" + }, + "has_replies": { + "description": "Whether message has replies", + "type": "boolean" + }, + "id": { + "description": "Message ID (msg_...)", + "type": "string" + }, + "idempotency_key": { + "description": "Client-provided idempotency key", + "type": "string" + }, + "legacy_agent": { + "description": "Legacy agent if sent by legacy chat agent", + "type": "string" + }, + "metadata": { + "description": "Message metadata", + "type": "object" + }, + "org": { + "description": "Organization", + "type": "string" + }, + "reactions": { + "description": "Message reactions", + "items": { + "$ref": "#/components/schemas/MessageReaction" + }, + "type": "array" + }, + "rendering_mode": { + "description": "Rendering mode hint", + "type": "string" + }, + "replies": { + "description": "Inline replies (if loaded)", + "items": { + "type": "object" + }, + "type": "array" + }, + "replies_after_cursor": { + "description": "Cursor for replies pagination", + "type": "string" + }, + "replies_before_cursor": { + "description": "Cursor for replies pagination", + "type": "string" + }, + "reply_count": { + "description": "Number of replies", + "type": "integer" + }, + "reply_to": { + "description": "Parent message object (if loaded)", + "type": "object" + }, + "sandbox": { + "description": "Sandbox identifier", + "type": "string" + }, + "team": { + "description": "Team", + "type": "string" + }, + "thread": { + "description": "Parent thread", + "type": "string" + }, + "user": { + "description": "Author user (public ID or expanded object when loaded)", + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + }, + "MessageReaction": { + "description": "Schema for inline message reactions.\n\nThis is the compact format used in Message.reactions[], which differs from\nthe full Reaction schema used in standalone reaction endpoints.\nMaps to format_reactions_for_client/1 output.\n", + "properties": { + "payload": { + "description": "Reaction payload (e.g., {emoji: '👍'})", + "type": "object" + }, + "type": { + "description": "Reaction type (e.g., emoji_reaction)", + "type": "string" + }, + "user": { + "description": "User who added the reaction", + "type": "string" + } + }, + "required": [ + "type" + ], + "type": "object" + }, + "Notification": { + "description": "API schema for an inbox notification (recipient view).", + "properties": { + "archived_at": { + "description": "When the recipient archived this (nil if not archived)", + "format": "date-time", + "type": "string" + }, + "created_at": { + "description": "When the notification was sent", + "format": "date-time", + "type": "string" + }, + "id": { + "description": "Notification ID (ntf_...)", + "type": "string" + }, + "read_at": { + "description": "When the recipient marked this read (nil if unread)", + "format": "date-time", + "type": "string" + }, + "rendered": { + "description": "Type-specific render spec. All types share `title`, `kind`, and `actions`; bespoke types add their own fields.", + "type": "object" + }, + "status": { + "description": "unread | read | archived", + "type": "string" + }, + "type": { + "description": "Notification type (e.g., app_info, custom:deploy_complete)", + "type": "string" + } + }, + "required": [ + "id", + "type", + "status", + "rendered", + "created_at" + ], + "type": "object" + }, + "NotificationPreference": { + "description": "API schema for a single notification preference row.\n\nThe recipient (`user_id` / `developer_id`) is intentionally omitted —\nevery row returned to a viewer belongs to that viewer, so echoing the\nid back adds noise without information.\n", + "properties": { + "app_id": { + "description": "App scope for the preference (nil = system / no-app slot)", + "type": "string" + }, + "channel": { + "description": "Channel (e.g., \"email\"). `:in_app` is never a preference row.", + "type": "string" + }, + "created_at": { + "description": "Created timestamp", + "format": "date-time", + "type": "string" + }, + "enabled": { + "description": "Whether the channel is enabled for this slot", + "type": "boolean" + }, + "id": { + "description": "Preference ID (ntfp_...)", + "type": "string" + }, + "type": { + "description": "Notification type — wire-format string. Builtins use the atom name (`\"app_info\"`, `\"billing_alert\"`, …); custom types use `\"custom:\"`.", + "type": "string" + }, + "updated_at": { + "description": "Updated timestamp", + "format": "date-time", + "type": "string" + } + }, + "required": [ + "id", + "type", + "channel", + "enabled" + ], + "type": "object" + }, + "NotificationPreferenceList": { + "description": "Schema for a list of notification preferences.", + "properties": { + "data": { + "description": "Notification preferences for the current viewer", + "items": { + "$ref": "#/components/schemas/NotificationPreference" + }, + "type": "array" + } + }, + "required": [ + "data" + ], + "type": "object" + }, + "OAuthTokenResponse": { + "description": "API schema for OAuth token endpoint responses.", + "properties": { + "access_token": { + "description": "OAuth access token", + "type": "string", + "x-sdk": "access_token" + }, + "expires_in": { + "description": "Token TTL in seconds", + "type": "integer", + "x-sdk": "token_expiry" + }, + "refresh_token": { + "description": "OAuth refresh token", + "type": "string", + "x-sdk": "refresh_token" + }, + "scope": { + "description": "Granted scopes (space-separated)", + "type": "string" + }, + "token_type": { + "description": "Token type (Bearer)", + "type": "string" + }, + "user": { + "$ref": "#/components/schemas/User", + "description": "Authenticated user" + } + }, + "required": [ + "access_token", + "token_type", + "expires_in" + ], + "type": "object" + }, + "PaginatedReplies": { + "description": "Schema for paginated message replies response.\n\nUsed by message replies list endpoints.\nNote: This response is NOT wrapped in a \"data\" field.\n", + "properties": { + "after_cursor": { + "description": "Cursor for fetching items after this point", + "type": "string" + }, + "before_cursor": { + "description": "Cursor for fetching items before this point", + "type": "string" + }, + "has_more": { + "description": "Whether more replies exist beyond the current page", + "type": "boolean" + }, + "replies": { + "description": "List of reply message objects", + "items": { + "$ref": "#/components/schemas/Message" + }, + "type": "array" + }, + "total_count": { + "description": "Total number of replies", + "type": "integer" + } + }, + "required": [ + "replies" + ], + "type": "object" + }, + "PresetConfig": { + "description": "API schema for preset handler configuration.\n\nMirrors `ArchAstro.Agents.Routines.PresetConfig`. Used wherever a request\nor response carries a preset config — routine-level and chain-step-level.\n\nServer-side validation (length/format rules on `instructions`, enum checks\non `session_mode`/`session_scope`, model lookup against\n`ChatCompletion.models/0`) is authoritative. This schema defines the\nrequest shape and typed response shape so OpenAPI consumers see real\ntypes instead of an opaque object.\n", + "properties": { + "instructions": { + "description": "Custom task or behavior instructions for the preset (max 10,000 chars).", + "type": "string" + }, + "llm": { + "$ref": "#/components/schemas/LLMConfig", + "description": "LLM invocation settings (e.g. a `model` override for this routine/step)." + }, + "session_mode": { + "description": "Session mode: `stateless` (default, new session per trigger) or `session` (find-or-create a persistent session scoped by `session_scope`).", + "type": "string" + }, + "session_scope": { + "description": "When `session_mode` is `session`, controls session scoping: `per_user` (default), `per_key`, `per_org`, or `global`.", + "type": "string" + }, + "structured_message_template_ids": { + "description": "Config IDs of AgentMessageSchema templates that constrain the agent's responses to predefined structured formats.", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + }, + "RoutinePreset": { + "description": "A routine preset entry in the preset listing endpoint. Describes *what*\na preset is, not a per-routine configuration — that's `PresetConfig`.\n", + "properties": { + "applicable_events": { + "description": "Event types this preset accepts. `[\"*\"]` means any event. Other event types are rejected at routine validation time.", + "items": { + "type": "string" + }, + "type": "array" + }, + "chainable": { + "description": "Whether this preset may appear as a step inside a `:chain` routine. Presets with session or async execution models are not chainable.", + "type": "boolean" + }, + "description": { + "description": "Preset description", + "type": "string" + }, + "label": { + "description": "Display label", + "type": "string" + }, + "name": { + "description": "Preset name (e.g. do_task)", + "type": "string" + }, + "sessionable": { + "description": "Whether this preset maintains a persistent chatroom session across turns (e.g. `participate`). Sessionable presets don't expose instructions or session-mode fields at the routine level.", + "type": "boolean" + }, + "unique": { + "description": "Whether only one routine with this preset may exist per agent. Enforced at the AgentRoutine unique-index layer.", + "type": "boolean" + } + }, + "required": [ + "name", + "label", + "description", + "applicable_events", + "sessionable", + "unique", + "chainable" + ], + "type": "object" + }, + "SolutionCategoryListResponse": { + "description": "Paginated list response for `GET /api/v1/solution_categories`.\n", + "properties": { + "data": { + "description": "Solution category summaries", + "items": { + "$ref": "#/components/schemas/SolutionCategorySummary" + }, + "type": "array" + }, + "has_next": { + "description": "Has next page", + "type": "boolean" + }, + "has_prev": { + "description": "Has previous page", + "type": "boolean" + }, + "page": { + "description": "Current page", + "type": "integer" + }, + "page_size": { + "description": "Results per page", + "type": "integer" + }, + "total_entries": { + "description": "Total entries after key dedupe", + "type": "integer" + }, + "total_pages": { + "description": "Total pages", + "type": "integer" + } + }, + "required": [ + "data", + "page", + "page_size", + "total_entries", + "total_pages", + "has_next", + "has_prev" + ], + "type": "object" + }, + "SolutionCategorySummary": { + "description": "Catalog category definition row for `GET /api/v1/solution_categories`.\n", + "properties": { + "created_at": { + "description": "Creation timestamp", + "format": "date-time", + "type": "string" + }, + "description": { + "description": "Short explanation of the category", + "type": "string" + }, + "id": { + "description": "SolutionCategory config ID (cfg_...)", + "type": "string" + }, + "key": { + "description": "Stable category key referenced by Solution.category_keys", + "type": "string" + }, + "kind": { + "description": "Always \"SolutionCategory\"", + "type": "string" + }, + "lookup_key": { + "description": "Stored lookup_key", + "type": "string" + }, + "metadata": { + "description": "Arbitrary category metadata", + "type": "object" + }, + "name": { + "description": "Display name", + "type": "string" + }, + "org": { + "description": "Organization", + "type": "string" + }, + "owners": { + "description": "Owner scopes this category appears under. Members: `\"system\"` (app-level system scope) and/or `\"org\"` (viewer's org scope).", + "items": { + "type": "string" + }, + "type": "array" + }, + "parent_key": { + "description": "Optional parent SolutionCategory key", + "type": "string" + }, + "sort_order": { + "description": "Optional numeric ordering hint", + "type": "integer" + }, + "updated_at": { + "description": "Last update timestamp", + "format": "date-time", + "type": "string" + }, + "virtual_path": { + "description": "Stored virtual_path", + "type": "string" + } + }, + "required": [ + "id", + "kind", + "key", + "owners" + ], + "type": "object" + }, + "SolutionDependentAgent": { + "description": "One agent that depends on a Solution's bundle, nested under\n`SolutionDependentsResponse`. An agent \"depends\" when it (or one of its\nroutines/skills/tools) references a bundled config.\n", + "properties": { + "id": { + "description": "Agent ID (agi_...).", + "type": "string" + }, + "name": { + "description": "Agent display name. May be null.", + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + }, + "SolutionDependentsResponse": { + "description": "Preview for `GET /api/v1/solutions/:solution/dependents`. Reports what\ndeleting the Solution would do to live agents, without deleting\nanything — used to warn in the delete-confirmation UI.\n\nDeleting a Solution never destroys agents: bundled configs that a live\nagent still references are kept (detached from the Solution) instead of\ndeleted. `preserved_config_count` is how many configs that protection\napplies to; `dependent_agent_count` is how many agents are affected.\n", + "properties": { + "dependent_agent_count": { + "description": "Distinct agents with at least one resource referencing a bundled config.", + "type": "integer" + }, + "dependent_agents": { + "description": "A bounded sample of the dependent agents for display. May be shorter than `dependent_agent_count`.", + "items": { + "$ref": "#/components/schemas/SolutionDependentAgent" + }, + "type": "array" + }, + "preserved_config_count": { + "description": "Bundled configs that would be kept (orphaned) rather than deleted because a live agent still references them.", + "type": "integer" + } + }, + "required": [ + "dependent_agent_count", + "dependent_agents", + "preserved_config_count" + ], + "type": "object" + }, + "SolutionDiffEntry": { + "description": "One row in a Solution upgrade response's `changes` array.\n", + "properties": { + "action": { + "type": "string" + }, + "content_changed": { + "type": "boolean" + }, + "id": { + "type": "string" + }, + "key": { + "type": "string" + }, + "kind": { + "type": "string" + }, + "lookup_key": { + "type": "string" + }, + "mime_type_changed": { + "type": "boolean" + }, + "referenced_by": { + "items": { + "$ref": "#/components/schemas/SolutionDiffReference" + }, + "type": "array" + }, + "relative_path_changed": { + "type": "boolean" + }, + "role": { + "type": "string" + }, + "virtual_path": { + "type": "string" + } + }, + "required": [ + "role", + "action", + "key", + "content_changed", + "mime_type_changed", + "relative_path_changed" + ], + "type": "object" + }, + "SolutionDiffReference": { + "description": "External reference to an orphaned config in a Solution upgrade diff.\n", + "properties": { + "id": { + "type": "string" + }, + "kind": { + "type": "string" + }, + "lookup_key": { + "type": "string" + }, + "reason": { + "type": "string" + } + }, + "required": [ + "id", + "kind", + "reason" + ], + "type": "object" + }, + "SolutionDiffSummary": { + "description": "Summary counts for a Solution upgrade diff.\n", + "properties": { + "adds": { + "type": "integer" + }, + "deletes": { + "type": "integer" + }, + "noops": { + "type": "integer" + }, + "orphans": { + "type": "integer" + }, + "referenced_orphans": { + "type": "integer" + }, + "updates": { + "type": "integer" + } + }, + "required": [ + "adds", + "updates", + "noops", + "orphans", + "deletes", + "referenced_orphans" + ], + "type": "object" + }, + "SolutionImportResponse": { + "description": "Response shape for `POST /api/v1/solutions` (import). The Solution\nconfig row plus an `installed_configs` array summarising every config\nthe import transaction persisted alongside it (Solution, skills,\nscripts, routine templates, message schemas, etc.).\n\nPairs with `SolutionInstallResponse` — import puts a Solution into\nthe library, install provisions a runtime resource (Agent etc.)\nfrom an already-imported Solution.\n", + "properties": { + "created_at": { + "description": "Creation timestamp", + "format": "date-time", + "type": "string" + }, + "id": { + "description": "Solution config ID (cfg_...)", + "type": "string" + }, + "import_result": { + "$ref": "#/components/schemas/SolutionImportResult", + "description": "Import result" + }, + "installed_configs": { + "description": "Deprecated legacy field. One entry per persisted config in the import (including the Solution itself), defaulting to an empty array. Callers should prefer `solution` plus follow-up APIs instead. `key` echoes the caller-supplied input identifier (original lookup_key for top-level configs; `:` for skill / solution-file children). Order is stable: sorted by `key`.", + "items": { + "$ref": "#/components/schemas/InstalledConfigEntry" + }, + "type": "array" + }, + "kind": { + "description": "Always \"Solution\"", + "type": "string" + }, + "lookup_key": { + "description": "Stored lookup_key (suffix applied)", + "type": "string" + }, + "solution": { + "$ref": "#/components/schemas/SolutionSummary", + "description": "Imported Solution in the same shape returned by GET /api/v1/solutions/:solution" + }, + "updated_at": { + "description": "Last update timestamp", + "format": "date-time", + "type": "string" + }, + "virtual_path": { + "description": "Stored virtual_path", + "type": "string" + } + }, + "required": [ + "id", + "kind", + "solution", + "import_result" + ], + "type": "object" + }, + "SolutionImportResult": { + "description": "Machine-readable result for Solution imports.\n\nDry-run callers use this to decide whether the import can proceed as\na normal create/update or needs a dedicated upgrade path.\n", + "properties": { + "code": { + "description": "Conflict code, if status is conflict", + "type": "string" + }, + "dry_run": { + "description": "Whether this result came from dry_run", + "type": "boolean" + }, + "existing_solution_version": { + "description": "Existing library Solution version", + "type": "string" + }, + "incoming_solution_version": { + "description": "Incoming bundle Solution version", + "type": "string" + }, + "message": { + "description": "Human-readable status detail", + "type": "string" + }, + "status": { + "description": "\"ready\" when import can proceed; \"conflict\" when upgrade flow is required", + "type": "string" + }, + "upgrade_required": { + "description": "Whether upgrade flow is required", + "type": "boolean" + } + }, + "required": [ + "status", + "dry_run", + "upgrade_required" + ], + "type": "object" + }, + "SolutionInstallResponse": { + "description": "Response shape for `POST /api/v1/solutions/:solution/install`.\n\nInstall provisions a runtime resource from an already-imported\nSolution — the kind of resource depends on what the Solution wraps\n(AgentTemplate → Agent, AutomationTemplate → Automation,\nAgentRoutineTemplate → AgentRoutine, AgentToolTemplate → AgentTool,\nAgentSkillTemplate → AgentSkill, AgentComputerTemplate → AgentComputer).\nThe response carries that resource's id + kind + lookup_key, plus a\nback-pointer to the source Solution.\n\nPairs with `SolutionImportResponse` — import puts a Solution into\nthe library; install provisions runtime resources from it.\n", + "properties": { + "id": { + "description": "Provisioned resource public id (`agi_…`, `aut_…`, `art_…`, `att_…`, `ask_…`, `cmp_…`)", + "type": "string" + }, + "kind": { + "description": "Kind of the provisioned resource: Agent, Automation, AgentRoutine, AgentTool, AgentSkill, or AgentComputer", + "type": "string" + }, + "lookup_key": { + "description": "Lookup_key stamped on the provisioned resource (null for AgentSkill, which is a join row with no lookup_key of its own)", + "type": "string" + }, + "solution": { + "description": "Source Solution config id (cfg_…) the install was provisioned from", + "type": "string" + } + }, + "required": [ + "id", + "kind", + "solution" + ], + "type": "object" + }, + "SolutionListResponse": { + "description": "Paginated list response for `GET /api/v1/solutions`. Each entry is a\n`SolutionSummary` — see that module for the per-row shape, owner\nsemantics, and dedupe rules.\n", + "properties": { + "data": { + "description": "Solution summaries", + "items": { + "$ref": "#/components/schemas/SolutionSummary" + }, + "type": "array" + }, + "has_next": { + "description": "Has next page", + "type": "boolean" + }, + "has_prev": { + "description": "Has previous page", + "type": "boolean" + }, + "page": { + "description": "Current page", + "type": "integer" + }, + "page_size": { + "description": "Results per page", + "type": "integer" + }, + "total_entries": { + "description": "Total entries (post-dedupe)", + "type": "integer" + }, + "total_pages": { + "description": "Total pages", + "type": "integer" + } + }, + "required": [ + "data", + "page", + "page_size", + "total_entries", + "total_pages", + "has_next", + "has_prev" + ], + "type": "object" + }, + "SolutionSummary": { + "description": "Catalog row for `GET /api/v1/solutions`. One entry per imported\nSolution config — the ID + storage location + vanity fields lifted\nfrom the Solution body, plus the list of owners it appears under\n(`\"system\"`, `\"org\"`) so callers can tell where it came from.\n\nMulti-owner entries are produced when the same Solution (same\n`solution_id`) exists at both the app-level system scope and the\nviewer's org scope. The list endpoint dedupes by `solution_id` and\nmerges the owners list. When the system-scope row's version is\nhigher than the org-scope row's, `upgrade_available` is `true` and\n`latest_version` carries the system version.\n", + "properties": { + "category_keys": { + "description": "SolutionCategory keys from the Solution body", + "items": { + "type": "string" + }, + "type": "array" + }, + "created_at": { + "description": "Creation timestamp", + "format": "date-time", + "type": "string" + }, + "description": { + "description": "Short tagline / summary (from Solution body)", + "type": "string" + }, + "id": { + "description": "Solution config ID (cfg_...)", + "type": "string" + }, + "kind": { + "description": "Always \"Solution\"", + "type": "string" + }, + "latest_solution": { + "description": "When `upgrade_available` is true, the system-scope Solution config ID that should be used as the upgrade source. Null otherwise.", + "type": "string" + }, + "latest_version": { + "description": "When `upgrade_available` is true, the higher system-scope `solution_version` available to upgrade to. Null otherwise.", + "type": "string" + }, + "lookup_key": { + "description": "Stored lookup_key", + "type": "string" + }, + "metadata": { + "description": "Arbitrary Solution metadata (e.g. category)", + "type": "object" + }, + "name": { + "description": "Display name (from Solution body)", + "type": "string" + }, + "org": { + "description": "Organization", + "type": "string" + }, + "owners": { + "description": "Owner scopes this Solution appears under. Members: `\"system\"` (app-level system scope) and/or `\"org\"` (viewer's org scope).", + "items": { + "type": "string" + }, + "type": "array" + }, + "readme_url": { + "description": "Relative path to the public README endpoint with a signed token already embedded. Null when the Solution has no README. Token expires in 1 hour — refresh via `GET /api/v1/solutions/:solution`.", + "type": "string" + }, + "solution_id": { + "description": "Stable Solution UUID (from Solution body)", + "type": "string" + }, + "solution_version": { + "description": "Solution semver (from Solution body)", + "type": "string" + }, + "tag_keys": { + "description": "SolutionTag keys from the Solution body", + "items": { + "type": "string" + }, + "type": "array" + }, + "template_kind": { + "description": "Wrapped template kind — `\"AgentTemplate\"`, `\"AutomationTemplate\"`, `\"AgentRoutineTemplate\"`, `\"AgentToolTemplate\"`, `\"AgentComputerTemplate\"`, or `\"SolutionTemplateRef\"` for ref-mode bundles.", + "type": "string" + }, + "templates": { + "description": "Template configs bundled by this Solution, in declaration order — the first entry is the deployable template the Solution wraps; the rest are sibling templates the wrapped template references.", + "items": { + "$ref": "#/components/schemas/SolutionTemplateSummary" + }, + "type": "array" + }, + "updated_at": { + "description": "Last update timestamp", + "format": "date-time", + "type": "string" + }, + "upgrade_available": { + "description": "True when this Solution is installed at the viewer's org scope and the app-level system scope carries a higher `solution_version`. Always false for system-only rows.", + "type": "boolean" + }, + "virtual_path": { + "description": "Stored virtual_path (dedupe key across owners)", + "type": "string" + } + }, + "required": [ + "id", + "kind", + "templates", + "owners", + "upgrade_available" + ], + "type": "object" + }, + "SolutionTagListResponse": { + "description": "Paginated list response for `GET /api/v1/solution_tags`.\n", + "properties": { + "data": { + "description": "Solution tag summaries", + "items": { + "$ref": "#/components/schemas/SolutionTagSummary" + }, + "type": "array" + }, + "has_next": { + "description": "Has next page", + "type": "boolean" + }, + "has_prev": { + "description": "Has previous page", + "type": "boolean" + }, + "page": { + "description": "Current page", + "type": "integer" + }, + "page_size": { + "description": "Results per page", + "type": "integer" + }, + "total_entries": { + "description": "Total entries after key dedupe", + "type": "integer" + }, + "total_pages": { + "description": "Total pages", + "type": "integer" + } + }, + "required": [ + "data", + "page", + "page_size", + "total_entries", + "total_pages", + "has_next", + "has_prev" + ], + "type": "object" + }, + "SolutionTagSummary": { + "description": "Catalog tag definition row for `GET /api/v1/solution_tags`.\n", + "properties": { + "created_at": { + "description": "Creation timestamp", + "format": "date-time", + "type": "string" + }, + "description": { + "description": "Short explanation of the tag", + "type": "string" + }, + "id": { + "description": "SolutionTag config ID (cfg_...)", + "type": "string" + }, + "key": { + "description": "Stable tag key referenced by Solution.tag_keys", + "type": "string" + }, + "kind": { + "description": "Always \"SolutionTag\"", + "type": "string" + }, + "lookup_key": { + "description": "Stored lookup_key", + "type": "string" + }, + "metadata": { + "description": "Arbitrary tag metadata", + "type": "object" + }, + "name": { + "description": "Display name", + "type": "string" + }, + "org": { + "description": "Organization", + "type": "string" + }, + "owners": { + "description": "Owner scopes this tag appears under. Members: `\"system\"` (app-level system scope) and/or `\"org\"` (viewer's org scope).", + "items": { + "type": "string" + }, + "type": "array" + }, + "sort_order": { + "description": "Optional numeric ordering hint", + "type": "integer" + }, + "updated_at": { + "description": "Last update timestamp", + "format": "date-time", + "type": "string" + }, + "virtual_path": { + "description": "Stored virtual_path", + "type": "string" + } + }, + "required": [ + "id", + "kind", + "key", + "owners" + ], + "type": "object" + }, + "SolutionTemplateSummary": { + "description": "Template row nested under a `SolutionSummary`.\n\nImported Solutions persist each wrapped/bundled template as a Config\nchild of the Solution. This schema exposes that child identity so\nclients can display and group Solutions at template granularity.\n", + "properties": { + "description": { + "description": "Short prose blurb from the template body's `description:` field. Optional — null when the body doesn't set one. Used as the card subhead in the Library carousel.", + "type": "string" + }, + "display_name": { + "description": "Human-facing label from the template body's `display_name:` field. Optional — null when the body doesn't set one. Library carousels use this for the card title, falling back to a humanized `name`.", + "type": "string" + }, + "id": { + "description": "Template config ID (cfg_...). Null for inline-only templates.", + "type": "string" + }, + "kind": { + "description": "Template config kind, or `SolutionTemplateRef` / `SolutionTemplatePath` when unresolved.", + "type": "string" + }, + "lookup_key": { + "description": "Stored template lookup_key.", + "type": "string" + }, + "name": { + "description": "Canonical name from the template body. For `AgentTemplate` this doubles as the human-facing label; for `AgentToolTemplate` it's the LLM-facing tool function identifier (snake_case); for `AgentRoutineTemplate` it's the routine identifier (kebab-case). Clients rendering carousels should prefer `display_name` and fall back to humanizing `name`.", + "type": "string" + }, + "readme_url": { + "description": "Relative path to the public README endpoint with a signed token already embedded, scoped to this template's bundled markdown asset. Null when the Solution body's `templates[].readme_path` is unset for this entry. Token expires in 1 hour — refresh via `GET /api/v1/solutions/:solution`.", + "type": "string" + }, + "virtual_path": { + "description": "Stored template virtual_path.", + "type": "string" + } + }, + "required": [ + "kind" + ], + "type": "object" + }, + "SolutionUpgradeResponse": { + "description": "Wire shape for `POST /api/v1/solutions/:solution/upgrade`. Mirrors\nSolutionImportResponse at the top but replaces import_result with\nthe richer upgrade_result (full diff).\n", + "properties": { + "created_at": { + "format": "date-time", + "type": "string" + }, + "id": { + "type": "string" + }, + "installed_configs": { + "items": { + "$ref": "#/components/schemas/InstalledConfigEntry" + }, + "type": "array" + }, + "kind": { + "type": "string" + }, + "lookup_key": { + "type": "string" + }, + "solution": { + "$ref": "#/components/schemas/SolutionSummary" + }, + "updated_at": { + "format": "date-time", + "type": "string" + }, + "upgrade_result": { + "$ref": "#/components/schemas/SolutionUpgradeResult" + }, + "virtual_path": { + "type": "string" + } + }, + "required": [ + "id", + "kind", + "solution", + "upgrade_result" + ], + "type": "object" + }, + "SolutionUpgradeResult": { + "description": "The structured upgrade_result slot in a SolutionUpgradeResponse.\n", + "properties": { + "changes": { + "items": { + "$ref": "#/components/schemas/SolutionDiffEntry" + }, + "type": "array" + }, + "code": { + "type": "string" + }, + "dry_run": { + "type": "boolean" + }, + "existing_solution_version": { + "type": "string" + }, + "incoming_solution_version": { + "type": "string" + }, + "message": { + "type": "string" + }, + "review_fingerprint": { + "type": "string" + }, + "status": { + "type": "string" + }, + "summary": { + "$ref": "#/components/schemas/SolutionDiffSummary" + }, + "version_change": { + "type": "string" + } + }, + "required": [ + "status", + "dry_run", + "version_change", + "summary", + "changes" + ], + "type": "object" + }, + "Team": { + "description": "API schema for a team.", + "properties": { + "acl": { + "$ref": "#/components/schemas/Acl", + "description": "Access control list. Contains grants array with principal_type, principal, and actions. Null when no ACL restrictions are applied." + }, + "app": { + "description": "Application", + "type": "string" + }, + "badges": { + "description": "Badge counts by category", + "type": "object" + }, + "created_at": { + "description": "Creation timestamp", + "format": "date-time", + "type": "string" + }, + "description": { + "description": "Team description", + "type": "string" + }, + "id": { + "description": "Team ID", + "type": "string" + }, + "membership_status": { + "description": "Viewer's membership role (owner, admin, member) or null if not a member", + "type": "string" + }, + "metadata": { + "description": "Team metadata", + "type": "object" + }, + "name": { + "description": "Team name", + "type": "string" + }, + "org": { + "description": "Organization", + "type": "string" + }, + "sandbox": { + "description": "Sandbox", + "type": "string" + }, + "slug": { + "description": "URL slug", + "type": "string" + }, + "updated_at": { + "description": "Last update timestamp", + "format": "date-time", + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + }, + "TeamInvite": { + "description": "Schema for a team invite response.\n", + "properties": { + "code": { + "description": "6-character invite code", + "type": "string" + } + }, + "required": [ + "code" + ], + "type": "object" + }, + "TeamMembership": { + "description": "API schema for a team membership.", + "properties": { + "agent": { + "$ref": "#/components/schemas/Agent", + "description": "Agent object (when loaded)" + }, + "created_at": { + "description": "Creation timestamp", + "format": "date-time", + "type": "string" + }, + "id": { + "description": "Membership ID", + "type": "string" + }, + "joined_at": { + "description": "Join timestamp", + "format": "date-time", + "type": "string" + }, + "metadata": { + "description": "Membership metadata", + "type": "object" + }, + "name": { + "description": "Member name", + "type": "string" + }, + "profile_picture": { + "$ref": "#/components/schemas/ImageSource", + "description": "Profile picture" + }, + "role": { + "description": "Role in team", + "type": "string" + }, + "team": { + "description": "Team object (when loaded)", + "type": "object" + }, + "type": { + "description": "Member type (user, agent, unknown)", + "type": "string" + }, + "updated_at": { + "description": "Last update timestamp", + "format": "date-time", + "type": "string" + }, + "user": { + "$ref": "#/components/schemas/User", + "description": "User object (when loaded)" + } + }, + "required": [ + "id" + ], + "type": "object" + }, + "TeamMembershipListResponse": { + "description": "Paginated list response for team memberships.", + "properties": { + "data": { + "description": "List of team memberships", + "items": { + "$ref": "#/components/schemas/TeamMembership" + }, + "type": "array" + }, + "has_next": { + "description": "Whether a next page exists", + "type": "boolean" + }, + "has_prev": { + "description": "Whether a previous page exists", + "type": "boolean" + }, + "page": { + "description": "Current page number", + "type": "integer" + }, + "page_size": { + "description": "Results per page", + "type": "integer" + }, + "total_entries": { + "description": "Total number of entries", + "type": "integer" + }, + "total_pages": { + "description": "Total number of pages", + "type": "integer" + } + }, + "required": [ + "data" + ], + "type": "object" + }, + "Thread": { + "description": "API schema for a chat thread.", + "properties": { + "agent_user": { + "description": "Owning agent user", + "type": "string" + }, + "created_at": { + "description": "Creation timestamp", + "format": "date-time", + "type": "string" + }, + "creator": { + "$ref": "#/components/schemas/User", + "description": "Creator user object" + }, + "description": { + "description": "Thread description", + "type": "string" + }, + "id": { + "description": "Thread ID (thr_...)", + "type": "string" + }, + "is_channel": { + "description": "Whether this is a channel", + "type": "boolean" + }, + "is_default": { + "description": "Whether this is the default thread", + "type": "boolean" + }, + "is_transient": { + "description": "Whether this thread is transient", + "type": "boolean" + }, + "is_unlisted": { + "description": "Whether this thread is unlisted", + "type": "boolean" + }, + "key": { + "description": "Thread key", + "type": "string" + }, + "last_activity": { + "description": "Last activity timestamp", + "format": "date-time", + "type": "string" + }, + "metadata": { + "description": "Thread metadata", + "type": "object" + }, + "muted": { + "description": "Whether notifications are muted for this thread", + "type": "boolean" + }, + "org": { + "description": "Organization", + "type": "string" + }, + "parent_message": { + "$ref": "#/components/schemas/Message", + "description": "Parent message object" + }, + "participant": { + "description": "Participant users", + "items": { + "type": "string" + }, + "type": "array" + }, + "participants": { + "description": "Participant user objects", + "items": { + "$ref": "#/components/schemas/User" + }, + "type": "array" + }, + "participating_actor": { + "description": "Actors participating in thread", + "items": { + "type": "string" + }, + "type": "array" + }, + "participating_agents": { + "description": "Agents participating in thread", + "items": { + "$ref": "#/components/schemas/Agent" + }, + "type": "array" + }, + "role": { + "description": "User's role in the thread", + "type": "string" + }, + "sandbox": { + "description": "Sandbox identifier", + "type": "string" + }, + "settings": { + "$ref": "#/components/schemas/ThreadSettings", + "description": "Thread settings" + }, + "slug": { + "description": "Thread slug", + "type": "string" + }, + "sub_threads": { + "description": "Sub-threads", + "items": { + "type": "object" + }, + "type": "array" + }, + "team": { + "description": "Owning team", + "type": "string" + }, + "title": { + "description": "Thread title", + "type": "string" + }, + "ttl": { + "description": "Time-to-live in seconds", + "type": "integer" + }, + "unread_count": { + "description": "Unread message count", + "type": "integer" + }, + "updated_at": { + "description": "Last update timestamp", + "format": "date-time", + "type": "string" + }, + "user": { + "description": "Owning user", + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + }, + "ThreadMember": { + "description": "API schema for a thread member.", + "properties": { + "membership_type": { + "description": "Membership type (owner or member)", + "type": "string" + }, + "thread": { + "description": "Thread", + "type": "string" + }, + "user": { + "$ref": "#/components/schemas/User", + "description": "User details (when loaded)" + } + }, + "type": "object" + }, + "ThreadReadStatus": { + "description": "Schema for thread read status response.\n", + "properties": { + "last_read_message": { + "description": "Last read message", + "type": "string" + }, + "thread": { + "description": "Thread", + "type": "string" + }, + "unread_count": { + "description": "Number of unread messages", + "type": "integer" + } + }, + "required": [ + "thread", + "unread_count" + ], + "type": "object" + }, + "ThreadSettings": { + "description": "Schema for thread settings response.\n\nUsed by thread settings show/update endpoints.\n", + "properties": { + "agent_enabled": { + "description": "Whether the agent is enabled for this thread", + "type": "boolean" + } + }, + "type": "object" + }, + "UpgradeTemplateSummary": { + "description": "Compact Config row summary for templates referenced by an agent upgrade.\n", + "properties": { + "created_at": { + "format": "date-time", + "type": "string" + }, + "description": { + "description": "Template description from the config body", + "type": "string" + }, + "display_name": { + "description": "Template display name from the config body", + "type": "string" + }, + "id": { + "description": "Template config ID (cfg_...)", + "type": "string" + }, + "kind": { + "description": "Template config kind", + "type": "string" + }, + "lookup_key": { + "description": "Stored template lookup_key", + "type": "string" + }, + "name": { + "description": "Template name from the config body", + "type": "string" + }, + "updated_at": { + "format": "date-time", + "type": "string" + }, + "virtual_path": { + "description": "Stored template virtual_path", + "type": "string" + } + }, + "required": [ + "id", + "kind" + ], + "type": "object" + }, + "User": { + "description": "API schema for a user.", + "properties": { + "alias": { + "description": "User alias/handle", + "type": "string" + }, + "email": { + "description": "User email address", + "type": "string" + }, + "id": { + "description": "User ID", + "type": "string" + }, + "metadata": { + "description": "User metadata", + "type": "object" + }, + "name": { + "description": "User display name. Null when the user has not set a name.", + "type": "string" + }, + "org": { + "description": "Organization", + "type": "string" + }, + "org_name": { + "description": "Organization display name. Null when the user is not in an org, or when the org association was not preloaded by the caller.", + "type": "string" + }, + "org_role": { + "description": "User's role within their org: \"admin\", \"member\", or \"viewer\". Null when the user is not in an org. Used by clients to gate org-admin UI surfaces.", + "type": "string" + }, + "sandbox": { + "description": "Sandbox", + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + }, + "UserInvite": { + "description": "API schema for a user invite.", + "properties": { + "created_at": { + "description": "Creation timestamp", + "format": "date-time", + "type": "string" + }, + "id": { + "description": "Invite ID (uin_...)", + "type": "string" + }, + "key": { + "description": "Invite key", + "type": "string" + }, + "metadata": { + "description": "Invite metadata", + "type": "object" + }, + "thread": { + "description": "Thread", + "type": "string" + }, + "user": { + "$ref": "#/components/schemas/InviteCreator", + "description": "Invite creator" + } + }, + "required": [ + "id" + ], + "type": "object" + }, + "ValidationResult": { + "description": "Schema for config validation result.\n", + "properties": { + "errors": { + "description": "List of validation errors", + "items": { + "type": "string" + }, + "type": "array" + }, + "valid": { + "description": "Whether the config is valid", + "type": "boolean" + }, + "warnings": { + "description": "Optional warnings emitted during validation", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "valid" + ], + "type": "object" + }, + "WorkerStatus": { + "description": "API schema for background worker status on a routine run.", + "properties": { + "attempt": { + "description": "Current attempt number (0 = not yet attempted)", + "type": "integer" + }, + "max_attempts": { + "description": "Maximum allowed attempts", + "type": "integer" + }, + "status": { + "description": "Worker state: queued, executing, retrying, completed, discarded, or cancelled", + "type": "string" + } + }, + "required": [ + "status", + "attempt", + "max_attempts" + ], + "type": "object" + }, + "WorkingMemoryEntry": { + "description": "API schema for a working memory entry.", + "properties": { + "agent": { + "description": "Owning agent", + "type": "string" + }, + "created_at": { + "description": "Creation timestamp", + "format": "date-time", + "type": "string" + }, + "expires_at": { + "description": "Expiration timestamp", + "format": "date-time", + "type": "string" + }, + "id": { + "description": "Memory entry ID (amm_...)", + "type": "string" + }, + "key": { + "description": "Memory key", + "type": "string" + }, + "updated_at": { + "description": "Last update timestamp", + "format": "date-time", + "type": "string" + }, + "value": { + "description": "Memory value", + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + }, + "WorkingMemoryEntryListResponse": { + "description": "Paginated list response for working memory entries.", + "properties": { + "data": { + "description": "List of working memory entries", + "items": { + "$ref": "#/components/schemas/WorkingMemoryEntry" + }, + "type": "array" + }, + "has_next": { + "description": "Whether a next page exists", + "type": "boolean" + }, + "has_prev": { + "description": "Whether a previous page exists", + "type": "boolean" + }, + "page": { + "description": "Current page number", + "type": "integer" + }, + "page_size": { + "description": "Results per page", + "type": "integer" + }, + "total_entries": { + "description": "Total number of entries", + "type": "integer" + }, + "total_pages": { + "description": "Total number of pages", + "type": "integer" + } + }, + "required": [ + "data" + ], + "type": "object" + } + } + }, + "info": { + "description": "Agent-first API for runtime + developer control-plane operations (users, teams, agents, routines, context, workflows, integrations, and webhooks).", + "title": "ArchAstro Platform API", + "version": "v1" + }, + "openapi": "3.0.0", + "paths": { + "/api/v1/activity_feed": { + "get": { + "operationId": "get_api_v1_activity_feed", + "parameters": [ + { + "description": "Filter by kind (routine_run, automation_run, thread_story, agent_quality_verdict, generic)", + "in": "query", + "name": "kind", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + { + "description": "Filter by level (debug, info, warn, error, audit)", + "in": "query", + "name": "level", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + { + "description": "Filter by agent IDs", + "in": "query", + "name": "agent", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + { + "description": "Filter by thread IDs", + "in": "query", + "name": "thread", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + { + "description": "Filter by team IDs", + "in": "query", + "name": "team", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + { + "description": "Filter by organization IDs", + "in": "query", + "name": "org", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + { + "description": "Filter by correlation group", + "in": "query", + "name": "correlation_id", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Maximum number of results (default 50, max 100)", + "in": "query", + "name": "limit", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Cursor for fetching older entries", + "in": "query", + "name": "before_cursor", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Cursor for fetching newer entries", + "in": "query", + "name": "after_cursor", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "description": "Cursor-paginated list of activity feed entries", + "properties": { + "after_cursor": { + "description": "Cursor for fetching newer entries", + "type": "string" + }, + "before_cursor": { + "description": "Cursor for fetching older entries", + "type": "string" + }, + "data": { + "description": "The entries", + "items": { + "description": "API schema for an activity feed entry.", + "properties": { + "agent": { + "description": "Agent (public ID or expanded object when loaded)", + "oneOf": [ + { + "type": "string" + }, { "description": "API schema for an agent.", "properties": { @@ -3168,6 +5616,10 @@ "description": "Identity prompt", "type": "string" }, + "last_applied_template_config": { + "description": "Config id of the AgentTemplate this agent was last provisioned/updated from", + "type": "string" + }, "lookup_key": { "description": "Unique lookup key", "type": "string" @@ -3184,6 +5636,14 @@ "description": "Organization", "type": "string" }, + "org_name": { + "description": "Organization display name. Null when the agent is not in an org, or when the org association was not preloaded by the caller.", + "type": "string" + }, + "originator": { + "description": "Free-form source or author of the agent", + "type": "string" + }, "phone_number": { "description": "Agent phone number", "type": "string" @@ -3196,176 +5656,4400 @@ "description": "Owning team", "type": "string" }, - "updated_at": { - "description": "Last update timestamp", - "format": "date-time", + "updated_at": { + "description": "Last update timestamp", + "format": "date-time", + "type": "string" + }, + "user": { + "description": "Owning user", + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + } + ] + }, + "app": { + "description": "Application", + "type": "string" + }, + "attachments": { + "description": "Entry attachments", + "items": { + "type": "object" + }, + "type": "array" + }, + "automation_run": { + "description": "Automation run", + "type": "string" + }, + "content": { + "description": "Longer explanation (markdown)", + "type": "string" + }, + "correlation_id": { + "description": "Correlation ID for grouped entries", + "type": "string" + }, + "created_at": { + "description": "Creation timestamp", + "format": "date-time", + "type": "string" + }, + "id": { + "description": "Entry ID (afe_...)", + "type": "string" + }, + "kind": { + "description": "Entry kind", + "type": "string" + }, + "level": { + "description": "Severity level", + "type": "string" + }, + "metadata": { + "description": "Entry metadata", + "type": "object" + }, + "org": { + "description": "Organization", + "type": "string" + }, + "routine_run": { + "description": "Routine run", + "type": "string" + }, + "sandbox": { + "description": "Sandbox identifier", + "type": "string" + }, + "session_record": { + "description": "Agent session", + "type": "string" + }, + "team": { + "description": "Team", + "type": "string" + }, + "thread": { + "description": "Thread", + "type": "string" + }, + "title": { + "description": "One-line summary", + "type": "string" + }, + "updated_at": { + "description": "Last update timestamp", + "format": "date-time", + "type": "string" + }, + "user": { + "description": "User (public ID or expanded object when loaded)", + "oneOf": [ + { + "type": "string" + }, + { + "description": "API schema for a user.", + "properties": { + "alias": { + "description": "User alias/handle", + "type": "string" + }, + "email": { + "description": "User email address", + "type": "string" + }, + "id": { + "description": "User ID", + "type": "string" + }, + "metadata": { + "description": "User metadata", + "type": "object" + }, + "name": { + "description": "User display name. Null when the user has not set a name.", + "type": "string" + }, + "org": { + "description": "Organization", + "type": "string" + }, + "org_name": { + "description": "Organization display name. Null when the user is not in an org, or when the org association was not preloaded by the caller.", + "type": "string" + }, + "org_role": { + "description": "User's role within their org: \"admin\", \"member\", or \"viewer\". Null when the user is not in an org. Used by clients to gate org-admin UI surfaces.", + "type": "string" + }, + "sandbox": { + "description": "Sandbox", + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + } + ] + } + }, + "required": [ + "id" + ], + "type": "object" + }, + "type": "array" + }, + "has_more": { + "description": "Whether more items exist beyond this page", + "type": "boolean" + } + }, + "required": [ + "data", + "has_more" + ], + "type": "object" + } + } + }, + "description": "Successful response" + }, + "400": { + "description": "Invalid cursor" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app." + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_computers/{computer}": { + "delete": { + "operationId": "delete_api_v1_agent_computers__computer", + "parameters": [ + { + "description": "Computer ID", + "in": "path", + "name": "computer", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Computer not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "get": { + "operationId": "get_api_v1_agent_computers__computer", + "parameters": [ + { + "description": "Computer ID", + "in": "path", + "name": "computer", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentComputer" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Computer not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_computers/{computer}/exec": { + "post": { + "operationId": "post_api_v1_agent_computers__computer_exec", + "parameters": [ + { + "description": "Computer ID", + "in": "path", + "name": "computer", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "command": { + "description": "Shell command to execute", + "type": "string" + }, + "dir": { + "description": "Working directory for the command", + "type": "string" + } + }, + "required": [ + "command" + ], + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ComputerExecResult" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Computer not found" + }, + "422": { + "description": "Execution failed" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_computers/{computer}/refresh": { + "post": { + "operationId": "post_api_v1_agent_computers__computer_refresh", + "parameters": [ + { + "description": "Computer ID", + "in": "path", + "name": "computer", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentComputer" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Computer not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_env_vars/{env_var}": { + "delete": { + "operationId": "delete_api_v1_agent_env_vars__env_var", + "parameters": [ + { + "description": "Environment variable ID (anv_...)", + "in": "path", + "name": "env_var", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" + }, + "404": { + "description": "Not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "get": { + "operationId": "get_api_v1_agent_env_vars__env_var", + "parameters": [ + { + "description": "Environment variable ID (anv_...)", + "in": "path", + "name": "env_var", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentEnvVarMasked" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" + }, + "404": { + "description": "Not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "patch": { + "operationId": "patch_api_v1_agent_env_vars__env_var", + "parameters": [ + { + "description": "Environment variable ID (anv_...)", + "in": "path", + "name": "env_var", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "description": { + "description": "New description", + "type": "string" + }, + "value": { + "description": "New value", + "type": "string" + } + }, + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentEnvVarMasked" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" + }, + "404": { + "description": "Not found" + }, + "422": { + "description": "Validation failed" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_health_actions/{health_action}": { + "get": { + "operationId": "get_api_v1_agent_health_actions__health_action", + "parameters": [ + { + "description": "Health action ID (aha_...)", + "in": "path", + "name": "health_action", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentHealthAction" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" + }, + "404": { + "description": "Agent health action not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_health_actions/{health_action}/verify": { + "post": { + "operationId": "post_api_v1_agent_health_actions__health_action_verify", + "parameters": [ + { + "description": "Health action ID (aha_...)", + "in": "path", + "name": "health_action", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentHealthAction" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" + }, + "404": { + "description": "Agent health action not found" + }, + "422": { + "description": "Verifier failed to run for this health action" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_installations": { + "get": { + "operationId": "get_api_v1_agent_installations", + "parameters": [ + { + "description": "Filter by agent ID", + "in": "query", + "name": "agent", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InstallationListResponse" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_installations/{installation}": { + "delete": { + "operationId": "delete_api_v1_agent_installations__installation", + "parameters": [ + { + "description": "Installation ID", + "in": "path", + "name": "installation", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Installation not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "get": { + "operationId": "get_api_v1_agent_installations__installation", + "parameters": [ + { + "description": "Installation ID", + "in": "path", + "name": "installation", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Installation" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Installation not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_installations/{installation}/activate": { + "post": { + "operationId": "post_api_v1_agent_installations__installation_activate", + "parameters": [ + { + "description": "Installation ID", + "in": "path", + "name": "installation", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Installation" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Installation not found" + }, + "422": { + "description": "Cannot activate - requires integration or invalid state" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_installations/{installation}/installation_sources": { + "get": { + "operationId": "get_api_v1_agent_installations__installation_installation_sources", + "parameters": [ + { + "description": "Installation ID", + "in": "path", + "name": "installation", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InstallationSourceListResponse" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Installation not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "post": { + "operationId": "post_api_v1_agent_installations__installation_installation_sources", + "parameters": [ + { + "description": "Installation ID", + "in": "path", + "name": "installation", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "payload": { + "description": "Source payload", + "type": "object" + }, + "type": { + "description": "Source type (e.g. file/document, web/link)", + "type": "string" + } + }, + "required": [ + "type", + "payload" + ], + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InstallationSource" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Installation not found" + }, + "422": { + "description": "Invalid source type, state, or payload" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_installations/{installation}/pause": { + "post": { + "operationId": "post_api_v1_agent_installations__installation_pause", + "parameters": [ + { + "description": "Installation ID", + "in": "path", + "name": "installation", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Installation" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Installation not found" + }, + "422": { + "description": "Cannot pause - invalid state" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_installations/{installation}/suspend": { + "post": { + "operationId": "post_api_v1_agent_installations__installation_suspend", + "parameters": [ + { + "description": "Installation ID", + "in": "path", + "name": "installation", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "reason": { + "description": "Optional suspension reason", + "type": "string" + } + }, + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Installation" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Installation not found" + }, + "422": { + "description": "Cannot suspend - already suspended or invalid state" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_routine_runs": { + "get": { + "operationId": "get_api_v1_agent_routine_runs", + "parameters": [ + { + "description": "Filter by one or more agent IDs or lookup_keys. Repeat the param (e.g. ?agent[]=agi_a&agent[]=agi_b) to OR multiple agents.", + "in": "query", + "name": "agent", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + { + "description": "Filter by status", + "in": "query", + "name": "status", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Maximum number of results (default 50, max 100)", + "in": "query", + "name": "limit", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Cursor for fetching items before this point (older)", + "in": "query", + "name": "before_cursor", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Cursor for fetching items after this point (newer)", + "in": "query", + "name": "after_cursor", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentRoutineRunListResponse" + } + } + }, + "description": "Successful response" + }, + "400": { + "description": "Invalid cursor" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Agent not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_routines": { + "get": { + "operationId": "get_api_v1_agent_routines", + "parameters": [ + { + "description": "Filter by agent ID", + "in": "query", + "name": "agent", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Filter by event type", + "in": "query", + "name": "event_type", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentRoutineListResponse" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_routines/presets": { + "get": { + "operationId": "get_api_v1_agent_routines_presets", + "parameters": [], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "items": { + "$ref": "#/components/schemas/RoutinePreset" + }, + "type": "array" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_routines/runs/{run}": { + "get": { + "operationId": "get_api_v1_agent_routines_runs__run", + "parameters": [ + { + "description": "Routine run ID", + "in": "path", + "name": "run", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentRoutineRun" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Routine run not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_routines/{routine}": { + "delete": { + "operationId": "delete_api_v1_agent_routines__routine", + "parameters": [ + { + "description": "Routine ID", + "in": "path", + "name": "routine", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Routine not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "get": { + "operationId": "get_api_v1_agent_routines__routine", + "parameters": [ + { + "description": "Routine ID", + "in": "path", + "name": "routine", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentRoutine" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Routine not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "patch": { + "operationId": "patch_api_v1_agent_routines__routine", + "parameters": [ + { + "description": "Routine ID", + "in": "path", + "name": "routine", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "acl": { + "description": "Access control list", + "properties": { + "add": { + "description": "Patch mode: grants to add or merge into existing", + "items": { + "description": "API schema for a single ACL grant entry.", + "properties": { + "actions": { + "description": "List of allowed actions (e.g. read, write)", + "items": { + "type": "string" + }, + "type": "array" + }, + "principal": { + "description": "Principal identifier (UUID for user/team/org/agent_user, role name for org_role, omit for everyone)", + "type": "string" + }, + "principal_type": { + "description": "Principal type: user, team, org, org_role, agent, or everyone", + "type": "string" + } + }, + "required": [ + "principal_type", + "actions" + ], + "type": "object" + }, + "type": "array" + }, + "grants": { + "description": "Replace mode: full list of grants (replaces all existing). Use [] to clear.", + "items": { + "description": "API schema for a single ACL grant entry.", + "properties": { + "actions": { + "description": "List of allowed actions (e.g. read, write)", + "items": { + "type": "string" + }, + "type": "array" + }, + "principal": { + "description": "Principal identifier (UUID for user/team/org/agent_user, role name for org_role, omit for everyone)", + "type": "string" + }, + "principal_type": { + "description": "Principal type: user, team, org, org_role, agent, or everyone", + "type": "string" + } + }, + "required": [ + "principal_type", + "actions" + ], + "type": "object" + }, + "type": "array" + }, + "remove": { + "description": "Patch mode: principals to remove from existing", + "items": { + "description": "API schema for identifying a principal to remove from an ACL.", + "properties": { + "principal": { + "description": "Principal identifier to remove (omit for everyone)", + "type": "string" + }, + "principal_type": { + "description": "Principal type to remove", + "type": "string" + } + }, + "required": [ + "principal_type" + ], + "type": "object" + }, + "type": "array" + } + }, + "type": "object" + }, + "config": { + "description": "Config ID", + "type": "string" + }, + "description": { + "description": "Description", + "type": "string" + }, + "event_config": { + "description": "Event config map. Keys are event types, values are entry objects with \"filters\" (filter map) and optional \"dedupe_key_path\" (JSON path for deduplication, e.g. \"$.thread.id\")", + "type": "object" + }, + "event_type": { + "description": "Event type (deprecated, use event_config)", + "type": "string" + }, + "handler_type": { + "description": "Handler type: workflow_graph, script, preset, or chain", + "type": "string" + }, + "lookup_key": { + "description": "Lookup key", + "type": "string" + }, + "metadata": { + "description": "Metadata", + "type": "object" + }, + "name": { + "description": "Routine name", + "type": "string" + }, + "preset_config": { + "description": "Preset config", + "properties": { + "instructions": { + "description": "Custom task or behavior instructions for the preset (max 10,000 chars).", + "type": "string" + }, + "llm": { + "description": "LLM invocation settings (e.g. a `model` override for this routine/step).", + "properties": { + "model": { + "description": "Model identifier. When set, overrides the agent's default_model.", + "type": "string" + } + }, + "type": "object" + }, + "session_mode": { + "description": "Session mode: `stateless` (default, new session per trigger) or `session` (find-or-create a persistent session scoped by `session_scope`).", + "type": "string" + }, + "session_scope": { + "description": "When `session_mode` is `session`, controls session scoping: `per_user` (default), `per_key`, `per_org`, or `global`.", + "type": "string" + }, + "structured_message_template_ids": { + "description": "Config IDs of AgentMessageSchema templates that constrain the agent's responses to predefined structured formats.", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + }, + "preset_name": { + "description": "Preset name", + "type": "string" + }, + "schedule": { + "description": "Cron expression for scheduled routines", + "type": "string" + }, + "script": { + "description": "Script content", + "type": "string" + }, + "steps": { + "description": "Linear sequence of steps (required when handler_type is \"chain\"; must be empty otherwise). See the Step schema for per-step fields. Replaces the step list entirely — send the full desired list, not a diff.", + "items": { + "description": "API schema for a single chain-routine step.\n\nMirrors the shape of `ArchAstro.Agents.Routines.Step` as seen by clients,\nwith one API-side normalization: clients send `config` (matching the\nroutine-level field name), and `cast/1` rewrites it to `config_id` so\ndownstream changeset code sees the canonical key.\n\nServer-side validation (handler-body mutual exclusion, `config_id`\nexistence + kind, unique step names within a chain) is authoritative\n— this schema only defines the *shape* of the request payload.\n", + "properties": { + "config": { + "description": "Config ID (for handler_type: workflow_graph, or as an alternative to inline `script` when handler_type: script). Normalized to `config_id` internally.", + "type": "string" + }, + "handler_type": { + "description": "Handler type for this step: preset, script, or workflow_graph", + "type": "string" + }, + "inputs": { + "description": "Optional map binding prior step outputs to this step's inputs.", + "type": "object" + }, + "name": { + "description": "Optional step label. Must be unique within the chain if set.", + "type": "string" + }, + "on_error": { + "description": "Error policy: halt (default), continue, or retry.", + "type": "string" + }, + "output_key": { + "description": "Optional name under which this step's result is addressable downstream. Defaults to `name`.", + "type": "string" + }, + "preset_config": { + "description": "Preset configuration (same shape as the routine-level preset_config). May include `llm: {model}` to override the agent's default_model for this step.", + "properties": { + "instructions": { + "description": "Custom task or behavior instructions for the preset (max 10,000 chars).", + "type": "string" + }, + "llm": { + "description": "LLM invocation settings (e.g. a `model` override for this routine/step).", + "properties": { + "model": { + "description": "Model identifier. When set, overrides the agent's default_model.", + "type": "string" + } + }, + "type": "object" + }, + "session_mode": { + "description": "Session mode: `stateless` (default, new session per trigger) or `session` (find-or-create a persistent session scoped by `session_scope`).", + "type": "string" + }, + "session_scope": { + "description": "When `session_mode` is `session`, controls session scoping: `per_user` (default), `per_key`, `per_org`, or `global`.", + "type": "string" + }, + "structured_message_template_ids": { + "description": "Config IDs of AgentMessageSchema templates that constrain the agent's responses to predefined structured formats.", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + }, + "preset_name": { + "description": "Preset name (for handler_type: preset)", + "type": "string" + }, + "script": { + "description": "Inline script source (for handler_type: script)", + "type": "string" + } + }, + "required": [ + "handler_type" + ], + "type": "object" + }, + "type": "array" + }, + "template": { + "description": "Optional AgentRoutineTemplate config ID or lookup key. When provided, re-resolves the template and patches the existing routine in place — preserves status, lookup_key, and the agent it's attached to. Other params override template defaults.", + "type": "string" + }, + "trigger_context": { + "description": "Trigger context: chat_session or event", + "type": "string" + } + }, + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentRoutine" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Routine not found" + }, + "422": { + "description": "Validation failed" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_routines/{routine}/activate": { + "post": { + "operationId": "post_api_v1_agent_routines__routine_activate", + "parameters": [ + { + "description": "Routine ID", + "in": "path", + "name": "routine", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentRoutine" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Routine not found" + }, + "422": { + "description": "Unprocessable entity - no workflow config attached" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_routines/{routine}/invoke": { + "post": { + "operationId": "post_api_v1_agent_routines__routine_invoke", + "parameters": [ + { + "description": "Routine ID or lookup_key", + "in": "path", + "name": "routine", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "idempotency_key": { + "description": "Idempotency key to deduplicate invocations", + "type": "string" + }, + "message": { + "description": "The message to send", + "type": "string" + }, + "metadata": { + "description": "Optional per-call metadata", + "type": "object" + }, + "session_key": { + "description": "Session key (required when session_scope is per_key)", + "type": "string" + }, + "thread_id": { + "description": "Optional thread to post preset output into", + "type": "string" + }, + "user": { + "description": "User ID (S2S/developer only; client uses viewer)", + "type": "string" + } + }, + "required": [ + "message" + ], + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentRoutineRun" + } + } + }, + "description": "Successful response" + }, + "400": { + "description": "Bad request" + }, + "401": { + "description": "Unauthorized" + }, + "402": { + "description": "Payment required — plan does not allow this feature" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Routine not found" + }, + "422": { + "description": "Unprocessable entity" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_routines/{routine}/pause": { + "post": { + "operationId": "post_api_v1_agent_routines__routine_pause", + "parameters": [ + { + "description": "Routine ID", + "in": "path", + "name": "routine", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentRoutine" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Routine not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_routines/{routine}/runs": { + "get": { + "operationId": "get_api_v1_agent_routines__routine_runs", + "parameters": [ + { + "description": "Routine ID", + "in": "path", + "name": "routine", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Filter by status", + "in": "query", + "name": "status", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Maximum number of results (default 50, max 100)", + "in": "query", + "name": "limit", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Cursor for fetching items before this point (older)", + "in": "query", + "name": "before_cursor", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Cursor for fetching items after this point (newer)", + "in": "query", + "name": "after_cursor", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentRoutineRunListResponse" + } + } + }, + "description": "Successful response" + }, + "400": { + "description": "Invalid cursor" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Routine not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_sessions": { + "get": { + "operationId": "get_api_v1_agent_sessions", + "parameters": [ + { + "description": "Filter by agent ID", + "in": "query", + "name": "agent", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Filter by statuses (pending, running, waiting, completed, failed, cancelled)", + "in": "query", + "name": "status", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + { + "description": "Filter by routine run IDs", + "in": "query", + "name": "routine_run", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + { + "description": "Exclude system-created sessions", + "in": "query", + "name": "exclude_system", + "required": false, + "schema": { + "type": "boolean" + } + }, + { + "description": "Maximum number of results (default 25, max 100)", + "in": "query", + "name": "limit", + "required": false, + "schema": { + "type": "integer" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentSessionListResponse" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "422": { + "description": "Validation failed" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "post": { + "operationId": "post_api_v1_agent_sessions", + "parameters": [], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "agent": { + "description": "Agent ID", + "type": "string" + }, + "instructions": { + "description": "Task description for the session", + "type": "string" + }, + "max_runs_per_turn": { + "description": "Max tool runs per turn (default 25)", + "type": "integer" + }, + "max_tokens": { + "description": "Max tokens (default 20000)", + "type": "integer" + }, + "max_turns": { + "description": "Max turns (default 100)", + "type": "integer" + }, + "metadata": { + "description": "Arbitrary metadata", + "type": "object" + }, + "name": { + "description": "Optional display name for the session", + "type": "string" + }, + "team": { + "description": "Optional team context", + "type": "string" + }, + "thread": { + "description": "Optional thread context", + "type": "string" + }, + "user": { + "description": "Optional user context", + "type": "string" + } + }, + "required": [ + "agent", + "instructions" + ], + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentSession" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Agent not found" + }, + "422": { + "description": "Validation failed" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_sessions/{agent_session}": { + "delete": { + "operationId": "delete_api_v1_agent_sessions__agent_session", + "parameters": [ + { + "description": "Agent session ID", + "in": "path", + "name": "agent_session", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Session not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "get": { + "operationId": "get_api_v1_agent_sessions__agent_session", + "parameters": [ + { + "description": "Agent session ID", + "in": "path", + "name": "agent_session", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentSession" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Session not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "patch": { + "operationId": "patch_api_v1_agent_sessions__agent_session", + "parameters": [ + { + "description": "Agent session ID", + "in": "path", + "name": "agent_session", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "metadata": { + "description": "Arbitrary metadata", + "type": "object" + } + }, + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentSession" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Session not found" + }, + "422": { + "description": "Validation failed" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_sessions/{agent_session}/cancel": { + "post": { + "operationId": "post_api_v1_agent_sessions__agent_session_cancel", + "parameters": [ + { + "description": "Agent session ID", + "in": "path", + "name": "agent_session", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentSession" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Session not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_sessions/{agent_session}/message": { + "post": { + "operationId": "post_api_v1_agent_sessions__agent_session_message", + "parameters": [ + { + "description": "Agent session ID", + "in": "path", + "name": "agent_session", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "content": { + "description": "Message content", + "type": "string" + }, + "metadata": { + "description": "Message metadata", + "type": "object" + }, + "role": { + "description": "Message role (default: user)", + "type": "string" + } + }, + "required": [ + "content" + ], + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentSession" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Session not found" + }, + "422": { + "description": "Validation failed" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_skills": { + "get": { + "operationId": "get_api_v1_agent_skills", + "parameters": [ + { + "description": "Filter by agent ID(s)", + "in": "query", + "name": "agent", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentSkillList" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Agent not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "post": { + "operationId": "post_api_v1_agent_skills", + "parameters": [], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "agent": { + "description": "Agent ID", + "type": "string" + }, + "config": { + "description": "Skill config ID", + "type": "string" + }, + "instruction": { + "description": "Optional instruction override", + "type": "string" + }, + "metadata": { + "description": "Arbitrary metadata", + "type": "object" + } + }, + "required": [ + "agent", + "config" + ], + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentSkill" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Agent not found" + }, + "422": { + "description": "Validation failed" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_skills/{agent_skill}": { + "delete": { + "operationId": "delete_api_v1_agent_skills__agent_skill", + "parameters": [ + { + "description": "Agent skill ID", + "in": "path", + "name": "agent_skill", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "get": { + "operationId": "get_api_v1_agent_skills__agent_skill", + "parameters": [ + { + "description": "Agent skill ID", + "in": "path", + "name": "agent_skill", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentSkill" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "patch": { + "operationId": "patch_api_v1_agent_skills__agent_skill", + "parameters": [ + { + "description": "Agent skill ID", + "in": "path", + "name": "agent_skill", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "instruction": { + "description": "Instruction override", + "type": "string" + }, + "metadata": { + "description": "Arbitrary metadata", + "type": "object" + }, + "template": { + "description": "Optional AgentSkillTemplate config ID, virtual path, or lookup key. When provided, re-resolves the template and patches the existing skill in place — re-points the skill config, refreshes template provenance, and preserves status. instruction and metadata override the template defaults when supplied.", + "type": "string" + } + }, + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentSkill" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Not found" + }, + "422": { + "description": "Validation failed" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_skills/{agent_skill}/activate": { + "post": { + "operationId": "post_api_v1_agent_skills__agent_skill_activate", + "parameters": [ + { + "description": "Agent skill ID", + "in": "path", + "name": "agent_skill", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentSkill" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_skills/{agent_skill}/deactivate": { + "post": { + "operationId": "post_api_v1_agent_skills__agent_skill_deactivate", + "parameters": [ + { + "description": "Agent skill ID", + "in": "path", + "name": "agent_skill", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentSkill" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_tools": { + "get": { + "operationId": "get_api_v1_agent_tools", + "parameters": [ + { + "description": "Filter by agent ID", + "in": "query", + "name": "agent", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Filter by kind (builtin or custom)", + "in": "query", + "name": "kind", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentToolListResponse" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Agent not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_tools/catalog": { + "get": { + "operationId": "get_api_v1_agent_tools_catalog", + "parameters": [], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "items": { + "$ref": "#/components/schemas/BuiltinToolCatalogEntry" + }, + "type": "array" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_tools/{tool}": { + "delete": { + "operationId": "delete_api_v1_agent_tools__tool", + "parameters": [ + { + "description": "Tool ID", + "in": "path", + "name": "tool", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Tool not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "get": { + "operationId": "get_api_v1_agent_tools__tool", + "parameters": [ + { + "description": "Tool ID", + "in": "path", + "name": "tool", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentTool" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Tool not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "patch": { + "operationId": "patch_api_v1_agent_tools__tool", + "parameters": [ + { + "description": "Tool ID", + "in": "path", + "name": "tool", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "async": { + "description": "Whether the tool executes asynchronously (custom kind)", + "type": "boolean" + }, + "builtin_tool_config": { + "description": "Built-in tool config", + "type": "object" + }, + "config": { + "description": "Config ID", + "type": "string" + }, + "description": { + "description": "Description", + "type": "string" + }, + "handler_type": { + "description": "Handler type: script or workflow_graph", + "type": "string" + }, + "instruction": { + "description": "LLM usage instruction", + "type": "string" + }, + "lookup_key": { + "description": "Lookup key", + "type": "string" + }, + "metadata": { + "description": "Metadata", + "type": "object" + }, + "name": { + "description": "Tool name (custom only)", + "type": "string" + }, + "name_prefix": { + "description": "Per-instance namespace for builtin tools that support multiple instances per agent. Stamped onto LLM-facing tool names. Required pattern: ^[a-z][a-z0-9_]*$ (max 24 chars).", + "type": "string" + }, + "parameters": { + "description": "JSON schema for tool input parameters", + "type": "object" + }, + "parameters_config": { + "description": "Config ID for a reusable JsonSchema", + "type": "string" + }, + "template": { + "description": "Optional AgentToolTemplate config ID or lookup key. When provided, re-resolves the template and patches the existing tool in place — preserves status, lookup_key, kind, and the agent it's attached to. Other params override template defaults.", + "type": "string" + } + }, + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentTool" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Tool not found" + }, + "422": { + "description": "Validation failed" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_tools/{tool}/activate": { + "post": { + "operationId": "post_api_v1_agent_tools__tool_activate", + "parameters": [ + { + "description": "Tool ID", + "in": "path", + "name": "tool", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentTool" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Tool not found" + }, + "422": { + "description": "Cannot activate tool" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agent_tools/{tool}/deactivate": { + "post": { + "operationId": "post_api_v1_agent_tools__tool_deactivate", + "parameters": [ + { + "description": "Tool ID", + "in": "path", + "name": "tool", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentTool" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Tool not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agents": { + "get": { + "operationId": "get_api_v1_agents", + "parameters": [ + { + "description": "Page number (default 1)", + "in": "query", + "name": "page", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Results per page (default 25)", + "in": "query", + "name": "page_size", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Search by agent, org, team, or owner fields", + "in": "query", + "name": "search", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Filter to agents owned by this user", + "in": "query", + "name": "user", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Filter to agents owned by this org", + "in": "query", + "name": "org_id", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Filter to agents whose last applied template matches this config id", + "in": "query", + "name": "template_config", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentListResponse" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "post": { + "operationId": "post_api_v1_agents", + "parameters": [], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "acl": { + "description": "Access control list", + "properties": { + "add": { + "description": "Patch mode: grants to add or merge into existing", + "items": { + "description": "API schema for a single ACL grant entry.", + "properties": { + "actions": { + "description": "List of allowed actions (e.g. read, write)", + "items": { + "type": "string" + }, + "type": "array" + }, + "principal": { + "description": "Principal identifier (UUID for user/team/org/agent_user, role name for org_role, omit for everyone)", + "type": "string" + }, + "principal_type": { + "description": "Principal type: user, team, org, org_role, agent, or everyone", + "type": "string" + } + }, + "required": [ + "principal_type", + "actions" + ], + "type": "object" + }, + "type": "array" + }, + "grants": { + "description": "Replace mode: full list of grants (replaces all existing). Use [] to clear.", + "items": { + "description": "API schema for a single ACL grant entry.", + "properties": { + "actions": { + "description": "List of allowed actions (e.g. read, write)", + "items": { + "type": "string" + }, + "type": "array" + }, + "principal": { + "description": "Principal identifier (UUID for user/team/org/agent_user, role name for org_role, omit for everyone)", + "type": "string" + }, + "principal_type": { + "description": "Principal type: user, team, org, org_role, agent, or everyone", + "type": "string" + } + }, + "required": [ + "principal_type", + "actions" + ], + "type": "object" + }, + "type": "array" + }, + "remove": { + "description": "Patch mode: principals to remove from existing", + "items": { + "description": "API schema for identifying a principal to remove from an ACL.", + "properties": { + "principal": { + "description": "Principal identifier to remove (omit for everyone)", + "type": "string" + }, + "principal_type": { + "description": "Principal type to remove", + "type": "string" + } + }, + "required": [ + "principal_type" + ], + "type": "object" + }, + "type": "array" + } + }, + "type": "object" + }, + "email": { + "description": "Agent email", + "type": "string" + }, + "identity": { + "description": "Identity prompt describing who the agent is", + "type": "string" + }, + "lookup_key": { + "description": "Unique lookup key", + "type": "string" + }, + "metadata": { + "description": "Arbitrary metadata", + "type": "object" + }, + "model": { + "description": "Default AI model for this agent", + "type": "string" + }, + "name": { + "description": "Agent name", + "type": "string" + }, + "org": { + "description": "Organization ID", + "type": "string" + }, + "originator": { + "description": "Free-form source or author of the agent", + "type": "string" + }, + "phone_number": { + "description": "Agent phone number", + "type": "string" + }, + "profile_picture": { + "description": "Base64-encoded profile picture", + "properties": { + "data": { + "description": "Base64-encoded image data", + "type": "string" + }, + "filename": { + "description": "Original filename", + "type": "string" + }, + "mime_type": { + "description": "MIME type of the image", + "type": "string" + } + }, + "required": [ + "data", + "mime_type", + "filename" + ], + "type": "object" + }, + "team": { + "description": "Team ID", + "type": "string" + }, + "template": { + "description": "Existing template ID or lookup_key to provision from", + "type": "string" + }, + "template_bundle": { + "description": "Self-contained install bundle (AgentTemplate + skills + configs). Mutually exclusive with `template`.", + "properties": { + "configs": { + "description": "Arbitrary-kind configs the template references", + "items": { + "description": "An arbitrary-kind config row to install — used for scripts, model\nconfigs, routine templates, message schemas, and any other config\nthe AgentTemplate's `config_ref:` entries point at.\n", + "properties": { + "content": { + "description": "Raw config body", + "type": "string" + }, + "content_type": { + "description": "MIME type for the body", + "type": "string" + }, + "relative_path": { + "description": "Bundle-relative path used to derive kind and storage identity", + "type": "string" + } + }, + "required": [ + "relative_path", + "content" + ], + "type": "object" + }, + "type": "array" + }, + "lookup_key_suffix": { + "description": "Appended to every uploaded config's lookup_key + every config_ref in the template body. Stable per install, randomised per attempt.", + "type": "string" + }, + "setup_actions": { + "description": "Post-install checklist items. Each becomes one agent_health_actions row with source: setup, status: pending, inserted in the same transaction.", + "items": { + "description": "One post-install setup checklist item to insert as part of the\ninstall. Becomes one `agent_health_actions` row with\n`source: :setup` and `status: :pending`.\n\n`params` and `verify_config` are arbitrary maps the verifier reads\nat runtime — the cast layer passes them through without inspecting\nshape.\n", + "properties": { + "depends_on": { + "description": "Identifiers of other actions that must complete first", + "items": { + "type": "string" + }, + "type": "array" + }, + "description": { + "description": "Markdown description shown in the checklist", + "type": "string" + }, + "kind": { + "description": "One of: env_var, install, custom", + "type": "string" + }, + "params": { + "description": "Kind-specific payload (e.g. `{key, scope}` for env_var, `{installation_kind}` for install)", + "type": "object" + }, + "required": { + "description": "Whether this action blocks the checklist progress bar (default true)", + "type": "boolean" + }, + "sort_order": { + "description": "Render order; defaults to insertion position", + "type": "integer" + }, + "title": { + "description": "Short human-readable title", + "type": "string" + }, + "verify_config": { + "description": "Verifier configuration (e.g. `{type: \"secret_present\"}`)", + "type": "object" + } + }, + "required": [ + "kind", + "title" + ], + "type": "object" + }, + "type": "array" + }, + "skills": { + "description": "Skill bundles (root + files)", + "items": { + "description": "A skill bundle to install: the SKILL.md root plus optional\naccompanying files. Persisted as one `Skill` config row plus N\n`File` config rows linked by `parent_id`.\n", + "properties": { + "content": { + "description": "SKILL.md body", + "type": "string" + }, + "content_type": { + "description": "MIME type. Defaults to text/markdown.", + "type": "string" + }, + "files": { + "description": "Files inside the skill folder", + "items": { + "description": "One file inside a skill folder. Persisted as a `File` config row whose\n`parent_id` points at the skill's root config.\n", + "properties": { + "content": { + "description": "Raw file body", + "type": "string" + }, + "content_type": { + "description": "MIME type. Defaults to a guess from the file extension.", "type": "string" }, - "user": { - "description": "Owning user", + "relative_path": { + "description": "Path relative to the skill folder root", "type": "string" } }, "required": [ - "id" + "relative_path", + "content" ], "type": "object" - } - ] + }, + "type": "array" + }, + "relative_path": { + "description": "Skill root path, conventionally `skills//SKILL.md`", + "type": "string" + } + }, + "required": [ + "relative_path", + "content" + ], + "type": "object" + }, + "type": "array" + }, + "template": { + "description": "AgentTemplate config to upload", + "properties": { + "content": { + "description": "Raw agent.yaml body", + "type": "string" + }, + "content_type": { + "description": "MIME type. Defaults to application/x-yaml.", + "type": "string" + }, + "relative_path": { + "description": "Template path used to derive storage identity", + "type": "string" + } + }, + "required": [ + "relative_path", + "content" + ], + "type": "object" + } + }, + "required": [ + "template" + ], + "type": "object" + }, + "user": { + "description": "User ID", + "type": "string" + } + }, + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentCreateResponse" + } + } + }, + "description": "Successful response" + }, + "400": { + "description": "Bad request" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden — app scope required" + }, + "404": { + "description": "Template not found" + }, + "409": { + "description": "Conflict" + }, + "422": { + "description": "Validation failed" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agents/{agent}": { + "delete": { + "operationId": "delete_api_v1_agents__agent", + "parameters": [ + { + "description": "Agent ID", + "in": "path", + "name": "agent", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app.; Permission denied. The connected account may not have the required permissions. Try reconnecting your account." + }, + "404": { + "description": "Agent not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "get": { + "operationId": "get_api_v1_agents__agent", + "parameters": [ + { + "description": "Agent ID or lookup_key (handle)", + "in": "path", + "name": "agent", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Agent" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Agent not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "patch": { + "operationId": "patch_api_v1_agents__agent", + "parameters": [ + { + "description": "Agent ID", + "in": "path", + "name": "agent", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "acl": { + "description": "Access control list", + "properties": { + "add": { + "description": "Patch mode: grants to add or merge into existing", + "items": { + "description": "API schema for a single ACL grant entry.", + "properties": { + "actions": { + "description": "List of allowed actions (e.g. read, write)", + "items": { + "type": "string" + }, + "type": "array" + }, + "principal": { + "description": "Principal identifier (UUID for user/team/org/agent_user, role name for org_role, omit for everyone)", + "type": "string" + }, + "principal_type": { + "description": "Principal type: user, team, org, org_role, agent, or everyone", + "type": "string" + } + }, + "required": [ + "principal_type", + "actions" + ], + "type": "object" + }, + "type": "array" + }, + "grants": { + "description": "Replace mode: full list of grants (replaces all existing). Use [] to clear.", + "items": { + "description": "API schema for a single ACL grant entry.", + "properties": { + "actions": { + "description": "List of allowed actions (e.g. read, write)", + "items": { + "type": "string" + }, + "type": "array" + }, + "principal": { + "description": "Principal identifier (UUID for user/team/org/agent_user, role name for org_role, omit for everyone)", + "type": "string" + }, + "principal_type": { + "description": "Principal type: user, team, org, org_role, agent, or everyone", + "type": "string" + } + }, + "required": [ + "principal_type", + "actions" + ], + "type": "object" + }, + "type": "array" + }, + "remove": { + "description": "Patch mode: principals to remove from existing", + "items": { + "description": "API schema for identifying a principal to remove from an ACL.", + "properties": { + "principal": { + "description": "Principal identifier to remove (omit for everyone)", + "type": "string" + }, + "principal_type": { + "description": "Principal type to remove", + "type": "string" + } + }, + "required": [ + "principal_type" + ], + "type": "object" + }, + "type": "array" + } + }, + "type": "object" + }, + "email": { + "description": "Agent email", + "type": "string" + }, + "identity": { + "description": "Identity prompt describing who the agent is", + "type": "string" + }, + "lookup_key": { + "description": "Unique lookup key", + "type": "string" + }, + "metadata": { + "description": "Arbitrary metadata", + "type": "object" + }, + "model": { + "description": "Default AI model for this agent. Empty string clears it.", + "type": "string" + }, + "name": { + "description": "Agent name", + "type": "string" + }, + "org": { + "description": "Organization ID", + "type": "string" + }, + "originator": { + "description": "Free-form source or author of the agent", + "type": "string" + }, + "phone_number": { + "description": "Agent phone number", + "type": "string" + }, + "profile_picture": { + "description": "Base64-encoded profile picture", + "properties": { + "data": { + "description": "Base64-encoded image data", + "type": "string" + }, + "filename": { + "description": "Original filename", + "type": "string" + }, + "mime_type": { + "description": "MIME type of the image", + "type": "string" + } + }, + "required": [ + "data", + "mime_type", + "filename" + ], + "type": "object" + }, + "team": { + "description": "Team ID", + "type": "string" + }, + "user": { + "description": "User ID", + "type": "string" + } + }, + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Agent" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Agent not found" + }, + "422": { + "description": "Validation failed" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agents/{agent}/agent_computers": { + "get": { + "operationId": "get_api_v1_agents__agent_agent_computers", + "parameters": [ + { + "description": "Agent ID", + "in": "path", + "name": "agent", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentComputerListResponse" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Agent not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "post": { + "operationId": "post_api_v1_agents__agent_agent_computers", + "parameters": [ + { + "description": "Agent ID", + "in": "path", + "name": "agent", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "config": { + "description": "Computer configuration", + "type": "object" + }, + "lookup_key": { + "description": "Unique lookup key", + "type": "string" + }, + "metadata": { + "description": "Arbitrary metadata", + "type": "object" + }, + "name": { + "description": "Computer name", + "type": "string" + }, + "region": { + "description": "Region to provision in (default: iad)", + "type": "string" + } + }, + "required": [ + "name" + ], + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentComputer" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Agent not found" + }, + "422": { + "description": "Validation failed" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agents/{agent}/agent_env_vars": { + "get": { + "operationId": "get_api_v1_agents__agent_agent_env_vars", + "parameters": [ + { + "description": "Agent ID", + "in": "path", + "name": "agent", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentEnvVarMaskedList" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" + }, + "404": { + "description": "Agent not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "post": { + "operationId": "post_api_v1_agents__agent_agent_env_vars", + "parameters": [ + { + "description": "Agent ID", + "in": "path", + "name": "agent", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "description": { + "description": "Description of the variable", + "type": "string" + }, + "key": { + "description": "Variable key (e.g. WEBHOOK_SECRET)", + "type": "string" + }, + "value": { + "description": "Variable value", + "type": "string" + } + }, + "required": [ + "key", + "value" + ], + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentEnvVarMasked" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" + }, + "404": { + "description": "Not found" + }, + "422": { + "description": "Validation failed" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agents/{agent}/agent_health_actions": { + "get": { + "operationId": "get_api_v1_agents__agent_agent_health_actions", + "parameters": [ + { + "description": "Agent ID or lookup_key", + "in": "path", + "name": "agent", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Filter by source(s): setup, health", + "in": "query", + "name": "source", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + { + "description": "Filter by status(es): pending, completed, skipped, degraded", + "in": "query", + "name": "status", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + { + "description": "Filter by kind(s): env_var, install, custom", + "in": "query", + "name": "kind", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HealthActionListResponse" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" + }, + "404": { + "description": "Agent not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agents/{agent}/agent_installations": { + "get": { + "operationId": "get_api_v1_agents__agent_agent_installations", + "parameters": [ + { + "description": "Agent ID", + "in": "path", + "name": "agent", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InstallationListResponse" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Agent not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "post": { + "operationId": "post_api_v1_agents__agent_agent_installations", + "parameters": [ + { + "description": "Agent ID", + "in": "path", + "name": "agent", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "config": { + "description": "Optional configuration", + "type": "object" + }, + "integration": { + "description": "Integration fields to auto-create for integration/* kinds. When provided, creates the underlying Integration record and activates the installation.", + "properties": { + "access_token": { + "description": "OAuth access token or API key", + "type": "string" + }, + "installation_id": { + "description": "External installation ID (e.g. GitHub App installation ID, Slack team_id)", + "type": "string" + }, + "metadata": { + "description": "Provider-specific metadata (e.g. bot_user_id)", + "type": "object" + }, + "refresh_token": { + "description": "OAuth refresh token", + "type": "string" + }, + "workspace_key": { + "description": "Workspace name or identifier", + "type": "string" + } + }, + "type": "object" + }, + "kind": { + "description": "Installation kind (e.g., enablement/github_app, enablement/slack_bot, integration/github, integration/gmail, web/site)", + "type": "string" + }, + "lookup_key": { + "description": "Optional stable identifier for the installation. Propagated to the backing Context.Source row(s) so they can be referenced via knowledge_search source_refs. Must be lowercase letters, numbers, underscores, or hyphens (max 100 chars). Unique within (app, org, sandbox).", + "type": "string" + }, + "shared_integration": { + "description": "Shared org/app integration ID to bind to this installation", + "type": "string" + } + }, + "required": [ + "kind" + ], + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Installation" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Agent not found" + }, + "422": { + "description": "Validation failed" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agents/{agent}/agent_installations/kinds": { + "get": { + "operationId": "get_api_v1_agents__agent_agent_installations_kinds", + "parameters": [ + { + "description": "Agent ID", + "in": "path", + "name": "agent", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InstallationKindListResponse" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agents/{agent}/agent_routines": { + "post": { + "operationId": "post_api_v1_agents__agent_agent_routines", + "parameters": [ + { + "description": "Agent ID", + "in": "path", + "name": "agent", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "acl": { + "description": "Access control list", + "properties": { + "add": { + "description": "Patch mode: grants to add or merge into existing", + "items": { + "description": "API schema for a single ACL grant entry.", + "properties": { + "actions": { + "description": "List of allowed actions (e.g. read, write)", + "items": { + "type": "string" + }, + "type": "array" + }, + "principal": { + "description": "Principal identifier (UUID for user/team/org/agent_user, role name for org_role, omit for everyone)", + "type": "string" + }, + "principal_type": { + "description": "Principal type: user, team, org, org_role, agent, or everyone", + "type": "string" + } }, - "app": { - "description": "Application", + "required": [ + "principal_type", + "actions" + ], + "type": "object" + }, + "type": "array" + }, + "grants": { + "description": "Replace mode: full list of grants (replaces all existing). Use [] to clear.", + "items": { + "description": "API schema for a single ACL grant entry.", + "properties": { + "actions": { + "description": "List of allowed actions (e.g. read, write)", + "items": { + "type": "string" + }, + "type": "array" + }, + "principal": { + "description": "Principal identifier (UUID for user/team/org/agent_user, role name for org_role, omit for everyone)", + "type": "string" + }, + "principal_type": { + "description": "Principal type: user, team, org, org_role, agent, or everyone", + "type": "string" + } + }, + "required": [ + "principal_type", + "actions" + ], + "type": "object" + }, + "type": "array" + }, + "remove": { + "description": "Patch mode: principals to remove from existing", + "items": { + "description": "API schema for identifying a principal to remove from an ACL.", + "properties": { + "principal": { + "description": "Principal identifier to remove (omit for everyone)", + "type": "string" + }, + "principal_type": { + "description": "Principal type to remove", + "type": "string" + } + }, + "required": [ + "principal_type" + ], + "type": "object" + }, + "type": "array" + } + }, + "type": "object" + }, + "config": { + "description": "Config ID (for workflow_graph handler)", + "type": "string" + }, + "description": { + "description": "Description", + "type": "string" + }, + "event_config": { + "description": "Event config map. Keys are event types, values are entry objects with \"filters\" (filter map) and optional \"dedupe_key_path\" (JSON path for deduplication, e.g. \"$.thread.id\")", + "type": "object" + }, + "event_type": { + "description": "Event type (deprecated, use event_config)", + "type": "string" + }, + "handler_type": { + "description": "Handler type: workflow_graph, script, preset, or chain", + "type": "string" + }, + "lookup_key": { + "description": "Unique lookup key", + "type": "string" + }, + "metadata": { + "description": "Arbitrary metadata", + "type": "object" + }, + "name": { + "description": "Routine name", + "type": "string" + }, + "preset_config": { + "description": "Preset config", + "properties": { + "instructions": { + "description": "Custom task or behavior instructions for the preset (max 10,000 chars).", + "type": "string" + }, + "llm": { + "description": "LLM invocation settings (e.g. a `model` override for this routine/step).", + "properties": { + "model": { + "description": "Model identifier. When set, overrides the agent's default_model.", "type": "string" - }, - "attachments": { - "description": "Entry attachments", - "items": { + } + }, + "type": "object" + }, + "session_mode": { + "description": "Session mode: `stateless` (default, new session per trigger) or `session` (find-or-create a persistent session scoped by `session_scope`).", + "type": "string" + }, + "session_scope": { + "description": "When `session_mode` is `session`, controls session scoping: `per_user` (default), `per_key`, `per_org`, or `global`.", + "type": "string" + }, + "structured_message_template_ids": { + "description": "Config IDs of AgentMessageSchema templates that constrain the agent's responses to predefined structured formats.", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + }, + "preset_name": { + "description": "Preset name (for preset handler)", + "type": "string" + }, + "schedule": { + "description": "Cron expression for scheduled routines", + "type": "string" + }, + "script": { + "description": "Script content (for script handler)", + "type": "string" + }, + "status": { + "description": "Initial status: draft or active (default: draft)", + "type": "string" + }, + "steps": { + "description": "Linear sequence of steps (required when handler_type is \"chain\"; must be empty otherwise). See the Step schema for the per-step fields. Exactly one handler body field (preset_name, script, or config) must be populated per step, matching that step's handler_type.", + "items": { + "description": "API schema for a single chain-routine step.\n\nMirrors the shape of `ArchAstro.Agents.Routines.Step` as seen by clients,\nwith one API-side normalization: clients send `config` (matching the\nroutine-level field name), and `cast/1` rewrites it to `config_id` so\ndownstream changeset code sees the canonical key.\n\nServer-side validation (handler-body mutual exclusion, `config_id`\nexistence + kind, unique step names within a chain) is authoritative\n— this schema only defines the *shape* of the request payload.\n", + "properties": { + "config": { + "description": "Config ID (for handler_type: workflow_graph, or as an alternative to inline `script` when handler_type: script). Normalized to `config_id` internally.", + "type": "string" + }, + "handler_type": { + "description": "Handler type for this step: preset, script, or workflow_graph", + "type": "string" + }, + "inputs": { + "description": "Optional map binding prior step outputs to this step's inputs.", + "type": "object" + }, + "name": { + "description": "Optional step label. Must be unique within the chain if set.", + "type": "string" + }, + "on_error": { + "description": "Error policy: halt (default), continue, or retry.", + "type": "string" + }, + "output_key": { + "description": "Optional name under which this step's result is addressable downstream. Defaults to `name`.", + "type": "string" + }, + "preset_config": { + "description": "Preset configuration (same shape as the routine-level preset_config). May include `llm: {model}` to override the agent's default_model for this step.", + "properties": { + "instructions": { + "description": "Custom task or behavior instructions for the preset (max 10,000 chars).", + "type": "string" + }, + "llm": { + "description": "LLM invocation settings (e.g. a `model` override for this routine/step).", + "properties": { + "model": { + "description": "Model identifier. When set, overrides the agent's default_model.", + "type": "string" + } + }, "type": "object" }, - "type": "array" - }, - "automation_run": { - "description": "Automation run", - "type": "string" - }, - "content": { - "description": "Longer explanation (markdown)", - "type": "string" - }, - "correlation_id": { - "description": "Correlation ID for grouped entries", - "type": "string" - }, - "created_at": { - "description": "Creation timestamp", - "format": "date-time", - "type": "string" - }, - "id": { - "description": "Entry ID (afe_...)", - "type": "string" - }, - "kind": { - "description": "Entry kind", - "type": "string" - }, - "level": { - "description": "Severity level", - "type": "string" - }, - "metadata": { - "description": "Entry metadata", - "type": "object" - }, - "org": { - "description": "Organization", - "type": "string" - }, - "routine_run": { - "description": "Routine run", - "type": "string" - }, - "sandbox": { - "description": "Sandbox identifier", - "type": "string" - }, - "session_record": { - "description": "Agent session", - "type": "string" - }, - "team": { - "description": "Team", - "type": "string" - }, - "thread": { - "description": "Thread", - "type": "string" - }, - "title": { - "description": "One-line summary", - "type": "string" - }, - "updated_at": { - "description": "Last update timestamp", - "format": "date-time", - "type": "string" - }, - "user": { - "description": "User (public ID or expanded object when loaded)", - "oneOf": [ - { + "session_mode": { + "description": "Session mode: `stateless` (default, new session per trigger) or `session` (find-or-create a persistent session scoped by `session_scope`).", + "type": "string" + }, + "session_scope": { + "description": "When `session_mode` is `session`, controls session scoping: `per_user` (default), `per_key`, `per_org`, or `global`.", + "type": "string" + }, + "structured_message_template_ids": { + "description": "Config IDs of AgentMessageSchema templates that constrain the agent's responses to predefined structured formats.", + "items": { "type": "string" }, - { - "description": "API schema for a user.", - "properties": { - "alias": { - "description": "User alias/handle", - "type": "string" - }, - "email": { - "description": "User email address", - "type": "string" - }, - "id": { - "description": "User ID", - "type": "string" - }, - "metadata": { - "description": "User metadata", - "type": "object" - }, - "name": { - "description": "User display name", - "type": "string" - }, - "org": { - "description": "Organization", - "type": "string" - }, - "sandbox": { - "description": "Sandbox", - "type": "string" - } - }, - "required": [ - "id" - ], - "type": "object" - } - ] - } + "type": "array" + } + }, + "type": "object" }, - "required": [ - "id" - ], - "type": "object" + "preset_name": { + "description": "Preset name (for handler_type: preset)", + "type": "string" + }, + "script": { + "description": "Inline script source (for handler_type: script)", + "type": "string" + } }, - "type": "array" + "required": [ + "handler_type" + ], + "type": "object" }, - "has_more": { - "description": "Whether more items exist beyond this page", - "type": "boolean" - } + "type": "array" }, - "required": [ - "data", - "has_more" - ], - "type": "object" + "trigger_context": { + "description": "Trigger context: chat_session or event (default: event)", + "type": "string" + } + }, + "required": [ + "name", + "handler_type" + ], + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentRoutine" } } }, "description": "Successful response" }, - "400": { - "description": "Invalid cursor" - }, "401": { "description": "Unauthorized" }, "403": { - "description": "App-scoped token required. Use a token scoped to the target app." + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Agent not found" + }, + "422": { + "description": "Validation failed" } }, "x-auth": [ @@ -3374,23 +10058,39 @@ ] } }, - "/api/v1/agent_computers/{computer}": { - "delete": { - "operationId": "delete_api_v1_agent_computers__computer", + "/api/v1/agents/{agent}/agent_tools": { + "get": { + "operationId": "get_api_v1_agents__agent_agent_tools", "parameters": [ { - "description": "Computer ID", + "description": "Filter by agent ID", "in": "path", - "name": "computer", + "name": "agent", "required": true, "schema": { "type": "string" } + }, + { + "description": "Filter by kind (builtin or custom)", + "in": "query", + "name": "kind", + "required": false, + "schema": { + "type": "string" + } } ], "responses": { - "204": { - "description": "No content" + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentToolListResponse" + } + } + }, + "description": "Successful response" }, "401": { "description": "Unauthorized" @@ -3399,7 +10099,7 @@ "description": "Forbidden - app scope required" }, "404": { - "description": "Computer not found" + "description": "Agent not found" } }, "x-auth": [ @@ -3407,25 +10107,92 @@ "bearer" ] }, - "get": { - "operationId": "get_api_v1_agent_computers__computer", + "post": { + "operationId": "post_api_v1_agents__agent_agent_tools", "parameters": [ { - "description": "Computer ID", + "description": "Agent ID", "in": "path", - "name": "computer", + "name": "agent", "required": true, "schema": { "type": "string" } } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "async": { + "description": "Whether the tool executes asynchronously (custom kind)", + "type": "boolean" + }, + "builtin_tool_config": { + "description": "Built-in tool config", + "type": "object" + }, + "builtin_tool_key": { + "description": "Built-in tool key (for builtin kind)", + "type": "string" + }, + "config": { + "description": "Config ID (for custom kind)", + "type": "string" + }, + "description": { + "description": "Tool description (for custom kind)", + "type": "string" + }, + "handler_type": { + "description": "Handler type: script or workflow_graph (for custom kind)", + "type": "string" + }, + "kind": { + "description": "Tool kind: builtin or custom", + "type": "string" + }, + "lookup_key": { + "description": "Unique lookup key", + "type": "string" + }, + "metadata": { + "description": "Arbitrary metadata", + "type": "object" + }, + "name": { + "description": "Tool name (for custom kind)", + "type": "string" + }, + "name_prefix": { + "description": "Per-instance namespace for builtin tools that support multiple instances per agent. Stamped onto LLM-facing tool names (e.g. \"org\" -> \"org_knowledge_search\"). Required pattern: ^[a-z][a-z0-9_]*$ (max 24 chars).", + "type": "string" + }, + "parameters": { + "description": "JSON schema for parameters (for custom kind)", + "type": "object" + }, + "status": { + "description": "Tool status: draft or active (default: draft)", + "type": "string" + } + }, + "required": [ + "kind" + ], + "type": "object" + } + } + }, + "required": true + }, "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AgentComputer" + "$ref": "#/components/schemas/AgentTool" } } }, @@ -3438,7 +10205,10 @@ "description": "Forbidden - app scope required" }, "404": { - "description": "Computer not found" + "description": "Agent not found" + }, + "422": { + "description": "Validation failed" } }, "x-auth": [ @@ -3447,49 +10217,104 @@ ] } }, - "/api/v1/agent_computers/{computer}/exec": { - "post": { - "operationId": "post_api_v1_agent_computers__computer_exec", + "/api/v1/agents/{agent}/agent_working_memory": { + "get": { + "operationId": "get_api_v1_agents__agent_agent_working_memory", "parameters": [ { - "description": "Computer ID", + "description": "Agent ID", "in": "path", - "name": "computer", + "name": "agent", "required": true, "schema": { "type": "string" } + }, + { + "description": "Page number (default 1)", + "in": "query", + "name": "page", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Results per page (default 25)", + "in": "query", + "name": "page_size", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Filter by key (ilike match)", + "in": "query", + "name": "search", + "required": false, + "schema": { + "type": "string" + } } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "properties": { - "command": { - "description": "Shell command to execute", - "type": "string" - }, - "dir": { - "description": "Working directory for the command", - "type": "string" - } - }, - "required": [ - "command" - ], - "type": "object" + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkingMemoryEntryListResponse" + } } - } + }, + "description": "Successful response" }, - "required": true + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Agent not found" + } }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/agents/{agent}/export": { + "get": { + "description": "Reconstructs an AgentTemplate config from a deployed agent and its sub-resources\n(tools, routines, skills, installations). Returns the template plus all dependent\nconfig files (scripts, workflows, skills, schemas) with their raw content for a\nfully self-contained export.\n", + "operationId": "get_api_v1_agents__agent_export", + "parameters": [ + { + "description": "Agent ID or lookup_key", + "in": "path", + "name": "agent", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "When true, remove instance-unique agent identity fields such as email and phone_number.", + "in": "query", + "name": "remove_identity", + "required": false, + "schema": { + "type": "boolean" + } + } + ], "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputerExecResult" + "$ref": "#/components/schemas/AgentExport" } } }, @@ -3502,26 +10327,24 @@ "description": "Forbidden - app scope required" }, "404": { - "description": "Computer not found" - }, - "422": { - "description": "Execution failed" + "description": "Agent not found" } }, + "summary": "Export agent as AgentTemplate", "x-auth": [ "publishable_key", "bearer" ] } }, - "/api/v1/agent_computers/{computer}/refresh": { - "post": { - "operationId": "post_api_v1_agent_computers__computer_refresh", + "/api/v1/agents/{agent}/health": { + "get": { + "operationId": "get_api_v1_agents__agent_health", "parameters": [ { - "description": "Computer ID", + "description": "Agent ID or lookup_key", "in": "path", - "name": "computer", + "name": "agent", "required": true, "schema": { "type": "string" @@ -3533,7 +10356,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AgentComputer" + "$ref": "#/components/schemas/AgentHealth" } } }, @@ -3546,7 +10369,7 @@ "description": "Forbidden - app scope required" }, "404": { - "description": "Computer not found" + "description": "Agent not found" } }, "x-auth": [ @@ -3555,14 +10378,23 @@ ] } }, - "/api/v1/agent_installations": { + "/api/v1/agents/{agent}/schedules": { "get": { - "operationId": "get_api_v1_agent_installations", + "operationId": "get_api_v1_agents__agent_schedules", "parameters": [ { - "description": "Filter by agent ID", + "description": "Agent ID", + "in": "path", + "name": "agent", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Filter by status (default: active and paused)", "in": "query", - "name": "agent", + "name": "status", "required": false, "schema": { "type": "string" @@ -3574,12 +10406,104 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/InstallationListResponse" + "description": "List of schedules", + "properties": { + "data": { + "description": "Schedule entries", + "items": { + "description": "API schema for an agent schedule.", + "properties": { + "agent": { + "description": "Owning agent ID", + "type": "string" + }, + "app": { + "description": "Application ID", + "type": "string" + }, + "created_at": { + "description": "Creation timestamp", + "format": "date-time", + "type": "string" + }, + "cron_expression": { + "description": "Cron expression (recurring only)", + "type": "string" + }, + "id": { + "description": "Schedule ID (asc_...)", + "type": "string" + }, + "instructions": { + "description": "Task instructions", + "type": "string" + }, + "last_run_at": { + "description": "Last execution time", + "format": "date-time", + "type": "string" + }, + "max_runs": { + "description": "Maximum runs (recurring only)", + "type": "integer" + }, + "metadata": { + "description": "Arbitrary metadata", + "type": "object" + }, + "next_run_at": { + "description": "Next scheduled execution", + "format": "date-time", + "type": "string" + }, + "run_count": { + "description": "Number of times executed", + "type": "integer" + }, + "schedule_type": { + "description": "Schedule type (once or recurring)", + "type": "string" + }, + "scheduled_at": { + "description": "One-time execution time", + "format": "date-time", + "type": "string" + }, + "status": { + "description": "Schedule status", + "type": "string" + }, + "thread": { + "description": "Thread ID (if thread-bound)", + "type": "string" + }, + "timezone": { + "description": "Schedule timezone", + "type": "string" + }, + "updated_at": { + "description": "Last update timestamp", + "format": "date-time", + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + }, + "type": "array" + } + }, + "type": "object" } } }, "description": "Successful response" }, + "400": { + "description": "Invalid status value" + }, "401": { "description": "Unauthorized" }, @@ -3593,46 +10517,23 @@ ] } }, - "/api/v1/agent_installations/{installation}": { - "delete": { - "operationId": "delete_api_v1_agent_installations__installation", + "/api/v1/agents/{agent}/schedules/{schedule}": { + "get": { + "operationId": "get_api_v1_agents__agent_schedules__schedule", "parameters": [ { - "description": "Installation ID", + "description": "Agent ID", "in": "path", - "name": "installation", + "name": "agent", "required": true, "schema": { "type": "string" } - } - ], - "responses": { - "204": { - "description": "No content" - }, - "401": { - "description": "Unauthorized" - }, - "403": { - "description": "Forbidden - app scope required" }, - "404": { - "description": "Installation not found" - } - }, - "x-auth": [ - "publishable_key", - "bearer" - ] - }, - "get": { - "operationId": "get_api_v1_agent_installations__installation", - "parameters": [ { - "description": "Installation ID", + "description": "Schedule ID", "in": "path", - "name": "installation", + "name": "schedule", "required": true, "schema": { "type": "string" @@ -3644,7 +10545,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Installation" + "$ref": "#/components/schemas/AgentSchedule" } } }, @@ -3657,7 +10558,7 @@ "description": "Forbidden - app scope required" }, "404": { - "description": "Installation not found" + "description": "Schedule not found" } }, "x-auth": [ @@ -3666,26 +10567,171 @@ ] } }, - "/api/v1/agent_installations/{installation}/activate": { + "/api/v1/agents/{agent}/search": { "post": { - "operationId": "post_api_v1_agent_installations__installation_activate", + "operationId": "post_api_v1_agents__agent_search", "parameters": [ { - "description": "Installation ID", + "description": "Agent ID", "in": "path", - "name": "installation", + "name": "agent", "required": true, "schema": { "type": "string" } } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "max_results": { + "description": "Max total results to return across both kinds (chunks and documents are ranked together into one capped list). Default 20, cap 100.", + "type": "integer" + }, + "mode": { + "description": "Search mode: hybrid, vector, or fulltext", + "type": "string" + }, + "query": { + "description": "Search query", + "type": "string" + }, + "recency_days": { + "description": "Limit results to last N days", + "type": "integer" + }, + "source_types": { + "description": "Filter chunk results by source types", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "query" + ], + "type": "object" + } + } + }, + "required": true + }, "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Installation" + "description": "Search results", + "properties": { + "data": { + "description": "Matching knowledge items as a `kind`-discriminated union (chunk | document). Documents appear only when the agent has an active `archastro/knowledge` installation. A single relevance ranking across both kinds, capped at `max_results` total.", + "items": { + "description": "Discriminated union of knowledge-search results. Discriminated by `kind`:\n\n * `:chunk` — chunk-level result (`Context.Item`-backed)\n * `:document` — doc-level result (`Context.Doc`-backed)\n\nEmitted on the wire as JSON-Schema `oneOf` with `discriminator: kind`.\nGenerated SDKs render a typed tagged union per variant.\n", + "discriminator": { + "propertyName": "kind" + }, + "oneOf": [ + { + "description": "API schema for a knowledge search result item.", + "properties": { + "content": { + "description": "Normalized content text", + "type": "string" + }, + "content_type": { + "description": "Content MIME type", + "type": "string" + }, + "created_at": { + "description": "Creation timestamp", + "format": "date-time", + "type": "string" + }, + "id": { + "description": "Item ID (cim_...)", + "type": "string" + }, + "kind": { + "default": "chunk", + "description": "Discriminator: always `:chunk` for this variant of KnowledgeResult", + "enum": [ + "chunk" + ], + "type": "string" + }, + "metadata": { + "description": "Additional metadata", + "type": "object" + }, + "raw_content": { + "description": "Raw content data", + "type": "object" + }, + "type": { + "description": "Source type (requires preloaded :source association)", + "type": "string" + } + }, + "required": [ + "kind", + "id" + ], + "type": "object" + }, + { + "description": "API schema for a doc-level knowledge search result (variant of\n`KnowledgeResult`).\n\nSnippet + stat derivations mirror the agent-side `KnowledgeTools.format_doc/1`\nbyte-for-byte so HTTP search results match the in-agent tool view.\n", + "properties": { + "id": { + "description": "Document ID (cdo_...)", + "type": "string" + }, + "kind": { + "default": "document", + "description": "Discriminator: always `:document` for this variant of KnowledgeResult", + "enum": [ + "document" + ], + "type": "string" + }, + "metadata": { + "description": "Document metadata", + "type": "object" + }, + "snippet": { + "description": "Leading 300-char snippet of the document text", + "type": "string" + }, + "title": { + "description": "Document title", + "type": "string" + }, + "total_lines": { + "description": "Total line count of the document text", + "type": "integer" + }, + "total_size": { + "description": "Total byte size of the document text", + "type": "integer" + } + }, + "required": [ + "kind", + "id" + ], + "type": "object" + } + ] + }, + "type": "array" + } + }, + "required": [ + "data" + ], + "type": "object" } } }, @@ -3694,14 +10740,11 @@ "401": { "description": "Unauthorized" }, - "403": { - "description": "Forbidden - app scope required" - }, "404": { - "description": "Installation not found" + "description": "Agent not found" }, "422": { - "description": "Cannot activate - requires integration or invalid state" + "description": "Invalid parameters" } }, "x-auth": [ @@ -3710,53 +10753,14 @@ ] } }, - "/api/v1/agent_installations/{installation}/installation_sources": { - "get": { - "operationId": "get_api_v1_agent_installations__installation_installation_sources", - "parameters": [ - { - "description": "Installation ID", - "in": "path", - "name": "installation", - "required": true, - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/InstallationSourceListResponse" - } - } - }, - "description": "Successful response" - }, - "401": { - "description": "Unauthorized" - }, - "403": { - "description": "Forbidden - app scope required" - }, - "404": { - "description": "Installation not found" - } - }, - "x-auth": [ - "publishable_key", - "bearer" - ] - }, + "/api/v1/agents/{agent}/threads": { "post": { - "operationId": "post_api_v1_agent_installations__installation_installation_sources", + "operationId": "post_api_v1_agents__agent_threads", "parameters": [ { - "description": "Installation ID", + "description": "Agent ID", "in": "path", - "name": "installation", + "name": "agent", "required": true, "schema": { "type": "string" @@ -3768,18 +10772,51 @@ "application/json": { "schema": { "properties": { - "payload": { - "description": "Source payload", - "type": "object" + "skip_welcome_message": { + "description": "Skip automatic welcome message", + "type": "boolean" }, - "type": { - "description": "Source type (e.g. file/document, web/link)", - "type": "string" + "thread": { + "description": "Thread attributes", + "properties": { + "description": { + "description": "Thread description", + "type": "string" + }, + "is_unlisted": { + "description": "Whether thread is unlisted", + "type": "boolean" + }, + "key": { + "description": "Unique thread key", + "type": "string" + }, + "metadata": { + "description": "Arbitrary metadata", + "type": "object" + }, + "muted": { + "description": "Whether notifications are muted for this thread", + "type": "boolean" + }, + "org": { + "description": "Organization ID", + "type": "string" + }, + "settings": { + "description": "Thread settings", + "type": "object" + }, + "title": { + "description": "Thread title", + "type": "string" + } + }, + "type": "object" } }, "required": [ - "type", - "payload" + "thread" ], "type": "object" } @@ -3792,7 +10829,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/InstallationSource" + "$ref": "#/components/schemas/Thread" } } }, @@ -3805,10 +10842,10 @@ "description": "Forbidden - app scope required" }, "404": { - "description": "Installation not found" + "description": "Agent not found" }, "422": { - "description": "Invalid source type, state, or payload" + "description": "Validation failed" } }, "x-auth": [ @@ -3817,42 +10854,101 @@ ] } }, - "/api/v1/agent_installations/{installation}/pause": { + "/api/v1/agents/{agent}/upgrade": { "post": { - "operationId": "post_api_v1_agent_installations__installation_pause", + "operationId": "post_api_v1_agents__agent_upgrade", "parameters": [ { - "description": "Installation ID", + "description": "Existing agent ID (`agi_...`) or lookup_key to upgrade", "in": "path", - "name": "installation", + "name": "agent", "required": true, "schema": { "type": "string" } } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "dry_run": { + "description": "Return the upgrade diff without writing changes", + "type": "boolean" + }, + "email": { + "description": "Safe agent email override", + "type": "string" + }, + "identity": { + "description": "Safe identity prompt override", + "type": "string" + }, + "metadata": { + "description": "Safe metadata override", + "type": "object" + }, + "mode": { + "description": "`reapply` to refresh the tracked template, or `replace` to move to a new template", + "enum": [ + "reapply", + "replace" + ], + "type": "string" + }, + "model": { + "description": "Safe default model override. Empty string clears it.", + "type": "string" + }, + "name": { + "description": "Safe agent name override", + "type": "string" + }, + "originator": { + "description": "Safe originator override", + "type": "string" + }, + "phone_number": { + "description": "Safe agent phone number override", + "type": "string" + }, + "template": { + "description": "AgentTemplate config ID (`cfg_...`) or lookup_key. Optional for reapply, required for replace.", + "type": "string" + } + }, + "type": "object" + } + } + }, + "required": true + }, "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Installation" + "$ref": "#/components/schemas/AgentUpgradeResponse" } } }, "description": "Successful response" }, + "400": { + "description": "Bad request" + }, "401": { "description": "Unauthorized" }, "403": { - "description": "Forbidden - app scope required" + "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" }, "404": { - "description": "Installation not found" + "description": "Agent not found; Template not found" }, "422": { - "description": "Cannot pause - invalid state" + "description": "Agent has no tracked template; Template has no parent Solution; Config is not an agent template; Validation failed" } }, "x-auth": [ @@ -3861,30 +10957,191 @@ ] } }, - "/api/v1/agent_installations/{installation}/suspend": { + "/api/v1/ai/chat/completions": { "post": { - "operationId": "post_api_v1_agent_installations__installation_suspend", - "parameters": [ - { - "description": "Installation ID", - "in": "path", - "name": "installation", - "required": true, - "schema": { - "type": "string" - } - } - ], + "operationId": "post_api_v1_ai_chat_completions", + "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { - "reason": { - "description": "Optional suspension reason", - "type": "string" + "context": { + "description": "Template context map", + "type": "object" + }, + "messages": { + "description": "Chat completion messages", + "items": { + "description": "AI chat message (OpenAI-compatible format).", + "properties": { + "content": { + "description": "Message text content", + "type": "string" + }, + "content_parts": { + "description": "Multimodal content parts", + "items": { + "type": "object" + }, + "type": "array" + }, + "resume_token": { + "description": "Resume token for continuing conversations", + "type": "string" + }, + "role": { + "description": "Message role (system, user, assistant, tool)", + "type": "string" + }, + "structured_output": { + "description": "Structured output data" + }, + "tool_calls": { + "description": "Tool calls from assistant", + "items": { + "description": "Tool call from assistant message.", + "properties": { + "arguments": { + "description": "Tool arguments", + "type": "object" + }, + "id": { + "description": "Tool call ID", + "type": "string" + }, + "name": { + "description": "Tool/function name", + "type": "string" + }, + "thought_signature": { + "description": "Optional thought signature", + "type": "string" + } + }, + "required": [ + "id", + "name", + "arguments" + ], + "type": "object" + }, + "type": "array" + }, + "tool_results": { + "description": "Tool results from tool execution", + "items": { + "description": "Tool result from tool execution.", + "properties": { + "content": { + "description": "Tool result content", + "type": "string" + }, + "id": { + "description": "Tool call ID this result responds to", + "type": "string" + }, + "name": { + "description": "Tool/function name", + "type": "string" + }, + "resolution": { + "description": "Structured tool resolution" + } + }, + "required": [ + "id", + "name" + ], + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "role" + ], + "type": "object" + }, + "type": "array" + }, + "opts": { + "description": "Completion options", + "properties": { + "max_tokens": { + "description": "Maximum tokens for the response", + "type": "integer" + }, + "model": { + "description": "Model identifier", + "type": "string" + }, + "server_tools": { + "description": "Server-side tool declarations (e.g. [{type: \"search\"}])", + "items": { + "type": "object" + }, + "type": "array" + }, + "temperature": { + "description": "Sampling temperature", + "type": "number" + }, + "tool_choice": { + "description": "Tool choice for OpenAI-style tools: auto, required, or none", + "type": "string" + }, + "tools": { + "description": "OpenAI tool definitions", + "items": { + "description": "OpenAI-style tool definition.", + "properties": { + "function": { + "description": "Function tool definition", + "properties": { + "description": { + "description": "Function description", + "type": "string" + }, + "name": { + "description": "Function name", + "type": "string" + }, + "parameters": { + "description": "JSON Schema for function parameters", + "type": "object" + } + }, + "required": [ + "name", + "parameters" + ], + "type": "object" + }, + "type": { + "description": "Tool type (function)", + "type": "string" + } + }, + "required": [ + "type", + "function" + ], + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "model" + ], + "type": "object" } }, + "required": [ + "messages", + "opts" + ], "type": "object" } } @@ -3896,70 +11153,23 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Installation" + "$ref": "#/components/schemas/AICompletionResult" } } }, "description": "Successful response" }, + "400": { + "description": "Bad request" + }, "401": { "description": "Unauthorized" }, - "403": { - "description": "Forbidden - app scope required" - }, - "404": { - "description": "Installation not found" + "402": { + "description": "Payment required — plan does not allow this feature" }, "422": { - "description": "Cannot suspend - already suspended or invalid state" - } - }, - "x-auth": [ - "publishable_key", - "bearer" - ] - } - }, - "/api/v1/agent_routines": { - "get": { - "operationId": "get_api_v1_agent_routines", - "parameters": [ - { - "description": "Filter by agent ID", - "in": "query", - "name": "agent", - "required": false, - "schema": { - "type": "string" - } - }, - { - "description": "Filter by event type", - "in": "query", - "name": "event_type", - "required": false, - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AgentRoutineListResponse" - } - } - }, - "description": "Successful response" - }, - "401": { - "description": "Unauthorized" - }, - "403": { - "description": "Forbidden - app scope required" + "description": "Validation failed" } }, "x-auth": [ @@ -3968,417 +11178,238 @@ ] } }, - "/api/v1/agent_routines/presets": { + "/api/v1/ai/chat/models": { "get": { - "operationId": "get_api_v1_agent_routines_presets", + "operationId": "get_api_v1_ai_chat_models", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { - "items": { - "$ref": "#/components/schemas/RoutinePreset" - }, - "type": "array" - } - } - }, - "description": "Successful response" - }, - "401": { - "description": "Unauthorized" - }, - "403": { - "description": "Forbidden - app scope required" - } - }, - "x-auth": [ - "publishable_key", - "bearer" - ] - } - }, - "/api/v1/agent_routines/runs/{run}": { - "get": { - "operationId": "get_api_v1_agent_routines_runs__run", - "parameters": [ - { - "description": "Routine run ID", - "in": "path", - "name": "run", - "required": true, - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AgentRoutineRun" - } - } - }, - "description": "Successful response" - }, - "401": { - "description": "Unauthorized" - }, - "403": { - "description": "Forbidden - app scope required" - }, - "404": { - "description": "Routine run not found" - } - }, - "x-auth": [ - "publishable_key", - "bearer" - ] - } - }, - "/api/v1/agent_routines/{routine}": { - "delete": { - "operationId": "delete_api_v1_agent_routines__routine", - "parameters": [ - { - "description": "Routine ID", - "in": "path", - "name": "routine", - "required": true, - "schema": { - "type": "string" - } - } - ], - "responses": { - "204": { - "description": "No content" + "description": "Available models", + "properties": { + "data": { + "description": "The models", + "items": { + "description": "Schema for AI model information.", + "properties": { + "default": { + "description": "True for the model the platform falls back to when an Agent has no `default_model` set (or for the system-wide default when used in image-generation contexts). Exactly one entry in the list carries this flag.", + "type": "boolean" + }, + "id": { + "description": "Model identifier", + "type": "string" + }, + "name": { + "description": "Human-readable label for this model, e.g. `\"Claude Sonnet 4.6\"` or `\"Gemini 3.5 Flash (thinking)\"`. Pickers should render this directly rather than parsing `id`. Falls back to the id string when the catalog entry doesn't declare a name.", + "type": "string" + } + }, + "required": [ + "id", + "name", + "default" + ], + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "data" + ], + "type": "object" + } + } + }, + "description": "Successful response" }, "401": { "description": "Unauthorized" - }, - "403": { - "description": "Forbidden - app scope required" - }, - "404": { - "description": "Routine not found" } }, "x-auth": [ "publishable_key", "bearer" ] - }, - "get": { - "operationId": "get_api_v1_agent_routines__routine", - "parameters": [ - { - "description": "Routine ID", - "in": "path", - "name": "routine", - "required": true, - "schema": { - "type": "string" + } + }, + "/api/v1/ai/image/edits": { + "post": { + "operationId": "post_api_v1_ai_image_edits", + "parameters": [], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "aspect_ratio": { + "description": "Aspect ratio (e.g. 1:1, 16:9)", + "type": "string" + }, + "background": { + "description": "Background setting (model-dependent)", + "type": "string" + }, + "height": { + "description": "Image height in pixels", + "type": "integer" + }, + "image_size": { + "description": "Image size tier for Gemini (e.g. 1K, 2K, 4K)", + "type": "string" + }, + "images": { + "description": "Source images to edit", + "items": { + "description": "Schema for an input image (base64-encoded) used in image editing.", + "properties": { + "image_data": { + "description": "Base64-encoded image data", + "type": "string" + }, + "image_type": { + "description": "MIME type (e.g. image/png, image/jpeg)", + "type": "string" + } + }, + "required": [ + "image_data", + "image_type" + ], + "type": "object" + }, + "type": "array" + }, + "model": { + "description": "Model identifier (defaults to the platform default)", + "type": "string" + }, + "output_format": { + "description": "Output format (png, jpeg, webp)", + "type": "string" + }, + "prompt": { + "description": "Text description of the edit to apply", + "type": "string" + }, + "quality": { + "description": "Quality setting (model-dependent)", + "type": "string" + }, + "size": { + "description": "Size string for OpenAI models (e.g. 1024x1024)", + "type": "string" + }, + "style": { + "description": "Style setting (model-dependent)", + "type": "string" + }, + "width": { + "description": "Image width in pixels", + "type": "integer" + } + }, + "required": [ + "prompt", + "images" + ], + "type": "object" + } } - } - ], + }, + "required": true + }, "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AgentRoutine" + "$ref": "#/components/schemas/AIImageResult" } } }, "description": "Successful response" }, + "400": { + "description": "Bad request" + }, "401": { "description": "Unauthorized" }, - "403": { - "description": "Forbidden - app scope required" - }, - "404": { - "description": "Routine not found" + "422": { + "description": "Image editing failed" } }, "x-auth": [ "publishable_key", "bearer" ] - }, - "patch": { - "operationId": "patch_api_v1_agent_routines__routine", - "parameters": [ - { - "description": "Routine ID", - "in": "path", - "name": "routine", - "required": true, - "schema": { - "type": "string" - } - } - ], + } + }, + "/api/v1/ai/image/generations": { + "post": { + "operationId": "post_api_v1_ai_image_generations", + "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { - "acl": { - "description": "Access control list", - "properties": { - "add": { - "description": "Patch mode: grants to add or merge into existing", - "items": { - "description": "API schema for a single ACL grant entry.", - "properties": { - "actions": { - "description": "List of allowed actions (e.g. read, write)", - "items": { - "type": "string" - }, - "type": "array" - }, - "principal": { - "description": "Principal identifier (UUID for user/team/org/agent_user, role name for org_role, omit for everyone)", - "type": "string" - }, - "principal_type": { - "description": "Principal type: user, team, org, org_role, agent, or everyone", - "type": "string" - } - }, - "required": [ - "principal_type", - "actions" - ], - "type": "object" - }, - "type": "array" - }, - "grants": { - "description": "Replace mode: full list of grants (replaces all existing). Use [] to clear.", - "items": { - "description": "API schema for a single ACL grant entry.", - "properties": { - "actions": { - "description": "List of allowed actions (e.g. read, write)", - "items": { - "type": "string" - }, - "type": "array" - }, - "principal": { - "description": "Principal identifier (UUID for user/team/org/agent_user, role name for org_role, omit for everyone)", - "type": "string" - }, - "principal_type": { - "description": "Principal type: user, team, org, org_role, agent, or everyone", - "type": "string" - } - }, - "required": [ - "principal_type", - "actions" - ], - "type": "object" - }, - "type": "array" - }, - "remove": { - "description": "Patch mode: principals to remove from existing", - "items": { - "description": "API schema for identifying a principal to remove from an ACL.", - "properties": { - "principal": { - "description": "Principal identifier to remove (omit for everyone)", - "type": "string" - }, - "principal_type": { - "description": "Principal type to remove", - "type": "string" - } - }, - "required": [ - "principal_type" - ], - "type": "object" - }, - "type": "array" - } - }, - "type": "object" - }, - "config": { - "description": "Config ID", - "type": "string" - }, - "description": { - "description": "Description", - "type": "string" - }, - "event_config": { - "description": "Event config map. Keys are event types, values are entry objects with \"filters\" (filter map) and optional \"dedupe_key_path\" (JSON path for deduplication, e.g. \"$.thread.id\")", - "type": "object" - }, - "event_type": { - "description": "Event type (deprecated, use event_config)", + "aspect_ratio": { + "description": "Aspect ratio (e.g. 1:1, 16:9)", "type": "string" }, - "handler_type": { - "description": "Handler type: workflow_graph, script, preset, or chain", + "background": { + "description": "Background setting (model-dependent)", "type": "string" }, - "lookup_key": { - "description": "Lookup key", - "type": "string" + "height": { + "description": "Image height in pixels", + "type": "integer" }, - "metadata": { - "description": "Metadata", - "type": "object" + "image_size": { + "description": "Image size tier for Gemini (e.g. 1K, 2K, 4K)", + "type": "string" }, - "name": { - "description": "Routine name", + "model": { + "description": "Model identifier (defaults to the platform default)", "type": "string" }, - "preset_config": { - "description": "Preset config", - "properties": { - "instructions": { - "description": "Custom task or behavior instructions for the preset (max 10,000 chars).", - "type": "string" - }, - "llm": { - "description": "LLM invocation settings (e.g. a `model` override for this routine/step).", - "properties": { - "model": { - "description": "Model identifier. When set, overrides the agent's default_model.", - "type": "string" - } - }, - "type": "object" - }, - "session_mode": { - "description": "Session mode: `stateless` (default, new session per trigger) or `session` (find-or-create a persistent session scoped by `session_scope`).", - "type": "string" - }, - "session_scope": { - "description": "When `session_mode` is `session`, controls session scoping: `per_user` (default), `per_key`, `per_org`, or `global`.", - "type": "string" - }, - "structured_message_template_ids": { - "description": "Config IDs of AgentMessageSchema templates that constrain the agent's responses to predefined structured formats.", - "items": { - "type": "string" - }, - "type": "array" - } - }, - "type": "object" + "n": { + "description": "Number of images to generate (default 1)", + "type": "integer" }, - "preset_name": { - "description": "Preset name", + "output_format": { + "description": "Output format (png, jpeg, webp)", "type": "string" }, - "schedule": { - "description": "Cron expression for scheduled routines", + "prompt": { + "description": "Text description of the image to generate", "type": "string" }, - "script": { - "description": "Script content", + "quality": { + "description": "Quality setting (model-dependent)", "type": "string" }, - "steps": { - "description": "Linear sequence of steps (required when handler_type is \"chain\"; must be empty otherwise). See the Step schema for per-step fields. Replaces the step list entirely — send the full desired list, not a diff.", - "items": { - "description": "API schema for a single chain-routine step.\n\nMirrors the shape of `ArchAstro.Agents.Routines.Step` as seen by clients,\nwith one API-side normalization: clients send `config` (matching the\nroutine-level field name), and `cast/1` rewrites it to `config_id` so\ndownstream changeset code sees the canonical key.\n\nServer-side validation (handler-body mutual exclusion, `config_id`\nexistence + kind, unique step names within a chain) is authoritative\n— this schema only defines the *shape* of the request payload.\n", - "properties": { - "config": { - "description": "Config ID (for handler_type: workflow_graph, or as an alternative to inline `script` when handler_type: script). Normalized to `config_id` internally.", - "type": "string" - }, - "handler_type": { - "description": "Handler type for this step: preset, script, or workflow_graph", - "type": "string" - }, - "inputs": { - "description": "Optional map binding prior step outputs to this step's inputs.", - "type": "object" - }, - "name": { - "description": "Optional step label. Must be unique within the chain if set.", - "type": "string" - }, - "on_error": { - "description": "Error policy: halt (default), continue, or retry.", - "type": "string" - }, - "output_key": { - "description": "Optional name under which this step's result is addressable downstream. Defaults to `name`.", - "type": "string" - }, - "preset_config": { - "description": "Preset configuration (same shape as the routine-level preset_config). May include `llm: {model}` to override the agent's default_model for this step.", - "properties": { - "instructions": { - "description": "Custom task or behavior instructions for the preset (max 10,000 chars).", - "type": "string" - }, - "llm": { - "description": "LLM invocation settings (e.g. a `model` override for this routine/step).", - "properties": { - "model": { - "description": "Model identifier. When set, overrides the agent's default_model.", - "type": "string" - } - }, - "type": "object" - }, - "session_mode": { - "description": "Session mode: `stateless` (default, new session per trigger) or `session` (find-or-create a persistent session scoped by `session_scope`).", - "type": "string" - }, - "session_scope": { - "description": "When `session_mode` is `session`, controls session scoping: `per_user` (default), `per_key`, `per_org`, or `global`.", - "type": "string" - }, - "structured_message_template_ids": { - "description": "Config IDs of AgentMessageSchema templates that constrain the agent's responses to predefined structured formats.", - "items": { - "type": "string" - }, - "type": "array" - } - }, - "type": "object" - }, - "preset_name": { - "description": "Preset name (for handler_type: preset)", - "type": "string" - }, - "script": { - "description": "Inline script source (for handler_type: script)", - "type": "string" - } - }, - "required": [ - "handler_type" - ], - "type": "object" - }, - "type": "array" + "size": { + "description": "Size string for OpenAI models (e.g. 1024x1024)", + "type": "string" }, - "trigger_context": { - "description": "Trigger context: chat_session or event", + "style": { + "description": "Style setting (model-dependent)", "type": "string" + }, + "width": { + "description": "Image width in pixels", + "type": "integer" } }, + "required": [ + "prompt" + ], "type": "object" } } @@ -4386,43 +11417,130 @@ "required": true }, "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AgentRoutine" - } - } - }, - "description": "Successful response" + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AIImageResult" + } + } + }, + "description": "Successful response" + }, + "400": { + "description": "Bad request" + }, + "401": { + "description": "Unauthorized" + }, + "422": { + "description": "Image generation failed" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/ai/image/models": { + "get": { + "operationId": "get_api_v1_ai_image_models", + "parameters": [], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "description": "Available models", + "properties": { + "data": { + "description": "The models", + "items": { + "description": "Schema for AI model information.", + "properties": { + "default": { + "description": "True for the model the platform falls back to when an Agent has no `default_model` set (or for the system-wide default when used in image-generation contexts). Exactly one entry in the list carries this flag.", + "type": "boolean" + }, + "id": { + "description": "Model identifier", + "type": "string" + }, + "name": { + "description": "Human-readable label for this model, e.g. `\"Claude Sonnet 4.6\"` or `\"Gemini 3.5 Flash (thinking)\"`. Pickers should render this directly rather than parsing `id`. Falls back to the id string when the catalog entry doesn't declare a name.", + "type": "string" + } + }, + "required": [ + "id", + "name", + "default" + ], + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "data" + ], + "type": "object" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/artifacts/{artifact}": { + "delete": { + "operationId": "delete_api_v1_artifacts__artifact", + "parameters": [ + { + "description": "Artifact ID", + "in": "path", + "name": "artifact", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No content" }, "401": { "description": "Unauthorized" }, "403": { - "description": "Forbidden - app scope required" + "description": "Forbidden" }, "404": { - "description": "Routine not found" - }, - "422": { - "description": "Validation failed" + "description": "Artifact not found" } }, "x-auth": [ "publishable_key", "bearer" ] - } - }, - "/api/v1/agent_routines/{routine}/activate": { - "post": { - "operationId": "post_api_v1_agent_routines__routine_activate", + }, + "get": { + "operationId": "get_api_v1_artifacts__artifact", "parameters": [ { - "description": "Routine ID", + "description": "Artifact ID", "in": "path", - "name": "routine", + "name": "artifact", "required": true, "schema": { "type": "string" @@ -4434,7 +11552,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AgentRoutine" + "$ref": "#/components/schemas/Artifact" } } }, @@ -4444,29 +11562,24 @@ "description": "Unauthorized" }, "403": { - "description": "Forbidden - app scope required" + "description": "Forbidden" }, "404": { - "description": "Routine not found" - }, - "422": { - "description": "Unprocessable entity - no workflow config attached" + "description": "Artifact not found" } }, "x-auth": [ "publishable_key", "bearer" ] - } - }, - "/api/v1/agent_routines/{routine}/invoke": { - "post": { - "operationId": "post_api_v1_agent_routines__routine_invoke", + }, + "put": { + "operationId": "put_api_v1_artifacts__artifact", "parameters": [ { - "description": "Routine ID or lookup_key", + "description": "Artifact ID", "in": "path", - "name": "routine", + "name": "artifact", "required": true, "schema": { "type": "string" @@ -4478,29 +11591,33 @@ "application/json": { "schema": { "properties": { - "idempotency_key": { - "description": "Idempotency key to deduplicate invocations", + "description": { + "description": "Artifact description", "type": "string" }, - "message": { - "description": "The message to send", + "file_content": { + "description": "Base64 encoded file content", "type": "string" }, - "metadata": { - "description": "Optional per-call metadata", - "type": "object" + "file_content_type": { + "description": "File MIME type", + "type": "string" }, - "session_key": { - "description": "Session key (required when session_scope is per_key)", + "file_name": { + "description": "File name", "type": "string" }, - "user": { - "description": "User ID (S2S/developer only; client uses viewer)", + "from_version": { + "description": "Current version for optimistic concurrency control", + "type": "integer" + }, + "name": { + "description": "Artifact name", "type": "string" } }, "required": [ - "message" + "from_version" ], "type": "object" } @@ -4513,7 +11630,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AgentRoutineRun" + "$ref": "#/components/schemas/Artifact" } } }, @@ -4526,274 +11643,425 @@ "description": "Forbidden" }, "404": { - "description": "Routine not found" + "description": "Artifact not found" + }, + "409": { + "description": "Version conflict" + }, + "422": { + "description": "Validation error" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/artifacts/{artifact}/archive": { + "post": { + "operationId": "post_api_v1_artifacts__artifact_archive", + "parameters": [ + { + "description": "Artifact ID", + "in": "path", + "name": "artifact", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Artifact not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/artifacts/{artifact}/content": { + "get": { + "operationId": "get_api_v1_artifacts__artifact_content", + "parameters": [ + { + "description": "Artifact ID", + "in": "path", + "name": "artifact", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Optional version number", + "in": "query", + "name": "version", + "required": false, + "schema": { + "type": "integer" + } + } + ], + "responses": { + "200": { + "content": { + "*/*": { + "schema": { + "format": "binary", + "type": "string" + } + } + }, + "description": "Raw artifact file content" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Artifact content not found" + }, + "422": { + "description": "Error retrieving content" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/auth/allowed_auth_methods": { + "get": { + "operationId": "get_api_v1_auth_allowed_auth_methods", + "parameters": [], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "description": "List of supported auth methods", + "properties": { + "data": { + "description": "Auth method metadata", + "items": { + "description": "Description of a single auth method the platform supports.\n\nReturned by the `/api/v1/auth/allowed_auth_methods` list endpoint so\nclients (the agent-network admin UI, the auth-react lib) don't have\nto hardcode method slugs or user-facing copy.\n", + "properties": { + "description": { + "description": "One-line user-facing description of what this method does", + "type": "string" + }, + "name": { + "description": "Short user-facing name for buttons / list items", + "type": "string" + }, + "slug": { + "description": "Stable enum value used in `enabled_auth_methods` (e.g., `password`, `magic_link`)", + "type": "string" + } + }, + "required": [ + "slug", + "name", + "description" + ], + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "data" + ], + "type": "object" + } + } + }, + "description": "Successful response" + } + }, + "tags": [ + "auth" + ], + "x-auth": [ + "publishable_key" + ] + } + }, + "/api/v1/auth/login": { + "post": { + "operationId": "post_api_v1_auth_login", + "parameters": [], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "email": { + "description": "User email address", + "type": "string" + }, + "password": { + "description": "User password", + "type": "string" + } + }, + "required": [ + "email", + "password" + ], + "type": "object" + } + } }, - "422": { - "description": "Unprocessable entity" - } + "required": true }, - "x-auth": [ - "publishable_key", - "bearer" - ] - } - }, - "/api/v1/agent_routines/{routine}/pause": { - "post": { - "operationId": "post_api_v1_agent_routines__routine_pause", - "parameters": [ - { - "description": "Routine ID", - "in": "path", - "name": "routine", - "required": true, - "schema": { - "type": "string" - } - } - ], "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AgentRoutine" + "$ref": "#/components/schemas/AuthTokens" } } }, "description": "Successful response" }, "401": { - "description": "Unauthorized" + "description": "Invalid credentials" }, "403": { - "description": "Forbidden - app scope required" + "description": "Password login is not enabled for this organization" }, - "404": { - "description": "Routine not found" + "429": { + "description": "Rate limited" } }, + "tags": [ + "auth" + ], "x-auth": [ - "publishable_key", - "bearer" + "publishable_key" ] } }, - "/api/v1/agent_routines/{routine}/runs": { - "get": { - "operationId": "get_api_v1_agent_routines__routine_runs", - "parameters": [ - { - "description": "Routine ID", - "in": "path", - "name": "routine", - "required": true, - "schema": { - "type": "string" - } - }, - { - "description": "Filter by status", - "in": "query", - "name": "status", - "required": false, - "schema": { - "type": "string" + "/api/v1/auth/login/link": { + "post": { + "operationId": "post_api_v1_auth_login_link", + "parameters": [], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "email": { + "description": "User email address", + "type": "string" + }, + "redirect_uri": { + "description": "Redirect URI after magic link verification", + "type": "string" + } + }, + "type": "object" + } } }, - { - "description": "Maximum number of results (default 50, max 100)", - "in": "query", - "name": "limit", - "required": false, - "schema": { - "type": "integer" - } + "required": true + }, + "responses": { + "204": { + "description": "No content" }, - { - "description": "Cursor for fetching items before this point (older)", - "in": "query", - "name": "before_cursor", - "required": false, - "schema": { - "type": "string" - } + "400": { + "description": "Missing email or redirect_uri" }, - { - "description": "Cursor for fetching items after this point (newer)", - "in": "query", - "name": "after_cursor", - "required": false, - "schema": { - "type": "string" - } + "429": { + "description": "Rate limited" } + }, + "tags": [ + "auth" + ], + "x-auth": [ + "publishable_key" ], + "x-sdk-name": "request_login_magic_link" + } + }, + "/api/v1/auth/refresh": { + "post": { + "operationId": "post_api_v1_auth_refresh", + "parameters": [], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "refresh_token": { + "description": "Refresh token to exchange", + "type": "string" + } + }, + "required": [ + "refresh_token" + ], + "type": "object" + } + } + }, + "required": true + }, "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AgentRoutineRunListResponse" + "$ref": "#/components/schemas/AuthTokens" } } }, "description": "Successful response" }, - "400": { - "description": "Invalid cursor" - }, "401": { - "description": "Unauthorized" - }, - "403": { - "description": "Forbidden - app scope required" + "description": "Invalid or expired refresh token" }, - "404": { - "description": "Routine not found" + "429": { + "description": "Rate limited" } }, + "tags": [ + "auth" + ], "x-auth": [ - "publishable_key", - "bearer" + "publishable_key" ] } }, - "/api/v1/agent_sessions": { - "get": { - "operationId": "get_api_v1_agent_sessions", - "parameters": [ - { - "description": "Filter by agent ID", - "in": "query", - "name": "agent", - "required": false, - "schema": { - "type": "string" - } - }, - { - "description": "Filter by statuses (pending, running, waiting, completed, failed, cancelled)", - "in": "query", - "name": "status", - "required": false, - "schema": { - "items": { - "type": "string" - }, - "type": "array" - } - }, - { - "description": "Filter by routine run IDs", - "in": "query", - "name": "routine_run", - "required": false, - "schema": { - "items": { - "type": "string" - }, - "type": "array" - } - }, - { - "description": "Exclude system-created sessions", - "in": "query", - "name": "exclude_system", - "required": false, - "schema": { - "type": "boolean" - } - }, - { - "description": "Maximum number of results (default 25, max 100)", - "in": "query", - "name": "limit", - "required": false, - "schema": { - "type": "integer" + "/api/v1/auth/register": { + "post": { + "operationId": "post_api_v1_auth_register", + "parameters": [], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "alias": { + "description": "User alias/handle", + "type": "string" + }, + "email": { + "description": "User email address", + "type": "string" + }, + "full_name": { + "description": "User's full name", + "type": "string" + }, + "invite_code": { + "description": "Invite code for invite-based registration", + "type": "string" + }, + "password": { + "description": "User password (required for standard registration)", + "type": "string" + }, + "team_invite": { + "description": "Team invite ID for team-based registration", + "type": "string" + }, + "timezone": { + "description": "User timezone", + "type": "string" + } + }, + "required": [ + "email" + ], + "type": "object" + } } - } - ], + }, + "required": true + }, "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AgentSessionListResponse" + "$ref": "#/components/schemas/AuthTokens" } } }, "description": "Successful response" }, - "401": { - "description": "Unauthorized" + "400": { + "description": "Missing required parameters" }, "403": { - "description": "Forbidden - app scope required" + "description": "Password registration is not enabled for this organization" + }, + "404": { + "description": "Team invite not found" }, "422": { "description": "Validation failed" } }, + "tags": [ + "auth" + ], "x-auth": [ - "publishable_key", - "bearer" + "publishable_key" ] - }, + } + }, + "/api/v1/auth/register/link": { "post": { - "operationId": "post_api_v1_agent_sessions", + "operationId": "post_api_v1_auth_register_link", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { - "agent": { - "description": "Agent ID", - "type": "string" - }, - "instructions": { - "description": "Task description for the session", + "alias": { + "description": "User alias/handle", "type": "string" }, - "max_runs_per_turn": { - "description": "Max tool runs per turn (default 25)", - "type": "integer" - }, - "max_tokens": { - "description": "Max tokens (default 20000)", - "type": "integer" - }, - "max_turns": { - "description": "Max turns (default 100)", - "type": "integer" - }, - "metadata": { - "description": "Arbitrary metadata", - "type": "object" - }, - "name": { - "description": "Optional display name for the session", + "email": { + "description": "User email address", "type": "string" }, - "team": { - "description": "Optional team context", + "full_name": { + "description": "User's full name", "type": "string" }, - "thread": { - "description": "Optional thread context", + "redirect_uri": { + "description": "Redirect URI after verification", "type": "string" }, - "user": { - "description": "Optional user context", + "timezone": { + "description": "User timezone", "type": "string" } }, - "required": [ - "agent", - "instructions" - ], "type": "object" } } @@ -4801,128 +12069,147 @@ "required": true }, "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AgentSession" - } - } - }, - "description": "Successful response" - }, - "401": { - "description": "Unauthorized" - }, - "403": { - "description": "Forbidden - app scope required" + "204": { + "description": "No content" }, - "404": { - "description": "Agent not found" + "400": { + "description": "Missing email" }, "422": { "description": "Validation failed" + }, + "429": { + "description": "Rate limited" } }, + "tags": [ + "auth" + ], "x-auth": [ - "publishable_key", - "bearer" - ] + "publishable_key" + ], + "x-sdk-name": "request_register_magic_link" } }, - "/api/v1/agent_sessions/{agent_session}": { - "delete": { - "operationId": "delete_api_v1_agent_sessions__agent_session", - "parameters": [ - { - "description": "Agent session ID", - "in": "path", - "name": "agent_session", - "required": true, - "schema": { - "type": "string" + "/api/v1/auth/request/link": { + "post": { + "operationId": "post_api_v1_auth_request_link", + "parameters": [], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "email": { + "description": "User email address", + "type": "string" + }, + "redirect_uri": { + "description": "Redirect URI after magic link verification", + "type": "string" + } + }, + "type": "object" + } } - } - ], + }, + "required": true + }, "responses": { "204": { "description": "No content" }, - "401": { - "description": "Unauthorized" + "400": { + "description": "Missing email or redirect_uri" }, - "403": { - "description": "Forbidden - app scope required" + "422": { + "description": "Validation failed" }, - "404": { - "description": "Session not found" + "429": { + "description": "Rate limited" } }, + "tags": [ + "auth" + ], "x-auth": [ - "publishable_key", - "bearer" - ] - }, - "get": { - "operationId": "get_api_v1_agent_sessions__agent_session", - "parameters": [ - { - "description": "Agent session ID", - "in": "path", - "name": "agent_session", - "required": true, - "schema": { - "type": "string" - } - } + "publishable_key" ], + "x-sdk-name": "request_magic_link" + } + }, + "/api/v1/auth/token": { + "post": { + "operationId": "post_api_v1_auth_token", + "parameters": [], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "timezone": { + "description": "User timezone to update if still default", + "type": "string" + }, + "token": { + "description": "One-time login token from email", + "type": "string" + } + }, + "required": [ + "token" + ], + "type": "object" + } + } + }, + "required": true + }, "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AgentSession" + "$ref": "#/components/schemas/AuthTokens" } } }, "description": "Successful response" }, + "400": { + "description": "Missing token" + }, "401": { - "description": "Unauthorized" + "description": "Invalid or expired token" }, - "403": { - "description": "Forbidden - app scope required" + "429": { + "description": "Rate limited" }, - "404": { - "description": "Session not found" + "500": { + "description": "Token exchange failed" } }, + "tags": [ + "auth" + ], "x-auth": [ - "publishable_key", - "bearer" - ] - }, - "patch": { - "operationId": "patch_api_v1_agent_sessions__agent_session", - "parameters": [ - { - "description": "Agent session ID", - "in": "path", - "name": "agent_session", - "required": true, - "schema": { - "type": "string" - } - } + "publishable_key" ], + "x-sdk-name": "exchange_login_token" + } + }, + "/api/v1/auth/verify/link": { + "post": { + "operationId": "post_api_v1_auth_verify_link", + "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { - "metadata": { - "description": "Arbitrary metadata", - "type": "object" + "token": { + "description": "Magic link token", + "type": "string" } }, "type": "object" @@ -4936,39 +12223,43 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AgentSession" + "$ref": "#/components/schemas/AuthTokens" } } }, "description": "Successful response" }, + "400": { + "description": "Missing token" + }, "401": { - "description": "Unauthorized" + "description": "Invalid or expired token" }, "403": { - "description": "Forbidden - app scope required" - }, - "404": { - "description": "Session not found" + "description": "Passwordless login is not enabled for this organization" }, - "422": { - "description": "Validation failed" + "429": { + "description": "Rate limited" } }, + "tags": [ + "auth" + ], "x-auth": [ - "publishable_key", - "bearer" - ] + "publishable_key" + ], + "x-sdk-name": "verify_magic_link" } }, - "/api/v1/agent_sessions/{agent_session}/cancel": { - "post": { - "operationId": "post_api_v1_agent_sessions__agent_session_cancel", + "/api/v1/automation_runs/{automation_run}": { + "get": { + "description": "Fetches one run created by an invoked automation.\n\nThis public lookup route only returns runs whose parent automation has\n`type: :invoked`.\n", + "operationId": "get_api_v1_automation_runs__automation_run", "parameters": [ { - "description": "Agent session ID", + "description": "Automation run ID", "in": "path", - "name": "agent_session", + "name": "automation_run", "required": true, "schema": { "type": "string" @@ -4980,7 +12271,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AgentSession" + "$ref": "#/components/schemas/AutomationRun" } } }, @@ -4990,26 +12281,27 @@ "description": "Unauthorized" }, "403": { - "description": "Forbidden - app scope required" + "description": "Forbidden" }, "404": { - "description": "Session not found" + "description": "Automation run not found" } }, + "summary": "Get a single invoked automation run", "x-auth": [ "publishable_key", "bearer" ] } }, - "/api/v1/agent_sessions/{agent_session}/message": { + "/api/v1/automations/{automation}/invoke": { "post": { - "operationId": "post_api_v1_agent_sessions__agent_session_message", + "operationId": "post_api_v1_automations__automation_invoke", "parameters": [ { - "description": "Agent session ID", + "description": "Automation ID or lookup_key", "in": "path", - "name": "agent_session", + "name": "automation", "required": true, "schema": { "type": "string" @@ -5021,22 +12313,15 @@ "application/json": { "schema": { "properties": { - "content": { - "description": "Message content", + "idempotency_key": { + "description": "Idempotency key to deduplicate invocations", "type": "string" }, - "metadata": { - "description": "Message metadata", + "payload": { + "description": "Input payload (validated against input_schema if configured)", "type": "object" - }, - "role": { - "description": "Message role (default: user)", - "type": "string" } }, - "required": [ - "content" - ], "type": "object" } } @@ -5048,7 +12333,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AgentSession" + "$ref": "#/components/schemas/AutomationRun" } } }, @@ -5058,13 +12343,13 @@ "description": "Unauthorized" }, "403": { - "description": "Forbidden - app scope required" + "description": "Forbidden" }, "404": { - "description": "Session not found" + "description": "Automation not found" }, "422": { - "description": "Validation failed" + "description": "Unprocessable entity" } }, "x-auth": [ @@ -5073,77 +12358,36 @@ ] } }, - "/api/v1/agent_skills": { - "get": { - "operationId": "get_api_v1_agent_skills", - "parameters": [ - { - "description": "Filter by agent ID(s)", - "in": "query", - "name": "agent", - "required": false, - "schema": { - "items": { - "type": "string" - }, - "type": "array" - } - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AgentSkillList" - } - } - }, - "description": "Successful response" - }, - "401": { - "description": "Unauthorized" - }, - "403": { - "description": "Forbidden - app scope required" - }, - "404": { - "description": "Agent not found" - } - }, - "x-auth": [ - "publishable_key", - "bearer" - ] - }, + "/api/v1/bug_reports": { "post": { - "operationId": "post_api_v1_agent_skills", + "operationId": "post_api_v1_bug_reports", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { - "agent": { - "description": "Agent ID", - "type": "string" - }, - "config": { - "description": "Skill config ID", + "client": { + "description": "Submitting client. One of: agent_network_web, cli, developer_portal.", "type": "string" }, - "instruction": { - "description": "Optional instruction override", + "client_version": { + "description": "Build SHA or package version of the client.", "type": "string" }, - "metadata": { - "description": "Arbitrary metadata", + "context": { + "description": "Optional client-shaped context blob; ≤5 KB serialized. Stored verbatim and surfaced for triage — clients commonly include url, user_agent, thread_id, message_id, etc.", "type": "object" + }, + "description": { + "description": "Freeform report text. 1–10,000 chars after trim.", + "type": "string" } }, "required": [ - "agent", - "config" + "description", + "client", + "client_version" ], "type": "object" } @@ -5156,23 +12400,23 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AgentSkill" + "$ref": "#/components/schemas/BugReport" } } }, "description": "Successful response" }, + "400": { + "description": "Bad request — invalid client value" + }, "401": { "description": "Unauthorized" }, - "403": { - "description": "Forbidden - app scope required" - }, - "404": { - "description": "Agent not found" - }, "422": { - "description": "Validation failed" + "description": "Validation failed — empty description, oversized payload, or other changeset error" + }, + "429": { + "description": "Rate limit exceeded — 10 reports per user per hour" } }, "x-auth": [ @@ -5181,152 +12425,86 @@ ] } }, - "/api/v1/agent_skills/{agent_skill}": { - "delete": { - "operationId": "delete_api_v1_agent_skills__agent_skill", + "/api/v1/config": { + "get": { + "operationId": "get_api_v1_config", "parameters": [ { - "description": "Agent skill ID", - "in": "path", - "name": "agent_skill", - "required": true, + "description": "Team ID (for team-owned configs)", + "in": "query", + "name": "team", + "required": false, "schema": { "type": "string" } - } - ], - "responses": { - "204": { - "description": "No content" - }, - "401": { - "description": "Unauthorized" - }, - "403": { - "description": "Forbidden - app scope required" }, - "404": { - "description": "Not found" - } - }, - "x-auth": [ - "publishable_key", - "bearer" - ] - }, - "get": { - "operationId": "get_api_v1_agent_skills__agent_skill", - "parameters": [ { - "description": "Agent skill ID", - "in": "path", - "name": "agent_skill", - "required": true, + "description": "User ID (for user-owned configs, defaults to current user)", + "in": "query", + "name": "user", + "required": false, "schema": { "type": "string" } - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AgentSkill" - } - } - }, - "description": "Successful response" }, - "401": { - "description": "Unauthorized" - }, - "403": { - "description": "Forbidden - app scope required" - }, - "404": { - "description": "Not found" - } - }, - "x-auth": [ - "publishable_key", - "bearer" - ] - }, - "patch": { - "operationId": "patch_api_v1_agent_skills__agent_skill", - "parameters": [ { - "description": "Agent skill ID", - "in": "path", - "name": "agent_skill", - "required": true, + "description": "Agent ID (for agent-owned configs)", + "in": "query", + "name": "agent", + "required": false, "schema": { "type": "string" } - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "properties": { - "instruction": { - "description": "Instruction override", - "type": "string" - }, - "metadata": { - "description": "Arbitrary metadata", - "type": "object" - } - }, - "type": "object" - } - } }, - "required": true - }, - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AgentSkill" - } - } - }, - "description": "Successful response" + { + "description": "Filter by config kind", + "in": "query", + "name": "kind", + "required": false, + "schema": { + "type": "string" + } }, - "401": { - "description": "Unauthorized" + { + "description": "Filter by exact lookup_key match", + "in": "query", + "name": "lookup_key", + "required": false, + "schema": { + "type": "string" + } }, - "403": { - "description": "Forbidden - app scope required" + { + "description": "Filter by virtual_path prefix", + "in": "query", + "name": "path_prefix", + "required": false, + "schema": { + "type": "string" + } }, - "404": { - "description": "Not found" + { + "description": "Filter: children of any listed parent config ID (pass one ID to fetch a single bundle's children)", + "in": "query", + "name": "parents", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } }, - "422": { - "description": "Validation failed" - } - }, - "x-auth": [ - "publishable_key", - "bearer" - ] - } - }, - "/api/v1/agent_skills/{agent_skill}/activate": { - "post": { - "operationId": "post_api_v1_agent_skills__agent_skill_activate", - "parameters": [ { - "description": "Agent skill ID", - "in": "path", - "name": "agent_skill", - "required": true, + "description": "Filter: configs imported with any listed Solution config ID", + "in": "query", + "name": "parent_solutions", + "required": false, "schema": { - "type": "string" + "items": { + "type": "string" + }, + "type": "array" } } ], @@ -5335,98 +12513,247 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AgentSkill" + "description": "List of configs", + "properties": { + "data": { + "description": "The configs", + "items": { + "description": "API schema for a config resource.", + "properties": { + "agent": { + "description": "Agent", + "type": "string" + }, + "created_at": { + "description": "Creation timestamp", + "format": "date-time", + "type": "string" + }, + "current_version": { + "description": "Current version", + "properties": { + "change_description": { + "description": "Description of changes", + "type": "string" + }, + "content_hash": { + "description": "sha256: over UTF-8 bytes of raw_content. Same format as the CLI's computeContentHash. Nullable for rows that predate the column.", + "type": "string" + }, + "created_at": { + "description": "Creation timestamp", + "format": "date-time", + "type": "string" + }, + "data": { + "description": "Additional structured data", + "type": "object" + }, + "id": { + "description": "Config version ID (cfv_...)", + "type": "string" + }, + "org": { + "description": "Organization", + "type": "string" + }, + "sandbox": { + "description": "Sandbox", + "type": "string" + }, + "version_number": { + "description": "Version number", + "type": "integer" + } + }, + "required": [ + "id", + "version_number" + ], + "type": "object" + }, + "id": { + "description": "Config ID (cfg_...)", + "type": "string" + }, + "is_archived": { + "description": "Whether config is archived", + "type": "boolean" + }, + "kind": { + "description": "Config kind (e.g., Agent, APITool)", + "type": "string" + }, + "lookup_key": { + "description": "Optional lookup key", + "type": "string" + }, + "mime_type": { + "description": "Content mime type", + "type": "string" + }, + "org": { + "description": "Organization", + "type": "string" + }, + "parent": { + "description": "Parent config ID (bundle children only)", + "type": "string" + }, + "parent_solution": { + "description": "Solution config ID this config was imported with", + "type": "string" + }, + "raw_content": { + "description": "Raw file content (system configs only)", + "type": "string" + }, + "relative_path": { + "description": "Path within parent bundle (bundle children only)", + "type": "string" + }, + "sandbox": { + "description": "Sandbox identifier", + "type": "string" + }, + "team": { + "description": "Team", + "type": "string" + }, + "updated_at": { + "description": "Last update timestamp", + "format": "date-time", + "type": "string" + }, + "user": { + "description": "User", + "type": "string" + }, + "virtual_path": { + "description": "Unique path within the team", + "type": "string" + } + }, + "required": [ + "id", + "kind" + ], + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "data" + ], + "type": "object" } } }, "description": "Successful response" }, + "400": { + "description": "Bad request - owner required" + }, "401": { "description": "Unauthorized" - }, - "403": { - "description": "Forbidden - app scope required" - }, - "404": { - "description": "Not found" } }, "x-auth": [ "publishable_key", "bearer" ] - } - }, - "/api/v1/agent_skills/{agent_skill}/deactivate": { + }, "post": { - "operationId": "post_api_v1_agent_skills__agent_skill_deactivate", - "parameters": [ - { - "description": "Agent skill ID", - "in": "path", - "name": "agent_skill", - "required": true, - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AgentSkill" - } + "operationId": "post_api_v1_config", + "parameters": [], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "agent": { + "description": "Agent ID (for agent-owned configs)", + "type": "string" + }, + "change_description": { + "description": "Description of changes", + "type": "string" + }, + "data": { + "description": "Additional structured data stored on the version", + "type": "object" + }, + "kind": { + "description": "Config kind (e.g., Agent, APITool)", + "type": "string" + }, + "lookup_key": { + "description": "Optional lookup key", + "type": "string" + }, + "mime_type": { + "description": "Content mime type", + "type": "string" + }, + "org": { + "description": "Organization ID", + "type": "string" + }, + "parent": { + "description": "Parent config ID (for bundle children, e.g. files under a Skill)", + "type": "string" + }, + "parent_solution": { + "description": "Solution config ID this config was imported with", + "type": "string" + }, + "raw_content": { + "description": "Raw content (YAML/JSON/etc)", + "type": "string" + }, + "relative_path": { + "description": "Path within the parent bundle (required when parent is set)", + "type": "string" + }, + "system": { + "description": "Create the config system-owned (team/user/agent all null). Privileged: developer, all-powerful, app system user — or an org admin combined with their own org (org-scoped system config).", + "type": "boolean" + }, + "take_ownership": { + "description": "When a config already exists at this virtual_path/lookup_key under a DIFFERENT owner (lookup_key uniqueness is owner-agnostic within the app + org scope), adopt it instead of failing: the row is re-owned to the requested owner, unarchived, and this content lands as its next version. Requires modify rights on the existing row (developer/all-powerful).", + "type": "boolean" + }, + "team": { + "description": "Team ID (for team-owned configs)", + "type": "string" + }, + "user": { + "description": "User ID (for user-owned configs)", + "type": "string" + }, + "virtual_path": { + "description": "Unique path within the owner scope", + "type": "string" + } + }, + "required": [ + "kind", + "raw_content", + "mime_type" + ], + "type": "object" } - }, - "description": "Successful response" - }, - "401": { - "description": "Unauthorized" - }, - "403": { - "description": "Forbidden - app scope required" - }, - "404": { - "description": "Not found" - } - }, - "x-auth": [ - "publishable_key", - "bearer" - ] - } - }, - "/api/v1/agent_tools": { - "get": { - "operationId": "get_api_v1_agent_tools", - "parameters": [ - { - "description": "Filter by agent ID", - "in": "query", - "name": "agent", - "required": false, - "schema": { - "type": "string" } }, - { - "description": "Filter by kind (builtin or custom)", - "in": "query", - "name": "kind", - "required": false, - "schema": { - "type": "string" - } - } - ], + "required": true + }, "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AgentToolListResponse" + "$ref": "#/components/schemas/Config" } } }, @@ -5438,8 +12765,11 @@ "403": { "description": "Forbidden - app scope required" }, - "404": { - "description": "Agent not found" + "409": { + "description": "Conflict - a config with this path/lookup_key already exists" + }, + "422": { + "description": "Validation failed" } }, "x-auth": [ @@ -5448,19 +12778,49 @@ ] } }, - "/api/v1/agent_tools/catalog": { - "get": { - "operationId": "get_api_v1_agent_tools_catalog", + "/api/v1/config/encrypt_secret": { + "post": { + "operationId": "post_api_v1_config_encrypt_secret", "parameters": [], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "org": { + "description": "Organization ID — overrides viewer's org for KEK scoping", + "type": "string" + }, + "plaintext": { + "description": "Secret value to encrypt", + "type": "string" + } + }, + "required": [ + "plaintext" + ], + "type": "object" + } + } + }, + "required": true + }, "responses": { "200": { "content": { "application/json": { "schema": { - "items": { - "$ref": "#/components/schemas/BuiltinToolCatalogEntry" + "description": "Encrypted secret value", + "properties": { + "encrypted_value": { + "description": "Encrypted ciphertext for use in secret_value!", + "type": "string" + } }, - "type": "array" + "required": [ + "encrypted_value" + ], + "type": "object" } } }, @@ -5471,6 +12831,9 @@ }, "403": { "description": "Forbidden - app scope required" + }, + "422": { + "description": "Encryption failed" } }, "x-auth": [ @@ -5479,149 +12842,53 @@ ] } }, - "/api/v1/agent_tools/{tool}": { - "delete": { - "operationId": "delete_api_v1_agent_tools__tool", + "/api/v1/config/facets": { + "get": { + "operationId": "get_api_v1_config_facets", "parameters": [ { - "description": "Tool ID", - "in": "path", - "name": "tool", - "required": true, + "description": "App ID (present when mounted under the developer scope)", + "in": "query", + "name": "app", + "required": false, "schema": { "type": "string" } - } - ], - "responses": { - "204": { - "description": "No content" - }, - "401": { - "description": "Unauthorized" - }, - "403": { - "description": "Forbidden - app scope required" }, - "404": { - "description": "Tool not found" - } - }, - "x-auth": [ - "publishable_key", - "bearer" - ] - }, - "get": { - "operationId": "get_api_v1_agent_tools__tool", - "parameters": [ { - "description": "Tool ID", - "in": "path", - "name": "tool", - "required": true, + "description": "Team ID (for team-owned configs)", + "in": "query", + "name": "team", + "required": false, "schema": { "type": "string" } - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AgentTool" - } - } - }, - "description": "Successful response" - }, - "401": { - "description": "Unauthorized" }, - "403": { - "description": "Forbidden - app scope required" + { + "description": "User ID (for user-owned configs; defaults to current user)", + "in": "query", + "name": "user", + "required": false, + "schema": { + "type": "string" + } }, - "404": { - "description": "Tool not found" - } - }, - "x-auth": [ - "publishable_key", - "bearer" - ] - }, - "patch": { - "operationId": "patch_api_v1_agent_tools__tool", - "parameters": [ { - "description": "Tool ID", - "in": "path", - "name": "tool", - "required": true, + "description": "Filter by org_id", + "in": "query", + "name": "org", + "required": false, "schema": { "type": "string" } } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "properties": { - "builtin_tool_config": { - "description": "Built-in tool config", - "type": "object" - }, - "config": { - "description": "Config ID", - "type": "string" - }, - "description": { - "description": "Description", - "type": "string" - }, - "handler_type": { - "description": "Handler type: script or workflow_graph", - "type": "string" - }, - "instruction": { - "description": "LLM usage instruction", - "type": "string" - }, - "lookup_key": { - "description": "Lookup key", - "type": "string" - }, - "metadata": { - "description": "Metadata", - "type": "object" - }, - "name": { - "description": "Tool name (custom only)", - "type": "string" - }, - "parameters": { - "description": "JSON schema for tool input parameters", - "type": "object" - }, - "parameters_config": { - "description": "Config ID for a reusable JsonSchema", - "type": "string" - } - }, - "type": "object" - } - } - }, - "required": true - }, "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AgentTool" + "$ref": "#/components/schemas/ConfigFacets" } } }, @@ -5632,12 +12899,6 @@ }, "403": { "description": "Forbidden - app scope required" - }, - "404": { - "description": "Tool not found" - }, - "422": { - "description": "Validation failed" } }, "x-auth": [ @@ -5646,17 +12907,20 @@ ] } }, - "/api/v1/agent_tools/{tool}/activate": { - "post": { - "operationId": "post_api_v1_agent_tools__tool_activate", + "/api/v1/config/kinds": { + "get": { + "operationId": "get_api_v1_config_kinds", "parameters": [ { - "description": "Tool ID", - "in": "path", - "name": "tool", - "required": true, + "description": "Filter by config kind name(s)", + "in": "query", + "name": "kind", + "required": false, "schema": { - "type": "string" + "items": { + "type": "string" + }, + "type": "array" } } ], @@ -5665,7 +12929,49 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AgentTool" + "description": "List of available config kinds", + "properties": { + "data": { + "description": "The config kinds", + "items": { + "description": "Schema for a config kind in the list response.\n", + "properties": { + "classification": { + "description": "Kind classification: root or supplemental", + "type": "string" + }, + "description": { + "description": "Markdown documentation describing what this config kind represents and how to use it", + "type": "string" + }, + "kind": { + "description": "The config kind name (e.g., Agent, APITool)", + "type": "string" + }, + "sample_available": { + "description": "Whether a YAML sample is available", + "type": "boolean" + }, + "schema_available": { + "description": "Whether a JSON schema is available", + "type": "boolean" + } + }, + "required": [ + "kind", + "sample_available", + "schema_available", + "classification" + ], + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "data" + ], + "type": "object" } } }, @@ -5673,15 +12979,6 @@ }, "401": { "description": "Unauthorized" - }, - "403": { - "description": "Forbidden - app scope required" - }, - "404": { - "description": "Tool not found" - }, - "422": { - "description": "Cannot activate tool" } }, "x-auth": [ @@ -5690,14 +12987,14 @@ ] } }, - "/api/v1/agent_tools/{tool}/deactivate": { - "post": { - "operationId": "post_api_v1_agent_tools__tool_deactivate", + "/api/v1/config/kinds/{kind}/schema": { + "get": { + "operationId": "get_api_v1_config_kinds__kind_schema", "parameters": [ { - "description": "Tool ID", + "description": "The config kind to get schema for", "in": "path", - "name": "tool", + "name": "kind", "required": true, "schema": { "type": "string" @@ -5709,7 +13006,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AgentTool" + "$ref": "#/components/schemas/ConfigKindSchema" } } }, @@ -5718,11 +13015,8 @@ "401": { "description": "Unauthorized" }, - "403": { - "description": "Forbidden - app scope required" - }, "404": { - "description": "Tool not found" + "description": "Kind not found" } }, "x-auth": [ @@ -5731,44 +13025,59 @@ ] } }, - "/api/v1/agents": { + "/api/v1/config/system": { "get": { - "operationId": "get_api_v1_agents", + "operationId": "get_api_v1_config_system", "parameters": [ { - "description": "Page number (default 1)", + "description": "Filter by config kind", "in": "query", - "name": "page", + "name": "kind", "required": false, "schema": { - "type": "integer" + "type": "string" } }, { - "description": "Results per page (default 25)", + "description": "Filter by config kind(s) — server-side `IN` filter. Combine with `kind` (singular) for backward compat.", "in": "query", - "name": "page_size", + "name": "kinds", "required": false, "schema": { - "type": "integer" + "items": { + "type": "string" + }, + "type": "array" } }, { - "description": "Search by agent, org, team, or owner fields", + "description": "Exclude rows whose `virtual_path` starts with any listed prefix.", "in": "query", - "name": "search", + "name": "excluded_path_prefixes", "required": false, "schema": { - "type": "string" + "items": { + "type": "string" + }, + "type": "array" } }, { - "description": "Filter to agents owned by this user", + "description": "Page number (default 1)", "in": "query", - "name": "user", + "name": "page", "required": false, "schema": { - "type": "string" + "type": "integer" + } + }, + { + "description": "Results per page (default 50, max 200)", + "in": "query", + "name": "page_size", + "required": false, + "schema": { + "type": "integer" } } ], @@ -5777,7 +13086,170 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AgentListResponse" + "description": "Paginated list of system configs", + "properties": { + "data": { + "description": "The system configs", + "items": { + "description": "API schema for a config resource.", + "properties": { + "agent": { + "description": "Agent", + "type": "string" + }, + "created_at": { + "description": "Creation timestamp", + "format": "date-time", + "type": "string" + }, + "current_version": { + "description": "Current version", + "properties": { + "change_description": { + "description": "Description of changes", + "type": "string" + }, + "content_hash": { + "description": "sha256: over UTF-8 bytes of raw_content. Same format as the CLI's computeContentHash. Nullable for rows that predate the column.", + "type": "string" + }, + "created_at": { + "description": "Creation timestamp", + "format": "date-time", + "type": "string" + }, + "data": { + "description": "Additional structured data", + "type": "object" + }, + "id": { + "description": "Config version ID (cfv_...)", + "type": "string" + }, + "org": { + "description": "Organization", + "type": "string" + }, + "sandbox": { + "description": "Sandbox", + "type": "string" + }, + "version_number": { + "description": "Version number", + "type": "integer" + } + }, + "required": [ + "id", + "version_number" + ], + "type": "object" + }, + "id": { + "description": "Config ID (cfg_...)", + "type": "string" + }, + "is_archived": { + "description": "Whether config is archived", + "type": "boolean" + }, + "kind": { + "description": "Config kind (e.g., Agent, APITool)", + "type": "string" + }, + "lookup_key": { + "description": "Optional lookup key", + "type": "string" + }, + "mime_type": { + "description": "Content mime type", + "type": "string" + }, + "org": { + "description": "Organization", + "type": "string" + }, + "parent": { + "description": "Parent config ID (bundle children only)", + "type": "string" + }, + "parent_solution": { + "description": "Solution config ID this config was imported with", + "type": "string" + }, + "raw_content": { + "description": "Raw file content (system configs only)", + "type": "string" + }, + "relative_path": { + "description": "Path within parent bundle (bundle children only)", + "type": "string" + }, + "sandbox": { + "description": "Sandbox identifier", + "type": "string" + }, + "team": { + "description": "Team", + "type": "string" + }, + "updated_at": { + "description": "Last update timestamp", + "format": "date-time", + "type": "string" + }, + "user": { + "description": "User", + "type": "string" + }, + "virtual_path": { + "description": "Unique path within the team", + "type": "string" + } + }, + "required": [ + "id", + "kind" + ], + "type": "object" + }, + "type": "array" + }, + "has_next": { + "description": "Has next page", + "type": "boolean" + }, + "has_prev": { + "description": "Has previous page", + "type": "boolean" + }, + "page": { + "description": "Current page", + "type": "integer" + }, + "page_size": { + "description": "Results per page", + "type": "integer" + }, + "total_entries": { + "description": "Total entries", + "type": "integer" + }, + "total_pages": { + "description": "Total pages", + "type": "integer" + } + }, + "required": [ + "data", + "page", + "page_size", + "total_entries", + "total_pages", + "has_next", + "has_prev" + ], + "type": "object" } } }, @@ -5785,208 +13257,31 @@ }, "401": { "description": "Unauthorized" - }, - "403": { - "description": "Forbidden - app scope required" } }, "x-auth": [ "publishable_key", "bearer" ] - }, - "post": { - "operationId": "post_api_v1_agents", + } + }, + "/api/v1/config/system/facets": { + "get": { + "operationId": "get_api_v1_config_system_facets", "parameters": [], - "requestBody": { - "content": { - "application/json": { - "schema": { - "properties": { - "acl": { - "description": "Access control list", - "properties": { - "add": { - "description": "Patch mode: grants to add or merge into existing", - "items": { - "description": "API schema for a single ACL grant entry.", - "properties": { - "actions": { - "description": "List of allowed actions (e.g. read, write)", - "items": { - "type": "string" - }, - "type": "array" - }, - "principal": { - "description": "Principal identifier (UUID for user/team/org/agent_user, role name for org_role, omit for everyone)", - "type": "string" - }, - "principal_type": { - "description": "Principal type: user, team, org, org_role, agent, or everyone", - "type": "string" - } - }, - "required": [ - "principal_type", - "actions" - ], - "type": "object" - }, - "type": "array" - }, - "grants": { - "description": "Replace mode: full list of grants (replaces all existing). Use [] to clear.", - "items": { - "description": "API schema for a single ACL grant entry.", - "properties": { - "actions": { - "description": "List of allowed actions (e.g. read, write)", - "items": { - "type": "string" - }, - "type": "array" - }, - "principal": { - "description": "Principal identifier (UUID for user/team/org/agent_user, role name for org_role, omit for everyone)", - "type": "string" - }, - "principal_type": { - "description": "Principal type: user, team, org, org_role, agent, or everyone", - "type": "string" - } - }, - "required": [ - "principal_type", - "actions" - ], - "type": "object" - }, - "type": "array" - }, - "remove": { - "description": "Patch mode: principals to remove from existing", - "items": { - "description": "API schema for identifying a principal to remove from an ACL.", - "properties": { - "principal": { - "description": "Principal identifier to remove (omit for everyone)", - "type": "string" - }, - "principal_type": { - "description": "Principal type to remove", - "type": "string" - } - }, - "required": [ - "principal_type" - ], - "type": "object" - }, - "type": "array" - } - }, - "type": "object" - }, - "email": { - "description": "Agent email", - "type": "string" - }, - "identity": { - "description": "Identity prompt describing who the agent is", - "type": "string" - }, - "lookup_key": { - "description": "Unique lookup key", - "type": "string" - }, - "metadata": { - "description": "Arbitrary metadata", - "type": "object" - }, - "model": { - "description": "Default AI model for this agent", - "type": "string" - }, - "name": { - "description": "Agent name", - "type": "string" - }, - "org": { - "description": "Organization ID", - "type": "string" - }, - "phone_number": { - "description": "Agent phone number", - "type": "string" - }, - "profile_picture": { - "description": "Base64-encoded profile picture", - "properties": { - "data": { - "description": "Base64-encoded image data", - "type": "string" - }, - "filename": { - "description": "Original filename", - "type": "string" - }, - "mime_type": { - "description": "MIME type of the image", - "type": "string" - } - }, - "required": [ - "data", - "mime_type", - "filename" - ], - "type": "object" - }, - "team": { - "description": "Team ID", - "type": "string" - }, - "template": { - "description": "Template ID to provision agent from", - "type": "string" - }, - "user": { - "description": "User ID", - "type": "string" - } - }, - "type": "object" - } - } - }, - "required": true - }, "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Agent" + "$ref": "#/components/schemas/ConfigFacets" } } }, "description": "Successful response" }, - "400": { - "description": "name or template_id is required" - }, "401": { "description": "Unauthorized" - }, - "403": { - "description": "Forbidden - app scope required" - }, - "404": { - "description": "Template not found" - }, - "422": { - "description": "Validation failed" } }, "x-auth": [ @@ -5995,14 +13290,14 @@ ] } }, - "/api/v1/agents/{agent}": { - "delete": { - "operationId": "delete_api_v1_agents__agent", + "/api/v1/config/system/{system}": { + "get": { + "operationId": "get_api_v1_config_system__system", "parameters": [ { - "description": "Agent ID", + "description": "Config path or lookup_key", "in": "path", - "name": "agent", + "name": "system", "required": true, "schema": { "type": "string" @@ -6010,230 +13305,144 @@ } ], "responses": { - "204": { - "description": "No content" + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Config" + } + } + }, + "description": "Successful response" }, "401": { "description": "Unauthorized" }, - "403": { - "description": "App-scoped token required. Use a token scoped to the target app.; Permission denied. The connected account may not have the required permissions. Try reconnecting your account." - }, "404": { - "description": "Agent not found" + "description": "Config not found" } }, "x-auth": [ "publishable_key", "bearer" ] - }, - "get": { - "operationId": "get_api_v1_agents__agent", + } + }, + "/api/v1/config/system/{system}/clone": { + "post": { + "operationId": "post_api_v1_config_system__system_clone", "parameters": [ { - "description": "Agent ID or lookup_key (handle)", + "description": "Source system config path or lookup_key", "in": "path", - "name": "agent", + "name": "system", "required": true, "schema": { "type": "string" } } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "lookup_key": { + "description": "Override lookup_key on the clone", + "type": "string" + }, + "org": { + "description": "Scope the clone to an org (must match viewer's org if set)", + "type": "string" + }, + "team": { + "description": "Clone to this team", + "type": "string" + }, + "user": { + "description": "Clone to this user", + "type": "string" + }, + "virtual_path": { + "description": "Override virtual_path on the clone", + "type": "string" + } + }, + "type": "object" + } + } + }, + "required": true + }, "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Agent" + "$ref": "#/components/schemas/Config" } } }, "description": "Successful response" }, + "400": { + "description": "Bad request - owner required" + }, "401": { "description": "Unauthorized" }, - "403": { - "description": "Forbidden - app scope required" - }, "404": { - "description": "Agent not found" + "description": "Source config not found" + }, + "422": { + "description": "Validation failed" } }, "x-auth": [ "publishable_key", "bearer" ] - }, - "patch": { - "operationId": "patch_api_v1_agents__agent", - "parameters": [ - { - "description": "Agent ID", - "in": "path", - "name": "agent", - "required": true, - "schema": { - "type": "string" - } - } - ], + } + }, + "/api/v1/config/validate": { + "post": { + "operationId": "post_api_v1_config_validate", + "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { - "acl": { - "description": "Access control list", - "properties": { - "add": { - "description": "Patch mode: grants to add or merge into existing", - "items": { - "description": "API schema for a single ACL grant entry.", - "properties": { - "actions": { - "description": "List of allowed actions (e.g. read, write)", - "items": { - "type": "string" - }, - "type": "array" - }, - "principal": { - "description": "Principal identifier (UUID for user/team/org/agent_user, role name for org_role, omit for everyone)", - "type": "string" - }, - "principal_type": { - "description": "Principal type: user, team, org, org_role, agent, or everyone", - "type": "string" - } - }, - "required": [ - "principal_type", - "actions" - ], - "type": "object" - }, - "type": "array" - }, - "grants": { - "description": "Replace mode: full list of grants (replaces all existing). Use [] to clear.", - "items": { - "description": "API schema for a single ACL grant entry.", - "properties": { - "actions": { - "description": "List of allowed actions (e.g. read, write)", - "items": { - "type": "string" - }, - "type": "array" - }, - "principal": { - "description": "Principal identifier (UUID for user/team/org/agent_user, role name for org_role, omit for everyone)", - "type": "string" - }, - "principal_type": { - "description": "Principal type: user, team, org, org_role, agent, or everyone", - "type": "string" - } - }, - "required": [ - "principal_type", - "actions" - ], - "type": "object" - }, - "type": "array" - }, - "remove": { - "description": "Patch mode: principals to remove from existing", - "items": { - "description": "API schema for identifying a principal to remove from an ACL.", - "properties": { - "principal": { - "description": "Principal identifier to remove (omit for everyone)", - "type": "string" - }, - "principal_type": { - "description": "Principal type to remove", - "type": "string" - } - }, - "required": [ - "principal_type" - ], - "type": "object" - }, - "type": "array" - } - }, - "type": "object" - }, - "email": { - "description": "Agent email", - "type": "string" - }, - "identity": { - "description": "Identity prompt describing who the agent is", - "type": "string" - }, - "lookup_key": { - "description": "Unique lookup key", - "type": "string" - }, - "metadata": { - "description": "Arbitrary metadata", - "type": "object" - }, - "model": { - "description": "Default AI model for this agent", + "agent": { + "description": "Agent ID (for agent-owned configs)", "type": "string" }, - "name": { - "description": "Agent name", + "kind": { + "description": "Config kind to validate against", "type": "string" }, - "org": { - "description": "Organization ID", + "mime_type": { + "description": "Content mime type", "type": "string" }, - "phone_number": { - "description": "Agent phone number", + "raw_content": { + "description": "Raw content to validate", "type": "string" }, - "profile_picture": { - "description": "Base64-encoded profile picture", - "properties": { - "data": { - "description": "Base64-encoded image data", - "type": "string" - }, - "filename": { - "description": "Original filename", - "type": "string" - }, - "mime_type": { - "description": "MIME type of the image", - "type": "string" - } - }, - "required": [ - "data", - "mime_type", - "filename" - ], - "type": "object" - }, "team": { - "description": "Team ID", + "description": "Team ID (for team-owned configs)", "type": "string" }, "user": { - "description": "User ID", + "description": "User ID (for user-owned configs)", "type": "string" } }, + "required": [ + "kind", + "raw_content", + "mime_type" + ], "type": "object" } } @@ -6245,12 +13454,49 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Agent" + "$ref": "#/components/schemas/ValidationResult" } } }, "description": "Successful response" }, + "400": { + "description": "Bad request - owner required" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/config/{config}": { + "delete": { + "operationId": "delete_api_v1_config__config", + "parameters": [ + { + "description": "Config ID, virtual_path, or lookup_key", + "in": "path", + "name": "config", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "400": { + "description": "Bad request - owner required" + }, "401": { "description": "Unauthorized" }, @@ -6258,30 +13504,73 @@ "description": "Forbidden - app scope required" }, "404": { - "description": "Agent not found" + "description": "Config not found" }, "422": { - "description": "Validation failed" + "description": "Validation failed - owner selector not allowed when addressing a config by id" } }, "x-auth": [ "publishable_key", "bearer" ] - } - }, - "/api/v1/agents/{agent}/agent_computers": { + }, "get": { - "operationId": "get_api_v1_agents__agent_agent_computers", + "operationId": "get_api_v1_config__config", "parameters": [ { - "description": "Agent ID", + "description": "Config ID, virtual_path, or lookup_key", "in": "path", - "name": "agent", + "name": "config", "required": true, "schema": { "type": "string" } + }, + { + "description": "Team ID (for team-owned configs)", + "in": "query", + "name": "team", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "User ID (for user-owned configs)", + "in": "query", + "name": "user", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Agent ID (for agent-owned configs)", + "in": "query", + "name": "agent", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Resolve a system-owned config by lookup_key/virtual_path (privileged viewer or org admin)", + "in": "query", + "name": "system", + "required": false, + "schema": { + "type": "boolean" + } + }, + { + "description": "Org ID — scope the lookup to a specific org's configs", + "in": "query", + "name": "org", + "required": false, + "schema": { + "type": "string" + } } ], "responses": { @@ -6289,12 +13578,15 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AgentComputerListResponse" + "$ref": "#/components/schemas/Config" } } }, "description": "Successful response" }, + "400": { + "description": "Bad request - owner required" + }, "401": { "description": "Unauthorized" }, @@ -6302,7 +13594,10 @@ "description": "Forbidden - app scope required" }, "404": { - "description": "Agent not found" + "description": "Config not found" + }, + "422": { + "description": "Validation failed - owner selector not allowed when addressing a config by id" } }, "x-auth": [ @@ -6310,13 +13605,13 @@ "bearer" ] }, - "post": { - "operationId": "post_api_v1_agents__agent_agent_computers", + "patch": { + "operationId": "patch_api_v1_config__config", "parameters": [ { - "description": "Agent ID", + "description": "Config ID, virtual_path, or lookup_key", "in": "path", - "name": "agent", + "name": "config", "required": true, "schema": { "type": "string" @@ -6328,30 +13623,63 @@ "application/json": { "schema": { "properties": { - "config": { - "description": "Computer configuration", + "agent": { + "description": "Agent ID (for agent-owned configs)", + "type": "string" + }, + "change_description": { + "description": "Description of changes", + "type": "string" + }, + "data": { + "description": "Additional structured data stored on the version", "type": "object" }, + "expected_version": { + "description": "Expected current version number for optimistic locking", + "type": "integer" + }, "lookup_key": { - "description": "Unique lookup key", + "description": "Update lookup key", "type": "string" }, - "metadata": { - "description": "Arbitrary metadata", - "type": "object" + "mime_type": { + "description": "Content mime type (defaults to existing if not provided)", + "type": "string" }, - "name": { - "description": "Computer name", + "org": { + "description": "Org ID — scope the lookup to a specific org's configs", "type": "string" }, - "region": { - "description": "Region to provision in (default: iad)", + "parent_solution": { + "description": "Update parent Solution provenance", + "type": "string" + }, + "raw_content": { + "description": "Raw content (YAML/JSON/etc) — omit to keep existing content (metadata-only update)", + "type": "string" + }, + "relative_path": { + "description": "Update relative path within parent bundle", + "type": "string" + }, + "system": { + "description": "Resolve a system-owned config by lookup_key/virtual_path (privileged viewer or org admin)", + "type": "boolean" + }, + "team": { + "description": "Team ID (for team-owned configs)", + "type": "string" + }, + "user": { + "description": "User ID (for user-owned configs)", + "type": "string" + }, + "virtual_path": { + "description": "Update virtual path", "type": "string" } }, - "required": [ - "name" - ], "type": "object" } } @@ -6363,12 +13691,15 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AgentComputer" + "$ref": "#/components/schemas/Config" } } }, "description": "Successful response" }, + "400": { + "description": "Bad request - owner required" + }, "401": { "description": "Unauthorized" }, @@ -6376,7 +13707,10 @@ "description": "Forbidden - app scope required" }, "404": { - "description": "Agent not found" + "description": "Config not found" + }, + "409": { + "description": "Conflict - config version changed" }, "422": { "description": "Validation failed" @@ -6388,53 +13722,14 @@ ] } }, - "/api/v1/agents/{agent}/agent_installations": { - "get": { - "operationId": "get_api_v1_agents__agent_agent_installations", - "parameters": [ - { - "description": "Agent ID", - "in": "path", - "name": "agent", - "required": true, - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/InstallationListResponse" - } - } - }, - "description": "Successful response" - }, - "401": { - "description": "Unauthorized" - }, - "403": { - "description": "Forbidden - app scope required" - }, - "404": { - "description": "Agent not found" - } - }, - "x-auth": [ - "publishable_key", - "bearer" - ] - }, + "/api/v1/config/{config}/archive": { "post": { - "operationId": "post_api_v1_agents__agent_agent_installations", + "operationId": "post_api_v1_config__config_archive", "parameters": [ { - "description": "Agent ID", + "description": "Config ID, virtual_path, or lookup_key", "in": "path", - "name": "agent", + "name": "config", "required": true, "schema": { "type": "string" @@ -6446,48 +13741,27 @@ "application/json": { "schema": { "properties": { - "config": { - "description": "Optional configuration", - "type": "object" + "agent": { + "description": "Agent ID (for agent-owned configs)", + "type": "string" }, - "integration": { - "description": "Integration fields to auto-create for integration/* kinds. When provided, creates the underlying Integration record and activates the installation.", - "properties": { - "access_token": { - "description": "OAuth access token or API key", - "type": "string" - }, - "installation_id": { - "description": "External installation ID (e.g. GitHub App installation ID, Slack team_id)", - "type": "string" - }, - "metadata": { - "description": "Provider-specific metadata (e.g. bot_user_id)", - "type": "object" - }, - "refresh_token": { - "description": "OAuth refresh token", - "type": "string" - }, - "workspace_key": { - "description": "Workspace name or identifier", - "type": "string" - } - }, - "type": "object" + "org": { + "description": "Org ID — scope the lookup to a specific org's configs", + "type": "string" }, - "kind": { - "description": "Installation kind (gmail, outlook, github, scrape/site)", + "system": { + "description": "Resolve a system-owned config by lookup_key/virtual_path (privileged viewer or org admin)", + "type": "boolean" + }, + "team": { + "description": "Team ID (for team-owned configs)", "type": "string" }, - "shared_integration": { - "description": "Shared org/app integration ID to bind to this installation", + "user": { + "description": "User ID (for user-owned configs)", "type": "string" } }, - "required": [ - "kind" - ], "type": "object" } } @@ -6499,12 +13773,15 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Installation" + "$ref": "#/components/schemas/Config" } } }, "description": "Successful response" }, + "400": { + "description": "Bad request - owner required" + }, "401": { "description": "Unauthorized" }, @@ -6512,10 +13789,10 @@ "description": "Forbidden - app scope required" }, "404": { - "description": "Agent not found" + "description": "Config not found" }, "422": { - "description": "Validation failed" + "description": "Validation failed - owner selector not allowed when addressing a config by id" } }, "x-auth": [ @@ -6524,36 +13801,77 @@ ] } }, - "/api/v1/agents/{agent}/agent_installations/kinds": { - "get": { - "operationId": "get_api_v1_agents__agent_agent_installations_kinds", + "/api/v1/config/{config}/change_owner": { + "post": { + "operationId": "post_api_v1_config__config_change_owner", "parameters": [ { - "description": "Agent ID", + "description": "Config ID (must be id-form: cfg_... or UUID — lookup_key/virtual_path rejected)", "in": "path", - "name": "agent", + "name": "config", "required": true, "schema": { "type": "string" } - } - ], + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "agent": { + "description": "New owner: Agent ID", + "type": "string" + }, + "org": { + "description": "Only meaningful with system:true. Omit → keep existing org_id; explicit value → that org; blank/null → app-level (org_id nil).", + "type": "string" + }, + "system": { + "description": "New owner: system (app-level). Requires privileged viewer.", + "type": "boolean" + }, + "team": { + "description": "New owner: Team ID", + "type": "string" + }, + "user": { + "description": "New owner: User ID", + "type": "string" + } + }, + "type": "object" + } + } + }, + "required": true + }, "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/InstallationKindListResponse" + "$ref": "#/components/schemas/Config" } } }, "description": "Successful response" }, + "400": { + "description": "Bad request - new owner required" + }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - app scope required" + }, + "404": { + "description": "Config not found (also returned when viewer cannot modify it)" + }, + "422": { + "description": "Validation failed (owner conflict, unique constraint, id-form required)" } }, "x-auth": [ @@ -6562,282 +13880,157 @@ ] } }, - "/api/v1/agents/{agent}/agent_routines": { - "post": { - "operationId": "post_api_v1_agents__agent_agent_routines", + "/api/v1/config/{config}/content": { + "get": { + "operationId": "get_api_v1_config__config_content", "parameters": [ { - "description": "Agent ID", + "description": "Config ID, virtual_path, or lookup_key", "in": "path", - "name": "agent", + "name": "config", "required": true, "schema": { "type": "string" } + }, + { + "description": "Team ID (for team-owned configs)", + "in": "query", + "name": "team", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "User ID (for user-owned configs)", + "in": "query", + "name": "user", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Agent ID (for agent-owned configs)", + "in": "query", + "name": "agent", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Resolve a system-owned config by lookup_key/virtual_path (privileged viewer or org admin)", + "in": "query", + "name": "system", + "required": false, + "schema": { + "type": "boolean" + } + }, + { + "description": "Org ID — scope the lookup to a specific org's configs", + "in": "query", + "name": "org", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Output format: yaml or json (converts if needed)", + "in": "query", + "name": "format", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "When false, returns stored raw content without injecting protected fields like virtual_path", + "in": "query", + "name": "inject_protected_fields", + "required": false, + "schema": { + "type": "boolean" + } } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "properties": { - "acl": { - "description": "Access control list", - "properties": { - "add": { - "description": "Patch mode: grants to add or merge into existing", - "items": { - "description": "API schema for a single ACL grant entry.", - "properties": { - "actions": { - "description": "List of allowed actions (e.g. read, write)", - "items": { - "type": "string" - }, - "type": "array" - }, - "principal": { - "description": "Principal identifier (UUID for user/team/org/agent_user, role name for org_role, omit for everyone)", - "type": "string" - }, - "principal_type": { - "description": "Principal type: user, team, org, org_role, agent, or everyone", - "type": "string" - } - }, - "required": [ - "principal_type", - "actions" - ], - "type": "object" - }, - "type": "array" - }, - "grants": { - "description": "Replace mode: full list of grants (replaces all existing). Use [] to clear.", - "items": { - "description": "API schema for a single ACL grant entry.", - "properties": { - "actions": { - "description": "List of allowed actions (e.g. read, write)", - "items": { - "type": "string" - }, - "type": "array" - }, - "principal": { - "description": "Principal identifier (UUID for user/team/org/agent_user, role name for org_role, omit for everyone)", - "type": "string" - }, - "principal_type": { - "description": "Principal type: user, team, org, org_role, agent, or everyone", - "type": "string" - } - }, - "required": [ - "principal_type", - "actions" - ], - "type": "object" - }, - "type": "array" - }, - "remove": { - "description": "Patch mode: principals to remove from existing", - "items": { - "description": "API schema for identifying a principal to remove from an ACL.", - "properties": { - "principal": { - "description": "Principal identifier to remove (omit for everyone)", - "type": "string" - }, - "principal_type": { - "description": "Principal type to remove", - "type": "string" - } - }, - "required": [ - "principal_type" - ], - "type": "object" - }, - "type": "array" - } - }, - "type": "object" - }, - "config": { - "description": "Config ID (for workflow_graph handler)", - "type": "string" - }, - "description": { - "description": "Description", - "type": "string" - }, - "event_config": { - "description": "Event config map. Keys are event types, values are entry objects with \"filters\" (filter map) and optional \"dedupe_key_path\" (JSON path for deduplication, e.g. \"$.thread.id\")", - "type": "object" - }, - "event_type": { - "description": "Event type (deprecated, use event_config)", - "type": "string" - }, - "handler_type": { - "description": "Handler type: workflow_graph, script, preset, or chain", - "type": "string" - }, - "lookup_key": { - "description": "Unique lookup key", - "type": "string" - }, - "metadata": { - "description": "Arbitrary metadata", - "type": "object" - }, - "name": { - "description": "Routine name", - "type": "string" - }, - "preset_config": { - "description": "Preset config", - "properties": { - "instructions": { - "description": "Custom task or behavior instructions for the preset (max 10,000 chars).", - "type": "string" - }, - "llm": { - "description": "LLM invocation settings (e.g. a `model` override for this routine/step).", - "properties": { - "model": { - "description": "Model identifier. When set, overrides the agent's default_model.", - "type": "string" - } - }, - "type": "object" - }, - "session_mode": { - "description": "Session mode: `stateless` (default, new session per trigger) or `session` (find-or-create a persistent session scoped by `session_scope`).", - "type": "string" - }, - "session_scope": { - "description": "When `session_mode` is `session`, controls session scoping: `per_user` (default), `per_key`, `per_org`, or `global`.", - "type": "string" - }, - "structured_message_template_ids": { - "description": "Config IDs of AgentMessageSchema templates that constrain the agent's responses to predefined structured formats.", - "items": { - "type": "string" - }, - "type": "array" - } - }, - "type": "object" - }, - "preset_name": { - "description": "Preset name (for preset handler)", + "responses": { + "200": { + "content": { + "*/*": { + "schema": { + "format": "binary", + "type": "string" + } + } + }, + "description": "Raw config content" + }, + "400": { + "description": "Bad request - owner required or conversion not possible" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Config not found" + }, + "422": { + "description": "Validation failed - owner selector not allowed when addressing a config by id" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/config/{config}/unarchive": { + "post": { + "operationId": "post_api_v1_config__config_unarchive", + "parameters": [ + { + "description": "Config ID, virtual_path, or lookup_key", + "in": "path", + "name": "config", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "agent": { + "description": "Agent ID (for agent-owned configs)", "type": "string" }, - "schedule": { - "description": "Cron expression for scheduled routines", + "org": { + "description": "Org ID — scope the lookup to a specific org's configs", "type": "string" }, - "script": { - "description": "Script content (for script handler)", - "type": "string" + "system": { + "description": "Resolve a system-owned config by lookup_key/virtual_path (privileged viewer or org admin)", + "type": "boolean" }, - "status": { - "description": "Initial status: draft or active (default: draft)", + "team": { + "description": "Team ID (for team-owned configs)", "type": "string" }, - "steps": { - "description": "Linear sequence of steps (required when handler_type is \"chain\"; must be empty otherwise). See the Step schema for the per-step fields. Exactly one handler body field (preset_name, script, or config) must be populated per step, matching that step's handler_type.", - "items": { - "description": "API schema for a single chain-routine step.\n\nMirrors the shape of `ArchAstro.Agents.Routines.Step` as seen by clients,\nwith one API-side normalization: clients send `config` (matching the\nroutine-level field name), and `cast/1` rewrites it to `config_id` so\ndownstream changeset code sees the canonical key.\n\nServer-side validation (handler-body mutual exclusion, `config_id`\nexistence + kind, unique step names within a chain) is authoritative\n— this schema only defines the *shape* of the request payload.\n", - "properties": { - "config": { - "description": "Config ID (for handler_type: workflow_graph, or as an alternative to inline `script` when handler_type: script). Normalized to `config_id` internally.", - "type": "string" - }, - "handler_type": { - "description": "Handler type for this step: preset, script, or workflow_graph", - "type": "string" - }, - "inputs": { - "description": "Optional map binding prior step outputs to this step's inputs.", - "type": "object" - }, - "name": { - "description": "Optional step label. Must be unique within the chain if set.", - "type": "string" - }, - "on_error": { - "description": "Error policy: halt (default), continue, or retry.", - "type": "string" - }, - "output_key": { - "description": "Optional name under which this step's result is addressable downstream. Defaults to `name`.", - "type": "string" - }, - "preset_config": { - "description": "Preset configuration (same shape as the routine-level preset_config). May include `llm: {model}` to override the agent's default_model for this step.", - "properties": { - "instructions": { - "description": "Custom task or behavior instructions for the preset (max 10,000 chars).", - "type": "string" - }, - "llm": { - "description": "LLM invocation settings (e.g. a `model` override for this routine/step).", - "properties": { - "model": { - "description": "Model identifier. When set, overrides the agent's default_model.", - "type": "string" - } - }, - "type": "object" - }, - "session_mode": { - "description": "Session mode: `stateless` (default, new session per trigger) or `session` (find-or-create a persistent session scoped by `session_scope`).", - "type": "string" - }, - "session_scope": { - "description": "When `session_mode` is `session`, controls session scoping: `per_user` (default), `per_key`, `per_org`, or `global`.", - "type": "string" - }, - "structured_message_template_ids": { - "description": "Config IDs of AgentMessageSchema templates that constrain the agent's responses to predefined structured formats.", - "items": { - "type": "string" - }, - "type": "array" - } - }, - "type": "object" - }, - "preset_name": { - "description": "Preset name (for handler_type: preset)", - "type": "string" - }, - "script": { - "description": "Inline script source (for handler_type: script)", - "type": "string" - } - }, - "required": [ - "handler_type" - ], - "type": "object" - }, - "type": "array" - }, - "trigger_context": { - "description": "Trigger context: chat_session or event (default: event)", + "user": { + "description": "User ID (for user-owned configs)", "type": "string" } }, - "required": [ - "name", - "handler_type" - ], "type": "object" } } @@ -6849,12 +14042,160 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AgentRoutine" + "$ref": "#/components/schemas/Config" + } + } + }, + "description": "Successful response" + }, + "400": { + "description": "Bad request - owner required" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Config not found" + }, + "422": { + "description": "Validation failed - owner selector not allowed when addressing a config by id" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/config/{config}/versions": { + "get": { + "operationId": "get_api_v1_config__config_versions", + "parameters": [ + { + "description": "Config ID, virtual_path, or lookup_key", + "in": "path", + "name": "config", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Team ID (for team-owned configs)", + "in": "query", + "name": "team", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "User ID (for user-owned configs)", + "in": "query", + "name": "user", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Agent ID (for agent-owned configs)", + "in": "query", + "name": "agent", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Resolve a system-owned config by lookup_key/virtual_path (privileged viewer or org admin)", + "in": "query", + "name": "system", + "required": false, + "schema": { + "type": "boolean" + } + }, + { + "description": "Org ID — scope the lookup to a specific org's configs", + "in": "query", + "name": "org", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "description": "Version history response", + "properties": { + "versions": { + "description": "List of versions", + "items": { + "description": "API schema for a config version.", + "properties": { + "change_description": { + "description": "Description of changes", + "type": "string" + }, + "content_hash": { + "description": "sha256: over UTF-8 bytes of raw_content. Same format as the CLI's computeContentHash. Nullable for rows that predate the column.", + "type": "string" + }, + "created_at": { + "description": "Creation timestamp", + "format": "date-time", + "type": "string" + }, + "data": { + "description": "Additional structured data", + "type": "object" + }, + "id": { + "description": "Config version ID (cfv_...)", + "type": "string" + }, + "org": { + "description": "Organization", + "type": "string" + }, + "sandbox": { + "description": "Sandbox", + "type": "string" + }, + "version_number": { + "description": "Version number", + "type": "integer" + } + }, + "required": [ + "id", + "version_number" + ], + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "versions" + ], + "type": "object" } } }, "description": "Successful response" }, + "400": { + "description": "Bad request - owner required" + }, "401": { "description": "Unauthorized" }, @@ -6862,10 +14203,10 @@ "description": "Forbidden - app scope required" }, "404": { - "description": "Agent not found" + "description": "Config not found" }, "422": { - "description": "Validation failed" + "description": "Validation failed - owner selector not allowed when addressing a config by id" } }, "x-auth": [ @@ -6874,27 +14215,114 @@ ] } }, - "/api/v1/agents/{agent}/agent_tools": { + "/api/v1/custom_objects": { "get": { - "operationId": "get_api_v1_agents__agent_agent_tools", + "operationId": "get_api_v1_custom_objects", "parameters": [ { - "description": "Filter by agent ID", - "in": "path", - "name": "agent", + "description": "Schema type (lookup_key)", + "in": "query", + "name": "type", "required": true, "schema": { "type": "string" } }, { - "description": "Filter by kind (builtin or custom)", + "description": "Filter by exact row_key value", "in": "query", - "name": "kind", + "name": "row_key", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Filter by sort_key value(s) — matches any", + "in": "query", + "name": "sort_key", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + { + "description": "Filter by owning team ID(s) — matches any", + "in": "query", + "name": "team", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + { + "description": "Filter by owning user ID(s) — matches any", + "in": "query", + "name": "user", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + { + "description": "Filter by owning agent ID(s) — matches any", + "in": "query", + "name": "agent", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + { + "description": "Filter by org ID(s) — matches any", + "in": "query", + "name": "org", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + { + "description": "Full-text search against the schema's configured search_fields. When set, results are ordered by ts_rank desc instead of inserted_at desc.", + "in": "query", + "name": "query", "required": false, "schema": { "type": "string" } + }, + { + "description": "Page number (default 1)", + "in": "query", + "name": "page", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Results per page (default 25, max 100)", + "in": "query", + "name": "page_size", + "required": false, + "schema": { + "type": "integer" + } } ], "responses": { @@ -6902,20 +14330,17 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AgentToolListResponse" + "$ref": "#/components/schemas/CustomObjectListResponse" } } }, "description": "Successful response" }, + "400": { + "description": "Invalid filter combination (e.g. sort_key without row_key)" + }, "401": { "description": "Unauthorized" - }, - "403": { - "description": "Forbidden - app scope required" - }, - "404": { - "description": "Agent not found" } }, "x-auth": [ @@ -6924,70 +14349,49 @@ ] }, "post": { - "operationId": "post_api_v1_agents__agent_agent_tools", - "parameters": [ - { - "description": "Agent ID", - "in": "path", - "name": "agent", - "required": true, - "schema": { - "type": "string" - } - } - ], + "operationId": "post_api_v1_custom_objects", + "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { - "builtin_tool_config": { - "description": "Built-in tool config", - "type": "object" - }, - "builtin_tool_key": { - "description": "Built-in tool key (for builtin kind)", - "type": "string" - }, - "config": { - "description": "Config ID (for custom kind)", + "agent": { + "description": "Owning agent (agent_user_id)", "type": "string" }, - "description": { - "description": "Tool description (for custom kind)", - "type": "string" + "fields": { + "description": "Field values for the new object", + "type": "object" }, - "handler_type": { - "description": "Handler type: script or workflow_graph (for custom kind)", + "org": { + "description": "Org ID to stamp on the row (typically required for system-owned)", "type": "string" }, - "kind": { - "description": "Tool kind: builtin or custom", - "type": "string" + "system": { + "description": "Create a system-owned (no team/user/agent owner) object. Requires admin, developer, or all_powerful viewer; otherwise can_create rejects with :forbidden.", + "type": "boolean" }, - "lookup_key": { - "description": "Unique lookup key", + "team": { + "description": "Owning team ID", "type": "string" }, - "metadata": { - "description": "Arbitrary metadata", - "type": "object" - }, - "name": { - "description": "Tool name (for custom kind)", + "type": { + "description": "Schema type (lookup_key)", "type": "string" }, - "parameters": { - "description": "JSON schema for parameters (for custom kind)", - "type": "object" + "upsert": { + "description": "When the schema declares a row_key (and optionally a sort_key) and a row already exists at that key for the same owner, update it in place instead of returning 409 Conflict. Returns 200 on update, 201 on create.", + "type": "boolean" }, - "status": { - "description": "Tool status: draft or active (default: draft)", + "user": { + "description": "Owning user ID", "type": "string" } }, "required": [ - "kind" + "type", + "fields" ], "type": "object" } @@ -7000,7 +14404,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AgentTool" + "$ref": "#/components/schemas/CustomObject" } } }, @@ -7010,10 +14414,10 @@ "description": "Unauthorized" }, "403": { - "description": "Forbidden - app scope required" + "description": "Forbidden" }, "404": { - "description": "Agent not found" + "description": "Not found" }, "422": { "description": "Validation failed" @@ -7025,42 +14429,75 @@ ] } }, - "/api/v1/agents/{agent}/agent_working_memory": { - "get": { - "operationId": "get_api_v1_agents__agent_agent_working_memory", + "/api/v1/custom_objects/{object}": { + "delete": { + "operationId": "delete_api_v1_custom_objects__object", "parameters": [ { - "description": "Agent ID", + "description": "Object ID", "in": "path", - "name": "agent", + "name": "object", "required": true, "schema": { "type": "string" } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "description": "Deletion result", + "properties": { + "deleted": { + "description": "Always true on success", + "type": "boolean" + }, + "id": { + "description": "The deleted object's ID", + "type": "string" + } + }, + "required": [ + "deleted", + "id" + ], + "type": "object" + } + } + }, + "description": "Successful response" }, - { - "description": "Page number (default 1)", - "in": "query", - "name": "page", - "required": false, - "schema": { - "type": "integer" - } + "401": { + "description": "Unauthorized" }, + "404": { + "description": "Not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "get": { + "operationId": "get_api_v1_custom_objects__object", + "parameters": [ { - "description": "Results per page (default 25)", + "description": "Object schema type (lookup_key)", "in": "query", - "name": "page_size", + "name": "type", "required": false, "schema": { - "type": "integer" + "type": "string" } }, { - "description": "Filter by key (ilike match)", - "in": "query", - "name": "search", - "required": false, + "description": "Object ID", + "in": "path", + "name": "object", + "required": true, "schema": { "type": "string" } @@ -7071,7 +14508,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/WorkingMemoryEntryListResponse" + "$ref": "#/components/schemas/CustomObject" } } }, @@ -7080,40 +14517,126 @@ "401": { "description": "Unauthorized" }, - "403": { - "description": "Forbidden - app scope required" - }, "404": { - "description": "Agent not found" + "description": "Not found" } }, "x-auth": [ "publishable_key", "bearer" ] - } - }, - "/api/v1/agents/{agent}/export": { - "get": { - "description": "Reconstructs an AgentTemplate config from a deployed agent and its sub-resources\n(tools, routines, skills, installations). Returns the template plus all dependent\nconfig files (scripts, workflows, skills, schemas) with their raw content for a\nfully self-contained export.\n", - "operationId": "get_api_v1_agents__agent_export", + }, + "put": { + "operationId": "put_api_v1_custom_objects__object", "parameters": [ { - "description": "Agent ID or lookup_key", + "description": "Object ID", "in": "path", - "name": "agent", + "name": "object", "required": true, "schema": { "type": "string" } } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "field_ops": { + "description": "Granular array operations per field", + "type": "object" + }, + "fields": { + "description": "Object field values to update", + "type": "object" + }, + "type": { + "description": "Object schema type (lookup_key)", + "type": "string" + } + }, + "required": [ + "fields" + ], + "type": "object" + } + } + }, + "required": true + }, "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AgentExport" + "description": "Updated custom object response", + "properties": { + "data": { + "description": "The updated object", + "properties": { + "created_at": { + "description": "Created timestamp", + "format": "date-time", + "type": "string" + }, + "fields": { + "description": "Object field values", + "type": "object" + }, + "id": { + "description": "Public ID (cobj_...)", + "type": "string" + }, + "org": { + "description": "Organization", + "type": "string" + }, + "row_key": { + "description": "Row key", + "type": "string" + }, + "sandbox": { + "description": "Sandbox identifier", + "type": "string" + }, + "schema_type": { + "description": "Schema type (lookup_key)", + "type": "string" + }, + "team": { + "description": "Owning team", + "type": "string" + }, + "updated_at": { + "description": "Updated timestamp", + "format": "date-time", + "type": "string" + }, + "user": { + "description": "Owning user", + "type": "string" + }, + "version": { + "description": "Aggregate version for OCC", + "type": "integer" + } + }, + "required": [ + "id" + ], + "type": "object" + }, + "meta": { + "description": "Version metadata", + "type": "object" + } + }, + "required": [ + "data" + ], + "type": "object" } } }, @@ -7122,38 +14645,37 @@ "401": { "description": "Unauthorized" }, - "403": { - "description": "Forbidden - app scope required" - }, "404": { - "description": "Agent not found" + "description": "Not found" + }, + "422": { + "description": "Validation failed" } }, - "summary": "Export agent as AgentTemplate", "x-auth": [ "publishable_key", "bearer" ] } }, - "/api/v1/agents/{agent}/schedules": { + "/api/v1/files/{file}/avatar": { "get": { - "operationId": "get_api_v1_agents__agent_schedules", + "operationId": "get_api_v1_files__file_avatar", "parameters": [ { - "description": "Agent ID", + "description": "Profile picture file ID (fil_…)", "in": "path", - "name": "agent", + "name": "file", "required": true, "schema": { "type": "string" } }, { - "description": "Filter by status (default: active and paused)", + "description": "HMAC capability token minted with the URL (see AvatarPublicUrl)", "in": "query", - "name": "status", - "required": false, + "name": "token", + "required": true, "schema": { "type": "string" } @@ -7162,136 +14684,29 @@ "responses": { "200": { "content": { - "application/json": { + "*/*": { "schema": { - "description": "List of schedules", - "properties": { - "data": { - "description": "Schedule entries", - "items": { - "description": "API schema for an agent schedule.", - "properties": { - "agent": { - "description": "Owning agent ID", - "type": "string" - }, - "app": { - "description": "Application ID", - "type": "string" - }, - "created_at": { - "description": "Creation timestamp", - "format": "date-time", - "type": "string" - }, - "cron_expression": { - "description": "Cron expression (recurring only)", - "type": "string" - }, - "id": { - "description": "Schedule ID (asc_...)", - "type": "string" - }, - "instructions": { - "description": "Task instructions", - "type": "string" - }, - "last_run_at": { - "description": "Last execution time", - "format": "date-time", - "type": "string" - }, - "max_runs": { - "description": "Maximum runs (recurring only)", - "type": "integer" - }, - "metadata": { - "description": "Arbitrary metadata", - "type": "object" - }, - "next_run_at": { - "description": "Next scheduled execution", - "format": "date-time", - "type": "string" - }, - "run_count": { - "description": "Number of times executed", - "type": "integer" - }, - "schedule_type": { - "description": "Schedule type (once or recurring)", - "type": "string" - }, - "scheduled_at": { - "description": "One-time execution time", - "format": "date-time", - "type": "string" - }, - "status": { - "description": "Schedule status", - "type": "string" - }, - "thread": { - "description": "Thread ID (if thread-bound)", - "type": "string" - }, - "timezone": { - "description": "Schedule timezone", - "type": "string" - }, - "updated_at": { - "description": "Last update timestamp", - "format": "date-time", - "type": "string" - } - }, - "required": [ - "id" - ], - "type": "object" - }, - "type": "array" - } - }, - "type": "object" + "format": "binary", + "type": "string" } } }, - "description": "Successful response" - }, - "400": { - "description": "Invalid status value" - }, - "401": { - "description": "Unauthorized" + "description": "Avatar image bytes" }, - "403": { - "description": "Forbidden - app scope required" + "404": { + "description": "Not found" } - }, - "x-auth": [ - "publishable_key", - "bearer" - ] + } } }, - "/api/v1/agents/{agent}/schedules/{schedule}": { - "get": { - "operationId": "get_api_v1_agents__agent_schedules__schedule", - "parameters": [ - { - "description": "Agent ID", - "in": "path", - "name": "agent", - "required": true, - "schema": { - "type": "string" - } - }, + "/api/v1/installation_sources/{source}": { + "delete": { + "operationId": "delete_api_v1_installation_sources__source", + "parameters": [ { - "description": "Schedule ID", + "description": "Source ID to remove", "in": "path", - "name": "schedule", + "name": "source", "required": true, "schema": { "type": "string" @@ -7299,15 +14714,8 @@ } ], "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AgentSchedule" - } - } - }, - "description": "Successful response" + "204": { + "description": "No content" }, "401": { "description": "Unauthorized" @@ -7316,7 +14724,7 @@ "description": "Forbidden - app scope required" }, "404": { - "description": "Schedule not found" + "description": "Installation or source not found" } }, "x-auth": [ @@ -7325,51 +14733,22 @@ ] } }, - "/api/v1/agents/{agent}/search": { + "/api/v1/invites/accept": { "post": { - "operationId": "post_api_v1_agents__agent_search", - "parameters": [ - { - "description": "Agent ID", - "in": "path", - "name": "agent", - "required": true, - "schema": { - "type": "string" - } - } - ], + "operationId": "post_api_v1_invites_accept", + "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { - "max_results": { - "description": "Max results to return", - "type": "integer" - }, - "mode": { - "description": "Search mode: hybrid, vector, or fulltext", - "type": "string" - }, - "query": { - "description": "Search query", + "key": { + "description": "Invite key", "type": "string" - }, - "recency_days": { - "description": "Limit results to last N days", - "type": "integer" - }, - "source_types": { - "description": "Filter by source types", - "items": { - "type": "string" - }, - "type": "array" } }, "required": [ - "query" + "key" ], "type": "object" } @@ -7382,40 +14761,165 @@ "content": { "application/json": { "schema": { - "description": "Search results", + "$ref": "#/components/schemas/UserInvite" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Invite not found" + }, + "409": { + "description": "Conflict" + }, + "422": { + "description": "Validation failed" + }, + "429": { + "description": "Too many requests" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/knowledge_documents": { + "get": { + "operationId": "get_api_v1_knowledge_documents", + "parameters": [ + { + "description": "Page number (default 1)", + "in": "query", + "name": "page", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Results per page (default 25)", + "in": "query", + "name": "page_size", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Filter by title (case-insensitive prefix)", + "in": "query", + "name": "q", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Filter by source IDs", + "in": "query", + "name": "source", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + { + "description": "Filter by installation IDs", + "in": "query", + "name": "installation", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + { + "description": "Filter by agent IDs", + "in": "query", + "name": "agent", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "description": "Paginated list of documents", "properties": { "data": { - "description": "Matching knowledge items", + "description": "The documents", "items": { - "description": "API schema for a knowledge search result item.", + "description": "Schema for a context document (`Context.Doc`).\n\nCarries metadata only — full text is returned by the `/content` endpoint.\n", "properties": { - "content": { - "description": "Normalized content text", - "type": "string" - }, - "content_type": { - "description": "Content MIME type", + "agent": { + "description": "Owning agent user", "type": "string" }, "created_at": { - "description": "Creation timestamp", + "description": "Created timestamp", "format": "date-time", "type": "string" }, + "file": { + "description": "Backing file ID (`fil_...`) when file-backed; nil for inline", + "type": "string" + }, "id": { - "description": "Item ID (cim_...)", + "description": "Public ID (cdo_...)", "type": "string" }, "metadata": { - "description": "Additional metadata", + "description": "Per-doc metadata", "type": "object" }, - "raw_content": { - "description": "Raw content data", - "type": "object" + "source": { + "description": "Source ID (cs_...)", + "type": "string" }, - "type": { - "description": "Source type (requires preloaded :source association)", + "team": { + "description": "Owning team", + "type": "string" + }, + "title": { + "description": "Display title", + "type": "string" + }, + "total_lines": { + "description": "Line count of `Doc.content`", + "type": "integer" + }, + "total_size": { + "description": "Byte size of `Doc.content`", + "type": "integer" + }, + "updated_at": { + "description": "Updated timestamp", + "format": "date-time", + "type": "string" + }, + "user": { + "description": "Owning user", "type": "string" } }, @@ -7425,10 +14929,40 @@ "type": "object" }, "type": "array" + }, + "has_next": { + "description": "Has next page", + "type": "boolean" + }, + "has_prev": { + "description": "Has previous page", + "type": "boolean" + }, + "page": { + "description": "Current page", + "type": "integer" + }, + "page_size": { + "description": "Results per page", + "type": "integer" + }, + "total_entries": { + "description": "Total entries", + "type": "integer" + }, + "total_pages": { + "description": "Total pages", + "type": "integer" } }, "required": [ - "data" + "data", + "page", + "page_size", + "total_entries", + "total_pages", + "has_next", + "has_prev" ], "type": "object" } @@ -7439,11 +14973,8 @@ "401": { "description": "Unauthorized" }, - "404": { - "description": "Agent not found" - }, - "422": { - "description": "Invalid parameters" + "403": { + "description": "App-scoped token required. Use a token scoped to the target app." } }, "x-auth": [ @@ -7452,79 +14983,58 @@ ] } }, - "/api/v1/agents/{agent}/threads": { - "post": { - "operationId": "post_api_v1_agents__agent_threads", + "/api/v1/knowledge_documents/{document}": { + "delete": { + "operationId": "delete_api_v1_knowledge_documents__document", + "parameters": [ + { + "description": "Document ID", + "in": "path", + "name": "document", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app." + }, + "404": { + "description": "Knowledge document not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "get": { + "operationId": "get_api_v1_knowledge_documents__document", "parameters": [ { - "description": "Agent ID", + "description": "Document ID", "in": "path", - "name": "agent", + "name": "document", "required": true, "schema": { "type": "string" } } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "properties": { - "skip_welcome_message": { - "description": "Skip automatic welcome message", - "type": "boolean" - }, - "thread": { - "description": "Thread attributes", - "properties": { - "description": { - "description": "Thread description", - "type": "string" - }, - "is_unlisted": { - "description": "Whether thread is unlisted", - "type": "boolean" - }, - "key": { - "description": "Unique thread key", - "type": "string" - }, - "metadata": { - "description": "Arbitrary metadata", - "type": "object" - }, - "org": { - "description": "Organization ID", - "type": "string" - }, - "settings": { - "description": "Thread settings", - "type": "object" - }, - "title": { - "description": "Thread title", - "type": "string" - } - }, - "type": "object" - } - }, - "required": [ - "thread" - ], - "type": "object" - } - } - }, - "required": true - }, "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Thread" + "$ref": "#/components/schemas/ContextDocument" } } }, @@ -7534,13 +15044,10 @@ "description": "Unauthorized" }, "403": { - "description": "Forbidden - app scope required" + "description": "App-scoped token required. Use a token scoped to the target app." }, "404": { - "description": "Agent not found" - }, - "422": { - "description": "Validation failed" + "description": "Knowledge document not found" } }, "x-auth": [ @@ -7549,212 +15056,69 @@ ] } }, - "/api/v1/ai/chat/completions": { - "post": { - "operationId": "post_api_v1_ai_chat_completions", - "parameters": [], - "requestBody": { - "content": { - "application/json": { - "schema": { - "properties": { - "context": { - "description": "Template context map", - "type": "object" - }, - "messages": { - "description": "Chat completion messages", - "items": { - "description": "AI chat message (OpenAI-compatible format).", - "properties": { - "content": { - "description": "Message text content", - "type": "string" - }, - "content_parts": { - "description": "Multimodal content parts", - "items": { - "type": "object" - }, - "type": "array" - }, - "resume_token": { - "description": "Resume token for continuing conversations", - "type": "string" - }, - "role": { - "description": "Message role (system, user, assistant, tool)", - "type": "string" - }, - "structured_output": { - "description": "Structured output data" - }, - "tool_calls": { - "description": "Tool calls from assistant", - "items": { - "description": "Tool call from assistant message.", - "properties": { - "arguments": { - "description": "Tool arguments", - "type": "object" - }, - "id": { - "description": "Tool call ID", - "type": "string" - }, - "name": { - "description": "Tool/function name", - "type": "string" - }, - "thought_signature": { - "description": "Optional thought signature", - "type": "string" - } - }, - "required": [ - "id", - "name", - "arguments" - ], - "type": "object" - }, - "type": "array" - }, - "tool_results": { - "description": "Tool results from tool execution", - "items": { - "description": "Tool result from tool execution.", - "properties": { - "content": { - "description": "Tool result content", - "type": "string" - }, - "id": { - "description": "Tool call ID this result responds to", - "type": "string" - }, - "name": { - "description": "Tool/function name", - "type": "string" - }, - "resolution": { - "description": "Structured tool resolution" - } - }, - "required": [ - "id", - "name" - ], - "type": "object" - }, - "type": "array" - } - }, - "required": [ - "role" - ], - "type": "object" - }, - "type": "array" - }, - "opts": { - "description": "Completion options", - "properties": { - "max_tokens": { - "description": "Maximum tokens for the response", - "type": "integer" - }, - "model": { - "description": "Model identifier", - "type": "string" - }, - "server_tools": { - "description": "Server-side tool declarations (e.g. [{type: \"search\"}])", - "items": { - "type": "object" - }, - "type": "array" - }, - "temperature": { - "description": "Sampling temperature", - "type": "number" - }, - "tools": { - "description": "OpenAI tool definitions", - "items": { - "description": "OpenAI-style tool definition.", - "properties": { - "function": { - "description": "Function tool definition", - "properties": { - "description": { - "description": "Function description", - "type": "string" - }, - "name": { - "description": "Function name", - "type": "string" - }, - "parameters": { - "description": "JSON Schema for function parameters", - "type": "object" - } - }, - "required": [ - "name", - "parameters" - ], - "type": "object" - }, - "type": { - "description": "Tool type (function)", - "type": "string" - } - }, - "required": [ - "type", - "function" - ], - "type": "object" - }, - "type": "array" - } - }, - "required": [ - "model" - ], - "type": "object" - } - }, - "required": [ - "messages", - "opts" - ], - "type": "object" - } + "/api/v1/knowledge_documents/{document}/content": { + "get": { + "operationId": "get_api_v1_knowledge_documents__document_content", + "parameters": [ + { + "description": "Document ID", + "in": "path", + "name": "document", + "required": true, + "schema": { + "type": "string" } }, - "required": true - }, + { + "description": "Optional starting position. With `unit=lines`: 1-indexed line. With `unit=bytes`: 0-indexed byte. Omit for full content.", + "in": "query", + "name": "offset", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Optional number of units to return. Defaults to 200 lines or 8192 bytes when offset is given.", + "in": "query", + "name": "limit", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Unit for offset/limit: `lines` (default) or `bytes`.", + "in": "query", + "name": "unit", + "required": false, + "schema": { + "type": "string" + } + } + ], "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AICompletionResult" + "$ref": "#/components/schemas/ContextDocumentContent" } } }, "description": "Successful response" }, - "400": { - "description": "Bad request" - }, "401": { "description": "Unauthorized" }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app." + }, + "404": { + "description": "Knowledge document not found" + }, "422": { - "description": "Validation failed" + "description": "Invalid parameters; Failed to load document content" } }, "x-auth": [ @@ -7763,227 +15127,275 @@ ] } }, - "/api/v1/ai/chat/models": { + "/api/v1/knowledge_sources": { "get": { - "operationId": "get_api_v1_ai_chat_models", - "parameters": [], + "operationId": "get_api_v1_knowledge_sources", + "parameters": [ + { + "description": "Page number (default 1)", + "in": "query", + "name": "page", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Results per page (default 25)", + "in": "query", + "name": "page_size", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Search by type", + "in": "query", + "name": "search", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Filter by source type", + "in": "query", + "name": "type", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Filter by installation ID", + "in": "query", + "name": "installation", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Filter by agent ID", + "in": "query", + "name": "agent", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Filter by org ID", + "in": "query", + "name": "org", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Owner scope filter: `any` (default — all visible), `individual` (only sources owned by a user/team/agent), or `system` (only sources with no individual owner; typically org-level when paired with `org`).", + "in": "query", + "name": "owner_scope", + "required": false, + "schema": { + "enum": [ + "any", + "individual", + "system" + ], + "type": "string" + } + } + ], "responses": { "200": { "content": { "application/json": { "schema": { - "description": "Available models", + "description": "Paginated list of context sources", "properties": { "data": { - "description": "The models", + "description": "The sources", "items": { - "description": "Schema for AI model information.", + "description": "Schema for a context source (`Context.Source`).\n", "properties": { + "agent": { + "description": "Owning agent", + "type": "string" + }, + "context_installation": { + "description": "Associated installation", + "type": "string" + }, + "created_at": { + "description": "Created timestamp", + "format": "date-time", + "type": "string" + }, "id": { - "description": "Model identifier", + "description": "Public ID (cso_...)", + "type": "string" + }, + "metadata": { + "description": "Additional metadata", + "type": "object" + }, + "org": { + "description": "Owning organization", + "type": "string" + }, + "parent_source": { + "description": "Parent source", + "type": "string" + }, + "payload": { + "description": "Type-specific configuration", + "type": "object" + }, + "sandbox": { + "description": "Owning sandbox", + "type": "string" + }, + "state": { + "description": "State: active or paused", + "type": "string" + }, + "team": { + "description": "Owning team", + "type": "string" + }, + "thread": { + "description": "Associated thread", + "type": "string" + }, + "type": { + "description": "Source type (e.g., gmail, github_activity)", + "type": "string" + }, + "updated_at": { + "description": "Updated timestamp", + "format": "date-time", + "type": "string" + }, + "user": { + "description": "Owning user", "type": "string" } }, "required": [ - "id" + "id", + "type", + "state" ], "type": "object" }, "type": "array" - } - }, - "required": [ - "data" - ], - "type": "object" - } - } - }, - "description": "Successful response" - }, - "401": { - "description": "Unauthorized" - } - }, - "x-auth": [ - "publishable_key", - "bearer" - ] - } - }, - "/api/v1/ai/image/edits": { - "post": { - "operationId": "post_api_v1_ai_image_edits", - "parameters": [], - "requestBody": { - "content": { - "application/json": { - "schema": { - "properties": { - "aspect_ratio": { - "description": "Aspect ratio (e.g. 1:1, 16:9)", - "type": "string" - }, - "background": { - "description": "Background setting (model-dependent)", - "type": "string" - }, - "height": { - "description": "Image height in pixels", - "type": "integer" - }, - "image_size": { - "description": "Image size tier for Gemini (e.g. 1K, 2K, 4K)", - "type": "string" - }, - "images": { - "description": "Source images to edit", - "items": { - "description": "Schema for an input image (base64-encoded) used in image editing.", - "properties": { - "image_data": { - "description": "Base64-encoded image data", - "type": "string" - }, - "image_type": { - "description": "MIME type (e.g. image/png, image/jpeg)", - "type": "string" - } - }, - "required": [ - "image_data", - "image_type" - ], - "type": "object" }, - "type": "array" - }, - "model": { - "description": "Model identifier (defaults to the platform default)", - "type": "string" - }, - "output_format": { - "description": "Output format (png, jpeg, webp)", - "type": "string" - }, - "prompt": { - "description": "Text description of the edit to apply", - "type": "string" - }, - "quality": { - "description": "Quality setting (model-dependent)", - "type": "string" - }, - "size": { - "description": "Size string for OpenAI models (e.g. 1024x1024)", - "type": "string" - }, - "style": { - "description": "Style setting (model-dependent)", - "type": "string" + "has_next": { + "description": "Has next page", + "type": "boolean" + }, + "has_prev": { + "description": "Has previous page", + "type": "boolean" + }, + "page": { + "description": "Current page", + "type": "integer" + }, + "page_size": { + "description": "Results per page", + "type": "integer" + }, + "total_entries": { + "description": "Total entries", + "type": "integer" + }, + "total_pages": { + "description": "Total pages", + "type": "integer" + } }, - "width": { - "description": "Image width in pixels", - "type": "integer" - } - }, - "required": [ - "prompt", - "images" - ], - "type": "object" - } - } - }, - "required": true - }, - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AIImageResult" + "required": [ + "data", + "page", + "page_size", + "total_entries", + "total_pages", + "has_next", + "has_prev" + ], + "type": "object" } } }, "description": "Successful response" }, - "400": { - "description": "Bad request" - }, "401": { "description": "Unauthorized" }, - "422": { - "description": "Image editing failed" + "403": { + "description": "App-scoped token required. Use a token scoped to the target app." } }, "x-auth": [ "publishable_key", "bearer" ] - } - }, - "/api/v1/ai/image/generations": { + }, "post": { - "operationId": "post_api_v1_ai_image_generations", + "operationId": "post_api_v1_knowledge_sources", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { - "aspect_ratio": { - "description": "Aspect ratio (e.g. 1:1, 16:9)", - "type": "string" - }, - "background": { - "description": "Background setting (model-dependent)", + "agent": { + "description": "Agent ID (owner)", "type": "string" }, - "height": { - "description": "Image height in pixels", - "type": "integer" + "metadata": { + "description": "Additional metadata", + "type": "object" }, - "image_size": { - "description": "Image size tier for Gemini (e.g. 1K, 2K, 4K)", + "org": { + "description": "Org ID — required for system-owned sources without a team/user/agent", "type": "string" }, - "model": { - "description": "Model identifier (defaults to the platform default)", + "parent_source": { + "description": "Parent source ID", "type": "string" }, - "n": { - "description": "Number of images to generate (default 1)", - "type": "integer" + "payload": { + "description": "Type-specific configuration", + "type": "object" }, - "output_format": { - "description": "Output format (png, jpeg, webp)", + "state": { + "description": "State: active or paused (default: active)", "type": "string" }, - "prompt": { - "description": "Text description of the image to generate", + "team": { + "description": "Team ID (owner)", "type": "string" }, - "quality": { - "description": "Quality setting (model-dependent)", + "thread": { + "description": "Thread ID", "type": "string" }, - "size": { - "description": "Size string for OpenAI models (e.g. 1024x1024)", + "type": { + "description": "Source type. Must be one of the kinds returned by `GET /api/v1/knowledge_sources/kinds`.", "type": "string" }, - "style": { - "description": "Style setting (model-dependent)", + "user": { + "description": "User ID (owner)", "type": "string" - }, - "width": { - "description": "Image width in pixels", - "type": "integer" } }, "required": [ - "prompt" + "type" ], "type": "object" } @@ -7992,24 +15404,24 @@ "required": true }, "responses": { - "200": { + "201": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AIImageResult" + "$ref": "#/components/schemas/KnowledgeSource" } } }, "description": "Successful response" }, - "400": { - "description": "Bad request" - }, "401": { "description": "Unauthorized" }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" + }, "422": { - "description": "Image generation failed" + "description": "Invalid parameters; Validation failed" } }, "x-auth": [ @@ -8018,46 +15430,165 @@ ] } }, - "/api/v1/ai/image/models": { + "/api/v1/knowledge_sources/kinds": { "get": { - "operationId": "get_api_v1_ai_image_models", + "operationId": "get_api_v1_knowledge_sources_kinds", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { - "description": "Available models", - "properties": { - "data": { - "description": "The models", - "items": { - "description": "Schema for AI model information.", - "properties": { - "id": { - "description": "Model identifier", - "type": "string" - } - }, - "required": [ - "id" - ], - "type": "object" - }, - "type": "array" - } + "$ref": "#/components/schemas/KnowledgeSourceKindListResponse" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app." + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/knowledge_sources/{source}": { + "delete": { + "operationId": "delete_api_v1_knowledge_sources__source", + "parameters": [ + { + "description": "Source ID", + "in": "path", + "name": "source", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" + }, + "404": { + "description": "Knowledge source not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "get": { + "operationId": "get_api_v1_knowledge_sources__source", + "parameters": [ + { + "description": "Source ID", + "in": "path", + "name": "source", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/KnowledgeSource" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app." + }, + "404": { + "description": "Knowledge source not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "patch": { + "operationId": "patch_api_v1_knowledge_sources__source", + "parameters": [ + { + "description": "Source ID", + "in": "path", + "name": "source", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "metadata": { + "description": "Additional metadata", + "type": "object" }, - "required": [ - "data" - ], - "type": "object" + "payload": { + "description": "Type-specific configuration", + "type": "object" + }, + "state": { + "description": "State: active or paused", + "type": "string" + } + }, + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/KnowledgeSource" } } }, "description": "Successful response" }, - "401": { - "description": "Unauthorized" + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" + }, + "404": { + "description": "Knowledge source not found" + }, + "422": { + "description": "Validation failed" } }, "x-auth": [ @@ -8066,47 +15597,151 @@ ] } }, - "/api/v1/artifacts/{artifact}": { - "delete": { - "operationId": "delete_api_v1_artifacts__artifact", + "/api/v1/knowledge_sources/{source}/ingest": { + "post": { + "operationId": "post_api_v1_knowledge_sources__source_ingest", "parameters": [ { - "description": "Artifact ID", + "description": "Source ID", "in": "path", - "name": "artifact", + "name": "source", "required": true, "schema": { "type": "string" } } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "content": { + "description": "Inline blob bytes. Mutually exclusive with `file` and `pull`.", + "properties": { + "content_type": { + "description": "MIME type", + "type": "string" + }, + "data": { + "description": "Content bytes (see `data_encoding`)", + "type": "string" + }, + "data_encoding": { + "description": "Encoding of `data`: \"raw\" (default) or \"base64\"", + "type": "string" + }, + "filename": { + "description": "Original filename", + "type": "string" + } + }, + "required": [ + "data" + ], + "type": "object" + }, + "file": { + "description": "ID of an already-uploaded file (`fil_...`). Upload via `POST /v1/files` first. Mutually exclusive with `content` and `pull`.", + "type": "string" + }, + "metadata": { + "description": "Per-document metadata", + "type": "object" + }, + "pull": { + "description": "Re-trigger ingestion using the source's own configured data — re-scrape a `scrape/site`, re-fetch a `web/link`, or re-process a `file/document`. Mutually exclusive with `file` and `content`. Not valid for `knowledge/documents` (use `file`/`content` to push new bytes).", + "type": "boolean" + }, + "title": { + "description": "Display title for the document", + "type": "string" + } + }, + "type": "object" + } + } + }, + "required": true + }, "responses": { - "204": { - "description": "No content" + "201": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContextIngestion" + } + } + }, + "description": "Successful response" }, "401": { "description": "Unauthorized" }, "403": { - "description": "Forbidden" + "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" }, "404": { - "description": "Artifact not found" + "description": "Knowledge source not found" + }, + "422": { + "description": "Invalid parameters" + }, + "429": { + "description": "Too many requests" } }, "x-auth": [ "publishable_key", "bearer" ] - }, + } + }, + "/api/v1/kv": { "get": { - "operationId": "get_api_v1_artifacts__artifact", + "operationId": "get_api_v1_kv", "parameters": [ { - "description": "Artifact ID", - "in": "path", - "name": "artifact", - "required": true, + "description": "Page number (developer / S2S, default 1)", + "in": "query", + "name": "page", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Results per page (developer / S2S, default 25, max 100)", + "in": "query", + "name": "page_size", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Filter by a specific user ID (developer / S2S)", + "in": "query", + "name": "user", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Substring match on user email and full name (developer / S2S)", + "in": "query", + "name": "user_search", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Prefix filter on the storage key (developer / S2S)", + "in": "query", + "name": "key", + "required": false, "schema": { "type": "string" } @@ -8117,20 +15752,20 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Artifact" + "$ref": "#/components/schemas/KeyValueStorageEntryPage" } } }, "description": "Successful response" }, + "400": { + "description": "Bad request" + }, "401": { "description": "Unauthorized" }, "403": { - "description": "Forbidden" - }, - "404": { - "description": "Artifact not found" + "description": "App-scoped token required. Use a token scoped to the target app." } }, "x-auth": [ @@ -8138,51 +15773,30 @@ "bearer" ] }, - "put": { - "operationId": "put_api_v1_artifacts__artifact", - "parameters": [ - { - "description": "Artifact ID", - "in": "path", - "name": "artifact", - "required": true, - "schema": { - "type": "string" - } - } - ], + "post": { + "operationId": "post_api_v1_kv", + "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { - "description": { - "description": "Artifact description", - "type": "string" - }, - "file_content": { - "description": "Base64 encoded file content", - "type": "string" - }, - "file_content_type": { - "description": "File MIME type", + "key": { + "description": "Storage key", "type": "string" }, - "file_name": { - "description": "File name", + "user": { + "description": "Target user ID. Required when calling as a developer or with a server-to-server key; ignored for end-user callers.", "type": "string" }, - "from_version": { - "description": "Current version for optimistic concurrency control", - "type": "integer" - }, - "name": { - "description": "Artifact name", + "value": { + "description": "Value to store", "type": "string" } }, "required": [ - "from_version" + "key", + "value" ], "type": "object" } @@ -8195,26 +15809,26 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Artifact" + "$ref": "#/components/schemas/KeyValueStorageEntry" } } }, "description": "Successful response" }, + "400": { + "description": "Bad request" + }, "401": { "description": "Unauthorized" }, "403": { - "description": "Forbidden" + "description": "Forbidden; App-scoped token required. Use a token scoped to the target app." }, "404": { - "description": "Artifact not found" - }, - "409": { - "description": "Version conflict" + "description": "User not found" }, "422": { - "description": "Validation error" + "description": "Invalid parameters" } }, "x-auth": [ @@ -8223,14 +15837,14 @@ ] } }, - "/api/v1/artifacts/{artifact}/archive": { - "post": { - "operationId": "post_api_v1_artifacts__artifact_archive", + "/api/v1/kv/{key}": { + "delete": { + "operationId": "delete_api_v1_kv__key", "parameters": [ { - "description": "Artifact ID", + "description": "Storage key", "in": "path", - "name": "artifact", + "name": "key", "required": true, "schema": { "type": "string" @@ -8241,97 +15855,104 @@ "204": { "description": "No content" }, + "400": { + "description": "Bad request" + }, "401": { "description": "Unauthorized" }, "403": { - "description": "Forbidden" + "description": "Forbidden; App-scoped token required. Use a token scoped to the target app." }, "404": { - "description": "Artifact not found" + "description": "Entry not found; User not found" } }, "x-auth": [ "publishable_key", "bearer" ] - } - }, - "/api/v1/artifacts/{artifact}/content": { + }, "get": { - "operationId": "get_api_v1_artifacts__artifact_content", + "operationId": "get_api_v1_kv__key", "parameters": [ { - "description": "Artifact ID", + "description": "Storage key", "in": "path", - "name": "artifact", + "name": "key", "required": true, "schema": { "type": "string" } }, { - "description": "Optional version number", + "description": "Target user ID. Required when calling as a developer or with a server-to-server key; ignored for end-user callers.", "in": "query", - "name": "version", + "name": "user", "required": false, "schema": { - "type": "integer" + "type": "string" } } ], "responses": { "200": { "content": { - "*/*": { + "application/json": { "schema": { - "format": "binary", - "type": "string" + "$ref": "#/components/schemas/KeyValueStorageEntry" } } }, - "description": "Raw artifact file content" + "description": "Successful response" + }, + "400": { + "description": "Bad request" }, "401": { "description": "Unauthorized" }, "403": { - "description": "Forbidden" + "description": "Forbidden; App-scoped token required. Use a token scoped to the target app." }, "404": { - "description": "Artifact content not found" - }, - "422": { - "description": "Error retrieving content" + "description": "Entry not found; User not found" } }, "x-auth": [ "publishable_key", "bearer" ] - } - }, - "/api/v1/auth/login": { - "post": { - "operationId": "post_api_v1_auth_login", - "parameters": [], + }, + "put": { + "operationId": "put_api_v1_kv__key", + "parameters": [ + { + "description": "Storage key", + "in": "path", + "name": "key", + "required": true, + "schema": { + "type": "string" + } + } + ], "requestBody": { "content": { "application/json": { "schema": { "properties": { - "email": { - "description": "User email address", + "user": { + "description": "Target user ID. Required when calling as a developer or with a server-to-server key; ignored for end-user callers.", "type": "string" }, - "password": { - "description": "User password", + "value": { + "description": "Value to store", "type": "string" } }, "required": [ - "email", - "password" + "value" ], "type": "object" } @@ -8344,116 +15965,113 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AuthTokens" + "$ref": "#/components/schemas/KeyValueStorageEntry" } } }, "description": "Successful response" }, + "400": { + "description": "Bad request" + }, "401": { - "description": "Invalid credentials" + "description": "Unauthorized" }, - "429": { - "description": "Rate limited" + "403": { + "description": "Forbidden; App-scoped token required. Use a token scoped to the target app." + }, + "404": { + "description": "User not found" + }, + "422": { + "description": "Invalid parameters" } }, - "tags": [ - "auth" - ], "x-auth": [ - "publishable_key" - ] + "publishable_key", + "bearer" + ], + "x-sdk-name": "upsert" } }, - "/api/v1/auth/refresh": { - "post": { - "operationId": "post_api_v1_auth_refresh", + "/api/v1/notification_preferences": { + "delete": { + "operationId": "delete_api_v1_notification_preferences", "parameters": [], - "requestBody": { - "content": { - "application/json": { - "schema": { - "properties": { - "refresh_token": { - "description": "Refresh token to exchange", - "type": "string" - } - }, - "required": [ - "refresh_token" - ], - "type": "object" - } - } + "responses": { + "204": { + "description": "No content" }, - "required": true + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app." + }, + "404": { + "description": "Notification preference not found" + } }, + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "get": { + "operationId": "get_api_v1_notification_preferences", + "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AuthTokens" + "$ref": "#/components/schemas/NotificationPreferenceList" } } }, "description": "Successful response" }, "401": { - "description": "Invalid or expired refresh token" + "description": "Unauthorized" }, - "429": { - "description": "Rate limited" + "403": { + "description": "App-scoped token required. Use a token scoped to the target app." } }, - "tags": [ - "auth" - ], "x-auth": [ - "publishable_key" + "publishable_key", + "bearer" ] - } - }, - "/api/v1/auth/register": { - "post": { - "operationId": "post_api_v1_auth_register", + }, + "put": { + "operationId": "put_api_v1_notification_preferences", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { - "alias": { - "description": "User alias/handle", - "type": "string" - }, - "email": { - "description": "User email address", - "type": "string" - }, - "full_name": { - "description": "User's full name", - "type": "string" - }, - "invite_code": { - "description": "Invite code for invite-based registration", + "app_id": { + "description": "Optional app to scope the preference to (nil = system / no-app slot)", "type": "string" }, - "password": { - "description": "User password (required for standard registration)", + "channel": { + "description": "Channel (e.g., \"email\"). `:in_app` is not configurable.", "type": "string" }, - "team_invite": { - "description": "Team invite ID for team-based registration", - "type": "string" + "enabled": { + "description": "Whether to enable the channel for this slot", + "type": "boolean" }, - "timezone": { - "description": "User timezone", + "type": { + "description": "Notification type. Either a builtin name (e.g., `\"app_info\"`, `\"billing_alert\"`) or a `\"custom:\"` identifier matching a NotificationType config in your app's bundle.", "type": "string" } }, "required": [ - "email" + "type", + "channel", + "enabled" ], "type": "object" } @@ -8466,50 +16084,204 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AuthTokens" + "$ref": "#/components/schemas/NotificationPreference" } } }, "description": "Successful response" }, - "400": { - "description": "Missing required parameters" + "401": { + "description": "Unauthorized" }, - "404": { - "description": "Team invite not found" + "403": { + "description": "App-scoped token required. Use a token scoped to the target app.; Viewer has no recipient context (no associated user or developer account)." }, "422": { "description": "Validation failed" } }, - "tags": [ - "auth" + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/notifications": { + "get": { + "operationId": "get_api_v1_notifications", + "parameters": [ + { + "description": "Status filter (all, active, unread, read, archived; default all)", + "in": "query", + "name": "status", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Maximum number of results (default 20, max 100)", + "in": "query", + "name": "limit", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Cursor for fetching older notifications", + "in": "query", + "name": "after_cursor", + "required": false, + "schema": { + "type": "string" + } + } ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "description": "Cursor-paginated list of notifications", + "properties": { + "after_cursor": { + "description": "Cursor for fetching older notifications", + "type": "string" + }, + "before_cursor": { + "description": "Always nil — inbox pagination is one-way", + "type": "string" + }, + "data": { + "description": "The notifications", + "items": { + "description": "API schema for an inbox notification (recipient view).", + "properties": { + "archived_at": { + "description": "When the recipient archived this (nil if not archived)", + "format": "date-time", + "type": "string" + }, + "created_at": { + "description": "When the notification was sent", + "format": "date-time", + "type": "string" + }, + "id": { + "description": "Notification ID (ntf_...)", + "type": "string" + }, + "read_at": { + "description": "When the recipient marked this read (nil if unread)", + "format": "date-time", + "type": "string" + }, + "rendered": { + "description": "Type-specific render spec. All types share `title`, `kind`, and `actions`; bespoke types add their own fields.", + "type": "object" + }, + "status": { + "description": "unread | read | archived", + "type": "string" + }, + "type": { + "description": "Notification type (e.g., app_info, custom:deploy_complete)", + "type": "string" + } + }, + "required": [ + "id", + "type", + "status", + "rendered", + "created_at" + ], + "type": "object" + }, + "type": "array" + }, + "has_more": { + "description": "Whether more items exist beyond this page", + "type": "boolean" + } + }, + "required": [ + "data", + "has_more" + ], + "type": "object" + } + } + }, + "description": "Successful response" + }, + "400": { + "description": "Bad request; Invalid cursor" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app." + } + }, "x-auth": [ - "publishable_key" + "publishable_key", + "bearer" ] } }, - "/api/v1/auth/token": { + "/api/v1/notifications/read_all": { + "post": { + "operationId": "post_api_v1_notifications_read_all", + "parameters": [], + "responses": { + "204": { + "description": "No content" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app." + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/notifications/send": { "post": { - "operationId": "post_api_v1_auth_token", + "operationId": "post_api_v1_notifications_send", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { - "timezone": { - "description": "User timezone to update if still default", + "data": { + "description": "Liquid render payload. Templates on the NotificationType config interpolate against this map plus the platform-provided render context (recipient, app, org, brand).", + "type": "object" + }, + "idempotency_key": { + "description": "Idempotency handle scoped to `(recipient, idempotency_key)`. A second send with the same key on the same recipient is a no-op and returns the originally-created notification without inserting a new row.", "type": "string" }, - "token": { - "description": "One-time login token from email", + "type": { + "description": "Custom notification type identifier in the form `custom:` matching a NotificationType config in the calling app's bundle.", + "type": "string" + }, + "user": { + "description": "Recipient user ID", "type": "string" } }, "required": [ - "token" + "type", + "user" ], "type": "object" } @@ -8522,43 +16294,80 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AuthTokens" + "$ref": "#/components/schemas/Notification" } } }, "description": "Successful response" }, "400": { - "description": "Missing token" + "description": "Bad request" }, "401": { - "description": "Invalid or expired token" + "description": "Unauthorized" }, - "429": { - "description": "Rate limited" + "403": { + "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" }, - "500": { - "description": "Token exchange failed" + "404": { + "description": "User not found" + }, + "422": { + "description": "Invalid parameters; No NotificationType config matched this `custom:` in the calling app's bundle." } }, - "tags": [ - "auth" - ], "x-auth": [ - "publishable_key" - ], - "x-sdk-name": "exchange_login_token" + "publishable_key", + "bearer" + ] } }, - "/api/v1/automation_runs/{automation_run}": { + "/api/v1/notifications/unread_count": { "get": { - "description": "Fetches one run created by an invoked automation.\n\nThis public lookup route only returns runs whose parent automation has\n`type: :invoked`.\n", - "operationId": "get_api_v1_automation_runs__automation_run", + "operationId": "get_api_v1_notifications_unread_count", + "parameters": [], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "description": "Unread count", + "properties": { + "count": { + "description": "Number of unread notifications", + "type": "integer" + } + }, + "required": [ + "count" + ], + "type": "object" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app." + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/notifications/{notification}/archive": { + "post": { + "operationId": "post_api_v1_notifications__notification_archive", "parameters": [ { - "description": "Automation run ID", + "description": "Notification ID (ntf_...)", "in": "path", - "name": "automation_run", + "name": "notification", "required": true, "schema": { "type": "string" @@ -8566,73 +16375,188 @@ } ], "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AutomationRun" - } - } - }, - "description": "Successful response" + "204": { + "description": "No content" }, "401": { "description": "Unauthorized" }, "403": { - "description": "Forbidden" + "description": "App-scoped token required. Use a token scoped to the target app." }, "404": { - "description": "Automation run not found" + "description": "Notification not found" } }, - "summary": "Get a single invoked automation run", "x-auth": [ "publishable_key", "bearer" ] } }, - "/api/v1/automations/{automation}/invoke": { + "/api/v1/notifications/{notification}/read": { "post": { - "operationId": "post_api_v1_automations__automation_invoke", + "operationId": "post_api_v1_notifications__notification_read", "parameters": [ { - "description": "Automation ID or lookup_key", + "description": "Notification ID (ntf_...)", "in": "path", - "name": "automation", + "name": "notification", "required": true, "schema": { "type": "string" } } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "properties": { - "idempotency_key": { - "description": "Idempotency key to deduplicate invocations", - "type": "string" - }, - "payload": { - "description": "Input payload (validated against input_schema if configured)", - "type": "object" - } - }, - "type": "object" - } + "responses": { + "204": { + "description": "No content" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app." + }, + "404": { + "description": "Notification not found" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/notifications/{notification}/unarchive": { + "post": { + "operationId": "post_api_v1_notifications__notification_unarchive", + "parameters": [ + { + "description": "Notification ID (ntf_...)", + "in": "path", + "name": "notification", + "required": true, + "schema": { + "type": "string" } + } + ], + "responses": { + "204": { + "description": "No content" }, - "required": true + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app." + }, + "404": { + "description": "Notification not found" + } }, + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/orgs": { + "get": { + "operationId": "get_api_v1_orgs", + "parameters": [ + { + "description": "Search by name, slug, or domain (case-insensitive)", + "in": "query", + "name": "search", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Page number (default 1)", + "in": "query", + "name": "page", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Results per page (default 25, max 100)", + "in": "query", + "name": "page_size", + "required": false, + "schema": { + "type": "integer" + } + } + ], "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AutomationRun" + "description": "Paginated list of organizations", + "properties": { + "data": { + "description": "The organizations", + "items": { + "description": "Public org schema for authenticated endpoints.\n\nOnly exposes fields safe for any authenticated user: id, name, domain,\nand logo. Does NOT expose sandbox, status, industry, description, or\nother internal fields that the Developer.Org schema includes.\n", + "properties": { + "domain": { + "description": "Primary domain", + "type": "string" + }, + "id": { + "description": "Public ID (org_...)", + "type": "string" + }, + "name": { + "description": "Organization name", + "type": "string" + } + }, + "required": [ + "id", + "name", + "domain" + ], + "type": "object" + }, + "type": "array" + }, + "has_next": { + "description": "Whether there are more pages", + "type": "boolean" + }, + "has_prev": { + "description": "Whether there are previous pages", + "type": "boolean" + }, + "page": { + "description": "Current page", + "type": "integer" + }, + "page_size": { + "description": "Results per page", + "type": "integer" + }, + "total_entries": { + "description": "Total matching organizations", + "type": "integer" + }, + "total_pages": { + "description": "Total pages", + "type": "integer" + } + }, + "required": [ + "data" + ], + "type": "object" } } }, @@ -8640,15 +16564,9 @@ }, "401": { "description": "Unauthorized" - }, - "403": { - "description": "Forbidden" - }, - "404": { - "description": "Automation not found" - }, - "422": { - "description": "Unprocessable entity" + }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app." } }, "x-auth": [ @@ -8657,39 +16575,54 @@ ] } }, - "/api/v1/config": { + "/api/v1/solution_categories": { "get": { - "operationId": "get_api_v1_config", + "operationId": "get_api_v1_solution_categories", "parameters": [ { - "description": "Team ID (for team-owned configs)", + "description": "Page number (default 1)", "in": "query", - "name": "team", + "name": "page", "required": false, "schema": { - "type": "string" + "type": "integer" } }, { - "description": "User ID (for user-owned configs, defaults to current user)", + "description": "Results per page (default 25)", "in": "query", - "name": "user", + "name": "page_size", "required": false, "schema": { - "type": "string" + "type": "integer" } }, { - "description": "Filter by config kind", + "description": "Filter by exact SolutionCategory keys", "in": "query", - "name": "kind", + "name": "keys", "required": false, "schema": { - "type": "string" + "items": { + "type": "string" + }, + "type": "array" } }, { - "description": "Filter by exact lookup_key match", + "description": "Filter by parent category keys; empty means root", + "in": "query", + "name": "parent_keys", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + { + "description": "Filter by exact lookup_key", "in": "query", "name": "lookup_key", "required": false, @@ -8698,9 +16631,18 @@ } }, { - "description": "Filter: children of any listed parent config ID (pass one ID to fetch a single bundle's children)", + "description": "Filter by virtual_path prefix", "in": "query", - "name": "parents", + "name": "path_prefix", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Restrict to owner scopes. Members: `\"system\"` and/or `\"org\"`. Omit to include both scopes the viewer can see.", + "in": "query", + "name": "owners", "required": false, "schema": { "items": { @@ -8715,275 +16657,96 @@ "content": { "application/json": { "schema": { - "description": "List of configs", - "properties": { - "data": { - "description": "The configs", - "items": { - "description": "API schema for a config resource.", - "properties": { - "created_at": { - "description": "Creation timestamp", - "format": "date-time", - "type": "string" - }, - "current_version": { - "description": "Current version", - "properties": { - "change_description": { - "description": "Description of changes", - "type": "string" - }, - "created_at": { - "description": "Creation timestamp", - "format": "date-time", - "type": "string" - }, - "data": { - "description": "Additional structured data", - "type": "object" - }, - "id": { - "description": "Config version ID (cfv_...)", - "type": "string" - }, - "org": { - "description": "Organization", - "type": "string" - }, - "sandbox": { - "description": "Sandbox", - "type": "string" - }, - "version_number": { - "description": "Version number", - "type": "integer" - } - }, - "required": [ - "id", - "version_number" - ], - "type": "object" - }, - "id": { - "description": "Config ID (cfg_...)", - "type": "string" - }, - "is_archived": { - "description": "Whether config is archived", - "type": "boolean" - }, - "kind": { - "description": "Config kind (e.g., Agent, APITool)", - "type": "string" - }, - "lookup_key": { - "description": "Optional lookup key", - "type": "string" - }, - "mime_type": { - "description": "Content mime type", - "type": "string" - }, - "org": { - "description": "Organization", - "type": "string" - }, - "parent": { - "description": "Parent config ID (bundle children only)", - "type": "string" - }, - "raw_content": { - "description": "Raw file content (system configs only)", - "type": "string" - }, - "relative_path": { - "description": "Path within parent bundle (bundle children only)", - "type": "string" - }, - "sandbox": { - "description": "Sandbox identifier", - "type": "string" - }, - "team": { - "description": "Team", - "type": "string" - }, - "updated_at": { - "description": "Last update timestamp", - "format": "date-time", - "type": "string" - }, - "user": { - "description": "User", - "type": "string" - }, - "virtual_path": { - "description": "Unique path within the team", - "type": "string" - } - }, - "required": [ - "id", - "kind" - ], - "type": "object" - }, - "type": "array" - } - }, - "required": [ - "data" - ], - "type": "object" + "$ref": "#/components/schemas/SolutionCategoryListResponse" } } }, "description": "Successful response" }, - "400": { - "description": "Bad request - owner required" - }, "401": { "description": "Unauthorized" + }, + "403": { + "description": "Forbidden — app scope required" } }, "x-auth": [ "publishable_key", "bearer" ] - }, - "post": { - "operationId": "post_api_v1_config", - "parameters": [], - "requestBody": { - "content": { - "application/json": { - "schema": { - "properties": { - "change_description": { - "description": "Description of changes", - "type": "string" - }, - "data": { - "description": "Additional structured data stored on the version", - "type": "object" - }, - "kind": { - "description": "Config kind (e.g., Agent, APITool)", - "type": "string" - }, - "lookup_key": { - "description": "Optional lookup key", - "type": "string" - }, - "mime_type": { - "description": "Content mime type", - "type": "string" - }, - "parent": { - "description": "Parent config ID (for bundle children, e.g. files under a Skill)", - "type": "string" - }, - "raw_content": { - "description": "Raw content (YAML/JSON/etc)", - "type": "string" - }, - "relative_path": { - "description": "Path within the parent bundle (required when parent is set)", - "type": "string" - }, - "team": { - "description": "Team ID (for team-owned configs)", - "type": "string" - }, - "user": { - "description": "User ID (for user-owned configs)", - "type": "string" - }, - "virtual_path": { - "description": "Unique path within the owner scope", - "type": "string" - } - }, - "required": [ - "kind", - "raw_content", - "mime_type" - ], - "type": "object" - } + } + }, + "/api/v1/solution_tags": { + "get": { + "operationId": "get_api_v1_solution_tags", + "parameters": [ + { + "description": "Page number (default 1)", + "in": "query", + "name": "page", + "required": false, + "schema": { + "type": "integer" } }, - "required": true - }, - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Config" - } - } - }, - "description": "Successful response" + { + "description": "Results per page (default 25)", + "in": "query", + "name": "page_size", + "required": false, + "schema": { + "type": "integer" + } }, - "400": { - "description": "Bad request - owner required" + { + "description": "Filter by exact SolutionTag keys", + "in": "query", + "name": "keys", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } }, - "401": { - "description": "Unauthorized" + { + "description": "Filter by exact lookup_key", + "in": "query", + "name": "lookup_key", + "required": false, + "schema": { + "type": "string" + } }, - "422": { - "description": "Validation failed" - } - }, - "x-auth": [ - "publishable_key", - "bearer" - ] - } - }, - "/api/v1/config/encrypt_secret": { - "post": { - "operationId": "post_api_v1_config_encrypt_secret", - "parameters": [], - "requestBody": { - "content": { - "application/json": { - "schema": { - "properties": { - "plaintext": { - "description": "Secret value to encrypt", - "type": "string" - } - }, - "required": [ - "plaintext" - ], - "type": "object" - } + { + "description": "Filter by virtual_path prefix", + "in": "query", + "name": "path_prefix", + "required": false, + "schema": { + "type": "string" } }, - "required": true - }, + { + "description": "Restrict to owner scopes. Members: `\"system\"` and/or `\"org\"`. Omit to include both scopes the viewer can see.", + "in": "query", + "name": "owners", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + } + ], "responses": { "200": { "content": { "application/json": { "schema": { - "description": "Encrypted secret value", - "properties": { - "encrypted_value": { - "description": "Encrypted ciphertext for use in secret_value!", - "type": "string" - } - }, - "required": [ - "encrypted_value" - ], - "type": "object" + "$ref": "#/components/schemas/SolutionTagListResponse" } } }, @@ -8992,8 +16755,8 @@ "401": { "description": "Unauthorized" }, - "422": { - "description": "Encryption failed" + "403": { + "description": "Forbidden — app scope required" } }, "x-auth": [ @@ -9002,14 +16765,50 @@ ] } }, - "/api/v1/config/kinds": { + "/api/v1/solutions": { "get": { - "operationId": "get_api_v1_config_kinds", + "operationId": "get_api_v1_solutions", "parameters": [ { - "description": "Filter by config kind name(s)", + "description": "Page number (default 1)", "in": "query", - "name": "kind", + "name": "page", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Results per page (default 25)", + "in": "query", + "name": "page_size", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Filter by exact lookup_key", + "in": "query", + "name": "lookup_key", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Filter by virtual_path prefix", + "in": "query", + "name": "path_prefix", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Restrict to a subset of owner scopes. Members: `\"system\"` (app-level system) and/or `\"org\"` (viewer's org). Omit to include both scopes the viewer can see.", + "in": "query", + "name": "owners", "required": false, "schema": { "items": { @@ -9024,94 +16823,335 @@ "content": { "application/json": { "schema": { - "description": "List of available config kinds", - "properties": { - "data": { - "description": "The config kinds", - "items": { - "description": "Schema for a config kind in the list response.\n", + "$ref": "#/components/schemas/SolutionListResponse" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden — app scope required" + } + }, + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "post": { + "operationId": "post_api_v1_solutions", + "parameters": [], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "dry_run": { + "description": "When true, runs the same import pipeline with transient storage and rolls back the transaction after building the response. No config or file rows are persisted.", + "type": "boolean" + }, + "org": { + "description": "Organization ID", + "type": "string" + }, + "solution": { + "description": "Existing system-owned, org-less Solution config ID or lookup_key. Mutually exclusive with `solution_bundle`.", + "type": "string" + }, + "solution_bundle": { + "description": "Self-contained install bundle (Solution + skills + configs + lookup_key_suffix). Mutually exclusive with `solution`.", + "properties": { + "configs": { + "description": "Arbitrary-kind configs the solution.yaml references", + "items": { + "description": "An arbitrary-kind config row to install — used for scripts, model\nconfigs, routine templates, message schemas, and any other config\nthe AgentTemplate's `config_ref:` entries point at.\n", + "properties": { + "content": { + "description": "Raw config body", + "type": "string" + }, + "content_type": { + "description": "MIME type for the body", + "type": "string" + }, + "relative_path": { + "description": "Bundle-relative path used to derive kind and storage identity", + "type": "string" + } + }, + "required": [ + "relative_path", + "content" + ], + "type": "object" + }, + "type": "array" + }, + "lookup_key_prefix": { + "description": "Prepended (with `-` separator) to every uploaded config's lookup_key + every `path://` ref in the solution body. Caller picks the value (typical: `solutions-`); the import burns it onto the stored Solution body so `solutions/:solution/install` can re-find the namespaced library rows at rehydration time.", + "type": "string" + }, + "lookup_key_suffix": { + "description": "Appended to every uploaded config's lookup_key + every `path://` ref in the solution body. Stable per install, randomised per attempt.", + "type": "string" + }, + "setup_actions": { + "description": "Post-install checklist items for the wrapped template's eventual provisioning. Persisted into a companion `AgentSetupActionsTemplate` config keyed off the wrapped template's derived identity (`