Skip to main content
DRiCE™

Docs

API overview

This page lists the DRiCE v1 handlers as implemented. The origin is https://drice.wentzel.ai. Request bodies are parsed as JSON. The active score model writes v0-unvalidated on model_version and returns incentive_recommendation false. A sample report for the score form defaults is on the product page.

Authentication

Score routes accept a staff session cookie or a partner API key. Send the key as Authorization: Bearer <key> or X-API-Key: <key>. When both are present, Authorization is the one that is read. A presented key that does not authenticate returns 401. The handler does not fall back to the session cookie.

A key is drk_ followed by 64 lowercase hex characters. Only a SHA-256 hash is stored. The plaintext is returned once, by the create-key response, which sets Cache-Control: no-store.

Key list, create, and revoke accept a staff session only. An API key cannot manage keys. Score scope for a key is score:run on POST score and score:read on GET score. A key without that scope receives 403 forbidden.

Partner score calls allow 120 calls per client IP and 60 calls per key, each per 60 seconds. The IP limit runs before the key is looked up. Staff-session calls have a ceiling of 10000 calls per caller and per client IP in the same window. Both use a persistent rate-limit store. A refused call returns 429 rate_limited. A missing store returns 503 rate_limit_unavailable; both include Retry-After in seconds. A partner limiter that cannot decide also returns 503 with Retry-After. Wait before retrying.

Endpoints

Endpoints
MethodPathAuthScopeSummary
POST/api/v1/scoreStaff session or API keyscore:runScore a JSON body and return an Actuarial Signal Report.
GET/api/v1/score/[id]Staff session or API keyscore:readFetch one report belonging to the caller organization.
GET/api/v1/auditStaff session or API keyaudit:readList the newest audit events of the caller organization.
GET/api/v1/keysStaff sessionNoneList key metadata. An admin sees every key; other staff see keys they issued.
POST/api/v1/keysStaff sessionNoneIssue a key. The plaintext is in this response only.
DELETE/api/v1/keys/[id]Staff sessionNoneRevoke one key. An admin may revoke any key; other staff, only a key they issued.

Score request

POST /api/v1/score takes a ScoreInputV1 body. A valid body returns 200 with the report. Errors use application/problem+json with type, title, status, code, and instance (request id), plus optional detail. Invalid JSON or schema input returns 400 validation_failed with errors: an array of pointer, detail, and optional code. Pointers identify request fields, such as /body/mfa_adoption. Malformed JSON points to /body with field code invalid_json.

Score request fields
FieldTypeRule
edr_coveragenumberOptional. 0 to 1 inclusive.
mfa_adoptionnumberOptional. 0 to 1 inclusive.
patch_cadence_daysnumberOptional. 0 to 365 inclusive.
external_hygienenumberOptional. 0 to 1 inclusive.
vuln_densitynumberOptional. 0 to 1 inclusive.
industrystringOptional. At most 64 characters.

Score response

POST score and GET /api/v1/score/[id] return an ActuarialSignalReportV1 object. GET returns 404 not_found when the id is missing or owned by another organization.

Score response fields
FieldTypeRule
actuarial_risk_scorenumber300 to 850 inclusive.
expected_loss_indexstringNon-empty string.
confidence_levelstringNon-empty string.
peer_benchmark_percentilestringNon-empty string.
key_strengthsstring[]Array of strings.
key_weaknessesstring[]Array of strings.
loss_event_frequency_indexnumber0 to 1 inclusive.
loss_event_severity_indexnumber0 to 1 inclusive.
incentive_recommendationbooleanBoolean.
report_idstringNon-empty string.
model_versionstringNon-empty string.
schema_versionstringThe literal v1.
Score errors
StatuscodeWhen
401unauthorizedNo staff session, or the presented API key is rejected.
403forbiddenThe API key does not include the route scope.
429rate_limitedA staff or key call exceeds its caller or IP limit.
503rate_limit_unavailableThe rate-limit store is missing or a partner limiter cannot decide. Retry-After is included.
400validation_failedInvalid JSON or request fields; errors contains JSON pointers.
413payload_too_largePOST body exceeds the size limit.
415unsupported_media_typePOST body is not application/json.
409conflictAn idempotent request is still in progress; retry later.
422idempotency_key_reuseIdempotency-Key was reused for a different request.
500internalAn unexpected runtime or storage failure occurs.
500score_failedScoring or persistence throws.
404not_foundGET only. The report is missing or belongs to another organization.

API keys

GET /api/v1/keys returns 200 { keys }. The list is newest first and includes revoked and expired keys. Each item has the metadata fields below and not the hash or the plaintext.

Key metadata fields
FieldTypeRule
idmetadataKey id. This is the [id] segment of the revoke route.
organizationIdmetadataOrganization the key acts for.
namemetadataLabel supplied when the key was issued.
prefixmetadataFirst characters of the plaintext, for display.
scopesmetadataGranted scopes.
createdAtmetadataWhen the key was issued.
expiresAtmetadataWhen the key stops authenticating.
lastUsedAtmetadataLast successful use, or null.
revokedAtmetadataWhen the key was revoked, or null.

POST /api/v1/keys returns 201 { key, plaintext } with Cache-Control: no-store. Default lifetime is 90 days. The longest lifetime is 365 days. DELETE /api/v1/keys/[id] returns 200 { revoked: true }. Unknown, already revoked, and issued-by-someone-else are all 404 not_found.

Create key fields
FieldTypeRule
namestringRequired. Trimmed, 1 to 100 characters.
organizationIdstringOptional partner organization ID. Must match the selected organization. Omitted means the selected organization; key management requires its admin role.
scopesstring[]Optional. A non-empty subset of score:run and score:read. Omitted grants both.
expiresInDaysnumberOptional integer from 1 to 365. Omitted means 90 days.
Key errors
StatuscodeWhen
401unauthorizedNo staff session. An API key is not accepted here.
403forbiddenPOST set organizationId and the session is not an admin.
400validation_failedInvalid JSON or request fields; errors contains JSON pointers.
413payload_too_largePOST body exceeds the size limit.
415unsupported_media_typePOST body is not application/json.
409conflictAn idempotent request is still in progress; retry later.
422idempotency_key_reuseIdempotency-Key was reused for a different request.
500internalAn unexpected runtime or storage failure occurs.
429rate_limitedStaff caller or IP ceiling exceeded; Retry-After included.
503rate_limit_unavailableMissing rate-limit store; Retry-After included.
500key_create_failedPOST could not store the key.
404not_foundDELETE found no active key for that id that this caller may revoke.

New partner? Follow the quick start. Questions about access: contact the team.