AI Intelligence

Extract credential metadata

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.

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

Query parameters

scope'user'

Explicit personal workspace; mutually exclusive with org_id.

org_idstring uuid

Authorized organization workspace; does not override key authority.

Request body

requestIdstring uuid

Stable durable extraction UUID. Required for API keys; opts JWT calls into receipt recovery.

strippedTextstring required

Locally redacted text; never raw document text, file bytes or paths.

credentialTypestring required

Type hint for extraction; not restricted to a five-category subset.

issuerHintstring

Optional locally redacted issuer hint.

fingerprintstring required

SHA-256 of the original document bytes; durable requests require lowercase hex.

Response

Extracted metadata fields

operationIdstring uuid

Present on durable receipt responses.

creditState'debited' | 'exempt' | 'not_charged'

Durable outcome; API keys never inherit JWT exemptions.

cachedboolean

For durable calls, true only for not_charged cache reuse.

fieldsobject

Extracted metadata fields (keys vary by credential type)

confidencenumber

Extraction confidence score (0-1)

confidenceScoresobject nullable

API-RICH-02 per-field confidence scores from the extraction manifest.

subTypestring nullable

API-RICH-02 fine-grained credential subtype when extracted.

descriptionstring nullable

API-RICH-02 human-readable credential summary when extracted.

fraudSignalsobject[] nullable

Fraud indicators returned by /ai/extract when emitted; /verify does not return fraudSignals today.

providerstring

AI provider used (e.g., gemini, cloudflare-workers-ai)

creditsRemaininginteger nullable

AI credits remaining after extraction.

manifestHashstring

Hash of the signed extraction manifest.

degradedboolean

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.

fallbackReasonstring nullable

Reason extraction used fallback behavior, when applicable.

degradedReason'timeout' | 'provider_unavailable' nullable

Typed cause when degraded is true; null otherwise.

retryableboolean

Present and true on a degraded answer: retrying can succeed.

Changes

No recorded changes to this operation across all 1 revision of this API.