Get an assessment

GET /v1/assess/:request_id returns a previously stored assessment by its request_id. Use it for async webhook workflows, audit logs, or to display an assessment in your own admin UI without re-running the scorer.

This endpoint does not deduct quota.

Endpoint

GET https://api.shieldsignup.com/v1/assess/{request_id}

Authentication

Bearer token in the Authorization header. See Authentication.

Path parameters

Parameter	Type	Required	Description
`request_id`	string	Yes	The `request_id` returned from a prior `POST /v1/assess` call (prefix `req_`).

Request example

curl https://api.shieldsignup.com/v1/assess/req_01hw5k3mfvx8t2b4ncqw7ydpej \
  -H "Authorization: Bearer ${SHIELDSIGNUP_API_KEY}"

const res = await fetch(
  `https://api.shieldsignup.com/v1/assess/${requestId}`,
  {
    headers: {
      "Authorization": `Bearer ${process.env.SHIELDSIGNUP_API_KEY}`,
    },
    signal: AbortSignal.timeout(3000),
  },
);

if (!res.ok) {
  // 400 missing_field — unknown request_id
  // 401 unauthorized — bad key
  throw new Error(`Assessment lookup failed: ${res.status}`);
}

const assessment = await res.json();

Response

200 OK with the same body shape as POST /v1/assess.

{
  "request_id": "req_01hw5k3mfvx8t2b4ncqw7ydpej",
  "verdict": "block",
  "score": 91,
  "reasons": [...],
  "ip_provided": true,
  "ip_status": "ok",
  "signals": { ... },
  "processed_ms": 18,
  "assessed_at": "2026-05-10T10:14:33Z"
}

Errors

HTTP	`error.code`	Meaning
`400`	`missing_field`	The `request_id` is empty or unknown.
`401`	`unauthorized`	Missing or invalid API key.
`500`	`internal_error`	Database lookup failed. Retry after a short delay.

The full error envelope is documented in Errors.