Endpoint: Analisi e Classificazione

Riferimento degli endpoint per l'analisi di contenuti, documenti PDF, CV e dati tabellari, l'OCR, la classificazione tramite catalogo Similarity, l'editor PDF, i template di analisi e l'integrazione con Askme Desk.

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).

Classificazione operativa

La classificazione operativa dei testi (triage, instradamento) passa dagli endpoint del catalogo Similarity (sezione 3), non da un endpoint di classificazione generico.

1. Analisi

Job di analisi orchestrati: contenuto testuale, PDF, CV, dati strutturati.

Modello di esecuzione: ogni POST /analysis/<tipo> accetta il body, restituisce 202 Accepted con un job in stato pending e schedula l'elaborazione asincrona. Il risultato si ottiene interrogando GET /analysis/{id}. Per i tipi che lo supportano sono disponibili anche le varianti /sync che attendono il completamento (200 OK).

Header opzionale Idempotency-Key: se ripetuto entro la finestra di idempotenza, restituisce lo stesso job invece di crearne uno nuovo.

Opzioni comuni (`options`)

Tutti i body POST espongono un campo opzionale options:

Campo	Tipo	Default	Descrizione
`model`	string	—	Override del modello LLM (es. `claude-haiku-4-5-20251001`).
`temperature`	float (0.0–2.0)	—	Sampling temperature.
`max_tokens`	int (1–128000)	—	Limite token risposta.
`language`	string	—	Hint lingua (`it`, `en`, ecc.).
`output_format`	string	`json`	`json`, `html`, `markdown`.
`guardrails`	bool	`false`	Abilita controlli PII/injection/toxicity.
`confidence_check`	bool	`false`	Abilita validazione qualità risultato.
`webhook_id`	int	—	Webhook (registrato con `/webhooks`, vedi Endpoint: Knowledge Base) da notificare a fine job.

Inoltre tutti i body accettano:

Campo	Tipo	Descrizione
`template_id`	int	ID di un template di analisi (sezione 6): il suo `input_config` viene fuso col body.
`name`	string (max 255)	Nome visualizzato del job.

`POST /analysis/content`

Analisi testuale generica (sentiment, entità, parole chiave, riassunto).

Attributi richiesta

Campo	In	Tipo	Obbligatorio	Default	Descrizione
`text`	body	string (1–200000)	Sì	—	Testo da analizzare.
`custom_instructions`	body	string (max 4000)	No	—	Istruzioni aggiuntive per il prompt.
`max_chars`	body	int (100–200000)	No	`20000`	Troncamento prima dell'invio al modello.
`template_id`, `name`, `options`	body	—	No	—	(vedi sopra).

Esempio richiesta

curl -X POST "https://ai.askme.it/api/v2/analysis/content" \
  -H "X-Api-Key: amai_xxxxxxxxxxxxxxxx" \
  -H "X-Source-App: api_direct" \
  -H "Idempotency-Key: 2c9e5c0e-..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Analisi recensione",
    "text": "Il prodotto è arrivato con un giorno di ritardo ma il servizio clienti è stato ottimo.",
    "options": { "language": "it" }
  }'

Esempio risposta (202 Accepted)

{
  "id": 88102,
  "tenant_id": "acme",
  "type": "content",
  "status": "pending",
  "input_config": {
    "name": "Analisi recensione",
    "text": "Il prodotto è arrivato con un giorno di ritardo...",
    "max_chars": 20000,
    "source_app": "api_direct"
  },
  "result": null,
  "error_message": null,
  "created_by": "user-uuid",
  "started_at": null,
  "completed_at": null,
  "created_at": "2026-04-30T11:00:00Z"
}

L'endpoint POST /analysis/content/sync ha lo stesso body ma attende il completamento e risponde 200 OK con il result popolato.

`POST /analysis/pdf`

Analisi di un documento PDF tramite LLM. Opzionalmente crea una KB temporanea e un agente per la modalità chat-with-doc.

Attributi richiesta

Campo	In	Tipo	Obbligatorio	Default	Descrizione
`filename`	body	string (max 512)	Sì	—	Nome del file (determina nome KB/agente).
`file_content`	body	string base64	Sì*	—	Contenuto PDF in base64. *Esattamente uno tra `file_content` e `file_path`.
`file_path`	body	string	Sì*	—	Path su object storage di un file già caricato.
`custom_prompt`	body	string (max 8000)	No	—	Istruzioni libere per l'analisi.
`agent_id`	body	int	No	—	Agente di fallback per il prompt.
`temp_agent_name`	body	string (max 512)	No	—	Nome dell'agente temporaneo (richiesto in alcune lingue).
`create_kb_agent`	body	bool	No	`false`	Se `true`, crea KB+agente temporanei con il documento per la chat.
`skip_analysis`	body	bool	No	`false`	Salta lo step di analisi LLM e crea solo KB+agente. Richiede `create_kb_agent=true`.
`template_id`, `name`, `options`	body	—	No	—	(vedi sopra).

Esempio richiesta

curl -X POST "https://ai.askme.it/api/v2/analysis/pdf" \
  -H "X-Api-Key: amai_xxxxxxxxxxxxxxxx" \
  -H "X-Source-App: api_direct" \
  -F "[email protected]" \
  -F 'options={"language":"it","create_kb_agent":true,"skip_analysis":false}'

Esempio risposta (202 Accepted)

{
  "id": 88103,
  "tenant_id": "acme",
  "type": "pdf",
  "status": "pending",
  "input_config": {
    "filename": "policy.pdf",
    "create_kb_agent": true,
    "skip_analysis": false,
    "source_app": "api_direct"
  },
  "result": null,
  "created_at": "2026-04-30T11:05:00Z"
}

Errori specifici

Codice	Significato
`422`	Né `file_content` né `file_path` forniti, oppure entrambi; oppure `skip_analysis=true` senza `create_kb_agent=true`.

L'endpoint /analysis/pdf/sync esegue in modo sincrono. Il polling dello stato è disponibile su GET /analysis/{job_id}/status:

curl -s "https://ai.askme.it/api/v2/analysis/88103/status" \
  -H "X-Api-Key: amai_xxxxxxxxxxxxxxxx" \
  -H "X-Source-App: api_direct"

Quando status == "completed", il dettaglio (GET /analysis/{job_id}) include result.response con la risposta dell'LLM.

`POST /analysis/cv`

Scoring di un CV rispetto alle job position configurate dal tenant.

Attributi richiesta

Campo	In	Tipo	Obbligatorio	Descrizione
`file_content`	body	string base64	Sì	CV (PDF o DOCX) in base64.
`filename`	body	string (max 512)	Sì	Nome file con estensione (determina il parser).
`job_position_id`	body	int	No	Limita lo scoring a una posizione. Se omesso, valuta contro tutte le posizioni del tenant.
`cv_prompt_id`	body	int	No	Override del prompt CV. Default: prompt configurato dal tenant (sezione 5).
`template_id`, `name`, `options`	body	—	No	(vedi sopra).

L'endpoint /analysis/cv/sync esegue in modo sincrono.

`POST /analysis/data`

Analisi su dati tabellari (CSV/XLSX letti come lista di dict).

Attributi richiesta

Campo	In	Tipo	Obbligatorio	Descrizione
`data`	body	object[] (1–10000)	Sì	Righe come `{ colonna: valore }`.
`columns`	body	string[]	No	Sottoinsieme di colonne da analizzare (default: tutte).
`custom_prompt`	body	string (max 4000)	No	Istruzioni LLM aggiuntive.
`agent_id`	body	int	No	Agente di fallback per il prompt.
`template_id`, `name`, `options`	body	—	No	(vedi sopra).

`GET /analysis`

Elenca i job di analisi del tenant.

Attributi richiesta

Campo	In	Tipo	Default	Descrizione
`offset`	query	int	`0`	Paginazione.
`limit`	query	int (1–200)	`50`	Page size.
`status`	query	string	—	`pending`, `running`, `completed`, `failed`.
`type`	query	string	—	`content`, `pdf`, `cv`, `data`, `ocr`.

Esempio risposta (200 OK)

{
  "items": [
    {
      "id": 88102,
      "tenant_id": "acme",
      "type": "content",
      "status": "completed",
      "input_config": { "name": "Analisi recensione", "source_app": "api_direct" },
      "error_message": null,
      "created_by": "user-uuid",
      "started_at": "2026-04-30T11:00:01Z",
      "completed_at": "2026-04-30T11:00:08Z",
      "created_at": "2026-04-30T11:00:00Z"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 50
}

`GET /analysis/{analysis_id}`

Dettaglio del job, incluso result (struttura specifica per tipo).

Esempio risposta (200 OK, content analysis completata)

{
  "id": 88102,
  "tenant_id": "acme",
  "type": "content",
  "status": "completed",
  "input_config": { "text": "...", "source_app": "api_direct" },
  "result": {
    "summary": "Il cliente segnala un ritardo ma riconosce la qualità del servizio.",
    "sentiment": { "label": "neutral", "score": 0.62 },
    "keywords": ["ritardo", "servizio clienti"],
    "entities": [{ "text": "servizio clienti", "type": "department" }],
    "language": "it"
  },
  "error_message": null,
  "started_at": "2026-04-30T11:00:01Z",
  "completed_at": "2026-04-30T11:00:08Z",
  "created_at": "2026-04-30T11:00:00Z"
}

`GET /analysis/{analysis_id}/status`

Solo lo stato del job (no result). Adatto al polling frequente.

Esempio risposta (200 OK)

{
  "id": 88102,
  "type": "content",
  "status": "running",
  "started_at": "2026-04-30T11:00:01Z",
  "completed_at": null,
  "error_message": null
}

`DELETE /analysis/{analysis_id}`

Soft-delete del job. Risposta 204.

2. OCR

`POST /analysis/ocr`

Estrazione di testo da immagini o PDF scansionati. Multipart/form-data (non JSON).

Attributi richiesta

Campo	In	Tipo	Obbligatorio	Default	Descrizione
`file`	form-data	file	Sì	—	Immagine o PDF (max 50 MB).
`language`	form-data	string	No	`ita`	Lingua Tesseract: `ita`, `eng`, `fra`, `deu`, `spa`.
`template_id`	form-data	int	No	—	Template OCR.
`webhook_id`	form-data	int	No	—	Webhook di notifica a completamento.

Esempio richiesta

curl -X POST "https://ai.askme.it/api/v2/analysis/ocr" \
  -H "X-Api-Key: amai_xxxxxxxxxxxxxxxx" \
  -H "X-Source-App: api_direct" \
  -F "[email protected]" \
  -F "language=ita"

Errori specifici

Codice	Significato
`400`	Tipo MIME non supportato o file vuoto.
`413`	File oltre 50 MB.

3. Classificazione (catalogo Similarity)

La classificazione di testi avviene attraverso il catalogo Similarity: si costruisce un indice a partire da esempi (con o senza etichette) e poi si classificano nuovi testi rispetto a quell'indice. Tutti gli endpoint sono prefissati da /api/v2/analysis/catalogs.

`POST /analysis/catalogs/build`

Avvia la build di un catalogo. Risposta 202 Accepted: la build è asincrona, con polling sullo stato del catalogo.

Attributi richiesta

Campo	In	Tipo	Obbligatorio	Default	Descrizione
`name`	body	string (1–100)	Sì	—	Nome del catalogo.
`mode`	body	string	Sì	—	`supervised` (richiede `label_path` su almeno una coppia) o `unsupervised`.
`threshold`	body	float (0.0–1.0)	No	`0.6`	Soglia minima di similarità per accettare un candidato.
`pairs`	body	object[]	Sì	—	Lista non vuota di coppie. Ogni elemento: `ticket` (string, obbligatorio), `response` (string), `label_path` (string[]).

Esempio richiesta (supervisionato, cURL)

curl -X POST "https://ai.askme.it/api/v2/analysis/catalogs/build" \
  -H "X-Api-Key: amai_xxxxxxxxxxxxxxxx" \
  -H "X-Source-App: api_direct" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Triage richieste clienti",
    "mode": "supervised",
    "threshold": 0.6,
    "pairs": [
      { "ticket": "Vorrei sapere quando arriva il pacco", "label_path": ["spedizione"] },
      { "ticket": "Il prodotto è arrivato rotto",           "label_path": ["reso"] },
      { "ticket": "Posso modificare l'\''indirizzo di consegna?", "label_path": ["modifica ordine"] }
    ]
  }'

Esempio richiesta (Python, httpx)

import httpx

client = httpx.Client(
    base_url="https://ai.askme.it/api/v2",
    headers={"X-Api-Key": "amai_xxxxxxxxxxxxxxxx", "X-Source-App": "api_direct"},
    timeout=30.0,
)

resp = client.post("/analysis/catalogs/build", json={
    "name": "Triage richieste",
    "mode": "supervised",
    "threshold": 0.6,
    "pairs": [
        {"ticket": "Vorrei sapere quando arriva il pacco", "label_path": ["spedizione"]},
        {"ticket": "Il prodotto è arrivato rotto", "label_path": ["reso"]},
        {"ticket": "Posso modificare l'indirizzo di consegna?", "label_path": ["modifica ordine"]},
        {"ticket": "Vorrei un preventivo per la versione enterprise", "label_path": ["vendita"]},
    ],
})
resp.raise_for_status()
catalog_id = resp.json()["id"]

Esempio risposta (202 Accepted)

{
  "id": 14,
  "tenant_id": "c9fe50b1-be08-...",
  "name": "Triage richieste clienti",
  "mode": "supervised",
  "status": "queued",
  "refinement_status": "templates_refined",
  "embedding_model": "text-embedding-3-small",
  "threshold": 0.6,
  "template_count": 0,
  "created_by": "...",
  "created_at": "2026-04-30T12:00:00Z"
}

Polling sullo stato:

curl "https://ai.askme.it/api/v2/analysis/catalogs/14" \
  -H "X-Api-Key: amai_xxxxxxxxxxxxxxxx" -H "X-Source-App: api_direct"

Quando status == "ready" il catalogo è pronto.

Errori specifici

Codice	Significato
`400`	`pairs` vuoto; oppure `mode=supervised` senza alcuna coppia con `label_path`.

`GET /analysis/catalogs`

Lista paginata dei cataloghi del tenant.

Query

Campo	Tipo	Default	Descrizione
`offset`	int	`0`	Indice del primo elemento.
`limit`	int (1–200)	`50`	Numero di elementi.
`status`	string	—	Filtro per stato: `queued`, `building`, `ready`, `failed`, `cancelled`.
`mode`	string	—	`supervised` o `unsupervised`.

`GET /analysis/catalogs/{catalog_id}`

Dettaglio del catalogo, inclusa la lista dei templates (esempi rappresentativi). Da usare per esplorare i cluster nei cataloghi non supervisionati o le etichette in quelli supervisionati.

`DELETE /analysis/catalogs/{catalog_id}`

Elimina il catalogo. Può essere invocata anche su un catalogo in stato building: la cancellazione interrompe la build.

`POST /analysis/catalogs/classify`

Classifica uno o più testi rispetto a un catalogo ready e restituisce i candidati top-N con punteggio di similarità.

Attributi richiesta

Campo	In	Tipo	Obbligatorio	Default	Descrizione
`catalog_id`	body	int	Sì	—	ID del catalogo.
`texts`	body	string[]	Sì	—	Testi da classificare.
`top_n`	body	int (1–10)	No	`3`	Numero di candidati per testo.
`threshold_override`	body	float (0.0–1.0)	No	—	Sovrascrive la soglia del catalogo per questa chiamata.

Esempio richiesta (cURL)

curl -X POST "https://ai.askme.it/api/v2/analysis/catalogs/classify" \
  -H "X-Api-Key: amai_xxxxxxxxxxxxxxxx" \
  -H "X-Source-App: api_direct" \
  -H "Content-Type: application/json" \
  -d '{
    "catalog_id": 14,
    "texts": ["Quando arriva il mio ordine?", "L'\''articolo che ho ricevuto è difettoso"],
    "top_n": 3
  }'

Esempio richiesta (Python, httpx)

resp = client.post("/analysis/catalogs/classify", json={
    "catalog_id": catalog_id,
    "texts": [
        "Quando arriva il mio ordine?",
        "L'articolo è difettoso, vorrei restituirlo",
    ],
    "top_n": 3,
})
resp.raise_for_status()
for result in resp.json()["results"]:
    print(result["text"], "->", result["best_label_path"], result["verdict"])

Esempio risposta

{
  "catalog_id": 14,
  "catalog_name": "Triage richieste clienti",
  "catalog_mode": "supervised",
  "refinement_status": "templates_refined",
  "total_texts": 2,
  "processing_time_seconds": 0.42,
  "threshold_used": 0.6,
  "top_n": 3,
  "results": [
    {
      "text": "Quando arriva il mio ordine?",
      "candidates": [
        { "label_path": ["spedizione"], "similarity": 0.91, "template_id": 22, "template_text": "Vorrei sapere quando arriva il pacco" }
      ],
      "best_label_path": ["spedizione"],
      "best_similarity": 0.91,
      "verdict": "strong"
    }
  ],
  "distribution": { "spedizione": 1, "reso": 1 }
}

verdict è uno di strong, medium, weak, none ed è calcolato sul punteggio del primo candidato e sul delta con il secondo.

`GET /analysis/catalogs/queue-status`

Stato della coda di build (depth, in-flight, dead-letter).

`POST /analysis/catalogs/{catalog_id}/requeue`

Rilancia un catalogo in stato failed o cancelled.

`POST /analysis/catalogs/{catalog_id}/refine-labels`

Affina i nomi dei cluster (solo cataloghi non supervisionati) con un passaggio LLM.

`POST /analysis/catalogs/{catalog_id}/refine-templates`

Seleziona i template più rappresentativi per ciascun cluster.

`PATCH /analysis/catalogs/{catalog_id}/templates/{template_id}`

Modifica manualmente testo o label_path di un singolo template.

Body

Campo	Tipo	Descrizione
`text`	string	Nuovo testo del template.
`label_path`	string[]	Nuova etichetta.

`DELETE /analysis/catalogs/{catalog_id}/templates/{template_id}`

Rimuove un template dal catalogo.

4. Editor PDF

note

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

Endpoint	Metodo	Descrizione
`/analysis/pdf/edit`	POST	Modifica un PDF esistente secondo istruzioni fornite.
`/analysis/pdf/smart-edit`	POST	Modifica guidata da LLM di sezioni specifiche del PDF.
`/analysis/pdf/fields`	POST	Estrazione dei campi compilabili di un modulo PDF.

5. Posizioni CV e prompt

note

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

Endpoint	Metodo	Descrizione
`/analysis/cv-prompt`	GET, PUT	Prompt di default utilizzato da `POST /analysis/cv` per il tenant.
`/analysis/job-positions`	GET, POST, PUT, DELETE	Gestione delle posizioni lavorative usate come riferimento per lo scoring dei CV.

6. Template di analisi

note

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

Endpoint	Metodo	Descrizione
`/templates`	GET, POST, PUT, DELETE	Gestione dei template di analisi, referenziabili tramite `template_id` nei body `POST /analysis/*`.

7. Report

note

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

Endpoint	Metodo	Descrizione
`/reports`	GET, POST	Gestione dei report generati a partire dai job di analisi.
`/reports/{id}/download`	GET	Download del report generato.

8. Integrazione con Askme Desk

Per integratori Askme Desk

Gli endpoint seguenti supportano l'integrazione tra Askme AI e Askme Desk (creazione richieste, classificazione dei ticket) e sono tipicamente consumati dal workflow del chatbot o dal middleware di integrazione, non da integrazioni dirette del cliente finale. Riferimento sintetico derivato dall'inventario delle funzionalità.

Endpoint	Metodo	Descrizione
`/desk/suggestions`	POST	Genera suggerimenti di risposta per un ticket Askme Desk.
`/desk/workflow/generate`	POST	Genera una proposta di workflow a partire da una descrizione.
`/desk/extract-attributes`	POST	Estrae attributi strutturati da un ticket.
`/desk/classify-triple`	POST	Classificazione su tripla categoria/sottocategoria/motivazione.
`/desk/classifications/{id}`	GET	Dettaglio di una classificazione eseguita.

1. Analisi​

Opzioni comuni (options)​

POST /analysis/content​

POST /analysis/pdf​

POST /analysis/cv​

POST /analysis/data​

GET /analysis​

GET /analysis/{analysis_id}​

GET /analysis/{analysis_id}/status​

DELETE /analysis/{analysis_id}​

2. OCR​

POST /analysis/ocr​

3. Classificazione (catalogo Similarity)​

POST /analysis/catalogs/build​

GET /analysis/catalogs​

GET /analysis/catalogs/{catalog_id}​

DELETE /analysis/catalogs/{catalog_id}​

POST /analysis/catalogs/classify​

GET /analysis/catalogs/queue-status​

POST /analysis/catalogs/{catalog_id}/requeue​

POST /analysis/catalogs/{catalog_id}/refine-labels​

POST /analysis/catalogs/{catalog_id}/refine-templates​

PATCH /analysis/catalogs/{catalog_id}/templates/{template_id}​

DELETE /analysis/catalogs/{catalog_id}/templates/{template_id}​

4. Editor PDF​

5. Posizioni CV e prompt​

6. Template di analisi​

7. Report​

8. Integrazione con Askme Desk​

Pagine correlate​

1. Analisi

Opzioni comuni (`options`)

`POST /analysis/content`

`POST /analysis/pdf`

`POST /analysis/cv`

`POST /analysis/data`

`GET /analysis`

`GET /analysis/{analysis_id}`

`GET /analysis/{analysis_id}/status`

`DELETE /analysis/{analysis_id}`

2. OCR

`POST /analysis/ocr`

3. Classificazione (catalogo Similarity)

`POST /analysis/catalogs/build`

`GET /analysis/catalogs`

`GET /analysis/catalogs/{catalog_id}`

`DELETE /analysis/catalogs/{catalog_id}`

`POST /analysis/catalogs/classify`

`GET /analysis/catalogs/queue-status`

`POST /analysis/catalogs/{catalog_id}/requeue`

`POST /analysis/catalogs/{catalog_id}/refine-labels`

`POST /analysis/catalogs/{catalog_id}/refine-templates`

`PATCH /analysis/catalogs/{catalog_id}/templates/{template_id}`

`DELETE /analysis/catalogs/{catalog_id}/templates/{template_id}`

4. Editor PDF

5. Posizioni CV e prompt

6. Template di analisi

7. Report

8. Integrazione con Askme Desk

Pagine correlate