API v2 Quellen und Training

Agentenquellen auflisten und erstellen, Dateien direkt in den Speicher hochladen, Dokumente löschen, den Trainingsstatus prüfen und das erneute Trainieren von Web-Quellen starten.

Verwenden Sie diese Endpunkte, um Text-, Q&A-, URL- und Dateiquellen zu verwalten und indexierte Web-Quellen neu zu trainieren. Jeder Endpunkt auf dieser Seite erfordert Authorization: Bearer YOUR_API_KEY und Zugriff auf {agentId}.

Gemeinsame Authentifizierungs-, Validierungs-, Kontingent- und Ressourcenfehler finden Sie im Fehlerkatalog.

Quellenobjekt

Field	Type	Notes
`id`	string	Dokument-ID.
`title`	string	Titel der Quelle.
`sourceType`	string	Gespeicherter Quelltyp, u. a. `web_crawl`, `file_upload`, `text_snippet` oder `qna_entry`.
`createdAt`	integer oder null	Unix-Zeitstempel in Sekunden.
`lastCrawledAt`	integer oder null	Unix-Zeitstempel in Sekunden.
`sourceMetadata`	any JSON value	Gespeicherte Metadaten der Quelle.

Quellen auflisten

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

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

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {agentId}.

Query	Required	Constraints
`limit`	Nein	Ganzzahl von 1 bis 100; Standardwert 20.
`cursor`	Nein	Undurchsichtiger Cursor der vorherigen Seite. Unverändert übergeben.
`sourceType`	Nein	`web_crawl`, `file_upload`, `text_snippet` oder `qna_entry`.

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'

Erfolg: 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
  }
}

Ungültige Limits, Cursor und Quelltypen führen zu 400 VALIDATION_INVALID_BODY.

Eine Textquelle hinzufügen

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

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

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {agentId}.

Body field	Required	Type and constraints
`title`	Ja	String mit 1 bis 200 Zeichen vor dem Trimmen; der akzeptierte Wert wird getrimmt.
`content`	Ja	Nicht leerer String, höchstens 262.144 UTF-8-Bytes (256 KB), nicht nur aus Leerraum bestehend.

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."}'

Erfolg: 201 Created

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

Ungültige Eingaben oder ein Verarbeitungsfehler ohne Speicherbezug führen zu 400 VALIDATION_INVALID_BODY. Ein Verarbeitungsfehler durch Erreichen des Speicherlimits führt zu 403 QUOTA_STORAGE_LIMIT.

Eine Q&A-Quelle hinzufügen

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

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

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {agentId}.

Body field	Required	Type and constraints
`title`	Ja	String mit 1 bis 200 Zeichen vor dem Trimmen; der akzeptierte Wert wird getrimmt.
`questions`	Ja	Array aus höchstens 10 Strings mit jeweils höchstens 500 Zeichen. Mindestens ein Eintrag muss ein Zeichen enthalten, das kein Leerraum ist.
`answer`	Ja	Nicht leerer String, höchstens 262.144 UTF-8-Bytes (256 KB), nicht nur aus Leerraum bestehend.

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."}'

Erfolg: 201 Created

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

Eine URL-Quelle hinzufügen oder neu trainieren

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

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

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {agentId}.

Body field	Required	Type and constraints
`url`	Ja	Nicht leere HTTP- oder HTTPS-URL mit einer Domain. Ein fehlendes Protokoll wird zu `https://` normalisiert. Loopback-, private, link-lokale und Unique-Local-Adressen, reservierte IP-Bereiche, Localhost-Varianten, interne TLDs sowie einteilige Hostnamen werden abgelehnt.

Das Übermitteln einer für den Agenten bereits indexierten URL erstellt einen Retraining-Job. Bei einer neuen URL wird zunächst die Speicherkapazität geprüft. Video-URLs erfordern zusätzlich Tarifzugriff auf die Video-Transkription.

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"}'

Erfolg: 202 Accepted

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

Ungültige Eingaben führen zu 400 VALIDATION_INVALID_BODY. Fehlender Zugriff auf die Video-Transkription führt zu 403 SUBSCRIPTION_API_RESTRICTED_PLAN; Speicher- oder Warteschlangen-Kontingentfehler führen zu 403 QUOTA_STORAGE_LIMIT; ein Fehler bei der Job-Erstellung ohne Kontingentbezug führt zu 500 INTERNAL_SERVER_ERROR.

Dateiquellen mit signierten Upload-URLs hinzufügen

Dateiquellen verwenden einen zweistufigen API-Ablauf, sodass die Datei-Bytes direkt von Ihrem Client in den privaten Speicher übertragen werden, statt über die API-Route zu laufen. Jede Datei darf höchstens 50 MB groß sein, und eine Anfrage kann höchstens 20 Dateien enthalten. Unterstützte Erweiterungen sind .pdf, .txt, .md, .docx, .xlsx und .pptx.

1. Signierte Upload-URLs erstellen

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

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

Senden Sie die ursprünglichen Dateinamen:

{
  "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"}]}'

Erfolg: 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. Die Datei-Bytes hochladen

Laden Sie jede Datei direkt mit PUT an ihre uploadUrl hoch:

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

Wenn Sie den Supabase-JavaScript-Client verwenden, übergeben Sie den passenden Pfad und das Token aus Schritt 1:

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

Ändern oder konstruieren Sie Speicherpfade nicht selbst. Die Registrierung akzeptiert nur Pfade, die in Schritt 1 für diesen Agenten zurückgegeben wurden.

3. Die hochgeladenen Dateien registrieren

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

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

Registrieren Sie nach Abschluss jedes direkten Uploads die zurückgegebenen Pfade zusammen mit ihren ursprünglichen Dateinamen:

{
  "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"
    }
  ]
}

Erfolg: 202 Accepted

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

Vor dem Start des Verarbeitungsjobs prüft die Registrierung, dass jedes Objekt existiert, nicht leer ist, höchstens 50 MB groß ist und zum angeforderten Agenten gehört. Ungültige oder fehlende Uploads führen zu 400 VALIDATION_INVALID_BODY; eine Ablehnung wegen des Speicherkontingents führt zu 403 QUOTA_STORAGE_LIMIT; Storage- oder Warteschlangenfehler führen zu 500 INTERNAL_SERVER_ERROR.

Eine Quelle löschen

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

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

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {agentId}.

{documentId} muss eine UUID sein, die von einer Quellenerstellung oder einer Listenantwort zurückgegeben wurde.

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'

Erfolg: 200 OK

{
  "deleted": true
}

Eine ungültige UUID führt zu 400 VALIDATION_INVALID_BODY. Eine gültige UUID, die kein Dokument des Agenten identifiziert, führt zu 404 RESOURCE_DOCUMENT_NOT_FOUND.

Trainingsstatus abrufen

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

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

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {agentId}.

Erfolg: 200 OK, mit einem reinen Statusobjekt.

Field	Type	Notes
`status`	string	`training`, wenn ein ausstehender oder laufender Job existiert; sonst `trained`, wenn ein Zeitstempel des letzten Trainings existiert; sonst `idle`.
`documentCount`	integer	Anzahl der Quelldokumente des Agenten.
`lastTrainedAt`	integer oder null	Unix-Zeitstempel in Sekunden.
`activeJob`	object oder null	Neuester ausstehender oder laufender Job.
`activeJob.id`	string	Job-ID.
`activeJob.status`	string	Gespeicherter Job-Status.
`activeJob.tasksCount`	integer	Gesamtanzahl der Aufgaben.
`activeJob.tasksCompletedCount`	integer	Anzahl abgeschlossener Aufgaben.
`activeJob.createdAt`	integer oder null	Unix-Zeitstempel in Sekunden.

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

Erneutes Trainieren von Web-Quellen starten

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

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {agentId}. Dieser Endpunkt erwartet keinen Request-Body.

Der Endpunkt trainiert indexierte Web-URLs neu, nicht Text-, Q&A- oder hochgeladene Dateiquellen.

Wenn mindestens eine indexierte URL existiert, ist der Erfolg 202 Accepted:

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

Wenn keine indexierten URLs existieren, ist der Erfolg 200 OK, und es wird kein Job erstellt:

{
  "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'

API v2 Quellen und Training

Agentenquellen auflisten und erstellen, Dateien direkt in den Speicher hochladen, Dokumente löschen, den Trainingsstatus prüfen und das erneute Trainieren von Web-Quellen starten.

Quellenobjekt

Quellen auflisten

Eine Textquelle hinzufügen

Eine Q&A-Quelle hinzufügen

Eine URL-Quelle hinzufügen oder neu trainieren

Dateiquellen mit signierten Upload-URLs hinzufügen

1. Signierte Upload-URLs erstellen

2. Die Datei-Bytes hochladen

3. Die hochgeladenen Dateien registrieren

Eine Quelle löschen

Trainingsstatus abrufen

Erneutes Trainieren von Web-Quellen starten

Referenz