openapi: 3.1.0
info:
  title: AXIMUR Claim Verification API
  version: 1.0.0
  description: |
    Evidence-bounded claim verification for RAG and AI-agent workflows.
    
    Send a claim + grounding source. Return SUPPORTED / UNSUPPORTED / UNCERTAIN 
    + confidence + reasoning + audit trail.
    
    **Pricing:** $49/mo API Access
    
    **Website:** https://aximur.com
    
    **Contact:** contact@aximur.com
    
    **Get API Access:** https://buy.stripe.com/eVq3cxd9m0Ws5X70IwfIs04
  contact:
    name: AXIMUR Security
    email: contact@aximur.com
    url: https://aximur.com
  license:
    name: Proprietary
    url: https://aximur.com/terms
servers:
  - url: https://api.aximur.com/v1
    description: Production API server
paths:
  /verify:
    post:
      summary: Verify a claim against a grounding source
      description: |
        Evaluates whether a claim is supported, contradicted, or uncertain 
        given the provided grounding source. Returns a structured verdict 
        with confidence, reasoning, and audit trail.
      operationId: verifyClaim
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyRequest'
            examples:
              supported_claim:
                summary: Supported claim with exact match
                value:
                  claim: "The global average temperature in 2023 was 1.45°C above pre-industrial levels."
                  grounding_source: "According to the WMO State of the Global Climate 2023 report, the global average temperature in 2023 was 1.45°C above the pre-industrial baseline (1850–1900)."
              unsupported_claim:
                summary: Contradicted claim
                value:
                  claim: "The global average temperature in 2023 was 2.1°C above pre-industrial levels."
                  grounding_source: "According to the WMO State of the Global Climate 2023 report, the global average temperature in 2023 was 1.45°C above the pre-industrial baseline (1850–1900)."
              uncertain_claim:
                summary: Claim not addressed by source
                value:
                  claim: "Global CO2 emissions peaked in 2023."
                  grounding_source: "According to the WMO State of the Global Climate 2023 report, the global average temperature in 2023 was 1.45°C above the pre-industrial baseline (1850–1900)."
      responses:
        '200':
          description: Successful verification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyResponse'
              examples:
                supported:
                  summary: Supported verdict
                  value:
                    verdict: "SUPPORTED"
                    confidence: 0.96
                    reasoning: "The claim matches the WMO report's stated figure of 1.45°C above pre-industrial levels (1850–1900 baseline). The grounding source directly supports the specific figure and baseline."
                    audit_trail:
                      - claim_span: "global average temperature in 2023 was 1.45°C above pre-industrial levels"
                        source_span: "global average temperature in 2023 was 1.45°C above the pre-industrial baseline (1850–1900)"
                        match_type: "exact_match"
                unsupported:
                  summary: Unsupported verdict
                  value:
                    verdict: "UNSUPPORTED"
                    confidence: 0.98
                    reasoning: "The grounding source states the 2023 temperature anomaly was 1.45°C, which directly contradicts the claim of 2.1°C. The source provides a specific, conflicting figure."
                    audit_trail:
                      - claim_span: "2.1°C above pre-industrial levels"
                        source_span: "1.45°C above the pre-industrial baseline"
                        match_type: "contradiction"
                uncertain:
                  summary: Uncertain verdict
                  value:
                    verdict: "UNCERTAIN"
                    confidence: 0.35
                    reasoning: "The grounding source discusses global temperature anomaly but does not mention CO2 emissions, peak emissions, or emission trends. The claim cannot be evaluated against this source."
                    audit_trail:
                      - claim_span: "Global CO2 emissions peaked in 2023"
                        source_span: ""
                        match_type: "insufficient_evidence"
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "invalid_request"
                  message: "Field 'claim' is required and must be a non-empty string (max 500 characters)."
                  details:
                    field: "claim"
                    max_length: 500
                    received_length: 0
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "unauthorized"
                  message: "Invalid or missing API key. Provide a valid Bearer token in the Authorization header."
                  details:
                    header_present: false
        '403':
          description: Subscription inactive
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "subscription_inactive"
                  message: "Subscription is inactive. Please renew at https://buy.stripe.com/eVq3cxd9m0Ws5X70IwfIs04"
                  details:
                    status: "past_due"
                    checkout_url: "https://buy.stripe.com/eVq3cxd9m0Ws5X70IwfIs04"
        '429':
          description: Rate limited
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Request limit for the window
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: Requests remaining in window
            X-RateLimit-Reset:
              schema:
                type: integer
              description: Unix timestamp when window resets
            Retry-After:
              schema:
                type: integer
              description: Seconds until next request allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "rate_limited"
                  message: "Rate limit exceeded. Limit: 60 requests/minute. Retry after 45 seconds."
                  details:
                    limit: 60
                    window: "minute"
                    retry_after_seconds: 45
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "internal_error"
                  message: "An unexpected error occurred. Please retry or contact support if persistent."
                  details:
                    request_id: "req_abc123xyz"
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "service_unavailable"
                  message: "Service temporarily unavailable. Please retry in 30 seconds."
                  details:
                    retry_after_seconds: 30
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: API key from https://aximur.com/dashboard
  schemas:
    VerifyRequest:
      type: object
      required:
        - claim
        - grounding_source
      properties:
        claim:
          type: string
          description: The claim to verify. Must be a specific, factual assertion.
          minLength: 1
          maxLength: 500
          example: "The global average temperature in 2023 was 1.45°C above pre-industrial levels."
        grounding_source:
          type: string
          description: |
            The evidence to evaluate the claim against. Can be a document, 
            passage, retrieved context, or any text source. AXIMUR evaluates 
            the claim ONLY against this source — no external knowledge is used.
          minLength: 1
          maxLength: 10000
          example: "According to the WMO State of the Global Climate 2023 report, the global average temperature in 2023 was 1.45°C above the pre-industrial baseline (1850–1900)."
    VerifyResponse:
      type: object
      required:
        - verdict
        - confidence
        - reasoning
        - audit_trail
      properties:
        verdict:
          type: string
          enum: ["SUPPORTED", "UNSUPPORTED", "UNCERTAIN"]
          description: The verification verdict.
        confidence:
          type: number
          format: double
          minimum: 0.0
          maximum: 1.0
          description: Model confidence in the verdict (0.0–1.0). Not a calibrated probability.
        reasoning:
          type: string
          description: Step-by-step explanation of how the verdict was reached.
        audit_trail:
          type: array
          description: Span-level evidence linking claim substrings to source substrings.
          items:
            $ref: '#/components/schemas/AuditTrailEntry'
    AuditTrailEntry:
      type: object
      required:
        - claim_span
        - source_span
        - match_type
      properties:
        claim_span:
          type: string
          description: Substring of the claim being evaluated.
        source_span:
          type: string
          description: Corresponding substring from the grounding source. Empty if no match.
        match_type:
          type: string
          enum: ["exact_match", "paraphrase_match", "contradiction", "insufficient_evidence"]
          description: |
            - exact_match: Claim and source text align closely
            - paraphrase_match: Same meaning, different wording
            - contradiction: Source explicitly contradicts claim
            - insufficient_evidence: Source does not address the claim
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum: ["invalid_request", "unauthorized", "subscription_inactive", "rate_limited", "internal_error", "service_unavailable"]
            message:
              type: string
            details:
              type: object
              description: Optional error-specific context