{ "openapi": "3.1.0", "info": { "title": "Aetherfy Agent Control Plane API", "version": "1.0.0", "summary": "Deploy, run, schedule and manage Aetherfy agents.", "description": "The Aetherfy agent control plane. This is a SEPARATE API from the Aetherfy vector data plane described in openapi.json: different origin, a separate per-minute request budget, and a different error envelope ({\"detail\": ...} rather than {\"error\": ...}). The auth codes are shared with the vector plane as of 2026-08-20 — INVALID_API_KEY here is INVALID_API_KEY there — so a client switching on the literal code no longer has to branch per host; it still has to read detail.code here and error.code there. Every path taking {agent} accepts either the agent UUID or its name.", "contact": { "name": "Aetherfy support", "email": "support@aetherfy.com", "url": "https://aetherfy.com" } }, "servers": [ { "url": "https://agents.aetherfy.com", "description": "Aetherfy agent control plane" } ], "security": [ { "bearerAuth": [] } ], "components": { "schemas": { "Error": { "type": "object", "required": [ "detail" ], "description": "The control-plane error envelope. NOTE the shape differs from the vector API, which uses {\"error\": {...}}. `detail` is an object carrying a stable `code` on every routed error, INCLUDING a request-schema validation failure: the control plane wraps the framework's per-field errors rather than passing them through, so a 422 is code VALIDATION_ERROR with the field errors in `violations`. The one shape not modelled here is an unrouted path, which is not an operation in this document: it never reaches the error handling and gets the framework default {\"detail\": \"Not Found\"}, where detail is a plain string.", "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable, append-only. Switch on this." }, "message": { "type": "string" }, "violations": { "type": "array", "description": "Present on VALIDATION_ERROR (422). The framework's per-field errors, verbatim.", "items": { "type": "object", "properties": { "loc": { "type": "array", "items": {} }, "msg": { "type": "string" }, "type": { "type": "string" } } } } }, "additionalProperties": true } } }, "Agent": { "type": "object", "required": [ "id", "user_id", "name", "description", "agent_type", "tier", "runtime", "memory_mb", "idle_timeout_minutes", "keep_alive", "serves_websocket", "status", "database_collection", "model_name", "entrypoint", "spawn_enabled", "allowed_workers", "parent_agent_id", "workspace_name", "deployed", "url", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 56 }, "description": { "type": "string", "nullable": true }, "agent_type": { "type": "string", "enum": [ "service", "job" ] }, "tier": { "type": "string", "enum": [ "free", "starter", "performance", "enterprise" ] }, "runtime": { "type": "string", "enum": [ "python3.11", "python3.12", "python3.13", "node20", "node22", "node20-ts", "node22-ts", "bun", "dockerfile" ] }, "memory_mb": { "type": "integer" }, "idle_timeout_minutes": { "type": "integer" }, "keep_alive": { "type": "boolean", "description": "Always-on. Counts as usage." }, "serves_websocket": { "type": "boolean", "description": "Whether the deployed app serves WebSocket routes, detected from the running agent rather than declared by you. Read-only. `null` means Aetherfy has no usable answer yet — it is NOT the same as `false`, which means the agent answered and serves none. Every agent is reachable over HTTP; this says what it additionally accepts.", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "building", "deploying", "running", "failed", "stopped", "paused", "usage_paused", "suspended", "archived", "deleting", "deleted" ] }, "database_collection": { "type": "string", "nullable": true }, "model_name": { "type": "string", "nullable": true }, "entrypoint": { "type": "string", "nullable": true }, "spawn_enabled": { "type": "boolean" }, "allowed_workers": { "type": "array", "items": { "type": "string" } }, "parent_agent_id": { "type": "string", "format": "uuid", "description": "Set when this agent was spawned by another.", "nullable": true }, "workspace_name": { "type": "string", "nullable": true }, "deployed": { "type": "boolean", "description": "Whether the agent currently holds a running app. This is the deployed test — it is what the plan's agent quota counts, and what archive, pause and run-now are offered on. True for a `job` agent, which deploys and serves nothing." }, "url": { "type": "string", "description": "Where to send requests to this agent. A different question from `deployed`: null for a `job`, which runs once and exits behind no HTTP server, and null for any agent that is not deployed. Stable across renames — the address is fixed at the first deploy and never moves.", "nullable": true }, "regions": { "type": "array", "items": { "type": "string" } }, "pending_regions": { "type": "array", "items": { "type": "string" } }, "regions_total": { "type": "integer" }, "regions_ready": { "type": "integer" }, "is_degraded": { "type": "boolean" }, "degraded_reason": { "type": "string", "nullable": true }, "failure_code": { "type": "string", "description": "Why the agent is FAILED, when nothing else on the record can say. Today the only value is `app_lost_on_provider`: the compute plane no longer has an app for this agent. Your code, secrets and address are kept and a redeploy brings it back. Null means no reason was recorded, which is NOT a claim that the agent is healthy — a FAILED agent whose build did not compile has null here and explains itself through its deployment error instead. Match on this, not on failure_message.", "nullable": true }, "failure_message": { "type": "string", "description": "The same reason as prose, for display. Wording may change between releases and is null for a code this platform version does not recognise — branch on failure_code.", "nullable": true }, "cron_schedule": { "type": "string", "description": "The scheduled task, as a 5-field cron expression evaluated in UTC.", "nullable": true }, "cron_next_run_at": { "type": "string", "format": "date-time", "nullable": true }, "cron_paused": { "type": "boolean" }, "cron_last_run_at": { "type": "string", "format": "date-time", "nullable": true }, "cron_last_status": { "type": "string", "nullable": true }, "cron_last_reason": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AgentCreate": { "type": "object", "required": [ "name" ], "description": "Creating an agent does not deploy it, and does NOT check the plan agent-count quota — that is enforced at deploy time. Per-agent caps (memory, always-on, regions) are checked here.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 56, "description": "Lowercase letters, digits and hyphens; no leading, trailing or doubled hyphen; not a reserved word. The name becomes the first label of the agent's URL, and 56 is the 63-character DNS limit minus the suffix Aetherfy appends." }, "description": { "type": "string", "nullable": true }, "agent_type": { "type": "string", "enum": [ "service", "job" ], "default": "service" }, "tier": { "type": "string", "enum": [ "free", "starter", "performance", "enterprise" ], "default": "free" }, "runtime": { "type": "string", "enum": [ "python3.11", "python3.12", "python3.13", "node20", "node22", "node20-ts", "node22-ts", "bun", "dockerfile" ], "default": "python3.11" }, "memory_mb": { "type": "integer", "default": 256 }, "idle_timeout_minutes": { "type": "integer", "default": 5 }, "keep_alive": { "type": "boolean", "default": false }, "database_collection": { "type": "string", "nullable": true }, "model_name": { "type": "string", "nullable": true }, "entrypoint": { "type": "string", "description": "e.g. main.py, index.js", "nullable": true }, "spawn_enabled": { "type": "boolean", "default": false }, "allowed_workers": { "type": "array", "items": { "type": "string" } }, "workspace_name": { "type": "string", "nullable": true } } }, "AgentUpdate": { "type": "object", "description": "Every field optional; omitted fields are untouched. workspace_name: null moves the agent out of any workspace. Changes apply on the next deploy.", "properties": { "name": { "type": "string", "description": "Same rules as create. Renaming does NOT change the agent's URL.", "nullable": true }, "description": { "type": "string", "nullable": true }, "agent_type": { "type": "string", "enum": [ "service", "job" ], "nullable": true }, "tier": { "type": "string", "enum": [ "free", "starter", "performance", "enterprise" ], "nullable": true }, "runtime": { "type": "string", "enum": [ "python3.11", "python3.12", "python3.13", "node20", "node22", "node20-ts", "node22-ts", "bun", "dockerfile" ], "nullable": true }, "memory_mb": { "type": "integer", "nullable": true }, "idle_timeout_minutes": { "type": "integer", "nullable": true }, "keep_alive": { "type": "boolean", "nullable": true }, "database_collection": { "type": "string", "nullable": true }, "model_name": { "type": "string", "nullable": true }, "entrypoint": { "type": "string", "nullable": true }, "spawn_enabled": { "type": "boolean", "nullable": true }, "allowed_workers": { "type": "array", "items": { "type": "string" }, "nullable": true }, "workspace_name": { "type": "string", "nullable": true } } }, "Deployment": { "type": "object", "required": [ "id", "agent_id", "version", "state", "image_size_mb", "regions", "pending_regions", "queue_position", "created_at", "started_at", "deployed_at", "error_message" ], "properties": { "id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "state": { "type": "string", "enum": [ "queued", "building", "deploying", "active", "failed", "rolled_back", "superseded", "completed" ] }, "image_size_mb": { "type": "integer", "nullable": true }, "regions": { "type": "array", "items": { "type": "string" } }, "pending_regions": { "type": "array", "items": { "type": "string" } }, "queue_position": { "type": "integer", "description": "Set while state is queued.", "nullable": true }, "is_ephemeral": { "type": "boolean", "description": "True for a scheduled, manual or spawned one-shot run." }, "is_serving": { "type": "boolean", "description": "Whether traffic is being answered." }, "is_degraded": { "type": "boolean" }, "regions_total": { "type": "integer" }, "regions_ready": { "type": "integer" }, "pending_region_alert_stage": { "type": "string", "nullable": true }, "can_redeploy": { "type": "boolean", "description": "Whether this version can be rebuilt. False once its stored code archive has been deleted — archives are kept for the 3 most recent successful deployments." }, "can_rollback": { "type": "boolean", "description": "Whether this version can be rolled back to. False for a version that never produced a built image, and for one-shot runs." }, "cancellation_requested": { "type": "boolean" }, "cancellation_reason": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "deployed_at": { "type": "string", "format": "date-time", "nullable": true }, "error_message": { "type": "string", "nullable": true } } }, "AgentStatusDetail": { "type": "object", "description": "Live machine state, read from the machine host rather than from stored state.", "required": [ "agent_id", "name", "status", "url", "machines" ], "properties": { "agent_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "building", "deploying", "running", "failed", "stopped", "paused", "usage_paused", "suspended", "archived", "deleting", "deleted" ] }, "url": { "type": "string", "description": "null until the agent has machines.", "nullable": true }, "machines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "region": { "type": "string" }, "state": { "type": "string" }, "source": { "type": "string", "enum": [ "live", "cached" ], "description": "PROVENANCE OF `state`. \"live\" = read from the machine host in this request. \"cached\" = the host read failed and this is the last stored value, up to about a minute stale. Require \"live\" before treating `state` as ground truth." }, "health": { "type": "string", "nullable": true }, "last_check": { "type": "string", "format": "date-time", "nullable": true }, "instance_id": { "type": "string", "nullable": true } } } } } }, "Run": { "type": "object", "description": "One ephemeral run. Spawned runs are excluded from run history by design.", "properties": { "id": { "type": "string", "format": "uuid" }, "trigger_source": { "type": "string", "enum": [ "cron", "manual" ] }, "state": { "type": "string", "enum": [ "queued", "building", "deploying", "active", "failed", "rolled_back", "superseded", "completed" ] }, "created_at": { "type": "string", "format": "date-time" }, "error_message": { "type": "string", "nullable": true }, "machine_started_at": { "type": "string", "format": "date-time", "nullable": true }, "machine_stopped_at": { "type": "string", "format": "date-time", "nullable": true }, "duration_seconds": { "type": "integer", "description": "null until the run has both started and stopped.", "nullable": true } } }, "RunRequest": { "type": "object", "properties": { "payload": { "type": "object", "additionalProperties": true, "description": "Input the run reads back at GET /deployments/{id}/payload.", "nullable": true } } }, "RunAccepted": { "type": "object", "required": [ "deployment_id", "version", "job_id" ], "properties": { "deployment_id": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "job_id": { "type": "string", "format": "uuid" } } }, "ScheduleState": { "type": "object", "required": [ "cron_paused", "cron_next_run_at", "changed" ], "description": "Idempotent: pausing an already-paused schedule returns changed=false and alters nothing. Resume recomputes the next occurrence from now and never backfills.", "properties": { "cron_paused": { "type": "boolean" }, "cron_next_run_at": { "type": "string", "format": "date-time", "nullable": true }, "changed": { "type": "boolean" } } }, "SpawnRequest": { "type": "object", "required": [ "child_agent_id" ], "properties": { "child_agent_id": { "type": "string", "description": "UUID or name of the type: job agent to spawn." }, "payload": { "type": "object", "additionalProperties": true } } }, "SpawnResponse": { "type": "object", "required": [ "spawn_id", "job_id", "child_agent_id", "workspace", "region", "status", "estimated_start" ], "properties": { "spawn_id": { "type": "string", "format": "uuid", "description": "The child deployment id, injected into the child as AETHERFY_SPAWN_ID." }, "job_id": { "type": "string", "format": "uuid" }, "child_agent_id": { "type": "string", "format": "uuid" }, "workspace": { "type": "string", "nullable": true }, "region": { "type": "string", "description": "Always the parent agent’s region." }, "status": { "type": "string" }, "estimated_start": { "type": "string" } } }, "SpawnPayload": { "type": "object", "required": [ "payload" ], "properties": { "payload": { "type": "object", "additionalProperties": true } } }, "LogEntry": { "type": "object", "required": [ "id", "timestamp", "stream", "level", "message" ], "properties": { "id": { "type": "integer", "description": "Keyset cursor for after_id / before_id." }, "timestamp": { "type": "string", "format": "date-time" }, "stream": { "type": "string", "enum": [ "stdout", "stderr", "system" ] }, "level": { "type": "string", "enum": [ "INFO", "WARN", "ERROR", "DEBUG", "SYSTEM" ] }, "message": { "type": "string" } } }, "SecretCreate": { "type": "object", "required": [ "key", "value" ], "description": "Upsert: posting an existing key replaces its value. The value is never returned.", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 255 }, "value": { "type": "string", "minLength": 1 }, "description": { "type": "string", "maxLength": 512, "nullable": true } } }, "Secret": { "type": "object", "required": [ "id", "agent_id", "key", "description", "created_at", "updated_at" ], "description": "No value field exists on any response. Aetherfy never returns a secret value.", "properties": { "id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "description": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WorkspaceSecret": { "type": "object", "required": [ "id", "workspace_name", "user_id", "key", "description", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_name": { "type": "string" }, "user_id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "description": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SecretKey": { "type": "object", "required": [ "key", "description", "created_at", "updated_at" ], "properties": { "key": { "type": "string" }, "description": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WorkspaceCreate": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 3, "maxLength": 63 }, "description": { "type": "string", "nullable": true }, "regions": { "type": "array", "items": { "type": "string" }, "description": "Omit to inherit the account default. An EMPTY array is rejected — that is a different request from omitting the field.", "nullable": true } } }, "Workspace": { "type": "object", "required": [ "id", "name", "description", "regions", "agent_count", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "regions": { "type": "array", "items": { "type": "string" } }, "agent_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WorkspaceUpdate": { "type": "object", "description": "Name is immutable — sending a different one returns 400 WORKSPACE_NAME_IMMUTABLE.", "properties": { "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true } } }, "WorkspaceDeleteResult": { "type": "object", "required": [ "status", "secrets_deleted" ], "properties": { "status": { "type": "string" }, "secrets_deleted": { "type": "integer" } } }, "WorkspaceAgent": { "type": "object", "required": [ "id", "name", "agent_type", "status", "deployed", "url", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "agent_type": { "type": "string", "enum": [ "service", "job" ] }, "status": { "type": "string", "enum": [ "pending", "building", "deploying", "running", "failed", "stopped", "paused", "usage_paused", "suspended", "archived", "deleting", "deleted" ] }, "deployed": { "type": "boolean", "description": "Whether the agent holds a running app." }, "url": { "type": "string", "description": "Where to send requests, null when there is nowhere.", "nullable": true }, "is_degraded": { "type": "boolean" }, "regions_total": { "type": "integer" }, "regions_ready": { "type": "integer" }, "degraded_reason": { "type": "string", "nullable": true }, "failure_code": { "type": "string", "description": "Why the agent is FAILED, when nothing else on the record can say. Today the only value is `app_lost_on_provider`: the compute plane no longer has an app for this agent. Your code, secrets and address are kept and a redeploy brings it back. Null means no reason was recorded, which is NOT a claim that the agent is healthy — a FAILED agent whose build did not compile has null here and explains itself through its deployment error instead. Match on this, not on failure_message.", "nullable": true }, "failure_message": { "type": "string", "description": "The same reason as prose, for display. Wording may change between releases and is null for a code this platform version does not recognise — branch on failure_code.", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "RegionsUpdateRequest": { "type": "object", "required": [ "regions" ], "properties": { "regions": { "type": "array", "items": { "type": "string" }, "description": "The desired FINAL set, not a delta." } } }, "RegionChangeNoOp": { "type": "object", "required": [ "status", "scope", "current_regions" ], "description": "Returned with 200 when the requested region set already equals the current one. Compared as a SET, so reordering is also a no-op. Carries no operation_id — there is nothing to poll.", "properties": { "status": { "type": "string", "enum": [ "no_op" ] }, "scope": { "type": "string" }, "current_regions": { "type": "array", "items": { "type": "string" } }, "workspace_name": { "type": "string" } } }, "RegionChangeAccepted": { "type": "object", "required": [ "operation_id", "from_regions", "to_regions", "regions_to_add", "regions_to_remove" ], "properties": { "operation_id": { "type": "string", "format": "uuid", "description": "Poll GET /api/v1/operations/{operation_id}." }, "from_regions": { "type": "array", "items": { "type": "string" } }, "to_regions": { "type": "array", "items": { "type": "string" } }, "regions_to_add": { "type": "array", "items": { "type": "string" } }, "regions_to_remove": { "type": "array", "items": { "type": "string" } }, "workspace_name": { "type": "string" } } }, "HomeRegionUpdateRequest": { "type": "object", "required": [ "region" ], "properties": { "region": { "type": "string", "description": "Single-region tiers only." } } }, "CollectionMoveRequest": { "type": "object", "description": "Send workspace_id OR regions, never both.", "properties": { "workspace_id": { "type": "string", "format": "uuid", "description": "Target workspace, or null to move out of any workspace.", "nullable": true }, "regions": { "type": "array", "items": { "type": "string" }, "nullable": true } } }, "Operation": { "type": "object", "required": [ "operation_id", "scope", "target_id", "status" ], "properties": { "operation_id": { "type": "string", "format": "uuid" }, "scope": { "type": "string", "nullable": true }, "target_id": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "in_progress", "succeeded", "failed" ], "description": "in_progress covers the brief window after a retryable sub-step failed and before it is retried. Only `failed` is terminal failure." }, "regions_to_add": { "type": "array", "items": { "type": "string" } }, "regions_to_remove": { "type": "array", "items": { "type": "string" } }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "failures": { "type": "array", "items": {}, "nullable": true }, "deleted_aliases": { "type": "array", "description": "Collection-move only. A move DELETES the source aliases and does not recreate them; this is the list to recreate deliberately.", "items": { "type": "object", "properties": { "alias_name": { "type": "string" }, "collection_name": { "type": "string" } } }, "nullable": true } } }, "UserInfo": { "type": "object", "required": [ "user_id", "email", "tier", "subscription_status", "is_test", "limits" ], "properties": { "user_id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "tier": { "type": "string" }, "subscription_status": { "type": "string" }, "is_test": { "type": "boolean", "description": "Derived from the API key prefix, not from a header." }, "limits": { "type": "object", "additionalProperties": true, "description": "The plan limits actually enforced for this account. limits.requests_per_minute is the control-plane rate budget; null means unlimited." } } }, "BillingSummary": { "type": "object", "required": [ "year", "month", "total_compute_ms", "total_compute_seconds", "free_tier_seconds", "billable_seconds", "total_cost_usd", "agents" ], "description": "Compute time only — not an invoice. Money is a decimal STRING, not a float.", "properties": { "year": { "type": "integer" }, "month": { "type": "integer" }, "total_compute_ms": { "type": "integer" }, "total_compute_seconds": { "type": "number" }, "free_tier_seconds": { "type": "integer" }, "billable_seconds": { "type": "number" }, "total_cost_usd": { "type": "string" }, "agents": { "type": "array", "items": { "type": "object", "properties": { "agent_id": { "type": "string", "format": "uuid" }, "agent_name": { "type": "string" }, "compute_ms": { "type": "integer" }, "compute_seconds": { "type": "number" }, "cost_usd": { "type": "string" }, "billing_tier": { "type": "string" } } } } } }, "GitHubLinkRequest": { "type": "object", "required": [ "repo" ], "properties": { "repo": { "type": "string", "description": "owner/repo" }, "branch": { "type": "string", "default": "main" }, "root_dir": { "type": "string", "nullable": true } } }, "GitHubLink": { "type": "object", "required": [ "repo", "branch", "root_dir", "webhook_id", "webhook_secret" ], "properties": { "repo": { "type": "string" }, "branch": { "type": "string" }, "root_dir": { "type": "string", "nullable": true }, "webhook_id": { "type": "string" }, "webhook_secret": { "type": "string", "description": "RETURNED ONCE, on this response only. No route reads it back. Store it now; if lost, unlink and link again to mint a new one." } } }, "GitHubLinkStatus": { "type": "object", "required": [ "linked" ], "properties": { "linked": { "type": "boolean" }, "repo": { "type": "string", "nullable": true }, "branch": { "type": "string", "nullable": true }, "root_dir": { "type": "string", "nullable": true }, "webhook_id": { "type": "string", "nullable": true } } }, "GitHubStatus": { "type": "object", "required": [ "connected" ], "properties": { "connected": { "type": "boolean" }, "installation_id": { "type": "integer", "nullable": true }, "connected_at": { "type": "string", "format": "date-time", "nullable": true } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An Aetherfy API key, sent as `Authorization: Bearer `. The prefix selects the environment: afy_live_… addresses production, afy_test_… the test environment. Keys are created at https://app.aetherfy.com/dashboard/settings/api-keys" } } }, "tags": [ { "name": "agents", "description": "Agent lifecycle" }, { "name": "deployments", "description": "Deploying, rolling back, cancelling" }, { "name": "runs", "description": "On-demand runs, scheduled tasks, spawns, logs" }, { "name": "secrets", "description": "Encrypted agent and workspace secrets" }, { "name": "workspaces", "description": "Workspaces, regional placement, long-running operations" }, { "name": "account", "description": "Identity, usage, GitHub connection" } ], "x-rate-limits": { "window": "sliding 60-second window", "retryAfterHeader": true, "headers": [ "Retry-After", "X-RateLimit-Limit", "X-RateLimit-Remaining", "X-RateLimit-Reset" ], "note": "X-RateLimit-* also ride SUCCESSFUL responses, so a client can pace itself without provoking a 429. Enterprise is unlimited and receives no X-RateLimit-* headers at all. This budget is separate from the vector API’s: saturating one leaves the other intact.", "perMinuteByTier": { "free": 100, "starter": 500, "performance": 2000, "enterprise": null } }, "x-async": { "note": "HTTP 202 means accepted, not finished. The 202 bodies of stop/start/archive/restore/delete carry a PROGRESS LABEL (\"paused\", \"archiving\", \"restoring\", \"deleting\"), which is not the agent status enum. Poll GET /api/v1/agents/{agent} for real state, or GET /api/v1/operations/{operation_id} for region changes and collection moves." }, "x-not-documented": [ "/internal/* — dashboard↔control-plane private contract, shared-secret auth", "POST /api/v1/webhooks/github and /api/v1/webhooks/github/{agent_id} — called by GitHub, signature-authenticated", "GET /api/v1/auth/github/callback — browser OAuth leg", "GET /api/v1/health, /readiness, /liveness — ops probes" ], "paths": { "/api/v1/agents": { "get": { "summary": "List every agent on the account.", "tags": [ "agents" ], "responses": { "200": { "description": "The account’s agents.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create an agent. Does not deploy it.", "tags": [ "agents" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreate" } } } }, "responses": { "201": { "description": "The created agent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "WORKSPACE_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "AGENT_NAME_TAKEN.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agent}": { "parameters": [ { "name": "agent", "in": "path", "required": true, "description": "The agent UUID or its name. Both address the same agent.", "schema": { "type": "string" } } ], "get": { "summary": "Read one agent.", "tags": [ "agents" ], "responses": { "200": { "description": "The agent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "AGENT_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update configuration. Applies on the next deploy.", "tags": [ "agents" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentUpdate" } } } }, "responses": { "200": { "description": "The updated agent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "400": { "description": "AGENT_COLLECTION_REGION_MISMATCH or AGENT_DEPLOYMENT_OUTSIDE_NEW_WORKSPACE_SCOPE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "AGENT_NOT_FOUND or WORKSPACE_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete an agent permanently. Asynchronous.", "tags": [ "agents" ], "responses": { "202": { "description": "Accepted; the agent moves to deleting." }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "AGENT_HAS_PENDING_DEPLOYMENTS or AGENT_HAS_WORKER_DEPENDENTS.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agent}/stop": { "parameters": [ { "name": "agent", "in": "path", "required": true, "description": "The agent UUID or its name. Both address the same agent.", "schema": { "type": "string" } } ], "post": { "summary": "Stop an agent. Its status becomes `paused`, NOT `stopped`.", "tags": [ "agents" ], "responses": { "202": { "description": "Accepted. Body {\"status\": \"paused\", \"agent_id\": \"…\"}." }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "AGENT_ALREADY_PAUSED, AGENT_NOT_PAUSEABLE_SYSTEM_STATE, AGENT_HAS_PENDING_DEPLOYMENTS, or AGENT_OPERATION_IN_PROGRESS (transient — retry).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agent}/start": { "parameters": [ { "name": "agent", "in": "path", "required": true, "description": "The agent UUID or its name. Both address the same agent.", "schema": { "type": "string" } } ], "post": { "summary": "Start a paused agent without rebuilding.", "tags": [ "agents" ], "responses": { "202": { "description": "Accepted." }, "400": { "description": "AGENT_NO_MACHINES — deploy first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "AGENT_NOT_PAUSED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agent}/archive": { "parameters": [ { "name": "agent", "in": "path", "required": true, "description": "The agent UUID or its name. Both address the same agent.", "schema": { "type": "string" } } ], "post": { "summary": "Archive an agent, releasing its quota slot but keeping config and code.", "tags": [ "agents" ], "responses": { "202": { "description": "Accepted." }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "AGENT_ALREADY_ARCHIVED, AGENT_NOT_ARCHIVABLE_SYSTEM_STATE, AGENT_HAS_PENDING_DEPLOYMENTS, or AGENT_HAS_WORKER_DEPENDENTS.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agent}/restore": { "parameters": [ { "name": "agent", "in": "path", "required": true, "description": "The agent UUID or its name. Both address the same agent.", "schema": { "type": "string" } } ], "post": { "summary": "Restore an archived agent. Re-checks quota, so it can be refused.", "tags": [ "agents" ], "responses": { "202": { "description": "Accepted." }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "AGENT_NOT_ARCHIVED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agent}/status": { "parameters": [ { "name": "agent", "in": "path", "required": true, "description": "The agent UUID or its name. Both address the same agent.", "schema": { "type": "string" } } ], "get": { "summary": "Live machine status. Read machines[].source before trusting state.", "tags": [ "agents" ], "responses": { "200": { "description": "Live status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentStatusDetail" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "AGENT_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agent}/yaml": { "parameters": [ { "name": "agent", "in": "path", "required": true, "description": "The agent UUID or its name. Both address the same agent.", "schema": { "type": "string" } } ], "get": { "summary": "Export the agent as aetherfy.yaml.", "tags": [ "agents" ], "responses": { "200": { "description": "The declarative config. Content-Type application/yaml, not JSON.", "content": { "application/yaml": { "schema": { "type": "string" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "AGENT_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agent}/deploy": { "parameters": [ { "name": "agent", "in": "path", "required": true, "description": "The agent UUID or its name. Both address the same agent.", "schema": { "type": "string" } }, { "name": "confirm_overage", "in": "query", "required": false, "description": "Set true to accept a deploy that adds usage, after a 402.", "schema": { "type": "boolean", "default": false } } ], "post": { "summary": "Deploy an agent from a gzipped tarball. Multipart, not JSON.", "tags": [ "deployments" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "code_archive" ], "properties": { "code_archive": { "type": "string", "format": "binary", "description": "Gzipped tarball of the agent directory. An aetherfy.yaml at its root is parsed and applied before building." } } } } } }, "responses": { "202": { "description": "Accepted; build queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deployment" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "OVERAGE_CONFIRM_REQUIRED — retry with confirm_overage=true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "SOFT_CAP_EXCEEDED, DUNNING_FROZEN, PLAN_LIMIT_EXCEEDED, DEPLOY_REGIONS_NOT_IN_SCOPE, or DEPLOY_REGIONS_NOT_IN_COLLECTION_SCOPE. Also, on every route: ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "COLLECTION_NOT_FOUND or WORKER_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "DEPLOYMENT_IN_PROGRESS (transient) or AGENT_PAUSED_CANNOT_DEPLOY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "DEPLOYMENT_ARCHIVE_TOO_LARGE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "DEPLOYMENT_CONFIG_PARSE_ERROR, RUNTIME_IMMUTABLE, or AGENT_SCHEDULE_NOT_ALLOWED_ON_WORKER.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "DEPLOYMENT_UPLOAD_FAILED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/deployments": { "parameters": [ { "name": "agent_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "List deployments across the account.", "tags": [ "deployments" ], "responses": { "200": { "description": "Deployments, newest first.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Deployment" } } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agent}/deployments": { "parameters": [ { "name": "agent", "in": "path", "required": true, "description": "The agent UUID or its name. Both address the same agent.", "schema": { "type": "string" } } ], "get": { "summary": "List one agent’s deployments.", "tags": [ "deployments" ], "responses": { "200": { "description": "Deployments, newest first.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Deployment" } } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/deployments/{deployment_id}": { "parameters": [ { "name": "deployment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read one deployment. Poll this to follow a build.", "tags": [ "deployments" ], "responses": { "200": { "description": "The deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deployment" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "DEPLOYMENT_ACCESS_DENIED. Also, on every route: ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "DEPLOYMENT_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agent}/deployments/{version}/rollback": { "parameters": [ { "name": "agent", "in": "path", "required": true, "description": "The agent UUID or its name. Both address the same agent.", "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer" } } ], "post": { "summary": "Redeploy a previously built version. Creates a new version.", "tags": [ "deployments" ], "responses": { "202": { "description": "Accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deployment" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "SOFT_CAP_EXCEEDED or DUNNING_FROZEN. Also, on every route: ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "DEPLOYMENT_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "DEPLOYMENT_IN_PROGRESS (transient) or AGENT_PAUSED_CANNOT_ROLLBACK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "DEPLOYMENT_ROLLBACK_TARGET_INVALID — most often the image is no longer available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agent}/deployments/{version}/redeploy": { "parameters": [ { "name": "agent", "in": "path", "required": true, "description": "The agent UUID or its name. Both address the same agent.", "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer" } } ], "post": { "summary": "Rebuild a version from its stored source, with current secrets. Creates a new version.", "tags": [ "deployments" ], "responses": { "202": { "description": "Accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deployment" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "SOFT_CAP_EXCEEDED or DUNNING_FROZEN. Also, on every route: ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "DEPLOYMENT_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "DEPLOYMENT_IN_PROGRESS (transient) or AGENT_PAUSED_CANNOT_REDEPLOY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "DEPLOYMENT_REDEPLOY_SOURCE_UNAVAILABLE — the stored code archive is gone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Runs a fresh build — unlike rollback, which re-deploys an existing image. Secrets are injected while the machine is built, so this is what applies a secret written since the last deploy. The agent keeps its current configuration; the archive is not re-read for it." } }, "/api/v1/agents/{agent}/deployments/{version}/cancel": { "parameters": [ { "name": "agent", "in": "path", "required": true, "description": "The agent UUID or its name. Both address the same agent.", "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer" } } ], "post": { "summary": "Request cancellation of an in-flight deployment. Cooperative.", "tags": [ "deployments" ], "responses": { "202": { "description": "Accepted; cancellation_requested is set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deployment" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "DEPLOYMENT_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "DEPLOYMENT_TERMINAL_CANNOT_CANCEL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/deployments/{deployment_id}/payload": { "parameters": [ { "name": "deployment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read the input a spawned or scheduled run was started with.", "tags": [ "runs" ], "responses": { "200": { "description": "The payload, or {} if none was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpawnPayload" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "DEPLOYMENT_NOT_FOUND, or DEPLOYMENT_NOT_EPHEMERAL for a normal deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Called by the running agent on itself, using AETHERFY_SPAWN_ID as the deployment id and AETHERFY_API_KEY as the credential — both injected into its environment." } }, "/api/v1/agents/{agent}/run": { "parameters": [ { "name": "agent", "in": "path", "required": true, "description": "The agent UUID or its name. Both address the same agent.", "schema": { "type": "string" } } ], "post": { "summary": "Run a type: job agent now. Does not touch its schedule.", "tags": [ "runs" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunRequest" } } } }, "responses": { "202": { "description": "Accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunAccepted" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "SOFT_CAP_EXCEEDED. Also, on every route: ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "AGENT_RUN_INELIGIBLE_STATE (carries current_state) or AGENT_RUN_IN_PROGRESS (transient).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "AGENT_RUN_REQUIRES_JOB_TYPE or AGENT_NOT_DEPLOYED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agent}/runs": { "parameters": [ { "name": "agent", "in": "path", "required": true, "description": "The agent UUID or its name. Both address the same agent.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "trigger_source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "cron", "manual" ] } }, { "name": "before", "in": "query", "required": false, "description": "ISO-8601 keyset cursor.", "schema": { "type": "string" } } ], "get": { "summary": "Run history, newest first. Spawned runs are excluded by design.", "tags": [ "runs" ], "responses": { "200": { "description": "Runs.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Run" } } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "AGENT_RUNS_INVALID_TRIGGER_SOURCE or AGENT_RUNS_INVALID_BEFORE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agent}/schedule/pause": { "parameters": [ { "name": "agent", "in": "path", "required": true, "description": "The agent UUID or its name. Both address the same agent.", "schema": { "type": "string" } } ], "post": { "summary": "Pause a scheduled task. Idempotent.", "tags": [ "runs" ], "responses": { "200": { "description": "Schedule state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleState" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "AGENT_SCHEDULE_NOT_SET.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agent}/schedule/resume": { "parameters": [ { "name": "agent", "in": "path", "required": true, "description": "The agent UUID or its name. Both address the same agent.", "schema": { "type": "string" } } ], "post": { "summary": "Resume a paused scheduled task. Never backfills missed occurrences.", "tags": [ "runs" ], "responses": { "200": { "description": "Schedule state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleState" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "AGENT_SCHEDULE_NOT_SET.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agent}/spawn": { "parameters": [ { "name": "agent", "in": "path", "required": true, "description": "The agent UUID or its name. Both address the same agent.", "schema": { "type": "string" } } ], "post": { "summary": "Spawn a type: job worker from this parent agent, in the parent’s region.", "tags": [ "runs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpawnRequest" } } } }, "responses": { "202": { "description": "Accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpawnResponse" } } } }, "400": { "description": "AGENT_CHILD_NOT_JOB_TYPE, AGENT_SPAWN_DEPTH_INVALID, AGENT_CHILD_NOT_DEPLOYED, or AGENT_PARENT_NO_DEPLOYMENT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "AGENT_NOT_SPAWN_ENABLED, AGENT_WORKER_NOT_ALLOWED, or SOFT_CAP_EXCEEDED. Also, on every route: ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "AGENT_PARENT_PAUSED, AGENT_WORKER_PAUSED, or AGENT_PARENT_NOT_SPAWNABLE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-throttles": { "AGENT_SPAWN_CONCURRENCY_LIMIT_EXCEEDED": "429 — a hard cap on concurrent spawns across the account. Wait for some to finish.", "AGENT_SPAWN_RATE_LIMITED": "503 — another deploy of the same agent held its version lock too long for this spawn to take it. Retry; if it repeats, a deploy is stuck." } } }, "/api/v1/agents/{agent}/logs": { "parameters": [ { "name": "agent", "in": "path", "required": true, "description": "The agent UUID or its name. Both address the same agent.", "schema": { "type": "string" } }, { "name": "tail", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 1000 } }, { "name": "since", "in": "query", "required": false, "description": "N followed by s, m, h or d — e.g. 30m, 2h.", "schema": { "type": "string" } }, { "name": "level", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "INFO", "WARN", "ERROR", "DEBUG", "SYSTEM" ] } }, { "name": "stream", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "stdout", "stderr", "system" ] } }, { "name": "search", "in": "query", "required": false, "description": "Case-insensitive substring match.", "schema": { "type": "string" } }, { "name": "deployment_id", "in": "query", "required": false, "description": "Narrow to one run.", "schema": { "type": "string", "format": "uuid" } }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "before_id", "in": "query", "required": false, "schema": { "type": "integer" } } ], "get": { "summary": "Runtime logs. Build output is NOT available through the API.", "tags": [ "runs" ], "responses": { "200": { "description": "Log entries.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LogEntry" } } } } }, "400": { "description": "AGENT_LOGS_INVALID_SINCE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "AGENT_LOGS_INVALID_FILTER or AGENT_LOGS_INVALID_DEPLOYMENT_ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "SORT ORDER DEPENDS ON after_id: without it, newest-first (id DESC); with it, oldest-first (id ASC) so that following a live agent moves forward. Retention is 7 days." } }, "/api/v1/agents/{agent}/secrets": { "parameters": [ { "name": "agent", "in": "path", "required": true, "description": "The agent UUID or its name. Both address the same agent.", "schema": { "type": "string" } } ], "get": { "summary": "List secret keys and metadata. Values are never returned.", "tags": [ "secrets" ], "responses": { "200": { "description": "Secret keys.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SecretKey" } } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Set a secret. Upsert — an existing key is replaced.", "tags": [ "secrets" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretCreate" } } } }, "responses": { "201": { "description": "The secret, without its value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Secret" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "SECRET_VALIDATION_ERROR.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agent}/secrets/{key}": { "parameters": [ { "name": "agent", "in": "path", "required": true, "description": "The agent UUID or its name. Both address the same agent.", "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "Delete a secret. Takes effect on the next deploy.", "tags": [ "secrets" ], "responses": { "204": { "description": "Deleted." }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SECRET_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agent}/secrets/{key}/rotate": { "parameters": [ { "name": "agent", "in": "path", "required": true, "description": "The agent UUID or its name. Both address the same agent.", "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Re-encrypt a secret under new material. The VALUE is unchanged.", "tags": [ "secrets" ], "responses": { "200": { "description": "The secret, without its value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Secret" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SECRET_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SECRET_INTERNAL_ERROR — the stored secret is unchanged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspace}/secrets": { "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "List a workspace’s secret keys.", "tags": [ "secrets" ], "responses": { "200": { "description": "Secret keys.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SecretKey" } } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Set a workspace secret, visible to every agent in the workspace.", "tags": [ "secrets" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretCreate" } } } }, "responses": { "201": { "description": "The secret, without its value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceSecret" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "SECRET_VALIDATION_ERROR.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspace}/secrets/{key}": { "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "Delete a workspace secret.", "tags": [ "secrets" ], "responses": { "204": { "description": "Deleted." }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SECRET_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces": { "get": { "summary": "List workspaces.", "tags": [ "workspaces" ], "responses": { "200": { "description": "Workspaces.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" } } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a workspace.", "tags": [ "workspaces" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceCreate" } } } }, "responses": { "201": { "description": "The workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "description": "WORKSPACE_LIMIT_EXCEEDED or INVALID_WORKSPACE_REGIONS.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "WORKSPACE_NAME_TAKEN.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "WORKSPACE_REGIONS_EMPTY — omit regions rather than sending [].", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspace}": { "parameters": [ { "name": "workspace", "in": "path", "required": true, "description": "The workspace NAME, not its UUID.", "schema": { "type": "string" } } ], "get": { "summary": "Read one workspace.", "tags": [ "workspaces" ], "responses": { "200": { "description": "The workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "WORKSPACE_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update a workspace description. The name is immutable.", "tags": [ "workspaces" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceUpdate" } } } }, "responses": { "200": { "description": "The workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "description": "WORKSPACE_NAME_IMMUTABLE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete an empty workspace. Its workspace secrets go with it.", "tags": [ "workspaces" ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceDeleteResult" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "WORKSPACE_HAS_AGENTS or WORKSPACE_HAS_COLLECTIONS.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspace}/agents": { "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "List the agents in a workspace, in summary form.", "tags": [ "workspaces" ], "responses": { "200": { "description": "Agents.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceAgent" } } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspace}/regions": { "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "summary": "Change a workspace’s region set. Asynchronous, unless it is a no-op.", "tags": [ "workspaces" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegionsUpdateRequest" } } } }, "responses": { "200": { "description": "The requested set already matches the current one. Idempotent no-op: nothing is enqueued, and the body is {status:\"no_op\", scope, current_regions, workspace_name} with NO operation_id to poll.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegionChangeNoOp" } } } }, "202": { "description": "Accepted; poll the operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegionChangeAccepted" } } } }, "400": { "description": "INVALID_WORKSPACE_REGIONS.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "WORKSPACE_NOT_FOUND or USER_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "REGION_OP_IN_FLIGHT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "STORAGE_LIMIT_EXCEEDED — every replica counts against the storage quota.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/collections/{collection_id}": { "parameters": [ { "name": "collection_id", "in": "path", "required": true, "description": "The collection UUID, not its name.", "schema": { "type": "string", "format": "uuid" } } ], "patch": { "summary": "Move a collection between workspaces, or set its regions.", "tags": [ "workspaces" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionMoveRequest" } } } }, "responses": { "200": { "description": "Applied with no data movement." }, "202": { "description": "Accepted; poll the operation." }, "400": { "description": "COLLECTION_REGIONS_WORKSPACE_COMBINED or VALIDATION_VIOLATIONS (iterate detail.violations).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "COLLECTION_NOT_FOUND or TARGET_WORKSPACE_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "COLLECTION_MOVE_IN_FLIGHT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "COLLECTION_REGIONS_EMPTY, COLLECTION_REGIONS_NOT_IN_SCOPE, or TARGET_WORKSPACE_HAS_NO_REGIONS.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "COLLECTION_MOVE_ENQUEUE_FAILED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "A move DELETES the collection’s aliases in the source scope and does not recreate them; the completed operation lists them in deleted_aliases. 200 when nothing has to move, 202 with an operation_id when data relocates." } }, "/api/v1/operations/{operation_id}": { "parameters": [ { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Poll a region change or collection move.", "tags": [ "workspaces" ], "responses": { "200": { "description": "The operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operation" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "OPERATION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/auth/me": { "get": { "summary": "The authenticated identity and its live plan limits.", "tags": [ "account" ], "responses": { "200": { "description": "Identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserInfo" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "The cheapest way to verify a key. is_test is derived from the key prefix. Read the rate budget from limits.requests_per_minute rather than hardcoding a tier number." } }, "/api/v1/users/me/home-region": { "patch": { "summary": "Set the account home region. Single-region tiers only.", "tags": [ "account" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HomeRegionUpdateRequest" } } } }, "responses": { "200": { "description": "Applied, or an idempotent no-op if unchanged." }, "400": { "description": "INVALID_REGION, or HOME_REGION_NOT_APPLICABLE on a multi-region plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "USER_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "STARTER_REGION_CONSISTENCY — region-bearing resources already exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/usage/summary": { "parameters": [ { "name": "year", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "month", "in": "query", "required": false, "schema": { "type": "integer" } } ], "get": { "summary": "Monthly compute usage. Not an invoice.", "tags": [ "account" ], "responses": { "200": { "description": "Usage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingSummary" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/usage/agent/{agent_id}/events": { "parameters": [ { "name": "agent_id", "in": "path", "required": true, "description": "UUID only — this route does not accept a name.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } } ], "get": { "summary": "Machine start/stop events behind an agent’s compute time.", "tags": [ "account" ], "responses": { "200": { "description": "Lifecycle events." }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "AGENT_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/auth/github": { "get": { "summary": "Begin the GitHub App installation. Redirects — use a browser.", "tags": [ "account" ], "responses": { "302": { "description": "Redirect to GitHub." }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "GITHUB_APP_NOT_CONFIGURED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Disconnect the GitHub account. Agent links stop deploying.", "tags": [ "account" ], "responses": { "204": { "description": "Disconnected." }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/auth/github/status": { "get": { "summary": "Whether a GitHub account is connected.", "tags": [ "account" ], "responses": { "200": { "description": "Connection status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubStatus" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agent}/github": { "parameters": [ { "name": "agent", "in": "path", "required": true, "description": "The agent UUID or its name. Both address the same agent.", "schema": { "type": "string" } } ], "get": { "summary": "Read an agent’s repository link. Never returns the webhook secret.", "tags": [ "deployments" ], "responses": { "200": { "description": "Link status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubLinkStatus" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Link an agent to a repository for push-to-deploy.", "tags": [ "deployments" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubLinkRequest" } } } }, "responses": { "201": { "description": "The link. webhook_secret is returned ONCE, here only.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubLink" } } } }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "GITHUB_REPO_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "GITHUB_NOT_CONNECTED — connect the account first — or GITHUB_WEBHOOK_CREATE_FAILED, which is GitHub itself rejecting the webhook (most often one already exists on the repository).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "GITHUB_PERSISTENCE_FAILED — the webhook was created, then storing the link failed; the orphan webhook is removed before this answers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "GITHUB_API_ERROR — GitHub was unreachable. Retry. Also, on every route: RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Unlink an agent and remove its webhook.", "tags": [ "deployments" ], "responses": { "204": { "description": "Unlinked." }, "401": { "description": "MISSING_API_KEY (no Authorization header) or INVALID_API_KEY (key does not resolve). Same codes the vector API uses, carried in detail.code rather than error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (control-plane only — the vector API does not gate on subscription status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT_EXCEEDED. Carries Retry-After and X-RateLimit-* headers, and retry_after_seconds in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "RESOURCE_BUSY — a worker held a row lock too long — or SERVICE_UNAVAILABLE, meaning a service the request depended on (on plan-gated routes, the plan lookup that checks your limits) was unreachable, so nothing was written. Both transient and always safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }