Requests, responses & errors

View as Markdown Open in ChatGPT Open in Claude

Conventions shared by every endpoint under https://tmmate.ai/api/v1.

Base URL & versioning


https://tmmate.ai/api/v1

The API is versioned in the path. The current OpenAPI document version is 1.1.0. There is no version header or content negotiation.

Content types

Request and response bodies are application/json.
The one exception is knowledge-base file upload, which is multipart/form-data — see Manage knowledge bases.

Request bodies are validated strictly: unknown fields are rejected with a 400.

Success envelope

Every successful response wraps its payload in a data key:


{ "data": { "id": "…", "name": "…" } }

List endpoints put the array under data and add a sibling pagination object (see below).

Status codes

Status	When
`200 OK`	Successful read, update, or delete.
`201 Created`	Successful create (agents, knowledge bases, content, file upload).
`400 Bad Request`	Validation failed, or the request can’t be fulfilled (e.g. unconfigured model).
`401 Unauthorized`	Missing / invalid / expired key.
`403 Forbidden`	Valid key without the required admin role.
`404 Not Found`	Resource doesn’t exist, or isn’t in your workspace.
`409 Conflict`	Duplicate agent name in the workspace.
`500 Internal Server Error`	Unexpected server error.

Error format

Errors return a consistent shape with a machine-readable code:


{
  "error": "Human-readable message",
  "code": "VALIDATION_ERROR",
  "details": [ /* present for validation errors */ ]
}

`code`	Status	Meaning
`VALIDATION_ERROR`	400	Body or query failed validation. `details` lists the issues.
`UNAUTHORIZED`	401	Authentication failed.
`FORBIDDEN`	403	Admin role required.
`AGENT_NOT_FOUND`	404	No such agent in this workspace.
`KNOWLEDGE_BASE_NOT_FOUND`	404	No such knowledge base in this workspace.
`AGENT_NAME_CONFLICT`	409	An agent with that name already exists.

A 500 returns { "error": "Internal server error" } with no code.

Pagination

Two styles are used, depending on the endpoint:

Page-based (knowledge-base list): query with page and limit.


{
  "data": { "knowledgeBases": [ /* … */ ] },
  "pagination": {
    "total": 42, "page": 1, "limit": 20,
    "totalPages": 3, "hasNextPage": true, "hasPrevPage": false
  }
}

Offset-based (embeddings list): query with limit and offset.


{ "data": { "embeddings": [ /* … */ ], "pagination": { "total": 500, "limit": 100, "offset": 0 } } }

Rate limits

The public API (/api/v1) does not currently enforce per-key rate limits. Be a good citizen: batch where you can, and back off on 5xx.

A note on field casing

Enum values are case-sensitive. In particular, model provider values are uppercase — OPENAI, ANTHROPIC, DEEPSEEK, OPEN_ROUTER, etc. (see Capabilities API).