Crosstabs Operations API

openapi: 3.2.0
info:
  title: Crosstabs Public Aggregate Statistics Operations API
  version: 1.0.0
  description: 'Existing free, accountless endpoints for aggregate integer frequency counts. No respondent-row upload or private project APIs are defined here. All inferential tables require 2–12 rows and columns, rectangular shape, positive row/column margins, and grand total ≤ 1000000000000. Fractional/weighted cells are rejected. These are ordinary independent-frequency methods, not survey-design inference. Source: lib/api/contingency-handler.ts and app/api/v1 route handlers. Unknown /api paths return HTTP 404 JSON with error, code=endpoint_not_found, hint and documentation; HEAD returns the same status without a body. API schema version is separate from application and PyPI package versions. Public REST v1 compatibility policy: breaking changes use a new major URL prefix rather than silently changing /api/v1. Additive response fields may be introduced; clients should tolerate unknown fields. Current v1 endpoints are not deprecated and have no scheduled sunset. If a deprecation is scheduled, the public changelog and developer documentation will publish the affected endpoints, migration guidance and planned dates. This policy is not an availability SLA or a promise of indefinite service. See https://www.crosstabs.com/changelog and https://www.crosstabs.com/developers for published changes and migration guidance.'
  contact:
    name: Crosstabs support
    email: support@crosstabs.com
    url: https://www.crosstabs.com/support
servers:
- url: https://www.crosstabs.com
security: []
tags:
- name: Operations
paths:
  /api/health:
    get:
      operationId: getHealth
      summary: Read application and known-answer statistics self-check
      tags:
      - Operations
      responses:
        '200':
          description: Operational. Trust-readiness pending evidence is separate and does not mark runtime health degraded.
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store, max-age=0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthReport'
        '503':
          description: Runtime or statistics self-check degraded.
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store, max-age=0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthReport'
    head:
      operationId: headHealth
      summary: Read health status without a response body
      tags:
      - Operations
      responses:
        '200':
          description: Operational, empty body.
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store, max-age=0
        '503':
          description: Degraded, empty body.
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store, max-age=0
components:
  schemas:
    HealthReport:
      type: object
      properties:
        schemaVersion:
          type: integer
          const: 3
        service:
          type: string
          const: crosstabs.com
        status:
          type: string
          enum:
          - operational
          - degraded
        checkedAt:
          type: string
          format: date-time
        build:
          type: object
          properties:
            deploymentId:
              type:
              - string
              - 'null'
            deploymentUrl:
              type:
              - string
              - 'null'
            sourceRevision:
              type:
              - string
              - 'null'
            sourceBranch:
              type:
              - string
              - 'null'
            applicationVersion:
              type: string
            provenance:
              type: object
              properties:
                confidence:
                  type: string
                  enum:
                  - metadata_only
                  - unverified
                limitations:
                  type: array
                  items:
                    type: string
              required:
              - confidence
              - limitations
          required:
          - deploymentId
          - deploymentUrl
          - sourceRevision
          - sourceBranch
          - applicationVersion
          - provenance
        trustReadiness:
          type: object
          properties:
            status:
              type: string
              enum:
              - pending
              - evidence_recorded
            affectsOperationalStatus:
              type: boolean
              const: false
            basis:
              type: string
              const: checked-in-release-contract
            contractUpdatedAt:
              type: string
            pendingEvidence:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  detail:
                    type: string
                required:
                - id
                - name
                - detail
            limitations:
              type: array
              items:
                type: string
          required:
          - status
          - affectsOperationalStatus
          - basis
          - contractUpdatedAt
          - pendingEvidence
          - limitations
        checks:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                enum:
                - application_runtime
                - statistics_engine
              name:
                type: string
              status:
                type: string
                enum:
                - operational
                - degraded
              detail:
                type: string
            required:
            - id
            - name
            - status
            - detail
      required:
      - schemaVersion
      - service
      - status
      - checkedAt
      - build
      - trustReadiness
      - checks
externalDocs:
  description: Examples, statistical limits, MCP and local CLI setup
  url: https://www.crosstabs.com/developers
x-crosstabs-interfaces:
  description: Informational Crosstabs extension, not an agent-manifest standard. MCP uses its own initialization, tools/list and tools/call protocol rather than the REST schemas below.
  openapi: https://www.crosstabs.com/openapi.json
  documentation: https://www.crosstabs.com/developers
  publicAggregateMcp:
    url: https://www.crosstabs.com/api/headless-mcp
    transport: Streamable HTTP
    toolCount: 5
    tools:
    - search
    - fetch
    - get_headless_capabilities
    - analyze_crosstab
    - render_crosstab
    maxPostBytes: 16384
    requestsPerMinutePerProcessClient: 60
    dataBoundary: Fixed public evidence and bounded aggregate counts only; no respondent rows or private projects.
  mcpSetup: https://www.crosstabs.com/mcp
  localPackage: https://pypi.org/project/crosstabs/1.5.1/
  evidence: https://www.crosstabs.com/evidence.json
  localCli:
    package: crosstabs==1.5.1
    install: pip install crosstabs==1.5.1
    command: crosstabs-headless
    transport: stdio
    dataBoundary: Local project processing; the AI client has its own data policies.