HIP API — Developer Documentation

Overview

The HIP API provides programmatic access to the Human Integrity Protocol's proof registry. Content that has been attested through HIP can be verified by anyone — no account or API key required for read-only verification.

Privacy by design: HIP never stores file contents or file names. The API works exclusively with SHA-256 content hashes — cryptographic fingerprints computed locally on the creator's device. Your files never leave your hands.

How it works

When a creator attests content through HIPKit, the app computes a SHA-256 hash of the file locally, then registers that hash with the HIP registry along with a classification, timestamp, and cryptographic signature. The verify endpoint lets anyone check whether a given content hash has been attested.

Authentication

The POST /api/attest endpoint requires API key authentication via the X-API-Key header. API keys are bound to a HIP credential and inherit its tier-based rate limits.

Secure key management: API keys are generated through the admin API and displayed once. Store them securely — if lost, a new key must be generated. Never commit API keys to version control or include them in client-side code.

Example Header

curl -X POST https://hipprotocol.org/api/attest \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{ ... }'

Verify Attestation

Check whether a piece of content has been attested through HIP. Provide the SHA-256 hash of the file and get back a verification result with attestation details.

GET /api/verify/{content_hash} Live

Returns whether the content hash has been attested and, if so, the attestation record including classification, credential tier, timestamp, and proof link.

Parameters

Parameter	Type	Description
`content_hash`	string	64-character lowercase hexadecimal SHA-256 hash of the file content Required

Success Response — Attested Content

{
  "verified": true,
  "record": {
    "content_hash": "a7c3e19f...82b",
    "classification": "CompleteHumanOrigin",
    "credential_tier": 1,
    "attested_at": "2026-04-01T12:00:00Z",
    "registered_at": "2026-04-01T12:00:01Z",
    "short_id": "xK7mQ2pL",
    "proof_url": "https://hipprotocol.org/proof.html?hash=a7c3e19f...82b",
    "short_url": "https://hipprotocol.org/p/xK7mQ2pL",
    "sealed": false
  }
}

Response — Not Attested

{
  "verified": false,
  "content_hash": "e52d80c4...9c17"
}

Response — Sealed Record

// The content has been attested, but the creator has sealed the proof details
{
  "verified": true,
  "record": {
    "content_hash": "3f91b2...d04a",
    "sealed": true,
    "registered_at": "2026-03-15T09:30:00Z"
  },
  "message": "This content has been attested but the proof details are sealed by its creator."
}

Response Fields

Field	Type	Description
`verified`	boolean	Whether the content hash has a registered attestation
`record.content_hash`	string	The SHA-256 hash that was queried
`record.classification`	string	HIP classification: `CompleteHumanOrigin`, `HumanOriginAssisted`, or `HumanDirectedCollaborative`
`record.credential_tier`	integer	Credential tier of the attester (1, 2, or 3)
`record.attested_at`	string	ISO 8601 UTC timestamp of when the creator attested the content
`record.registered_at`	string	ISO 8601 UTC timestamp of when the proof was registered in the HIP registry
`record.short_id`	string	8-character short ID for the proof link
`record.proof_url`	string	Full URL to the proof card on hipprotocol.org
`record.short_url`	string	Short URL for sharing (hipprotocol.org/p/{short_id})
`record.sealed`	boolean	Whether the proof details have been sealed by the creator

Classifications

Value	Meaning
`CompleteHumanOrigin`	Entirely created by a human with no AI assistance
`HumanOriginAssisted`	Human-created with AI-assisted editing or enhancement
`HumanDirectedCollaborative`	Human-directed work with significant AI collaboration

Error Responses

Status	Condition	Body
400	Invalid hash format	`{ "verified": false, "error": "Invalid content hash..." }`

Note: A verified: false response uses HTTP 200, not 404. The request succeeded — the content simply has not been attested. Reserve error codes for actual errors (malformed hashes, server issues).

Submit Attestation

Register a new attestation through the API. Requires API key authentication. The content hash is computed locally — your files never leave your hands.

POST /api/attest Live

Submit a content hash with classification and cryptographic signature to register an attestation. Returns the registered proof record with permalink.

Headers

Header	Required	Description
`X-API-Key`	Required	Your API key
`Content-Type`	Required	application/json

Request Body

Field	Type	Description
`content_hash`	string	64-character lowercase hex SHA-256 hash. Required
`classification`	string	HIP classification value. Required
`signature`	string	Ed25519 signature from your credential. Required
`attested_at`	string	ISO 8601 UTC timestamp. Optional, defaults to current time
`sealed`	boolean	Seal proof details from public view. Optional, defaults to false
`public_key`	string	64-char hex Ed25519 public key. Optional

Success Response

{
  "success": true,
  "content_hash": "a7c3e19f...82b",
  "classification": "CompleteHumanOrigin",
  "credential_tier": 1,
  "attested_at": "2026-04-13T12:00:00Z",
  "registered_at": "2026-04-13T12:00:01Z",
  "proof_url": "https://hipprotocol.org/proof.html?hash=a7c3e19f...82b",
  "short_id": "xK7mQ2pL",
  "short_url": "https://hipprotocol.org/p/xK7mQ2pL",
  "sealed": false
}

Error Responses

Status	Condition	Body (summarized)
400	Missing/invalid fields	`{ "error": "..." }`
401	Missing X-API-Key	`{ "error": "Missing X-API-Key header..." }`
403	Invalid/deactivated key	`{ "error": "Invalid API key" }`
409	Hash already attested	`{ "error": "conflict", "message": "...", "existing_record": {...} }`
429	Rate limit exceeded	`{ "error": "Rate limit exceeded...", "limit": N, "current": N }`

Code Examples

curl -X POST https://hipprotocol.org/api/attest \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "content_hash": "a7c3e19f...",
    "classification": "CompleteHumanOrigin",
    "signature": "ed25519_sig...",
    "sealed": false
  '

async function submitAttestation(hash, classification, signature) {
  const res = await fetch(
    "https://hipprotocol.org/api/attest",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-Key": process.env.HIP_API_KEY,
      },
      body: JSON.stringify({
        content_hash: hash,
        classification: classification,
        signature: signature,
        sealed: false,
      }),
    }
  );
  const data = await res.json();
  if (data.success) {
    console.log("Attestation registered:", data.short_url);
  }
}

import requests, os, hashlib

def submit_attestation(content_hash, classification, signature):
    api_key = os.getenv("HIP_API_KEY")
    payload = {
        "content_hash": content_hash,
        "classification": classification,
        "signature": signature,
        "sealed": False
    }

    resp = requests.post(
        "https://hipprotocol.org/api/attest",
        json=payload,
        headers={
            "X-API-Key": api_key,
            "Content-Type": "application/json"
        }
    )
    data = resp.json()

    if data.get("success"):
        print(f"Proof: {data['short_url']}")
    else:
        print(f"Error: {data['error']}")

Rate limits: Rate limits are shared between app and API attestations. A Tier 1 credential can submit up to 50 attestations per 24-hour window across all channels.

Integration Examples

Quick examples in common languages. All examples compute the SHA-256 hash of a local file and check it against the HIP registry.

# Compute SHA-256 hash of a file
HASH=$(shasum -a 256 photo.jpg | awk '{print $1}')

# Verify against HIP registry
curl "https://hipprotocol.org/api/verify/$HASH"

async function verifyWithHIP(file) {
  // Compute SHA-256 hash
  const buffer = await file.arrayBuffer();
  const hashBuf = await crypto.subtle.digest("SHA-256", buffer);
  const hash = Array.from(new Uint8Array(hashBuf))
    .map(b => b.toString(16).padStart(2, "0")).join("");

  // Verify against HIP registry
  const res = await fetch(
    `https://hipprotocol.org/api/verify/${hash}`
  );
  const data = await res.json();

  if (data.verified) {
    console.log("Attested:", data.record.classification);
    console.log("Proof:", data.record.proof_url);
  } else {
    console.log("Not attested through HIP");
  }
}

import hashlib, requests

def verify_with_hip(file_path):
    # Compute SHA-256 hash
    sha256 = hashlib.sha256()
    with open(file_path, "rb") as f:
        for chunk in iter(lambda: f.read(8192), b""):
            sha256.update(chunk)
    content_hash = sha256.hexdigest()

    # Verify against HIP registry
    resp = requests.get(
        f"https://hipprotocol.org/api/verify/{content_hash}"
    )
    data = resp.json()

    if data["verified"]:
        record = data["record"]
        print(f"Attested: {record['classification']}")
        print(f"Proof: {record['proof_url']}")
    else:
        print("Not attested through HIP")

verify_with_hip("photo.jpg")

Rate Limits

The verification endpoint is designed for high availability. Standard rate limits apply to prevent abuse.

Endpoint	Limit	Window
`GET /api/verify/{hash}`	1,000 requests	Per IP, per hour
`POST /api/attest`	Tier-based	Per credential, per 24h

Attestation Rate Limits by Tier

Tier	Attestations per 24h
Tier 1	50
Tier 2	25
Tier 3	10

Need higher limits? If you're building a high-volume integration, reach out and we'll work with you on appropriate rate limits for your use case.

API Roadmap

Verification and authenticated attestation endpoints are live. Portfolio query is in development.

GET /api/verify/{content_hash} Live

Public read-only verification. Check if any content hash has been attested through HIP.

POST /api/attest Live

Submit attestations programmatically via API key. Register content hashes with classification, timestamp, and cryptographic signature. Requires authenticated credential.

GET /api/portfolio/{credential_id} Coming Soon

Query all attestations for a given credential. Supports pagination and filtering by classification. Requires API key authentication.

Build on HIP

Overview

How it works

Authentication

Verify Attestation

Response Fields

Classifications

Error Responses

Submit Attestation

Integration Examples

Rate Limits

Attestation Rate Limits by Tier

API Roadmap