API-oversikt

Alle RolChat REST-endepunkter følger én kontrakt: samme basis-URL, samme svarkonvolutt, samme paginering, samme feilformat. Lær den én gang, så leses alle endepunktfamilier i endepunktreferansen på samme måte.

Basis-URL og versjonering

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

Versjonen står i stien. Å legge til valgfrie felt, nye endepunkter eller nye spørringsparametere med standardverdier er ikke en bakoverinkompatibel endring og øker ikke versjonen. Bakoverinkompatible endringer leveres som v2, og avviklede v1-endepunkter fortsetter å virke i minst seks måneder etter at de er kunngjort (se Avvikling).

Autentisering

Metode	Header	Brukes til
JWT bearer	Authorization: Bearer <access_token>	Interaktive økter (nettappen, mobilappene)
API-nøkkel	Authorization: Bearer rcp_<secret>	Kall mellom maskiner, plugin-API-nøkler
HMAC-signatur	X-RolChat-Signature: sha256=…	Innkommende webhooks fra systemene dine, se Webhooks
Ingen	-	Offentlige widgetendepunkter (/widget/…, /forms/…), avgrenset av nettsted og opprinnelse

For integrasjoner bruker du en API-nøkkel (et personlig tilgangstoken). Nøkler opprettes i Innstillinger → Plugins → RolChat API-nøkler, vises én gang og lagres bare som en hash. En nøkkel kan aldri gjøre mer enn medlemmet som opprettet den: tilgangsomfanget kontrolleres mot medlemmets gjeldende tillatelser ved hvert kall. Se Autentisering for JWT-levetider, headeren X-Account-Id og økter i flere selskaper.

Svarkonvolutt

En enkelt ressurs:

{
  "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 uten body (204 No Content etter en sletting) har likevel headeren X-Request-Id.

En feil:

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

code er maskinlesbar snake_case og er verdien du forgrener på; message er på engelsk og beregnet på logger. field og details er med når de er til hjelp, og inneholder aldri personopplysninger. API-et svarer aldri 200 med en errors-liste: hvis det finnes feil, er statusen 400 eller høyere. Den fullstendige kodelisten finner du på siden Feil.

Paginering

Listeendepunkter som kan vokse, bruker markørbasert paginering. Be om den første siden uten markør, og send deretter tilbake next_cursor du fikk, uendret:

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

• limit er 50 som standard og maksimalt 200; større verdier avvises med 400 validation_failed.
• Markører er ugjennomsiktige og utløper etter 24 timer (400 validation_failed med code: cursor_expired).
• Resultatene er konsistente med øyeblikksbildet fra den første siden: poster som slettes mellom sidene, forsvinner, og nye poster vises først når du starter på nytt uten markør.
• En Link-header med rel="next" og rel="prev" sendes også for klienter som foretrekker det.

Idempotens

Send en Idempotency-Key-header (en UUID eller ULID, opptil 255 tegn) med alle POST, PATCH eller DELETE:

• Den første forespørselen med en nøkkel kjøres, og statusen og bodyen lagres i 24 timer.
• En gjentakelse med samme nøkkel og samme body returnerer det lagrede svaret uten å utløse sideeffekter på nytt.
• En gjentakelse med samme nøkkel, men en annen body, avvises med 409 idempotency_key_conflict.

Bruk den for alle kall som oppretter noe med sideeffekter: sending av en melding, en e-post eller en SMS, oppringing, alt som faktureres. GET-forespørsler er alltid idempotente og ignorerer headeren.

Hastighetsgrenser

Grensene telles per minutt og er knyttet til kontoen, API-nøkkelen eller brukeren (til IP-adressen på ruter som ikke krever innlogging). Standardgrensene:

Gruppe	Standardgrense	Per minutt
Forespørsler uten innlogging (per IP)	60	per IP
Innlogget bruker (dashbordet)	1 000	per bruker
API-nøkkel	1 000	per nøkkel
Offentlige widgetendepunkter	60 per besøkende og 600 per nettverksadresse	per minutt
Innlogging (/auth/login)	5	per IP
Innkommende webhooks	300	per minutt
MCP-server	600	per minutt
OAuth-endepunkter	600	per minutt

Grensene er plattformens standardverdier og kan endres av operatøren; abonnementet ditt multipliserer dem ikke, og Enterprise-grenser avtales i kontrakten. Endepunkter med hastighetsgrense returnerer:

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

Når du overskrider en grense, er svaret 429 med code: rate_limited i errors-matrisen og en Retry-After-header i sekunder. Vent så lenge før neste kall. Ti mislykkede innlogginger låser kontoen i 30 minutter.

Størrelser og tidsavbrudd

Kategori	Maks. størrelse på forespørselsbody	Tidsavbrudd på serveren
Standard	1 MB	30 s
Melding med vedlegg	25 MB	30 s
CSV-import	50 MB	returnerer 202 og kjører i bakgrunnen
Bilder i kunnskapsbasen	10 MB	30 s
Masse-API	10 MB	30 s
Søk	1 MB	10 s
AI-forespørsler	1 MB	60 s
Widgetendepunkter	100 KB	30 s

For store bodyer får 413 payload_too_large. En oppstrømstjeneste som får tidsavbrudd, svarer 504 med code: upstream_timeout og et retry_after-hint når et nytt forsøk kan hjelpe.

Innholdstyper, datoer og ID-er

• Forespørsler og svar er application/json; charset=utf-8. Filopplastinger bruker multipart/form-data; CSV-eksporter returnerer text/csv. Ugyldig UTF-8 avvises med 400 validation_failed.
• Tidsstempler er ISO-8601 i UTC med millisekundpresisjon: 2026-04-20T14:23:45.123Z. Alle ISO-8601-forskyvninger godtas i inndata og normaliseres til UTC.
• Identifikatorer er ugjennomsiktige ULID-er eller UUID-er. Det finnes ingen numeriske ID-er, og e-postadresser eller telefonnumre vises aldri i en URL.

Kundeisolering og tillatelser

Hver autentisert forespørsel kjører innenfor én konto. En ressurs som tilhører en annen konto, eller et nettsted anroperens rolle ikke dekker, svarer 404 not_found i stedet for 403, slik at det aldri lekker ut at poster finnes. Et gyldig token uten den nødvendige tillatelsen (for eksempel contacts.delete) svarer 403 forbidden. Noen tillatelser har et omfangssuffiks (conversations.read:own, :team, :all) som begrenser hva en liste returnerer.

PATCH godtar bare skrivbare felt. id, account_id, created_at, updated_at og tilstandsfelt som resolved_at er skrivebeskyttet; sender du ett av dem, returneres 400 validation_failed med details.forbidden_fields. Tilstandsendringer går gjennom egne handlinger, som POST /tickets/:id/resolve.

Hver skriveoperasjon registreres i kontoens revisjonslogg.

Headere for observerbarhet

Hvert svar inneholder:

X-Request-Id: req_01HK…

Logg X-Request-Id. Det er det første kundestøtte spør etter.

CORS

Opprinnelsen til dashbordet i nettleseren er https://app.rolchat.com. Offentlige widgetendepunkter tillater alle opprinnelser, eller bare opprinnelsene du verifiserer for et nettsted. Kall mellom servere med en API-nøkkel er ikke underlagt CORS.

Avvikling

1. Endringen kunngjøres i endringsloggen, og det berørte endepunktet begynner å sende Deprecation: true og en Sunset-header med fjerningsdatoen.
2. Offentlige endepunkter fortsetter å virke i minst seks måneder etter kunngjøringen.
3. Fjerning skjer bare i en ny hovedversjon. Innenfor v1 er endringene kun tillegg.

Helse

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