{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/arkova-ai/json-schema/arkova-ai-extraction-response-schema.json",
  "title": "ExtractionResponse",
  "x-generated": "2026-11-01",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/arkova-ai-openapi.json#/components/schemas/ExtractionResponse",
  "type": "object",
  "properties": {
    "operationId": {
      "type": "string",
      "format": "uuid",
      "description": "Present on durable receipt responses."
    },
    "creditState": {
      "type": "string",
      "enum": [
        "debited",
        "exempt",
        "not_charged"
      ],
      "description": "Durable outcome; API keys never inherit JWT exemptions."
    },
    "cached": {
      "type": "boolean",
      "description": "For durable calls, true only for not_charged cache reuse."
    },
    "receipt": {
      "$ref": "#/$defs/ExtractionReceipt"
    },
    "fields": {
      "type": "object",
      "description": "Extracted metadata fields (keys vary by credential type)",
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "number"
          },
          {
            "type": "boolean"
          },
          {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        ]
      }
    },
    "confidence": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "Extraction confidence score (0-1)"
    },
    "confidenceScores": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": true,
      "description": "API-RICH-02 per-field confidence scores from the extraction manifest."
    },
    "subType": {
      "type": [
        "string",
        "null"
      ],
      "description": "API-RICH-02 fine-grained credential subtype when extracted."
    },
    "description": {
      "type": [
        "string",
        "null"
      ],
      "description": "API-RICH-02 human-readable credential summary when extracted."
    },
    "fraudSignals": {
      "type": [
        "array",
        "null"
      ],
      "description": "Fraud indicators returned by /ai/extract when emitted; /verify does not return fraudSignals today.",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "provider": {
      "type": "string",
      "description": "AI provider used (e.g., gemini, cloudflare-workers-ai)"
    },
    "creditsRemaining": {
      "type": [
        "integer",
        "null"
      ],
      "description": "AI credits remaining after extraction."
    },
    "manifestHash": {
      "type": "string",
      "description": "Hash of the signed extraction manifest."
    },
    "degraded": {
      "type": "boolean",
      "description": "True when extraction ran in fallback/degraded mode. A degraded answer is a stand-in guess, not an analysis: the credit is refunded, it is never cached, and an identical retry reaches the model again."
    },
    "fallbackReason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Reason extraction used fallback behavior, when applicable."
    },
    "degradedReason": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "timeout",
        "provider_unavailable"
      ],
      "description": "Typed cause when degraded is true; null otherwise."
    },
    "retryable": {
      "type": "boolean",
      "description": "Present and true on a degraded answer: retrying can succeed."
    }
  },
  "$defs": {
    "ExtractionReceipt": {
      "type": "object",
      "required": [
        "id",
        "manifestId",
        "manifestHash",
        "receiptHash",
        "fingerprint",
        "requestDigest",
        "modelContractHash"
      ],
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "manifestId": {
          "type": "string",
          "format": "uuid"
        },
        "manifestHash": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        },
        "receiptHash": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        },
        "fingerprint": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        },
        "requestDigest": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        },
        "modelContractHash": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        }
      }
    }
  }
}