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
| Campo | In | Tipo | Obbligatorio | Default | Descrizione |
|---|---|---|---|---|---|
name | body | string (1–255) | Sì | — | Nome KB. |
description | body | string | No | — | Descrizione libera. |
type | body | string | No | manual | manual, scraping, db, mixed. |
embedding_model | body | string | No | text-embedding-3-small | Modello di embedding. Per modelli Mistral è obbligatorio configurare vector_store_config su Qdrant a 1024 dimensioni. |
chunk_strategy | body | string | No | recursive | Strategia di chunking. |
chunk_size | body | int (100–4000) | No | 512 | Dimensione chunk in caratteri. |
chunk_overlap | body | int (0–1000) | No | 50 | Sovrapposizione tra chunk. |
languages | body | string[] | No | ["it"] | Codici lingua ISO 639-1. Le query in lingue fuori da questo set sono auto-tradotte alla prima lingua dell'array. |
parent_id | body | int | No | — | KB genitore (per gerarchie). |
is_temporary | body | bool | No | false | KB nascosta dalle liste standard. |
vector_store_config | body | object | No | pgvector | { "provider": "pgvector", "dimensions": 1536 } oppure { "provider": "qdrant", "url": "...", "collection_name": "...", "dimensions": 1536 }. |
config | body | object | No | — | Configurazione 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
| Campo | In | Tipo | Default | Descrizione |
|---|---|---|---|---|
offset | query | int | 0 | Paginazione. |
limit | query | int (1–100) | 50 | Page size. |
search | query | string | — | Ricerca su nome/descrizione. |
status | query | string | — | Filtro stato. |
sort_by | query | string | — | Campo di ordinamento. |
order | query | string | — | asc o desc. |
include_temporary | query | bool | false | Include 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
| Campo | In | Tipo | Obbligatorio | Default | Descrizione |
|---|---|---|---|---|---|
file | form-data | file | Sì | — | Il file da caricare. |
priority | form-data | int | No | 2 | Priorità di elaborazione. |
category | form-data | string | No | — | Etichetta libera. |
language | form-data | string | No | — | Codice 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
| Codice | Significato |
|---|---|
413 | File oltre il limite del piano (file_upload_size_mb). |
POST /knowledge-bases/{kb_id}/documents/text
Crea un documento da testo grezzo.
Attributi richiesta
| Campo | In | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|---|
title | body | string (1–500) | Sì | Titolo del documento. |
content | body | string (≥1) | Sì | Contenuto testuale. |
metadata | body | object | No | Metadati 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
| Campo | In | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|---|
is_visible | body | bool | Sì | true 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
| Campo | In | Tipo | Obbligatorio | Default | Descrizione |
|---|---|---|---|---|---|
question | body | string (max 500) | Sì | — | Domanda canonica. |
answer | body | string (max 5000) | Sì | — | Risposta. |
category | body | string (max 255) | No | — | Categoria. |
priority | body | int | No | 2 | Priorità nel ranking. |
variants | body | string[] | No | [] | Riformulazioni alternative della domanda. |
editorial_status | body | string | No | draft | Stato 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
| Campo | In | Tipo | Obbligatorio | Default | Descrizione |
|---|---|---|---|---|---|
url | body | string | Sì | — | URL di partenza. Può essere una pagina, una sitemap o un feed RSS/Atom. |
depth | body | int (1–5) | No | 1 | Profondità del crawl. |
schedule_cron | body | string | No | — | Cron expression per esecuzione ricorrente. |
config | body | object | No | — | Opzioni 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
| Campo | In | Tipo | Descrizione |
|---|---|---|---|
page_ids | body | int[] | ID specifici da modificare. |
selected | body | bool | Nuovo stato. |
select_all | body | bool | Se true ignora page_ids e applica a tutte. |
filter_source | body | string | sitemap 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
| Campo | In | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|---|
connection_type | body | string | Sì | postgresql, mysql, mssql. |
name | body | string | No | Nome del connettore. |
host | body | string | Sì | Host del DB. |
port | body | int (1–65535) | Sì | Porta. |
database | body | string | Sì | Nome del database. |
username | body | string | Sì | Utente. |
password | body | string | No | Password. Cifrata at-rest. |
schema | body | string | No | Nome dello schema (PostgreSQL/MSSQL). |
table | body | string | No | Tabella sorgente (alternativa a query). |
query | body | string | No | Query SQL custom (alternativa a table). |
sync_interval_minutes | body | int (≥1) | No | Intervallo 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
| Campo | In | Tipo | Obbligatorio | Default | Descrizione |
|---|---|---|---|---|---|
query | body | string (1–2000) | Sì | — | Testo della query. |
knowledge_base_ids | body | int[] | Sì | — | Almeno una KB. |
top_k | body | int (1–100) | No | 10 | Numero di risultati. |
min_score | body | float (0.0–1.0) | No | 0.0 | Soglia minima di rilevanza. |
use_reranking | body | bool | No | false | Abilita il reranker (cross-encoder o Cohere). |
enable_bm25 | body | bool | No | true | Includi 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 campofaqs;chunksè sempre vuoto.
7. Webhook ed eventi
Riferimento sintetico derivato dall'inventario delle funzionalità; parametri di dettaglio ed esempi di payload saranno aggiunti in un aggiornamento successivo.
| Endpoint | Metodo | Descrizione |
|---|---|---|
/webhooks | GET, POST, PUT, DELETE | Gestione dei webhook di notifica del tenant. |
/webhooks/event-types | GET | Elenco dei tipi di evento notificabili. |
/webhooks/{id}/test | POST | Invia una notifica di test al webhook configurato. |
/webhooks/generate-secret | POST | Genera un secret per la verifica della firma delle notifiche. |
/events | GET | Stream SSE delle notifiche del tenant in tempo reale. |