AcuiQ Corpus API

openapi: 3.2.0
info:
  title: AcuiQ Corpus 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: Corpus
paths:
  /api/corpus:
    get:
      operationId: getCorpus
      summary: The complete protocol corpus as JSONL
      description: Every extracted protocol with its resolved source, credibility score, reported course length, catalogue point codes and canonical symptom names – one JSON object per line. The same rows as protocols.jsonl in the corpus licence. Priced at $1.00 over MPP (Machine Payments Protocol).
      x-payment-info:
        method: stripe
        intent: charge
        amount: '100'
        currency: usd
        description: The complete AcuiQ protocol corpus as JSONL.
      security:
      - payment: []
      responses:
        '200':
          description: 'JSONL corpus: header lines beginning with "#", then one CorpusLine per line'
          content:
            application/x-ndjson:
              schema:
                $ref: '#/components/schemas/CorpusLine'
        '402':
          description: 'Payment required. The WWW-Authenticate: Payment header carries the challenge; the body states the price and lists the free alternatives.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Payment verification temporarily unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Corpus
components:
  schemas:
    CorpusLine:
      type: object
      description: 'One line of GET /api/corpus and of protocols.jsonl in the corpus zip: one source reporting one point selection for these symptoms. It is not evidence the selection worked.'
      properties:
        id:
          type: integer
        ref:
          type: string
          nullable: true
          description: Source reference as extracted
        source:
          type: object
          description: The reference as the site classifies it. kind study means the ref resolves to a DOI or a PubMed record, not that the finding was positive
          properties:
            kind:
              type: string
              enum:
              - study
              - text
              - web
              - unsourced
            label:
              type: string
            url:
              type: string
              description: Present when the source is directly reachable
          required:
          - kind
          - label
        cred:
          type: integer
          nullable: true
          description: Credibility score of the source, not of the finding
        modality:
          type: array
          items:
            type: string
            enum:
            - needling
            - electroacupuncture
            - moxibustion
            - acupressure
            - press-needle
            - teas
            - laser
            - embedding
            - injection
            - application
            - bloodletting
            - cupping
        sessions:
          type: integer
          nullable: true
        courseDays:
          type: integer
          nullable: true
        sex:
          type: string
          nullable: true
        age:
          type: number
          nullable: true
          description: Recorded cohort age, often a mean
        outcome:
          type: string
          enum:
          - positive
          - no-effect
          - unreported
          - not-tested
        comparator:
          type: string
          nullable: true
          enum:
          - sham
          - active
          - usual-care
          - waitlist
          - none
          description: Null where the result has not been read
        note:
          type: string
          description: Absent when the row has none
        points:
          type: array
          items:
            type: string
          description: Catalogue point codes
        symptoms:
          type: array
          items:
            type: string
          description: Canonical symptom names
        raw:
          type: string
          nullable: true
          description: The treatments as the source wrote them
      required:
      - id
      - ref
      - source
      - cred
      - modality
      - sessions
      - courseDays
      - sex
      - age
      - outcome
      - comparator
      - points
      - symptoms
      - raw
    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.'