api overview

API Overview

You will learn the public API structure, response formats, error handling, and versioning conventions.

Base path

Most public API endpoints live under /api/v1/.

Two public utility endpoints sit outside that versioned prefix:

• /healthz — lightweight service health check
• /mcp — Model Context Protocol endpoint using Streamable HTTP transport

Methods

Public /api/v1/ read endpoints accept GET and HEAD. Unsupported methods on known routes return 405 Method Not Allowed with an Allow header.

The MCP endpoint at /mcp accepts GET, POST, and DELETE for Streamable HTTP sessions.

OPTIONS requests are handled by CORS middleware before route dispatch. See Rate Limits and CORS.

Response formats

Format	Content-Type	Used for
JSON	application/json	Most endpoints: metadata, catalogs, search results, comparisons
Text	text/plain	Raw IP lists, composed sets
CSV	text/csv	Feed history (DateTime,Entries,UniqueIPs)

Error responses

The API uses standard HTTP status codes:

• 200 — success
• 400 — invalid request, bad parameter, or invalid feed/provider name
• 404 — feed or resource not found
• 405 — method not allowed
• 429 — rate limit exceeded
• 500 — internal server error
• 503 — supporting aggregate/entity artifact is not ready or readable, or required admin authentication is not configured. Missing feed-scoped artifacts usually return 404.

Alias routes

Two backward-compatible alias families exist:

• /api/v1/ipsets and /api/v1/ipsets/{name} → same as /api/v1/sets and /api/v1/sets/{name}
• /api/v1/query → same as /api/v1/search

These aliases exist for compatibility with the bash-era tooling. Use the canonical paths for new integrations.

Versioning

The current version is v1. Payload schemas may evolve compatibly within v1 (new fields, not removed fields). The endpoint families and their semantic purpose are part of the public contract.

Next steps

• Health and Status — health check and runtime status endpoints
• Feed Endpoints — catalog, detail, data, history, comparison, per-feed classification
• Search and Query — global IP lookup, per-feed scoped search
• Compose Endpoint — custom IP set composition
• Classification Endpoints — country, ASN, maintainer indexes
• Infrastructure Endpoints — critical infrastructure overlap data
• Methodology Endpoints — methodology page content
• MCP Endpoint — Model Context Protocol endpoint for AI agents
• Metadata Files — robots.txt, sitemap, llms.txt
• Raw File Downloads — direct .ipset/.netset file access
• Rate Limits and CORS — rate limiting and cross-origin rules