{ "opencollection": "1.0.0", "info": { "name": "ArchAstro Platform Activity Feed Agents API", "version": "v1" }, "items": [ { "info": { "name": "Agents", "type": "folder" }, "items": [ { "info": { "name": "List agents", "type": "http" }, "http": { "method": "GET", "url": "{{baseUrl}}/api/v1/agents", "params": [ { "name": "template_config", "value": "string", "type": "query", "description": "Config ID (`cfg_...`) or `lookup_key` of an AgentTemplate. Returns only agents whose last applied template matches." }, { "name": "search", "value": "string", "type": "query", "description": "Free-text search string matched against the agent name, org, team, and owner fields." }, { "name": "page_size", "value": "1", "type": "query", "description": "Number of agents to return per page. Defaults to `25`." }, { "name": "org_id", "value": "string", "type": "query", "description": "Organization ID (`org_...`) to filter by. Returns only agents owned by this org." }, { "name": "page", "value": "1", "type": "query", "description": "Page number to retrieve, 1-indexed. Defaults to `1`." }, { "name": "user", "value": "string", "type": "query", "description": "User ID (`usr_...`) to filter by. Returns only agents owned by this user." } ] }, "docs": "Returns a paginated list of agents visible to the authenticated caller. Results are\nordered by creation time descending.\n\nUse `search` to filter by name, org, team, or owner fields. Use `user` or `org_id`\nto scope the list to a specific owner. Use `template_config` to find agents whose\nlast applied template matches a given config ID.\n\nPagination is page-based: pass `page` and `page_size` to navigate through large\nresult sets. When called under a developer app scope, only agents belonging to that" }, { "info": { "name": "Create an agent", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/api/v1/agents", "body": { "type": "json", "data": "{}" } }, "docs": "Creates a new agent. Supports two mutually exclusive provisioning modes.\n\n**Template mode** — pass `template` with the ID or `lookup_key` of an existing\nAgentTemplate config. The agent's tools, routines, skills, and installations are\nprovisioned from that template's `config_ref` entries.\n\n**Bundle mode** — pass `template_bundle` with a self-contained install payload\n(AgentTemplate body plus every skill, script, and config it references). The entire\nbundle commits in a single transaction; any fai" }, { "info": { "name": "Retrieve an agent", "type": "http" }, "http": { "method": "GET", "url": "{{baseUrl}}/api/v1/agents/:agent", "params": [ { "name": "agent", "value": "string", "type": "path", "description": "ID (`agi_...`) or `lookup_key` of the agent to retrieve." } ] }, "docs": "Returns the agent identified by ID or `lookup_key`. The authenticated caller must\nown the agent or hold sufficient permissions within its owning org or team.\n\nWhen called under a developer app scope, the agent must belong to that app. Use the\nlist endpoint to retrieve many agents at once." }, { "info": { "name": "Update an agent", "type": "http" }, "http": { "method": "PATCH", "url": "{{baseUrl}}/api/v1/agents/:agent", "params": [ { "name": "agent", "value": "string", "type": "path", "description": "ID (`agi_...`) or `lookup_key` of the agent to update." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Updates one or more fields on an existing agent. Only the fields you supply are\nchanged; omitted fields retain their current values.\n\nTo clear the agent's default model, pass `model` as an empty string. The\nauthenticated caller must own the agent or hold write permissions within its owning\norg or team. When called under a developer app scope, the caller must hold the app\nscope for the target app." }, { "info": { "name": "Delete an agent", "type": "http" }, "http": { "method": "DELETE", "url": "{{baseUrl}}/api/v1/agents/:agent", "params": [ { "name": "agent", "value": "string", "type": "path", "description": "ID (`agi_...`) or `lookup_key` of the agent to delete." } ] }, "docs": "Permanently deletes an agent and all of its associated resources. This action cannot\nbe undone.\n\nThe authenticated caller must own the agent or hold sufficient permissions within its\nowning org or team. When called under a developer app scope, the caller must hold the\napp scope for the target app." }, { "info": { "name": "List computers", "type": "http" }, "http": { "method": "GET", "url": "{{baseUrl}}/api/v1/agents/:agent/agent_computers", "params": [ { "name": "agent", "value": "string", "type": "path", "description": "Agent ID (`agt_...`). When provided, only computers belonging to this agent are returned." } ] }, "docs": "Returns all computers belonging to the authenticated app, ordered by creation\ntime descending. Pass `agent` to scope the results to a single agent's\ncomputers. When `agent` is omitted, computers for all agents in the app are\nreturned.\n\nRequires an app-scoped API key. If the specified agent does not exist or does\nnot belong to the app, the endpoint returns 404." }, { "info": { "name": "Provision a computer for an agent", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/api/v1/agents/:agent/agent_computers", "params": [ { "name": "agent", "value": "string", "type": "path", "description": "Agent ID (`agt_...`). The computer is associated with this agent." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Creates and provisions a new computer resource associated with the specified\nagent. The computer is allocated in the requested region (defaulting to `iad`)\nand its status transitions from `provisioning` to `running` once it is ready.\n\nRequires an app-scoped API key. The agent identified by `agent` must belong\nto the same app. Supplying a `lookup_key` lets you retrieve this computer\nlater without storing its ID — the key must be unique within the app." }, { "info": { "name": "List an agent's environment variables", "type": "http" }, "http": { "method": "GET", "url": "{{baseUrl}}/api/v1/agents/:agent/agent_env_vars", "params": [ { "name": "agent", "value": "string", "type": "path", "description": "Agent ID (`agt_...`). Returns environment variables belonging to this agent." } ] }, "docs": "Returns all environment variables defined for the specified agent. Variable\nvalues are always masked in the response; only the last four characters are\nvisible. To inspect a specific variable, use the retrieve endpoint.\n\nThe authenticated user must have access to the agent's parent app. Pass the\napp scope via the `app` parameter when calling with an API key that is scoped\nto a specific app. Results are returned in an unordered flat list." }, { "info": { "name": "Create an agent environment variable", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/api/v1/agents/:agent/agent_env_vars", "params": [ { "name": "agent", "value": "string", "type": "path", "description": "Agent ID (`agt_...`). The agent must belong to an app the caller can access." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Creates a new environment variable for the specified agent. The variable is\nstored securely and the plaintext `value` is never returned after creation;\nsubsequent reads return a masked representation showing only the last four\ncharacters.\n\nThe authenticated user must have access to the agent's parent app. Pass the\napp scope via the `app` parameter when calling with an API key that is scoped\nto a specific app. Each `key` must be unique within the agent; attempting to\ncreate a duplicate key return" }, { "info": { "name": "List health actions for an agent", "type": "http" }, "http": { "method": "GET", "url": "{{baseUrl}}/api/v1/agents/:agent/agent_health_actions", "params": [ { "name": "agent", "value": "string", "type": "path", "description": "Agent ID (`agt_...`) or lookup key of the agent whose health actions you want to list." }, { "name": "source", "value": "string", "type": "query", "description": "Filter results to actions from one or more lifecycle stages. Accepted values: `\"setup\"` (actions created during agent installation) and `\"health\"` (ongoing health checks). Omit to return actions from all stages." }, { "name": "status", "value": "string", "type": "query", "description": "Filter results to actions in one or more statuses. Accepted values: `\"pending\"`, `\"completed\"`, `\"skipped\"`, and `\"degraded\"`. Omit to return actions in all statuses." }, { "name": "kind", "value": "string", "type": "query", "description": "Filter results to actions of one or more kinds. Accepted values: `\"env_var\"` (a required secret or config value), `\"install\"` (an OAuth or integration install step), and `\"custom\"` (a platform-defined check). Omit to return all kinds." } ] }, "docs": "Returns all health actions associated with a given agent. Health actions\nrepresent required or recommended steps — such as setting environment\nvariables, completing OAuth installations, or running custom verifiers —\nthat an agent needs to reach a healthy state.\n\nResults are not paginated; the full list for the agent is returned. Use\nthe `source`, `status`, and `kind` filters to narrow results to the\nsubset your UI or workflow needs. Multiple values for the same filter\nare treated as OR (e.g. pas" }, { "info": { "name": "List installations for an agent", "type": "http" }, "http": { "method": "GET", "url": "{{baseUrl}}/api/v1/agents/:agent/agent_installations", "params": [ { "name": "agent", "value": "string", "type": "path", "description": "Agent ID (`agt_...`) whose installations you want to retrieve." } ] }, "docs": "Returns all installations belonging to the specified agent, across all kinds and\nstates. Use this endpoint to inspect which external services and enablement channels\nan agent is connected to.\n\nResults are scoped to the authenticated app and are returned in an unordered array.\nTo list installations across all agents in an app, use the top-level List\nInstallations endpoint instead. The caller must have app scope for the app that\nowns the agent." }, { "info": { "name": "Create an installation", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/api/v1/agents/:agent/agent_installations", "params": [ { "name": "agent", "value": "string", "type": "path", "description": "Agent ID (`agt_...`) that will own this installation." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Creates a new installation for an agent, connecting it to an external service or\nenablement channel via the specified `kind`. The installation begins in a pending\nstate unless an integration is supplied at creation time, in which case it is\nactivated immediately.\n\nSupply `shared_integration` to bind an existing org- or app-level integration, or\nsupply `integration` to create a new integration inline and activate the installation\nin a single request. Supplying both fields returns 422.\n\nUse `looku" }, { "info": { "name": "List available installation kinds", "type": "http" }, "http": { "method": "GET", "url": "{{baseUrl}}/api/v1/agents/:agent/agent_installations/kinds", "params": [ { "name": "agent", "value": "string", "type": "path", "description": "Agent ID (`agt_...`). Accepted for forward compatibility but currently does not filter the response." } ] }, "docs": "Returns the full catalogue of installation kinds supported by the platform. Use\nthe returned `kind` values when calling the Create Installation endpoint.\n\nThe list is platform-wide and does not vary by agent. The `agent` parameter is\naccepted for future per-agent filtering but is currently unused. The caller must\nhave app scope to call this endpoint." }, { "info": { "name": "Create a routine", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/api/v1/agents/:agent/agent_routines", "params": [ { "name": "agent", "value": "string", "type": "path", "description": "Agent ID (`agt_...`) that this routine will be attached to." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Creates a new routine and attaches it to the specified agent. Routines define\nhow an agent responds to events or a cron schedule; the `handler_type` controls\nwhich execution model is used.\n\nThe routine is created in `\"draft\"` status by default. To start processing\nevents immediately, either pass `status: \"active\"` or call the activate\nendpoint after creation. Scheduled routines must run no more frequently than\nonce per hour. Requires app scope." }, { "info": { "name": "List agent tools", "type": "http" }, "http": { "method": "GET", "url": "{{baseUrl}}/api/v1/agents/:agent/agent_tools", "params": [ { "name": "kind", "value": "string", "type": "query", "description": "Filter by tool kind. One of `\"builtin\"` or `\"custom\"`. Omit to return tools of all kinds." }, { "name": "agent", "value": "string", "type": "path", "description": "Filter results to tools belonging to this agent (`agt_...`). Omit to return tools across all agents in the app." } ] }, "docs": "Returns all tools for the authenticated app, optionally filtered by agent\nor tool kind. Both explicitly created tools and tools derived from connected\nintegrations (installation-sourced tools) are included in the response.\n\nInstallation-sourced tools appear with `source: \"installation\"` and\n`status: \"active\"`. They are synthesized at request time from connected\nintegrations and do not have a persistent tool ID of the `atl_...` form;\ntheir `id` is a composite of the installation ID and server too" }, { "info": { "name": "Create an agent tool", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/api/v1/agents/:agent/agent_tools", "params": [ { "name": "agent", "value": "string", "type": "path", "description": "Agent ID (`agt_...`) to attach the tool to." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Creates a new tool and attaches it to the specified agent. Tools can be\neither `\"builtin\"` (a platform-provided capability identified by\n`builtin_tool_key`) or `\"custom\"` (a caller-defined tool with its own name,\ndescription, parameter schema, and handler).\n\nNew tools are created in `\"draft\"` status by default unless `status:\n\"active\"` is explicitly supplied. Draft tools are not exposed to the LLM\nduring agent runs; call the activate endpoint to promote them.\n\nFor built-in tools that support mul" }, { "info": { "name": "List working memory entries for an agent", "type": "http" }, "http": { "method": "GET", "url": "{{baseUrl}}/api/v1/agents/:agent/agent_working_memory", "params": [ { "name": "agent", "value": "string", "type": "path", "description": "Agent ID (`agt_...`) whose working memory entries to retrieve." }, { "name": "page_size", "value": "1", "type": "query", "description": "Number of entries to return per page. Defaults to 25." }, { "name": "page", "value": "1", "type": "query", "description": "Page number to retrieve, starting at 1. Defaults to 1." }, { "name": "search", "value": "string", "type": "query", "description": "Substring filter applied to entry keys (case-insensitive). Omit to return all keys." } ] }, "docs": "Returns a paginated list of working memory entries belonging to the specified\nagent. Entries are key-value pairs the agent stores for context between\ninteractions. Results are ordered by creation time descending (newest first)\nand can be filtered with a substring search against the key name.\n\nRequires an app-scoped API key. The authenticated caller must have access to\nthe app the agent belongs to. Returns 403 if the key is not app-scoped, and\n404 if the agent does not exist within the accessible" }, { "info": { "name": "Export an agent as an AgentTemplate", "type": "http" }, "http": { "method": "GET", "url": "{{baseUrl}}/api/v1/agents/:agent/export", "params": [ { "name": "agent", "value": "string", "type": "path", "description": "ID (`agi_...`) or `lookup_key` of the agent to export." }, { "name": "remove_identity", "value": "true", "type": "query", "description": "When `true`, strips instance-unique identity fields (`email`, `phone_number`) from the exported template so it can be reused as a generic blueprint." } ] }, "docs": "Reconstructs an AgentTemplate config from a deployed agent and all of its\nsub-resources (tools, routines, skills, installations). Returns the template\ndefinition together with every dependent config file (scripts, workflows, skills,\nschemas) and their raw content, producing a fully self-contained export bundle.\n\nUse this endpoint to snapshot an agent's current configuration for backup,\nmigration, or to seed a new Solution template. Pass `remove_identity: true` to\nstrip instance-specific fields (" }, { "info": { "name": "Retrieve an agent's health profile", "type": "http" }, "http": { "method": "GET", "url": "{{baseUrl}}/api/v1/agents/:agent/health", "params": [ { "name": "agent", "value": "string", "type": "path", "description": "ID (`agi_...`) or `lookup_key` of the agent to evaluate." } ] }, "docs": "Returns an aggregate health profile for the specified agent, including an overall\nstatus, a numeric health score, recent activity metrics, and a list of recommended\nremediation actions.\n\nThe health check is computed on demand at request time. The `checked_at` timestamp\nin the response reflects when the evaluation ran. Use this endpoint to surface\ndiagnostics about tool availability, model configuration, and runtime activity in\ndashboards or monitoring workflows.\n\nThe authenticated caller must ow" }, { "info": { "name": "List schedules for an agent", "type": "http" }, "http": { "method": "GET", "url": "{{baseUrl}}/api/v1/agents/:agent/schedules", "params": [ { "name": "agent", "value": "string", "type": "path", "description": "Agent ID (`agi_...`). The agent whose schedules you want to retrieve." }, { "name": "status", "value": "string", "type": "query", "description": "Filter results by schedule status. One of `\"active\"`, `\"paused\"`, `\"completed\"`, `\"cancelled\"`, or `\"expired\"`. Omit to return schedules in all statuses." } ] }, "docs": "Returns all schedules belonging to the specified agent in any status. Use the\n`status` parameter to narrow results to a single lifecycle state.\n\nRequires an app-scoped API key. The agent must belong to the app identified\nby the key." }, { "info": { "name": "Retrieve a schedule", "type": "http" }, "http": { "method": "GET", "url": "{{baseUrl}}/api/v1/agents/:agent/schedules/:schedule", "params": [ { "name": "agent", "value": "string", "type": "path", "description": "Agent ID (`agi_...`). The agent that owns the schedule." }, { "name": "schedule", "value": "string", "type": "path", "description": "Schedule ID (`asc_...`). The schedule to retrieve." } ] }, "docs": "Returns a single schedule belonging to the specified agent. Use this endpoint\nto fetch the current state, next run time, and configuration of an individual\nschedule.\n\nRequires an app-scoped API key. Both the agent and the schedule must belong\nto the app identified by the key. Returns 404 if the schedule does not exist\nor belongs to a different agent." }, { "info": { "name": "Search an agent's knowledge base", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/api/v1/agents/:agent/search", "params": [ { "name": "agent", "value": "string", "type": "path", "description": "ID (`agi_...`) or `lookup_key` of the agent whose knowledge base to search." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Performs a semantic search over an agent's knowledge base and returns a ranked,\n`kind`-discriminated list of matching items.\n\nTwo item kinds may appear in `data`:\n\n- `\"chunk\"` — chunk-level results from the agent's context store. Present for all agents.\n- `\"document\"` — document-level results. Present only when the agent has an active\n `archastro/knowledge` installation.\n\nResults from both kinds are scored with Reciprocal Rank Fusion (RRF), normalized to\nbe comparable across kinds, then merged " }, { "info": { "name": "Create a thread for an agent", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/api/v1/agents/:agent/threads", "params": [ { "name": "agent", "value": "string", "type": "path", "description": "Agent ID (`agt_...`). The thread will be owned by this agent." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Creates a new thread owned by the specified agent. The thread is scoped to the\nagent's identity and is immediately available for messaging.\n\nThe authenticated caller must have access to the agent's parent app. If your\nAPI key is scoped to a specific app, pass that app's ID via the `app` parameter.\nAttempting to create a thread for an agent you cannot access returns 404.\n\nBy default the platform may send an automatic welcome message into the new\nthread. Pass `skip_welcome_message: true` to suppre" }, { "info": { "name": "Upgrade an agent from an AgentTemplate", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/api/v1/agents/:agent/upgrade", "params": [ { "name": "agent", "value": "string", "type": "path", "description": "ID (`agi_...`) or `lookup_key` of the agent to upgrade." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Upgrades an existing agent by reconciling it against an AgentTemplate from a\nSolution. Supports two modes:\n\n- `\"reapply\"` (default) — re-applies the agent's currently tracked template,\n picking up any changes the template author has made since the last apply.\n- `\"replace\"` — moves the agent to a different template. `template` is required\n in this mode.\n\nSet `dry_run: true` to compute and return the full upgrade diff (adds, updates,\nremoves, noops) without writing any changes. The response incl" } ] } ], "bundled": true }