The Directory News
Write for Us

The Directory News API & developer docs

A read-only API for The Directory News' articles and public civic records. No account, API key or login: every endpoint is anonymous and returns what the public pages already show.

REST API

Machine-readable description: /openapi.json (OpenAPI 3.1). Catalog: /.well-known/api-catalog.

curl "https://thedirectorynews-staging.vercel.app/api/v1/search?q=city%20council&limit=5"

Errors are JSON: {"error":{"code":"missing_query","message":"…","hint":"…"}} with a 4xx status.

POST /api/v1/batch runs up to 10 search/articles operations in one request.

POST /api/v1/export starts an asynchronous export and answers 202 with a Location to poll (GET /api/v1/jobs/{id}). POSTs accept an Idempotency-Key header; since everything only reads, a retry is always safe.

Search is cursor-paginated: pass next_cursor from a response as cursor (null means no more). A sandbox with fixed fixture data lives at /api/v1/sandbox/search?q=test, so a client can be tested without live content.

Limits and versioning

60 requests per minute per client. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; over the limit you get a 429 with Retry-After. The API is versioned in the path (/api/v1); a breaking change ships as /api/v2 and v1 stays for at least 12 months, announced with Deprecation and Sunset headers and on this page.

MCP server

Streamable HTTP, stateless, at https://thedirectorynews-staging.vercel.app/mcp (also /.well-known/mcp). Tools: search_site, latest_articles, both read-only, with an MCP Apps results view (ui://thedirectorynews/results). Documentation is its own MCP server at /mcp/docs. Server card: /.well-known/mcp/server-card.json.

A2A agent

Card: /.well-known/agent-card.json. Send a JSON-RPC message/send to /a2a.

NLWeb

POST /ask with {"query":"…"} returns schema.org items (_meta.response_type: "list"); send {"prefer":{"streaming":true}} for Server-Sent Events.

More