{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"Humanproof Public API","version":"2026-05-14","summary":"Public verification and Humanproof Skill Standard endpoints.","description":"REST contract for public HSS records, Score VC verification, paid candidate and score reads, API webhook endpoint management, and private agent decision reporting. Dashboard developer tools such as the sandbox, delivery history, and test-event sender are documented at https://humanproof.io/developers.","contact":{"name":"Humanproof","url":"https://humanproof.io","email":"standard@humanproof.io"},"license":{"name":"CC BY-SA 4.0","url":"https://creativecommons.org/licenses/by-sa/4.0/"}},"externalDocs":{"description":"Humanproof developer docs, quickstart, sandbox, and webhook signing guide.","url":"https://humanproof.io/developers"},"servers":[{"url":"https://humanproof.io","description":"Production"}],"tags":[{"name":"Discovery","description":"Machine-readable contracts and verifier discovery documents."},{"name":"HSS","description":"Humanproof Skill Standard records and vocabulary."},{"name":"Score VC","description":"Public status and revocation verification for Score VCs."},{"name":"Scores","description":"Read-only public score lookup for public Humanproof profiles."},{"name":"Candidates","description":"Read-only public candidate previews and details built from public Humanproof profiles."},{"name":"Webhooks","description":"API webhook endpoint registration for HMAC-signed event delivery. Delivery history and test events are available in the signed-in developer dashboard."},{"name":"Agent decisions","description":"Private reporting for decisions and outcomes produced by API clients after using Humanproof candidate or score data."}],"paths":{"/api/v1/openapi.json":{"get":{"tags":["Discovery"],"operationId":"getOpenApiDocument","summary":"Get the OpenAPI contract","description":"Returns the OpenAPI 3.1 source of truth for the public Humanproof REST surface.","parameters":[{"name":"Humanproof-Version","in":"header","required":false,"description":"Optional date-based minor version. Defaults to 2026-05-14. Unsupported dates return 400.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-05-14"}}],"responses":{"200":{"description":"OpenAPI document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenApiDocument"}}}},"400":{"description":"Invalid or unsupported API version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/candidates/search":{"get":{"tags":["Candidates"],"operationId":"searchCandidatePreviews","summary":"Search public candidate previews","description":"Returns public profile previews only. Private evidence, email, identity artifacts, worker ids, and hiring-decision data are not returned. Requires an API key with the `candidates:read` scope, or a successful x402 paid retry.","security":[{"HumanproofApiKey":[]},{"X402Payment":[]},{"X402PaymentSignature":[]}],"parameters":[{"name":"Humanproof-Version","in":"header","required":false,"description":"Optional date-based minor version. Defaults to 2026-05-14. Unsupported dates return 400.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-05-14"}},{"name":"q","in":"query","required":true,"description":"Skill, handle, display name, or title prefix. Leading @ is accepted for handles.","schema":{"type":"string","minLength":2,"maxLength":80}},{"name":"limit","in":"query","required":false,"description":"Maximum number of previews to return.","schema":{"type":"integer","minimum":1,"maximum":50,"default":18}}],"responses":{"200":{"description":"Public candidate preview search results","headers":{"PAYMENT-RESPONSE":{"description":"Base64-encoded x402 settlement receipt. Present on successful x402-paid retries.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CandidatePreviewSearchResult"}}}},"400":{"description":"Invalid API version, query, or search limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required. API-key callers may receive insufficient_credits; unauthenticated callers may receive an x402 challenge.","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 payment challenge. Present when the caller has no API key and credit metering is enabled.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/X402PaymentChallenge"}]}}}},"403":{"description":"API key does not have the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many candidate preview searches","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Candidate search temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/candidates/{username}":{"get":{"tags":["Candidates"],"operationId":"getCandidateDetail","summary":"Get a public candidate detail","description":"Returns one public candidate profile by username. Private evidence, email, identity artifacts, worker ids, raw ranking signals, and hiring-decision data are not returned. Requires an API key with the `candidates:read` scope, or a successful x402 paid retry.","security":[{"HumanproofApiKey":[]},{"X402Payment":[]},{"X402PaymentSignature":[]}],"parameters":[{"name":"Humanproof-Version","in":"header","required":false,"description":"Optional date-based minor version. Defaults to 2026-05-14. Unsupported dates return 400.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-05-14"}},{"name":"username","in":"path","required":true,"description":"Public Humanproof username. Leading @ is accepted by the endpoint when URL-encoded.","schema":{"type":"string","minLength":3,"maxLength":31,"pattern":"^@?[a-z0-9][a-z0-9_-]{1,28}[a-z0-9]$","not":{"enum":["search","@search"]}}}],"responses":{"200":{"description":"Public candidate detail","headers":{"PAYMENT-RESPONSE":{"description":"Base64-encoded x402 settlement receipt. Present on successful x402-paid retries.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CandidateDetail"}}}},"400":{"description":"Invalid API version or candidate username","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required. API-key callers may receive insufficient_credits; unauthenticated callers may receive an x402 challenge.","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 payment challenge. Present when the caller has no API key and credit metering is enabled.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/X402PaymentChallenge"}]}}}},"403":{"description":"API key does not have the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Candidate not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many candidate detail requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Candidate detail temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/scores/{scoreId}":{"get":{"tags":["Scores"],"operationId":"getPublicScore","summary":"Get a public score","description":"Returns one active public score snapshot by id when the score belongs to an onboarded public profile with active identity verification. Private evidence, worker ids, raw VC JSON-LD, engine binary hashes, evidence trace hashes, and status-list indexes are not returned. Requires an API key with the `scores:read` scope, or a successful x402 paid retry.","security":[{"HumanproofApiKey":[]},{"X402Payment":[]},{"X402PaymentSignature":[]}],"parameters":[{"name":"Humanproof-Version","in":"header","required":false,"description":"Optional date-based minor version. Defaults to 2026-05-14. Unsupported dates return 400.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-05-14"}},{"name":"scoreId","in":"path","required":true,"description":"Public score snapshot id.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Public score lookup result","headers":{"PAYMENT-RESPONSE":{"description":"Base64-encoded x402 settlement receipt. Present on successful x402-paid retries.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicScore"}}}},"400":{"description":"Invalid API version or score id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required. API-key callers may receive insufficient_credits; unauthenticated callers may receive an x402 challenge.","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 payment challenge. Present when the caller has no API key and credit metering is enabled.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/X402PaymentChallenge"}]}}}},"403":{"description":"API key does not have the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Score not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many score lookup requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Score lookup temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/.well-known/humanproof-openapi.json":{"get":{"tags":["Discovery"],"operationId":"getWellKnownOpenApiDocument","summary":"Get the OpenAPI contract from well-known discovery","parameters":[{"name":"Humanproof-Version","in":"header","required":false,"description":"Optional date-based minor version. Defaults to 2026-05-14. Unsupported dates return 400.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-05-14"}}],"responses":{"200":{"description":"OpenAPI document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenApiDocument"}}}},"400":{"description":"Invalid or unsupported API version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/.well-known/humanproof-engine.json":{"get":{"tags":["Discovery"],"operationId":"getEngineDiscovery","summary":"Get scoring engine and Score VC verifier metadata","parameters":[{"name":"Humanproof-Version","in":"header","required":false,"description":"Optional date-based minor version. Defaults to 2026-05-14. Unsupported dates return 400.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-05-14"}}],"responses":{"200":{"description":"Engine discovery document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EngineDiscovery"}}}},"400":{"description":"Invalid or unsupported API version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/.well-known/humanproof-score-vc-public-key.json":{"get":{"tags":["Discovery","Score VC"],"operationId":"getScoreVcPublicKey","summary":"Get the current Score VC public verification key","description":"Stable public-key document for independent Humanproof Score VC verification. Publishes the current Ed25519 verification method and public key only; private signing material is never exposed.","parameters":[{"name":"Humanproof-Version","in":"header","required":false,"description":"Optional date-based minor version. Defaults to 2026-05-14. Unsupported dates return 400.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-05-14"}}],"responses":{"200":{"description":"Score VC public key document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoreVcPublicKey"}}}},"400":{"description":"Invalid or unsupported API version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Score VC signing is not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/.well-known/humanproof-score-core-release-manifest.json":{"get":{"tags":["Discovery"],"operationId":"getScoreCoreReleaseManifest","summary":"Get the score-core release manifest","parameters":[{"name":"Humanproof-Version","in":"header","required":false,"description":"Optional date-based minor version. Defaults to 2026-05-14. Unsupported dates return 400.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-05-14"}}],"responses":{"200":{"description":"Score-core release manifest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoreCoreReleaseManifest"}}}},"400":{"description":"Invalid or unsupported API version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/standard/v1/context.jsonld":{"get":{"tags":["HSS"],"operationId":"getHssContext","summary":"Get the HSS JSON-LD context","parameters":[{"name":"Humanproof-Version","in":"header","required":false,"description":"Optional date-based minor version. Defaults to 2026-05-14. Unsupported dates return 400.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-05-14"}}],"responses":{"200":{"description":"JSON-LD context","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/JsonLdContextDocument"}}}},"400":{"description":"Invalid or unsupported API version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/standard/v1/skills":{"get":{"tags":["HSS"],"operationId":"listHssSkills","summary":"List HSS skill records","parameters":[{"name":"Humanproof-Version","in":"header","required":false,"description":"Optional date-based minor version. Defaults to 2026-05-14. Unsupported dates return 400.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-05-14"}}],"responses":{"200":{"description":"Skill catalog","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/SkillCatalog"}}}},"400":{"description":"Invalid or unsupported API version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/standard/v1/skills/{id}":{"get":{"tags":["HSS"],"operationId":"getHssSkill","summary":"Get one HSS skill record","parameters":[{"name":"Humanproof-Version","in":"header","required":false,"description":"Optional date-based minor version. Defaults to 2026-05-14. Unsupported dates return 400.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-05-14"}},{"name":"id","in":"path","required":true,"description":"Skill slug, JSON-LD filename, or hss-prefixed id. Examples: react, react.jsonld, hss:react.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Skill record","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/SkillRecord"}}}},"400":{"description":"Invalid or unsupported API version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Skill not found","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/SkillNotFoundError"}}}}}}},"/standard/v1/score-bands.jsonld":{"get":{"tags":["HSS"],"operationId":"getScoreBands","summary":"Get Humanproof Score band definitions","parameters":[{"name":"Humanproof-Version","in":"header","required":false,"description":"Optional date-based minor version. Defaults to 2026-05-14. Unsupported dates return 400.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-05-14"}}],"responses":{"200":{"description":"Score band definitions","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/ScoreBandDefinitionSet"}}}},"400":{"description":"Invalid or unsupported API version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/standard/v1/score-vc-status/{statusToken}":{"get":{"tags":["Score VC"],"operationId":"getScoreVcStatus","summary":"Check public Score VC revocation status","description":"Looks up a public status token embedded in a Score VC. The response reveals status only, not worker identity, score, evidence, or revocation reason.","parameters":[{"name":"Humanproof-Version","in":"header","required":false,"description":"Optional date-based minor version. Defaults to 2026-05-14. Unsupported dates return 400.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-05-14"}},{"name":"statusToken","in":"path","required":true,"schema":{"type":"string","minLength":64,"maxLength":64,"pattern":"^[0-9a-f]{64}$"}},{"name":"vcSha256","in":"query","required":false,"description":"Optional SHA-256 hex digest of the Score VC payload for an exact token and credential match.","schema":{"type":"string","pattern":"^[0-9a-f]{64}$"}}],"responses":{"200":{"description":"Score VC public status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoreVcStatus"}}}},"400":{"description":"Invalid API version, status token, or VC digest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Status token not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/standard/v1/status-lists/score-vc-revocation/{listId}":{"get":{"tags":["Score VC"],"operationId":"getScoreVcRevocationStatusList","summary":"Get a signed Score VC revocation bitstring status list","parameters":[{"name":"Humanproof-Version","in":"header","required":false,"description":"Optional date-based minor version. Defaults to 2026-05-14. Unsupported dates return 400.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-05-14"}},{"name":"listId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Signed bitstring status list credential","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/ScoreVcStatusListCredential"}}}},"400":{"description":"Invalid API version or status list id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Status list not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Score VC signing is not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/score-vc/verify":{"post":{"tags":["Score VC"],"operationId":"verifyScoreVc","summary":"Verify a presented Score VC","description":"Public, unauthenticated, side-effect-free Score VC verification. The caller POSTs the signed credential JSON exactly as issued by Humanproof. The endpoint performs three independent trust checks (issuer pinning, Ed25519 signature against the published key, revocation lookup) and returns a structured result envelope. Failure to verify is encoded as `{ valid: false, reason }` with HTTP 200 so machine consumers always see the structured outcome; only protocol-level problems (wrong content type, unreadable body, oversize payload, unsupported version header, invalid API key, insufficient scope, paid metering failure, or per-IP rate limiting) return non-200. Anonymous callers are capped at 60 calls/min and 1,000 calls/day per IP. Valid `scores:read` API-key callers use the paid `score_lookup` meter for higher limits when credit metering is enabled.","security":[{},{"HumanproofApiKey":[]}],"parameters":[{"name":"Humanproof-Version","in":"header","required":false,"description":"Optional date-based minor version. Defaults to 2026-05-14. Unsupported dates return 400.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-05-14"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoreVcVerifyRequest"}},"application/ld+json":{"schema":{"$ref":"#/components/schemas/ScoreVcVerifyRequest"}}}},"responses":{"200":{"description":"Structured verification result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoreVcVerifyResult"}}}},"400":{"description":"Body unreadable, not JSON, or unsupported API version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient credits for API-key verifier calls","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key does not have the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Payload exceeds 256 KB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"Unsupported content type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Per-IP rate limit exceeded; retry after the Retry-After window","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"API key or metering temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"tags":["Score VC"],"operationId":"describeScoreVcVerifier","summary":"Describe the Score VC verifier endpoint","parameters":[{"name":"Humanproof-Version","in":"header","required":false,"description":"Optional date-based minor version. Defaults to 2026-05-14. Unsupported dates return 400.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-05-14"}}],"responses":{"200":{"description":"Endpoint description, accepted content types, and max body size","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoreVcVerifyEndpointDescription"}}}},"400":{"description":"Invalid or unsupported API version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/agent-decisions":{"post":{"tags":["Agent decisions"],"operationId":"createAgentDecisionReport","summary":"Report an agent decision","description":"Creates one private agent decision or outcome report. Requires an API key with the `agent-decisions:write` scope and an `Idempotency-Key` header. Retrying the same normalized request with the same idempotency key returns the same report with `replayed: true`; reusing the key for different content returns 409. Reports are visible only to the API key owner and Humanproof operations, and never expose private worker ids.","security":[{"HumanproofApiKey":[]}],"parameters":[{"name":"Humanproof-Version","in":"header","required":false,"description":"Optional date-based minor version. Defaults to 2026-05-14. Unsupported dates return 400.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-05-14"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for retry-safe create requests. Use the same key only when retrying the exact same normalized request.","schema":{"type":"string","minLength":16,"maxLength":128,"pattern":"^[A-Za-z0-9._~:-]{16,128}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDecisionReportCreateRequest"}}}},"responses":{"200":{"description":"Idempotent replay of an existing agent decision report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDecisionReportCreateResponse"}}}},"201":{"description":"Created agent decision report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDecisionReportCreateResponse"}}}},"400":{"description":"Invalid subject, decision, outcome, metadata, JSON body, or Idempotency-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key does not have the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Idempotency-Key reused for different request content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many report requests or failed authentication attempts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Agent decision report persistence failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Agent decision report service temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/webhooks/endpoints":{"get":{"tags":["Webhooks"],"operationId":"listWebhookEndpoints","summary":"List webhook endpoints","description":"Lists active webhook endpoints owned by the API key user. Requires an API key with the `webhooks:write` scope. Signing secrets are never returned after creation.","security":[{"HumanproofApiKey":[]}],"parameters":[{"name":"Humanproof-Version","in":"header","required":false,"description":"Optional date-based minor version. Defaults to 2026-05-14. Unsupported dates return 400.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-05-14"}}],"responses":{"200":{"description":"Webhook endpoint list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointList"}}}},"400":{"description":"Invalid or unsupported API version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key does not have the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many failed authentication attempts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Webhook endpoint persistence failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Webhook endpoint service temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Webhooks"],"operationId":"createWebhookEndpoint","summary":"Create a webhook endpoint","description":"Creates one HTTPS webhook endpoint for HMAC-signed event delivery. Requires an API key with the `webhooks:write` scope and an `Idempotency-Key` header. Retrying the same normalized request with the same idempotency key returns the same endpoint and one-time `signingSecret`; reusing the key for different content returns 409. The `signingSecret` is stored only as a KMS-encrypted envelope.","security":[{"HumanproofApiKey":[]}],"parameters":[{"name":"Humanproof-Version","in":"header","required":false,"description":"Optional date-based minor version. Defaults to 2026-05-14. Unsupported dates return 400.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-05-14"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for retry-safe create requests. Use the same key only when retrying the exact same normalized request.","schema":{"type":"string","minLength":16,"maxLength":128,"pattern":"^[A-Za-z0-9._~:-]{16,128}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointCreateRequest"}}}},"responses":{"201":{"description":"Created webhook endpoint and one-time signing secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointCreateResponse"}}}},"400":{"description":"Invalid URL, event set, description, JSON body, or Idempotency-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key does not have the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Maximum active webhook endpoint count reached, or Idempotency-Key reused for different request content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many failed authentication attempts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Webhook endpoint persistence failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Webhook endpoint service temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/webhooks/endpoints/{endpointId}":{"delete":{"tags":["Webhooks"],"operationId":"deleteWebhookEndpoint","summary":"Disable a webhook endpoint","description":"Soft-disables one webhook endpoint owned by the API key user. Requires an API key with the `webhooks:write` scope. Disabled endpoints no longer receive events and are omitted from the list response.","security":[{"HumanproofApiKey":[]}],"parameters":[{"name":"Humanproof-Version","in":"header","required":false,"description":"Optional date-based minor version. Defaults to 2026-05-14. Unsupported dates return 400.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-05-14"}},{"name":"endpointId","in":"path","required":true,"description":"Webhook endpoint id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Disabled webhook endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointMutation"}}}},"400":{"description":"Invalid endpoint id or API version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key does not have the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many failed authentication attempts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Webhook endpoint persistence failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Webhook endpoint service temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"securitySchemes":{"HumanproofApiKey":{"type":"http","scheme":"bearer","bearerFormat":"Humanproof API key","description":"Humanproof API key. Accepted on paid v1 endpoints (candidates/*, scores/*), webhook endpoint management, and agent decision reporting. Get one at https://humanproof.io/dashboard/developer/api-keys. Paid endpoints also accept successful x402 paid retries, and the public Score VC verifier (`/api/v1/score-vc/verify`) remains unauthenticated."},"X402Payment":{"type":"apiKey","in":"header","name":"X-PAYMENT","description":"Base64-encoded x402 payment payload for a paid retry after receiving a 402 challenge."},"X402PaymentSignature":{"type":"apiKey","in":"header","name":"PAYMENT-SIGNATURE","description":"Base64-encoded x402 payment payload for clients using the PAYMENT-SIGNATURE header name."}},"schemas":{"OpenApiDocument":{"type":"object","additionalProperties":true,"required":["openapi","info","paths"],"properties":{"openapi":{"type":"string"},"info":{"type":"object","additionalProperties":true},"paths":{"type":"object","additionalProperties":true}}},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"},"supported_version":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}},"WebhookEventType":{"type":"string","enum":["score.updated","score.revised","evidence.revoked","dispute.opened","dispute.resolved","candidate.consent_changed"]},"WebhookEndpoint":{"type":"object","additionalProperties":false,"required":["schemaVersion","id","userId","url","description","eventTypes","secretPrefix","createdAt","updatedAt","disabledAt"],"properties":{"schemaVersion":{"const":"humanproof.webhook_endpoint.v1"},"id":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"description":{"type":["string","null"],"maxLength":120},"eventTypes":{"type":"array","minItems":1,"maxItems":6,"uniqueItems":true,"items":{"$ref":"#/components/schemas/WebhookEventType"}},"secretPrefix":{"type":"string","pattern":"^whsec_[A-Za-z0-9_-]{12}$"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"disabledAt":{"type":["string","null"],"format":"date-time"}}},"WebhookEndpointList":{"type":"object","additionalProperties":false,"required":["schemaVersion","endpoints"],"properties":{"schemaVersion":{"const":"humanproof.webhook_endpoints.v1"},"endpoints":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"WebhookEndpointCreateRequest":{"type":"object","additionalProperties":false,"required":["url","events"],"example":{"url":"https://api.example.com/humanproof/webhooks","description":"Production events","events":["score.updated","score.revised"]},"properties":{"url":{"type":"string","format":"uri","maxLength":2048,"pattern":"^https://"},"events":{"type":"array","minItems":1,"maxItems":6,"uniqueItems":true,"items":{"$ref":"#/components/schemas/WebhookEventType"}},"description":{"type":"string","maxLength":120}}},"WebhookEndpointCreateResponse":{"type":"object","additionalProperties":false,"required":["schemaVersion","endpoint","signingSecret"],"example":{"schemaVersion":"humanproof.webhook_endpoint_create.v1","endpoint":{"schemaVersion":"humanproof.webhook_endpoint.v1","id":"11111111-1111-4111-8111-111111111111","userId":"22222222-2222-4222-8222-222222222222","url":"https://api.example.com/humanproof/webhooks","description":"Production events","eventTypes":["score.updated","score.revised"],"secretPrefix":"whsec_abc123ABC456","createdAt":"2026-06-01T00:00:00.000Z","updatedAt":"2026-06-01T00:00:00.000Z","disabledAt":null},"signingSecret":"whsec_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQ"},"properties":{"schemaVersion":{"const":"humanproof.webhook_endpoint_create.v1"},"endpoint":{"$ref":"#/components/schemas/WebhookEndpoint"},"signingSecret":{"type":"string","pattern":"^whsec_[A-Za-z0-9_-]{43}$","description":"One-time plaintext signing secret. Store it immediately; Humanproof will not return it again."}}},"WebhookEndpointMutation":{"type":"object","additionalProperties":false,"required":["endpoint"],"properties":{"endpoint":{"$ref":"#/components/schemas/WebhookEndpoint"}}},"AgentDecisionValue":{"type":"string","enum":["shortlisted","rejected","contacted","interview_requested","offer_extended","hired","no_action"]},"AgentOutcomeValue":{"type":"string","enum":["pending","positive","negative","neutral","unknown"]},"AgentDecisionSubject":{"oneOf":[{"type":"object","additionalProperties":false,"required":["kind","username"],"properties":{"kind":{"const":"candidate"},"username":{"type":"string","pattern":"^@?[a-z0-9][a-z0-9_-]{1,28}[a-z0-9]$"}}},{"type":"object","additionalProperties":false,"required":["kind","scoreId"],"properties":{"kind":{"const":"score"},"scoreId":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}}]},"AgentDecisionReport":{"type":"object","additionalProperties":false,"required":["schemaVersion","id","userId","apiKeyId","subject","decision","outcome","agentName","agentVersion","jobRef","reasonCodes","notes","metadata","createdAt"],"properties":{"schemaVersion":{"const":"humanproof.agent_decision_report.v1"},"id":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid"},"apiKeyId":{"type":["string","null"],"format":"uuid"},"subject":{"$ref":"#/components/schemas/AgentDecisionSubject"},"decision":{"$ref":"#/components/schemas/AgentDecisionValue"},"outcome":{"$ref":"#/components/schemas/AgentOutcomeValue"},"agentName":{"type":["string","null"],"maxLength":80},"agentVersion":{"type":["string","null"],"maxLength":80},"jobRef":{"type":["string","null"],"maxLength":120},"reasonCodes":{"type":"array","maxItems":10,"uniqueItems":true,"items":{"type":"string","pattern":"^[a-z0-9_.:-]{1,64}$"}},"notes":{"type":["string","null"],"maxLength":1000},"metadata":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"}}},"AgentDecisionReportCreateRequest":{"type":"object","additionalProperties":false,"required":["subject","decision"],"example":{"subject":{"kind":"candidate","username":"maya-chen"},"decision":"shortlisted","outcome":"pending","agentName":"Talent routing agent","agentVersion":"2026.06.01","jobRef":"req-frontend-123","reasonCodes":["react_match","verified_score"],"metadata":{"workflowId":"wf_123"}},"properties":{"subject":{"$ref":"#/components/schemas/AgentDecisionSubject"},"decision":{"$ref":"#/components/schemas/AgentDecisionValue"},"outcome":{"$ref":"#/components/schemas/AgentOutcomeValue","default":"pending"},"agentName":{"type":"string","maxLength":80},"agentVersion":{"type":"string","maxLength":80},"jobRef":{"type":"string","maxLength":120},"reasonCodes":{"type":"array","maxItems":10,"uniqueItems":true,"items":{"type":"string","pattern":"^[a-z0-9_.:-]{1,64}$"}},"notes":{"type":"string","maxLength":1000},"metadata":{"type":"object","additionalProperties":true}}},"AgentDecisionReportCreateResponse":{"type":"object","additionalProperties":false,"required":["schemaVersion","report","replayed"],"properties":{"schemaVersion":{"const":"humanproof.agent_decision_report_create.v1"},"report":{"$ref":"#/components/schemas/AgentDecisionReport"},"replayed":{"type":"boolean"}}},"X402PaymentChallenge":{"type":"object","additionalProperties":false,"required":["x402Version","accepts"],"properties":{"x402Version":{"const":1},"accepts":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/X402PaymentRequirement"}}}},"X402PaymentRequirement":{"type":"object","additionalProperties":true,"required":["scheme","network","maxAmountRequired","resource","description","payTo","asset","extra"],"properties":{"scheme":{"const":"exact"},"network":{"type":"string","enum":["base","base-sepolia"]},"amount":{"type":"string","pattern":"^\\d+$"},"maxAmountRequired":{"type":"string","pattern":"^\\d+$"},"resource":{"type":"string","format":"uri"},"description":{"type":"string"},"mimeType":{"const":"application/json"},"payTo":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"asset":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"maxTimeoutSeconds":{"type":"integer","minimum":1},"extra":{"type":"object","additionalProperties":true,"required":["name","version","nonce","endpoint","idempotencyKey"],"properties":{"name":{"type":"string"},"version":{"type":"string"},"nonce":{"type":"string","minLength":16,"maxLength":128},"endpoint":{"type":"string","enum":["score_lookup","candidate_lookup","candidate_search"]},"idempotencyKey":{"type":"string","minLength":16,"maxLength":128}}}}},"SkillNotFoundError":{"type":"object","additionalProperties":false,"required":["error","id"],"properties":{"error":{"const":"skill_not_found"},"id":{"type":"string","pattern":"^hss:[a-z0-9-]+$"}}},"JsonLdContextDocument":{"type":"object","additionalProperties":true,"required":["@context"],"properties":{"@context":{"type":"object","additionalProperties":true}}},"SkillCatalog":{"type":"object","additionalProperties":true,"required":["@context","@type","version","count","skills"],"properties":{"@context":{"type":"string"},"@type":{"const":"SkillCatalog"},"version":{"type":"string"},"count":{"type":"integer","minimum":0},"skills":{"type":"array","items":{"$ref":"#/components/schemas/SkillRecord"}}}},"SkillRecord":{"type":"object","additionalProperties":false,"required":["@context","@type","@id","id","version","label","aliases","domain","category","description","evidence_types","decay_half_life_months","depends_on","related_to","proficiency_rubric","anchored"],"properties":{"@context":{"type":"string"},"@type":{"const":"Skill"},"@id":{"type":"string"},"id":{"type":"string","pattern":"^hss:[a-z0-9-]+$"},"version":{"type":"string"},"label":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"domain":{"type":"string","enum":["technical","creative","interpersonal","domain","foundational"]},"subdomain":{"type":["string","null"]},"category":{"type":"array","items":{"type":"string"}},"description":{"type":"string"},"evidence_types":{"type":"array","items":{"$ref":"#/components/schemas/SkillEvidenceType"}},"decay_half_life_months":{"type":"integer","minimum":0},"depends_on":{"type":"array","items":{"type":"string"}},"related_to":{"type":"array","items":{"type":"string"}},"proficiency_rubric":{"type":"object","additionalProperties":false,"required":["novice","intermediate","advanced","expert"],"properties":{"novice":{"type":"string"},"intermediate":{"type":"string"},"advanced":{"type":"string"},"expert":{"type":"string"}}},"anchored":{"type":"string"}}},"SkillEvidenceType":{"type":"object","additionalProperties":false,"required":["type","weight","signal"],"properties":{"type":{"type":"string"},"weight":{"type":"number","minimum":0,"maximum":1},"signal":{"type":"string"}}},"ScoreBandDefinitionSet":{"type":"object","additionalProperties":true,"required":["@context","@type","@id","version","score_scale","bands"],"properties":{"@context":{"type":"string"},"@type":{"const":"ScoreBandDefinitionSet"},"@id":{"type":"string"},"version":{"type":"string"},"score_scale":{"type":"object","additionalProperties":true},"bands":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"ScoreVcStatus":{"type":"object","additionalProperties":false,"required":["schemaVersion","status","revoked","checkedAt"],"properties":{"schemaVersion":{"const":"humanproof.score_vc_status.v1"},"status":{"type":"string","enum":["active","revoked"]},"revoked":{"type":"boolean"},"revokedAt":{"type":"string","format":"date-time"},"checkedAt":{"type":"string","format":"date-time"}}},"ScoreVcStatusListCredential":{"type":"object","additionalProperties":true,"required":["@context","type","issuer","validFrom","credentialSubject","proof"],"properties":{"@context":{"type":"array","items":{"type":"string"}},"type":{"type":"array","items":{"type":"string"}},"issuer":{"type":"string"},"validFrom":{"type":"string","format":"date-time"},"validUntil":{"type":"string","format":"date-time"},"credentialSubject":{"type":"object","additionalProperties":true},"proof":{"type":"object","additionalProperties":true}}},"ScoreVcPublicKey":{"type":"object","additionalProperties":false,"required":["schemaVersion","id","issuer","proofType","proofPurpose","verificationMethod"],"properties":{"schemaVersion":{"const":"humanproof.score_vc_public_key.v1"},"id":{"type":"string"},"issuer":{"type":"string"},"proofType":{"const":"HumanproofScoreEd25519Signature2026"},"proofPurpose":{"const":"assertionMethod"},"verificationMethod":{"type":"object","additionalProperties":false,"required":["id","type","controller","publicKeyBase64url"],"properties":{"id":{"type":"string"},"type":{"const":"Ed25519VerificationKey2020"},"controller":{"type":"string"},"publicKeyBase64url":{"type":"string","pattern":"^[A-Za-z0-9_-]+$"}}}}},"ScoreVcVerifyRequest":{"type":"object","additionalProperties":true,"required":["@context","type","issuer","credentialSubject","proof"],"properties":{"@context":{"type":"array","items":{"type":"string"}},"type":{"type":"array","items":{"type":"string"}},"issuer":{"type":"string"},"issuanceDate":{"type":"string","format":"date-time"},"credentialSubject":{"type":"object","additionalProperties":true},"credentialStatus":{"type":"object","additionalProperties":true},"proof":{"type":"object","additionalProperties":true}}},"ScoreVcVerifyResult":{"type":"object","additionalProperties":true,"required":["schemaVersion","valid"],"properties":{"schemaVersion":{"type":"string","enum":["humanproof.score_vc_verify.v1"]},"valid":{"type":"boolean"},"signatureValid":{"type":"boolean"},"issuerMatch":{"type":"boolean"},"revocation":{"type":"object","additionalProperties":false,"required":["checked","revoked"],"properties":{"checked":{"type":"boolean"},"revoked":{"type":"boolean"},"revokedAt":{"type":["string","null"]}}},"credential":{"type":"object","additionalProperties":true,"properties":{"issuer":{"type":"string"},"subject":{"type":"string"},"score":{"type":"integer"},"scoreBand":{"type":"string"},"confidenceLow":{"type":"integer"},"confidenceHigh":{"type":"integer"},"issuedAt":{"type":"string"},"engineId":{"type":"string"},"engineVersion":{"type":"string"},"engineBinarySha256":{"type":"string"},"verificationMethod":{"type":"string"}}},"notes":{"type":"array","items":{"type":"string"}},"reason":{"type":"string"},"message":{"type":"string"},"presented":{"type":"object","additionalProperties":true}}},"ScoreVcVerifyEndpointDescription":{"type":"object","additionalProperties":false,"required":["endpoint","schemaVersion","acceptedContentTypes","maxBodyBytes"],"properties":{"endpoint":{"type":"string"},"schemaVersion":{"type":"string"},"acceptedContentTypes":{"type":"array","items":{"type":"string"}},"maxBodyBytes":{"type":"integer"},"rateLimits":{"type":"object","additionalProperties":false,"properties":{"anonymous":{"type":"object","additionalProperties":false,"required":["perMinute","perDay"],"properties":{"perMinute":{"type":"integer"},"perDay":{"type":"integer"}}},"apiKey":{"type":"string"}}},"docs":{"type":"string"},"humanUi":{"type":"string"}}},"PublicScore":{"type":"object","additionalProperties":false,"required":["schemaVersion","id","score","confidence","scoreBand","issuedAt","evidenceCount","engineVersion","profile","scoreVc"],"properties":{"schemaVersion":{"const":"humanproof.public_score.v1"},"id":{"type":"string","pattern":"^[0-9a-f]{64}$"},"score":{"type":"integer","minimum":0,"maximum":1000},"confidence":{"type":"object","additionalProperties":false,"required":["low","high"],"properties":{"low":{"type":"integer","minimum":0,"maximum":1000},"high":{"type":"integer","minimum":0,"maximum":1000}}},"scoreBand":{"type":"string","enum":["emerging","developing","verified","strong","exceptional"]},"issuedAt":{"type":"string","format":"date-time"},"evidenceCount":{"type":"integer","minimum":0},"engineVersion":{"type":"string"},"profile":{"$ref":"#/components/schemas/PublicScoreProfile"},"scoreVc":{"oneOf":[{"$ref":"#/components/schemas/PublicScoreVc"},{"type":"null"}]}}},"PublicScoreProfile":{"type":"object","additionalProperties":false,"required":["username","displayName","avatarUrl","profilePath"],"properties":{"username":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{1,28}[a-z0-9]$"},"displayName":{"type":"string"},"avatarUrl":{"type":["string","null"]},"profilePath":{"type":"string","pattern":"^/u/[^/]+$"}}},"PublicScoreVc":{"type":"object","additionalProperties":false,"required":["sha256","statusUrl","statusListCredential"],"properties":{"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"statusUrl":{"type":["string","null"]},"statusListCredential":{"type":["string","null"]}}},"CandidatePreviewSearchResult":{"type":"object","additionalProperties":false,"required":["query","candidates","resultCount"],"properties":{"query":{"type":"string"},"candidates":{"type":"array","items":{"$ref":"#/components/schemas/CandidatePreview"}},"resultCount":{"type":"integer","minimum":0}}},"CandidatePreview":{"type":"object","additionalProperties":false,"required":["username","displayName","title","avatarUrl","profilePath","topSkills","matchedSkills","skillCount","verifiedSkillCount"],"properties":{"username":{"type":"string","pattern":"^[a-z0-9_][a-z0-9_.-]{0,62}$"},"displayName":{"type":"string"},"title":{"type":["string","null"]},"avatarUrl":{"type":["string","null"]},"profilePath":{"type":"string","pattern":"^/u/[^/]+$"},"topSkills":{"type":"array","items":{"$ref":"#/components/schemas/CandidateSkill"}},"matchedSkills":{"type":"array","items":{"$ref":"#/components/schemas/CandidateSkill"}},"skillCount":{"type":"integer","minimum":0},"verifiedSkillCount":{"type":"integer","minimum":0}}},"CandidateDetail":{"type":"object","additionalProperties":false,"required":["username","displayName","title","bio","avatarUrl","profilePath","memberSince","skills","skillCount","verifiedSkillCount","score"],"properties":{"username":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{1,28}[a-z0-9]$","not":{"const":"search"}},"displayName":{"type":"string"},"title":{"type":["string","null"]},"bio":{"type":["string","null"]},"avatarUrl":{"type":["string","null"]},"profilePath":{"type":"string","pattern":"^/u/[^/]+$"},"memberSince":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}$"},"skills":{"type":"array","items":{"$ref":"#/components/schemas/CandidateSkill"}},"skillCount":{"type":"integer","minimum":0},"verifiedSkillCount":{"type":"integer","minimum":0},"score":{"oneOf":[{"$ref":"#/components/schemas/CandidateScore"},{"type":"null"}]}}},"CandidateScore":{"type":"object","additionalProperties":false,"required":["score","confidence","scoreBand","issuedAt","evidenceCount","engineVersion","scoreVc"],"properties":{"score":{"type":"integer","minimum":0,"maximum":1000},"confidence":{"type":"object","additionalProperties":false,"required":["low","high"],"properties":{"low":{"type":"integer","minimum":0,"maximum":1000},"high":{"type":"integer","minimum":0,"maximum":1000}}},"scoreBand":{"type":"string","enum":["emerging","developing","verified","strong","exceptional"]},"issuedAt":{"type":"string","format":"date-time"},"evidenceCount":{"type":"integer","minimum":0},"engineVersion":{"type":"string"},"scoreVc":{"oneOf":[{"$ref":"#/components/schemas/CandidateScoreVc"},{"type":"null"}]}}},"CandidateScoreVc":{"type":"object","additionalProperties":false,"required":["sha256","statusUrl","statusListCredential"],"properties":{"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"statusUrl":{"type":["string","null"]},"statusListCredential":{"type":["string","null"]}}},"CandidateSkill":{"type":"object","additionalProperties":false,"required":["name","verified","level"],"properties":{"name":{"type":"string"},"verified":{"type":"boolean"},"level":{"type":["string","null"]}}},"EngineDiscovery":{"type":"object","additionalProperties":true,"required":["schema_version","issuer","standard","engine","score_vc"],"properties":{"schema_version":{"const":"humanproof.engine_discovery.v1"},"issuer":{"type":"string"},"standard":{"type":"object","additionalProperties":true},"engine":{"type":"object","additionalProperties":true},"score_vc":{"type":"object","additionalProperties":true}}},"ScoreCoreReleaseManifest":{"type":"object","additionalProperties":true,"required":["schema_version","generated_at","engine","binary","release"],"properties":{"schema_version":{"const":"humanproof.score_core.release_manifest.v1"},"generated_at":{"type":"string","format":"date-time"},"engine":{"type":"object","additionalProperties":true},"binary":{"type":"object","additionalProperties":true},"release":{"type":"object","additionalProperties":true},"content_hashes":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}}