API-oversigt

Alle RolChats REST-endpoints følger én kontrakt: samme basis-URL, samme svarkonvolut, samme paginering, samme fejlform. Lær den én gang, så læses hver endpoint-familie i endpoint-referencen på samme måde.

Basis-URL og versionering

https://api.rolchat.com/api/v1/

Versionen står i stien. At tilføje valgfrie felter, nye endpoints eller nye forespørgselsparametre med standardværdier er ikke en bagudinkompatibel ændring og hæver ikke versionen. Bagudinkompatible ændringer udgives som v2, og udfasede v1-endpoints bliver ved med at virke i mindst seks måneder efter annonceringen (se Udfasning).

Godkendelse

Metode	Header	Bruges til
JWT bearer	Authorization: Bearer <access_token>	Interaktive sessioner (webappen, mobilapps)
API-nøgle	Authorization: Bearer rcp_<secret>	Kald mellem maskiner, plugin-API-nøgler
HMAC-signatur	X-RolChat-Signature: sha256=…	Indgående webhooks fra dine systemer, se Webhooks
Ingen	-	Offentlige widget-endpoints (/widget/…, /forms/…), afgrænset af websted og oprindelse

Til integrationer bruger du en API-nøgle (et personligt adgangstoken). Nøgler oprettes under Indstillinger → Plugins → RolChat API-nøgler, vises én gang og gemmes kun som en hash. En nøgle kan aldrig gøre mere end det medlem, der oprettede den: dens scopes kontrolleres mod medlemmets aktuelle tilladelser ved hvert kald. Se Godkendelse for JWT-levetider, headeren X-Account-Id og sessioner på tværs af flere virksomheder.

Svarkonvolut

En enkelt ressource:

{
  "data": { "id": "cnt_01HK…", "email": "ada@example.com" },
  "meta": {
    "request_id": "req_01HK…"
  }
}

En liste:

{
  "data": [ { … }, { … } ],
  "meta": {
    "request_id": "req_01HK…",
    "count": 50,
    "next_cursor": "cur_01HK…",
    "prev_cursor": "cur_01HK…",
    "has_more": true
  }
}

Svar uden body (204 No Content efter en sletning) har stadig headeren X-Request-Id.

En fejl:

{
  "errors": [
    {
      "code": "validation_failed",
      "message": "Email must be valid.",
      "field": "email",
      "details": { "received": "not-an-email" }
    }
  ],
  "meta": { "request_id": "req_01HK…" }
}

code er maskinlæsbar snake_case og er den værdi, du forgrener på; message er på engelsk og beregnet til logs. field og details er med, når de hjælper, og indeholder aldrig personoplysninger. API’et svarer aldrig 200 med et errors-array: hvis der er fejl, er status 400 eller højere. Den fulde liste over koder findes på siden Fejl.

Paginering

Liste-endpoints, der kan vokse, bruger cursor-paginering. Bed om den første side uden cursor, og send derefter den next_cursor, du modtog, tilbage uændret:

GET /api/v1/contacts?limit=50
GET /api/v1/contacts?limit=50&cursor=eyJrIjoi…

• limit er som standard 50 og højst 200; større værdier afvises med 400 validation_failed.
• Cursorer er uigennemsigtige og udløber efter 24 timer (400 validation_failed med code: cursor_expired).
• Resultaterne er konsistente i forhold til det øjebliksbillede, der blev taget på den første side: poster, der slettes mellem siderne, forsvinder, og nye poster vises først, når du starter forfra uden cursor.
• En Link-header med rel="next" og rel="prev" sendes også til klienter, der foretrækker den.

Idempotens

Send en Idempotency-Key-header (en UUID eller ULID på op til 255 tegn) med enhver POST, PATCH eller DELETE:

• Den første anmodning med en nøgle køres, og dens status og body gemmes i 24 timer.
• En gentagelse med samme nøgle og samme body returnerer det gemte svar uden at udføre sideeffekterne igen.
• En gentagelse med samme nøgle, men en anden body afvises med 409 idempotency_key_conflict.

Brug den til alle kald, der opretter noget med sideeffekter: at sende en besked, en e-mail eller en SMS, at foretage et opkald, alt, der faktureres. GET-anmodninger er altid idempotente og ignorerer headeren.

Hastighedsgrænser

Grænserne tælles pr. minut og gælder pr. konto, API-nøgle eller bruger (pr. IP-adresse på ruter uden login). Standardlofterne:

Spand	Standardgrænse	Pr. minut
Anmodninger uden login (pr. IP)	60	pr. IP
Logget ind bruger (dashboard)	1 000	pr. bruger
API-nøgle	1 000	pr. nøgle
Offentlige widget-endpoints	60 pr. besøgende og 600 pr. netværksadresse	pr. minut
Login (/auth/login)	5	pr. IP
Indgående webhooks	300	pr. minut
MCP-server	600	pr. minut
OAuth-endpoints	600	pr. minut

Lofterne er platformens standardværdier og kan ændres af operatøren; din plan ganger dem ikke, og Enterprise-grænser aftales i din kontrakt. Endpoints med hastighedsgrænse returnerer:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 543

Når du overskrider en grænse, er svaret 429 med code: rate_limited i errors-arrayet og en Retry-After-header i sekunder. Vent så længe, før du kalder igen. Ti mislykkede login låser kontoen i 30 minutter.

Størrelser og timeouts

Kategori	Maks. anmodningsbody	Server-timeout
Standard	1 MB	30 s
Besked med vedhæftninger	25 MB	30 s
CSV-import	50 MB	returnerer 202 og kører i baggrunden
Billeder i vidensbasen	10 MB	30 s
Masse-API	10 MB	30 s
Søgning	1 MB	10 s
AI-anmodninger	1 MB	60 s
Widget-endpoints	100 KB	30 s

For store bodies får 413 payload_too_large. En upstream, der løber ud i timeout, svarer 504 med code: upstream_timeout og et retry_after-hint, når et genforsøg kan hjælpe.

Indholdstyper, datoer og id’er

• Anmodninger og svar er application/json; charset=utf-8. Filuploads bruger multipart/form-data; CSV-eksporter returnerer text/csv. Ugyldig UTF-8 afvises med 400 validation_failed.
• Tidsstempler er ISO-8601 i UTC med millisekundpræcision: 2026-04-20T14:23:45.123Z. Enhver ISO-8601-forskydning accepteres i input og normaliseres til UTC.
• Id’er er uigennemsigtige ULID’er eller UUID’er. Der er ingen numeriske id’er, og e-mailadresser eller telefonnumre optræder aldrig i en URL.

Lejeradskillelse og tilladelser

Hver godkendt anmodning kører inden for én konto. En ressource, der tilhører en anden konto eller et websted, som kalderens rolle ikke dækker, svarer 404 not_found i stedet for 403, så det aldrig lækkes, at posterne findes. Et gyldigt token uden den krævede tilladelse (for eksempel contacts.delete) svarer 403 forbidden. Nogle tilladelser har et omfangssuffiks (conversations.read:own, :team, :all), der indsnævrer, hvad en liste returnerer.

PATCH accepterer kun skrivbare felter. id, account_id, created_at, updated_at og tilstandsfelter som resolved_at er skrivebeskyttede; sender du et af dem, returneres 400 validation_failed med details.forbidden_fields. Tilstandsændringer går gennem dedikerede handlinger som POST /tickets/:id/resolve.

Hver skrivning registreres i kontoens revisionslog.

Observerbarhedsheadere

Hvert svar indeholder:

X-Request-Id: req_01HK…

Log X-Request-Id. Det er det første, support spørger om.

CORS

Oprindelsen for browserdashboardet er https://app.rolchat.com. Offentlige widget-endpoints tillader enhver oprindelse eller kun de oprindelser, du verificerer for et websted. Kald mellem servere med en API-nøgle er ikke underlagt CORS.

Udfasning

1. Ændringen annonceres i ændringsloggen, og det berørte endpoint begynder at sende Deprecation: true og en Sunset-header med fjernelsesdatoen.
2. Offentlige endpoints bliver ved med at virke i mindst seks måneder efter annonceringen.
3. Fjernelse sker kun i en ny hovedversion. Inden for v1 er ændringer kun tilføjelser.

Sundhed

Hver tjeneste udstiller /healthz (liveness) og /readyz (readiness).