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
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:
- A request limit per minute, which covers all API calls and depends on your plan.
- A send limit per hour, which covers messages delivered to your customers and grows with your number of paid seats.
Request Limit (per minute)
| Plan | Request Limit |
|---|---|
| Herodesk Free | API not available |
| Herodesk Basic | 60 points/min |
| Herodesk Plus | 600 points/min |
| Herodesk Pro | 1,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
| Action | Cost |
|---|---|
| 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 |
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:
| Plan | Messages per paid seat per hour | Minimum per hour |
|---|---|---|
| Herodesk Basic | 30 | 60 |
| Herodesk Plus | 60 | 120 |
| Herodesk Pro | 120 | 240 |
Your send limit is seats × messages per seat, and never lower than the minimum. Examples:
| Paid seats | Basic | Plus | Pro |
|---|---|---|---|
| 1 | 60/hour | 120/hour | 240/hour |
| 3 | 90/hour | 180/hour | 360/hour |
| 10 | 300/hour | 600/hour | 1,200/hour |
| 25 | 750/hour | 1,500/hour | 3,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.
| Plan | 404 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
| Header | Description |
|---|---|
| X-Rate-Limit-Remaining | Points remaining in the current minute window, after this request's cost |
| X-Rate-Limit-Reset | Seconds until the current minute window resets |
| X-Rate-Limit-Cost | The cost of the current request |
| X-Rate-Limit-404-Penalty | Additional penalty applied (only on 404 responses) |
| X-Rate-Limit-Banned | true if your API key is temporarily banned |
| X-Rate-Limit-Ban-Reason | Reason for the ban and when it expires |
| X-Rate-Limit-Ban-Expires | Seconds until the ban is lifted |
| X-Send-Limit-Limit | Your hourly send limit (only on requests that send a message) |
| X-Send-Limit-Remaining | Messages you can still send in the current hour window |
| X-Send-Limit-Reset | Seconds until the current hour window resets |
What Happens When You Exceed a Limit
Both 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.
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.