API della Knowledge Base #

La tua knowledge base è ciò da cui l’IA attinge le informazioni. È composta da due parti, ed entrambe sono trattate in questa pagina:

• Fonti di conoscenza (/kb-sources) — le pagine web e i documenti caricati che fornisci alla piattaforma. Ognuno viene letto, suddiviso in sezioni e trasformato in FAQ a cui la tua IA può rispondere.
• Gruppi di conoscenza (/kb-groups) — pacchetti denominati di FAQ che puoi applicare a un Agente o a una campagna con una singola chiamata, in modo che un corpo di conoscenze già curato possa essere riutilizzato sul prossimo Agente che creerai.

Le FAQ prodotte da una fonte finiscono nella stessa libreria di quelle scritte a mano, quindi una volta terminata l’importazione puoi leggerle, modificarle e collegarle con le API delle FAQ.

Tutti gli endpoint seguenti sono relativi all’URL di base https://api.youraiconnector.com/v1. Ogni richiesta deve essere autenticata: consulta Accesso API e Autenticazione. L’accesso all’API è una funzionalità a pagamento; in caso contrario, le richieste verranno rifiutate con un 403.

L’importazione consuma crediti. Leggere una pagina o un documento e scrivere FAQ a partire da essi consuma crediti, approssimativamente in proporzione alla quantità di contenuti. Usa Stima un’importazione prima di procedere con una scansione di grandi dimensioni.

Come funziona un’importazione #

L’importazione è un processo in background, non qualcosa che termina mentre attendi. Ogni endpoint di importazione risponde immediatamente con un source_id, e tu interroghi quella fonte finché non è completata:

1. Avvia l’importazione — POST /kb-sources/url (una pagina), POST /kb-sources/file (un documento caricato), o POST /kb-sources/bulk-import (fino a 100 pagine). Riceverai un ID sorgente e un status: "queued".
2. Interroga — GET /kb-sources/{sourceId} finché status non è più queued o processing.
3. Leggi le FAQ — quando lo stato è ready, le voci prodotte si trovano nella tua libreria FAQ: GET /faqs.

Ogni fonte riporta uno di questi stati:

Collega durante l’importazione. Passa autoLinkToAgentId su qualsiasi endpoint di importazione e la fonte — insieme a ogni FAQ che produce — verrà aggiunta alla knowledge base di quell’Agente nella stessa chiamata, senza passaggi di collegamento successivi. autoLinkToCampaignId fa lo stesso per una campagna classica. Il collegamento è un tentativo: un ID che non esiste, o che appartiene a un altro account, viene ignorato silenziosamente e l’importazione viene comunque eseguita, quindi conferma il collegamento leggendo nuovamente l’Agente.

Importa una pagina web #

POST /kb-sources/url

Aggiunge una pagina web alla tua knowledge base.

Campi della richiesta

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/url?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/kb-sources/url", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/pricing",
    autoLinkToAgentId: "ag7HkQ2ZpLxR3mNb",
  }),
});
const { source_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-sources/url",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "url": "https://example.com/pricing",
        "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb",
    },
)
source_id = res.json().get("source_id")

Risposta — 202 Accepted

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "queued",
  "batch_id": "batch_9f2a"
}

Esegui il polling di source_id con Controlla una fonte finché lo stato non è ready o failed.

Se la stessa pagina è già presente nella tua knowledge base, non viene accodato nulla di nuovo e riceverai invece un 200 — e se hai richiesto un collegamento automatico, la fonte esistente verrà comunque collegata per te:

{
  "success": true,
  "status": "exists",
  "skipped_duplicate": 1
}

Un url mancante, o uno che non è un indirizzo http/https valido, restituisce 400.

Importa un documento caricato #

POST /kb-sources/file

Aggiunge un documento che si trova già nell’archivio file del tuo account come fonte di conoscenza. Tipi supportati: PDF, DOCX, TXT, MD, CSV e XLSX.

Questo endpoint non trasporta il file. Non c’è caricamento multipart, nessun corpo base64 e nessun download da un URL: invii la posizione di archiviazione di un file che esiste già, e deve trovarsi nella tua cartella di caricamento (storage_path deve iniziare con users/{your user id}/uploads/) o la richiesta verrà rifiutata con 403. La dashboard inserisce i file lì quando li trascini. Se non hai modo di inserire un file lì, importa una pagina web con Importa una pagina web in alternativa.

Campi della richiesta

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/file?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "storage_path": "users/abc123uid/uploads/handbook.pdf",
    "filename": "handbook.pdf",
    "mime_type": "application/pdf",
    "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb"
  }'

Risposta — 202 Accepted

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "queued"
}

Controlla una fonte #

GET /kb-sources/{sourceId}

Il polling che segue ogni importazione e aggiornamento. Ripetilo finché lo stato non è ready o failed.

cURL

curl "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const source = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
source = res.json()

Risposta

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "ready",
  "faq_count": 24,
  "section_count": 31,
  "error_message": null
}

Eliminare una sorgente #

DELETE /kb-sources/{sourceId}

Rimuove una sorgente di conoscenza. Per impostazione predefinita, le FAQ prodotte vengono conservate — aggiungi delete_faqs=true per rimuovere anche quelle.

Parametri di query

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123?delete_faqs=true&apiKey=YOUR_API_KEY"

Risposta

{
  "success": true,
  "faqs_deleted": 24
}

faqs_deleted è 0 a meno che tu non abbia richiesto delete_faqs=true.

Importare molte pagine contemporaneamente #

POST /kb-sources/bulk-import

Aggiunge fino a 100 pagine web in una sola chiamata. Il tuo account può avere fino a 5.000 pagine in attesa di essere importate contemporaneamente (il limite di importazione del tuo account), contando le pagine già in coda o in fase di lettura. Una chiamata che supererebbe tale limite viene rifiutata con 400 e error_code: kb_import_page_limit e nulla di quella chiamata viene messo in coda. Le importazioni superiori a 5.000 pagine richiedono l’approvazione, quindi contatta l’assistenza per aumentare il limite. È il consueto passaggio successivo a Scopri pagine su un sito web o Trova nuove pagine su un sito web. Le pagine già presenti nella tua base di conoscenza vengono saltate invece di essere duplicate (e rimangono collegate all’Agente quando richiesto).

Un’importazione che il tuo account non può pagare viene rifiutata prima che qualsiasi cosa venga messa in coda, con 402 e error_code: kb_import_insufficient_credits (la risposta contiene anche required_credits, available_credits e waiting_pages). Ogni pagina conta come almeno un chunk per questo controllo, e contano anche le pagine che hai già in attesa di essere importate, poiché vengono addebitate solo quando vengono elaborate. Gli account con ricarica automatica impostata non vengono rifiutati in base al saldo. Anche gli account che utilizzano la propria chiave AI non vengono rifiutati, a meno che non utilizzino il piano Max, che viene addebitato in crediti. Per un sub-account, available_credits è null.

Importare più di 100 pagine richiede diverse chiamate. Invia la dimensione dell’intera selezione come plannedTotal nella prima chiamata. Il limite di pagine e il controllo del credito coprono quindi l’intera selezione in quella chiamata, in modo che un’importazione che non può essere completata venga rifiutata prima che qualsiasi pagina venga messa in coda, invece di fermarsi a metà. Quando la prima chiamata viene accettata, la sua risposta include un import_session: invialo come importSession in ogni chiamata successiva della stessa selezione. Tali chiamate saltano quindi il controllo del credito preventivo fino al numero approvato di pagine, per un’ora. Il limite di pagine rimane valido e ogni pagina viene comunque addebitata quando viene elaborata.

Campi della richiesta

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/bulk-import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/pricing", "https://example.com/faq"],
    "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/kb-sources/bulk-import", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    urls: ["https://example.com/pricing", "https://example.com/faq"],
    autoLinkToAgentId: "ag7HkQ2ZpLxR3mNb",
  }),
});
const { queued_source_ids } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-sources/bulk-import",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "urls": ["https://example.com/pricing", "https://example.com/faq"],
        "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb",
    },
)
queued_source_ids = res.json()["queued_source_ids"]

Risposta — 202 Accepted

{
  "success": true,
  "batch_id": "batch_9f2a",
  "queued": 2,
  "skipped_duplicate": 0,
  "queued_source_ids": ["kb_src_abc123", "kb_src_def456"]
}

Esegui il polling di ogni ID in queued_source_ids con Controllare una sorgente. L’invio di un array urls vuoto, di una voce non stringa o di più di 100 voci restituisce 400.

Eliminare molte sorgenti contemporaneamente #

POST /kb-sources/bulk-delete

Rimuove fino a 2.000 sorgenti di conoscenza in una sola chiamata. La rimozione viene eseguita in background e riceverai un’email al termine dell’operazione.

L’eliminazione in blocco rimuove sempre anche le FAQ. A differenza di Elimina una fonte, che le conserva a meno che non venga richiesto diversamente, questo endpoint elimina ogni fonte insieme alle FAQ che ha prodotto. Non c’è opzione per conservarle.

Campi della richiesta

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/bulk-delete?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceIds": ["kb_src_abc123", "kb_src_def456"],
    "domainLabel": "example.com"
  }'

Risposta — 202 Accepted

{
  "success": true,
  "batch_id": "del_batch_31a",
  "queued": 2
}

Esplora le pagine di un sito web #

POST /kb-sources/discover-pages

Esplora un sito web partendo da un indirizzo iniziale ed elenca le pagine trovate sullo stesso dominio, ognuna con un parere sull’opportunità di importarla. Non viene importato nulla e non viene selezionato nulla per te: questo è il passaggio “cosa c’è su questo sito” da eseguire prima di decidere cosa inviare a Importa molte pagine contemporaneamente.

Campi della richiesta

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/discover-pages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com", "maxPages": 100 }'

Risposta

{
  "success": true,
  "source_type": "sitemap",
  "pages": [
    {
      "url": "https://example.com/pricing",
      "title": "Pricing",
      "depth": 1,
      "score": 95,
      "recommendation": "add",
      "reason_key": "core_page"
    }
  ]
}

L’esplorazione è un tentativo. Se il sito non può essere letto, la risposta è comunque 200, con success: false, un elenco pages vuoto e un messaggio error. Controlla success prima di leggere pages.

Un url mancante restituisce 400.

Stima il costo di un’importazione #

POST /kb-sources/estimate-cost

Calcola quanti crediti consumerebbe un’importazione proposta, prima di impegnarsi. Le pagine vengono recuperate e i documenti letti per misurarne la dimensione, ma non viene importato nulla e la stima stessa non consuma crediti.

Campi della richiesta

Invia urls, files, o entrambi.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/estimate-cost?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "urls": ["https://example.com/pricing"] }'

Risposta

{
  "success": true,
  "estimates": [
    { "ref": "https://example.com/pricing", "chunks": 7, "credits": 7 }
  ],
  "total_chunks": 7,
  "total_credits": 7,
  "affordable": true,
  "required_credits": 7,
  "available_credits": 120,
  "checked_chunks": 7,
  "waiting_pages": 0,
  "max_affordable_chunks": 120
}

Ogni riga riporta l’URL o il percorso di archiviazione in ref in modo da poterlo abbinare al tuo input. Una pagina o un file che non è stato possibile leggere ottiene comunque una riga, conteggiata come un chunk, con un error sopra.

affordable indica se il tuo account può pagare per questa stima, contando le pagine che hai già in attesa di essere importate (waiting_pages). max_affordable_chunks è il numero massimo di ulteriori chunk che può pagare, così puoi confrontare un totale parziale quando stimi una grande selezione in diverse chiamate. È null quando il tuo saldo non ti limita (ricarica automatica impostata, o la tua chiave AI sotto il piano Max), ed è sempre null per un sub-account, che ottiene solo affordable (invia prior_chunks in modo che copra l’intera selezione) e un null available_credits.

Interrompere un’importazione #

POST /kb-sources/cancel-import

Interrompe le pagine ancora in attesa nella coda di importazione: il pulsante “interrompi importazione” per una scansione che si è rivelata più grande del previsto. Annullare una pagina in attesa non costa nulla, poiché non è ancora stata letta.

Le pagine già in fase di elaborazione non vengono interrotte: il loro lavoro è in corso e viene addebitato in ogni caso, quindi vengono completate. La risposta riporta quante erano.

Campi della richiesta

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/cancel-import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "host": "docs.example.com" }'

Risposta

{
  "success": true,
  "cancelled": 412,
  "in_flight": 3
}

Riprendere un’importazione in pausa #

POST /kb-sources/resume-import

Riavvia un’importazione che era stata messa in pausa perché la tua chiave AI ha smesso di funzionare.

Chiamare questo metodo costituisce il tuo consenso a completare l’importazione con qualsiasi chiave sia attiva in quel momento, il che potrebbe significare spendere crediti della piattaforma se la tua chiave è ancora inattiva.

Campi della richiesta

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/resume-import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Risposta

{
  "success": true,
  "resumed": 58
}

Trovare nuove pagine su un sito web #

POST /kb-sources/refresh-domain

Esplora un sito web da cui hai già effettuato un’importazione e segnala solo le pagine che non sono ancora presenti nella tua base di conoscenza, ognuna con lo stesso consiglio della scoperta delle pagine. Nulla viene importato e nulla viene modificato.

I due passaggi successivi sono chiamate deliberatamente separate, quindi abbandonare questa operazione non costa nulla:

• importa le nuove pagine che desideri con Importa molte pagine contemporaneamente;
• rileggi le pagine che già possiedi con Aggiorna ogni pagina di un sito web.

Campi della richiesta

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/refresh-domain?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "baseUrl": "https://example.com" }'

Risposta

{
  "success": true,
  "source_type": "sitemap",
  "discovered": 249,
  "new_pages": [
    {
      "url": "https://example.com/new-guide",
      "score": 95,
      "recommendation": "add",
      "reason_key": "core_page"
    }
  ],
  "new_urls_queued": 0,
  "existing_refresh_queued": 249
}

Come per l’individuazione, questo fallisce in modo non bloccante: un sito che non può essere letto restituisce comunque 200, con success: false, un new_pages vuoto e un error. Un baseUrl mancante o vuoto restituisce 400.

Aggiorna ogni pagina di un sito web #

POST /kb-sources/trigger-domain-refresh

Rilegge ogni pagina che hai già importato da un sito web, in modo che le sue FAQ seguano il contenuto attuale del sito: le sezioni modificate vengono aggiornate, quelle nuove aggiunte e quelle rimosse eliminate.

Questo accoda il lavoro e restituisce immediatamente. Segui con Monitora l’aggiornamento di un sito web e interrompilo con Interrompi l’aggiornamento di un sito web.

Campi della richiesta

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/trigger-domain-refresh?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "baseUrl": "https://example.com" }'

Risposta

{
  "success": true,
  "queued": 249
}

Monitora l’aggiornamento di un sito web #

GET /kb-sources/domain-refresh-status

A che punto è l’aggiornamento di un sito web, così da poter mostrare il progresso come “221 di 249”.

Parametri di query

cURL

curl "https://api.youraiconnector.com/v1/kb-sources/domain-refresh-status?baseUrl=https://example.com&apiKey=YOUR_API_KEY"

Risposta

{
  "success": true,
  "job": {
    "domainBatchId": "job_7c1e",
    "host": "example.com",
    "total": 249,
    "pending": 28,
    "succeeded": 219,
    "failed": 2,
    "skippedDuplicate": 0,
    "status": "refreshing",
    "startedAtIso": "2026-06-15T09:00:00.000Z"
  }
}

job è null quando non è in esecuzione alcun aggiornamento per quel sito web. Le pagine completate finora sono total meno pending. Il lavoro status è uno tra refreshing (elaborazione delle pagine in corso), deduplicating (passaggio di pulizia finale), o i finali completed, failed e cancelled. Conserva domainBatchId: è ciò che passi all’endpoint di annullamento.

Un baseUrl mancante o vuoto restituisce 400.

Interrompi l’aggiornamento di un sito web #

POST /kb-sources/refresh-domain/cancel

Interrompe l’aggiornamento di un sito web che sta ancora elaborando le sue pagine. Le pagine già completate mantengono il loro contenuto aggiornato; le pagine non ancora avviate vengono rimosse e le pagine che erano in fase di rilettura tornano al loro stato precedente.

Campi della richiesta

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/refresh-domain/cancel?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jobId": "job_7c1e" }'

Risposta

{
  "success": true,
  "status": "cancelled",
  "cancelled_units": 28,
  "sources_reset": 3,
  "sources_cancelled": 25
}

Annullare due volte è innocuo: la seconda chiamata riporta lo stesso stato finale. Una volta che l’aggiornamento è passato alla fase di pulizia, non può più essere interrotto e la risposta restituisce success: false e reason: "already_finalizing". Un jobId mancante restituisce 400, e un lavoro che non è presente nel tuo account restituisce 404.

Aggiorna una singola fonte #

POST /kb-sources/{sourceId}/refresh

Rilegge una pagina web che hai già importato e allinea le sue FAQ al contenuto attuale della pagina: le sezioni modificate vengono aggiornate, quelle nuove aggiunte e quelle rimosse eliminate.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123/refresh?apiKey=YOUR_API_KEY"

Risposta — 202 Accepted

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "queued"
}

Esegui il polling della fonte finché il suo stato non esce da queued e processing. Un ID fonte non presente nel tuo account restituisce 404.

Seleziona le pagine più pertinenti #

POST /kb-sources/select-relevant-pages

Chiede all’IA di scegliere le cinque pagine, da un elenco di candidate, che descrivono meglio un’attività: utilizzato durante la generazione di un playbook di campagna da un sito web. Questa operazione consuma crediti.

Campi della richiesta

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/select-relevant-pages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "homeUrl": "https://example.com",
    "urls": ["https://example.com/about", "https://example.com/pricing"]
  }'

Risposta

{
  "success": true,
  "pages": [
    { "url": "https://example.com/pricing", "title": "Pricing", "type": "pricing" }
  ]
}

Questo è un helper, non una risorsa: in caso di errore risponde comunque 200, con success: false, un elenco pages vuoto e un messaggio error.

Gruppi di conoscenza #

Un gruppo di conoscenza è un insieme denominato di FAQ — “Spedizioni e resi”, “Onboarding” — che puoi applicare a un Agente o a una campagna con una sola chiamata. Il gruppo contiene riferimenti, non copie: le FAQ stesse rimangono nella tua libreria unica, quindi modificarne una con la API delle FAQ la aggiorna ovunque venga utilizzata.

L’applicazione di un gruppo aggiunge sempre e solo ciò che manca, quindi applicare lo stesso gruppo due volte è innocuo e added_count restituisce 0 la seconda volta.

Creare un gruppo di conoscenza #

POST /kb-groups

Crea un gruppo. Inizia vuoto: aggiungi FAQ al suo interno con Aggiungi una FAQ a un gruppo.

Campi della richiesta

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Shipping and returns" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/kb-groups", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Shipping and returns" }),
});
const { group_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-groups",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Shipping and returns"},
)
group_id = res.json()["group_id"]

Risposta — 201 Created

{
  "success": true,
  "group_id": "kbg_abc123"
}

Rinominare un gruppo di conoscenza #

PUT /kb-groups/{groupId}

Cambia il nome di un gruppo. Le sue FAQ rimangono invariate.

Campi della richiesta

cURL

curl -X PUT "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Shipping, returns and refunds" }'

Risposta

{
  "success": true,
  "group_id": "kbg_abc123",
  "name": "Shipping, returns and refunds"
}

Eliminare un gruppo di conoscenza #

DELETE /kb-groups/{groupId}

Elimina il gruppo. Viene rimosso solo il pacchetto: le FAQ al suo interno rimangono nella tua libreria e tutto ciò a cui il gruppo era già stato applicato mantiene tali FAQ.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123?apiKey=YOUR_API_KEY"

Risposta

{
  "success": true
}

Aggiungi una FAQ a un gruppo #

POST /kb-groups/{groupId}/faqs

Inserisce una FAQ esistente in un gruppo. Questo modifica solo il bundle: non collega la FAQ a nessun Agente di per sé; applica il gruppo per quello.

Campi della richiesta

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/faqs?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "faq_id": "aBcD1234eFgH5678" }'

Risposta

{
  "success": true,
  "group_id": "kbg_abc123",
  "faq_id": "aBcD1234eFgH5678"
}

Rimuovi una FAQ da un gruppo #

DELETE /kb-groups/{groupId}/faqs/{faqId}

Rimuove una FAQ da un gruppo. La FAQ in sé non viene eliminata e gli Agenti a cui il gruppo era già stato applicato la manterranno.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/faqs/aBcD1234eFgH5678?apiKey=YOUR_API_KEY"

Risposta

{
  "success": true,
  "group_id": "kbg_abc123",
  "faq_id": "aBcD1234eFgH5678"
}

Applica un gruppo a un Agente #

POST /kb-groups/{groupId}/apply-to-agent

Aggiunge ogni FAQ nel gruppo alla conoscenza di un Agente AI in un’unica chiamata: il modo rapido per fornire a un nuovo Agente un corpo di conoscenze che hai già curato.

Campi della richiesta

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-agent?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "ag7HkQ2ZpLxR3mNb" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-agent",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ agent_id: "ag7HkQ2ZpLxR3mNb" }),
  }
);
const { added_count } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-agent",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"agent_id": "ag7HkQ2ZpLxR3mNb"},
)
added_count = res.json()["added_count"]

Risposta

{
  "success": true,
  "group_id": "kbg_abc123",
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "added_count": 12
}

added_count indica quante FAQ sono state effettivamente aggiunte: 0 quando il gruppo è vuoto o già applicato.

Applica un gruppo a una campagna #

POST /kb-groups/{groupId}/apply-to-campaign

La versione per campagne classiche della chiamata precedente. Su un account basato su Agenti, usa invece Applica un gruppo a un Agente.

Campi della richiesta

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-campaign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": "campaign123" }'

Risposta

{
  "success": true,
  "group_id": "kbg_abc123",
  "campaign_id": "campaign123",
  "added_count": 12
}

Errori dell’API della Knowledge Base #

Questi endpoint restituiscono il formato di errore standard:

{
  "success": false,
  "error": "Knowledge base source not found."
}

Gli errori lievi (soft failures) non sono errori. La scoperta (discover-pages, refresh-domain) e l’helper di selezione delle pagine rispondono 200 con success: false e un messaggio error quando il sito web non può essere letto, invece di far fallire la richiesta. Controlla sempre success prima di leggere i dati.

I codici condivisi che ogni endpoint può restituire — 401, 403 (il tuo piano non include l’accesso all’API), 429 (limite di frequenza) e 500 — sono elencati con indicazioni sui tentativi in Errori e Paginazione.

Correlati #

• API FAQ — leggi, modifica e collega le FAQ prodotte dalle tue fonti.
• Gestione FAQ — la stessa knowledge base nella dashboard.
• Agenti AI — gli Agenti a cui colleghi fonti e gruppi.
• Accesso API — genera la tua chiave API.
• Autenticazione — tutti i modi per trasmettere la tua chiave.