Developers
Build on Wilmo
API
REST and OpenAPI
Read tickets, conversations and teams over HTTP with an API key.
curl https://app.wilmo.ai/api/v2/tickets \
-H "Authorization: Bearer $WILMO_API_KEY"Claude & MCP
Connect Claude in 2 minutes
Add Wilmo as a custom connector and ask Claude about your support.
https://app.wilmo.ai/api/mcpCLI
Wilmo in your terminal
Sign in with your browser and run any public operation as a command.
npx @wilmo/cli loginOne definition, every surface#
Every operation is written once in Wilmo as an action. That one definition is the API route, the MCP tool Claude calls, the CLI command and the entry in these docs. They share a name, take the same input, and answer the same data, so a new operation reaches all four together.
one operation: list tickets
|
+--> REST GET https://app.wilmo.ai/api/v2/tickets
+--> MCP tool list_tickets (https://app.wilmo.ai/api/mcp)
+--> CLI wilmo tickets list
+--> Docs operationId list_tickets (OpenAPI)Authentication#
Send a key as a Bearer token: Authorization: Bearer <key>. What it reads depends on the key.
| Key | Made in | Reads | Works with |
|---|---|---|---|
| Team API key | Settings > API keys | Its own team | REST, MCP, CLI |
| Organization key | Settings > Connected apps (organization admins) | Every team of the organization, with the scopes chosen when it was made | REST, MCP, CLI |
| Claude or CLI sign-in (OAuth) | Sign in with Wilmo as an organization admin | Every team of the organization, read-only | MCP, CLI |
OAuth access tokens work on the MCP server only. Scopes today are read:tickets and read:analytics; each operation names the one it needs. Revoke a key in Settings > API keys, and an organization key or a Claude connection in Settings > Connected apps.
Keep keys secret
Headers#
| Authorization | Bearer <key> | Every request. |
| Wilmo-Version | YYYY-MM-DD | Pins the request and response shape. Default: the key's pinned version. |
| Wilmo-Organization | <organization id> | Only when the caller belongs to several organizations. A key already names its own. |
| Idempotency-Key | <uuid> | Writes (POST, PATCH, DELETE). The same key and body within 24 hours answers the stored response. |
Every response
| Request-Id | req_... | Every response. Quote it when you contact us. |
| Wilmo-Version | YYYY-MM-DD | The version that shaped the response. |
| RateLimit-Limit / RateLimit-Remaining | integer | The current window and what is left of it. |
| Retry-After | seconds | On a 429. |
Responses#
A success answers the object itself. A list answers { "object": "list", "data": [...], "has_more", "next_cursor" }. An error answers { "error": { "type", "code", "message", "param", "request_id", "doc_url" } }. Branch on code; every code is explained in Errors.
Versions#
The API has dated versions. The first is 2026-11-06. Each key and Claude connection is pinned to the version that was current when it was made, and Wilmo-Version overrides it per request. New fields and operations arrive without a new version; anything that could break you waits for one. How versions work
Rate limits#
An API key may send 2,500 requests per 10 minutes. A Claude connection may send 300 per 10 minutes. Over the limit, the API answers 429 rate_limited with Retry-After in seconds. Wait that long, then retry.
Agent skills#
Building with a coding agent? Give it a skill that teaches it the API, so it writes correct calls the first time.
Using the Wilmo API
Authenticate, discover operations, call them, page, handle errors, rate limits and versions.
Migrating between Wilmo API versions
Read the versions document and move a pinned integration to a newer API version.
The whole developer surface is also listed for language models at /llms.txt.