Anchoring

Submit credential for anchoring

Submit a credential fingerprint for Bitcoin anchoring. Returns 201 for a new record. A repeat fingerprint for the same caller and organization returns 200 with idempotent: true when supplied private tags agree with the original; the existing record is not overwritten. Different actors in the same organization are not the same idempotency scope. Conflicts return 409 without an existing public_id; see the conflict response for recovery. The receipt uses idempotent, not already_exists. Requires an API key with anchor:write or write:anchors.

post/anchor

Request

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

Request body

fingerprintstring required

SHA-256 document fingerprint (64-char hex; normalized to lowercase)

receipt_idstring uuid

Completed extraction receipt. Requires request_id and matching fingerprint; stored extraction fields are consumed server-side.

request_idstring uuid

Stable submission UUID, distinct from extraction requestId. Required with receipt_id. Replay unchanged input after an uncertain response; changed input conflicts.

filenamestring

Receipt submission basename only; never a local path.

file_sizeinteger

Original document size in bytes for receipt submission.

file_mimestring
labelstring nullable

Optional legacy record label, stored separately from filename and description. It can appear in public credential projections; do not include personal or confidential data. Omit it or pass null when no label is needed.

descriptionstring

Public document description included in verification responses (at most 500 characters)

credential_type'DEGREE' | 'LICENSE' | 'CERTIFICATE' | 'TRANSCRIPT' | 'PROFESSIONAL' | 'CPE' | 'CLE' | 'BADGE' | 'ATTESTATION' | 'FINANCIAL' | 'LEGAL' | 'INSURANCE' | 'SEC_FILING' | 'PATENT' | 'REGULATION' | 'PUBLICATION' | 'CHARITY' | 'ACCREDITATION' | 'FINANCIAL_ADVISOR' | 'BUSINESS_ENTITY' | 'RESUME' | 'MEDICAL' | 'MILITARY' | 'IDENTITY' | 'CONTRACT_PRESIGNING' | 'CONTRACT_POSTSIGNING' | 'OTHER' | 'DIPLOMA'

DIPLOMA is a legacy input alias stored as DEGREE; responses use the canonical credential type.

action'queue' | 'instant'

Queue for batch anchoring or reserve one anchor credit to start now

metadataobject

PII-stripped metadata fields

Response

Existing caller-owned submission (idempotent)

public_idstring required
fingerprintstring required
statusstring required

Record lifecycle: PENDING means accepted for processing; SUBMITTED means sent to the network; SECURED means confirmed. Acceptance is not proof of confirmation. An idempotent response returns the current record status.

created_atstring date-time required
record_uristring uri required
action'queue' | 'instant' required
credits_exemptboolean nullable

True when the durable Instant claim used an actor usage exemption; credit_state is null because no credit was spent or refunded.

credit_state'pending' | 'spent' | 'refunded' nullable required
instant_status'QUEUED' | 'PROCESSING' | 'NEEDS_CREDIT' | 'RETRYABLE' | 'HELD' | 'SUBMITTED' | 'FAILED' nullable required

Instant-processing state, separate from record status. null: normal queue with no instant intent. QUEUED: accepted, waiting for a worker. PROCESSING: worker owns the attempt. NEEDS_CREDIT: add a credit before retrying instant processing. RETRYABLE: a safe retry is available. HELD: uncertain network outcome; poll status and do not create a new record. SUBMITTED: sent, awaiting network confirmation. FAILED: instant attempt ended; inspect submission status before retrying. Example: status=PENDING, instant_status=NEEDS_CREDIT means the record was accepted but instant processing needs credit; status=SUBMITTED, instant_status=SUBMITTED is not yet SECURED.

idempotentboolean required

Changes

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