openapi: 3.1.0
info:
  title: Resource Library API
  version: 1.0.0
  summary: Read-only JSON API over the CheapInfra curated resource catalog.
  description: |
    Read-only API over the curated resource catalog: developer resources
    shared in the CheapInfra Discord's #share-tech and #providers channels,
    each with an editorial brief, its sharer, a share date, and controlled
    taxonomy facets. No auth, no write endpoints, no vector search.

    ## Surfaces

    - **Static artifacts** (`/index.json`, `/taxonomy.json`, `/facets.json`,
      `/resources.json`) are files generated by `scripts/api_build.py` and
      work on any static host. Query parameters on them are ignored by the
      host.
    - **Dynamic routes** (`/search`, `/resources`, `/resources/{id}`) are
      Cloudflare Pages Functions in `functions/api/v1/`, a behavior-identical
      JS port of the stdlib local adapter `scripts/api_server.py`. They read
      the same deployment's static assets, so a function and the catalog it
      serves can never skew across deploys. `scripts/edge_parity.py` is the
      parity gate.
    - Unknown paths under `/api/v1/` are **not** JSON 404s in production:
      the static host falls back to the site's HTML. Use only the paths
      documented here. (The local adapter returns a JSON `not_found`.)

    ## HTTP behavior (dynamic routes)

    - Methods: GET, HEAD, OPTIONS. Any other method returns 405
      `method_not_allowed`. OPTIONS returns 204 with
      `Access-Control-Allow-Methods: GET, HEAD, OPTIONS` and
      `Access-Control-Allow-Headers: If-None-Match`.
    - CORS: `Access-Control-Allow-Origin: *` on every response, never
      credentials.
    - Caching: strong `ETag` (quoted SHA-256 of the exact body); send
      `If-None-Match` to get a 304. `Last-Modified` is the manifest's
      `generated_at`. `Cache-Control: public, max-age=60` for /search,
      `300` for /resources, `3600` for /resources/{id}; error responses are
      `no-store`.
    - Content type: `application/json; charset=utf-8`.

    ## Filters

    Facet filters (`resource_type`/`type`, `topic`, `use_case`,
    `interface`, `technology`, `channel`) accept CSV: values are OR-ed
    within a family and families AND together. Every value must exist in
    `/facets.json`, otherwise 400 `bad_filter`. A single value echoes back
    as a string, multiple values as a deduplicated array. `from`/`to` are
    inclusive `YYYY-MM-DD` bounds on `shared_on`; invalid calendar dates or
    `from > to` return `bad_filter`. Unknown query parameters are ignored.

    ## Known limits (v1)

    - `/search` only returns records that match a non-empty `q`. A request
      with filters but no `q` returns `results: []`. To browse a facet
      without a query, page `/resources.json` (or `/resources`) and filter
      client-side using the record fields.
    - `fields` cannot select `details` yet; fetch the full record instead.
    - `/search` responses carry no `total`; page with `next_cursor`.
    - `verification.status` is `unchecked` on every record today.

    ## Versioning

    The major version lives in the path. Within v1 changes are additive
    only: new optional fields, endpoints, and taxonomy values may appear;
    fields, endpoints, and error codes are never renamed or removed.
  license:
    name: CC-BY-4.0 (catalog content)
    url: https://creativecommons.org/licenses/by/4.0/
  contact:
    name: Resource Library on GitHub
    url: https://github.com/thelaggingway/resource-library
externalDocs:
  description: Agent-oriented index (llms.txt)
  url: https://cheapinfra-resources.wyrdwerk.com/llms.txt
servers:
  - url: https://cheapinfra-resources.wyrdwerk.com/api/v1
    description: Production (Cloudflare Pages, custom domain)
  - url: https://resource-library-7q4.pages.dev/api/v1
    description: Production (pages.dev domain)
  - url: http://localhost:8765/api/v1
    description: Local adapter (python3 scripts/api_server.py 8765)
tags:
  - name: search
    description: Ranked lexical search with facet filters
  - name: records
    description: Canonical resource records
  - name: metadata
    description: Manifest, taxonomy, and facet vocabularies
paths:
  /search:
    get:
      operationId: searchResources
      tags: [search]
      summary: Deterministic lexical search
      description: |
        Exact id (`q=openrouter`) or normalized-URL (`q=https://openrouter.ai`)
        queries short-circuit to rank 1. Otherwise each record gets a fixed,
        weighted lexical score over title (5.0), brief (2.0), taxonomy labels
        (3.0), and curated aliases (3.0), plus a phrase bonus for multi-word
        queries found verbatim in the title (8.0) or brief. Light stemming (a word and its stem variants count once);
        domain-style queries (`openrouter.com`) are also tried with dots
        split. Records scoring 0 are not returned. No embeddings, no model
        calls — the same query against the same catalog always returns the
        same order.

        Sorting: `relevance` (score desc, id asc), `newest`/`oldest`
        (`shared_on`, id tiebreak), `title` (case-insensitive title asc,
        id tiebreak). Sorting reorders the matched set; it never adds
        records that did not match `q`.

        Pagination: `next_cursor` is the id of the last record on the page.
        Pass it back unchanged with the same query and filters. An unknown
        cursor on /search restarts from the first page (no error).
      parameters:
        - name: q
          in: query
          description: |
            Free-text query. Effectively required — an empty or missing `q`
            returns no results even when filters are set.
          schema:
            type: string
          examples:
            phrase:
              value: open source react components
            exactId:
              value: openrouter
        - name: resource_type
          in: query
          description: Resource type, CSV allowed (OR within the family).
          style: form
          explode: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ResourceType'
          example: [repository, tool]
        - name: type
          in: query
          description: Alias of `resource_type`; ignored when `resource_type` is also given.
          style: form
          explode: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ResourceType'
        - name: topic
          in: query
          description: Topic slugs, CSV allowed (OR within the family).
          style: form
          explode: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Topic'
          example: [frontend, design]
        - name: use_case
          in: query
          description: Use-case slugs, CSV allowed (OR within the family).
          style: form
          explode: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/UseCase'
        - name: interface
          in: query
          description: Interface slugs, CSV allowed (OR within the family).
          style: form
          explode: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Interface'
        - name: technology
          in: query
          description: Technology slugs, CSV allowed (OR within the family).
          style: form
          explode: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Technology'
        - name: channel
          in: query
          description: Source Discord channel, CSV allowed.
          style: form
          explode: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Channel'
        - name: open_source
          in: query
          description: |
            `true` keeps records whose brief explicitly says open source.
            `false` keeps every other record — including the many whose
            license is simply unknown (`open_source: null`) — so it means
            "not known to be open source", not "closed source".
          schema:
            type: boolean
        - name: from
          in: query
          description: Inclusive lower bound on `shared_on`.
          schema:
            type: string
            format: date
          example: '2026-09-01'
        - name: to
          in: query
          description: Inclusive upper bound on `shared_on`; must be >= `from`.
          schema:
            type: string
            format: date
          example: '2026-09-30'
        - name: sort
          in: query
          schema:
            type: string
            enum: [relevance, newest, oldest, title]
            default: relevance
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: Ranked results with a stable pagination cursor
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Cache-Control:
              description: public, max-age=60
              schema:
                type: string
            Last-Modified:
              $ref: '#/components/headers/LastModified'
            Access-Control-Allow-Origin:
              $ref: '#/components/headers/ACAO'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
              example:
                query: react components
                filters:
                  topic: [frontend, design]
                sort: relevance
                limit: 2
                results:
                  - id: beui-motion-components
                    title: beUI motion components
                  - id: obsidian-ui
                    title: obsidian ui
                next_cursor: obsidian-ui
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          $ref: '#/components/responses/BadRequest'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/Internal'
        '503':
          $ref: '#/components/responses/CatalogUnavailable'
  /resources:
    get:
      operationId: listResources
      tags: [records]
      summary: Canonical records in stable order (paginated)
      description: |
        Every record in canonical order (the site's data.json order), paged
        with `limit`/`cursor`. Pages Function in production; the local
        adapter serves the same payload at `/resources.json` with these
        query parameters. Unlike /search, an unknown cursor is a 400
        `bad_cursor`.
      parameters:
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: One page of records
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Cache-Control:
              description: public, max-age=300
              schema:
                type: string
            Last-Modified:
              $ref: '#/components/headers/LastModified'
            Access-Control-Allow-Origin:
              $ref: '#/components/headers/ACAO'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourcePage'
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          $ref: '#/components/responses/BadRequest'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/Internal'
        '503':
          $ref: '#/components/responses/CatalogUnavailable'
  /resources/{id}:
    get:
      operationId: getResource
      tags: [records]
      summary: One canonical record by id
      description: |
        Ids are immutable slugs, never regenerated. Find them via /search,
        /resources, or the `id` field of /resources.json.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            pattern: '^[a-z0-9][a-z0-9-]{1,95}$'
          example: openrouter
        - $ref: '#/components/parameters/Fields'
      responses:
        '200':
          description: The canonical record
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Cache-Control:
              description: public, max-age=3600
              schema:
                type: string
            Last-Modified:
              $ref: '#/components/headers/LastModified'
            Access-Control-Allow-Origin:
              $ref: '#/components/headers/ACAO'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Resource'
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/Internal'
        '503':
          $ref: '#/components/responses/CatalogUnavailable'
  /resources.json:
    get:
      operationId: getResourcesSnapshot
      tags: [records]
      summary: Full canonical record array (static asset)
      description: |
        The raw, ordered array of all records — the simplest way to mirror
        the whole catalog in one request. Served as a static file in
        production; query parameters are ignored there. (The local adapter
        additionally accepts fields/limit/cursor on this path and returns
        the /resources page shape.)
      responses:
        '200':
          description: All records in canonical order
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Resource'
  /facets.json:
    get:
      operationId: getFacets
      tags: [metadata]
      summary: Facet values with corpus counts (static asset)
      description: |
        Per-family facet value -> resource count, keyed by the filter
        parameter names. Every vocabulary value is included (count 0 if
        unused); families are ordered count desc, slug asc. Generated by
        scripts/api_build.py from the same catalog as the search filters,
        so counts can never skew from the deployed index. Family objects
        satisfy `$defs.facets` in schemas/exports.schema.json.
      responses:
        '200':
          description: Facet families with counts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Facets'
  /taxonomy.json:
    get:
      operationId: getTaxonomy
      tags: [metadata]
      summary: Taxonomy registries and curated synonyms (static asset)
      description: |
        The five controlled vocabularies (resource-types, topics, use-cases,
        interfaces, technologies) with a label, definition, aliases, and
        status per slug, plus the curated query-expansion synonym map.
        Source: catalog/taxonomy/*.json.
      responses:
        '200':
          description: The five taxonomy registries plus the synonym map
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Taxonomy'
  /index.json:
    get:
      operationId: getManifest
      tags: [metadata]
      summary: API manifest (static asset)
      description: |
        Version, record count, channels, a SHA-256 of resources.json, and
        a registry of the static endpoints. Poll this (or compare
        `resources_sha256`) to detect catalog updates cheaply.
      responses:
        '200':
          description: Manifest with version, counts, and content hashes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Manifest'
components:
  parameters:
    Fields:
      name: fields
      in: query
      description: |
        Sparse field selection: comma-separated top-level record fields.
        Unknown names (including `details`, not yet selectable) return 400
        `bad_fields`.
      style: form
      explode: false
      schema:
        type: array
        items:
          $ref: '#/components/schemas/SelectableField'
      example: [id, title, canonical_url]
    Limit:
      name: limit
      in: query
      description: Page size. Outside 1..100 or non-integer returns 400 `bad_limit`.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    Cursor:
      name: cursor
      in: query
      description: Opaque cursor copied from a previous `next_cursor`. Do not construct or parse it.
      schema:
        type: string
  headers:
    ETag:
      description: Strong validator — quoted SHA-256 of the exact response body.
      schema:
        type: string
    LastModified:
      description: The catalog build time (manifest `generated_at`), HTTP-date.
      schema:
        type: string
    ACAO:
      description: Always `*`.
      schema:
        type: string
        const: '*'
  responses:
    NotModified:
      description: The `If-None-Match` ETag still matches; no body.
    BadRequest:
      description: Invalid parameter (bad_fields, bad_limit, bad_cursor, bad_filter, bad_sort)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: bad_filter
              message: 'unknown topic: front-end'
    NotFound:
      description: Unknown resource id
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: not_found
              message: "no resource 'nope'"
    MethodNotAllowed:
      description: Any method other than GET, HEAD, OPTIONS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: method_not_allowed
              message: method not allowed; use GET, HEAD, or OPTIONS
    Internal:
      description: Unexpected function failure
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    CatalogUnavailable:
      description: The function could not load the deployment's catalog assets
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    ResourceType:
      type: string
      enum: [article-guide, dataset, directory-gallery, documentation, library-framework, other, provider, repository, service-platform, template-starter, tool]
    Topic:
      type: string
      enum: [ai-agents, app-development, backend, cloud-infrastructure, databases, design, developer-tools, devops, frontend, inference, observability, productivity, security, self-hosting, testing, web-development]
    UseCase:
      type: string
      enum: [automate-workflows, build-interfaces, create-media, deploy-applications, discover-design-references, generate-code, host-models, learn-technique, manage-agents, monitor-systems, operate-databases, provision-infrastructure, run-inference, search-code, test-software]
    Interface:
      type: string
      enum: [api, cli, desktop, extension, mcp, web]
    Technology:
      type: string
      enum: [anthropic-api, claude-code, docker, electron, github-actions, go, javascript, kubernetes, mcp-protocol, neovim, next-js, node-js, ollama, openai-api, postgres, python, react, rust, sqlite, svelte, tailwind-css, typescript, vscode, vue, zed]
    Channel:
      type: string
      enum: [share-tech, providers]
    SelectableField:
      type: string
      enum: [schema_version, id, title, canonical_url, brief, caveat, resource_type, topics, use_cases, interfaces, technologies, license, open_source, display_period, legacy_categories, source, shared_on, verification]
    Resource:
      type: object
      description: |
        One canonical record (catalog/resources/<id>.json). Validated by
        schemas/resource.schema.json. With `fields`, only the requested
        keys are present.
      required: [schema_version, id, title, canonical_url, brief, resource_type, topics, use_cases, source, shared_on]
      properties:
        schema_version:
          type: string
          const: '1.0'
        id:
          type: string
          description: Immutable slug identity; never regenerated.
          example: openrouter
        title:
          type: string
          maxLength: 160
        canonical_url:
          type: string
          format: uri
          description: Primary destination; HTTPS only; unique across the catalog.
        brief:
          type: string
          description: ~2-sentence editorial summary.
          maxLength: 1200
        caveat:
          type: [string, 'null']
          description: Warning lifted from the brief (typically an unverified claim); null if none.
        details:
          type: [string, 'null']
          maxLength: 2000
          description: |
            Researched long-form breakdown of what the resource is, written
            from the live page (notes/details-*.md). Null until enriched.
            Not selectable via `fields` yet.
        resource_type:
          $ref: '#/components/schemas/ResourceType'
        topics:
          type: array
          minItems: 1
          maxItems: 5
          items:
            $ref: '#/components/schemas/Topic'
        use_cases:
          type: array
          minItems: 1
          maxItems: 6
          items:
            $ref: '#/components/schemas/UseCase'
        interfaces:
          type: array
          items:
            $ref: '#/components/schemas/Interface'
        technologies:
          type: array
          items:
            $ref: '#/components/schemas/Technology'
        license:
          type: [string, 'null']
          description: Only when verified from the source; never inferred (currently always null).
        open_source:
          type: [boolean, 'null']
          description: true only when the brief literally says open source; unknown stays null.
        display_period:
          type: string
          description: Site week label (e.g. "24 Sep–1 Oct 2026") or "providers".
        legacy_categories:
          type: array
          description: The six frozen site categories (compatibility only).
          items:
            type: string
            enum: [ai-tool, dev-tool, github, web-app, article, providers]
        source:
          type: object
          required: [channel, sharer]
          properties:
            channel:
              $ref: '#/components/schemas/Channel'
            sharer:
              type: string
              description: Discord username as shown in the channel.
        shared_on:
          type: string
          format: date
          description: Date the link was shared in Discord (evidence-traced, never inferred).
        verification:
          type: object
          required: [status]
          properties:
            status:
              type: string
              enum: [reachable, unreachable, unchecked]
            checked_at:
              type: [string, 'null']
              format: date-time
            final_url:
              type: [string, 'null']
    SearchResponse:
      type: object
      required: [query, filters, sort, limit, results, next_cursor]
      properties:
        query:
          type: string
          description: The `q` value as received.
        filters:
          type: object
          description: |
            Echo of the applied filters. Facet families echo a string for one
            value or an array for several; `open_source` echoes a boolean;
            `from`/`to` echo the date strings.
          additionalProperties: true
        sort:
          type: string
        limit:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/Resource'
        next_cursor:
          type: [string, 'null']
    ResourcePage:
      type: object
      required: [records, next_cursor, total]
      properties:
        records:
          type: array
          items:
            $ref: '#/components/schemas/Resource'
        next_cursor:
          type: [string, 'null']
        total:
          type: integer
          description: Total records in the catalog.
    Facets:
      type: object
      required: [resource_type, topic, use_case, interface, technology, channel, open_source]
      description: "Family -> {value: count}. `open_source` has keys \"true\" and \"false\"."
      additionalProperties:
        type: object
        additionalProperties:
          type: integer
          minimum: 0
      example:
        channel:
          share-tech: 221
          providers: 89
    TaxonomyRegistry:
      type: object
      required: [facet, cardinality, values]
      properties:
        $id:
          type: string
        facet:
          type: string
        cardinality:
          type: string
        note:
          type: string
        values:
          type: object
          additionalProperties:
            type: object
            properties:
              label:
                type: string
              definition:
                type: string
              aliases:
                type: array
                items:
                  type: string
              status:
                type: string
    Taxonomy:
      type: object
      required: [resource-types, topics, use-cases, interfaces, technologies, synonyms]
      properties:
        resource-types:
          $ref: '#/components/schemas/TaxonomyRegistry'
        topics:
          $ref: '#/components/schemas/TaxonomyRegistry'
        use-cases:
          $ref: '#/components/schemas/TaxonomyRegistry'
        interfaces:
          $ref: '#/components/schemas/TaxonomyRegistry'
        technologies:
          $ref: '#/components/schemas/TaxonomyRegistry'
        synonyms:
          type: object
          properties:
            note:
              type: string
            synonyms:
              type: object
              description: Query term -> taxonomy slug (query expansion only).
              additionalProperties:
                type: string
    Manifest:
      type: object
      required: [api_version, record_count, resources_sha256]
      properties:
        api_version:
          type: string
          example: '1'
        generated_at:
          type: string
          format: date-time
        record_count:
          type: integer
        channels:
          type: array
          items:
            $ref: '#/components/schemas/Channel'
        resources_sha256:
          type: string
          description: SHA-256 of the exact resources.json bytes.
        endpoints:
          type: object
          description: Static endpoint registry (relative paths).
          properties:
            records:
              type: string
            taxonomy:
              type: string
            facets:
              type: string
    Error:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: string
              enum: [bad_fields, bad_limit, bad_cursor, bad_filter, bad_sort, not_found, method_not_allowed, catalog_unavailable, internal]
            message:
              type: string
              description: Human-readable; do not parse.
