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
| Method | Path | Auth | Scope | Summary |
|---|---|---|---|---|
| POST | /api/v1/score | Staff session or API key | score:run | Score a JSON body and return an Actuarial Signal Report. |
| GET | /api/v1/score/[id] | Staff session or API key | score:read | Fetch one report belonging to the caller organization. |
| GET | /api/v1/audit | Staff session or API key | audit:read | List the newest audit events of the caller organization. |
| GET | /api/v1/keys | Staff session | None | List key metadata. An admin sees every key; other staff see keys they issued. |
| POST | /api/v1/keys | Staff session | None | Issue a key. The plaintext is in this response only. |
| DELETE | /api/v1/keys/[id] | Staff session | None | Revoke 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.
| Field | Type | Rule |
|---|---|---|
| edr_coverage | number | Optional. 0 to 1 inclusive. |
| mfa_adoption | number | Optional. 0 to 1 inclusive. |
| patch_cadence_days | number | Optional. 0 to 365 inclusive. |
| external_hygiene | number | Optional. 0 to 1 inclusive. |
| vuln_density | number | Optional. 0 to 1 inclusive. |
| industry | string | Optional. 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.
| Field | Type | Rule |
|---|---|---|
| actuarial_risk_score | number | 300 to 850 inclusive. |
| expected_loss_index | string | Non-empty string. |
| confidence_level | string | Non-empty string. |
| peer_benchmark_percentile | string | Non-empty string. |
| key_strengths | string[] | Array of strings. |
| key_weaknesses | string[] | Array of strings. |
| loss_event_frequency_index | number | 0 to 1 inclusive. |
| loss_event_severity_index | number | 0 to 1 inclusive. |
| incentive_recommendation | boolean | Boolean. |
| report_id | string | Non-empty string. |
| model_version | string | Non-empty string. |
| schema_version | string | The literal v1. |
| Status | code | When |
|---|---|---|
| 401 | unauthorized | No staff session, or the presented API key is rejected. |
| 403 | forbidden | The API key does not include the route scope. |
| 429 | rate_limited | A staff or key call exceeds its caller or IP limit. |
| 503 | rate_limit_unavailable | The rate-limit store is missing or a partner limiter cannot decide. Retry-After is included. |
| 400 | validation_failed | Invalid JSON or request fields; errors contains JSON pointers. |
| 413 | payload_too_large | POST body exceeds the size limit. |
| 415 | unsupported_media_type | POST body is not application/json. |
| 409 | conflict | An idempotent request is still in progress; retry later. |
| 422 | idempotency_key_reuse | Idempotency-Key was reused for a different request. |
| 500 | internal | An unexpected runtime or storage failure occurs. |
| 500 | score_failed | Scoring or persistence throws. |
| 404 | not_found | GET 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.
| Field | Type | Rule |
|---|---|---|
| id | metadata | Key id. This is the [id] segment of the revoke route. |
| organizationId | metadata | Organization the key acts for. |
| name | metadata | Label supplied when the key was issued. |
| prefix | metadata | First characters of the plaintext, for display. |
| scopes | metadata | Granted scopes. |
| createdAt | metadata | When the key was issued. |
| expiresAt | metadata | When the key stops authenticating. |
| lastUsedAt | metadata | Last successful use, or null. |
| revokedAt | metadata | When 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.
| Field | Type | Rule |
|---|---|---|
| name | string | Required. Trimmed, 1 to 100 characters. |
| organizationId | string | Optional partner organization ID. Must match the selected organization. Omitted means the selected organization; key management requires its admin role. |
| scopes | string[] | Optional. A non-empty subset of score:run and score:read. Omitted grants both. |
| expiresInDays | number | Optional integer from 1 to 365. Omitted means 90 days. |
| Status | code | When |
|---|---|---|
| 401 | unauthorized | No staff session. An API key is not accepted here. |
| 403 | forbidden | POST set organizationId and the session is not an admin. |
| 400 | validation_failed | Invalid JSON or request fields; errors contains JSON pointers. |
| 413 | payload_too_large | POST body exceeds the size limit. |
| 415 | unsupported_media_type | POST body is not application/json. |
| 409 | conflict | An idempotent request is still in progress; retry later. |
| 422 | idempotency_key_reuse | Idempotency-Key was reused for a different request. |
| 500 | internal | An unexpected runtime or storage failure occurs. |
| 429 | rate_limited | Staff caller or IP ceiling exceeded; Retry-After included. |
| 503 | rate_limit_unavailable | Missing rate-limit store; Retry-After included. |
| 500 | key_create_failed | POST could not store the key. |
| 404 | not_found | DELETE found no active key for that id that this caller may revoke. |
New partner? Follow the quick start. Questions about access: contact the team.