Skip to content

Developers

API changelog

Every change to the Partner API lands here, dated. Email is reserved for what needs your attention — breaking changes, security issues, and terms updates. API reference · Integration guide

Change policy

  • Additive changes— new endpoints, new optional parameters, new response fields — ship anytime, changelog-only. Don't rely on field order or on unknown fields being absent.
  • Breaking changes are announced by email and here at least 6 monthsbefore they take effect (12 if you're in production on the old behavior), with a migration guide and Sunset headers on affected responses.
  • Terms changes are emailed at least 30 days before the effective date.
  • Security issues — immediate email, no waiting.
  1. Added

    TypeScript SDK 2.7.0 — decision envelope, partner reviews, canonical session evidence

    • Every POST /verify response — success and failure alike — now carries an additive decision envelope for automation: status (verified_binding, needs_review, invalid_proof), stable reason slugs, a recommendedAction, the credential carrier, source-detail coverage, and counts of declarations, conflicts, and unverifiable facts. It is policy-neutral and never labels a track human or AI; needs_review means the evidence report asks for a human decision, not that the credential failed.
    • A metadata-only review workflow under /partner/reviews binds a registered proof to your own opaque catalog identifiers (creator, account, submission, track) and tracks evidence requests through to your Accept / Hold / Reject outcome. PoH stores workflow state and bounded opaque references only — never source files, licences, creator names, or free-form notes — and review metadata expires after 180 days. Wrapped as partner.createReview, getReview, requestEvidence, updateEvidence, and resolveReview.
    • Proofs issued from this release carry session.evidence: activity counters replayed server-side from the signed capture trace, with a per-metric status (observed, not_observed, unsupported, unknown), coverage, and the trace's SHA-256. Client-supplied summaries are compatibility input, never evidence; if one disagrees with the replay, the trace wins and the report records a session_summary_reconciled fact with needs_review status. Render the status instead of a bare zero: an Ableton save channel is unsupported, not silent.
    • Evidence reports can include declarations — the creator's raw survey answers as authenticated envelopes with survey version, submission time and id, subject, and an honest authenticated_post_issuance_record binding status (a declaration is recorded after issuance; it is not part of the original proof signature).
    • Versions 2.6.1 and 2.6.2 published no spec change (documentation and server-side hardening only); 2.7.0 is the first contract change after 2.6.0.
  2. Added

    TypeScript SDK 2.6.0 — proof records, source-level evidence v2, complete creator declarations

    • GET /records/{proofId} returns the registered record for a proof id: song, issue time, bound-audio SHA-256, the structured evidence report, the process note, and credential delivery — without presenting the audio. It is not a verification result and never claims any file matches; confirming a candidate file still requires POST /verify with the file itself. Legacy grade and classification are not on this surface, and erased, never-issued, and still-pending ids return one uniform 404. Wrapped as getProofRecord(proofId).
    • Approved commercial integrations can request poh-source-detail-2 for supported Ableton proofs: report-local track and placement identifiers, exact DAW beat ranges with tempo-snapshot second estimates, last-observed clip and track state, bounded source-linked edit counts, and the signed-session time of the latest completed source-map observation. Reading v2 requires the exact pinned v6 creator consent; ordinary and public verification are unchanged, and reports never claim final-mix contribution.
    • Evidence reports now publish every answered creator-survey dimension as a creator_declaration fact — favorable and adverse alike: declared origin, AI share band, manual work, contribution band, and a disputed assessment. Previously only six adverse answers surfaced, so an honest declaration could leave no public trace. New conflict code observed_import_vs_creator_origin_declaration marks a directly witnessed import that contradicts a made-from-scratch or majority-self-made declaration; unrecognized fact codes render as raw codes in older readers and no request shape changed.
    • Report surfaces now show an explicit “none recorded” state for creator declarations, so a missing survey is distinguishable from hidden declarations.
  3. Added

    TypeScript SDK 2.5.0 — source-aware evidence reports

    • GET /proofs, GET /proofs/{proofId}, and POST /verify can now include an optional evidenceReport with direct system observations, rule inferences, creator declarations, explicit conflicts, and unverifiable coverage gaps.
    • The new field is additive and backward-compatible. Older proofs can omit it, and clients must handle that state as unavailable source evidence rather than reconstructing facts from a score.
    • The legacy grade field remains on the wire for compatibility and internal calibration only. Its values do not have a validated final-audio denominator and must not be presented as human or AI authorship percentages.
  4. Added

    Beta integration environment

    • https://beta.api.proofofhuman.fm/v1 is the pre-production endpoint for integration testing: the same contract and authentication as production on isolated infrastructure with separate API keys, a separate registry, and disposable test proofs.
    • Beta and production keys are different secrets and never interchangeable. Ask for a beta key alongside your production key, point staging at the beta base URL, and switch to production at go-live.
    • No production request or response behavior changed.
  5. Changed

    TypeScript SDK 2.4.1 — quickstart and partner monitoring

    • The generated reference, SDK README, curl samples, and AI-agent context now lead with one-file credentialed WAV verification and retain the legacy audio + .poh fallback.
    • The integration guide now covers request IDs, safe client telemetry, health/quota checks, retries, and recommended alerts. PoH operations now tracks one-file versus legacy verification verdicts per opaque client ID.
    • No request or response field changed; existing integrations are unaffected. This ships as an SDK documentation patch.
  6. Added

    TypeScript SDK 2.4.0 — interpretation policy provenance

    • Ready process notes can include policyVersion so integrations can identify the fixed presentation policy that produced the report-only summary.
    • The field is optional and backward-compatible; credential validity and grade calculations are unchanged.
  7. Added

    TypeScript SDK 2.3.0 — one-file credentialed audio

    • POST /verify now accepts uploadId without poh for a PoH credentialed WAV; the legacy audio + .poh body remains supported.
    • POST /uploads accepts purpose=verify for a 65 MiB slot, GET /proofs/{proofId}/asset retrieves an owned credentialed deliverable, and responses can include embeddedCredential.
  8. Added

    TypeScript SDK 2.2.0 — local device seals

    • Verification can return local_seal when an intact artist-device seal was never registered with PoH. Treat unknown future verdict values as failed verification.
    • This distinguishes an opt-out/local proof from tampering without accepting it as PoH-issued.
  9. Added

    TypeScript SDK 2.0.1

    • client.health() liveness check; PoHError.requestId on failures; require()/CommonJS support fixed (the SDK now bundles its one dependency — zero runtime deps).
    • 2.0.0 carries the deployedAt unix-seconds change below — no other API surface change. npm install @proof-of-human/ts-sdk@^2.
  10. Added

    Durable audit trail for key lifecycle events

    • Every key rotation and expiry now leaves a durable, append-only audit record on your account.
    • No API surface change — your integration is unaffected.
  11. Changed

    Request IDs on every response · unix timestamps

    • Every API response now carries an X-Request-Id header — quote it when reporting an issue.
    • GET /health deployedAt is now unix epoch seconds (was an ISO string). SDK 2.0.0 surfaces requestId on errors.
  12. Added

    Partner key self-service + TypeScript SDK

    • GET /partner/keys, POST /partner/keys/rotate (72h grace, Idempotency-Key), GET /partner/usage.
    • @proof-of-human/ts-sdk on npm, generated from the same model as the API.