Create and start an assessment

POST 
/api/v1/assessments

Create an assessment and immediately spawn its workflow agent.

Admission is checked before any credit spend so gated workflows 400 cleanly. Credits are atomically deducted, the assessment record is created, and the workflow agent is spawned via the internal RPC. On any failure after credits are spent, they are refunded.

• Scope required: assessments:create + manager-or-above role.
• Rate-limit tier: assessment_create (100/hour/user).
• For source-code assessments use the draft flow (POST /drafts → upload → POST /drafts/{id}/start) instead.

Request

Responses

200

Successful Response

400

Bad request — malformed input or failed validation.

401

Missing, expired, or invalid credentials.

403

Authenticated but not authorized for this resource. Note: cross-organization reads return 404, not 403.

404

Resource not found, or hidden for tenant-enumeration safety (the caller lacks permission to know whether the resource exists).

409

Conflict — the current resource state does not allow this operation (e.g. assessment already started, email already in use).

422

Semantic validation failure — request shape was valid but contents were not.

429

Too many requests — rate limited. Retry after the window resets.

500

Internal server error — unexpected failure.