API v2 Fonti e addestramento

Usa questi endpoint per gestire le fonti di testo, Q&A, URL e file, e per riaddestrare le fonti web indicizzate. Ogni endpoint di questa pagina richiede Authorization: Bearer YOUR_API_KEY e l'accesso a {agentId}.

Consulta il catalogo degli errori per gli errori comuni di autenticazione, validazione, quota e risorse.

Oggetto fonte

Elenca le fonti

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

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

Autenticazione: Chiave API Bearer con accesso a {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'

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

Limiti, cursori e tipi di fonte non validi restituiscono 400 VALIDATION_INVALID_BODY.

Aggiungi una fonte di testo

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

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

Autenticazione: Chiave API Bearer con accesso a {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."}'

Successo: 201 Created

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

Un input non valido o un errore di elaborazione non legato allo storage restituisce 400 VALIDATION_INVALID_BODY. Un errore di elaborazione dovuto al limite di storage restituisce 403 QUOTA_STORAGE_LIMIT.

Aggiungi una fonte Q&A

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

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

Autenticazione: Chiave API Bearer con accesso a {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."}'

Successo: 201 Created

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

Un input non valido o un errore di elaborazione non legato allo storage restituisce 400 VALIDATION_INVALID_BODY. Un errore di elaborazione dovuto al limite di storage restituisce 403 QUOTA_STORAGE_LIMIT.

Aggiungi o riaddestra una fonte URL

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

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

Autenticazione: Chiave API Bearer con accesso a {agentId}.

Inviare un URL già indicizzato per l'agente crea un job di riaddestramento. Per un nuovo URL viene prima verificata la capacità di storage disponibile. Gli URL video richiedono anche l'accesso alla trascrizione video previsto dal piano.

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

Successo: 202 Accepted

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

Un input non valido restituisce 400 VALIDATION_INVALID_BODY. La mancanza di accesso alla trascrizione video restituisce 403 SUBSCRIPTION_API_RESTRICTED_PLAN; gli errori di quota su storage o coda restituiscono 403 QUOTA_STORAGE_LIMIT; un errore nella creazione del job non legato alla quota restituisce 500 INTERNAL_SERVER_ERROR.

Aggiungi fonti file con URL di caricamento firmati

Le fonti file usano un flusso API in due passaggi, in modo che i byte del file viaggino direttamente dal tuo client allo storage privato, senza passare attraverso la rotta API. Ogni file può avere una dimensione massima di 50 MB e una richiesta può contenere al massimo 20 file. Le estensioni supportate sono .pdf, .txt, .md, .docx, .xlsx e .pptx.

1. Crea gli URL di caricamento firmati

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

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

Invia i nomi originali dei file:

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

Successo: 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. Carica i byte del file

Carica ogni file direttamente sul relativo uploadUrl usando PUT:

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

Se usi il client JavaScript di Supabase, passa il percorso e il token corrispondenti ottenuti al passaggio 1:

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

Non modificare né costruire tu stesso i percorsi di storage. La registrazione accetta solo i percorsi restituiti per questo agente al passaggio 1.

3. Registra i file caricati

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

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

Al termine di ogni caricamento diretto, registra i percorsi restituiti insieme ai nomi originali dei file:

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

Successo: 202 Accepted

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

Prima di avviare il job di elaborazione, la registrazione verifica che ogni oggetto esista, non sia vuoto, non superi i 50 MB e appartenga all'agente richiesto. Caricamenti non validi o mancanti restituiscono 400 VALIDATION_INVALID_BODY; un rifiuto per quota di storage restituisce 403 QUOTA_STORAGE_LIMIT; errori di storage o di coda restituiscono 500 INTERNAL_SERVER_ERROR.

Elimina una fonte

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

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

Autenticazione: Chiave API Bearer con accesso a {agentId}.

{documentId} deve essere uno UUID restituito da una risposta di creazione o di elenco delle fonti.

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'

Successo: 200 OK

{
  "deleted": true
}

Uno UUID non valido restituisce 400 VALIDATION_INVALID_BODY. Uno UUID valido che non identifica un documento per l'agente restituisce 404 RESOURCE_DOCUMENT_NOT_FOUND.

Recupera lo stato di addestramento

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

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

Autenticazione: Chiave API Bearer con accesso a {agentId}.

Successo: 200 OK, con l'oggetto di stato restituito diretto.

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

Avvia il riaddestramento delle fonti web

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

Autenticazione: Chiave API Bearer con accesso a {agentId}. Questo endpoint non richiede un corpo della richiesta.

L'endpoint riaddestra gli URL web indicizzati, non le fonti di testo, Q&A o i file caricati.

Quando esiste almeno un URL indicizzato, l'esito positivo è 202 Accepted:

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

Quando non esiste alcun URL indicizzato, l'esito positivo è 200 OK e non viene creato alcun job:

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

Riferimenti correlati

• Panoramica API v2
• Catalogo degli errori API v2
• Agenti e impostazioni di addestramento