openapi: 3.1.0
info:
  title: CrowLingo — Public Read API
  version: 1.0.0
  description: |
    Read-only API for CrowLingo, an editorial publication on AI-powered
    animal language processing for the American crow. Supports natural-
    language queries via the NLWEB `ask` verb and a Machine Capability
    Profile (MCP) endpoint.
  contact:
    name: CrowLingo
    email: contact@kymatalabs.com
    url: https://crowlingo.org
  license:
    name: CC-BY-NC-4.0 (content) · MIT (source)
    url: https://crowlingo.org/terms
servers:
  - url: https://crowlingo.org
    description: Production
paths:
  /api/ask:
    get:
      operationId: askGet
      summary: Natural-language query across the CrowLingo content registry (NLWEB).
      description: |
        Returns a JSON-LD SearchResultsPage with itemListElement entries.
        Implements the NLWEB `ask` verb. Query the site as if you were
        asking a question.
      parameters:
        - name: q
          in: query
          required: true
          description: The natural-language query (1-500 chars).
          schema:
            type: string
            minLength: 1
            maxLength: 500
            example: "How do I cluster crow vocalizations?"
        - name: limit
          in: query
          required: false
          description: Max items to return (1-20).
          schema:
            type: integer
            minimum: 1
            maximum: 20
            default: 8
      responses:
        "200":
          description: JSON-LD SearchResultsPage
          content:
            application/ld+json:
              schema:
                type: object
                properties:
                  "@context":
                    type: string
                    example: "https://schema.org"
                  "@type":
                    type: string
                    example: "SearchResultsPage"
                  name:
                    type: string
                  query:
                    type: string
                  numberOfItems:
                    type: integer
                  itemListElement:
                    type: array
                    items:
                      type: object
                      properties:
                        "@type":
                          type: string
                          example: "ListItem"
                        position:
                          type: integer
                        url:
                          type: string
                        name:
                          type: string
                        description:
                          type: string
    post:
      operationId: askPost
      summary: Natural-language query (POST body for long queries).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [q]
              properties:
                q:
                  type: string
                limit:
                  type: integer
      responses:
        "200":
          description: JSON-LD SearchResultsPage (same shape as GET).

  /api/mcp:
    get:
      operationId: getMCP
      summary: Machine Capability Profile (NLWEB WebAPI description).
      description: Returns a schema.org WebAPI describing this site's capabilities.
      responses:
        "200":
          description: JSON-LD WebAPI document with nlweb block.
          content:
            application/ld+json:
              schema:
                type: object

  /llms.txt:
    get:
      operationId: getLLMs
      summary: Compact LLM discovery file (Howard llms.txt standard).
      responses:
        "200":
          description: Markdown-shaped sitemap for LLMs.
          content:
            text/plain:
              schema:
                type: string

  /llms-full.txt:
    get:
      operationId: getLLMsFull
      summary: Extended LLM reference with per-page metadata + FAQs.
      responses:
        "200":
          description: Markdown reference document.
          content:
            text/plain:
              schema:
                type: string

  /ai.json:
    get:
      operationId: getAIJson
      summary: Structured site registry (brand, keywords, sections, endpoints).
      responses:
        "200":
          description: JSON document.
          content:
            application/json:
              schema:
                type: object

  /feed.json:
    get:
      operationId: getFeedJson
      summary: JSON Feed 1.1 of all content entities, newest-first.
      responses:
        "200":
          description: JSON Feed 1.1 document.
          content:
            application/feed+json:
              schema:
                type: object

  /schema-feed.json:
    get:
      operationId: getSchemaFeed
      summary: JSON-LD DataFeed of all content with schema.org typing.
      responses:
        "200":
          description: JSON-LD DataFeed.
          content:
            application/ld+json:
              schema:
                type: object

  /sitemap.xml:
    get:
      operationId: getSitemap
      summary: Standard XML sitemap with every public URL.
      responses:
        "200":
          description: XML sitemap.
          content:
            application/xml:
              schema:
                type: string
