Ask whether Permafrost holds provenance for a hash.

GET

/v1/api/verify

const url = 'https://testnet.permafrost.live/v1/api/verify?hash=3b8c1f0d5e4a29671c8b0d3f2a5e6c7b9d0a1f2e3c4b5a69788796a5b4c3d2e1';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://testnet.permafrost.live/v1/api/verify?hash=3b8c1f0d5e4a29671c8b0d3f2a5e6c7b9d0a1f2e3c4b5a69788796a5b4c3d2e1'

The one route on this instance that takes no credential. It answers a single question — does Permafrost hold provenance for these bytes — and nothing else. No owner, no tenant, no bucket, no key, no size, no count. When several stored objects carry the same hash, the answer names one canonical on-chain record and does not reveal that there are others.

It indexes the hash of what was STORED. For an object stored encrypted, the stored bytes are the ciphertext, so the hash to present here is the stored hash — not the hash of the plaintext you hold. On the custody surface those two are returned side by side as stored_hash and content_hash; presenting content_hash here answers provenance: false, which is the wrong hash rather than a missing record.

certified: true means the object has cleared certification on Walrus. nft_id and explorer_url are empty strings when nothing has been minted for that record yet.

The overall edge limit applies here as it does everywhere, so this route can answer 429 even though it needs no credential.

Parameters

Query Parameters

hash

required

string

/^(0[xX])?[0-9a-fA-F]{64}$/

Example

3b8c1f0d5e4a29671c8b0d3f2a5e6c7b9d0a1f2e3c4b5a69788796a5b4c3d2e1

A sha256 as 64 hex characters. A leading 0x is stripped and upper-case is folded before the lookup, so 0xAB… and ab… are the same query.

Responses

200

The verdict. A hash Permafrost does not hold is a normal 200, not a 404.

application/json

The whole public verdict. The four fields below provenance are present only when it is true; when it is false the body carries the echoed hash and nothing else.

object

hash

required

The queried hash, as it was normalised for the lookup.

string

provenance

required

Whether Permafrost holds provenance for these bytes.

boolean

nft_id

The on-chain provenance record for this hash. An empty string when nothing has been minted for it yet.

string

content_hash

The content fingerprint anchored on chain.

string

certified

True once the object has cleared certification on Walrus.

boolean

explorer_url

A Sui explorer address for nft_id. Empty when nft_id is.

string

Examples

Provenance held, object certified.

{
  "hash": "3b8c1f0d5e4a29671c8b0d3f2a5e6c7b9d0a1f2e3c4b5a69788796a5b4c3d2e1",
  "provenance": true,
  "nft_id": "0x5c1f0e2d3a4b5968778695a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4",
  "content_hash": "3b8c1f0d5e4a29671c8b0d3f2a5e6c7b9d0a1f2e3c4b5a69788796a5b4c3d2e1",
  "certified": true,
  "explorer_url": "https://suiscan.xyz/testnet/object/0x5c1f0e2d3a4b5968778695a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4"
}

Not held. The body carries nothing else.

{
  "hash": 1.1111111111111112e+63,
  "provenance": false
}

400

The hash parameter is absent or is not 64 hex characters. The input is not echoed back.

application/json

The refusal shape. detail is present on a few routes and deliberately absent from the custody surface, where a detail string could carry an internal path.

object

error

required

The code, or a short fixed sentence.

string

detail

A human-readable note, where a route carries one.

string

Example

{
  "error": "invalid_hash"
}

500

Something failed on the instance. The reason is logged there, not returned.

application/json

The refusal shape. detail is present on a few routes and deliberately absent from the custody surface, where a detail string could carry an internal path.

object

error

required

The code, or a short fixed sentence.

string

detail

A human-readable note, where a route carries one.

string

Example

{
  "error": "internal_error"
}

Permafrost runs on Sui testnet and Walrus testnet. Everything here describes a shipped testnet instance, not a production service.