Proofs
Create permanent proof from a local file fingerprint
POST
https://backend.immut.io/api/v1/proofsRequired scope: documents:write
The file never leaves the caller's environment. Send field hash (64-char hex fingerprint of file bytes). Idempotent per hash and workspace: re-posting returns 200 with alreadyProven true. Paid organisations get permanent proofs. Default salted scheme returns proofNonce once: store it for verification. Scope documents:write.
Request body
Content type: application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
hash | string | yes | 64-char hex fingerprint of the file (SHA-256 of file bytes) |
workspace | string | yes | Workspace id (GET /workspaces) |
fileName | string | no | |
fileSize | number | no | Bytes |
mimeType | string | no | |
metadata | object | no |
Responses
| Status | Meaning |
|---|---|
200 | Already proven. These exact bytes were proven before, so the original proof is returned unchanged. |
201 | Created. Keep proofId, txHash and proofNonce: without the nonce a salted proof cannot be verified later. |
400 | BadRequest |
401 | Unauthorized |
403 | Forbidden |
429 | RateLimited |
502 | Proof network error (code XRPL_ERROR). Safe to retry: the attempt is rolled back. |
Response fields (200)
Returned inside data.
| Field | Description |
|---|---|
proofId | id for status polling and certificates |
txHash | permanent transaction reference used for public verification |
verifyUrl | public explorer link for the transaction (returned by API) |
certPath | /api/v1/certificates/{proofId} |
ledger | opaque network label (mainnet | testnet) |
ledgerIndex | opaque index when available |
timestamp | ISO 8601 |
hashScheme | sha256-plain-v1 | hmac-sha256-nonce-v3 |
proofCommitment | commitment value in the public proof when the scheme is salted |
proofNonce | KEEP THIS for hash-only salted proofs: required to verify later. Also embedded in the certificate PDF. |
Example
curl -X POST "https://backend.immut.io/api/v1/proofs" \
-H "Authorization: Bearer $IMMUT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"hash":"<hash>","workspace":"<workspace>","fileName":"<fileName>","fileSize":"<fileSize>","mimeType":"<mimeType>","metadata":"<metadata>"}'
Generated from the immut API contract, version 1.9.0. Machine-readable: this page as markdown · everything in one file · OpenAPI