API Reference

Overview

Base URL: https://app.arkova.ai/api/v1

• All responses are JSON. All timestamps are ISO 8601 UTC.
• The verification response schema is frozen — no breaking changes without a v2 prefix and 12-month deprecation.

Authentication

Two authentication methods are supported: Bearer token and X-API-Key header.

# Bearer token
curl https://app.arkova.ai/api/v1/verify/ARK-2026-001 \
  -H "Authorization: Bearer YOUR_API_KEY"

# X-API-Key header
curl https://app.arkova.ai/api/v1/verify/ARK-2026-001 \
  -H "X-API-Key: YOUR_API_KEY"

• API keys are created in the dashboard under Settings → API Keys.
• Keys use HMAC-SHA256 — the raw key is shown once at creation and never stored.
• Scoped permissions: verify, verify:batch, keys:manage, usage:read.

Verification

GET /verify/{publicId}

Verify a single credential. Authentication is optional — an API key unlocks higher rate limits.

Response schema:

{
  "verified": true,
  "status": "ACTIVE",
  "issuer_name": "University of Michigan",
  "recipient_identifier": "sha256:ab3f...",
  "credential_type": "DIPLOMA",
  "issued_date": "2026-01-15T00:00:00Z",
  "expiry_date": null,
  "anchor_timestamp": "2026-03-10T08:00:00Z",
  "bitcoin_block": 204567,
  "network_receipt_id": "b8e381df09ca404e...",
  "merkle_proof_hash": null,
  "record_uri": "https://app.arkova.io/verify/ARK-2026-001",
  "jurisdiction": "US-MI"
}

Status values: ACTIVE, REVOKED, SUPERSEDED, EXPIRED, PENDING

GET /verify/{publicId}/proof

Download the cryptographic proof package for a credential.

GET /verify/search

Semantic search across credentials — designed for AI agents, ATS platforms, and background check integrations.

GET /verify/entity

Cross-reference an entity against public records (EDGAR, Federal Register, DAPIP, OpenAlex).

Batch Verification

POST /verify/batch

Verify up to 100 credentials in a single request. Authentication is required (API key).

Request body:

{
  "public_ids": ["ARK-2026-001", "ARK-2026-002"]
}

• Synchronous for ≤20 items. For >20 items the request is processed asynchronously and returns a job_id.

GET /jobs/{jobId}

Poll the status of an async batch verification job.

Anchoring

POST /anchor

Submit a credential fingerprint for network anchoring. Authentication is required (API key or x402). The endpoint is idempotent — it returns 200 if the fingerprint already exists.

Request body:

{
  "fingerprint": "a1b2c3d4e5f6...64-char-hex",
  "label": "Bachelor of Science in Computer Science",
  "credential_type": "DIPLOMA",
  "metadata": {
    "issuer": "University of Michigan",
    "issued_date": "2026-01-15"
  }
}

Attestations

• Types: identity, employment, education, certification, compliance.
• Lifecycle: Created (active) → Expired (auto) or Revoked (manual).

AI Intelligence

Key Management

All key-management endpoints require Supabase JWT authentication.

Usage & Billing

GET /usage

Returns current-month API usage across all organization keys.

Rate Limits

• Every response includes rate-limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
• HTTP 429 is returned with a Retry-After header when the limit is exceeded.

Errors

All errors follow a consistent envelope:

{
  "error": "not_found",
  "message": "Credential with public ID ARK-2026-999 not found"
}