Skip to content

api-overview.md

Latest commit

 

History

History
67 lines (45 loc) · 2.97 KB

api-overview.md

File metadata and controls

67 lines (45 loc) · 2.97 KB
Raw

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