Public REST API

This article contains everything you need to know about our API and how to get started

Written by Anders Eiler
Last updated 2026-03-19
On this page

Herodesks API is a public REST API with Swagger documentation.

How to find your API key

Every Herodesk account has one API key.

You can find it in your Herodesk account -> Settings -> API & Webhooks:

Press the copy-icon to the right of the truncated API key preview to copy the whole API key to your clipholder.

API Documentation

You can find the Swagger API Documentation here: https://api.herodesk.io

AI agents

You can set up and run your AI agents through the API: create and configure agents, give them knowledge, manage their topics, instructions and skills, test them in the playground, and work with goals and fine-tuning. Everything that belongs to one agent lives under that agent, for example /v1/ai-agents/{agent_id}/topics and /v1/ai-agents/{agent_id}/datasets. See the Swagger documentation for every endpoint.

The AI agent endpoints that change an agent's setup require an API key or a user with the manager role.

Deprecated endpoints

These endpoints still work, but will be removed in a future version. Responses from them carry a Deprecation header.

DeprecatedUse instead
GET /v1/ai-topicsGET /v1/ai-agents/{agent_id}/topics
GET /v1/ai-topics/{id}GET /v1/ai-agents/{agent_id}/topics/{id}
PATCH /v1/ai-topics/{id}PATCH /v1/ai-agents/{agent_id}/topics/{id}

Pagination and other metadata

Our API returns the actual data of your request.

Details about pagination and other metadata are available in the headers.

You can change the page size by using the ?per-page query parameter, fx ?per-page=50. The per-page query parameter is capped at 100.

Rate limiting

Our API uses two limits to ensure fair usage and platform stability:

  1. A request limit per minute, which covers all API calls and depends on your plan.
  2. A send limit per hour, which covers messages delivered to your customers and grows with your number of paid seats.

Request Limit (per minute)

PlanRequest Limit
Herodesk FreeAPI not available
Herodesk Basic60 points/min
Herodesk Plus600 points/min
Herodesk Pro1,200 points/min

The limit is enforced with a sliding window, so it's smooth and fair regardless of when in the minute you make your requests.

Weighted Request Costs

ActionCost
Most endpoints (GET, updates, tags, internal notes, etc.)1 point
Create a conversation (POST /v1/conversations)5 points
Add a message to a conversation (POST /v1/conversations/{id}/messages)5 points
Test an AI agent in the playground (POST /v1/ai-agents/{id}/playground)10 points

AI agent playground tests are also limited to 60 per hour for your whole account, shared with the Herodesk MCP server. Tests in the Playground inside Herodesk don't count.

Send Limit (per hour)

Every message your integration delivers to a customer (message_type: "sent", when creating a conversation or adding a message) also counts against an hourly send limit. The limit scales with the number of paid seats on your account, so if you need to send more, add seats:

PlanMessages per paid seat per hourMinimum per hour
Herodesk Basic3060
Herodesk Plus60120
Herodesk Pro120240

Your send limit is seats × messages per seat, and never lower than the minimum. Examples:

Paid seatsBasicPlusPro
160/hour120/hour240/hour
390/hour180/hour360/hour
10300/hour600/hour1,200/hour
25750/hour1,500/hour3,000/hour

Good to know:

  • Only messages that are actually sent to a customer count. Recording incoming messages (received), internal notes, and requests that fail (e.g. validation errors) don't use your send limit.
  • Messages sent by your human agents in Herodesk, by the AI Agent and by rules don't count. The send limit applies to the API and to the Herodesk MCP server, which share one limit per account.
  • Lite users (free, can't reply) don't count as paid seats.

Penalty for 404 Responses

Requests that return a 404 Not Found incur an extra penalty of 10% of your per-minute request limit, on top of the normal request cost. This discourages invalid requests and API enumeration.

Plan404 Penalty
Basic (60/min)6 extra points per 404
Plus (600/min)60 extra points per 404
Pro (1,200/min)120 extra points per 404

For example, on the Basic plan a 404 response costs 1 (normal) + 6 (penalty) = 7 points in total.

Temporary Ban for Excessive 404s

If your integration generates 50 or more 404 responses within 5 minutes, your API key will be temporarily banned for 15 minutes. During this time, all requests will return 429 Too Many Requests.

Response Headers

HeaderDescription
X-Rate-Limit-RemainingPoints remaining in the current minute window, after this request's cost
X-Rate-Limit-ResetSeconds until the current minute window resets
X-Rate-Limit-CostThe cost of the current request
X-Rate-Limit-404-PenaltyAdditional penalty applied (only on 404 responses)
X-Rate-Limit-Bannedtrue if your API key is temporarily banned
X-Rate-Limit-Ban-ReasonReason for the ban and when it expires
X-Rate-Limit-Ban-ExpiresSeconds until the ban is lifted
X-Send-Limit-LimitYour hourly send limit (only on requests that send a message)
X-Send-Limit-RemainingMessages you can still send in the current hour window
X-Send-Limit-ResetSeconds until the current hour window resets

What Happens When You Exceed a Limit

All limits return 429 Too Many Requests:

  • Request limit: the message is "Rate limit exceeded." Use X-Rate-Limit-Reset to see when you can resume.
  • Send limit: the message says how many messages per hour your plan allows. Use X-Send-Limit-Reset to see when you can resume, or add seats or upgrade your plan to raise the limit.
  • AI agent playground limit: the message says how long to wait, and the Retry-After header gives the seconds.

Best Practices

  • Monitor the response headers. Use X-Rate-Limit-Remaining and X-Send-Limit-Remaining to throttle before you hit a limit.
  • Handle 429 responses gracefully. Implement exponential backoff and retry logic.
  • Avoid invalid requests. 404 responses are penalised, so validate resource IDs before making API calls.
  • Size your plan for your sending volume. If your integration sends many messages to customers, add seats or choose Plus or Pro to raise your hourly send limit.
  • Move off deprecated endpoints. Watch for the Deprecation header and switch to the endpoints listed above.