AcuiQ Symptoms API

openapi: 3.2.0
info:
  title: AcuiQ Symptoms 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: Symptoms
paths:
  /api/symptoms:
    get:
      operationId: searchSymptoms
      summary: Search or list symptoms
      description: 'Fuzzy-search symptom names or get trending symptoms. Rows are identical to the MCP search_symptoms tool. Rate limit: 500 req/min.'
      parameters:
      - name: query
        in: query
        schema:
          type: string
        description: Partial symptom name (e.g. "head")
      - name: popular
        in: query
        schema:
          type: string
          enum:
          - 'true'
        description: Set to "true" to get top 12 trending symptoms
      - name: points
        in: query
        schema:
          type: string
          enum:
          - '1'
        description: 'Set to "1" to append matching acupoints (by code, name, Chinese name or pinyin) as rows with kind: "point"'
      responses:
        '200':
          description: Symptom rows
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SymptomListResponse'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Symptoms
components:
  schemas:
    SymptomRow:
      type: object
      description: The shared symptom-search row (GET /api/symptoms and the MCP search_symptoms tool).
      properties:
        name:
          type: string
          description: Display label (displayName when present, else the taxonomy key)
        displayName:
          type: string
          nullable: true
        url:
          type: string
          format: uri
          description: Canonical symptom page
      required:
      - name
      - displayName
      - url
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
          enum:
          - RATE_LIMITED
          - INVALID_PARAMS
          - NOT_FOUND
          - SERVICE_ERROR
          - PAYMENT_REQUIRED
      required:
      - error
    SymptomListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SymptomRow'
        error:
          type: string
        code:
          type: string
  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.'