Overzicht van de API

Sleutels, bereik, de vorm van elk antwoord, fouten, limieten en paginering. Alles wat voor de hele REST-API geldt.

Wat je in het dashboard kunt doen, kun je ook via de API, onder dezelfde regels. Een limiet van je abonnement die je in het dashboard tegenhoudt, houdt een sleutel op dezelfde manier tegen, en bij elke wijziging die een sleutel aanbrengt, staat in het auditlog welke sleutel dat was.

Basisadres

https://chatterlab.ai/api/v1

Het exacte adres voor jouw werkruimte staat onder Instellingen, in het blok API-sleutels. Gebruik je je eigen domein, dan is het je eigen hostnaam, en op je hostnaam bereikt een sleutel alleen je eigen werkruimte.

Sleutels

Maak een sleutel onder Instellingen, API-sleutels. Je kiest een naam, wat hij mag (zijn bereik) en, als je wilt, één agent om hem aan te koppelen.

Sleutels, en daarmee de API en de MCP-server, horen bij Studio en hoger. Op Free en Starter kun je geen sleutel maken. Een sleutel die op een hoger abonnement is gemaakt, blijft bestaan, maar wordt geweigerd met api_not_in_plan zolang je werkruimte op een lager abonnement dan Studio zit. Hij werkt weer zodra je teruggaat naar Studio of hoger.

Een sleutel ziet eruit als cl_ gevolgd door 48 tekens. Je ziet hem één keer. Wij bewaren er alleen een vingerafdruk van, dus een kwijtgeraakte sleutel is niet terug te halen, alleen te vervangen.
Stuur hem mee met elk verzoek:

curl https://chatterlab.ai/api/v1/agents \
  -H "Authorization: Bearer cl_your_key"

Een werkruimte heeft hoogstens 25 sleutels. Intrekken werkt meteen.
Sleutels horen op een server. Zet er nooit een in een webpagina of in een app die een gebruiker kan openen. Gebruik voor een chat op een website de widget, die geen sleutel nodig heeft.

Bereik

Een sleutel kan één van drie dingen. Het zijn geen treden van een ladder: elk bereik is er voor iets anders. In het dashboard heten ze Lezen, Chatten en Beheren.

Bereik	Mag	Mag niet
`read`	Kijken: agents, bronnen, gesprekken, analysecijfers	Vragen stellen, iets wijzigen
`chat`	Een agent vragen stellen	Gesprekken of instellingen lezen, iets wijzigen
`manage`	Alles: lezen, vragen stellen, aanmaken, wijzigen, verwijderen

Een sleutel in de backend van je website die alleen vragen stelt, kan dus geen gesprekken van andere bezoekers lezen als hij uitlekt, en een sleutel voor een rapportagetool kan je credits niet opmaken. Geef elke integratie het smalste bereik dat volstaat.

Een sleutel gekoppeld aan één agent

Koppel een sleutel aan een agent en hij ziet alleen die agent. Elke andere agent antwoordt met not_found, alsof hij niet bestaat. Zo'n sleutel krijgt ook niets te horen over je werkruimte: niet je abonnement, niet je credits en niet je andere sleutels. Het is de sleutel om aan de ontwikkelaars van een klant te geven.

Antwoorden van de API

Elk antwoord is JSON, in een van drie vormen.

{ "data": { "id": "ag_...", "name": "Support" } }

{ "data": [ ... ], "pagination": { "nextCursor": "..." } }

{ "error": { "code": "invalid_request", "message": "...", "details": [ { "field": "name", "message": "..." } ] } }

Tijden zijn ISO 8601 in UTC. Identifiers zijn strings met een voorvoegsel dat zegt wat ze zijn: ag_ een agent, src_ een bron, conv_ een gesprek, msg_ een bericht. Elk antwoord heeft een header x-request-id. Vermeld die als je ons over een verzoek schrijft.

De body van een verzoek is strikt

Stuur JSON met Content-Type: application/json. Een veld dat we niet kennen, is een fout en niet iets wat we negeren: een verkeerd gespeld temprature levert je een 400 op die het veld noemt, in plaats van een instelling die stilletjes nooit is veranderd.

Fouten

De code is stabiel en bedoeld voor je programma. De message is bedoeld voor een mens en kan anders geformuleerd worden.

Code	Status	Betekenis
`invalid_request`	400	De body of een parameter klopt niet. `details` noemt de velden.
`unsafe_url`	400	Het adres om te crawlen staat niet op het openbare internet.
`unauthorized`	401	De sleutel ontbreekt, is misvormd of is ingetrokken.
`credits_exhausted`	402	De credits van de werkruimte zijn op voor deze maand.
`model_not_allowed`	402	Dat model zit niet in het abonnement.
`agent_limit_reached`	402	Het abonnement heeft geen ruimte voor nog een agent.
`agent_paused`	402	De agent valt buiten wat het abonnement dekt.
`storage_limit_reached`	402	Hiermee zou de agent over zijn opslaglimiet gaan.
`api_not_in_plan`	402	Het abonnement bevat de API en MCP niet.
`clients_not_in_plan`	402	Het abonnement bevat geen klanten. Die horen bij Agency en hoger.
`forbidden`	403	Het bereik van de sleutel staat dit niet toe.
`high_risk_use_case`	403	Werving, kredietscoring en gezondheidszorg worden als toepassing geweigerd.
`not_found`	404	Niets met dat id is zichtbaar voor deze sleutel.
`key_limit_reached`	409	De werkruimte heeft het maximale aantal sleutels.
`already_corrected`	409	Dat antwoord heeft al een correctie.
`agent_busy`	409	De agent is nog iets aan het leren. Train opnieuw zodra zijn bronnen klaar zijn.
`file_too_large`	413	Het bestand of de afbeelding op dat adres is groter dan mag worden opgehaald.
`unsupported_file_type`	415	Het bestand of de afbeelding op dat adres is geen soort die we aannemen.
`fetch_failed`	422	Het adres gaf ons het bestand niet. De melding zegt wat er terugkwam.
`asked_with_file`	422	Dat antwoord hoorde bij een vraag met een bestand, en een vraag-antwoordpaar kan dat bestand niet dragen.
`rate_limited`	429	Te veel verzoeken. Wacht `Retry-After` seconden.
`internal_error`	500	Onze fout. Later opnieuw proberen is redelijk.

Een 402 betekent altijd "een kwestie van je abonnement": opnieuw proberen helpt niet, een wijziging in het abonnement of de credits wel.

Limiet op verzoeken

120 verzoeken per minuut per sleutel. Elk antwoord vertelt je waar je staat:

Header	Betekenis
`x-ratelimit-limit`	Toegestane verzoeken per minuut
`x-ratelimit-remaining`	Verzoeken die je deze minuut nog over hebt
`x-ratelimit-reset`	Seconden tot de minuut voorbij is
`Retry-After`	Bij een `429`: het aantal seconden dat je moet wachten

De limiet wordt gedeeld tussen de API en MCP als beide dezelfde sleutel gebruiken.

Paginering

Bronnen en gesprekken komen met 50 tegelijk, de nieuwste eerst. Vraag er tot 100 op met ?limit=. Is er meer, dan bevat pagination.nextCursor een waarde die je als ?cursor= meegeeft voor de volgende pagina. Is die null, dan heb je alles. Een cursor is niet bedoeld om te lezen of aan te passen: geef hem ongewijzigd terug. Agents komen allemaal in één keer, de oudste eerst, in dezelfde vorm, waarin nextCursor altijd null is.

Stabiliteit

Binnen /api/v1 voegen we toe en halen we niets weg: er kunnen nieuwe velden, nieuwe endpoints en nieuwe foutcodes bijkomen, en de bestaande houden hun naam en betekenis. Schrijf je client zo dat hij velden negeert die hij niet kent.

Hierna: de API-referentie.