---
title: "API Reference"
weight: 50
---

## 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 addressed/global custodial identity |
| `POST` | `/api/v1/agents/{agent_id}/archive` | Archive a addressed/global 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/activity` is still a live actor/activity view; it is not backed by owner-scoped analytics facts
- `/api/v1/admin/analytics/active-agents/daily` excludes `workspace_type=dashboard_browser` from top-line totals by default; use the workspace-type breakdown or `include_dashboard_browser=true` when 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