Certification, programmatically.

Bearer API keys

Generate keys from Settings → API keys in your dashboard (Publisher plan). Pass the key in the Authorization header. Keys are prefixed hm_ and every use updates a last-used timestamp you can audit.

Authorization: Bearer hm_your_api_key

Certify up to 10 documents in one call. Documents must belong to the API key's account, be in DRAFT or REJECTED status, and have recorded writing sessions — the analysis runs on captured behavioral telemetry, exactly as it does in the editor.

curl -X POST https://humanums.com/api/v1/certify \
  -H "Authorization: Bearer hm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"documentIds": ["doc_abc123", "doc_def456"]}'

{
  "results": [
    {
      "documentId": "doc_abc123",
      "success": true,
      "certified": true,
      "shortCode": "HM-7K2X-9M4N",
      "badgeLevel": "VERIFIED_HUMAN",
      "confidenceScore": 87
    },
    {
      "documentId": "doc_def456",
      "success": true,
      "certified": false,
      "error": "Composite score below certification threshold."
    }
  ]
}

Look up any certificate by its short code. Returns the confidence score, badge level, the six behavioral signal scores, writing statistics, and the content hash — everything the public verification page shows, as JSON.

curl https://humanums.com/api/certificates/HM-7K2X-9M4N

{
  "shortCode": "HM-7K2X-9M4N",
  "confidenceScore": 87,
  "badgeLevel": "VERIFIED_HUMAN",
  "signals": {
    "keystrokeCadence": 89.4,
    "pauseFrequency": 81.2,
    "revisionRatio": 86.7,
    "pasteRatio": 93.9,
    "sessionDist": 70.0,
    "contentTime": 89.5
  },
  "stats": { "...": "writing duration, sessions, revisions, WPM" },
  "contentHash": "sha256...",
  "issuedAt": "2026-06-11T12:00:00.000Z"
}

The badge is a cacheable SVG. Render it anywhere and link it to the verification page. Options: size (compact | full) and theme (light | dark).

<a href="https://humanums.com/verify/HM-7K2X-9M4N">
  <img src="https://humanums.com/api/badge/HM-7K2X-9M4N?size=full&theme=dark"
       alt="Verified Human Content" />
</a>

Error format

Every error is JSON with a machine-readable error code and a human-readable message. Bulk certification reports per-document failures inside results instead of failing the whole batch.

{ "error": "unauthorized", "message": "Valid Publisher API key required." }  // 401
{ "error": "bad_request", "message": "Maximum 10 documents per request." }    // 400
{ "error": "not_found", "message": "Certificate not found." }                 // 404