Skip to main content
The Meshagent REST API allows you to create and manage projects, rooms, members, and the room-level permissions that become participant tokens. Use the REST API for project and identity lifecycle tasks—provisioning rooms, assigning scopes, and managing membership. For real-time collaboration inside an active room, call the Room APIs.

​
Getting started

from meshagent.api.client import Meshagent

async def main():
    async with Meshagent(
        # optional; defaults to MESHAGENT_API_URL
        base_url="https://api.meshagent.com",
        # optional; defaults to MESHAGENT_API_KEY
        token="<bearer-access-token>",
    ) as client:
        # ...use the client...
        ...
  • base_url If set, environment variable MESHAGENT_API_URL is used. Default https://api.meshagent.com.
  • token If set, environment variable MESHAGENT_API_KEY is used. The user session token can also be used. The session token can be retrieved from ~/.meshagent/session.json which is set when using the meshagent cli to login.
Every method raises meshagent.api.RoomException on non-2xx responses and validates responses with Pydantic models, so malformed payloads surface as rich errors.

​
Managing project room grants

Project room grants store a user’s allowed ApiScope for a specific room. They are persisted as ProjectRoomGrant { room, user_id, permissions } records and later copied into the runtime ParticipantToken. Key methods:
MethodDescription
create_room_grant(project_id, room_id, user_id, permissions)Creates a grant (POST /accounts/projects/{project_id}/room-grants). Accepts an ApiScope instance for permissions.
update_room_grant(project_id, room_id, user_id, permissions)Replaces the stored ApiScope for an existing grant (PUT /room-grants).
get_room_grant(project_id, room_id, user_id)Returns the persisted ProjectRoomGrant (GET /room-grants/{room_id}/{user_id}).
list_room_grants(project_id, limit?, offset?, order_by?)Lists every grant in a project with pagination support.
list_room_grants_by_user(project_id, user_id, ...)Lists the rooms a specific user can access.
list_room_grants_by_room(project_id, room_id, ...)Lists the users that have access to a room.
list_unique_rooms_with_grants(project_id, ...)Returns ProjectRoomGrantCount objects summarising how many grants exist per room.
list_unique_users_with_grants(project_id, ...)Returns ProjectUserGrantCount objects summarising grant counts per user.
Example: assign a user read-only storage access in a room. 
from meshagent.api.client import Meshagent
from meshagent.api.participant_token import ApiScope, StorageGrant, StoragePathGrant

scope = ApiScope(
    storage=StorageGrant(paths=[StoragePathGrant(path="/data", read_only=True)])
)

await client.create_room_grant(
    project_id="proj_123",
    room_id="room_456",
    user_id="user_789",
    permissions=scope,
)
When that user connects, the router copies scope into the api grant of the token it mints (cloud_router_server.connect_room).

​
Other administration helpers

The client also exposes utilities for day-to-day project administration:
  • Room lifecycle: create, rename, delete rooms; fetch room metadata.
  • Project membership: add/remove users, check roles, and list members.
  • Storage helpers: upload and download files under /accounts/projects/{project_id}/storage/*.
  • OAuth clients: create, update, list, and delete OAuth client records for project integrations.

​
What’s next?