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 rate limiting to ensure fair usage and platform stability. Rate limits are based on your Herodesk subscription plan.
Rate Limits by Plan
| Plan | Rate Limit |
|---|---|
| Herodesk Free | API not available |
| Herodesk Basic | 60 requests/min |
| Herodesk Plus | 600 requests/min |
These rate limits apply across all endpoints using a sliding window algorithm, which ensures smooth and fair enforcement regardless of when in the minute you make your requests.
Weighted Request Costs
Not all API calls cost the same. Most requests cost 1 point against your rate limit, but some actions are more expensive:
| Action | Cost |
|---|---|
| Most endpoints (GET, etc.) | 1 |
| Create conversation | 5 |
| Create/send message | 25 |
For example, on the Basic plan (60/min), sending a single message consumes 100 points — which exceeds the full allowance. Plan your usage accordingly, especially for message-heavy integrations where the Plus plan is recommended.
404 Penalty
Requests that result in a 404 Not Found response incur an additional penalty of 10% of your rate 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 |
For example, on the Basic plan, a 404 response costs 1 (normal) + 6 (penalty) = 7 points 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
Every API response includes headers to help you monitor your rate limit usage:
| Header | Description |
|---|---|
| X-Rate-Limit-Remaining | Number of points remaining in the current window |
| X-Rate-Limit-Reset | Seconds until the current 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 |
What Happens When You Exceed the Limit
If you exceed your rate limit, the API will return a 429 Too Many Requests response. Use the X-Rate-Limit-Reset header to determine when you can resume making requests.
Best Practices
- Monitor the response headers — use X-Rate-Limit-Remaining to throttle your requests before hitting the limit.
- Handle 429 responses gracefully — implement exponential backoff and retry logic.
- Avoid invalid requests — 404 responses are penalized, so validate resource IDs before making API calls.
- Use the Plus plan for message-heavy integrations — sending messages costs 100 points per request.
These rate limits apply across all endpoints.