Create Risk Assessment Job

POST /api/v1/analysis/risk

Submits a fast risk-assessment job for a blob of text. Use this when you need a quick numeric compliance signal — for routing, gating, triage, or scoring — without the full finding-and-citation payload returned by Create Screen Analysis Job.

Unlike screen analysis, risk assessment returns its result inline on the submit response when the job completes synchronously. The same envelope can also be fetched later through the Get Job.

Submit a Risk Assessment Job

Request Body

{
  "content": {
    "type": "text",
    "text": "we can't provide a provisional dispute credit until the investigation is completed"
  },
  "scenario": "dispute"
}

Fields

Name	Type	Required	Description
content.type	string	yes	Content type. v1 supports text.
content.text	string	yes	Text to score for compliance risk. Min 1 character.
scenario	string	yes	One of the scenario enum values. Selects the screening context the backend uses.

Scenario Enum

Same scenario values as Create Screen Analysis Job:

Value	Use for
marketing_asset	Outbound promotional content
dispute	Transaction or billing error handling
debt_collection	Collections communications
complaint	Responses to consumer complaints
generic	Anything that does not fit the specialized buckets above

Response

Returns 200 OK with the terminal job envelope. The type discriminator is always risk_assessment.

Succeeded

{
  "id": "job_01HY3K4M7QR9VP2N8WYJF5GTB",
  "type": "risk_assessment",
  "status": "succeeded",
  "result": {
    "type": "analysis.risk.result",
    "riskScore": 72
  },
  "error": null
}

Failed

{
  "id": "job_01HY3K4M7QR9VP2N8WYJF5GTB",
  "type": "risk_assessment",
  "status": "failed",
  "result": null,
  "error": {
    "code": "analysis_failed",
    "message": "Risk assessment could not be completed."
  }
}

Risk Assessment Result

For the reusable object reference, see The Risk Assessment Result Object.

Field	Type	Description
type	string	Result discriminator. Always analysis.risk.result.
riskScore	integer	Overall compliance risk score (0–100). 0–20: Limited. 21–40: Low. 41–60: Moderate. 61–80: High. 81–100: Critical.

Rate Limits

Submit calls are rate-limited per API key. If the caller exceeds the limit, the endpoint responds with 429 rate_limit_exceeded and a Retry-After header. See Errors for the shared error envelope.

Retrieve a Risk Assessment Job

GET /api/v1/jobs/{id}

The same id returned on submit can be re-fetched through the Get Job. The response envelope is identical to the submit response, with the standard running / succeeded / failed status lifecycle and createdAt / updatedAt timestamps.

When to use risk vs. screen

• Risk Assessment — fast numeric score only; ideal for gating, triage, routing, and high-volume scoring.
• Screen Analysis — full prioritized findings with regulatory citations; ideal for human review, redlines, and audit trails.