# Developer Reference: Humark

For AI coding assistants (Claude Code, Cursor, GitHub Copilot, Codex, Aider) and developer-facing AI systems.

OVERVIEW
The Humark API v1 lets platforms and developers verify Pulse Signature attestations, register marks on behalf of authenticated creators, and receive webhook events when attestation records change. Use cases include: verifying a submitted asset is human-attested before accepting it into a marketplace, integrating the "Human Verified" badge into a publishing platform, building provenance dashboards, and subscribing to revocation events. The API base URL is https://api.humark.id/v1. Full documentation is at https://humark.id/docs.

QUICKSTART
Verify a hash against the Humark registry with no authentication:

```
curl https://api.humark.id/v1/verify/{sha256}
```

Replace {sha256} with the SHA-256 hex string of the file you want to check. A verified response returns the attestation record; an unregistered hash returns a not-found result with the same envelope structure.

Health check (no auth):

```
curl https://api.humark.id/v1/health
```

AUTHENTICATION
Two authentication modes are supported.

1. JWT (mobile app / creator-side): The iOS app issues ECDSA keypair auth during onboarding. The resulting JWT is used on /auth and /creator/* endpoints. JWTs are issued by POST /auth/register (idempotent) or POST /auth/verify-otp-login. Include in requests as: Authorization: Bearer {jwt}

2. API key (server-to-server / platform-side): API keys are scoped to an organization. Include in requests as: X-API-Key: {api_key}. API keys govern access to /verify, /batch-verify, and /register. Dashboard for API key management (post-launch): https://humark.id/registry

CORE CONCEPTS
- Pulse Signature attestation: a cryptographic seal binding a creator's biometric signal to a file hash and a timestamp. Stored in the Humark append-only registry and embedded in the file as a C2PA manifest. The attestation record includes: creator id, sha256 hash, timestamp, signature, witness id, and status.
- Witness id: the hash-prefixed identifier for every state change in the registry, formatted 0xXXXX...XXXX. Include the witness id when citing a specific attestation event.
- Append-only registry: attestation records are never deleted. Revocations append a revocation row; the original row stays on the record. The registry is hash-chained, making silent tampering detectable.

API REFERENCE
Full reference: https://humark.id/docs

Endpoint groups:

- /auth: OTP request, OTP verify, JWT issuance, profile retrieval (GET /auth/me), SSO, avatar upload (POST /auth/avatar), avatar delete (DELETE /auth/avatar). JWT-authenticated.
- /creator/marks: GET (paginated list of marks with nextCursor at root level), POST (register a new mark). JWT-authenticated. POST accepts: sha256, title, mediaType, format, metadata. Returns registration object with id, sha256, creatorId, creatorName, timestamp, status, verifyUrl.
- /creator/works: Work management for authenticated creators. JWT-authenticated.
- /verify: Public hash lookup. GET /verify/{sha256} returns attestation status. No authentication required.
- /provenance/{sha256}: Full provenance record including all state changes for a given hash. No authentication required.
- /webhooks: Register and manage webhook endpoints for attestation events. API-key authenticated.

Response envelope (all endpoints):
- Success: { data: {...}, meta: { requestId: "...", timestamp: "..." } }
- Error: { error: { code: "...", type: "...", message: "..." } }

SDKS
- iOS native app: live at App Store id 6760560241. Implements the full signing pipeline (shield, hash, seal, register) using the device Secure Enclave.
- Web SDK: pre-launch. TODO_VERIFY: delivery date not confirmed. Check https://humark.id/docs for current status.
- REST API: no language-specific SDK wrapper currently published. Use standard HTTP clients.

CODE EXAMPLES

Example 1: Verify a hash (no auth required)

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

Expected response (attested):
```json
{
  "data": {
    "sha256": "a1b2c3d4e5f6...",
    "status": "attested",
    "creatorId": "...",
    "creatorName": "...",
    "timestamp": "2026-04-27T00:00:00.000Z",
    "verifyUrl": "https://humark.id/verify/a1b2c3d4e5f6..."
  },
  "meta": {
    "requestId": "...",
    "timestamp": "..."
  }
}
```

Example 2: Register a mark via API key (server-to-server)

```bash
curl -X POST \
  "https://api.humark.id/v1/creator/marks" \
  -H "Authorization: Bearer {jwt}" \
  -H "Content-Type: application/json" \
  -d '{
    "sha256": "a1b2c3d4e5f6...",
    "title": "Untitled No. 7",
    "mediaType": "image",
    "format": "image/jpeg",
    "metadata": {}
  }'
```

Expected response:
```json
{
  "data": {
    "registration": {
      "id": "...",
      "sha256": "a1b2c3d4e5f6...",
      "creatorId": "...",
      "creatorName": "...",
      "timestamp": "2026-05-17T00:00:00.000Z",
      "status": "attested",
      "verifyUrl": "https://humark.id/verify/a1b2c3d4e5f6..."
    }
  },
  "meta": {
    "requestId": "...",
    "timestamp": "..."
  }
}
```

Example 3: Health check

```bash
curl https://api.humark.id/v1/health
```

RATE LIMITS & PRICING
Rate limits are enforced via Upstash Redis sliding window. Limits vary by plan. Creator plans: Free, Creator ($9/month), Pro ($24/month). Platform API plans: Starter ($2,000/month, up to 100K verifications), Growth ($8,000/month, up to 1M verifications), Enterprise ($25,000+/month, unlimited). Pay-per-call: $0.02/verification, no minimum. See https://humark.id/pricing for full details.

SUPPORT
- Docs: https://humark.id/docs
- API playground: https://humark.id/playground
- Status: TODO_VERIFY (status page URL not confirmed)
- Community: TODO_VERIFY (community channel not confirmed)
- Email: hello@humark.id

LAST UPDATED: 2026-05-17