API-översikt

Varje REST-endpoint i RolChat följer ett och samma kontrakt: samma bas-URL, samma svarsomslag, samma paginering, samma form på fel. Lär dig det en gång så läses varje endpoint-familj i endpoint-referensen på samma sätt.

Bas-URL och versionshantering

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

Versionen finns i sökvägen. Att lägga till valfria fält, nya endpoints eller nya frågeparametrar med standardvärden är inte en bakåtinkompatibel ändring och höjer inte versionen. Bakåtinkompatibla ändringar levereras som v2, och utfasade v1-endpoints fortsätter att fungera i minst sex månader efter att de har meddelats (se Utfasning).

Autentisering

Metod	Header	Används för
JWT bearer	Authorization: Bearer <access_token>	Interaktiva sessioner (webbappen, mobilappar)
API-nyckel	Authorization: Bearer rcp_<secret>	Anrop mellan maskiner, API-nycklar för plugins
HMAC-signatur	X-RolChat-Signature: sha256=…	Inkommande webhooks från dina system, se Webhooks
Ingen	-	Publika widget-endpoints (/widget/…, /forms/…), avgränsade av webbplats och ursprung

För integrationer använder du en API-nyckel (en personlig åtkomsttoken). Nycklar skapas under Inställningar → Plugins → RolChat API-nycklar, visas en gång och lagras bara som en hash. En nyckel kan aldrig göra mer än den medlem som skapade den: dess omfång kontrolleras mot medlemmens aktuella behörigheter vid varje anrop. Se Autentisering för JWT-livslängder, headern X-Account-Id och sessioner i flera företag.

Svarsomslag

En enskild resurs:

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

En lista:

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

Svar utan body (204 No Content efter en radering) innehåller ändå headern X-Request-Id.

Ett fel:

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

code är maskinläsbar snake_case och är värdet att förgrena på; message är på engelska och avsett för loggar. field och details finns med när de är till hjälp och innehåller aldrig personuppgifter. API:et svarar aldrig 200 med en errors-array: om fel finns är statusen 400 eller högre. Den fullständiga kodlistan finns på sidan Fel.

Paginering

List-endpoints som kan växa använder markörbaserad paginering. Begär den första sidan utan markör och skicka sedan tillbaka den next_cursor du fick, oförändrad:

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

• limit är som standard 50 och högst 200; större värden avvisas med 400 validation_failed.
• Markörer är ogenomskinliga och upphör att gälla efter 24 timmar (400 validation_failed med code: cursor_expired).
• Resultaten är konsekventa mot den ögonblicksbild som togs på den första sidan: poster som raderas mellan sidorna försvinner, nya poster visas först när du börjar om utan markör.
• En header Link med rel="next" och rel="prev" skickas också för klienter som föredrar den.

Idempotens

Skicka en header Idempotency-Key (ett UUID eller ULID, upp till 255 tecken) med valfri POST, PATCH eller DELETE:

• Den första förfrågan med en nyckel körs, och dess status och body lagras i 24 timmar.
• En upprepning med samma nyckel och samma body returnerar det lagrade svaret utan att köra sidoeffekterna igen.
• En upprepning med samma nyckel men en annan body avvisas med 409 idempotency_key_conflict.

Använd den för varje anrop som skapar något med sidoeffekter: att skicka ett meddelande, ett e-postmeddelande eller ett sms, att ringa ett samtal, allt som faktureras. GET-förfrågningar är alltid idempotenta och ignorerar headern.

Hastighetsgränser

Gränserna räknas per minut och knyts till kontot, API-nyckeln eller användaren (till IP-adressen på vägar som inte kräver inloggning). Standardtaken:

Hink	Standardgräns	Per minut
Förfrågningar utan inloggning (per IP-adress)	60	per IP-adress
Inloggad användare (instrumentpanelen)	1 000	per användare
API-nyckel	1 000	per nyckel
Publika widgetendpoints	60 per besökare och 600 per nätverksadress	per minut
Inloggning (/auth/login)	5	per IP-adress
Inkommande webhooks	300	per minut
MCP-server	600	per minut
OAuth-endpoints	600	per minut

Taken är plattformens standardvärden och kan ändras av operatören; din plan multiplicerar dem inte, och Enterprise-gränser avtalas i ditt avtal. Endpoints med hastighetsbegränsning returnerar:

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

När du överskrider en gräns blir svaret 429 med code: rate_limited i errors-listan och en header Retry-After i sekunder. Vänta så länge innan nästa anrop. Tio misslyckade inloggningar låser kontot i 30 minuter.

Storlekar och tidsgränser

Kategori	Största förfrågans body	Serverns tidsgräns
Standard	1 MB	30 s
Meddelande med bilagor	25 MB	30 s
CSV-import	50 MB	returnerar 202 och körs i bakgrunden
Bilder i kunskapsbasen	10 MB	30 s
Bulk-API	10 MB	30 s
Sökning	1 MB	10 s
AI-förfrågningar	1 MB	60 s
Widget-endpoints	100 KB	30 s

För stora bodies får 413 payload_too_large. En uppströmstjänst som överskrider tidsgränsen svarar 504 med code: upstream_timeout och en ledtråd retry_after när ett nytt försök kan hjälpa.

Innehållstyper, datum och ID:n

• Förfrågningar och svar är application/json; charset=utf-8. Filuppladdningar använder multipart/form-data; CSV-exporter returnerar text/csv. Ogiltig UTF-8 avvisas med 400 validation_failed.
• Tidsstämplar är ISO-8601 i UTC med millisekundprecision: 2026-04-20T14:23:45.123Z. Varje ISO-8601-förskjutning accepteras i indata och normaliseras till UTC.
• Identifierare är ogenomskinliga ULID:er eller UUID:er. Det finns inga numeriska ID:n, och e-postadresser eller telefonnummer förekommer aldrig i en URL.

Klientisolering och behörigheter

Varje autentiserad förfrågan körs inom ett konto. En resurs som tillhör ett annat konto, eller en webbplats som anroparens roll inte omfattar, svarar 404 not_found i stället för 403, så att det aldrig läcker ut att poster finns. En giltig token utan den behörighet som krävs (till exempel contacts.delete) svarar 403 forbidden. Vissa behörigheter har ett omfångssuffix (conversations.read:own, :team, :all) som begränsar vad en lista returnerar.

PATCH accepterar bara skrivbara fält. id, account_id, created_at, updated_at och tillståndsfält som resolved_at är skrivskyddade; skickar du ett sådant returneras 400 validation_failed med details.forbidden_fields. Tillståndsändringar görs via särskilda åtgärder som POST /tickets/:id/resolve.

Varje skrivning registreras i kontots granskningslogg.

Headers för observerbarhet

Varje svar innehåller:

X-Request-Id: req_01HK…

Logga X-Request-Id. Det är det första supporten frågar efter.

CORS

Ursprunget för instrumentpanelen i webbläsaren är https://app.rolchat.com. Publika widget-endpoints tillåter alla ursprung, eller bara de ursprung du verifierar för en webbplats. Anrop mellan servrar med en API-nyckel omfattas inte av CORS.

Utfasning

1. Ändringen meddelas i ändringsloggen och den berörda endpointen börjar skicka Deprecation: true och en header Sunset med datumet för borttagningen.
2. Publika endpoints fortsätter att fungera i minst sex månader efter meddelandet.
3. Borttagning sker bara i en ny huvudversion. Inom v1 är ändringarna enbart tillägg.

Hälsa

Varje tjänst exponerar /healthz (liveness) och /readyz (readiness).