Audits and violations

Read the results of compliance audits and record review decisions. Every decision follows the same rules as the Typetone app and shows up in the audit's activity trail.

Endpoints

GET /v1/audits List audits
GET /v1/audits/{audit_id}/violations List violations
GET /v1/violations/{violation_id} Get a violation
POST /v1/violations/{violation_id}/review Review a violation
POST /v1/violations/{violation_id}/comments Comment on a violation

List audits

GET api.app.typetone.ai/public/v1/audits

Returns the workspace's compliance audits, newest first, with a violation count for each.

Authorization

X-API-Keyheaderrequired
Your workspace API key.

Query parameters

limitintegerdefault 20
Maximum number of results.

Response · 200

auditsarray of Auditrequired
The audits, newest first.
returnedintegerrequired
Number of items in this response.
limitintegerrequired
Maximum number of results.

Errors

401 Missing or invalid API key.
403 The workspace is not on a plan with API access.
404 The resource does not exist in this workspace.
422 A parameter or the request body is invalid. detail says which.

curl "https://api.app.typetone.ai/public/v1/audits?limit=20" \
  -H "X-API-Key: $TYPETONE_API_KEY"

import os
import requests

response = requests.get(
    "https://api.app.typetone.ai/public/v1/audits?limit=20",
    headers={"X-API-Key": os.environ["TYPETONE_API_KEY"]},
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.app.typetone.ai/public/v1/audits?limit=20", {
  headers: {
    "X-API-Key": process.env.TYPETONE_API_KEY,
  },
});
const data = await response.json();

Response · 200

{
  "audits": [
    {
      "id": "cmuf2k8x10001ab12cd34ef56",
      "name": "Homepage audit",
      "status": "COMPLETED",
      "created_at": "2026-09-24T09:30:00Z",
      "completed_at": "2026-09-24T09:42:00Z",
      "total_assets": 42,
      "completed_assets": 3,
      "failed_assets": 3,
      "total_violations": 42
    }
  ],
  "returned": 3,
  "limit": 3
}

List violations

GET api.app.typetone.ai/public/v1/audits/{audit_id}/violations

Pages through the violations of one audit. By default it returns open violations nobody has decided on yet (review_state=undecided), so a reviewer can work through the queue. review_progress counts every state for the whole audit.

Authorization

X-API-Keyheaderrequired
Your workspace API key.

Path parameters

audit_idstringrequired
ID of the audit, from List audits.

Query parameters

review_statestring
undecided, elevated_risk, urgent_violation, dismissed or fixed. As a filter, all returns every state.
One ofundecidedelevated_riskurgent_violationdismissedfixedall
severitystring | null
Severity of the rule: CRITICAL, HIGH, MEDIUM, LOW or UNSPECIFIED.
One ofUNSPECIFIEDLOWMEDIUMHIGHCRITICAL
searchstring | null
Only violations whose text, reason or rule name contains this term.
pageintegerdefault 1
Page number, starting at 1.
page_sizeintegerdefault 20
Results per page.

Response · 200

audit_idstringrequired
ID of the audit, from List audits.
violationsarray of Violationrequired
The violations on this page.
totalintegerrequired
Total number of matching violations.
pageintegerrequired
Page number, starting at 1.
page_sizeintegerrequired
Results per page.
has_morebooleanrequired
Whether there is another page.
review_progressReviewProgressrequired
How many violations of the whole audit are in each review state.

Errors

401 Missing or invalid API key.
403 The workspace is not on a plan with API access.
404 The resource does not exist in this workspace.
422 A parameter or the request body is invalid. detail says which.

curl "https://api.app.typetone.ai/public/v1/audits/cmrl4bksl5wtt78geytff18uw/violations?review_state=string&page_size=20" \
  -H "X-API-Key: $TYPETONE_API_KEY"

import os
import requests

response = requests.get(
    "https://api.app.typetone.ai/public/v1/audits/cmrl4bksl5wtt78geytff18uw/violations?review_state=string&page_size=20",
    headers={"X-API-Key": os.environ["TYPETONE_API_KEY"]},
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.app.typetone.ai/public/v1/audits/cmrl4bksl5wtt78geytff18uw/violations?review_state=string&page_size=20", {
  headers: {
    "X-API-Key": process.env.TYPETONE_API_KEY,
  },
});
const data = await response.json();

Response · 200

{
  "audit_id": "cmrl4bksl5wtt78geytff18uw",
  "violations": [
    {
      "id": "cmuf2k8x10001ab12cd34ef56",
      "audit_id": "cmrl4bksl5wtt78geytff18uw",
      "review_state": "undecided",
      "severity": "HIGH",
      "rule_id": "cmoa6kg13yytl58gel3vakaxy",
      "rule_name": "No guaranteed returns",
      "asset_id": "cmrl4apwj5wtdllge0x59w6v2",
      "asset_name": "Savings account landing page",
      "asset_url": "https://www.example.com/savings",
      "violating_text": "Guaranteed 8% return, every year.",
      "reason": "The copy promises a guaranteed return, which is misleading for an investment product.",
      "recommended_solution": "Remove the guarantee and state that returns can vary.",
      "suggested_text": "Target return of 8% a year. Returns are not guaranteed.",
      "dismissal_reason": null,
      "group_id": "cmrl4g2b75wv1jfge9hx0p2kd",
      "assigned_to_user_ids": [
        "cmuf2k8x10001ab12cd34ef56"
      ]
    }
  ],
  "total": 42,
  "page": 1,
  "page_size": 20,
  "has_more": false,
  "review_progress": {
    "undecided": 3,
    "elevated_risk": 3,
    "urgent_violation": 3,
    "dismissed": 3,
    "fixed": 3
  }
}

Get a violation

GET api.app.typetone.ai/public/v1/violations/{violation_id}

Everything a reviewer needs to decide: the flagged text, why it was flagged, the rule, the recommended fix, suggested replacement text and the comment thread.

Authorization

X-API-Keyheaderrequired
Your workspace API key.

Path parameters

violation_idstringrequired
ID of the violation, from List violations.

Response · 200

idstringrequired
Unique ID.
audit_idstring | nullrequired
ID of the audit, from List audits.
review_statestringrequired
undecided, elevated_risk, urgent_violation, dismissed or fixed. As a filter, all returns every state.
One ofundecidedelevated_riskurgent_violationdismissedfixed
severitystring | nullrequired
Severity of the rule: CRITICAL, HIGH, MEDIUM, LOW or UNSPECIFIED.
rule_idstring | nullrequired
The rule the violation breaks.
rule_namestring | nullrequired
Name of the rule.
asset_idstring | nullrequired
The asset (web page, document or post) the violation was found on.
asset_namestring | nullrequired
Name of the asset.
asset_urlstring | nullrequired
URL or identifier of the asset.
violating_textstring | nullrequired
The text on the asset that triggered the violation.
reasonstringrequired
Why the audit flagged this text.
recommended_solutionstring | nullrequired
How to fix the violation.
suggested_textstring | nullrequired
Replacement text that would fix the violation, when the audit could suggest one.
dismissal_reasonstring | nullrequired
Why the violation was dismissed, when it was.
group_idstring | nullrequired
Violations with the same group_id are the same finding on several assets; review them together with apply_to_group.
assigned_to_user_idsarray of stringrequired
Users the violation is assigned to in the app.
rule_descriptionstring | nullrequired
What the rule checks.
rule_explanationstring | nullrequired
Background on the rule, such as the regulation behind it.
commentsarray of ViolationCommentrequired
The comment thread, oldest first.

Errors

401 Missing or invalid API key.
403 The workspace is not on a plan with API access.
404 The resource does not exist in this workspace.
422 A parameter or the request body is invalid. detail says which.

curl "https://api.app.typetone.ai/public/v1/violations/cmrl4efwd5wu8jfgepgjbxam6" \
  -H "X-API-Key: $TYPETONE_API_KEY"

import os
import requests

response = requests.get(
    "https://api.app.typetone.ai/public/v1/violations/cmrl4efwd5wu8jfgepgjbxam6",
    headers={"X-API-Key": os.environ["TYPETONE_API_KEY"]},
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.app.typetone.ai/public/v1/violations/cmrl4efwd5wu8jfgepgjbxam6", {
  headers: {
    "X-API-Key": process.env.TYPETONE_API_KEY,
  },
});
const data = await response.json();

Response · 200

{
  "id": "cmuf2k8x10001ab12cd34ef56",
  "audit_id": "cmrl4bksl5wtt78geytff18uw",
  "review_state": "undecided",
  "severity": "HIGH",
  "rule_id": "cmoa6kg13yytl58gel3vakaxy",
  "rule_name": "No guaranteed returns",
  "asset_id": "cmrl4apwj5wtdllge0x59w6v2",
  "asset_name": "Savings account landing page",
  "asset_url": "https://www.example.com/savings",
  "violating_text": "Guaranteed 8% return, every year.",
  "reason": "The copy promises a guaranteed return, which is misleading for an investment product.",
  "recommended_solution": "Remove the guarantee and state that returns can vary.",
  "suggested_text": "Target return of 8% a year. Returns are not guaranteed.",
  "dismissal_reason": null,
  "group_id": "cmrl4g2b75wv1jfge9hx0p2kd",
  "assigned_to_user_ids": [
    "cmuf2k8x10001ab12cd34ef56"
  ],
  "rule_description": "string",
  "rule_explanation": "string",
  "comments": [
    {
      "id": "cmuf2k8x10001ab12cd34ef56",
      "author_email": "reviewer@example.com",
      "content": "Checked with legal: fix before Friday.",
      "created_at": "2026-09-24T09:30:00Z"
    }
  ]
}

Review a violation

POST api.app.typetone.ai/public/v1/violations/{violation_id}/review

Records a review decision. dismiss needs a reason; the other actions don't take one (add a comment instead). Set apply_to_group to apply the decision to every violation with the same group_id: the same finding on several assets.

Authorization

X-API-Keyheaderrequired
Your workspace API key.

Path parameters

violation_idstringrequired
ID of the violation, from List violations.

Request body

actionstringrequired
The decision: dismiss, elevated_risk, urgent_violation, mark_fixed or reopen.
One ofdismisselevated_riskurgent_violationmark_fixedreopen
reasonstring | null
Required for, and only accepted with, action 'dismiss'.
apply_to_groupbooleandefault false
Apply the same decision to every violation with the same group_id.

Response · 200

violation_idstringrequired
ID of the violation, from List violations.
actionstringrequired
The decision: dismiss, elevated_risk, urgent_violation, mark_fixed or reopen.
One ofdismisselevated_riskurgent_violationmark_fixedreopen
review_statestringrequired
undecided, elevated_risk, urgent_violation, dismissed or fixed. As a filter, all returns every state.
One ofundecidedelevated_riskurgent_violationdismissedfixed
violations_updatedintegerrequired
How many violations the decision was applied to (more than one with apply_to_group).

Errors

401 Missing or invalid API key.
403 The workspace is not on a plan with API access.
404 The resource does not exist in this workspace.
422 A parameter or the request body is invalid. detail says which.

curl -X POST "https://api.app.typetone.ai/public/v1/violations/cmrl4efwd5wu8jfgepgjbxam6/review" \
  -H "X-API-Key: $TYPETONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "urgent_violation",
    "apply_to_group": false
  }'

import os
import requests

response = requests.post(
    "https://api.app.typetone.ai/public/v1/violations/cmrl4efwd5wu8jfgepgjbxam6/review",
    headers={"X-API-Key": os.environ["TYPETONE_API_KEY"]},
    json={
      "action": "urgent_violation",
      "apply_to_group": False
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.app.typetone.ai/public/v1/violations/cmrl4efwd5wu8jfgepgjbxam6/review", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.TYPETONE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "action": "urgent_violation",
    "apply_to_group": false
  }),
});
const data = await response.json();

Response · 200

{
  "violation_id": "cmrl4efwd5wu8jfgepgjbxam6",
  "action": "dismiss",
  "review_state": "undecided",
  "violations_updated": 3
}

Comment on a violation

POST api.app.typetone.ai/public/v1/violations/{violation_id}/comments

Adds a comment to the violation's thread. Mentions in the comment don't assign the violation or notify anyone.

Authorization

X-API-Keyheaderrequired
Your workspace API key.

Path parameters

violation_idstringrequired
ID of the violation, from List violations.

Request body

commentstringrequired
The comment text, up to 5,000 characters.

Response · 201

idstringrequired
Unique ID.
author_emailstring | nullrequired
Email of the person who wrote the comment, when they belong to your workspace.
contentstringrequired
created_atdatetimerequired
When it was created.

Errors

401 Missing or invalid API key.
403 The workspace is not on a plan with API access.
404 The resource does not exist in this workspace.
422 A parameter or the request body is invalid. detail says which.

curl -X POST "https://api.app.typetone.ai/public/v1/violations/cmrl4efwd5wu8jfgepgjbxam6/comments" \
  -H "X-API-Key: $TYPETONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Checked with legal: fix before Friday."
  }'

import os
import requests

response = requests.post(
    "https://api.app.typetone.ai/public/v1/violations/cmrl4efwd5wu8jfgepgjbxam6/comments",
    headers={"X-API-Key": os.environ["TYPETONE_API_KEY"]},
    json={
      "comment": "Checked with legal: fix before Friday."
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.app.typetone.ai/public/v1/violations/cmrl4efwd5wu8jfgepgjbxam6/comments", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.TYPETONE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "comment": "Checked with legal: fix before Friday."
  }),
});
const data = await response.json();

Response · 201

{
  "id": "cmuf2k8x10001ab12cd34ef56",
  "author_email": "reviewer@example.com",
  "content": "Checked with legal: fix before Friday.",
  "created_at": "2026-09-24T09:30:00Z"
}

Something unclear or missing? Tell us and we'll improve this page.