API v2 – źródła i trenowanie

Za pomocą tych punktów końcowych zarządzasz źródłami tekstowymi, Q&A, URL i plikowymi oraz ponownie trenujesz zindeksowane źródła internetowe. Każdy punkt końcowy na tej stronie wymaga nagłówka Authorization: Bearer YOUR_API_KEY oraz dostępu do {agentId}.

Wspólne błędy uwierzytelniania, walidacji, limitów i zasobów opisano w katalogu błędów.

Obiekt źródła

Lista źródeł

Ścieżka: /api/v2/agents/{agentId}/sources

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

Uwierzytelnianie: klucz API typu Bearer z dostępem do {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'

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

Nieprawidłowe wartości limit, cursor oraz sourceType skutkują błędem 400 VALIDATION_INVALID_BODY.

Dodawanie źródła tekstowego

Ścieżka: /api/v2/agents/{agentId}/sources/text

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

Uwierzytelnianie: klucz API typu Bearer z dostępem do {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."}'

Sukces: 201 Created

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

Nieprawidłowe dane wejściowe lub błąd przetwarzania niezwiązany z pamięcią masową skutkuje błędem 400 VALIDATION_INVALID_BODY. Przekroczenie limitu pamięci masowej podczas przetwarzania skutkuje błędem 403 QUOTA_STORAGE_LIMIT.

Dodawanie źródła pytań i odpowiedzi

Ścieżka: /api/v2/agents/{agentId}/sources/qna

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

Uwierzytelnianie: klucz API typu Bearer z dostępem do {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."}'

Sukces: 201 Created

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

Nieprawidłowe dane wejściowe lub błąd przetwarzania niezwiązany z pamięcią masową skutkuje błędem 400 VALIDATION_INVALID_BODY. Przekroczenie limitu pamięci masowej podczas przetwarzania skutkuje błędem 403 QUOTA_STORAGE_LIMIT.

Dodawanie lub ponowne trenowanie źródła URL

Ścieżka: /api/v2/agents/{agentId}/sources/url

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

Uwierzytelnianie: klucz API typu Bearer z dostępem do {agentId}.

Przesłanie adresu URL już zindeksowanego dla danego agenta tworzy zadanie ponownego trenowania. W przypadku nowego adresu URL najpierw sprawdzana jest dostępna pamięć masowa. Adresy URL prowadzące do wideo wymagają dodatkowo dostępu do transkrypcji wideo w ramach planu.

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

Sukces: 202 Accepted

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

Nieprawidłowe dane wejściowe skutkują błędem 400 VALIDATION_INVALID_BODY. Brak dostępu do transkrypcji wideo skutkuje błędem 403 SUBSCRIPTION_API_RESTRICTED_PLAN; przekroczenie limitu pamięci masowej lub kolejki skutkuje błędem 403 QUOTA_STORAGE_LIMIT; błąd tworzenia zadania niezwiązany z limitem skutkuje błędem 500 INTERNAL_SERVER_ERROR.

Dodawanie źródeł plikowych za pomocą podpisanych adresów URL przesyłania

Źródła plikowe wykorzystują dwuetapowy przepływ API, dzięki czemu bajty pliku trafiają bezpośrednio z Twojego klienta do prywatnej pamięci masowej, zamiast przechodzić przez trasę API. Każdy plik może mieć maksymalnie 50 MB, a jedno żądanie może zawierać maksymalnie 20 plików. Obsługiwane rozszerzenia to .pdf, .txt, .md, .docx, .xlsx i .pptx.

1. Tworzenie podpisanych adresów URL przesyłania

Ścieżka: /api/v2/agents/{agentId}/sources/file/upload-url

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

Wyślij oryginalne nazwy plików:

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

Sukces: 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. Przesyłanie bajtów pliku

Prześlij każdy plik bezpośrednio pod jego adres uploadUrl metodą PUT:

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

Jeśli korzystasz z klienta JavaScript Supabase, przekaż odpowiadającą ścieżkę i token z kroku 1:

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

Nie zmieniaj ani nie konstruuj ścieżek pamięci masowej samodzielnie. Rejestracja akceptuje wyłącznie ścieżki zwrócone dla tego agenta w kroku 1.

3. Rejestrowanie przesłanych plików

Ścieżka: /api/v2/agents/{agentId}/sources/file

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

Po zakończeniu każdego bezpośredniego przesyłania zarejestruj zwrócone ścieżki wraz z oryginalnymi nazwami plików:

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

Sukces: 202 Accepted

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

Przed rozpoczęciem zadania przetwarzania rejestracja sprawdza, czy każdy obiekt istnieje, jest niepusty, nie przekracza 50 MB i należy do wskazanego agenta. Nieprawidłowe lub brakujące przesłania skutkują błędem 400 VALIDATION_INVALID_BODY; odmowa z powodu limitu pamięci masowej skutkuje błędem 403 QUOTA_STORAGE_LIMIT; błędy pamięci masowej lub kolejki skutkują błędem 500 INTERNAL_SERVER_ERROR.

Usuwanie źródła

Ścieżka: /api/v2/agents/{agentId}/sources/{documentId}

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

Uwierzytelnianie: klucz API typu Bearer z dostępem do {agentId}.

{documentId} musi być identyfikatorem UUID zwróconym przez odpowiedź tworzenia źródła lub listy źródeł.

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'

Sukces: 200 OK

{
  "deleted": true
}

Nieprawidłowy UUID skutkuje błędem 400 VALIDATION_INVALID_BODY. Prawidłowy UUID, który nie wskazuje dokumentu należącego do danego agenta, skutkuje błędem 404 RESOURCE_DOCUMENT_NOT_FOUND.

Pobieranie stanu trenowania

Ścieżka: /api/v2/agents/{agentId}/train

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

Uwierzytelnianie: klucz API typu Bearer z dostępem do {agentId}.

Sukces: 200 OK wraz z nieopakowanym obiektem stanu.

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

Rozpoczynanie ponownego trenowania źródeł internetowych

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

Uwierzytelnianie: klucz API typu Bearer z dostępem do {agentId}. Ten punkt końcowy nie przyjmuje treści żądania.

Ten punkt końcowy ponownie trenuje zindeksowane adresy URL, a nie źródła tekstowe, Q&A ani przesłane pliki.

Gdy istnieje co najmniej jeden zindeksowany adres URL, odpowiedź w przypadku powodzenia to 202 Accepted:

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

Gdy nie ma żadnych zindeksowanych adresów URL, odpowiedź w przypadku powodzenia to 200 OK, a żadne zadanie nie jest tworzone:

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

Powiązane materiały

• Przegląd API v2
• Katalog błędów API v2
• Agenci i ustawienia trenowania