developers

cache.directory developer resources

This is the cache.directory machine interface: a public REST catalog API, an OpenAPI 3.1 document for function calling, markdown representations of HTML pages, and the curated llms.txt map. No API key is required for the public GET endpoints. Production at https://cache.directory is the sandbox — there is no separate staging origin.

cache.directory OpenAPI specification

Agents should load https://cache.directory/openapi.json or https://cache.directory/api/openapi.yaml. Every public operation has a unique operationId, a description, typed parameters, and a JSON response schema. cache.directory does not ship GraphQL; requests to /graphql return a JSON error that points back to this REST spec.

Public endpoints

  • GET /api/health — liveness JSON (operationId: getHealth)
  • GET /api/v1/search.json — flat catalog index for client-side search (operationId: searchCatalog)
  • GET /api/v1/skills.json — skills shelf listing; swap the collection name for other shelves (operationId: listShelf)
  • GET /api/v1/resolve/{slug}.json — one entry's metadata (operationId: resolveEntry)
  • GET /api/v1/raw/{shelf}/{slug} — raw SKILL.md / prompt / MCP snippet (operationId: getRawArtifact)

Example: curl -s https://cache.directory/api/v1/search.json with Accept: application/json. Health check: curl -s https://cache.directory/api/health. OpenAPI: curl -s https://cache.directory/openapi.json.

Authentication

Public GET endpoints above are unauthenticated. Do not send bearer tokens; they are ignored. There is no API-key product in v1. If you need a correction or a takedown, email hello@cache.directory or legal@cache.directory — that is not an authenticated API.

Rate limits

Public API responses include RFC RateLimit and RateLimit-Policy headers plus X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. The default public policy is 60 requests per 60 seconds per client IP. HTTP 429 includes Retry-After. Slow down when remaining approaches zero instead of retrying in a tight loop.

JSON errors

API errors are JSON objects with error.code, error.message, and error.resolution. HTML error pages are not used for /api/* misses. Unknown API paths return 404 JSON, not the marketing homepage.

Markdown content negotiation

HTML pages honor Accept: text/markdown and return Content-Type: text/markdown; charset=utf-8 with Vary: Accept, Accept-Encoding so caches do not mix HTML and Markdown. Browsers that send a standard HTML Accept header still receive the visual site.

Webhooks

cache.directory has no public inbound webhook product. Catalog data is pull-based: poll /api/v1/search.json or a shelf JSON file. Do not POST to catalog routes.

Related cache.directory files