API Reference

Production route contracts verified against the live Agent OS deployment.

Authentication: the web app uses a secure browser session cookie after /api/signup or /api/signin. External callers should use the returned bearerToken. The legacy apiKey field remains as an alias for compatibility.
Canonical production URL: https://agentos-app.vercel.app. The custom domain https://agentos.service is still activating until the apex DNS A record points to Vercel.
Product direction: Agent OS is infrastructure first. Any social or X routes listed below are optional example integrations, not required parts of the core agent runtime.
https://agentos-app.vercel.app
GET
/health
Auth: None

Liveness check for the production app and tool registry.

Response
{ "status": "ok", "version": "1.0.0", "timestamp": "...", "tools": 32 }
GET
/tools
Auth: None

List the universal MCP tool registry exposed by Agent OS.

Response
{ "tools": [{ "name": "agentos.mem_set", "description": "...", "inputSchema": {...} }] }
POST
/register
Auth: None

Self-service external-agent registration. Creates a registry record and returns a 90-day bearer token for universal MCP access.

Request Body
agentIdstringrequiredLowercase agent identifier using letters, numbers, and hyphens only
namestringrequiredHuman-readable agent name
descriptionstringOptional summary of what the agent does
ownerEmailstringOptional owner contact email
allowedDomainsstring[]Optional outbound domain allowlist. Empty means all domains allowed.
allowedToolsstring[]Optional tool permission list. Defaults to all built-in agentos.* primitives.
Response
{ "agentId": "external-agent", "token": "eyJ...", "expiresIn": "90d", "allowedDomains": ["httpbin.org"], "allowedTools": ["agentos.net_http_get"], "mcpEndpoint": "https://agentos-app.vercel.app/mcp", "toolsEndpoint": "https://agentos-app.vercel.app/tools" }
GET
/agent/me
Auth: Browser Session or Bearer (Agent)

Return the current external-agent registration details without reissuing the token.

Response
{ "agentId": "external-agent", "name": "My Agent", "status": "active", "allowedDomains": ["httpbin.org"], "allowedTools": ["agentos.net_http_get"], "totalCalls": 1, "lastActiveAt": "...", "createdAt": "...", "mcpEndpoint": "https://agentos-app.vercel.app/mcp", "toolsEndpoint": "https://agentos-app.vercel.app/tools" }
POST
/api/signup
Auth: None

Create an agent account, start a secure browser session, and return a 90-day bearer token for external use.

Request Body
emailstringrequiredValid email address
passwordstringrequiredAt least 8 characters
agentNamestringOptional display name for the new agent
Response
{ "success": true, "credentials": { "agentId": "agent_...", "bearerToken": "eyJ...", "apiKey": "eyJ...", "expiresIn": "90 days" } }
POST
/api/signin
Auth: None

Authenticate an existing account, refresh the secure browser session, and return a fresh external bearer token.

Request Body
emailstringrequiredAccount email address
passwordstringrequiredExisting account password
Response
{ "success": true, "credentials": { "agentId": "agent_...", "bearerToken": "eyJ...", "apiKey": "eyJ...", "agentName": "My Agent", "expiresIn": "90 days" } }
GET
/api/session
Auth: Browser Session or Bearer (Agent)

Return the current authenticated browser session or bearer-backed session state.

Response
{ "authenticated": true, "session": { "agentId": "agent_...", "agentName": "My Agent", "expiresAt": "..." } }
DELETE
/api/session
Auth: Browser Session or Bearer (Agent)

Clear the current browser session cookie.

Response
{ "success": true }
POST
/api/session/token
Auth: Browser Session or Bearer (Agent)

Mint a fresh bearer token for external API, SDK, or CLI use while keeping the browser session active.

Response
{ "success": true, "credentials": { "agentId": "agent_...", "bearerToken": "eyJ...", "apiKey": "eyJ...", "expiresIn": "90 days" } }
GET
/api/social/platforms
Auth: Browser Session or Bearer (Agent)

Optional example integration route: return the social-platform catalog, including which connectors are live and how many X accounts are currently connected.

Response
{ "platforms": [{ "id": "x", "status": "live", "connectorReady": true, "connectedCount": 1 }, { "id": "facebook", "status": "scaffolded", "connectorReady": false, "connectedCount": 0 }] }
POST
/api/x/connect
Auth: Browser Session or Bearer (Agent)

Optional example integration route: start the X OAuth authorization flow for the current operator session.

Request Body
redirectTostringOptional in-app path to return to after OAuth completes
Response
{ "authorizationUrl": "https://x.com/i/oauth2/authorize?..." }
GET
/api/x/accounts
Auth: Browser Session or Bearer (Agent)

Optional example integration route: list connected X accounts visible to the current operator, including owner and child-agent mapping.

Response
{ "accounts": [{ "id": "...", "username": "brand_handle", "child_agent_id": "x_brand_...", "status": "active" }] }
GET
/api/x/drafts
Auth: Browser Session or Bearer (Agent)

Optional example integration route: list X drafts awaiting review, including guardrail status, reasons, and approval state.

Response
{ "drafts": [{ "id": "...", "kind": "post", "approval_status": "required", "guardrail_status": "review", "guardrail_reasons": ["..."], "similarity_score": 0.14 }] }
GET
/api/x/queue
Auth: Browser Session or Bearer (Agent)

Optional example integration route: list queued, published, failed, or canceled X publish items for the authenticated operator.

Response
{ "queue": [{ "id": "...", "publish_status": "queued", "scheduled_for": "...", "account": { "username": "brand_handle" } }] }
POST
/api/x/publish
Auth: Browser Session or Bearer (Agent)

Optional example integration route: publish an approved X draft immediately or force a queued publish item to run now.

Request Body
draftIdstringDraft UUID to publish immediately
queueIdstringQueue UUID to publish immediately
Response
{ "draftId": "...", "queueId": "...", "postId": "...", "publishedAt": "..." }
POST
/api/forgot-password
Auth: None

Request a password reset. Production returns a generic success response even when the account does not exist.

Request Body
emailstringrequiredAccount email address
Response
{ "success": true }
POST
/api/forgot-password/confirm
Auth: None

Confirm a password reset with the emailed token and a new password.

Request Body
emailstringrequiredAccount email address
tokenstringrequiredReset token from the password reset link
newPasswordstringrequiredAt least 8 characters
Response
{ "success": true }
POST
/mcp
Auth: Browser Session or Bearer (Agent)

Execute any Agent OS primitive, runtime function, installed skill capability, or external MCP tool through the universal MCP router.

Request Body
toolstringrequiredUniversal tool name such as agentos.mem_set or mcp.github.create_issue
inputobjectNormalized tool arguments
argumentsobjectAlias for input
serverstringOptional MCP server hint for legacy clients
Response
{ "success": true, "result": <tool-specific result> }
POST
/api/studio/command
Auth: Browser Session or Bearer (Agent)

Run a Studio command. Mutating commands return a preview first and require a confirmation token on the second request.

Request Body
commandstringrequiredStrict Studio command string
confirmTokenstringShort-lived token returned by preview responses
advancedModebooleanMust be true for advanced sandbox commands
Response
{ "kind": "help|preview|result|error", "summary": "...", "result": {...}, "snippet": "..." }
GET
/api/skills
Auth: None

Browse published marketplace skills. Supports category, search, sort, page, limit, and author query params.

Response
{ "skills": [...], "pagination": { "page": 1, "limit": 50, "total": 54 } }
POST
/api/skills/install
Auth: Browser Session or Bearer (Agent)

Install a published skill for the authenticated agent.

Request Body
skill_idstringrequiredSkill UUID from the marketplace listing
Response
{ "success": true, "installation": { "id": "...", "installed_at": "..." } }
GET
/api/skills/installed
Auth: Browser Session or Bearer (Agent)

List installed skills for the authenticated agent.

Response
{ "installed_skills": [{ "id": "...", "installed_at": "...", "skill": {...} }] }
POST
/api/skills/use
Auth: Browser Session or Bearer (Agent)

Run a capability from an installed skill in the hardened skill runtime.

Request Body
skill_slugstringrequiredInstalled skill slug
capabilitystringrequiredCapability method name
paramsobjectCapability input payload
Response
{ "success": true, "result": <any>, "execution_time_ms": 12 }
GET
/api/ops/metrics
Auth: None

Return public aggregate ops coverage and health metrics. Detailed internals are only returned to ops-admin callers.

Response
{ "summary": {...}, "settings": {...}, "metrics": {...}, "requiresAuthForDetails": true }
GET
/api/ops/crew
Auth: None

Return the public crew coverage summary. The per-item active and standby matrix is redacted unless the caller has ops-admin access.

Response
{ "summary": {...}, "settings": {...}, "coverage": {...}, "requiresAuthForDetails": true }
POST
/api/ops/crew/bootstrap
Auth: Browser Session or Bearer (Ops Admin)

Idempotently restore active and standby coverage across the canonical feature catalog.

Response
{ "success": true, "result": {...} }
POST
/api/ops/crew/failover
Auth: Browser Session or Bearer (Ops Admin)

Force a failover for a specific feature or runtime-function slot.

Request Body
featureSlugstringrequiredCatalog slug for the target feature or function
reasonstringOptional operator-supplied failover reason
Response
{ "success": true, "result": {...} }
POST
/api/ops/crew/cron
Auth: Bearer (Cron/Admin)

Run the autonomous crew cron cycle manually using the cron secret or admin token.

Response
{ "success": true, "result": {...} }