Overview of the public agents API

The public agents API lets you create and manage agents programmatically — the same agents you build in the app, exposed as REST. Use it for custom apps, backend workflows, controlled embeds, or any integration that needs to call or configure an agent outside the TeamMate UI.

Base URL and auth

All requests go to:


https://tmmate.ai/api/v1

Authenticate with a workspace API key sent as a Bearer token:


Authorization: Bearer sk_prod_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Agent endpoints require the workspace admin role. See Generating API keys.

What you can do

Capability	Endpoint	Reference
Create an agent	`POST /agents`	Agents API
Read an agent	`GET /agents/{agentId}`	Agents API
Update an agent	`PUT` / `PATCH /agents/{agentId}`	Agents API
Delete an agent	`DELETE /agents/{agentId}`	Agents API
Discover valid IDs	`GET /capabilities/*`	Capabilities API

Before creating an agent, call the capabilities endpoints to get valid model, tool, and knowledge-base IDs for your workspace. Passing an ID that isn’t connected returns a 400.

Conventions

Envelope — every success response is { "data": ... }.
Errors — { "error": string, "code": string, "details"?: unknown } with a matching HTTP status.
Content type — application/json (file uploads use multipart/form-data).
Versioning — path-based (/api/v1).

Quick check

Confirm a key works by listing the models in your workspace:


curl https://tmmate.ai/api/v1/capabilities/models \
  -H "Authorization: Bearer $TEAMMATE_API_KEY"

Full reference

This section is the agent-focused entry point. The complete request/response reference, schemas, and interactive explorer live in the API reference: