openapi: 3.1.0
info:
  title: 8bitconcepts Research API
  description: |
    Programmatic access to 8bitconcepts research on enterprise AI strategy,
    governance, and operational risk. Designed for AI agents and crawlers
    that need a discoverable, structured index of available research.
  version: "1.0.0"
  contact:
    name: 8bitconcepts
    url: https://8bitconcepts.com
    email: hello@8bitconcepts.com
  license:
    name: Proprietary — research summaries citable, full text © 8bitconcepts
    url: https://8bitconcepts.com
servers:
  - url: https://8bitconcepts.com
    description: Production
paths:
  /.well-known/agent.json:
    get:
      operationId: getAgentManifest
      summary: Agent-facing manifest
      responses:
        "200":
          description: Agent manifest with commerce endpoints
          content:
            application/json:
              schema:
                type: object
  /.well-known/commerce.json:
    get:
      operationId: getCommerceManifest
      summary: Agent-readable commerce manifest
      responses:
        "200":
          description: Commerce manifest for 8bitconcepts paid offers
          content:
            application/json:
              schema:
                type: object
  /api/v1/catalog:
    get:
      operationId: getCommerceCatalog
      summary: List paid products
      responses:
        "200":
          description: Catalog of paid 8bitconcepts offers
          content:
            application/json:
              schema:
                type: object
  /api/v1/quote:
    get:
      operationId: getDiagnosticQuote
      summary: Static quote for the AI diagnostic
      responses:
        "200":
          description: Static quote with total and checkout URL
          content:
            application/json:
              schema:
                type: object
  /api/v1/checkout:
    get:
      operationId: getDiagnosticCheckout
      summary: Static Stripe Payment Link and SPT checkout handoff
      responses:
        "200":
          description: Checkout URL for the AI diagnostic plus the external SPT settlement endpoint hosted on aidevboard.com.
          content:
            application/json:
              schema:
                type: object
  /local/:
    get:
      operationId: getLocalConsultingHub
      summary: Pacific Northwest AI consulting service-area hub
      responses:
        "200":
          description: HTML hub linking city-specific local AI consulting pages
          content:
            text/html:
              schema:
                type: string
  /local/{city}.html:
    get:
      operationId: getLocalConsultingCityPage
      summary: City-specific Pacific Northwest AI consulting page
      description: |
        Returns one city-specific local SEO page for embedded AI consulting.
        Current city slugs are vancouver-wa, camas-wa, portland-or, tigard-or,
        beaverton-or, hillsboro-or, lake-oswego-or, salem-or, oregon-city-or, gresham-or, tualatin-or, wilsonville-or,
        sherwood-or, newberg-or, mcminnville-or, forest-grove-or, troutdale-or, battle-ground-wa, ridgefield-wa, and washougal-wa.
      parameters:
        - name: city
          in: path
          required: true
          description: Local page slug without the .html suffix.
          schema:
            type: string
            enum:
              - vancouver-wa
              - camas-wa
              - portland-or
              - tigard-or
              - beaverton-or
              - hillsboro-or
              - lake-oswego-or
              - salem-or
              - oregon-city-or
              - gresham-or
              - tualatin-or
              - wilsonville-or
              - sherwood-or
              - newberg-or
              - mcminnville-or
              - forest-grove-or
              - troutdale-or
              - battle-ground-wa
              - ridgefield-wa
              - washougal-wa
      responses:
        "200":
          description: HTML local consulting landing page
          content:
            text/html:
              schema:
                type: string
        "404":
          description: City page not found
  /research.json:
    get:
      operationId: listResearchPapers
      summary: List all research papers
      description: |
        Returns a structured ItemList of every research paper, including slug,
        title, summary, canonical URL, and topic tags. Use this as the entry
        point for discovering research programmatically.
      responses:
        "200":
          description: ItemList of research papers
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResearchIndex"
  /research/{slug}.html:
    get:
      operationId: getResearchPaper
      summary: Fetch a single research paper as HTML
      description: |
        Returns the full HTML article for a given paper slug. Each paper
        includes Open Graph + Twitter card metadata and is structured for
        clean text extraction by AI crawlers.
      parameters:
        - name: slug
          in: path
          required: true
          description: Paper slug from the research index (e.g. `the-guardrails-gap`).
          schema:
            type: string
            pattern: "^[a-z0-9-]+$"
      responses:
        "200":
          description: HTML article body
          content:
            text/html:
              schema:
                type: string
        "404":
          description: Slug not found
  /llms.txt:
    get:
      operationId: getLLMsTxt
      summary: AI-agent discovery file
      description: Plain-text index of research papers in the llms.txt format.
      responses:
        "200":
          description: llms.txt index
          content:
            text/plain:
              schema:
                type: string
components:
  schemas:
    ResearchIndex:
      type: object
      properties:
        $schema:
          type: string
          example: "https://schema.org/ItemList"
        name:
          type: string
        description:
          type: string
        publisher:
          type: object
          properties:
            name:
              type: string
            url:
              type: string
        license:
          type: string
        updated_at:
          type: string
          format: date
        total:
          type: integer
        papers:
          type: array
          items:
            $ref: "#/components/schemas/ResearchPaper"
    ResearchPaper:
      type: object
      required: [slug, title, summary, url, tags]
      properties:
        slug:
          type: string
          pattern: "^[a-z0-9-]+$"
        title:
          type: string
        summary:
          type: string
        url:
          type: string
          format: uri
        tags:
          type: array
          items:
            type: string