REST API

• Projects & Rooms: Create projects, manage rooms, and mint room connection tokens
• Room grants : Persist per-user permissions to manage participant access and available actions
• Project storage: Upload/download project files by path
• Services: Manage project-wide and room-scoped services
• Secrets: Manage key-based and image-pull secrets
• 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

​

Getting started

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

source .venv/bin/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).

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

MESHAGENT_API_KEY=your-api-key-value
MESHAGENT_PROJECT_ID=your-project-id

​

3. Create a MeshAgent client

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

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

​

Projects, Rooms, and managed agents

​

Room grants

​

Agent grants

​

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

​

Sessions

​

Scheduled Tasks

​

Billing & usage

​

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.