{"components":{"schemas":{"Error":{"properties":{"error":{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"type":"object"}},"required":["error"],"type":"object"}},"securitySchemes":{"apiToken":{"description":"A personal AgentX API token, sent as `Authorization: Bearer \u003ctoken\u003e`.","scheme":"bearer","type":"http"}}},"info":{"description":"A JSON API for creating and steering AgentX agents from your own scripts and tools. Authenticate with a personal API token created in your account settings. Every call needs exactly one scope, and no scope is granted by default.","title":"AgentX Web API","version":"v1"},"openapi":"3.1.0","paths":{"/api/v1":{"get":{"description":"Lists every endpoint in this API with the scope each one needs, and links to the OpenAPI description. No authentication required.","operationId":"getAPIIndex","responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"api":{"type":"string"},"openapi":{"type":"string"},"routes":{"items":{"additionalProperties":false,"properties":{"method":{"type":"string"},"path":{"type":"string"},"scope":{"type":"string"},"summary":{"type":"string"}},"required":["method","path"],"type":"object"},"type":["null","array"]},"version":{"type":"string"}},"required":["api","version","openapi","routes"],"type":"object"}}},"description":"Success."}},"security":[],"summary":"Index of this API"}},"/api/v1/agents":{"get":{"description":"Lists every agent across all daemons in your account. If a daemon could not be reached, it is named in `unreachable` — treat the result as partial whenever that list is non-empty.","operationId":"listAgents","parameters":[{"description":"Set to `true` to also include disabled agents, and agents whose backend is unavailable.","in":"query","name":"include_all","required":false,"schema":{"enum":["true"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"agents":{"items":{"additionalProperties":false,"properties":{"account_removable":{"type":"boolean"},"activity":{"type":"string"},"agent_id":{"type":"string"},"authority_writable":{"type":"boolean"},"avatar_artifact_id":{"type":"string"},"avatar_color":{"type":"string"},"backend":{"type":"string"},"bubble_id":{"type":"string"},"capabilities":{"items":{"type":"string"},"type":["null","array"]},"compat":{"type":"string"},"created_at":{"type":"string"},"daemon_version":{"type":"string"},"description":{"type":"string"},"exit_error":{"type":"string"},"hook_injects_user_prompt_submit":{"type":"boolean"},"identity":{"type":"string"},"kind":{"type":"string"},"locality":{"type":"string"},"location":{"type":"string"},"manager":{"type":"boolean"},"model":{"type":"string"},"name":{"type":"string"},"owner_display_name":{"type":"string"},"owner_user_id":{"type":"string"},"principal_configure_allowed":{"type":"boolean"},"principal_delete_allowed":{"type":"boolean"},"route_bridge_id":{"type":"string"},"route_daemon_id":{"type":"string"},"run_count":{"maximum":2147483647,"minimum":-2147483648,"type":"integer"},"session_count":{"maximum":2147483647,"minimum":-2147483648,"type":"integer"},"session_id":{"type":"string"},"state":{"type":"string"},"type":{"type":"string"},"work_dir":{"type":"string"},"workspace_not_removable_reason":{"type":"string"},"workspace_removable":{"type":"boolean"}},"type":"object"},"type":["null","array"]},"backends":{"items":{"type":"string"},"type":["null","array"]},"next_cursor":{"type":"string"},"total":{"maximum":2147483647,"minimum":-2147483648,"type":"integer"},"unreachable":{"items":{"additionalProperties":false,"properties":{"agent_id":{"type":"string"},"bridge_id":{"type":"string"},"class":{"type":"string"},"code":{"type":"string"},"daemon_id":{"type":"string"},"name":{"type":"string"},"reason":{"type":"string"}},"type":"object"},"type":["null","array"]}},"type":"object"}}},"description":"Success."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No valid API token was supplied."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Your API token is valid but does not carry the `agentx:agent.read` scope."}},"security":[{"apiToken":["agentx:agent.read"]}],"summary":"List your agents"},"post":{"description":"Creates an agent on one of your daemons — the machine that runs it. `daemon`, `name` and `backend` are required.","operationId":"createAgent","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"agent_id":{"type":"string"},"approval":{"type":"string"},"authority":{"items":{"additionalProperties":false,"properties":{"class":{"type":"string"},"scope":{"type":"string"}},"type":"object"},"type":["null","array"]},"auto_compact_threshold_tokens":{"maximum":2147483647,"minimum":-2147483648,"type":"integer"},"backend":{"type":"string"},"boot_resume_policy":{"type":"string"},"create_run_as":{"type":"boolean"},"daemon":{"type":"string"},"extra_system_prompt":{"type":"string"},"idle_reap_after_seconds":{"maximum":2147483647,"minimum":-2147483648,"type":"integer"},"idle_reap_enabled":{"type":"boolean"},"manager":{"type":["null","boolean"]},"max_sessions":{"maximum":2147483647,"minimum":-2147483648,"type":"integer"},"model":{"type":"string"},"name":{"type":"string"},"network":{"type":"string"},"run_as":{"type":"string"},"sandbox":{"type":"string"},"system_prompt":{"type":"string"},"work_dir":{"type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"agent":{"additionalProperties":false,"properties":{"account_removable":{"type":"boolean"},"activity":{"type":"string"},"agent_id":{"type":"string"},"authority_writable":{"type":"boolean"},"avatar_artifact_id":{"type":"string"},"avatar_color":{"type":"string"},"backend":{"type":"string"},"bubble_id":{"type":"string"},"capabilities":{"items":{"type":"string"},"type":["null","array"]},"compat":{"type":"string"},"created_at":{"type":"string"},"daemon_version":{"type":"string"},"description":{"type":"string"},"exit_error":{"type":"string"},"hook_injects_user_prompt_submit":{"type":"boolean"},"identity":{"type":"string"},"kind":{"type":"string"},"locality":{"type":"string"},"location":{"type":"string"},"manager":{"type":"boolean"},"model":{"type":"string"},"name":{"type":"string"},"owner_display_name":{"type":"string"},"owner_user_id":{"type":"string"},"principal_configure_allowed":{"type":"boolean"},"principal_delete_allowed":{"type":"boolean"},"route_bridge_id":{"type":"string"},"route_daemon_id":{"type":"string"},"run_count":{"maximum":2147483647,"minimum":-2147483648,"type":"integer"},"session_count":{"maximum":2147483647,"minimum":-2147483648,"type":"integer"},"session_id":{"type":"string"},"state":{"type":"string"},"type":{"type":"string"},"work_dir":{"type":"string"},"workspace_not_removable_reason":{"type":"string"},"workspace_removable":{"type":"boolean"}},"type":"object"}},"required":["agent"],"type":"object"}}},"description":"Success."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No valid API token was supplied."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Your API token is valid but does not carry the `agentx:agent.create` scope."}},"security":[{"apiToken":["agentx:agent.create"]}],"summary":"Create an agent"}},"/api/v1/agents/{agent}/upload":{"post":{"description":"Streams a file into an agent's workspace. Authenticate with a bearer token that carries `agentx:agent.upload`. Session cookies are not accepted. The query requires `bubble` (name or id). The body is multipart: a `size` part (declared byte count) first, then a `file` part. There is no size cap at this door; the agent's machine refuses with a retryable code when it is busy and a distinct non-retryable code when the file cannot fit. The response is `{bytes, status}`; the landed path stays on the daemon.","operationId":"uploadAgentFile","parameters":[{"description":"Required path parameter.","in":"path","name":"agent","required":true,"schema":{"type":"string"}},{"description":"Bubble name or id the file is uploaded to. Required. A name that matches more than one bubble is refused; send the id instead.","in":"query","name":"bubble","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"properties":{"file":{"description":"The file contents. Second part.","format":"binary","type":"string"},"size":{"description":"Declared byte count. First part. A non-negative decimal with no size cap on the payload that follows.","type":"string"}},"required":["size","file"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"bytes":{"type":"integer"},"status":{"type":"string"}},"required":["bytes","status"],"type":"object"}}},"description":"Success."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No valid API token was supplied."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Your API token is valid but does not carry the `agentx:agent.upload` scope."}},"security":[{"apiToken":["agentx:agent.upload"]}],"summary":"Upload a file to an agent"}},"/api/v1/bubbles":{"get":{"description":"Lists the bubbles in your account. If a daemon could not be reached, it is named in `unreachable`.","operationId":"listBubbles","parameters":[{"description":"Maximum number of bubbles to return. Must not be negative; zero returns all of them.","in":"query","name":"limit","required":false,"schema":{"minimum":0,"type":"integer"}},{"description":"Pagination cursor. Pass the `next_cursor` value from a previous response.","in":"query","name":"cursor","required":false,"schema":{"type":"string"}},{"description":"Only return bubbles whose name matches this text.","in":"query","name":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"bubbles":{"items":{"additionalProperties":false,"properties":{"archived":{"type":"boolean"},"bubble_id":{"type":"string"},"closed":{"type":"boolean"},"latest_activity_at":{"type":"string"},"lead_agent_id":{"type":"string"},"member_count":{"maximum":2147483647,"minimum":-2147483648,"type":"integer"},"members":{"items":{"additionalProperties":false,"properties":{"agent":{"type":"string"},"agent_id":{"type":"string"},"backend":{"type":"string"},"compat":{"type":"string"},"home_daemon_id":{"type":"string"},"identity":{"type":"string"},"joined_at":{"type":"string"},"session_id":{"type":"string"},"type":{"type":"string"}},"type":"object"},"type":["null","array"]},"name":{"type":"string"},"node_class":{"type":"string"},"owner_user_id":{"type":"string"},"route_bridge_id":{"type":"string"},"route_daemon_id":{"type":"string"},"session_count":{"maximum":2147483647,"minimum":-2147483648,"type":"integer"},"updated":{"type":"string"}},"type":"object"},"type":["null","array"]},"next_cursor":{"type":"string"},"total":{"maximum":2147483647,"minimum":-2147483648,"type":"integer"},"unreachable":{"items":{"additionalProperties":false,"properties":{"agent_id":{"type":"string"},"bridge_id":{"type":"string"},"class":{"type":"string"},"code":{"type":"string"},"daemon_id":{"type":"string"},"name":{"type":"string"},"reason":{"type":"string"}},"type":"object"},"type":["null","array"]}},"type":"object"}}},"description":"Success."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No valid API token was supplied."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Your API token is valid but does not carry the `agentx:bubble.read` scope."}},"security":[{"apiToken":["agentx:bubble.read"]}],"summary":"List your bubbles"},"post":{"description":"Creates a bubble — a shared conversation between you and one or more agents — anchored to the agent you name. `name` and `anchor_agent` are required.","operationId":"createBubble","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"agent_id":{"type":"string"},"anchor_agent":{"type":"string"},"bubble_id":{"type":"string"},"name":{"type":"string"},"route_bridge_id":{"type":"string"},"route_daemon_id":{"type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"bubble":{"additionalProperties":false,"properties":{"archived":{"type":"boolean"},"bubble_id":{"type":"string"},"closed":{"type":"boolean"},"latest_activity_at":{"type":"string"},"lead_agent_id":{"type":"string"},"member_count":{"maximum":2147483647,"minimum":-2147483648,"type":"integer"},"members":{"items":{"additionalProperties":false,"properties":{"agent":{"type":"string"},"agent_id":{"type":"string"},"backend":{"type":"string"},"compat":{"type":"string"},"home_daemon_id":{"type":"string"},"identity":{"type":"string"},"joined_at":{"type":"string"},"session_id":{"type":"string"},"type":{"type":"string"}},"type":"object"},"type":["null","array"]},"name":{"type":"string"},"node_class":{"type":"string"},"owner_user_id":{"type":"string"},"route_bridge_id":{"type":"string"},"route_daemon_id":{"type":"string"},"session_count":{"maximum":2147483647,"minimum":-2147483648,"type":"integer"},"updated":{"type":"string"}},"type":"object"}},"required":["bubble"],"type":"object"}}},"description":"Success."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No valid API token was supplied."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Your API token is valid but does not carry the `agentx:bubble.create` scope."}},"security":[{"apiToken":["agentx:bubble.create"]}],"summary":"Create a bubble"}},"/api/v1/bubbles/{bubbleID}":{"delete":{"description":"Deletes a bubble for every user of your account. Only the bubble's owner and account admins may delete it; anyone else is refused with 403. A bubble that is already deleted is refused with 409. A delete can't be undone.","operationId":"deleteBubble","parameters":[{"description":"Required path parameter.","in":"path","name":"bubbleID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"bubble":{"additionalProperties":false,"properties":{"archived":{"type":"boolean"},"bubble_id":{"type":"string"},"closed":{"type":"boolean"},"latest_activity_at":{"type":"string"},"lead_agent_id":{"type":"string"},"member_count":{"maximum":2147483647,"minimum":-2147483648,"type":"integer"},"members":{"items":{"additionalProperties":false,"properties":{"agent":{"type":"string"},"agent_id":{"type":"string"},"backend":{"type":"string"},"compat":{"type":"string"},"home_daemon_id":{"type":"string"},"identity":{"type":"string"},"joined_at":{"type":"string"},"session_id":{"type":"string"},"type":{"type":"string"}},"type":"object"},"type":["null","array"]},"name":{"type":"string"},"node_class":{"type":"string"},"owner_user_id":{"type":"string"},"route_bridge_id":{"type":"string"},"route_daemon_id":{"type":"string"},"session_count":{"maximum":2147483647,"minimum":-2147483648,"type":"integer"},"updated":{"type":"string"}},"type":"object"}},"required":["bubble"],"type":"object"}}},"description":"Success."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No valid API token was supplied."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Your API token is valid but does not carry the `agentx:bubble.delete` scope."}},"security":[{"apiToken":["agentx:bubble.delete"]}],"summary":"Delete a bubble"}},"/api/v1/daemons/claim":{"post":{"description":"Connects a daemon to your account using the claim code the daemon prints when it starts. `claim_code` is required.","operationId":"claimDaemon","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"claim_code":{"type":"string"}},"required":["claim_code"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"connection":{"additionalProperties":false,"properties":{"allow_account_provisioning":{"type":"boolean"},"backends":{"items":{"additionalProperties":false,"properties":{"id":{"type":"string"},"label":{"type":"string"}},"required":["id","label"],"type":"object"},"type":["null","array"]},"bridge_id":{"type":"string"},"capabilities":{"items":{"type":"string"},"type":["null","array"]},"claimed_at":{"type":"string"},"claimed_by_user_id":{"type":"string"},"compat":{"type":"string"},"conferrable_grants":{"items":{"additionalProperties":false,"properties":{"class":{"type":"string"},"scope":{"type":"string"}},"type":"object"},"type":["null","array"]},"create_allowed":{"type":"boolean"},"created_at":{"type":"string"},"daemon_id":{"type":"string"},"hostname":{"type":"string"},"id":{"type":"string"},"install_id":{"type":"string"},"last_seen_at":{"type":"string"},"local_callback_url":{"type":"string"},"manager_user_ids":{"items":{"type":"string"},"type":["null","array"]},"min_version":{"type":"string"},"os":{"type":"string"},"public_key_fingerprint":{"type":"string"},"required_capability":{"type":"string"},"revoked_at":{"type":"string"},"router_token_id":{"type":"string"},"run_as_users":{"items":{"type":"string"},"type":["null","array"]},"settings_allowed":{"type":"boolean"},"status":{"type":"string"},"surfaces":{"additionalProperties":false,"properties":{"web":{"additionalProperties":false,"properties":{"enabled":{"type":"boolean"},"listen_addr":{"type":"string"},"public_url":{"type":"string"},"public_url_override":{"type":"string"}},"required":["enabled"],"type":"object"}},"type":"object"},"tenant_id":{"type":"string"},"updated_at":{"type":"string"},"version":{"type":"string"}},"required":["id","status","install_id","public_key_fingerprint"],"type":"object"}},"required":["connection"],"type":"object"}}},"description":"Success."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No valid API token was supplied."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Your API token is valid but does not carry the `agentx:daemon.claim` scope."}},"security":[{"apiToken":["agentx:daemon.claim"]}],"summary":"Claim a daemon"}},"/api/v1/messages":{"post":{"description":"Sends a message to a single recipient, named explicitly by `agent`, `address` or `session_id`. Set `bubble` when the recipient is addressed inside a bubble — either its `bubble_id` or its name, as returned by GET /api/v1/bubbles. A name that matches more than one bubble is refused; send the id instead.","operationId":"sendMessage","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"address":{"type":"string"},"agent":{"type":"string"},"bubble":{"type":"string"},"kind":{"type":"string"},"message":{"type":"string"},"name":{"type":"string"},"session_id":{"type":"string"},"start":{"type":"boolean"},"timeout":{"maximum":2147483647,"minimum":-2147483648,"type":"integer"},"to":{"type":"string"}},"required":["message"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"error":{"type":"string"},"message_id":{"type":"string"},"next":{"type":"string"},"route_bridge_id":{"type":"string"},"route_daemon_id":{"type":"string"},"spawned_identity":{"type":"string"},"status":{"type":"string"},"target_session_id":{"type":"string"},"warning":{"type":"string"}},"type":"object"}}},"description":"Success."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No valid API token was supplied."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Your API token is valid but does not carry the `agentx:bubble.send` scope."}},"security":[{"apiToken":["agentx:bubble.send"]}],"summary":"Send a message to an agent"}},"/api/v1/openapi.json":{"get":{"description":"The full OpenAPI 3.1 description of this API. No authentication required.","operationId":"getOpenAPIDocument","responses":{"200":{"description":"Success."}},"security":[],"summary":"OpenAPI description of this API"}},"/api/v1/output":{"post":{"description":"Reads what an agent has been saying. `agent` or `to` names it; `session_id` reads one session instead. `lines`, or `tail` when `lines` is absent, is how far back to read. `format` empty is the conversation; `screen` is the raw terminal. `bubble` is required when the agent is named.","operationId":"checkAgentOutput","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"agent":{"type":"string"},"bubble":{"type":"string"},"format":{"type":"string"},"lines":{"maximum":2147483647,"minimum":-2147483648,"type":["null","integer"]},"session_id":{"type":"string"},"tail":{"maximum":2147483647,"minimum":-2147483648,"type":["null","integer"]},"to":{"type":"string"},"verbose":{"type":"boolean"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"bytes":{"type":"integer"},"lines":{"maximum":2147483647,"minimum":-2147483648,"type":"integer"},"output":{"type":"string"},"output_format":{"type":"string"},"source":{"type":"string"},"state":{"type":"string"},"truncated":{"type":"boolean"}},"type":"object"}}},"description":"Success."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No valid API token was supplied."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Your API token is valid but does not carry the `agentx:agent.read` scope."}},"security":[{"apiToken":["agentx:agent.read"]}],"summary":"Read an agent's output"}}},"servers":[{"url":"https://www.agentxhq.com"}]}