> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meshagent.com/llms.txt
> Use this file to discover all available pages before exploring further.
# REST API
The MeshAgent REST API exposes administrative and lifecycle operations for projects, rooms, users, permissions, services, storage, billing, sessions, and project settings.
The REST API can be used for:
* **Projects & Rooms**: Create projects, manage rooms, and mint room connection tokens
* **Resource policies**: Manage access to rooms, repositories, feeds, service accounts, and other project resources
* **Project storage**: Upload/download project files by path
* **Services**: Manage project-wide and room-scoped services
* **Secrets**: Manage user-owned and service-account-owned credentials
* **Project settings & integrations**: Update project settings, model routing configuration, webhooks, API keys, and OAuth clients
* **Shares**: Create share links for Rooms
* **Mailboxes**: Manage mailboxes mapped to Rooms
* **Operations**: Understand sessions (events/spans/metrics) and create/manage scheduled tasks
* **Billing & usage**: Get insight into your account balance, transactions, subscriptions, and usage reporting
For room-specific operations such as working with agents, datasets, or queues use the [Room APIs](../room_api/overview).
## Getting started
To call the MeshAgent REST API, authenticate with a project API key. The simplest path is:
1. **Set up a Python environment** with the MeshAgent SDK installed (requires Python 3.13)
2. **Use the MeshAgent CLI to create and activate an API key**, then store it in a `.env` file
3. **Load the key from `.env`** and create a `Meshagent()` client
> MeshAgent requires **Python 3.13**. We recommend using `uv`, which manages Python versions, virtual environments, and dependencies automatically. To learn more about `uv` see the [Machine Setup Guide for Python](../reference/machine_setup)
### 1. Set up the SDK
Install uv, then create a project and virtual environment with MeshAgent installed:
```bash theme={null}
# Install uv if needed
curl -LsSf https://astral.sh/uv/install.sh | sh
# Create and navigate to your project directory
mkdir meshagent-project && cd meshagent-project
# Initialize the project and pin Python 3.13
uv init --python 3.13
# Create virtual environment (uv will download python 3.13 if not already installed on your machine)
uv venv --python 3.13
# Install MeshAgent SDK and other dependencies
uv add "meshagent[all]" python-dotenv
```
Activate your virtual environment:
```bash macOS/Linux theme={null}
source .venv/bin/activate
```
```bash Windows theme={null}
.venv\Scripts\activate
```
> **Note**: You'll know your virtual environment is active when you see `(.venv)` at the start of your terminal prompt. When the environment is activated, you can run commands directly (e.g. `meshagent setup` or `python main.py`). If the environment is not activated, prefix commands with `uv run` (e.g. `uv run meshagent setup` or `uv run python main.py`).
To upgrade dependencies later, run:
```bash theme={null}
uv lock --upgrade
uv sync
```
### 2. Create a new API key and store it in `.env`
```bash theme={null}
# Authenticate to MeshAgent if not already signed in
meshagent setup # this will also print your project ID
# Get your current project ID
meshagent project list # the project with the * next to it is the current active project
# Create an API Key
meshagent api-key create my-key --activate
```
Create a `.env` file in your project and paste the key value:
```bash theme={null}
MESHAGENT_API_KEY=your-api-key-value
MESHAGENT_PROJECT_ID=your-project-id
```
### 3. Create a MeshAgent client
Now we can create the MeshAgent client and use it to do something like list all the rooms in our project.
```python Python theme={null}
import asyncio
import os
from dotenv import load_dotenv
from meshagent.api.client import Meshagent
load_dotenv()
api_key = os.getenv("MESHAGENT_API_KEY")
project_id = os.getenv("MESHAGENT_PROJECT_ID")
if not api_key:
raise RuntimeError("MESHAGENT_API_KEY is not set")
if not project_id:
raise RuntimeError("MESHAGENT_PROJECT_ID is not set")
async def main():
client = Meshagent(token=api_key)
try:
rooms = await client.list_rooms(project_id=project_id)
print(rooms)
finally:
await client.close()
asyncio.run(main())
```
### Client configuration
The `Meshagent()` client accepts a `base_url` and `token`.
* `base_url`: defaults to `MESHAGENT_API_URL` (defaults to [https://api.meshagent.com](https://api.meshagent.com))
* `token`: a bearer token for the Authorization header.
* This will default to `MESHAGENT_API_KEY`. API keys are scoped to a specific project, so most REST calls will also require a `project_id`.
REST calls raise `meshagent.api.RoomException` on non-2xx responses. Many methods also validate responses with typed models, while others still return plain JSON dicts or lists directly.
## Projects, Rooms, and managed agents
Create and manage projects, Rooms, and managed agent identities. Room and agent connection methods return signed connection information for the target runtime.
Project settings are independent documents named `openai`, `anthropic`, `otel`, `admission`, `room`, and `room_roles`. They are stored in project storage under `.meshagent/settings/` as one JSON file per group (for example, `.meshagent/settings/openai.json`). The REST path and storage filename for `room_roles` use `room-roles`; SDK clients translate that name automatically. A missing document is unconfigured and is not read from the legacy project settings field or any database fallback.
| SDK method | HTTP route | What it does |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `create_project(name)` | `POST /accounts/projects` | Create a project. |
| `list_projects()` | `GET /accounts/projects` | List projects you can access. |
| `get_project(project_id)` | `GET /accounts/projects/{project_id}` | Fetch one project. |
| `get_project_settings_document(project_id, name)` | `GET /accounts/projects/{project_id}/settings/{name}` | Fetch one settings document. |
| `set_project_settings_document(project_id, name, document)` | `PUT /accounts/projects/{project_id}/settings/{name}` | Set one settings document. |
| `delete_project_settings_document(project_id, name)` | `DELETE /accounts/projects/{project_id}/settings/{name}` | Revert one settings document to its unconfigured/default state. |
| `get_project_status(project_id)` | `GET /accounts/projects/{project_id}/status` | Check whether the project is enabled. |
| `get_project_role(project_id)` | `GET /accounts/projects/{project_id}/role` | Get your role in the project. |
| `add_user_to_project(project_id, user_id, …)` | `POST /accounts/projects/{project_id}/users` | Add a user with project roles such as `admin`, `developer`, `room_creator`, `agent_creator`, or `llm_proxy_user`. |
| `remove_user_from_project(project_id, user_id)` | `DELETE /accounts/projects/{project_id}/users/{user_id}` | Remove a user from the project. |
| `get_users_in_project(project_id)` | `GET /accounts/projects/{project_id}/users` | List users in the project. |
| `get_user_profile(user_id)` | `GET /accounts/profiles/{user_id}` | Fetch a user profile. |
| `update_user_profile(user_id, first_name, last_name)` | `PUT /accounts/profiles/{user_id}` | Update basic profile fields. |
| `create_room(project_id, name, metadata?, permissions?, if_not_exists?)` | `POST /accounts/projects/{project_id}/rooms` | Create a room (supports metadata + optional initial permissions). |
| `list_rooms(project_id, limit?, offset?, order_by?)` | `GET /accounts/projects/{project_id}/rooms` | List rooms with pagination. |
| `get_room(project_id, room_name)` | `GET /accounts/projects/{project_id}/rooms/{room_name}` | Fetch a room by name. |
| `get_room_status(project_id, room_name)` | `GET /accounts/projects/{project_id}/rooms/{room_name}/status` | Return current control-plane allocation state (`Allocated` or `Unallocated`), including allocation time and running duration when active; this is not lifecycle history or service health. |
| `list_room_events(project_id, room_name, limit?)` | `GET /accounts/projects/{project_id}/rooms/{room_name}/events` | List recent historical lifecycle transitions across the room's sessions, including allocation, startup, shutdown, and startup failures; this is not current state. |
| `update_room(project_id, room_id, name, metadata?)` | `PUT /accounts/projects/{project_id}/rooms/{room_id}` | Rename/update a room. |
| `delete_room(project_id, room_id)` | `DELETE /accounts/projects/{project_id}/rooms/{room_id}` | Delete a room. |
| `connect_room(project_id, room_name)` | `POST /accounts/projects/{project_id}/rooms/{room_name}/connect` | Return `RoomConnectionInfo` (`jwt`, `room_url`, etc.). |
| `create_agent(project_id, configuration, if_not_exists?, permissions?)` | `POST /accounts/projects/{project_id}/agents` | Create a managed agent identity. |
| `get_agent(project_id, name)` | `GET /accounts/projects/{project_id}/agents/{agent_name}` | Fetch a managed agent by name. |
| `update_agent(project_id, agent_id, configuration)` | `PUT /accounts/projects/{project_id}/agents/{agent_id}` | Update a managed agent. |
| `delete_agent(project_id, agent_id)` | `DELETE /accounts/projects/{project_id}/agents/{agent_id}` | Delete a managed agent. |
| `connect_agent(project_id, agent)` | `POST /accounts/projects/{project_id}/agents/{agent_name}/connect` | Return `AgentConnectionInfo`. |
## Resource policies
Managed agent resource policies are not supported. Use service-account `run_as` configuration for agent access, and use resource policies for supported resource types.
| SDK method | HTTP route | What it does |
| ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------- |
| `grant_resource_policy(project_id, resource_type, resource_id, subject, roles)` | `POST /accounts/projects/{project_id}/policies/resources/{resource_type}/{resource_id}` | Grant roles on supported resource types. |
| `revoke_resource_policy(project_id, resource_type, resource_id, subject, roles?)` | `DELETE /accounts/projects/{project_id}/policies/resources/{resource_type}/{resource_id}` | Revoke resource-policy roles. |
| `get_resource_policy(project_id, resource_type, resource_id, page_size?, continuation_token?)` | `GET /accounts/projects/{project_id}/policies/resources/{resource_type}/{resource_id}` | List direct resource-policy bindings. |
## Project Storage
MeshAgent allows you to use both project wide and room specific storage. For room-scoped storage see the [Storage API](../room_api/storage) documentation.
| SDK method | HTTP route | What it does |
| -------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------ |
| `upload(project_id, path, data)` | `POST /projects/{project_id}/storage/upload?path=…` | Upload raw bytes (`Content-Type: application/octet-stream`). |
| `download(project_id, path)` | `GET /projects/{project_id}/storage/download?path=…` | Download raw bytes. |
## Services
Create and manage project and room services. Project services are available to all rooms in your project while room services are scoped to a specific room.
### Project Services
| SDK method | HTTP route | What it does |
| ------------------------------------------------------------------------ | -------------------------------------------------------------- | ------------------------------------------------- |
| `create_service(project_id, service)` | `POST /accounts/projects/{project_id}/services` | Create a project-level service. |
| `create_service_from_template(project_id, template, values)` | `POST /accounts/projects/{project_id}/services` | Create a project service from a template payload. |
| `list_services(project_id)` | `GET /accounts/projects/{project_id}/services` | List project services. |
| `get_service(project_id, service_id)` | `GET /accounts/projects/{project_id}/services/{service_id}` | Fetch a service spec. |
| `update_service(project_id, service_id, service)` | `PUT /accounts/projects/{project_id}/services/{service_id}` | Update a service. |
| `update_service_from_template(project_id, service_id, template, values)` | `PUT /accounts/projects/{project_id}/services/{service_id}` | Update a service from a template payload. |
| `delete_service(project_id, service_id)` | `DELETE /accounts/projects/{project_id}/services/{service_id}` | Delete a service. |
## Room Services
| SDK method | HTTP route | What it does |
| ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------- |
| `create_room_service(project_id, room_name, service)` | `POST /accounts/projects/{project_id}/rooms/{room_name}/services` | Create a room-scoped service. |
| `create_room_service_from_template(project_id, room_name, template, values)` | `POST /accounts/projects/{project_id}/rooms/{room_name}/services` | Create a room service from a template payload. |
| `list_room_services(project_id, room_name)` | `GET /accounts/projects/{project_id}/rooms/{room_name}/services` | List room services. |
| `get_room_service(project_id, room_name, service_id)` | `GET /accounts/projects/{project_id}/rooms/{room_name}/services/{service_id}` | Fetch a room service spec. |
| `update_room_service(project_id, room_name, service_id, service)` | `PUT /accounts/projects/{project_id}/rooms/{room_name}/services/{service_id}` | Update a room service. |
| `update_room_service_from_template(project_id, room_name, service_id, template, values)` | `PUT /accounts/projects/{project_id}/rooms/{room_name}/services/{service_id}` | Update a room service from a template payload. |
| `delete_room_service(project_id, room_name, service_id)` | `DELETE /accounts/projects/{project_id}/rooms/{room_name}/services/{service_id}` | Delete a room service. |
## Secrets
Secret workflows use user-owned and service-account-owned secrets; see [Secrets and Credentials](../secrets/overview).
## Routes
Create and manage project routes that map domains to rooms, ports, and route specs.
| SDK method | HTTP route | What it does |
| ------------------------------------------------------------------- | -------------------------------------------------------------- | ----------------------- |
| `create_route(project_id, spec? or domain, room_name, port)` | `POST /accounts/projects/{project_id}/routes` | Create a route. |
| `update_route(project_id, domain, spec? or room_name, port)` | `PUT /accounts/projects/{project_id}/routes/{domain}` | Update a route. |
| `get_route(project_id, domain)` | `GET /accounts/projects/{project_id}/routes/{domain}` | Fetch a route. |
| `list_routes(project_id, count?, offset?, filter?)` | `GET /accounts/projects/{project_id}/routes` | List project routes. |
| `list_room_routes(project_id, room_name, count?, offset?, filter?)` | `GET /accounts/projects/{project_id}/rooms/{room_name}/routes` | List routes for a room. |
| `delete_route(project_id, domain)` | `DELETE /accounts/projects/{project_id}/routes/{domain}` | Delete a route. |
## Feeds and subscriptions
Create project feeds, publish messages, and fan them out into room storage through subscriptions.
| SDK method | HTTP route | What it does |
| --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------- |
| `create_feed(project_id, name, description?, visibility?, paused?, annotations?, message_schema?)` | `POST /accounts/projects/{project_id}/feeds` | Create a feed. |
| `update_feed(project_id, feed_id, name, description?, paused?, annotations?, message_schema?)` | `PUT /accounts/projects/{project_id}/feeds/{feed_id}` | Update a feed. |
| `get_feed(project_id, feed_id)` | `GET /accounts/projects/{project_id}/feeds/{feed_id}` | Fetch a feed. |
| `list_feeds(project_id, count?, offset?, filter?)` | `GET /accounts/projects/{project_id}/feeds` | List project feeds. |
| `list_room_feeds(project_id, room_name, count?, offset?, filter?)` | `GET /accounts/projects/{project_id}/rooms/{room_name}/feeds` | List feeds visible to a room. |
| `delete_feed(project_id, feed_id)` | `DELETE /accounts/projects/{project_id}/feeds/{feed_id}` | Delete a feed. |
| `publish_feed_message(project_id, feed_id, message)` | `POST /accounts/projects/{project_id}/feeds/{feed_id}/messages` | Publish one message. |
| `publish_feed_batch(project_id, feed_id, messages)` | `POST /accounts/projects/{project_id}/feeds/{feed_id}/messages/batch` | Publish a batch. |
| `create_feed_subscription(project_id, feed_id, room, path, filename_datetime_format?, annotations?)` | `POST /accounts/projects/{project_id}/feeds/{feed_id}/subscriptions` | Create a subscription. |
| `update_feed_subscription(project_id, feed_id, subscription_id, filename_datetime_format?, annotations?)` | `PUT /accounts/projects/{project_id}/feeds/{feed_id}/subscriptions/{subscription_id}` | Update a subscription. |
| `get_feed_subscription(project_id, feed_id, subscription_id)` | `GET /accounts/projects/{project_id}/feeds/{feed_id}/subscriptions/{subscription_id}` | Fetch a subscription. |
| `list_feed_subscriptions(project_id, feed_id)` | `GET /accounts/projects/{project_id}/feeds/{feed_id}/subscriptions` | List subscriptions. |
| `delete_feed_subscription(project_id, feed_id, subscription_id)` | `DELETE /accounts/projects/{project_id}/feeds/{feed_id}/subscriptions/{subscription_id}` | Delete a subscription. |
## LLM loggers
Create project LLM loggers that copy LLM proxy events into destination feeds. Use these when you need a feed-backed stream of LLM request metadata for processing or analysis.
| SDK method | HTTP route | What it does |
| --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | --------------------- |
| `create_llm_logger(project_id, destination_feed_id, filter_expression, paused?, annotations?)` | `POST /accounts/projects/{project_id}/llm-loggers` | Create an LLM logger. |
| `update_llm_logger(project_id, logger_id, destination_feed_id, filter_expression, paused?, annotations?)` | `PUT /accounts/projects/{project_id}/llm-loggers/{logger_id}` | Update an LLM logger. |
| `get_llm_logger(project_id, logger_id)` | `GET /accounts/projects/{project_id}/llm-loggers/{logger_id}` | Fetch an LLM logger. |
| `list_llm_loggers(project_id)` | `GET /accounts/projects/{project_id}/llm-loggers` | List LLM loggers. |
| `delete_llm_logger(project_id, logger_id)` | `DELETE /accounts/projects/{project_id}/llm-loggers/{logger_id}` | Delete an LLM logger. |
## Registries
Create and manage project-owned image repositories.
| SDK method | HTTP route | What it does |
| ------------------------------------------------------------- | ------------------------------------------------------------------------- | ---------------------------- |
| `create_repository(project_id, repository)` | `POST /accounts/projects/{project_id}/repositories` | Create a project repository. |
| `update_repository(project_id, repository_id, repository)` | `PUT /accounts/projects/{project_id}/repositories/{repository_id}` | Update a repository. |
| `get_repository(project_id, repository_id)` | `GET /accounts/projects/{project_id}/repositories/{repository_id}` | Fetch a repository. |
| `list_repositories(project_id)` | `GET /accounts/projects/{project_id}/repositories` | List repositories. |
| `delete_repository(project_id, repository_id)` | `DELETE /accounts/projects/{project_id}/repositories/{repository_id}` | Delete a repository. |
| `create_repository_token(project_id, repository_id, request)` | `POST /accounts/projects/{project_id}/repositories/{repository_id}/token` | Create a repository token. |
## Webhooks
| SDK method | HTTP route | What it does |
| ------------------------------------------- | -------------------------------------------------------------- | ----------------- |
| `create_webhook(project_id, …)` | `POST /accounts/projects/{project_id}/webhooks` | Create a webhook. |
| `list_webhooks(project_id)` | `GET /accounts/projects/{project_id}/webhooks` | List webhooks. |
| `update_webhook(project_id, webhook_id, …)` | `PUT /accounts/projects/{project_id}/webhooks/{webhook_id}` | Update a webhook. |
| `delete_webhook(project_id, webhook_id)` | `DELETE /accounts/projects/{project_id}/webhooks/{webhook_id}` | Delete a webhook. |
## API Keys
| SDK method | HTTP route | What it does |
| ----------------------------------------------- | ------------------------------------------------------ | ----------------------------------------- |
| `create_api_key(project_id, name, description)` | `POST /accounts/projects/{project_id}/api-keys` | Issue a new API key (returns value once). |
| `list_api_keys(project_id)` | `GET /accounts/projects/{project_id}/api-keys` | List keys (does not list key value). |
| `delete_api_key(project_id, id)` | `DELETE /accounts/projects/{project_id}/api-keys/{id}` | Revoke a key. |
## OAuth clients
Manage OAuth Clients for connections with other services.
| SDK method | HTTP route | What it does |
| ----------------------------------------------- | ------------------------------------------------------------------ | ----------------------------------------- |
| `create_oauth_client(project_id, …)` | `POST /accounts/projects/{project_id}/oauth/clients` | Create an OAuth client (includes secret). |
| `list_oauth_clients(project_id)` | `GET /accounts/projects/{project_id}/oauth/clients` | List OAuth clients. |
| `get_oauth_client(project_id, client_id)` | `GET /accounts/projects/{project_id}/oauth/clients/{client_id}` | Fetch one client. |
| `update_oauth_client(project_id, client_id, …)` | `PUT /accounts/projects/{project_id}/oauth/clients/{client_id}` | Update a client. |
| `delete_oauth_client(project_id, client_id)` | `DELETE /accounts/projects/{project_id}/oauth/clients/{client_id}` | Delete a client. |
## External OAuth registrations
Manage project and room external OAuth registrations. These records are separate from project OAuth clients: OAuth clients let your app authenticate users through MeshAgent, while external OAuth registrations connect MeshAgent-managed integrations to external OAuth providers.
| SDK method | HTTP route | What it does |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------- |
| `create_project_external_oauth_registration(project_id, registration)` | `POST /accounts/projects/{project_id}/external-oauth` | Create a project external OAuth registration. |
| `update_project_external_oauth_registration(project_id, registration_id, registration)` | `PUT /accounts/projects/{project_id}/external-oauth/{registration_id}` | Update a project external OAuth registration. |
| `list_project_external_oauth_registrations(project_id)` | `GET /accounts/projects/{project_id}/external-oauth` | List project external OAuth registrations. |
| `delete_project_external_oauth_registration(project_id, registration_id)` | `DELETE /accounts/projects/{project_id}/external-oauth/{registration_id}` | Delete a project external OAuth registration. |
| `create_room_external_oauth_registration(project_id, room_name, registration)` | `POST /accounts/projects/{project_id}/rooms/{room_name}/external-oauth` | Create a room external OAuth registration. |
| `update_room_external_oauth_registration(project_id, room_name, registration_id, registration)` | `PUT /accounts/projects/{project_id}/rooms/{room_name}/external-oauth/{registration_id}` | Update a room external OAuth registration. |
| `list_room_external_oauth_registrations(project_id, room_name)` | `GET /accounts/projects/{project_id}/rooms/{room_name}/external-oauth` | List room external OAuth registrations. |
| `delete_room_external_oauth_registration(project_id, room_name, registration_id)` | `DELETE /accounts/projects/{project_id}/rooms/{room_name}/external-oauth/{registration_id}` | Delete a room external OAuth registration. |
## Shares
Manage share records for a project.
| SDK method | HTTP route | What it does |
| ----------------------------------------------- | ---------------------------------------------------------- | ---------------------- |
| `create_share(project_id, settings?)` | `POST /accounts/projects/{project_id}/shares` | Create a share token. |
| `list_shares(project_id)` | `GET /accounts/projects/{project_id}/shares` | List shares. |
| `update_share(project_id, share_id, settings?)` | `PUT /accounts/projects/{project_id}/shares/{share_id}` | Update share settings. |
| `delete_share(project_id, share_id)` | `DELETE /accounts/projects/{project_id}/shares/{share_id}` | Delete a share. |
## Mailboxes
Create and manage mailboxes that can be used by Agents or Rooms.
| SDK method | HTTP route | What it does |
| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| `create_mailbox(project_id, address, room, queue, public?)` | `POST /accounts/projects/{project_id}/mailboxes` | Create a mailbox mapping. |
| `list_mailboxes(project_id)` | `GET /accounts/projects/{project_id}/mailboxes` | List mailboxes. |
| `list_room_mailboxes(project_id, room_name)` | `GET /accounts/projects/{project_id}/rooms/{room_name}/mailboxes` | List mailboxes for a room. |
| `get_mailbox(project_id, address)` | `GET /accounts/projects/{project_id}/mailboxes/{address}` | Get a mailbox. |
| `update_mailbox(project_id, address, room, queue, public?)` | `PUT /accounts/projects/{project_id}/mailboxes/{address}` | Update mapping. |
| `delete_mailbox(project_id, address)` | `DELETE /accounts/projects/{project_id}/mailboxes/{address}` | Delete mapping. |
| `list_mailbox_deliveries(project_id, address, ...)` | `GET /accounts/projects/{project_id}/mailboxes/{address}/deliveries` | List recipient deliveries, ordered by `submitted_at DESC, id DESC`. |
| `get_mailbox_delivery(project_id, address, delivery_id)` | `GET /accounts/projects/{project_id}/mailboxes/{address}/deliveries/{delivery_id}` | Get current delivery status and SMTP details. |
| `list_mailbox_delivery_events(project_id, address, delivery_id, ...)` | `GET /accounts/projects/{project_id}/mailboxes/{address}/deliveries/{delivery_id}/events` | List provider events, ordered by `occurred_at ASC, id ASC`. |
Delivery routes require `mailboxes:read` plus the project
`mailbox_inventory` relation. They are not room-scoped, and the response does
not repeat the mailbox address because it is already part of the request path.
Project API keys retain project-wide access.
### Delivery status API
`GET /accounts/projects/{project_id}/mailboxes/{address}/deliveries` returns one
current delivery record per recipient. Results are newest first and the response
has the shape `{ "deliveries": [...], "total": number }`. It accepts:
| Query parameter | Description |
| --------------- | ----------------------------------------------------------------- |
| `status` | Current status: `accepted`, `deferred`, `delivered`, or `failed`. |
| `recipient` | Case-insensitive recipient substring. |
| `message_id` | Exact message ID. |
| `count` | Page size from 1 through 1000; defaults to 100. |
| `offset` | Zero-based row offset; defaults to 0. |
`GET /accounts/projects/{project_id}/mailboxes/{address}/deliveries/{delivery_id}`
returns `{ "delivery": {...} }`. The record contains the current status,
submission and recipient identifiers, status timestamps, attempt count, and
the latest available SMTP, MX host, TLS, and failure details.
`GET /accounts/projects/{project_id}/mailboxes/{address}/deliveries/{delivery_id}/events`
returns `{ "events": [...], "total": number }`. It accepts `count` and
`offset`, and returns events in chronological order. The normalized event types
are `accepted`, `temporary_failed`, `delivered`, and `permanent_failed`; their
resulting delivery statuses are `accepted`, `deferred`, `delivered`, and
`failed`, respectively. Each event includes its occurrence and receipt times,
provider event ID, resulting status, and any provider-supplied attempt, SMTP,
MX host, TLS, certificate, reason, and description fields.
## Sessions
Inspect active/recent sessions and fetch diagnostics, or terminate sessions.
| SDK method | HTTP route | What it does |
| ----------------------------------------------------------- | ------------------------------------------------------------------------ | --------------------------- |
| `list_active_sessions(project_id)` | `GET /accounts/projects/{project_id}/sessions/active` | List active sessions. |
| `list_recent_sessions(project_id)` | `GET /accounts/projects/{project_id}/sessions` | List recent sessions. |
| `get_session(project_id, session_id)` | `GET /accounts/projects/{project_id}/sessions/{session_id}` | Fetch session metadata. |
| `list_session_events(project_id, session_id)` | `GET /accounts/projects/{project_id}/sessions/{session_id}/events` | Session event stream. |
| `list_session_spans(project_id, session_id)` | `GET /accounts/projects/{project_id}/sessions/{session_id}/spans` | Trace spans. |
| `list_session_metrics(project_id, session_id)` | `GET /accounts/projects/{project_id}/sessions/{session_id}/metrics` | Metrics data. |
| `get_session_participant_counts(project_id, session_id)` | `GET /accounts/projects/{project_id}/sessions/{session_id}/participants` | Participant counts. |
| `list_active_agent_sessions(project_id)` | `GET /accounts/projects/{project_id}/agents/sessions/active` | List active agent sessions. |
| `list_recent_agent_sessions(project_id, limit?, agent_id?)` | `GET /accounts/projects/{project_id}/agents/sessions` | List recent agent sessions. |
| `terminate(project_id, session_id)` | `POST /accounts/projects/{project_id}/sessions/{session_id}/terminate` | Terminate a session. |
## Scheduled Tasks
Scheduled tasks let you automate room workflows by sending queued messages on a schedule (cron or one-time).
| SDK method | HTTP route | What it does |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------ |
| `create_scheduled_task(project_id, room_name, …)` | `POST /accounts/projects/{project_id}/rooms/{room_name}/scheduled-tasks` | Create a scheduled task. |
| `update_scheduled_task(project_id, task_id, …)` | `PUT /accounts/projects/{project_id}/scheduled-tasks/{task_id}` | Update a task. |
| `delete_scheduled_task(project_id, task_id)` | `DELETE /accounts/projects/{project_id}/scheduled-tasks/{task_id}` | Delete a task. |
| `list_scheduled_tasks(project_id, room_id?, task_id?, active?, limit?, offset?)` | `GET /accounts/projects/{project_id}/scheduled-tasks` | List tasks with filters. |
| `list_scheduled_task_runs(project_id, task_id, limit?, offset?)` | `GET /accounts/projects/{project_id}/scheduled-tasks/{task_id}/runs` | List task runs. |
## Billing & usage
Checkout balances, transactions, subscriptions, and usage reports.
| SDK method | HTTP route | What it does |
| -------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `get_pricing()` | `GET /pricing` | Fetch pricing metadata. |
| `get_balance(project_id)` | `GET /accounts/projects/{project_id}/balance` | Fetch current balance and auto-recharge config, including the monthly auto-recharge budget. |
| `get_recent_transactions(project_id)` | `GET /accounts/projects/{project_id}/transactions` | List recent transactions. |
| `set_auto_recharge(project_id, enabled, amount, threshold, monthly_budget?)` | `POST /accounts/projects/{project_id}/recharge` | Configure auto-recharge and an optional monthly auto-recharge budget. |
| `get_checkout_url(project_id, success_url, cancel_url)` | `POST /accounts/projects/{project_id}/subscription` | Create subscription checkout; returns `checkout_url`. |
| `get_credits_checkout_url(project_id, success_url, cancel_url, quantity)` | `POST /accounts/projects/{project_id}/credits` | Purchase credits checkout; returns `checkout_url`. |
| `get_subscription(project_id)` | `GET /accounts/projects/{project_id}/subscription` | Fetch subscription info. |
| `get_usage(project_id, start?, end?, interval?, report?, users?, room?, provider?, model?, usage_type?)` | `GET /accounts/projects/{project_id}/usage` | Usage reporting with optional filters. |
## What’s next?
* Explore the [Room API overview](../room_api/overview) to work with live collaborative rooms.
* Review the [`ApiScope` reference](./api_scopes) for details on permission shape.
* Learn how room connections inherit grants in [participant tokens](./participant_tokens).