{
  "openapi": "3.1.0",
  "info": {
    "title": "cache.directory Public API",
    "version": "1.0.0",
    "description": "cache.directory is a curated catalog of agent skills, MCP servers, system prompts, editor rules, starters, and local LLM tools — schema-validated entries with a public JSON API for agents. This OpenAPI 3.1 document describes the public, unauthenticated JSON catalog API. No API keys. Rate limits use RFC RateLimit headers; HTTP 429 includes Retry-After.",
    "contact": {
      "name": "cache.directory developer support",
      "email": "hello@cache.directory",
      "url": "https://cache.directory/developers"
    },
    "license": {
      "name": "Content and API terms",
      "url": "https://cache.directory/privacy"
    }
  },
  "security": [],
  "servers": [
    {
      "url": "https://cache.directory",
      "description": "cache.directory production"
    }
  ],
  "tags": [
    {
      "name": "Health",
      "description": "Service liveness for agents and monitors."
    },
    {
      "name": "Catalog",
      "description": "Shelf listings, search index, and per-entry resolve/raw artifacts."
    },
    {
      "name": "Discovery",
      "description": "Machine-readable specs and docs."
    }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "operationId": "getHealth",
        "tags": [
          "Health"
        ],
        "summary": "Service health",
        "description": "Returns a JSON health document so agents can confirm the cache.directory origin is reachable without executing JavaScript.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Service is reachable.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "service",
                    "timestamp"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "ok"
                    },
                    "service": {
                      "type": "string",
                      "example": "cache.directory"
                    },
                    "timestamp": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/search.json": {
      "get": {
        "operationId": "searchCatalog",
        "tags": [
          "Catalog"
        ],
        "summary": "Flat catalog search index",
        "description": "Returns every indexable catalog entry across all shelves as JSON. Agents download this index and filter client-side; there is no query-string search on the origin.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Flat catalog index.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "count",
                    "entries"
                  ],
                  "properties": {
                    "count": {
                      "type": "integer"
                    },
                    "entries": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "slug",
                          "shelf",
                          "name",
                          "url"
                        ],
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "shelf": {
                            "type": "string",
                            "enum": [
                              "skills",
                              "mcp",
                              "starters",
                              "prompts",
                              "rules",
                              "local-llm",
                              "tools",
                              "guides",
                              "comparisons"
                            ]
                          },
                          "name": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "tags": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "author": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "stars": {
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "updated": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/{shelf}.json": {
      "get": {
        "operationId": "listShelf",
        "tags": [
          "Catalog"
        ],
        "summary": "List entries on one shelf",
        "description": "Lists indexable entries for a single catalog shelf. The path parameter is the Astro collection name (skills, mcp-servers, starters, prompts, rules, local-llm, tools, guides, comparisons), not the URL vertical id for MCP (mcp).",
        "parameters": [
          {
            "name": "shelf",
            "in": "path",
            "required": true,
            "description": "Astro content collection name used in /api/v1/{shelf}.json.",
            "schema": {
              "type": "string",
              "enum": [
                "skills",
                "mcp-servers",
                "starters",
                "prompts",
                "rules",
                "local-llm",
                "tools",
                "guides",
                "comparisons"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Shelf payload with entries.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "shelf",
                    "label",
                    "count",
                    "entries"
                  ],
                  "properties": {
                    "shelf": {
                      "type": "string"
                    },
                    "label": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "generatedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "entries": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "url",
                          "name",
                          "description"
                        ],
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          },
                          "name": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "category": {
                            "type": "string"
                          },
                          "tags": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "author": {
                            "type": "string"
                          },
                          "license": {
                            "type": "string"
                          },
                          "updated": {
                            "type": "string"
                          },
                          "stars": {
                            "type": "integer"
                          },
                          "installs": {
                            "type": "integer"
                          },
                          "featured": {
                            "type": "boolean"
                          },
                          "installCommand": {
                            "type": "string"
                          },
                          "sourceUrl": {
                            "type": "string",
                            "format": "uri"
                          },
                          "repoUrl": {
                            "type": "string",
                            "format": "uri"
                          },
                          "sandbox": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Structured JSON error with code, message, and resolution hint.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message",
                        "resolution"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "example": "NOT_FOUND"
                        },
                        "message": {
                          "type": "string"
                        },
                        "resolution": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Structured JSON error with code, message, and resolution hint.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message",
                        "resolution"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "example": "NOT_FOUND"
                        },
                        "message": {
                          "type": "string"
                        },
                        "resolution": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Structured JSON error with code, message, and resolution hint.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message",
                        "resolution"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "example": "NOT_FOUND"
                        },
                        "message": {
                          "type": "string"
                        },
                        "resolution": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/resolve/{slug}.json": {
      "get": {
        "operationId": "resolveEntry",
        "tags": [
          "Catalog"
        ],
        "summary": "Resolve one catalog slug",
        "description": "Returns full public metadata for a catalog slug plus the raw artifact URL used by install clients.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Entry slug as used on the HTML page (without .md).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Resolved entry metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "slug",
                    "shelf",
                    "name",
                    "url",
                    "artifacts"
                  ],
                  "properties": {
                    "slug": {
                      "type": "string"
                    },
                    "shelf": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "artifacts": {
                      "type": "object",
                      "properties": {
                        "raw": {
                          "type": "string",
                          "format": "uri"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Structured JSON error with code, message, and resolution hint.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message",
                        "resolution"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "example": "NOT_FOUND"
                        },
                        "message": {
                          "type": "string"
                        },
                        "resolution": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Structured JSON error with code, message, and resolution hint.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message",
                        "resolution"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "example": "NOT_FOUND"
                        },
                        "message": {
                          "type": "string"
                        },
                        "resolution": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Structured JSON error with code, message, and resolution hint.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message",
                        "resolution"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "example": "NOT_FOUND"
                        },
                        "message": {
                          "type": "string"
                        },
                        "resolution": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/raw/{shelf}/{slug}": {
      "get": {
        "operationId": "getRawArtifact",
        "tags": [
          "Catalog"
        ],
        "summary": "Fetch raw installable artifact",
        "description": "Returns the raw skill/prompt/rules body or MCP config snippet for a catalog entry. Content-Type is text/markdown, text/plain, or application/json depending on the shelf.",
        "parameters": [
          {
            "name": "shelf",
            "in": "path",
            "required": true,
            "description": "URL vertical id (skills, mcp, starters, prompts, rules, local-llm, tools, guides, comparisons).",
            "schema": {
              "type": "string",
              "enum": [
                "skills",
                "mcp",
                "starters",
                "prompts",
                "rules",
                "local-llm",
                "tools",
                "guides",
                "comparisons"
              ]
            }
          },
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Entry slug.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Raw artifact body.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "type": "object"
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Structured JSON error with code, message, and resolution hint.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message",
                        "resolution"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "example": "NOT_FOUND"
                        },
                        "message": {
                          "type": "string"
                        },
                        "resolution": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Structured JSON error with code, message, and resolution hint.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message",
                        "resolution"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "example": "NOT_FOUND"
                        },
                        "message": {
                          "type": "string"
                        },
                        "resolution": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Structured JSON error with code, message, and resolution hint.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message",
                        "resolution"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "example": "NOT_FOUND"
                        },
                        "message": {
                          "type": "string"
                        },
                        "resolution": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "operationId": "getOpenApiDocument",
        "tags": [
          "Discovery"
        ],
        "summary": "OpenAPI 3.1 specification",
        "description": "Machine-readable cache.directory API surface for LLM function calling and API clients. Every operation has a unique operationId, a description, typed parameters where applicable, and a response schema.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "OpenAPI document.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/openapi.yaml": {
      "get": {
        "operationId": "getOpenApiYaml",
        "tags": [
          "Discovery"
        ],
        "summary": "OpenAPI 3.1 specification (YAML)",
        "description": "Same cache.directory public API as /openapi.json, serialized as YAML for clients that prefer application/yaml. Use this document to bind unique operationIds for function calling.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "OpenAPI document in YAML.",
            "content": {
              "application/yaml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ApiError": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "resolution"
            ],
            "properties": {
              "code": {
                "type": "string",
                "example": "NOT_FOUND"
              },
              "message": {
                "type": "string"
              },
              "resolution": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}