REST API Documentation

Authentication

Base URL: https://api.verixid.com

VerixID acts as a mathematical witness for digital assets. The API accepts only the file fingerprint (SHA-256 hash), never the source file payload (zero-custody guarantee).

🔑

All endpoints require an API key transmitted via the header X-Secure-Key: <64-character-api-key>. API keys are provisioned from the VerixID dashboard and displayed once upon generation. Keep your key secure and never publish it in code repositories or public logs.

· Key Format: 64 alphanumeric characters (A-Z, a-z, 0-9), case-sensitive.

Registering a File

POST /submit

Commits a new file fingerprint to the append-only ledger.

Headers

Content-Type: application/json X-Secure-Key: <api-key>

Body

{ "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" }

Field	Required	Description
`hash`	Yes	64-character SHA-256 hex string calculated client-side. Raw file payload is never transmitted.

Limits: Maximum payload size 10 KB · Rate limit 20 requests/minute. Submissions are metered against your plan quota.

Successful Response — 201 Created

{ "record_id":"vx202607026731ce", "server_timestamp":"2026-07-21T12:54:59.469Z", "receipt_signature":"...", "ownership_key":"..." }

Store the record_id — this is the public identifier used for verification. Safeguard the ownership_key (if returned in response); it acts as private cryptographic proof of entitlement and cannot be recovered if misplaced.

Hash Previously Registered

409 Conflict

Verifying a Record

GET /verify

Validates record existence — accessible by anyone possessing a valid record_id.

GET /verify?id=vx202607a1b2c3d4 GET /verify?id=vx202607a1b2c3d4&ownership_key=<64-hex>

Parameter	Required	Description
`id`	Yes	Format: `vx` + `YYYYMM` + 8 hex characters. Example: `vx202607a1b2c3d4`.
`ownership_key`	No	64-character hex key. Returns entitlement proof if valid.

This endpoint is governed by Fair Usage Policy (rate limiting and anti-abuse protection).

Mode 1 — Without ownership_key (Public Audit Check)

{ "record_id": "vx202607a1b2c3d4", "registered_at": 1784375908188, "hash_preview": "f8bd8b98730d5c19...", "ownership_verified": false }

hash_preview returns only the first 16 characters to prevent public identity brute-forcing.

Mode 2 — With Valid ownership_key (Ownership Entitlement Proof)

{ "record_id": "vx202607a1b2c3d4", "registered_at": 1784375908188, "hash_preview": "d5fc7d44cb58413b2c9d9c4e66722a031080279d9c25c9bb88f6c2e0d17439fb", "ed25519_signature": "4b6bd41e1dc082fa02f4081374...", "ownership_verified": true }

hash_preview exposes the full 64-character hash alongside an ed25519_signature (128-character hex string / 64 bytes), which can be independently authenticated using the VerixID public key at /.well-known/verixid-public-key.pem.

Record Not Found

404 Not Found

Error Format

All API errors return a standardized JSON structure:

{ "code": "invalid_hash", "title": "Invalid Hash", "status": 400, "detail": "Hash must be a SHA-256 hex string (64 characters)." }

code	Status	Condition
`unauthorized`	401	Missing, malformed, or unassigned API key
`billing_expired`	402	Account suspended or billing cycle ended
`invalid_json`	400	Malformed Request JSON body
`invalid_hash`	400	`hash` parameter is not a 64-character SHA-256 hex string
`invalid_id`	400	`id` parameter fails format specifications
`invalid_key` / `invalid_ownership_key`	400	`ownership_key` is not a valid 64-character hex string
`payload_too_large`	400	Request payload exceeds 10 KB limit
`quota_exceeded`	429	Monthly plan submission limit reached
`rate_limit_exceeded`	429	Requests exceeded 20 calls/minute ceiling
`method_not_allowed`	405	HTTP method not permitted on endpoint
`not_found`	404	Endpoint path unresolved
`upstream_error`	502	Internal processing fault; retry request
`internal_error`	500	Uncaught system exception

cURL Examples

Submit File Hash

curl -X POST https://api.verixid.com/submit \ -H "X-Secure-Key: <api-key>" \ -H "Content-Type: application/json" \ -d '{ "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" }'

Verify Record (Public Mode)

curl "https://api.verixid.com/verify?id=vx202607a1b2c3d4" \ -H "X-Secure-Key: <api-key>"

Verify Record (With Ownership Proof)

curl "https://api.verixid.com/verify?id=vx202607a1b2c3d4&ownership_key=<64-hex-key>" \ -H "X-Secure-Key: <api-key>"

💡

Never commit production API keys to source control, shell histories, or client-side web bundles. If a key is compromised, rotate it immediately via the dashboard.

Core Principles

Zero-Custody: Source files are never transmitted or stored — only SHA-256 digests are processed.
Verify, Don't Trust: Verification is entirely deterministic and mathematically verifiable (SHA-256 + Ed25519) without relying on blind trust in VerixID.
Append-Only Architecture: Committed records are immutable. Test submissions using dummy hashes persist permanently on the ledger.
Explicit Scope: VerixID is not an e-signature suite, blockchain layer, or identity provider — it is pure mathematical proof of file existence and integrity.