AcuiQ Wiki API

openapi: 3.2.0
info:
  title: AcuiQ Wiki API
  version: 2.1.0
  description: 'Acupuncture protocol matching API. Search symptoms, browse meridians, find treatment protocols and search the reference wiki – no account and no API key. Two bulk exports carry a per-request charge over MPP (Machine Payments Protocol), paid through Stripe; every per-query endpoint is free. Licence scope: AcuiQ-authored prose (symptom and meridian descriptions, the wiki, the auricular crosswalk) is licensed CC-BY-4.0: https://creativecommons.org/licenses/by/4.0/. The assembled protocol compilation is not: build on it with attribution, but do not redistribute it whole as a dataset – https://acuiq.com/terms. The underlying findings are the cited sources'' claims – each entry carries its citation; verify against the source before relying on it. Not medical advice: https://acuiq.com/terms'
  contact:
    name: AcuiQ
    url: https://acuiq.com
  license:
    name: Creative Commons Attribution 4.0 International
    identifier: CC-BY-4.0
servers:
- url: https://acuiq.com
  description: Production
tags:
- name: Wiki
paths:
  /api/wiki:
    get:
      operationId: searchWiki
      summary: Search the reference wiki
      description: 'Keyword search over wiki titles and prose, with an English full-text fallback for questions the literal match cannot answer. Ranked titles starting with the term, titles containing it, literal prose hits, then full-text hits by relevance. Rows are identical to the MCP search_wiki tool. Rate limit: 60 req/min.'
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
        description: A keyword, phrase or question (e.g. "moxibustion")
      - name: page
        in: query
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: pageSize
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
      responses:
        '200':
          description: Matching pages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WikiSearchResponse'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Wiki
components:
  schemas:
    WikiSearchRow:
      type: object
      description: The shared wiki-search row (GET /api/wiki?q= and the MCP search_wiki tool).
      properties:
        path:
          type: string
          description: Section and slug, e.g. "safety/pregnancy-and-the-forbidden-points"
        title:
          type: string
        snippet:
          type: string
          description: The passage that matched, else the page description
        basis:
          type: string
        audience:
          type: string
        lastVerified:
          type:
          - string
          - 'null'
          format: date
          description: When the page was last checked against its sources; null if it never has been
        url:
          type: string
          format: uri
        markdown:
          type: string
          format: uri
          description: The whole page as markdown
      required:
      - path
      - title
      - snippet
      - basis
      - audience
      - lastVerified
      - url
      - markdown
    WikiSearchResponse:
      type: object
      properties:
        query:
          type: string
        total:
          type: integer
        page:
          type: integer
        pageSize:
          type: integer
        totalPages:
          type: integer
        hasMore:
          type: boolean
        nextPage:
          type: integer
        pages:
          type: array
          items:
            $ref: '#/components/schemas/WikiSearchRow'
      required:
      - query
      - total
      - page
      - pageSize
      - totalPages
      - hasMore
      - pages
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
          enum:
          - RATE_LIMITED
          - INVALID_PARAMS
          - NOT_FOUND
          - SERVICE_ERROR
          - PAYMENT_REQUIRED
      required:
      - error
  securitySchemes:
    payment:
      type: http
      scheme: Payment
      description: 'MPP (Machine Payments Protocol) (https://mpp.dev), method "stripe", paid with a Stripe shared payment token (SPT), single use scoped to Stripe profile profile_61VcHMvCI7idwYC2zA6VcHMv8oE9roGsBkZRtDHSi0ng. Request the resource without it, answer the WWW-Authenticate challenge from the 402, and retry with Authorization: Payment. Only the two bulk exports use this; everything else on this spec is free and anonymous.'