{"openapi":"3.1.0","info":{"title":"HumanProof Server API","version":"2026-07-22","description":"Version 1 of the deterministic HumanProof server contract. All API calls in this document are server-to-server; never expose the bearer secret in browser code."},"servers":[{"url":"https://humanproof.work"}],"security":[{"serverSecret":[]}],"paths":{"/api/verify/standing":{"get":{"operationId":"getProof","summary":"Read the current app-scoped proof","description":"Read-only and safe to retry. The session token is not consumed.","parameters":[{"$ref":"#/components/parameters/SessionToken"}],"responses":{"200":{"description":"Current proof","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandingProof"},"example":{"score":91,"tier":"passive","label":"Likely human","pass":true,"confidence":"high","reasons":["human_evidence_observed"],"input_authenticity":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/abuse/evaluate":{"post":{"operationId":"evaluateAction","summary":"Evaluate a protected action","description":"actionId is the app-scoped idempotency key. An exact retry returns the original response without new velocity or usage; conflicting reuse returns 409. The 600 requests/minute service-protection limit is separate from the account's commercial evaluated-action cap.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvaluateRequest"},"example":{"actionId":"generation-123","sessionToken":"hpv_st_example","action":"ai_credits","costUsdMicros":25000,"context":{"accountAgeBand":"gt_180d","authenticationStrength":"multi_factor","paymentPresent":true,"priorFreeUsageBand":"none"}}}}},"responses":{"200":{"description":"Immutable evaluation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvaluateResponse"},"example":{"decision":"allow","confidence":"high","reasons":[],"policyVersion":"ai_credits-2026-07-22","mode":"shadow","proof":{"version":"woe-2026-06-16b","score":91,"tier":"passive","label":"Likely human","pass":true,"confidence":"high","reasons":["human_evidence_observed"]}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"A paid subscription or payment recovery is required for new production evaluations; stored idempotent replays remain readable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialSubscriptionError"}}}},"409":{"$ref":"#/components/responses/Conflict"},"429":{"description":"New work exceeded either service protection or the customer-set commercial cap; stored idempotent replays remain readable","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiError"},{"$ref":"#/components/schemas/CommercialQuotaError"}]}}}},"503":{"description":"Evaluation unavailable; apply the explicit customer-configured fallback","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvaluationUnavailableError"},"example":{"error":"Evaluation temporarily unavailable.","code":"temporarily_unavailable","fallback":{"decision":"step_up","source":"outage_fallback"}}}}}}}},"/api/abuse/outcome":{"post":{"operationId":"recordOutcome","summary":"Attach independent customer truth","description":"outcomeId is the app-scoped idempotency key. Exact retries return the original append-only record; conflicting reuse returns 409. New work is limited to 600 requests per minute per app and request source.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutcomeRequest"},"example":{"outcomeId":"result-123","actionId":"generation-123","outcome":"abuse","occurredAt":"2026-07-22T16:00:00.000Z","confirmedLossUsdMicros":25000}}}},"responses":{"200":{"description":"Immutable outcome record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutcomeResponse"},"example":{"outcomeId":"result-123","actionId":"generation-123","outcome":"abuse","source":"customer_api","occurredAt":"2026-07-22T16:00:00.000Z","receivedAt":"2026-07-22T16:00:01.000Z","confirmedLossUsdMicros":25000}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}}},"webhooks":{"humanProofEvent":{"post":{"summary":"Signed HumanProof event","description":"Verify the signature against the exact raw request body before decoding JSON. Reject timestamps more than 300 seconds from the receiver clock and deduplicate by deliveryId.","parameters":[{"name":"HumanProof-Timestamp","in":"header","required":true,"schema":{"type":"string","pattern":"^[0-9]{1,12}$"}},{"name":"HumanProof-Signature","in":"header","required":true,"schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}(,v1=[a-f0-9]{64})?$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEnvelope"}}}},"responses":{"200":{"description":"Event accepted"}}}}},"components":{"securitySchemes":{"serverSecret":{"type":"http","scheme":"bearer","bearerFormat":"hpv_sk_…","description":"Server-only app secret. Never embed it in client code."}},"parameters":{"SessionToken":{"name":"sessionToken","in":"query","required":true,"schema":{"type":"string","maxLength":128},"example":"hpv_st_example"}},"headers":{"RetryAfter":{"description":"Minimum delay in seconds before another attempt","schema":{"type":"integer","minimum":0,"maximum":60}}},"responses":{"BadRequest":{"description":"Request rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Unauthorized":{"description":"Missing, invalid, expired, revoked, or cross-app credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Verify secret required.","code":"unauthorized"}}}},"NotFound":{"description":"App-scoped resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Conflict":{"description":"Idempotency key reused with different immutable input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Evaluation request rejected.","code":"action_id_conflict"}}}},"RateLimited":{"description":"New work is rate limited; stored idempotent replays remain readable","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Too many requests.","code":"rate_limited"}}}},"Unavailable":{"description":"Temporary outage","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"Temporarily unavailable.","code":"temporarily_unavailable"}}}}},"schemas":{"Identifier":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$"},"Confidence":{"type":"string","enum":["high","medium","low"]},"ProofReason":{"type":"string","enum":["human_evidence_observed","automation_risk","insufficient_evidence","evidence_limited","proof_held"]},"ActionReason":{"type":"string","enum":["proof_automation_risk","proof_insufficient","proof_coverage_limited","action_velocity_elevated","account_velocity_elevated","device_velocity_elevated","network_velocity_elevated","account_too_new","authentication_weak","payment_absent","free_usage_elevated","value_at_risk_elevated","evaluation_evidence_limited"]},"PublicProof":{"type":"object","additionalProperties":false,"required":["score","tier","label","pass","confidence","reasons"],"properties":{"score":{"type":"integer","minimum":0,"maximum":100},"tier":{"type":"string","enum":["passive","insufficient"]},"label":{"type":"string"},"pass":{"type":"boolean"},"confidence":{"$ref":"#/components/schemas/Confidence"},"reasons":{"type":"array","uniqueItems":true,"items":{"$ref":"#/components/schemas/ProofReason"}}}},"VersionedPublicProof":{"type":"object","additionalProperties":false,"required":["version","score","tier","label","pass","confidence","reasons"],"properties":{"version":{"type":"string","minLength":1},"score":{"type":"integer","minimum":0,"maximum":100},"tier":{"type":"string","enum":["passive","insufficient"]},"label":{"type":"string"},"pass":{"type":"boolean"},"confidence":{"$ref":"#/components/schemas/Confidence"},"reasons":{"type":"array","uniqueItems":true,"items":{"$ref":"#/components/schemas/ProofReason"}}}},"StandingProof":{"type":"object","additionalProperties":false,"required":["score","tier","label","pass","confidence","reasons","input_authenticity"],"properties":{"score":{"type":"integer","minimum":0,"maximum":100},"tier":{"type":"string","enum":["passive","insufficient"]},"label":{"type":"string"},"pass":{"type":"boolean"},"confidence":{"$ref":"#/components/schemas/Confidence"},"reasons":{"type":"array","uniqueItems":true,"items":{"$ref":"#/components/schemas/ProofReason"}},"input_authenticity":{"oneOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["score","confidence"],"properties":{"score":{"type":"number","minimum":0,"maximum":100},"confidence":{"$ref":"#/components/schemas/Confidence"}}}]}}},"ActionContext":{"type":"object","additionalProperties":false,"properties":{"accountAgeBand":{"type":"string","enum":["unknown","lt_1d","1d_7d","8d_30d","31d_180d","gt_180d"]},"authenticationStrength":{"type":"string","enum":["anonymous","single_factor","multi_factor"]},"paymentPresent":{"type":"boolean"},"priorFreeUsageBand":{"type":"string","enum":["none","low","medium","high"]}}},"EvaluateRequest":{"type":"object","additionalProperties":false,"required":["actionId","sessionToken","action"],"properties":{"actionId":{"$ref":"#/components/schemas/Identifier"},"sessionToken":{"type":"string","maxLength":128},"accountRef":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,255}$"},"action":{"type":"string","pattern":"^[a-z][a-z0-9._-]{0,63}$"},"costUsdMicros":{"type":"integer","minimum":0,"maximum":1000000000000},"context":{"$ref":"#/components/schemas/ActionContext"}}},"EvaluateResponse":{"type":"object","additionalProperties":false,"required":["decision","confidence","reasons","policyVersion","mode","proof"],"properties":{"decision":{"type":"string","enum":["allow","limit","step_up","deny"]},"confidence":{"$ref":"#/components/schemas/Confidence"},"reasons":{"type":"array","items":{"$ref":"#/components/schemas/ActionReason"}},"policyVersion":{"type":"string","minLength":1},"mode":{"type":"string","enum":["shadow","enforce"]},"limitPercent":{"type":"integer","minimum":1,"maximum":99},"proof":{"$ref":"#/components/schemas/VersionedPublicProof"}}},"OutcomeRequest":{"type":"object","additionalProperties":false,"required":["outcomeId","actionId","outcome","occurredAt"],"properties":{"outcomeId":{"$ref":"#/components/schemas/Identifier"},"actionId":{"$ref":"#/components/schemas/Identifier"},"outcome":{"type":"string","enum":["legitimate","abuse","converted","banned","chargeback"]},"occurredAt":{"type":"string","format":"date-time"},"confirmedLossUsdMicros":{"type":"integer","minimum":0,"maximum":1000000000000},"correctsOutcomeId":{"$ref":"#/components/schemas/Identifier"}}},"OutcomeResponse":{"type":"object","additionalProperties":false,"required":["outcomeId","actionId","outcome","occurredAt","source","receivedAt"],"properties":{"outcomeId":{"$ref":"#/components/schemas/Identifier"},"actionId":{"$ref":"#/components/schemas/Identifier"},"outcome":{"type":"string","enum":["legitimate","abuse","converted","banned","chargeback"]},"occurredAt":{"type":"string","format":"date-time"},"confirmedLossUsdMicros":{"type":"integer","minimum":0,"maximum":1000000000000},"correctsOutcomeId":{"$ref":"#/components/schemas/Identifier"},"source":{"const":"customer_api"},"receivedAt":{"type":"string","format":"date-time"}}},"ApiError":{"type":"object","additionalProperties":false,"required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"}}},"EvaluationUnavailableError":{"type":"object","additionalProperties":false,"required":["error","code","fallback"],"properties":{"error":{"type":"string"},"code":{"const":"temporarily_unavailable"},"fallback":{"type":"object","additionalProperties":false,"required":["decision","source"],"properties":{"decision":{"type":"string","enum":["allow","limit","step_up"]},"source":{"const":"outage_fallback"},"limitPercent":{"type":"integer","minimum":1,"maximum":99}}}}},"CommercialQuotaError":{"type":"object","additionalProperties":false,"required":["error","code","retryAt"],"properties":{"error":{"type":"string"},"code":{"const":"commercial_quota_exceeded"},"retryAt":{"type":"string","format":"date-time"}}},"CommercialSubscriptionError":{"type":"object","additionalProperties":false,"required":["error","code","recovery"],"properties":{"error":{"type":"string"},"code":{"const":"commercial_subscription_required"},"recovery":{"type":"string","enum":["subscribe","payment"]}}},"EvaluationWebhookPayload":{"type":"object","additionalProperties":false,"required":["actionId","action","decision","confidence","reasons","policyVersion","mode","proof"],"properties":{"actionId":{"$ref":"#/components/schemas/Identifier"},"action":{"type":"string","pattern":"^[a-z][a-z0-9._-]{0,63}$"},"decision":{"type":"string","enum":["allow","limit","step_up","deny"]},"confidence":{"$ref":"#/components/schemas/Confidence"},"reasons":{"type":"array","items":{"$ref":"#/components/schemas/ActionReason"}},"policyVersion":{"type":"string"},"mode":{"type":"string","enum":["shadow","enforce"]},"limitPercent":{"type":"integer","minimum":1,"maximum":99},"proof":{"$ref":"#/components/schemas/VersionedPublicProof"}}},"PolicyWebhookPayload":{"type":"object","additionalProperties":false,"required":["changeKind","previousMode","nextMode","previousPolicyVersion","nextPolicyVersion"],"properties":{"changeKind":{"type":"string","enum":["update","rollback"]},"previousMode":{"type":"string","enum":["shadow","enforce"]},"nextMode":{"type":"string","enum":["shadow","enforce"]},"previousPolicyVersion":{"type":"string"},"nextPolicyVersion":{"type":"string"}}},"QuotaWarningWebhookPayload":{"type":"object","additionalProperties":false,"required":["periodStart","periodEnd","threshold","usage","includedActions","capActions","plan"],"properties":{"periodStart":{"type":"string","format":"date-time"},"periodEnd":{"type":"string","format":"date-time"},"threshold":{"type":"integer","enum":[50,80,100]},"usage":{"type":"integer","minimum":0},"includedActions":{"type":"integer","minimum":1},"capActions":{"type":"integer","minimum":1},"plan":{"type":"string","enum":["launch","growth"]}}},"WebhookEnvelope":{"type":"object","allOf":[{"if":{"properties":{"type":{"const":"action.evaluated"}},"required":["type"]},"then":{"properties":{"payload":{"$ref":"#/components/schemas/EvaluationWebhookPayload"}}}},{"if":{"properties":{"type":{"const":"action.outcome_recorded"}},"required":["type"]},"then":{"properties":{"payload":{"$ref":"#/components/schemas/OutcomeResponse"}}}},{"if":{"properties":{"type":{"const":"action.policy_updated"}},"required":["type"]},"then":{"properties":{"payload":{"$ref":"#/components/schemas/PolicyWebhookPayload"}}}},{"if":{"properties":{"type":{"const":"quota.warning"}},"required":["type"]},"then":{"properties":{"payload":{"$ref":"#/components/schemas/QuotaWarningWebhookPayload"}}}}],"additionalProperties":false,"required":["id","deliveryId","appId","type","schemaVersion","occurredAt","payload"],"properties":{"id":{"type":"string","pattern":"^evt_[A-Za-z0-9_-]{16,64}$"},"deliveryId":{"type":"string","pattern":"^dlv_[A-Za-z0-9_-]{16,64}$"},"appId":{"type":"string"},"type":{"type":"string","enum":["action.evaluated","action.outcome_recorded","action.policy_updated","quota.warning"]},"schemaVersion":{"const":"2026-07-22"},"occurredAt":{"type":"string","format":"date-time"},"payload":{"type":"object"}}}}}}