API reference

The Mantle Chat API lets your code read agents and tasks, start task runs, ask an agent for a response, manage webhook endpoints for signed events, and post as a bot. The endpoint pages in this tab are generated from the same contract the API serves, so they always match it.

Base URL

Send every request to https://api.mantle.chat. Every path starts with /v1.

Authentication

Send a token in the Authorization header:

curl https://api.mantle.chat/v1/agents \
  -H "Authorization: Bearer $MANTLE_API_KEY"

There are two kinds of token, and each endpoint takes one of them:

Token	Looks like	For	Where it comes from
API key	`mk_live_…`	Agents, tasks and runs, agent responses and webhook endpoints	A workspace owner or admin creates it in Settings → Developer → API keys, choosing its scopes. It’s shown once.
Bot token	`mbt_live_…`	`/v1/me`, `/v1/channels` and channel messages	Installing a bot app in a workspace. See Build a bot.

An API key belongs to one workspace and the member who made it. It stops working when that member leaves the workspace or the key is revoked.
A key only reaches what its scopes allow. Anything else answers 403 insufficient_scope.
Keep tokens on your server. Store them in a secret manager, never in a browser or an app.

Requests and responses

Bodies are JSON. Send content-type: application/json with them.
Lists come in pages of { "data": [...], "nextCursor": "…" }. Pass nextCursor back as cursor for the next page; it’s null on the last one. limit sets the page size.
An Idempotency-Key header makes a retry safe. Most requests that create or change something require one, such as a UUID you make, and posting a bot message accepts one. Repeat a request with the same key and Mantle answers with the first result instead of doing it twice. Reusing a key for a different request answers 409 idempotency_conflict. Validating a change set, cancelling an agent response, and editing or deleting a bot’s post take no key. Each endpoint’s page says whether it needs one.
Timestamps are UTC, in RFC 3339, such as 2026-10-21T12:00:00Z.

Errors

An error answers with its HTTP status and a body like this:

{
  "error": {
    "code": "insufficient_scope",
    "message": "The API credential does not have the required scope.",
    "requestId": "req_4d2c…"
  }
}

code is stable, so match on it rather than on message. Include requestId when you contact support.

Status	Codes, for example	What to do
`400`	`invalid_request`, `invalid_cursor`, `invalid_idempotency_key`	Fix the request
`401`	`invalid_credential` (API key), `invalid_token` (bot token)	Check the token, or create a new one
`403`	`insufficient_scope`, `access_denied`, `workspace_not_enabled`	Give the key the scope it needs, or check the workspace’s access
`404`	`agent_not_found`, `task_not_found`, `run_not_found`, `channel_not_found`, …	Check the id, and that the token’s workspace has it
`409`	`idempotency_conflict`, `idempotency_in_progress`, `resource_conflict`, `stale_change_set`	Read the resource again, or wait for the first request to finish
`422`	`validation_failed`, `invalid_change_set`, `invalid_webhook_endpoint`	Fix what `details` names
`429`	`rate_limited`, `capacity_exceeded`	Wait for the seconds in `Retry-After`, then retry
`503`	`platform_unavailable`, `agent_responses_not_enabled`	Retry later

Limits

Token	Requests a minute
API key	120 for each key, and 600 across a workspace
Bot token	60 for each installed bot, and 600 across a workspace

Over a limit, a request answers 429 rate_limited with a Retry-After header.

Webhooks

A webhook endpoint you create with POST /v1/webhook-endpoints receives signed events, such as a run that finished. Each one is a POST with mantle-webhook-id, mantle-webhook-timestamp and mantle-webhook-signature headers. The signature is v1= followed by the hex HMAC-SHA256 of {timestamp}.{id}.{body}, keyed with the endpoint’s signing secret. Check it against the exact body you received, and refuse events more than 5 minutes old.

Agent responses

Agent responses are a pilot: they’re on for some workspaces only, and need their own scopes. Elsewhere they answer 503 agent_responses_not_enabled. Contact us to turn them on.

SDK

The TypeScript SDK wraps every endpoint and checks webhook signatures for you. It runs on Node 20 or later, Bun and Deno.

npm install @mantlechat/sdk

import { MantleClient } from '@mantlechat/sdk';

const mantle = new MantleClient({ apiKey: process.env.MANTLE_API_KEY });

for await (const agent of mantle.agents.listAll()) {
  console.log(agent.id, agent.name);
}

Get started

Endpoints

Base URL

Authentication

Requests and responses

Errors

Limits

Webhooks

Agent responses

SDK

​Base URL

​Authentication

​Requests and responses

​Errors

​Limits

​Webhooks

​Agent responses

​SDK

Base URL

Authentication

Requests and responses

Errors

Limits

Webhooks

Agent responses

SDK