API v2-bronnen en -training

Gebruik deze endpoints om tekst-, Q&A-, URL- en bestandsbronnen te beheren en om geïndexeerde webbronnen opnieuw te trainen. Elk endpoint op deze pagina vereist Authorization: Bearer YOUR_API_KEY en toegang tot {agentId}.

Zie de foutcatalogus voor gedeelde authenticatie-, validatie-, quota- en resourcefouten.

Bronobject

Bronnen weergeven

Pad: /api/v2/agents/{agentId}/sources

GET /api/v2/agents/{agentId}/sources

Authenticatie: Bearer API-sleutel met toegang tot {agentId}.

curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/sources?sourceType=text_snippet&limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Succes: 200 OK

{
  "data": [
    {
      "id": "41b4c1d3-887d-46a5-95ae-c761922c6bc7",
      "title": "Refund policy",
      "sourceType": "text_snippet",
      "createdAt": 1784332800,
      "lastCrawledAt": null,
      "sourceMetadata": null
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 1
  }
}

Ongeldige limieten, cursors en brontypen geven 400 VALIDATION_INVALID_BODY terug.

Een tekstbron toevoegen

Pad: /api/v2/agents/{agentId}/sources/text

POST /api/v2/agents/{agentId}/sources/text

Authenticatie: Bearer API-sleutel met toegang tot {agentId}.

curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/sources/text' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Refund policy","content":"Refunds are available within 30 days."}'

Succes: 201 Created

{
  "documentId": "41b4c1d3-887d-46a5-95ae-c761922c6bc7"
}

Ongeldige invoer of een verwerkingsfout die geen opslaglimiet betreft, geeft 400 VALIDATION_INVALID_BODY terug. Een opslaglimietfout tijdens verwerking geeft 403 QUOTA_STORAGE_LIMIT terug.

Een Q&A-bron toevoegen

Pad: /api/v2/agents/{agentId}/sources/qna

POST /api/v2/agents/{agentId}/sources/qna

Authenticatie: Bearer API-sleutel met toegang tot {agentId}.

curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/sources/qna' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Shipping time","questions":["How long does shipping take?","When will my order arrive?"],"answer":"Standard shipping takes 3–5 business days."}'

Succes: 201 Created

{
  "documentId": "531a3fbe-40c2-4d22-a524-1f4a70f509f1"
}

Ongeldige invoer of een verwerkingsfout die geen opslaglimiet betreft, geeft 400 VALIDATION_INVALID_BODY terug. Een opslaglimietfout tijdens verwerking geeft 403 QUOTA_STORAGE_LIMIT terug.

Een URL-bron toevoegen of opnieuw trainen

Pad: /api/v2/agents/{agentId}/sources/url

POST /api/v2/agents/{agentId}/sources/url

Authenticatie: Bearer API-sleutel met toegang tot {agentId}.

Als je een URL indient die al voor de agent is geïndexeerd, wordt een taak voor opnieuw trainen aangemaakt. Bij een nieuwe URL wordt eerst de opslagcapaciteit gecontroleerd. Video-URL's vereisen bovendien toegang tot video-transcriptie via het abonnement.

curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/sources/url' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://docs.example.com/getting-started"}'

Succes: 202 Accepted

{
  "jobId": "c3c61f67-70fe-42da-a843-24112ded8aeb",
  "isRetrain": false
}

Ongeldige invoer geeft 400 VALIDATION_INVALID_BODY terug. Ontbrekende toegang tot video-transcriptie geeft 403 SUBSCRIPTION_API_RESTRICTED_PLAN terug; fouten met het opslag- of wachtrijquotum geven 403 QUOTA_STORAGE_LIMIT terug; een fout bij het aanmaken van de taak die geen quotum betreft, geeft 500 INTERNAL_SERVER_ERROR terug.

Bestandsbronnen toevoegen met ondertekende upload-URL's

Bestandsbronnen gebruiken een tweestaps-API-flow, zodat bestandsbytes rechtstreeks van je client naar privéopslag gaan in plaats van via de API-route te lopen. Elk bestand mag maximaal 50 MB groot zijn, en één aanvraag mag maximaal 20 bestanden bevatten. Ondersteunde extensies zijn .pdf, .txt, .md, .docx, .xlsx, en .pptx.

1. Ondertekende upload-URL's aanmaken

Pad: /api/v2/agents/{agentId}/sources/file/upload-url

POST /api/v2/agents/{agentId}/sources/file/upload-url

Stuur de oorspronkelijke bestandsnamen mee:

{
  "files": [
    { "fileName": "product-guide.pdf" },
    { "fileName": "faq.md" }
  ]
}

curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/sources/file/upload-url' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"files":[{"fileName":"product-guide.pdf"},{"fileName":"faq.md"}]}'

Succes: 200 OK

{
  "files": [
    {
      "fileName": "product-guide.pdf",
      "storagePath": "chatbot-955f28f1-8515-40bb-802c-f3f730bf0343/V1StGXR8_Z5jdHi6-product-guide.pdf",
      "uploadUrl": "https://storage.example.com/storage/v1/object/upload/sign/training_files/chatbot-955f28f1-8515-40bb-802c-f3f730bf0343/V1StGXR8_Z5jdHi6-product-guide.pdf?token=SIGNED_TOKEN",
      "token": "SIGNED_TOKEN"
    },
    {
      "fileName": "faq.md",
      "storagePath": "chatbot-955f28f1-8515-40bb-802c-f3f730bf0343/N5jFt4Z9kSC3vHqA-faq.md",
      "uploadUrl": "https://storage.example.com/storage/v1/object/upload/sign/training_files/chatbot-955f28f1-8515-40bb-802c-f3f730bf0343/N5jFt4Z9kSC3vHqA-faq.md?token=SIGNED_TOKEN",
      "token": "SIGNED_TOKEN"
    }
  ]
}

2. De bestandsbytes uploaden

Upload elk bestand rechtstreeks naar de bijbehorende uploadUrl met PUT:

await fetch(uploadUrl, {
  method: 'PUT',
  headers: { 'Content-Type': file.type },
  body: file,
});

Als je de Supabase JavaScript-client gebruikt, geef dan het bijbehorende pad en token uit stap 1 mee:

await supabase.storage
  .from('training_files')
  .uploadToSignedUrl(storagePath, token, file);

Wijzig opslagpaden nooit en stel ze niet zelf samen. Bij registratie worden alleen paden geaccepteerd die in stap 1 voor deze agent zijn teruggegeven.

3. De geüploade bestanden registreren

Pad: /api/v2/agents/{agentId}/sources/file

POST /api/v2/agents/{agentId}/sources/file

Registreer, zodra elke directe upload is voltooid, de teruggegeven paden samen met hun oorspronkelijke bestandsnamen:

{
  "files": [
    {
      "storagePath": "chatbot-955f28f1-8515-40bb-802c-f3f730bf0343/V1StGXR8_Z5jdHi6-product-guide.pdf",
      "fileName": "product-guide.pdf"
    },
    {
      "storagePath": "chatbot-955f28f1-8515-40bb-802c-f3f730bf0343/N5jFt4Z9kSC3vHqA-faq.md",
      "fileName": "faq.md"
    }
  ]
}

Succes: 202 Accepted

{
  "jobId": 321,
  "fileCount": 2
}

Voordat de verwerkingstaak start, controleert de registratie of elk object bestaat, niet leeg is, niet groter is dan 50 MB, en bij de gevraagde agent hoort. Ongeldige of ontbrekende uploads geven 400 VALIDATION_INVALID_BODY terug; een weigering vanwege het opslagquotum geeft 403 QUOTA_STORAGE_LIMIT terug; fouten met opslag of de wachtrij geven 500 INTERNAL_SERVER_ERROR terug.

Een bron verwijderen

Pad: /api/v2/agents/{agentId}/sources/{documentId}

DELETE /api/v2/agents/{agentId}/sources/{documentId}

Authenticatie: Bearer API-sleutel met toegang tot {agentId}.

{documentId} moet een UUID zijn die is teruggegeven door een response voor het aanmaken of weergeven van bronnen.

curl -X DELETE 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/sources/41b4c1d3-887d-46a5-95ae-c761922c6bc7' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Succes: 200 OK

{
  "deleted": true
}

Een ongeldige UUID geeft 400 VALIDATION_INVALID_BODY terug. Een geldige UUID die geen document voor de agent aanduidt, geeft 404 RESOURCE_DOCUMENT_NOT_FOUND terug.

Trainingsstatus ophalen

Pad: /api/v2/agents/{agentId}/train

GET /api/v2/agents/{agentId}/train

Authenticatie: Bearer API-sleutel met toegang tot {agentId}.

Succes: 200 OK, met een statusobject zonder envelop.

{
  "status": "training",
  "documentCount": 12,
  "lastTrainedAt": 1784246400,
  "activeJob": {
    "id": "c3c61f67-70fe-42da-a843-24112ded8aeb",
    "status": "running",
    "tasksCount": 8,
    "tasksCompletedCount": 3,
    "createdAt": 1784332800
  }
}

Opnieuw trainen van webbronnen starten

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

Authenticatie: Bearer API-sleutel met toegang tot {agentId}. Dit endpoint heeft geen aanvraagtekst nodig.

Het endpoint traint geïndexeerde web-URL's opnieuw, niet tekst-, Q&A-, of geüploade bestandsbronnen.

Als er minimaal één geïndexeerde URL bestaat, is de response bij succes 202 Accepted:

{
  "jobId": "c3c61f67-70fe-42da-a843-24112ded8aeb",
  "count": 8,
  "message": "Retraining started for 8 URLs"
}

Als er geen geïndexeerde URL's bestaan, is de response bij succes 200 OK, en wordt er geen taak aangemaakt:

{
  "jobId": null,
  "count": 0,
  "message": "No web sources to retrain"
}

curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/train' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Gerelateerde referentie

• API v2-overzicht
• API v2-foutcatalogus
• Agents en trainingsinstellingen