API Reference

The ArchAgent API is a single Express app deployed as a Firebase Cloud Functions v2 HTTP function. All endpoints are prefixed with /api/.

OpenAPI Specification

A machine-readable OpenAPI 3.1 spec is available in docs-legacy/openapi.yaml. It covers auth, billing, profile, agents, and copilot endpoints with full request/response schemas.

Base URLs

Environment	URL
Dev	https://amlcloud-monitor-dev.web.app/api/
Prod	https://agent-coder-ai.web.app/api/

Authentication

Two authentication methods are supported:

Bearer Token (Firebase ID Token)

Authorization: Bearer <firebase-id-token>

Obtained by logging in via the web dashboard or CLI (archagent login). Tokens expire in ~1 hour.

API Key

X-API-Key: <archagent-api-key>

Generated via POST /api/profile/api-key. Suitable for scripts and CI integrations.

Rate Limits

• Default: 60 requests/minute per IP
• Chat/Copilot: 20 requests/minute per IP (higher cost due to LLM inference)

Route Overview

Route File	Base Path	Auth	Purpose
auth-api.ts	/api/auth	None	Token refresh, exchange, verify
billing.ts	/api/billing	Bearer/API key	Stripe checkout, portal, subscription status
profile.ts	/api/profile	Bearer/API key	User profile, API keys, settings, channel apps, integration apps
admin.ts	/api/admin	Bearer (admin)	Platform stats, config
instances.ts	/api/instances	Bearer/API key + subscription	Workspace CRUD, start/stop, logs, approvals
agents.ts	/api/agents	Bearer/API key + subscription	Agent CRUD, chat, channels, integrations, memory, tasks
chat.ts	/api/chat	Bearer/API key + subscription	Instance copilot
channel-test.ts	/api/channel-test	Bearer/API key + subscription	Test chat on channel
integration-test.ts	/api/integration-test	Bearer/API key + subscription	Test integration tokens

Instances (Workspaces)

GET /api/instances

List all instances owned by the authenticated user.

Response: { instances: Instance[] }

POST /api/instances

Create a new workspace instance.

Body:

Field	Type	Required	Description
name	string	Yes	Workspace name
agentType	string	No	Initial agent runtime type
agentConfig	object	No	Initial agent configuration

Response: { instanceId, cloudRunService, ... }

GET /api/instances/:id

Get instance details including status and Cloud Run service info.

POST /api/instances/:id/start

Start a stopped instance.

POST /api/instances/:id/stop

Stop a running instance.

DELETE /api/instances/:id

Destroy an instance and its Cloud Run service.

GET /api/instances/:id/logs/deploy

Get Cloud Run deployment logs (last 200 entries).

POST /api/instances/:id/approvals/:approvalId/resolve

Resolve an execution approval request.

Body: { decision: "approved" | "rejected", response?: string }

Agents

GET /api/agents

List all agents owned by the authenticated user.

Response: { agents: Agent[] } -- config is sanitized (secrets stripped).

POST /api/agents

Create a new agent within a workspace.

Body:

Field	Type	Required	Description
instanceId	string	Yes	Parent workspace ID
agentType	string	Yes	openclaw, mastra, or custom
config	object	Yes	Must include config.name
role	string	No	Agent role description
goal	string	No	Agent goal
capabilities	string	No	Agent capabilities

Response: { agentId, ... }

GET /api/agents/:id

Get agent details with sanitized config.

PUT /api/agents/:id

Update agent config, role, goal, or capabilities.

DELETE /api/agents/:id

Delete an agent and its subcollections.

POST /api/agents/:id/status

Set agent status.

Body: { status: "running" | "paused" | "stopped" }

Agent Messages

GET /api/agents/:id/messages

Get recent messages (default 50, max 200).

Query: ?limit=50

Response: { messages: [{ id, role, content, status, channel, timestamp }] }

POST /api/agents/:id/messages

Send a message to a running agent. The message is queued in Firestore and picked up by the agent loop.

Body: { message: string }

Requires: Instance must be in running or provisioning status.

Agent Channels

GET /api/agents/:id/channel

Get channel connection status.

Response: { connected, channel, appId, channelMode, channelStatus, isHealthy }

POST /api/agents/:id/channel

Connect an agent to a channel app. Validates the bot token against the platform API.

Body: { appId: string, channelMode?: "mention" | "all" }

DELETE /api/agents/:id/channel

Disconnect agent from its channel.

Agent Integrations

GET /api/agents/:id/integration

Get integration connection status and policy.

Response: { connected, integration, integrationAppId, policy, integrationStatus }

POST /api/agents/:id/integration

Connect an agent to an integration (e.g., GitHub). Generates a per-agent proxy secret.

Body: { appId: string, policy?: PolicyPreset | { rules: PolicyRule[] } }

Policy presets: read-only, docs-only, full-access.

PUT /api/agents/:id/integration

Update the integration access policy.

Body: { policy: { rules: PolicyRule[] } }

DELETE /api/agents/:id/integration

Disconnect integration and clear secrets.

POST /api/agents/:id/integration/test

Test a request against the agent's integration policy without executing it.

Body: { method: string, path: string }

Response: { method, path, filePath, allowed, reason, matchedRule }

GET /api/agents/:id/integration/audit

Get integration proxy audit log.

Query: ?limit=50 (max 200)

Response: { entries: [{ id, method, path, filePath, allowed, reason, timestamp }] }

Agent Memory

GET /api/agents/:id/memory

Get all memory entries for an agent.

PUT /api/agents/:id/memory

Create or update a memory entry.

Body:

Field	Type	Required	Description
type	string	Yes	identity, user_relationship, task, knowledge, or team_shared
key	string	Yes	Memory key
content	string	Yes	Memory content
metadata	object	No	Additional metadata

DELETE /api/agents/:id/memory/:entryId

Delete a memory entry.

Agent Tasks

GET /api/agents/:id/tasks

List all tasks for an agent, ordered by creation time.

POST /api/agents/:id/tasks

Create a new task.

Body: { title: string, description?: string }

PUT /api/agents/:id/tasks/:taskId

Update a task.

Body: { title?, description?, status? }

DELETE /api/agents/:id/tasks/:taskId

Delete a task.

Copilot

POST /api/chat

Send a message to the instance copilot. Uses Anthropic tool-calling to manage agents, credentials, and troubleshooting.

Body:

Field	Type	Required	Description
message	string	Yes	User message
conversationId	string	No	For multi-turn conversations
agentId	string	No	Focus on a specific agent

Response: { conversationId, response }

POST /api/agents/:id/copilot

Send a message to an agent-specific copilot. Has access to agent config, tasks, memory, and runtime-specific tools.

Body: { message: string, conversationId?: string }

Auth

POST /api/auth/refresh

Refresh a Firebase ID token.

Body: { refreshToken: string }

POST /api/auth/exchange

Exchange a Firebase ID token for a custom token (used by CLI device code flow).

Body: { idToken: string }

POST /api/auth/verify

Verify whether an ID token is valid.

Body: { idToken: string }

Profile

GET /api/profile

Get user profile and saved API keys (masked).

PUT /api/profile/api-keys

Save a provider API key.

Body: { provider: "anthropic" | "openai" | "google" | "ollama", key: string, label?: string, makeDefault?: boolean }

DELETE /api/profile/api-keys/:provider/:keyId

Delete a saved API key.

POST /api/profile/api-key

Generate an ArchAgent API key. The key is returned only once.

GET /api/profile/settings

Get account settings.

PUT /api/profile/settings

Update account settings (displayName, defaultModelProvider, defaultChannel, timezone, notifications).

Billing

POST /api/billing/checkout

Create a Stripe Checkout session.

Body: { priceId: string }

POST /api/billing/portal

Create a Stripe billing portal session.

POST /api/billing/subscription

Get current subscription and trial access state.

Error Responses

All errors follow a consistent format:

{ "error": "Human-readable error message" }

Common HTTP status codes:

• 400 -- Bad request (missing/invalid fields)
• 401 -- Unauthorized (missing or invalid auth)
• 402 -- Payment required (no API credits)
• 404 -- Resource not found
• 429 -- Rate limited
• 500 -- Internal server error