---
title: "Extract credential metadata"
method: POST
path: "/ai/extract"
tags: ["AI Intelligence"]
---

# Extract credential metadata

`POST /ai/extract`

## Request

- Base URL: `https://app.arkova.ai/api/v1`
- URL: `https://app.arkova.ai/api/v1/ai/extract`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - API key in header `X-API-Key`

Extract structured metadata from locally redacted text. Human API-key calls require ai:extract, a stable requestId UUID and current personal or member-bound organization authority; agent keys cannot use extraction. Integrators must remove personal information locally before sending strippedText or issuerHint. The server validates the request shape but does not certify that text is redacted; never send original document bytes or raw OCR text. JWT calls opt into durable receipts by supplying requestId. A first uncached paid operation consumes one AI credit; recovery never invokes the provider or debits again. Unknown outcomes must be recovered by GET, not a new UUID. Gated by ENABLE_AI_EXTRACTION; receipt responses are private/no-store.

## Query parameters

- `scope` 'user'
- `org_id` string, uuid

## Request body

- ExtractionRequest
  - `requestId` string, uuid: Stable durable extraction UUID. Required for API keys; opts JWT calls into receipt recovery.
  - `strippedText` string, required: Locally redacted text; never raw document text, file bytes or paths.
  - `credentialType` string, required: Type hint for extraction; not restricted to a five-category subset.
  - `issuerHint` string: Optional locally redacted issuer hint.
  - `fingerprint` string, required: SHA-256 of the original document bytes; durable requests require lowercase hex.

## Response `200`

Extracted metadata fields

- ExtractionResponse
  - `operationId` string, uuid: Present on durable receipt responses.
  - `creditState` 'debited' | 'exempt' | 'not_charged': Durable outcome; API keys never inherit JWT exemptions.
  - `cached` boolean: For durable calls, true only for not_charged cache reuse.
  - `receipt` ExtractionReceipt
    - `id` string, uuid, required
    - `manifestId` string, uuid, required
    - `manifestHash` string, required
    - `receiptHash` string, required
    - `fingerprint` string, required
    - `requestDigest` string, required
    - `modelContractHash` string, required
  - `fields` object: Extracted metadata fields (keys vary by credential type)
  - `confidence` number: Extraction confidence score (0-1)
  - `confidenceScores` object, nullable: API-RICH-02 per-field confidence scores from the extraction manifest.
  - `subType` string, nullable: API-RICH-02 fine-grained credential subtype when extracted.
  - `description` string, nullable: API-RICH-02 human-readable credential summary when extracted.
  - `fraudSignals` object[], nullable: Fraud indicators returned by /ai/extract when emitted; /verify does not return fraudSignals today.
  - `provider` string: AI provider used (e.g., gemini, cloudflare-workers-ai)
  - `creditsRemaining` integer, nullable: AI credits remaining after extraction.
  - `manifestHash` string: Hash of the signed extraction manifest.
  - `degraded` boolean: 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` string, nullable: Reason extraction used fallback behavior, when applicable.
  - `degradedReason` 'timeout' | 'provider_unavailable', nullable: Typed cause when degraded is true; null otherwise.
  - `retryable` boolean: Present and true on a degraded answer: retrying can succeed.

## Other responses

- `202`: Durable operation is pending or outcome unknown; never claim queue or anchor completion.
- `400`: Invalid request
- `401`: Authentication required
- `402`: Insufficient AI credits
- `403`: Insufficient permissions
- `409`: Request UUID conflict or terminal failed operation. Inspect the original outcome before starting new work.
- `429`: Rate limit exceeded
- `503`: API not enabled (feature flag off)

---

[API](https://skmtc.dev/arkova/apis/arkova-verification-api.md) · [All operations](https://skmtc.dev/arkova/apis/arkova-verification-api/llms.txt) · [OpenAPI document](https://skmtc.dev/arkova/apis/arkova-verification-api/revisions/a14858d1efd4?raw)