Search API

The CLI and other read-only clients use:

GET https://patterns.directory/api/search?q=feature+folders&limit=20

q may be empty to browse the current catalog. limit is clamped by the service. sort orders results by relevance (the default), recent (latest indexed update first), or az (alphabetical by title).

Structured filters

Filters can be combined with or without a text query:

GET /api/search?language=typescript&framework=react&target=frontend-application
GET /api/search?q=database+migration&category=persistence&runtime=node

Supported parameters are category, target, language, framework, and runtime.

Filter values are normalized with the same kebab-case grammar the index applies to manifest facets, so cosmetic spelling never misses: ?framework=Next.js matches patterns indexed as next-js, and ?language=C%23 matches c-sharp.

Response

{
  "data": [
    {
      "name": "frontend-feature-modules",
      "title": "Organize a React App by Feature",
      "ref": "mimrai-org/patterns-seed/patterns/frontend-feature-modules",
      "description": "Organize UI, state, data access, and tests around each user-facing feature.",
      "category": "code-organization",
      "targets": ["frontend-application"],
      "languages": ["typescript"],
      "frameworks": ["react"],
      "runtimes": ["browser"],
      "tags": ["feature-first", "feature-modules"],
      "stack": ["typescript", "react"],
      "installs": 0
    }
  ]
}

The original name, ref, description, stack, and installs fields remain present for older clients. Enriched fields are additive.

Ranking

The index weighs exact and prefix matches first, then full-text relevance across title, ID, aliases, description, category, tags, facets, and the manifest's guide summaries. Install count is a tie-breaker. Clients should preserve server order.

Exact detail lookup

The CLI's patterns inspect command resolves an exact catalog entry with one selector:

GET /api/patterns?ref=owner/repository/subdirectory
GET /api/patterns?name=stable-pattern-id

Supplying both selectors, neither, or a syntactically invalid ref returns 400; 404 is reserved for a well-formed selector that is not in the index. name is a globally unique identifier — one name resolves to at most one pattern across the whole directory. Successful responses use { "data": PatternDetail } and include the indexed commit so clients can inspect the immutable Git manifest.

Search and publishing may be rate-limited. A temporary directory outage does not affect pinned Git installations.