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.

Getting started

To call the MeshAgent REST API, authenticate with a project API key. The simplest path is:

Set up a Python environment with the MeshAgent SDK installed (requires Python 3.13)
Use the MeshAgent CLI to create and activate an API key, then store it in a .env file
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

1. Set up the SDK

Install uv, then create a project and virtual environment with MeshAgent installed:

# 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:

source .venv/bin/activate

.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:

uv lock --upgrade
uv sync

2. Create a new API key and store it in `.env`

# 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:

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.

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)
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`, `user_profile_editor`, or `llm_proxy_user`.
`update_project_user(project_id, user_id, roles)`	`PUT /accounts/projects/{project_id}/users/{user_id}`	Replace a user’s project roles.
`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 project users with `view=project	user	merged` (default merged).
`get_user_profile(user_id)`	`GET /accounts/profiles/{user_id}`	Fetch your global profile. With `project_id`, use the project profile route and selected view.
`update_user_profile(user_id, first_name=None, last_name=None, metadata=..., annotations=..., project_id=...)`	`PUT /accounts/profiles/{user_id}`	Edit your global names/metadata, or project overrides when `project_id` is supplied. Project edits always require `user_profile_editor`.
`get_user_profile(user_id, project_id=..., view="merged")`	`GET /accounts/projects/{project_id}/users/{user_id}/profile`	Read project overrides, global defaults, or their merged profile.
`update_user_profile(user_id, project_id=..., inherit=...)`	`PUT /accounts/projects/{project_id}/users/{user_id}/profile`	Update project overrides or restore inheritance; requires `user_profile_editor`.
`search_sysadmin_users(filter=..., page_size=...)`	`GET /accounts/sysadmin/users`	Search and paginate global accounts; requires sysadmin scope and membership.
`get_sysadmin_user_profile(user_id)`	`GET /accounts/sysadmin/users/{user_id}`	Read a global account profile as a sysadmin.
`update_sysadmin_user_profile(user_id, update=...)`	`PUT /accounts/sysadmin/users/{user_id}`	Edit global names, metadata, and annotations as a sysadmin.
`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`.

User profiles

A project user profile combines shared account defaults with overrides stored for that project. The same account can have different names, metadata, and annotations in different projects. ID and email remain account identity fields and cannot be edited through profile updates.

Read views

GET /accounts/projects/{project_id}/users and GET /accounts/projects/{project_id}/users/{user_id}/profile accept view=project|user|merged. Use me for the signed-in user.

View	Attributes returned
`merged` (default)	Global names and maps with project overrides applied.
`user`	Shared global profile attributes, without project overrides.
`project`	Only stored project overrides, together with the account ID and email. Missing name fields mean inherit; an explicit `null` clears the name.

Metadata and annotations merge by key; a project key replaces the global value, including an entire nested metadata value. Global values remain visible wherever the project has no override. All three views require project membership and an OAuth token covering the project with projects:iam.read. The legacy admin scope and projects:iam.write also cover reads. A requested user must belong to the project. Project API keys can read users in their project. The account endpoint, GET /accounts/profiles/me, requires profile:read and is self-only. To read another user’s shared profile, use an authorized project endpoint with view=user, or a sysadmin endpoint.

Editing project overrides

PUT /accounts/projects/{project_id}/users/{user_id}/profile always edits project-local overrides. Every edit requires user_profile_editor, including editing your own project profile, and a token covering the project with projects:iam.write (legacy admin is accepted). Project owners and admins inherit the editor role. The target must belong to the project.

PUT /accounts/projects/{project_id}/users/{user_id}/profile
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "first_name": "Ada",
  "metadata": {"department": "research"},
  "annotations": {"reviewed": "yes"}
}

Send only changed fields. Supplied maps replace the project’s stored map; omitted fields are preserved. {} clears the local map, revealing global defaults. Annotation values must be strings; metadata values may be arbitrary JSON. Name fields accept strings or null. Email, IDs, and roles are not editable through this endpoint. To restore inheritance, send inherit, containing field names to remove from the project profile:

{"inherit": ["first_name", "metadata", "annotations"]}

A field cannot be both supplied and inherited in the same request. Project profile editors should load view=project for editing and view=user to show inherited defaults. Saving the merged view would copy defaults into project overrides.

Editing global defaults

PUT /accounts/profiles/me requires profile:write and lets users edit their own global names and metadata. It cannot edit global annotations or another account, even when the caller has a project editor role. Project edits never write the global profile. Sysadmins use these dedicated endpoints:

Route	Purpose
`GET /accounts/sysadmin/users?filter=...`	Search by email, name, or user ID, with `page_size` and `continuation_token`.
`GET /accounts/sysadmin/users/{user_id}`	Read a global profile.
`PUT /accounts/sysadmin/users/{user_id}`	Edit global names, metadata, or annotations.

All sysadmin endpoints require both the OAuth sysadmin scope and registered sysadmin membership. A scope alone does not grant platform authority. Global annotations are edited only through these endpoints. Global profile data returned to projects is shared data; keep private account settings outside these profile maps. Successful updates return {"ok": true}. Invalid views, JSON, fields, or inheritance requests return 400; missing permissions return 403; missing profiles return 404.

Python SDK examples

await client.update_user_profile("me", metadata={"theme": "dark"})

await client.update_user_profile(
    user_id,
    project_id=project_id,
    metadata={"department": "research"},
    annotations={"reviewed": "yes"},
)

merged = await client.get_user_profile(user_id, project_id=project_id)
overrides = await client.get_user_profile(user_id, project_id=project_id, view="project")
defaults = await client.get_user_profile(user_id, project_id=project_id, view="user")
await client.update_user_profile(user_id, project_id=project_id, inherit=["first_name"])

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 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.

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.

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 to work with live collaborative rooms.
Review the ApiScope reference for details on permission shape.
Learn how room connections inherit grants in participant tokens.

Introduction

Rooms

Agents & Tools

Deploy & Manage

Projects

Product Interfaces

Developer Reference

Getting started

1. Set up the SDK

2. Create a new API key and store it in `.env`

3. Create a MeshAgent client

Client configuration

Projects, Rooms, and managed agents

User profiles

Read views

Editing project overrides

Editing global defaults

Python SDK examples

Resource policies

Project Storage

Services

Project Services

Room Services

Secrets

Routes

Feeds and subscriptions

LLM loggers

Registries

Webhooks

API Keys

OAuth clients

External OAuth registrations

Shares

Mailboxes

Delivery status API

Sessions

Scheduled Tasks

Billing & usage

What’s next?

​Getting started

​1. Set up the SDK

​2. Create a new API key and store it in .env

​3. Create a MeshAgent client

​Client configuration

​Projects, Rooms, and managed agents

​User profiles

​Read views

​Editing project overrides

​Editing global defaults

​Python SDK examples

​Resource policies

​Project Storage

​Services

​Project Services

​Room Services

​Secrets

​Routes

​Feeds and subscriptions

​LLM loggers

​Registries

​Webhooks

​API Keys

​OAuth clients

​External OAuth registrations

​Shares

​Mailboxes

​Delivery status API

​Sessions

​Scheduled Tasks

​Billing & usage

​What’s next?

Getting started

1. Set up the SDK

2. Create a new API key and store it in `.env`

3. Create a MeshAgent client

Client configuration

Projects, Rooms, and managed agents

User profiles

Read views

Editing project overrides

Editing global defaults

Python SDK examples

Resource policies

Project Storage

Services

Project Services

Room Services

Secrets

Routes

Feeds and subscriptions

LLM loggers

Registries

Webhooks

API Keys

OAuth clients

External OAuth registrations

Shares

Mailboxes

Delivery status API

Sessions

Scheduled Tasks

Billing & usage

What’s next?