hipkit-docs

Public HTTP API documentation for HIPKit — a commercial product built on the Human Integrity Protocol (HIP).

These docs cover the endpoints HIPKit exposes for programmatic use. They are intentionally separate from the HIPKit application source code so that anyone — SDK authors, third-party tool builders, alternative client implementations — can integrate with HIPKit without depending on (or needing access to) the application repo. This separation is deliberate: it satisfies the protocol's DP-5 (Permissionless Proliferation) principle, which guarantees that anyone may build on top of HIP without permission.

If you want to build a tool, integration, or alternative client that talks to HIPKit's API, this is the source of truth.

Base URL

https://hipprotocol.org

All endpoints documented here are reachable on this canonical domain. The underlying Cloudflare Worker that serves the API is also reachable at https://hip-tier1-worker.hipprotocol.workers.dev, but the canonical domain is the recommended URL for production integrations — it's stable across worker deployments.

What's covered

Doc	Topic
authentication.md	The two auth models — public reads, X-API-Key for programmatic attestations, and AppAuth (Ed25519 signature over a fixed canonical) for credential-holder operations.
endpoints.md	Full endpoint reference — single attestation, verify, dispute, series, collections, key management, portfolio, attestation history.
errors.md	Error codes, HTTP status mapping, and what each one means.
rate-limits-and-credits.md	Per-credential, per-IP, and per-key rate limits, plus the HIPKit credit model (when calls debit a credit and when they don't).
CHANGELOG.md	Versioned history of breaking and notable changes to this docs repo.

What's NOT covered

• Credential issuance — bootstrapping a HIP credential (Tier 1 via Didit identity verification, Tier 2 via peer vouch, Tier 3 via WebAuthn) is owned by HIPVerify and the protocol's permissionless issuance surfaces, not by HIPKit. The endpoints /trust/initialize and /upgrade-credential exist on the same worker but are out of scope for HIPKit integrations and are not documented here.
• Stripe integration internals — POST /api/stripe/checkout and POST /api/stripe/portal exist for the HIPKit application's own billing flow and are not intended for external integrations.
• The HIPKit web app itself — front-end code, UI flows, and product-specific features live in the application repo. This docs repo is API-only.

Quickstart — verify a content hash (no auth)

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

# 2. Ask the registry whether it's been attested
curl "https://hipprotocol.org/api/verify/$HASH"

Response is { "verified": true, "record": {...}, "signature_verified": true } for an attested record, or { "verified": false, "content_hash": "..." } for an unknown hash. See endpoints.md → Verify attestation for full response shape.

Quickstart — create an API key (one-time)

You need a HIP credential to create an API key. The simplest path is to install HIPKit, complete Tier 1 issuance via HIPVerify, and use the Keys tab in the app to create a key. The key is shown once at creation — copy it into a secret manager.

For SDK authors who need to create or manage keys programmatically, see authentication.md → AppAuth and endpoints.md → Key management.

Quickstart — programmatic attestation

curl -X POST https://hipprotocol.org/api/attest \
  -H "Content-Type: application/json" \
  -H "X-API-Key: hipk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "content_hash": "<64-char-lowercase-hex-sha256>",
    "classification": "CompleteHumanOrigin",
    "attested_at": "2026-04-23T12:00:00Z",
    "public_key": "<64-char-hex-ed25519-pubkey>",
    "signature": "<base64-ed25519-signature>"
  }'

signature is an Ed25519 signature by the credential's private key over the HIPKit canonical: content_hash | credential_id | classification | attested_at | protocol_version. Full canonical and worked example in authentication.md.

Charter foundations

The endpoints here implement the protocol primitives defined in:

• HP-SPEC-v1.2 — Credential model, Trust Index formula, lifecycle states, rate limits, liveness.
• WF-SPEC-v1 — Proof Bundle wire format (locked).
• CRYPTO-SPEC-v1.1 — Ed25519 + SHA-256 + RFC 8785 (JCS).
• SERIES-SPEC-v1 — Open, append-only, creator-bound stream construct.

Specs live in the hip-protocol repository (read-only reference; you do not need to read them to use the API).

License

These docs are published under [TBD — see LICENSE]. Code samples in this repo are provided under the same license unless otherwise noted.

Contributing

Issues and pull requests welcome. For protocol-level questions (e.g., proposed changes to the canonical message format, new tier semantics), open an issue on hip-protocol instead.

---

HIPKit™ is a trademark of Peter Rieveschl. The Human Integrity Protocol is an open, permissionless protocol; HIPKit is one commercial implementation among many possible.