API per sviluppatori

I contenuti di EsameNautica sono disponibili anche per programmi e agenti AI: un'API REST pubblica in sola lettura, un server MCP e le singole pagine in markdown. Stessi dati del sito: le guide sull'esame della patente nautica, le regole d'esame del DM 323/2021 e del patentino D1, le sedi d'esame per città.

Accesso

Nessuna autenticazione e nessuna chiave. Base URL: https://esamenautica.app. Specifica completa in OpenAPI 3.1, catalogo in /.well-known/api-catalog.

Endpoint

Richiesta	Risposta
`GET /api/v1/info`	Informazioni sul sito
`GET /api/v1/exam`	Regole d'esame
`GET /api/v1/guides?q=&cluster=&limit=`	Elenca o cerca le guide
`GET /api/v1/guides/{slug}`	Leggi una guida
`GET /api/v1/cities?region=`	Elenca le città
`GET /api/v1/cities/{slug}`	Dettaglio città

Esempi

curl https://esamenautica.app/api/v1/exam
curl "https://esamenautica.app/api/v1/guides?q=punto%20nave&limit=3"
curl https://esamenautica.app/api/v1/cities/napoli
curl -H "Accept: text/markdown" https://esamenautica.app/carteggio/
curl -X POST https://esamenautica.app/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Server MCP

Endpoint https://esamenautica.app/mcp, trasporto Streamable HTTP (JSON-RPC 2.0 via POST). Tool: get_site_info, get_exam_rules, search_guides, get_guide, list_cities, get_city. Risorse: llms.txt, regole d'esame, indice delle guide e delle città. Manifest in server-card.json e server.json.

{
  "mcpServers": {
    "esamenautica": { "type": "http", "url": "https://esamenautica.app/mcp" }
  }
}

Limiti

60 richieste ogni 60 secondi per indirizzo IP, applicate dalla singola istanza edge. Ogni risposta riporta gli header RateLimit-Policy: "default";q=60;w=60 e RateLimit: "default";r=…;t=…. Oltre il limite la risposta è 429 con Retry-After.

Errori

Gli errori sotto /api/ usano application/problem+json (RFC 9457) con i campi type, title, status, detail, code e resolution.

code	HTTP
`invalid_query`	400
`invalid_cluster`	400
`invalid_limit`	400
`invalid_slug`	400
`invalid_region`	400
`guide_not_found`	404
`city_not_found`	404
`not_found`	404
`method_not_allowed`	405
`rate_limited`	429

{
  "type": "https://esamenautica.app/docs/#errori",
  "title": "Not Found",
  "status": 404,
  "detail": "Nessuna guida con slug \"xyz\".",
  "code": "guide_not_found",
  "resolution": "Elenca le guide con GET https://esamenautica.app/api/v1/guides."
}

Markdown e llms.txt

Ogni pagina risponde in markdown se la richiesta ha Accept: text/markdown. Le guide sono anche file statici in /content/blog/<slug>.md. L'indice per agenti è in llms.txt, il testo completo in llms-full.txt.