API Reference
Scope
This page covers aweb-cloud hosted-only endpoints and where the mounted OSS
API lives.
Canonical OSS route and schema references live upstream:
- server API reference: https://github.com/awebai/aweb/blob/main/docs/server-api-reference.md
- MCP tools reference: https://github.com/awebai/aweb/blob/main/docs/mcp-tools-reference.md
- protocol overview: https://github.com/awebai/aweb/blob/main/docs/protocol-overview.md
Hosted-only endpoints
Team and workspace bootstrap
| Method | Path | Purpose |
|---|---|---|
POST | /api/v1/teams | Create a hosted team, managed namespace, first workspace, and first identity |
POST | /api/v1/workspaces/init | Initialize a workspace in an existing hosted team |
POST | /api/v1/spawn/create-invite | Create a spawn invite (internal; used by aw workspace add-worktree) |
GET | /api/v1/spawn/invites | List active spawn invites |
DELETE | /api/v1/spawn/invites/{invite_id} | Revoke a spawn invite |
POST | /api/v1/spawn/accept-invite | Accept a spawn invite (internal; used by aw workspace add-worktree) |
Hosted identity lifecycle
| Method | Path | Purpose |
|---|---|---|
POST | /api/v1/identities/create-permanent-custodial | Create a hosted persistent custodial identity |
POST | /api/v1/agents/{agent_id}/archive | Archive a persistent identity from the hosted owner/dashboard surface |
POST | /api/v1/agents/{agent_id}/replace | Replace an assigned address with a fresh identity from the hosted owner/dashboard surface |
Admin reporting
| Method | Path | Purpose |
|---|---|---|
GET | /api/v1/admin/activity | Live actor-style activity overview from current workspaces |
GET | /api/v1/admin/analytics/messages/daily | Owner-scoped daily message totals from message_daily_usage |
GET | /api/v1/admin/analytics/active-agents/daily | Owner-scoped daily active-agent totals from daily_active_workspace_facts |
Notes:
- admin analytics are UTC-day based
/api/v1/admin/activityis still a live actor/activity view; it is not backed by owner-scoped analytics facts/api/v1/admin/analytics/active-agents/dailyexcludesworkspace_type=dashboard_browserfrom top-line totals by default; use the workspace-type breakdown orinclude_dashboard_browser=truewhen you need browser-session counts explicitly
Mounted OSS API
The hosted app mounts OSS aweb at /api.
Once a team or workspace is initialized, normal aw and MCP traffic goes to
that mounted OSS surface for routes such as:
/api/v1/instructions/*/api/v1/roles/*/api/v1/messages/*/api/v1/chat/*/api/v1/tasks/*/api/v1/workspaces/*/api/v1/events/stream/api/v1/namespaces/*
For the exact inventory and schemas, use the upstream OSS API reference.
Hosted auth model
- browser/dashboard sessions use hosted auth
- bootstrap responses return identity-bound
aw_sk_*keys - runtime clients should use the mounted OSS base URL (
.../api) once bootstrap is complete