Passa al contenuto principale

Endpoint: Knowledge Base

Riferimento degli endpoint per la gestione delle knowledge base, dei documenti, delle FAQ, delle sorgenti di scraping web e database, della ricerca e dei webhook di notifica.

Tutte le richieste utilizzano l'URL base https://ai.askme.it/api/v2 e gli header descritti in Autenticazione (X-Api-Key, X-Source-App, X-External-Id opzionale). Le liste seguono la paginazione offset/limit descritta in Panoramica.

1. Knowledge Base

POST /knowledge-bases

Crea una nuova knowledge base.

Attributi richiesta

CampoInTipoObbligatorioDefaultDescrizione
namebodystring (1–255)Nome KB.
descriptionbodystringNoDescrizione libera.
typebodystringNomanualmanual, scraping, db, mixed.
embedding_modelbodystringNotext-embedding-3-smallModello di embedding. Per modelli Mistral è obbligatorio configurare vector_store_config su Qdrant a 1024 dimensioni.
chunk_strategybodystringNorecursiveStrategia di chunking.
chunk_sizebodyint (100–4000)No512Dimensione chunk in caratteri.
chunk_overlapbodyint (0–1000)No50Sovrapposizione tra chunk.
languagesbodystring[]No["it"]Codici lingua ISO 639-1. Le query in lingue fuori da questo set sono auto-tradotte alla prima lingua dell'array.
parent_idbodyintNoKB genitore (per gerarchie).
is_temporarybodyboolNofalseKB nascosta dalle liste standard.
vector_store_configbodyobjectNopgvector{ "provider": "pgvector", "dimensions": 1536 } oppure { "provider": "qdrant", "url": "...", "collection_name": "...", "dimensions": 1536 }.
configbodyobjectNoConfigurazione RAG di default per la KB (override possibile a livello agente). Vedi i campi rag_config documentati in Endpoint: Agenti, Chat e Conversazioni.

Esempio richiesta

curl -X POST "https://ai.askme.it/api/v2/knowledge-bases" \
-H "X-Api-Key: amai_xxxxxxxxxxxxxxxx" \
-H "X-Source-App: api_direct" \
-H "Content-Type: application/json" \
-d '{
"name": "Manuali tecnici",
"description": "Documentazione prodotto",
"type": "manual",
"languages": ["it", "en"],
"chunk_size": 800,
"chunk_overlap": 100
}'

Esempio risposta (201 Created)

{
"id": 24,
"tenant_id": "acme",
"name": "Manuali tecnici",
"description": "Documentazione prodotto",
"type": "manual",
"embedding_model": "text-embedding-3-small",
"chunk_strategy": "recursive",
"chunk_size": 800,
"chunk_overlap": 100,
"config": {},
"vector_store_config": null,
"status": "active",
"document_count": 0,
"total_chunks": 0,
"languages": ["it", "en"],
"is_temporary": false,
"parent_id": null,
"created_by": "user-uuid",
"created_at": "2026-04-30T09:00:00Z",
"updated_at": "2026-04-30T09:00:00Z"
}

GET /knowledge-bases

Elenca le knowledge base del tenant.

Attributi richiesta

CampoInTipoDefaultDescrizione
offsetqueryint0Paginazione.
limitqueryint (1–100)50Page size.
searchquerystringRicerca su nome/descrizione.
statusquerystringFiltro stato.
sort_byquerystringCampo di ordinamento.
orderquerystringasc o desc.
include_temporaryqueryboolfalseInclude KB temporanee (es. quelle create da analisi PDF chat-with-doc).

GET /knowledge-bases/{kb_id}

Dettaglio della KB.

PATCH /knowledge-bases/{kb_id}

Aggiorna la KB (campi opzionali: name, description, status, chunk_strategy, chunk_size, chunk_overlap, config, parent_id, languages). Il vector_store_config non è modificabile dopo la creazione.

DELETE /knowledge-bases/{kb_id}

Elimina la KB, i documenti e i chunk associati. Rilascia la quota knowledge_bases. Risposta 204 No Content.


GET /knowledge-bases/{kb_id}/quality-metrics

Metriche strutturali della KB (numero documenti, distribuzione chunk, pagine scrapate, ecc.). Nessuna chiamata LLM.

Esempio risposta (200 OK)

{
"total_documents": 38,
"indexed_documents": 36,
"pending_documents": 1,
"error_documents": 1,
"doc_status_breakdown": { "indexed": 36, "pending": 1, "error": 1 },
"source_type_breakdown": { "file": 20, "url": 15, "text": 3 },
"total_chunks": 1240,
"avg_chunk_tokens": 380.4,
"min_chunk_tokens": 120,
"max_chunk_tokens": 510,
"docs_with_empty_chunks": 0,
"scraping_jobs_count": 2
}

GET /knowledge-bases/{kb_id}/export

Esporta la KB come archivio ZIP (streaming application/zip).

GET /knowledge-bases/{kb_id}/change-log

Cronologia delle modifiche strutturali alla KB (creazione/rimozione documenti, aggiornamenti di configurazione).


2. Documenti

Endpoint sotto /knowledge-bases/{kb_id}/documents.

POST /knowledge-bases/{kb_id}/documents/upload

Carica un file (multipart). Tipi supportati: PDF, DOCX, TXT, MD, HTML, CSV, XLSX, JSON.

Attributi richiesta

CampoInTipoObbligatorioDefaultDescrizione
fileform-datafileIl file da caricare.
priorityform-dataintNo2Priorità di elaborazione.
categoryform-datastringNoEtichetta libera.
languageform-datastringNoCodice lingua.

Esempio richiesta (cURL)

curl -X POST "https://ai.askme.it/api/v2/knowledge-bases/24/documents/upload" \
-H "X-Api-Key: amai_xxxxxxxxxxxxxxxx" \
-H "X-Source-App: api_direct" \
-F "[email protected]" \
-F "priority=1" \
-F "language=it"

Esempio richiesta (Python, httpx)

import os, httpx

with open("policy-resi.pdf", "rb") as f:
files = {"file": ("policy-resi.pdf", f, "application/pdf")}
resp = httpx.post(
f"{os.environ['ASKMEAI_HOST']}/api/v2/knowledge-bases/3/documents",
headers={
"X-Api-Key": os.environ["ASKMEAI_API_KEY"],
"X-Source-App": "api_direct",
},
files=files,
timeout=120,
)
resp.raise_for_status()
print(resp.json())

Esempio risposta (201 Created)

{
"id": 711,
"knowledge_base_id": 24,
"title": "manuale.pdf",
"source_type": "file",
"source_url": null,
"file_path": "tenant/acme/kb/24/manuale.pdf",
"mime_type": "application/pdf",
"status": "processing",
"file_size": 2148572,
"chunk_count": 0,
"metadata": null,
"error_message": null,
"created_at": "2026-04-30T09:30:00Z",
"updated_at": "2026-04-30T09:30:00Z",
"priority": 1,
"is_visible": true
}

L'ingest è asincrono: lo stato passa per pending → processing → ready. Va verificato con GET /knowledge-bases/{kb_id}/documents/{document_id}.

Errori specifici

CodiceSignificato
413File oltre il limite del piano (file_upload_size_mb).

POST /knowledge-bases/{kb_id}/documents/text

Crea un documento da testo grezzo.

Attributi richiesta

CampoInTipoObbligatorioDescrizione
titlebodystring (1–500)Titolo del documento.
contentbodystring (≥1)Contenuto testuale.
metadatabodyobjectNoMetadati liberi.

GET /knowledge-bases/{kb_id}/documents

Elenca i documenti della KB. Parametri standard di paginazione offset/limit.

GET /knowledge-bases/{kb_id}/documents/{document_id}/preview

Anteprima testuale del documento.

GET /knowledge-bases/{kb_id}/documents/{document_id}/download

Download del file originale.

DELETE /knowledge-bases/{kb_id}/documents/{document_id}

Elimina il documento e i suoi chunk. Risposta 204.

DELETE /knowledge-bases/{kb_id}/documents/bulk

Eliminazione multipla. Body: { "ids": [711, 712, 713] }.

PATCH /knowledge-bases/{kb_id}/documents/{document_id}/visibility

Mostra/nasconde il documento come fonte citata. Quando is_visible=false, il contenuto è ancora usato per il contesto RAG ma il documento non appare nelle citazioni della risposta.

Attributi richiesta

CampoInTipoObbligatorioDescrizione
is_visiblebodybooltrue per rendere visibile, false per nascondere.

3. FAQ

Endpoint sotto /knowledge-bases/{kb_id}/faqs.

POST /knowledge-bases/{kb_id}/faqs

Crea una FAQ.

Attributi richiesta

CampoInTipoObbligatorioDefaultDescrizione
questionbodystring (max 500)Domanda canonica.
answerbodystring (max 5000)Risposta.
categorybodystring (max 255)NoCategoria.
prioritybodyintNo2Priorità nel ranking.
variantsbodystring[]No[]Riformulazioni alternative della domanda.
editorial_statusbodystringNodraftStato editoriale (draft, published, ecc.).

Esempio risposta (201 Created)

{
"id": 401,
"knowledge_base_id": 24,
"question": "Quali sono i tempi di consegna?",
"answer": "Le consegne avvengono entro 24-72 ore lavorative.",
"category": "spedizioni",
"priority": 1,
"variants": ["Quando arriva il pacco?", "Tempi di spedizione?"],
"editorial_status": "published",
"is_visible": true,
"created_at": "2026-04-30T10:00:00Z",
"updated_at": "2026-04-30T10:00:00Z"
}

GET /knowledge-bases/{kb_id}/faqs

Lista paginata delle FAQ.

PUT /knowledge-bases/{kb_id}/faqs/{faq_id}

Aggiornamento completo. Stessi campi di POST (tutti opzionali tranne question e answer).

DELETE /knowledge-bases/{kb_id}/faqs/{faq_id}

Eliminazione (204).

PATCH /knowledge-bases/{kb_id}/faqs/{faq_id}/visibility

Body: { "is_visible": true }. Stessa semantica di documents/{id}/visibility.

POST /knowledge-bases/{kb_id}/faqs/import

Import massivo da file CSV o JSON (multipart [email protected]). Restituisce { "imported": <int> }.

GET /knowledge-bases/{kb_id}/faqs/template/{formato}

Restituisce un file modello scaricabile per l'import massivo, nel formato richiesto (csv o json).


4. Scraping web

Endpoint sotto /knowledge-bases/{kb_id}/scraping-jobs. Il servizio riconosce automaticamente sitemap XML e feed RSS/Atom (estensioni .rss, .atom, /feed, content-type application/rss+xml, application/atom+xml).

POST /knowledge-bases/{kb_id}/scraping-jobs

Crea un job di scraping.

Attributi richiesta

CampoInTipoObbligatorioDefaultDescrizione
urlbodystringURL di partenza. Può essere una pagina, una sitemap o un feed RSS/Atom.
depthbodyint (1–5)No1Profondità del crawl.
schedule_cronbodystringNoCron expression per esecuzione ricorrente.
configbodyobjectNoOpzioni avanzate (selettori CSS, esclusioni, ecc.).

Esempio risposta (201 Created)

{
"id": 33,
"knowledge_base_id": 24,
"url": "https://example.com/sitemap.xml",
"status": "pending",
"depth": 1,
"pages_scraped": 0,
"pages_discovered": 0,
"last_run_at": null,
"schedule_cron": null,
"trigger": "manual",
"config": null,
"error_message": null,
"created_at": "2026-04-30T10:30:00Z",
"updated_at": "2026-04-30T10:30:00Z"
}

GET /knowledge-bases/{kb_id}/scraping-jobs

Elenco dei job.

POST /knowledge-bases/{kb_id}/scraping-jobs/{job_id}/discover

Avvia la fase di discovery (sitemap + crawl) senza scaricare le pagine. Restituisce contatori sitemap_urls_count, crawl_urls_count.

GET /knowledge-bases/{kb_id}/scraping-jobs/{job_id}/discovered-pages

Pagine trovate, paginabili. Ogni pagina ha selected: bool e status (pending, scraped, skipped, error).

PATCH /knowledge-bases/{kb_id}/scraping-jobs/{job_id}/discovered-pages/selection

Seleziona/deseleziona pagine prima dello scraping vero e proprio.

Attributi richiesta

CampoInTipoDescrizione
page_idsbodyint[]ID specifici da modificare.
selectedbodyboolNuovo stato.
select_allbodyboolSe true ignora page_ids e applica a tutte.
filter_sourcebodystringsitemap o crawl per filtrare.

POST /knowledge-bases/{kb_id}/scraping-jobs/{job_id}/trigger

Esegue lo scraping delle pagine selezionate. Risposta 202 Accepted.

GET /knowledge-bases/{kb_id}/scraping-jobs/{job_id}/progress

Stato di avanzamento in tempo reale del job (SSE).

DELETE /knowledge-bases/{kb_id}/scraping-jobs/{job_id}

Elimina il job (204). Per eliminazione massiva: DELETE .../scraping-jobs/bulk con body { "ids": [...] }.


5. Sorgenti database

Endpoint sotto /knowledge-bases/{kb_id}/db-source.

PUT /knowledge-bases/{kb_id}/db-source

Crea o aggiorna la configurazione di una sorgente DB (un solo connettore per KB).

Attributi richiesta

CampoInTipoObbligatorioDescrizione
connection_typebodystringpostgresql, mysql, mssql.
namebodystringNoNome del connettore.
hostbodystringHost del DB.
portbodyint (1–65535)Porta.
databasebodystringNome del database.
usernamebodystringUtente.
passwordbodystringNoPassword. Cifrata at-rest.
schemabodystringNoNome dello schema (PostgreSQL/MSSQL).
tablebodystringNoTabella sorgente (alternativa a query).
querybodystringNoQuery SQL custom (alternativa a table).
sync_interval_minutesbodyint (≥1)NoIntervallo di sync in minuti. Convertito internamente in cron.

POST /knowledge-bases/{kb_id}/db-source/test

Verifica la connessione senza salvarla. Stessi campi di PUT esclusi gli attributi di sync. Risponde { "success": true|false, "message": "..." }.

GET /knowledge-bases/{kb_id}/db-source/preview

Anteprima di poche righe dalla sorgente configurata. Risposta:

{
"rows": [
{ "id": 1, "title": "...", "content": "..." }
],
"columns": ["id", "title", "content"]
}

POST /knowledge-bases/{kb_id}/db-source/run

Avvia un'estrazione manuale. Risposta:

{
"documents_created": 124,
"rows_processed": 124,
"message": "Estrazione completata."
}

GET /knowledge-bases/{kb_id}/db-source/{connector_id}/runs

Storico esecuzioni (started_at, completed_at, rows_extracted, chunks_created, error_message).

DELETE /knowledge-bases/{kb_id}/db-source/{connector_id}/runs

Pulisce lo storico esecuzioni del connettore (204).

DELETE /knowledge-bases/{kb_id}/db-source/{connector_id}

Elimina la sorgente DB (204).


6. Ricerca

Endpoint sotto /search.

POST /search

Ricerca ibrida (vettoriale + BM25 + RRF + FAQ) su una o più KB.

Attributi richiesta

CampoInTipoObbligatorioDefaultDescrizione
querybodystring (1–2000)Testo della query.
knowledge_base_idsbodyint[]Almeno una KB.
top_kbodyint (1–100)No10Numero di risultati.
min_scorebodyfloat (0.0–1.0)No0.0Soglia minima di rilevanza.
use_rerankingbodyboolNofalseAbilita il reranker (cross-encoder o Cohere).
enable_bm25bodyboolNotrueIncludi BM25 nella fusione RRF.

Esempio richiesta

curl -X POST "https://ai.askme.it/api/v2/search" \
-H "X-Api-Key: amai_xxxxxxxxxxxxxxxx" \
-H "X-Source-App: api_direct" \
-H "Content-Type: application/json" \
-d '{
"query": "tempi medi consegna Italia",
"knowledge_base_ids": [24],
"top_k": 5,
"use_reranking": true
}'

Esempio risposta (200 OK)

{
"query": "tempi medi consegna Italia",
"chunks": [
{
"id": "chunk-117-3",
"document_id": 117,
"knowledge_base_id": 24,
"content": "Le spedizioni standard partono entro 24 ore lavorative ...",
"score": 0.83,
"metadata": { "page": 2 }
}
],
"faqs": [
{
"id": 401,
"knowledge_base_id": 24,
"question": "Quali sono i tempi di consegna?",
"answer": "Le consegne avvengono entro 24-72 ore lavorative.",
"score": 0.92,
"is_visible": true
}
],
"total_results": 6,
"search_time_ms": 132.4
}

Endpoint atomici

Stesso DTO di /search. Differiscono per la strategia retrieval, utili in pipeline di fan-out:

  • POST /search/advanced — ricerca con filtri estesi e reranking. Accetta ?document_ids=... (lista) come query string.
  • POST /search/vector — solo retrieval vettoriale puro (no BM25, no rerank, no fusion).
  • POST /search/fulltext — solo BM25 / Postgres FTS (KB con vector store esterno solamente vengono ignorate).
  • POST /search/faq — solo FAQ matching (vettoriale + opzionale BM25 con RRF). I risultati sono nel campo faqs; chunks è sempre vuoto.

7. Webhook ed eventi

note

Riferimento sintetico derivato dall'inventario delle funzionalità; parametri di dettaglio ed esempi di payload saranno aggiunti in un aggiornamento successivo.

EndpointMetodoDescrizione
/webhooksGET, POST, PUT, DELETEGestione dei webhook di notifica del tenant.
/webhooks/event-typesGETElenco dei tipi di evento notificabili.
/webhooks/{id}/testPOSTInvia una notifica di test al webhook configurato.
/webhooks/generate-secretPOSTGenera un secret per la verifica della firma delle notifiche.
/eventsGETStream SSE delle notifiche del tenant in tempo reale.

Pagine correlate