REST API v2.1

AssurAI API Reference

Programmatic access to risks, controls, workpapers, evidence, audit plans, and users — all scoped to your organization. Authenticate with an API key and query or write data using standard HTTP.

Get API Key Browse Endpoints

Endpoints

SDKs

v2.1

Version

99.9%

Uptime

API calls — last 14 days

Acme Corp · ak_live_••••••••3f2a

+18% vs prior period

Authentication

Every request must carry a valid API key. Pass it as a Bearer token or via the x-api-key header. Keys are org-scoped — you can only read and write your own org's data. Generate and revoke keys in Settings → Enterprise API.

Your API key

ak_live_••••••••••••••••••••••••3f2a

Bearer token header

HTTP

Authorization: Bearer ak_live_acmecorp_demo_3f2a

x-api-key header (alternative)

HTTP

x-api-key: ak_live_acmecorp_demo_3f2a

Key scopes

read — all GET endpoints write — create + update operations admin — user management, key provisioning

Risks

Read and manage risk register entries

5 endpoints

GET /api/v2.1/risks List risks with optional filters

Query parameters

Param	Type		Description
status	string	opt	open · mitigated · accepted · closed
severity	string	opt	Critical · High · Medium · Low
category	string	opt	Operational · Financial · Compliance
limit	integer	opt	Max 200, default 50
offset	integer	opt	Records to skip, default 0

Example request

cURL

curl "https://getassurai.com/api/v2.1/risks?status=open&severity=Critical" \
  -H "x-api-key: ak_live_acmecorp_demo_3f2a"

Response 200

JSON

{
  "data": [{
    "id": "r_9f2e4a",
    "title": "Unpatched ERP system (SAP)",
    "severity": "Critical",
    "status": "open",
    "owner": "j.martinez@acmecorp.com"
  }],
  "meta": { "limit": 50, "offset": 0, "count": 14 }
}

GET /api/v2.1/risks/{id} Retrieve a single risk

Path parameters

Param	Type		Description
id	string	req	Risk UUID or short ID (e.g. r_9f2e4a)

Example request

cURL

curl "https://getassurai.com/api/v2.1/risks/r_9f2e4a" \
  -H "x-api-key: ak_live_acmecorp_demo_3f2a"

POST /api/v2.1/risks Create a new risk

write

Body fields

Field	Type		Description
title	string	req	Short risk description
severity	string	opt	Critical · High · Medium · Low
category	string	opt	Operational · Financial · Compliance
owner	string	opt	Assignee email
due_date	date	opt	ISO 8601 date string
likelihood	integer	opt	1–5 scale
impact	integer	opt	1–5 scale

Example request

cURL

curl -X POST "https://getassurai.com/api/v2.1/risks" \
  -H "x-api-key: ak_live_acmecorp_demo_3f2a" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Vendor SLA breach risk — Tier 1",
    "severity": "High",
    "category": "Operational",
    "owner": "l.chen@acmecorp.com",
    "likelihood": 3,
    "impact": 4
  }'

Response 201

JSON

{ "data": {
  "id": "r_c1d82f",
  "title": "Vendor SLA breach risk — Tier 1",
  "severity": "High",
  "status": "open"
}}

PUT /api/v2.1/risks/{id} Update a risk

write

All body fields from POST are accepted. Only supplied fields are updated (partial update).

cURL

curl -X PUT "https://getassurai.com/api/v2.1/risks/r_c1d82f" \
  -H "x-api-key: ak_live_acmecorp_demo_3f2a" \
  -H "Content-Type: application/json" \
  -d '{ "status": "mitigated" }'

DELETE /api/v2.1/risks/{id} Delete a risk

write

Returns 204 No Content on success. This operation is irreversible.

Controls

Read and manage control library entries

4 endpoints

GET /api/v2.1/controls List controls

Query parameters

Param	Type		Description
status	string	opt	effective · deficient · not_tested
framework	string	opt	SOX · SOC2 · ISO27001 · NIST
limit	integer	opt	Max 200, default 50

Example response

JSON

{ "data": [{
  "id": "c_4a19bd",
  "name": "Logical access review — quarterly",
  "status": "effective",
  "framework": "SOX",
  "control_id": "ITGC-04"
}], "meta": { "count": 42 }}

GET /api/v2.1/controls/{id} Get a single control

Returns full control detail including linked test procedures and workpapers.

POST /api/v2.1/controls Create a control

write

Required: name, framework. Optional: description, owner, frequency, control_type.

PUT /api/v2.1/controls/{id} Update a control

write

Partial update — only supplied fields are changed. Returns the updated control object.

Workpapers

Access and create audit workpapers

4 endpoints

GET /api/v2.1/workpapers List workpapers

Query parameters

Param	Type		Description
status	string	opt	draft · in_review · approved · signed_off
prepared_by	string	opt	Filter by preparer email
project_id	string	opt	Filter by audit project UUID

Example response

JSON

{ "data": [{
  "id": "wp_7b3e1c",
  "title": "AP Cutoff Testing Q2",
  "status": "in_review",
  "prepared_by": "r.patel@acmecorp.com"
}]}

GET /api/v2.1/workpapers/{id} Get workpaper detail

Returns full workpaper with body, review history, and linked evidence items.

POST /api/v2.1/workpapers Create a workpaper

write

Required: title. Optional: body (markdown), project_id, control_id, prepared_by, status.

PUT /api/v2.1/workpapers/{id} Update workpaper status or body

write

Partial update. Advancing status from draft → in_review notifies assigned reviewers.

Evidence

Upload and retrieve supporting evidence files

3 endpoints

GET /api/v2.1/evidence List evidence items

Query parameters

Param	Type		Description
workpaper_id	string	opt	Filter by parent workpaper
file_type	string	opt	pdf · xlsx · csv · png · jpg

POST /api/v2.1/evidence Upload evidence file

write

Send as multipart/form-data. Max file size 50 MB. Accepted: PDF, XLSX, CSV, PNG, JPG.

cURL

curl -X POST "https://getassurai.com/api/v2.1/evidence" \
  -H "x-api-key: ak_live_acmecorp_demo_3f2a" \
  -F "file=@access_review_q2_2026.xlsx" \
  -F "workpaper_id=wp_7b3e1c" \
  -F "label=Q2 Access Review Export"

DELETE /api/v2.1/evidence/{id} Delete an evidence item

write

Returns 204 No Content. The underlying file is permanently removed from storage.

Audit Plans

Create and manage audit engagements

4 endpoints

GET /api/v2.1/audit-plans List audit plans

Query parameters

Param	Type		Description
fiscal_year	integer	opt	e.g. 2026
status	string	opt	planning · in_progress · completed

Example response

JSON

{ "data": [{
  "id": "ap_2a7fc9",
  "name": "FY2026 SOX Walkthrough",
  "fiscal_year": 2026,
  "status": "in_progress"
}]}

GET /api/v2.1/audit-plans/{id} Get audit plan detail

Returns plan metadata plus a list of linked controls and workpapers.

POST /api/v2.1/audit-plans Create an audit plan

write

Required: name. Optional: fiscal_year, start_date, end_date, lead_auditor, description.

PUT /api/v2.1/audit-plans/{id} Update an audit plan

write

Partial update. Advancing status to completed locks the plan for further edits.

Users

List org members and manage invitations

4 endpoints

GET /api/v2.1/users List org members

Query parameters

Param	Type		Description
role	string	opt	admin · auditor · reviewer · viewer
status	string	opt	active · invited · suspended

Example response

JSON

{ "data": [{
  "id": "u_d4f81a",
  "email": "j.martinez@acmecorp.com",
  "role": "auditor",
  "status": "active"
}]}

GET /api/v2.1/users/{id} Get user profile

Returns profile including role, joined date, and last-active timestamp.

POST /api/v2.1/users/invite Invite a new member

admin

Body fields

Field	Type		Description
email	string	req	Invitee email address
role	string	req	admin · auditor · reviewer · viewer
message	string	opt	Custom invite message

Example request

cURL

curl -X POST "https://getassurai.com/api/v2.1/users/invite" \
  -H "x-api-key: ak_live_acmecorp_demo_3f2a" \
  -H "Content-Type: application/json" \
  -d '{ "email": "new.hire@acmecorp.com", "role": "auditor" }'

DELETE /api/v2.1/users/{id} Remove a user from the org

admin

Removes the user from your org. Their data (workpapers, evidence) is preserved. Returns 204 No Content.

Errors

HTTP status codes returned by the API

Status	Meaning
200	OK — list or read succeeded
201	Created — POST succeeded
204	No Content — DELETE succeeded
400	Invalid request body or missing required field
401	Missing, malformed, or revoked API key
403	Key lacks the required scope for this operation
404	Resource not found or not in your org
429	Rate limit exceeded — 1,000 requests/hour per key
5xx	Internal error — retry with exponential backoff

Pagination

All list endpoints use limit/offset

Pass limit (max 200, default 50) and offset as query params. Every list response includes a meta envelope:

JSON

{
  "data": [ /* records */ ],
  "meta": {
    "limit": 50,
    "offset": 0,
    "count": 142  // total matching records
  }
}

Rate Limits

Per-key rolling window

Each API key is limited to 1,000 requests per hour (rolling 60-minute window). Exceeding the limit returns 429 Too Many Requests. Keys do not share a budget. Retry with exponential backoff and respect the Retry-After header.

AssurAI API Reference

Authentication

Risks

Controls

Workpapers

Evidence

Audit Plans

Users

Errors

Pagination

Rate Limits

List Risks