API v2

API v2 is een gestructureerde REST API voor het beheren van agents en het bouwen van eigen chatervaringen. Het voegt agentbeheer, streaming chat, gespreksgeschiedenis, berichtfeedback, contacten, leads, bronnen, instellingen en trainingsendpoints toe.

Voor API-toegang heb je minimaal het Hobby-abonnement nodig, met actieve facturering.

Basis-URL

https://your-domain.com/api/v2

Authenticatie

Behalve voor de statuscontrole stuur je je werkruimte-API-sleutel mee als bearer-token:

Authorization: Bearer YOUR_API_KEY

Maak of trek API-sleutels in via Instellingen > API-sleutels.

Responsformaat

De meeste succesvolle responses geven een resource-object of een data-envelop terug:

{
  "data": []
}

Lijstendpoints bevatten cursorpaginering:

{
  "data": [],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 0
  }
}

Fouten gebruiken een gestructureerd error-object:

{
  "error": {
    "code": "VALIDATION_INVALID_BODY",
    "message": "Invalid request body"
  }
}

Elke v2-respons bevat een x-request-id-header. Vermeld deze waarde wanneer je contact opneemt met support over een API-aanvraag.

Bereik van gesprekken

Alleen-lezen gespreksendpoints gebruiken standaard source=api_v2. Zet source=widget om widget- en Playground-gesprekken terug te geven; Playground-rijen worden opgeslagen met de bron widget. Zet source=all om API v2-, widget- en Playground-gesprekken terug te geven. Resultaten blijven altijd beperkt tot de agent van het geauthenticeerde account. Een ongeldige source-waarde of meer dan één source-queryparameter geeft 400 VALIDATION_INVALID_BODY terug. Chat-vervolg, retry, feedback, berichtenlijsten en per-gebruikersreads blijven beperkt tot API v2-gesprekken.

Health-check

GET /api/v2/health

De health-check vereist geen authenticatie.

Succes: 200 OK

{
  "status": "ok",
  "timestamp": 1784332800
}

timestamp is de huidige Unix-tijdstempel in seconden.

Chat

POST /api/v2/agents/{agentId}/chat

Aanvraag:

{
  "message": "What plans do you offer?",
  "conversationId": "optional-existing-conversation-id",
  "userId": "optional-user-id",
  "stream": true
}

Streamingresponses gebruiken Server-Sent Events. De stream bevat de events message-start, text-start, text-delta, text-end, message-metadata, finish en [DONE]. Bij een fout in de stream of in de voltooiingshook wordt een error-event uitgezonden met error.code op CHAT_STREAMING_ERROR; deze SSE-only protocolcode staat los van de gestructureerde REST-foutcatalogus. message-metadata bevat het assistant-bericht-ID wanneer opslag lukt, plus het gespreks-ID, gebruikers-ID, finish reason en gebruik. messageId is null wanneer er geen assistant-bericht is opgeslagen. Wanneer het antwoord pauzeert op een client-side actie, zendt de stream ook een tool-call-event uit met { "id", "name", "arguments" }; dien het resultaat in bij het tool-result-endpoint om het gesprek te hervatten — de response op dat verzoek streamt het vervolg.

Niet-streamingresponses geven het volgende terug:

{
  "data": {
    "id": "123",
    "role": "assistant",
    "parts": [{ "type": "text", "text": "..." }],
    "pendingToolCall": null,
    "metadata": {
      "userMessageId": "122",
      "conversationId": "abc123",
      "userId": "user_123",
      "finishReason": "stop",
      "usage": { "credits": 1 }
    }
  }
}

De waarden van data.id en metadata.userMessageId zijn numerieke bericht-ID's, geserialiseerd als strings, of null wanneer het bijbehorende bericht niet is opgeslagen. metadata.userId is het meegegeven/opgeslagen gebruikers-ID, of null. pendingToolCall is null, tenzij het antwoord is gepauzeerd op een client-side tool-aanroep; in dat geval bevat het { "id", "name", "arguments" } voor het tool-result-endpoint.

Overzicht van endpoints

Feedback

Gebruik feedback om API v2-assistantberichten te markeren als positive, negative, of null. Zie Gesprekken, berichten en feedback voor het aanvraagschema, de respons en het foutgedrag.

Paginering

Behandel cursors als ondoorzichtige tokens die door de API worden geretourneerd. Geef de waarde van pagination.cursor ongewijzigd door bij de volgende aanvraag; construeer of decodeer deze niet.

Contacten accepteren ook search. Leads accepteren de inclusieve ISO 8601-datumfilters createdAfter en createdBefore. Bronnen accepteren sourceType met web_crawl, file_upload, text_snippet, of qna_entry.

Cursorformaten zijn een intern implementatiedetail. Clients moeten elke cursor als ondoorzichtig behandelen en ongewijzigd doorgeven, zonder deze te construeren of te decoderen.

Veelvoorkomende fouten

Zie de volledige API v2-foutcatalogus voor alle 27 gedeclareerde codes, HTTP-statussen, triggers en gereserveerde codes.

Referentie

• Foutcatalogus
• Agents en instellingen
• Gesprekken, berichten, retries en feedback
• Bronnen en training
• Contacten en leads
• Instagram-kanaal

Volgende stappen

• Een API-sleutel aanmaken
• Identiteitsverificatie instellen
• API v2-fouten bekijken
• Agents en instellingen beheren
• Werken met gesprekken
• Bronnen en training beheren
• Contacten en leads beheren
• Instagram-kanaal beheren