Agents API

Manage agents programmatically. All endpoints are under https://tmmate.ai/api/v1 and require an admin key (see Authentication). Responses use the { "data": ... } envelope.

Tip: before creating an agent, call the Capabilities API to get valid model, tool, and knowledge-base IDs for your workspace.

Create an agent

Creates an agent in your workspace. Returns 201.

Body (application/json, strict — unknown fields rejected)

Example

curl -X POST https://tmmate.ai/api/v1/agents \
  -H "Authorization: Bearer $TEAMMATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Triage",
    "description": "Reads inbound email and drafts replies.",
    "systemPrompt": "You are a concise, friendly support agent.",
    "visibility": "private",
    "model": { "provider": "OPENAI", "model": "openai/gpt-4.1-mini", "temperature": 0.4 },
    "features": { "memory": true, "webSearch": true },
    "capabilities": {
      "knowledgeBases": [{ "id": "b2f1…UUID", "access": "read" }]
    }
  }'

Response 201

{ "data": { "id": "a1c2…UUID", "name": "Support Triage", "visibility": "private", "published": false, "model": { "provider": "OPENAI", "model": "openai/gpt-4.1-mini", "temperature": 0.4, "maxTokens": 150, "topP": 1, "frequencyPenalty": 0, "presencePenalty": 0 }, "features": { "memory": true, "webSearch": true, "attachments": false }, "...": "see AgentResponse" } }

Errors — 400 (validation, or model/toolkit not configured in workspace), 409 AGENT_NAME_CONFLICT, 401 / 403.

Get an agent

curl https://tmmate.ai/api/v1/agents/a1c2…UUID \
  -H "Authorization: Bearer $TEAMMATE_API_KEY"

Returns 200 → { "data": AgentResponse }. 404 AGENT_NOT_FOUND if it doesn’t exist in your workspace.

Update an agent

PUT and PATCH behave identically here: both accept a partial body (every field optional). Omitted fields are left unchanged; features are merged field-by-field.

curl -X PATCH https://tmmate.ai/api/v1/agents/a1c2…UUID \
  -H "Authorization: Bearer $TEAMMATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "published": true, "features": { "followUp": true } }'

Returns 200 → { "data": AgentResponse }. Errors: 400, 404.

Delete an agent

curl -X DELETE https://tmmate.ai/api/v1/agents/a1c2…UUID \
  -H "Authorization: Bearer $TEAMMATE_API_KEY"

Returns 200:

{ "data": { "id": "a1c2…UUID", "deleted": true } }

Listing agents: there is no strict GET /api/v1/agents list endpoint in this surface yet. Track the IDs you create, or browse agents in the app.

Schemas

ModelConfig

provider ∈ OPENAI, ANTHROPIC, GROQ, OPEN_ROUTER, DEEPSEEK, CODEX, ZAI, OLLAMA, LM_STUDIO, CLAUDE_CODE, CUSTOM. The (provider, model) pair must exist and be connected in your workspace’s AI configuration — otherwise the create/update returns 400. Use GET /capabilities/models for valid values (id → model.model).

ToolReference

A capabilities.tools[] entry is a discriminated union on kind:

{ "kind": "system", "id": "web_search", "config": {} }

{ "kind": "composio", "appId": "gmail", "actions": ["GMAIL_SEND_EMAIL"] }

For composio, the toolkit must be connected in your workspace or the request fails 400. Discover both with GET /capabilities/tools.

KnowledgeBaseReference

{ "id": "b2f1…UUID", "access": "read" }

access is "read" (default) or "read-write".

AgentFeatures

All optional booleans: attachments, webSearch, planning, memory, textToSpeech, followUp, dynamicUi, scheduledTasks. On create, memory defaults to true and the rest to false.

AgentWorkspaceConfig

{ enabled (default false), environment ("local" | "docker" | "daytona" | "cloud" | "browser", default "local"), capabilities { fileSystem (default true), shell, codeExecution, browser, desktop, readOnly }, advanced { searchIndexing, requireApproval, operationTimeout (default 60) } }.

Trigger

{
  "id": "gmail-new-email",
  "name": "New email",
  "appId": "composio.gmail",
  "values": { "connectionId": "c3d4…UUID", "customFieldValues": {} }
}

AgentResponse

The object returned by every agent endpoint:

id (UUID), workspaceId, createdBy, createdAt (ISO 8601), updatedAt (ISO 8601), name, description, systemPrompt, welcomeMessage, avatar, visibility, agentMode, published, publishedId, model (ModelConfig), capabilities, features (AgentFeatures), workspace (AgentWorkspaceConfig | null), appId, triggers (Trigger[]). Nullable fields return null when unset.