API per agenti LLM & Claude Code

Endpoint read-only per accedere al knowledge base MonitoraggioCDV direttamente da altri agenti AI: ricerca FTS multi-sorgente, ranking di pertinenza, riconoscimento di query in italiano naturale, citation_url pronti per essere inseriti nelle risposte.

Pensata per essere scoperta autonomamente da un agente: parti dal manifest e procedi.

305417atti CDV

18124atti Consiglio

1712BURC

428gare PGT

28ODG Giunta

In questa pagina:

Quickstart: integra l'API in 30 secondi
Autenticazione
Endpoint disponibili
Sintassi delle query
Esempi pratici
Prompt template per Claude Code
Manifest JSON live

🚀 Quickstart

Tutto quello che serve a un agente per iniziare:

BASE="https://monitoraggiocdv.progetti.campania.it"
TOKEN="<chiedere a Ferdinando>"

# 1. Discovery (no auth)
curl "$BASE/api/agent/manifest"

# 2. Ricerca multi-source
curl -H "Authorization: Bearer $TOKEN" \
  "$BASE/api/agent/search?q=PCE+contaminazione+falda&limit=5"

# 3. Espandi un risultato
curl -H "Authorization: Bearer $TOKEN" \
  "$BASE/api/agent/fetch?source=cdv&id=18715"

# 4. Briefing ultime 24h
curl -H "Authorization: Bearer $TOKEN" \
  "$BASE/api/agent/recent?hours=24"

Tutti gli endpoint sono GET, idempotenti, e restituiscono JSON. Nessuna modifica al backend è possibile via questa API.

Sorgenti disponibili

cdvAtti Casa di Vetro (decreti, delibere, determine)

crConsiglio Regionale (interrogazioni, mozioni, leggi)

burcBollettino Ufficiale Regione Campania

gareGare d'appalto Portale Gare Telematiche

odgOrdini del Giorno Sedute di Giunta

🔑 Autenticazione

Tutti gli endpoint — tranne /api/agent/manifest e /api/agent/tipologie — richiedono un Bearer token.

Authorization: Bearer mcdv-agent-<...>

Token AGENT_TOKEN: disponibile su richiesta al gestore del servizio. È separato dall'admin token e ha solo permessi di lettura.

📡 Endpoint disponibili

GET/api/agent/manifest

Pubblico, no auth. Discovery delle capability. Un agente può partire da qui senza altra documentazione.

curl https://monitoraggiocdv.progetti.campania.it/api/agent/manifest

GET/api/agent/search

Ricerca multi-source con ranking di pertinenza.

Param	Tipo	Default	Note
`q`	string	—	obbligatorio
`limit`	int	10	1–50
`sources`	csv	tutte	es. `cdv,cr`
`snippet`	bool	true	frammenti `<mark>…</mark>`

curl -H "Authorization: Bearer $T" \
  "$BASE/api/agent/search?q=DGR%20254%20del%2024/05/2022&limit=3"

Schema risultato: { source, id, title, snippet, tipologia, num_atto_anno, data, struttura, fonte, rank, citation_url, pdf_url, _branch }

GET/api/agent/fetch

Singolo documento con metadati + testo PDF estratto + lista allegati.

Param	Tipo	Note
`source`	string	cdv \| cr \| burc \| gare \| odg
`id`	int	dall'`id` di /search
`max_text`	int	default 50000 (max 400000)

curl -H "Authorization: Bearer $T" \
  "$BASE/api/agent/fetch?source=cdv&id=18715&max_text=20000"

GET/api/agent/recent

Ultimi atti pubblicati. Per briefing giornalieri.

Param	Default	Note
`hours`	48	1–720
`limit`	30	1–100
`sources`	tutte	csv

curl -H "Authorization: Bearer $T" \
  "$BASE/api/agent/recent?hours=24&sources=cdv,cr"

GET/api/agent/structure

Mappa delle strutture amministrative regionali con codici (es. 50|14 = DG 50.14 RU). Utile per interpretare il campo struttura dei documenti.

GET/api/agent/tipologie

Pubblico, no auth. Codici tipologia → label (E=Decreto Dirigenziale, G=Delibera di Giunta, …).

🔍 Sintassi delle query

Il motore prova più strategie in cascata (la prima che matcha vince):

Esempio	Strategia	Note
`DGR 254 del 24/05/2022`	atto naturale	parser italiano: tipologia+num+anno+data
`dd 207/2024`	atto naturale	shorthand
`595/2025`	code num/anno	match esatto su num+anno_atto
`00595/2025`	code num/anno	zero-padding accettato
`9876543210`	code CIG	10 caratteri alfanumerici
`"concorso straordinario"`	FTS	frase esatta
`farmacia -decadenza`	FTS	esclusione termine
`sarn*`	FTS	prefix match
`PCE OR TCE`	FTS	alternative
`endometriosi`	FTS	stemming italiano

Il campo _branch nella risposta indica quale strategia ha trovato il risultato (utile per debug del ranking).

💡 Esempi pratici

Tema ambientale (es. contaminazione del Sarno)

Trova gli atti correlati a un tema di interesse pubblico:

curl -H "Authorization: Bearer $T" \
  "$BASE/api/agent/search?q=Sarno+PCE+contaminazione&limit=10"

Regolamento UDCP (BURC 56/2025)

curl -H "Authorization: Bearer $T" \
  "$BASE/api/agent/search?q=BURC%2056/2025&sources=burc"

Briefing pre-Giunta della settimana

curl -H "Authorization: Bearer $T" \
  "$BASE/api/agent/recent?hours=168&sources=odg,cdv"

Atti del Consiglio per firmatario o tema

curl -H "Authorization: Bearer $T" \
  "$BASE/api/agent/search?q=interrogazione+sanità&sources=cr&limit=20"

Cerca un atto per numero (es. DD 595/2025)

# Per numero esatto
curl -H "Authorization: Bearer $T" "$BASE/api/agent/search?q=595/2025"
# Espandi
curl -H "Authorization: Bearer $T" "$BASE/api/agent/fetch?source=cdv&id=<...>"

🤖 Prompt template per Claude Code

Incolla questo nel system prompt di un'altra sessione Claude Code (o nel CLAUDE.md di un progetto) per dargli accesso all'archivio:

Hai accesso al knowledge base MonitoraggioCDV (Regione Campania, ~104k atti).

Base URL: https://monitoraggiocdv.progetti.campania.it
Auth: Authorization: Bearer ${AGENT_TOKEN}   # da .env / segreto

Workflow consigliato:
1. Per query libere → GET /api/agent/search?q=...
2. Per espandere un risultato → GET /api/agent/fetch?source=<s>&id=<id>
3. Per briefing recenti → GET /api/agent/recent?hours=24
4. Cita SEMPRE il campo `citation_url` restituito.

Sintassi query:
- "frase esatta" / -escludi / prefix* / A OR B
- Numero atto: "595/2025" oppure "DGR 254 del 24/05/2022"
- CIG: 10 caratteri alfanumerici

Sources: cdv (atti regionali) | cr (Consiglio) | burc | gare | odg

Per scoprire tutte le capability senza memorizzarle, l'agente puo' iniziare con:
  curl https://monitoraggiocdv.progetti.campania.it/api/agent/manifest
(no auth richiesta sul manifest).

📋 Manifest JSON live

Il manifest è generato dinamicamente dal backend. Un agente può scaricarlo a runtime per scoprire eventuali nuovi endpoint:

GET /api/agent/manifest →

Garanzie: tutte le rotte /api/agent/* sono GET read-only. Non c'è alcun modo per un agente, anche con il token, di modificare i dati o eseguire codice lato server.