AcuiQ Protocols API

openapi: 3.2.0
info:
  title: AcuiQ Protocols 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: Protocols
paths:
  /api/protocols:
    get:
      operationId: searchProtocols
      summary: Search treatment protocols by symptoms
      description: 'Find acupuncture protocols matching the given symptoms, optionally filtered by age and sex. Returns up to 50 matches ranked by relevance, each carrying provenance (sourceKind, source, caveat). The same ranked pipeline as the MCP search_protocols tool, which returns a compact projection of these rows. Rate limit: 200 req/min.'
      parameters:
      - name: symptoms
        in: query
        required: true
        schema:
          type: string
        description: Comma-separated symptom names (max 10)
      - name: age
        in: query
        schema:
          type: number
          minimum: 0
          maximum: 130
        description: Patient age
      - name: sex
        in: query
        schema:
          type: string
          enum:
          - male
          - female
        description: Patient sex
      responses:
        '200':
          description: Matching protocols
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResultResponse'
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Protocols
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
          enum:
          - RATE_LIMITED
          - INVALID_PARAMS
          - NOT_FOUND
          - SERVICE_ERROR
          - PAYMENT_REQUIRED
      required:
      - error
    SearchResult:
      type: object
      properties:
        matches:
          type: array
          items:
            $ref: '#/components/schemas/ProtocolMatch'
        directMatches:
          type: array
          items:
            $ref: '#/components/schemas/Treatment'
          description: Points whose indications list the searched symptoms, returned only when no protocol matched. Index entries, not prescriptions.
        studyBacked:
          type: boolean
          description: Whether any study-reported protocol covers this query at all, decided over the whole ranked candidate set rather than the page returned. False means every prescription on offer comes from a clinical text or a website.
        query:
          type: array
          items:
            type: string
          description: Normalized symptom names
        queryAge:
          type: integer
          nullable: true
        querySex:
          type: string
          nullable: true
      required:
      - matches
      - query
    ProtocolTreatment:
      type: object
      properties:
        id:
          type: integer
        treatment:
          $ref: '#/components/schemas/Treatment'
      required:
      - id
      - treatment
    Treatment:
      type: object
      properties:
        id:
          type: integer
        code:
          type: string
        name:
          type: string
          nullable: true
        type:
          type: string
        chineseName:
          type: string
          nullable: true
        pinyin:
          type: string
          nullable: true
        location:
          type: string
          nullable: true
        warnings:
          type: string
          nullable: true
        meridian:
          $ref: '#/components/schemas/Meridian'
        indications:
          type: array
          items:
            $ref: '#/components/schemas/Symptom'
      required:
      - id
      - code
      - type
      - indications
    Symptom:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
      required:
      - id
      - name
    SearchResultResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/SearchResult'
        error:
          type: string
        code:
          type: string
    ProtocolMatch:
      type: object
      properties:
        protocol:
          $ref: '#/components/schemas/Protocol'
        score:
          type: number
          minimum: 0
          maximum: 1
          description: Fuzzy match relevance score
        sourceKind:
          type: string
          enum:
          - study
          - text
          - web
          - unsourced
          description: How the source reference was classified
        source:
          type: string
          description: Human-readable source label
        caveat:
          type: string
          description: Plain-language statement of what this row is
        substantiation:
          type: object
          description: 'Which of this row''s points a study-reported protocol for the same query also chose. On a study-reported row it compares against every OTHER study, matched on distinct reference so a paper carrying several prescriptions cannot corroborate itself; on any other row it compares against all of them. Absent when no study but this row''s own covers the query (see studyBacked). An empty `points` array is meaningful: studies cover the query and none used any of these points. Two limits travel with it — a shared point is not an endorsement of the prescription, because no study tested it; and a second reference is not necessarily a second research group.'
          properties:
            points:
              type: array
              items:
                type: string
              description: Point codes shared with a study-reported protocol
            study:
              type: object
              properties:
                label:
                  type: string
                url:
                  type: string
                  description: Present when the study is directly reachable
              required:
              - label
          required:
          - points
          - study
      required:
      - protocol
      - score
      - sourceKind
      - source
      - caveat
    Protocol:
      type: object
      properties:
        id:
          type: integer
        ref:
          type: string
          nullable: true
          description: Source reference
        cred:
          type: integer
          nullable: true
          description: Credibility score
        modality:
          type: array
          items:
            type: string
            enum:
            - needling
            - electroacupuncture
            - moxibustion
            - acupressure
            - press-needle
            - teas
            - laser
            - embedding
            - injection
            - application
            - bloodletting
            - cupping
          description: How the source delivered the points; empty when it does not say
        sessions:
          type: integer
          nullable: true
          description: Treatment sessions in the course the source ran
        courseDays:
          type: integer
          nullable: true
          description: Calendar length of that course in days, follow-up excluded
        outcome:
          type: string
          enum:
          - positive
          - no-effect
          - unreported
          - not-tested
          description: What the source reported for this arm; not-tested is a textbook or web indication. Search returns positive and not-tested rows, and no-effect rows whose comparator is sham
        comparator:
          type: string
          nullable: true
          enum:
          - sham
          - active
          - usual-care
          - waitlist
          - none
          description: What the arm was measured against; none is a single-arm before-and-after study. Null where the result has not been read
        note:
          type: string
          nullable: true
          description: An erratum in the source, or how this row relates to sibling rows from the same paper
        sex:
          type: string
          nullable: true
        age:
          type: number
          nullable: true
          description: Recorded cohort age, often a mean
        symptoms:
          type: array
          items:
            $ref: '#/components/schemas/Symptom'
        protocolTreatments:
          type: array
          items:
            $ref: '#/components/schemas/ProtocolTreatment'
      required:
      - id
      - protocol
      - symptoms
      - protocolTreatments
    Meridian:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        description:
          type: string
          nullable: true
        element:
          type: string
          nullable: true
      required:
      - id
      - name
  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.'