Skip to main content
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:
  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

1. Set up the SDK

Install uv, then create a project and virtual environment with MeshAgent installed:
Activate your virtual environment:
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:

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

Create a .env file in your project and paste the key value:

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.

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.

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.

Project Storage

MeshAgent allows you to use both project wide and room specific storage. For room-scoped storage see the Storage API documentation.

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

Room Services

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.

Feeds and subscriptions

Create project feeds, publish messages, and fan them out into room storage through subscriptions.

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.

Registries

Create and manage project-owned image repositories.

Webhooks

API Keys

OAuth clients

Manage OAuth Clients for connections with other services.

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.

Shares

Manage share records for a project.

Mailboxes

Create and manage mailboxes that can be used by Agents or Rooms.

Sessions

Inspect active/recent sessions and fetch diagnostics, or terminate sessions.

Scheduled Tasks

Scheduled tasks let you automate room workflows by sending queued messages on a schedule (cron or one-time).

Billing & usage

Checkout balances, transactions, subscriptions, and usage reports.

What’s next?