Herodesks API er en offentlig REST API med Swagger-dokumentation.
Sådan finder du din API-nøgle
Hver Herodesk-konto har én API-nøgle.
Du kan finde den i din Herodesk-konto -> Indstillinger -> API & Webhooks:
Tryk på kopier-ikonet til højre for det forkortede forhåndsvisning af API-nøglen for at kopiere hele API-nøglen til dit udklipsholder.
API-dokumentation
Du kan finde Swagger API-dokumentationen her: https://api.herodesk.io
Paginering og anden metadata
Vores API returnerer de faktiske data fra din forespørgsel.
Detaljer om paginering og anden metadata findes i headerne.
Begrænsning af hastighed
Vores API bruger to grænser for at sikre fair brug og platformsstabilitet:
- En forespørgselsgrænse pr. minut, som dækker alle API-kald og afhænger af din plan.
- En afsendelsesgrænse pr. time, som dækker beskeder, der leveres til dine kunder, og som vokser med antallet af betalte pladser.
Forespørgselsgrænse (pr. minut)
| Plan | Forespørgselsgrænse |
|---|---|
| Herodesk Free | API ikke tilgængelig |
| Herodesk Basic | 60 points/min |
| Herodesk Plus | 600 points/min |
| Herodesk Pro | 1.200 points/min |
Grænsen håndhæves med et glidende vindue, så den er jævn og fair uanset hvornår i minuttet du foretager dine forespørgsler.
Vægtede forespørgselsomkostninger
| Handling | Omkostning |
|---|---|
| De fleste endepunkter (GET, opdateringer, tags, interne noter osv.) | 1 point |
Opret en samtale (POST /v1/conversations) | 5 points |
Tilføj en besked til en samtale (POST /v1/conversations/{id}/messages) | 5 points |
Afsendelsesgrænse (pr. time)
Hver besked, din integration leverer til en kunde (message_type: "sent", når du opretter en samtale eller tilføjer en besked), tæller også med i en afsendelsesgrænse pr. time. Grænsen vokser med antallet af betalte pladser på din konto, så hvis du har brug for at sende mere, kan du tilføje pladser:
| Plan | Beskeder pr. betalt plads pr. time | Minimum pr. time |
|---|---|---|
| Herodesk Basic | 30 | 60 |
| Herodesk Plus | 60 | 120 |
| Herodesk Pro | 120 | 240 |
Din afsendelsesgrænse er pladser × beskeder pr. plads, og aldrig lavere end minimum. Eksempler:
| Betalte pladser | Basic | Plus | Pro |
|---|---|---|---|
| 1 | 60/time | 120/time | 240/time |
| 3 | 90/time | 180/time | 360/time |
| 10 | 300/time | 600/time | 1.200/time |
| 25 | 750/time | 1.500/time | 3.000/time |
Godt at vide:
- Kun beskeder, der rent faktisk sendes til en kunde, tæller med. Registrering af indgående beskeder (
received), interne noter og forespørgsler, der fejler (fx valideringsfejl), bruger ikke din afsendelsesgrænse. - Beskeder sendt af dine menneskelige medarbejdere i Herodesk, af AI-agenten og af regler tæller ikke med. Afsendelsesgrænsen gælder for API'en og for Herodesk MCP-serveren, som deler én grænse pr. konto.
- Lite-brugere (gratis, kan ikke svare) tæller ikke som betalte pladser.
Straf for 404-svar
Forespørgsler, der returnerer et 404 Not Found-svar, medfører en ekstra straf på 10 % af din forespørgselsgrænse pr. minut ud over den normale forespørgselsomkostning. Dette modvirker ugyldige forespørgsler og API-enumerering.
| Plan | 404-straf |
|---|---|
| Basic (60/min) | 6 ekstra points pr. 404 |
| Plus (600/min) | 60 ekstra points pr. 404 |
| Pro (1.200/min) | 120 ekstra points pr. 404 |
For eksempel koster et 404-svar på Basic-planen 1 (normal) + 6 (straf) = 7 points i alt.
Midlertidig blokering ved overdrevne 404'er
Hvis din integration genererer 50 eller flere 404-svar inden for 5 minutter, vil din API-nøgle blive midlertidigt blokeret i 15 minutter. I denne tid vil alle forespørgsler returnere 429 Too Many Requests.
Respons-header
| Header | Beskrivelse |
|---|---|
| X-Rate-Limit-Remaining | Points tilbage i det aktuelle minutvindue, efter denne forespørgsels omkostning |
| X-Rate-Limit-Reset | Sekunder indtil det aktuelle minutvindue nulstilles |
| X-Rate-Limit-Cost | Omkostningen ved den aktuelle forespørgsel |
| X-Rate-Limit-404-Penalty | Yderligere straf anvendt (kun på 404-svar) |
| X-Rate-Limit-Banned | true hvis din API-nøgle er midlertidigt blokeret |
| X-Rate-Limit-Ban-Reason | Årsag til blokeringen og hvornår den udløber |
| X-Rate-Limit-Ban-Expires | Sekunder indtil blokeringen ophæves |
| X-Send-Limit-Limit | Din afsendelsesgrænse pr. time (kun på forespørgsler, der sender en besked) |
| X-Send-Limit-Remaining | Beskeder, du stadig kan sende i det aktuelle timevindue |
| X-Send-Limit-Reset | Sekunder indtil det aktuelle timevindue nulstilles |
Hvad sker der, når du overskrider en grænse
Begge grænser returnerer 429 Too Many Requests:
- Forespørgselsgrænsen: beskeden er "Rate limit exceeded." Brug X-Rate-Limit-Reset til at se, hvornår du kan genoptage.
- Afsendelsesgrænsen: beskeden fortæller, hvor mange beskeder pr. time din plan tillader. Brug X-Send-Limit-Reset til at se, hvornår du kan genoptage, eller tilføj pladser eller opgrader din plan for at hæve grænsen.
Bedste praksis
- Overvåg respons-headerne. Brug X-Rate-Limit-Remaining og X-Send-Limit-Remaining til at dæmpe dine forespørgsler, før du rammer en grænse.
- Håndter 429-svar elegant. Implementer eksponentiel backoff og gentagelseslogik.
- Undgå ugyldige forespørgsler. 404-svar straffes, så valider ressource-ID'er, før du foretager API-opkald.
- Dimensioner din plan efter dit afsendelsesvolumen. Hvis din integration sender mange beskeder til kunder, kan du tilføje pladser eller vælge Plus eller Pro for at hæve din afsendelsesgrænse.