API Reference

Humark API

Verify human origin, register assets, and query provenance records. Everything you need to integrate Humark into your platform.

Base URL

https://api.humark.id/v1

Try it in the Playground

Quick Start

Get up and running in under five minutes. Grab a demo API key, then make your first verification call.

1. Get an API Key

For testing, use the demo key below. For production access, request a pilot account.

Demo Key

hmk_demo_pk_test_51x8kQ2e

2. Make Your First Call

Verify whether an asset with a given SHA-256 hash has been registered and verified by Humark.

verify.sh

curl -X GET \
  https://api.humark.id/v1/verify/e3b0c44298fc1c149afbf4c8996fb924 \
  -H "Accept: application/json"

Authentication

Public endpoints (verify, provenance, health, stats) require no authentication. Authenticated endpoints (register, batch verify) require an API key passed via the Authorization header.

auth-header.txt

Authorization: Bearer hmk_live_pk_your_key_here

Demo key: Use hmk_demo_pk_test_51x8kQ2e for sandbox testing. Demo keys are rate-limited to 100 requests/day and cannot access write endpoints.

GET

/api/v1/verify/:sha256

public

Check whether an asset identified by its SHA-256 hash has been registered and verified in the Humark registry. Returns verification status, creator info, and provenance metadata.

Parameters

Parameter	Type	Required	Description
sha256	string	required	SHA-256 hash of the asset file (hex-encoded, 64 characters).

Example Request

curl

curl -X GET \
  https://api.humark.id/v1/verify/e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Example Response

response.json

{
  "status": "verified",
  "sha256": "e3b0c44298fc1c14...7852b855",
  "creator": {
    "displayName": "Yuki Tanaka",
    "publicKey": "did:key:z6MkhaX..."
  },
  "timestamp": "2026-03-07T12:00:00Z",
  "shieldVersion": "1.0",
  "manifestUrl": "https://registry.humark.id/manifests/e3b0c4..."
}

POST

/api/v1/register

authenticated

Register a new asset in the Humark registry. Requires a signed C2PA manifest and the asset's SHA-256 hash. The creator's identity is bound via biometric signature.

Parameters

Parameter	Type	Required	Description
sha256	string	required	SHA-256 hash of the asset file.
manifest	object	required	Signed C2PA manifest object.
creatorDid	string	required	DID (Decentralized Identifier) of the creator.
shieldVersion	string	optional	Version of the Shield adversarial layer applied. Defaults to "1.0".
metadata	object	optional	Optional metadata (title, description, tags).

Example Request

curl

curl -X POST https://api.humark.id/v1/register \
  -H "Authorization: Bearer hmk_live_pk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "sha256": "a1b2c3d4e5f6...",
    "manifest": { "...signed C2PA manifest..." },
    "creatorDid": "did:key:z6MkhaXgBZD...",
    "shieldVersion": "1.0",
    "metadata": {
      "title": "Sunset over Kyoto",
      "tags": ["photography", "landscape"]
    }
  }'

Example Response

response.json

{
  "status": "registered",
  "sha256": "a1b2c3d4e5f6...",
  "registryId": "hmk_asset_9f8e7d6c5b4a",
  "manifestUrl": "https://registry.humark.id/manifests/a1b2c3...",
  "createdAt": "2026-03-08T09:15:22Z"
}

GET

/api/v1/assets/:sha256/provenance

public

Retrieve the full provenance chain for a registered asset, including all C2PA manifests, creator history, and verification events.

Parameters

Parameter	Type	Required	Description
sha256	string	required	SHA-256 hash of the asset file.
include	string	optional	Comma-separated list of optional fields: "manifests", "events", "related". Defaults to all.

Example Request

curl

curl -X GET \
  "https://api.humark.id/v1/assets/e3b0c44298fc1c14.../provenance?include=manifests,events"

Example Response

response.json

{
  "sha256": "e3b0c44298fc1c14...7852b855",
  "creator": {
    "displayName": "Yuki Tanaka",
    "did": "did:key:z6MkhaX..."
  },
  "provenance": [
    {
      "action": "registered",
      "timestamp": "2026-03-07T12:00:00Z",
      "actor": "did:key:z6MkhaX...",
      "manifestUrl": "https://registry.humark.id/manifests/e3b0c4..."
    },
    {
      "action": "verified",
      "timestamp": "2026-03-07T12:01:15Z",
      "verifier": "platform:stock-example"
    }
  ],
  "shieldVersion": "1.0",
  "relatedAssets": []
}

POST

/api/v1/verify/batch

authenticated

Verify multiple assets in a single request. Accepts up to 100 SHA-256 hashes and returns verification status for each.

Parameters

Parameter	Type	Required	Description
hashes	string[]	required	Array of SHA-256 hashes to verify. Maximum 100 per request.

Example Request

curl

curl -X POST https://api.humark.id/v1/verify/batch \
  -H "Authorization: Bearer hmk_live_pk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "hashes": [
      "e3b0c44298fc1c14...7852b855",
      "a1b2c3d4e5f67890...abcdef01",
      "9f8e7d6c5b4a3210...12345678"
    ]
  }'

Example Response

response.json

{
  "results": [
    {
      "sha256": "e3b0c44298fc1c14...7852b855",
      "status": "verified",
      "creator": "Yuki Tanaka"
    },
    {
      "sha256": "a1b2c3d4e5f67890...abcdef01",
      "status": "unverified"
    },
    {
      "sha256": "9f8e7d6c5b4a3210...12345678",
      "status": "verified",
      "creator": "Marcus Rivera"
    }
  ],
  "verified": 2,
  "unverified": 1,
  "total": 3
}

GET

/api/v1/health

public

Check the health and availability of the Humark API. Use this for uptime monitoring and integration health checks.

Example Request

curl

curl -X GET https://api.humark.id/v1/health

Example Response

response.json

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime": "99.98%",
  "timestamp": "2026-03-08T10:30:00Z"
}

GET

/api/v1/stats

public

Get aggregate statistics from the Humark registry, including total registered assets, verification counts, and active creators.

Example Request

curl

curl -X GET https://api.humark.id/v1/stats

Example Response

response.json

{
  "totalAssets": 142857,
  "totalVerifications": 1283946,
  "activeCreators": 8421,
  "platformPartners": 23,
  "lastUpdated": "2026-03-08T10:00:00Z"
}

Rate Limits

Rate limits are applied per API key. Exceeding limits returns a 429 status with a Retry-After header.

Tier	Requests	Burst	Notes
Demo	100 / day	10 / min	Demo API key, public endpoints only
Starter	100K / month	100 / min	Authenticated, all endpoints
Growth	1M / month	500 / min	Authenticated, priority routing
Enterprise	Unlimited	Custom	Dedicated infra, SLA

Error Codes

All errors return a JSON body with error and message fields.

error-response.json

{
  "error": "UNAUTHORIZED",
  "message": "Missing or invalid API key.",
  "statusCode": 401
}

Code	Meaning	Description
200	OK	Request succeeded.
201	Created	Asset successfully registered.
400	Bad Request	Invalid parameters or malformed request body.
401	Unauthorized	Missing or invalid API key.
403	Forbidden	API key lacks permission for this endpoint.
404	Not Found	Asset or resource not found in registry.
409	Conflict	Asset with this hash is already registered.
429	Too Many Requests	Rate limit exceeded. Retry after the time in Retry-After header.
500	Internal Server Error	Something went wrong on our end. Contact support.

SDKs & Integration

Official client libraries are coming soon. In the meantime, the REST API works with any HTTP client in any language.

JavaScript / TypeScript

@humark/sdk

Coming Soon

Python

humark-python

Coming Soon

Ruby

humark-ruby

Coming Soon

Need help integrating? Our team provides hands-on integration support for pilot partners. Visit the Platforms page to request pilot access and get dedicated engineering support.

Ready to integrate?

Start with a free 10-day pilot. We'll help you integrate the Verification API, and you get full access to all endpoints with dedicated support.

Request Pilot Access View Pricing