compliance:write

compliance:write The compliance:write scope allows you to run OEM advertising compliance checks and apply suggested replacements. Use the sync freeform endpoints for pasted copy (agents / MCP), or trigger an async check on existing Hrizn content. Freeform checks also require the dealership’s Compliance Checking plan feature (Pro+ / add-on). Results are heuristics — not legal advice.

Endpoints

Method	Path	Description
`POST`	`/public/compliance/check`	Sync freeform compliance check
`POST`	`/public/compliance/apply-fixes`	Apply selected replacements to supplied text (persists nothing)
`POST`	`/public/content/{id}/compliance`	Trigger an async article compliance check
`POST`	`/public/content/{id}/compliance/apply`	Accept or ignore stored findings — rewrites the article and records decisions

Article reports are retrieved with content:read via GET /public/content/{id}/compliance, or via the compliance.completed webhook.

Check freeform copy

POST /public/compliance/check

Analyzes arbitrary marketing copy (plain text or HTML) against OEM checking rules for this dealership. Returns overall score, categories, and a flat issues array with stable ids plus suggested_replacement text.

Body

Name	Type	Required	Description
`text`	string	Yes	Copy to analyze
`format`	`plain` \| `html`	No	Optional format hint
`source_label`	string	No	Optional label stamped on the report

Apply compliance fixes

POST /public/compliance/apply-fixes

Applies selected issue ids (from a prior check) and/or explicit problematic_text → suggested_replacement pairs. Set recheck: true to run another check on the revised text in one round-trip.

Trigger article compliance check

POST /public/content/{id}/compliance

Starts an asynchronous compliance check on the specified content. The check evaluates the content against OEM compliance rules and dealership advertising guidelines.

Path parameters

Name	Type	Required	Description
`id`	string (UUID)	Yes	Article ID

Request body

No request body is required.

Example

curl -X POST https://api.app.hrizn.io/v1/public/content/d4e5f6a7-b8c9-0123-def0-456789abcdef/compliance \
  -H "X-API-Key: hzk_your_key_here"

const res = await fetch(
  "https://api.app.hrizn.io/v1/public/content/d4e5f6a7-b8c9-0123-def0-456789abcdef/compliance",
  {
    method: "POST",
    headers: { "X-API-Key": "hzk_your_key_here" },
  }
);
const data = await res.json();

import requests

response = requests.post(
    "https://api.app.hrizn.io/v1/public/content/d4e5f6a7-b8c9-0123-def0-456789abcdef/compliance",
    headers={"X-API-Key": "hzk_your_key_here"},
)
data = response.json()

$ch = curl_init("https://api.app.hrizn.io/v1/public/content/d4e5f6a7-b8c9-0123-def0-456789abcdef/compliance");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: hzk_your_key_here"],
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch));

Response — `202 Accepted`

{
  "data": {
    "article_id": "d4e5f6a7-b8c9-0123-def0-456789abcdef",
    "status": "checking"
  }
}

Setting auto_compliance: true when creating content records that intent on the article, but it does not start the check — you still need this call once generation completes. Do not treat auto_compliance: true as evidence that an article was screened.

Retrieving the compliance report

Once the check completes, retrieve the report using the content:read scope:

curl https://api.app.hrizn.io/v1/public/content/d4e5f6a7-b8c9-0123-def0-456789abcdef/compliance \
  -H "X-API-Key: hzk_your_key_here"

const res = await fetch(
  "https://api.app.hrizn.io/v1/public/content/d4e5f6a7-b8c9-0123-def0-456789abcdef/compliance",
  { headers: { "X-API-Key": "hzk_your_key_here" } }
);
const data = await res.json();

import requests

response = requests.get(
    "https://api.app.hrizn.io/v1/public/content/d4e5f6a7-b8c9-0123-def0-456789abcdef/compliance",
    headers={"X-API-Key": "hzk_your_key_here"},
)
data = response.json()

$ch = curl_init("https://api.app.hrizn.io/v1/public/content/d4e5f6a7-b8c9-0123-def0-456789abcdef/compliance");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ["X-API-Key: hzk_your_key_here"],
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch));

{
  "data": {
    "article_id": "d4e5f6a7-b8c9-0123-def0-456789abcdef",
    "status": "completed",
    "report": {
      "overall": "WARN",
      "overall_score": 92,
      "summary": { "total_issues": 1, "high_severity_issues": 0, "medium_severity_issues": 1, "low_severity_issues": 0 },
      "issues": [
        {
          "id": "9f3d2a417c05b1e8",
          "severity": "medium",
          "category": "msrp_pricing",
          "description": "Price mentioned may be outdated",
          "problematic_text": "priced at $28,995",
          "suggested_replacement": "see current pricing"
        }
      ],
      "timestamp": "2026-02-01T15:30:00Z"
    },
    "dispositions": []
  }
}

Each issue’s id is stable across re-checks — feed it to POST /public/content/{id}/compliance/apply as issue_ids or ignore_issue_ids. Decisions already made appear under dispositions.

Status codes

Code	Description
`202`	Compliance check started
`400`	Article ID is required
`401`	Missing or invalid API key
`403`	API key does not have `compliance:write` scope
`404`	Content not found or belongs to a different site
`500`	Internal server error

Apply compliance decisions to an article

POST /public/content/{id}/compliance/apply

Acts on the STORED report by finding id: issue_ids are accepted — the suggested replacement is applied to the article body — and ignore_issue_ids are dismissed with a reason, leaving the copy untouched. Body and decisions persist atomically, and both survive re-checks: a fixed or dismissed finding does not come back as open.

Body

Name	Type	Required	Description
`issue_ids`	string[]	One of	Findings to fix (ids from the stored report)
`ignore_issue_ids`	string[]	One of	Findings to dismiss without changing copy
`reason`	string	No	Why the dismissed findings are acceptable
`allow_published`	boolean	No	Must be `true` to rewrite published content

A 409 with code stale_content means the article body changed between reading the report and applying it — nothing was written. Re-run the check for a fresh report, then retry. Use an Idempotency-Key header to make retries safe. This is the endpoint behind the apply_content_compliance_fixes MCP tool. POST /public/compliance/apply-fixes (above) is the freeform variant: it revises supplied text and stores nothing.

Error response — Missing scope

If your API key does not include compliance:write, any request to this endpoint returns:

{
  "error": {
    "code": "forbidden",
    "message": "This API key requires one of the following scopes: compliance:write",
    "details": {
      "required_scopes": ["compliance:write"]
    }
  }
}

Getting Started

Concepts

Guides

Scopes

Endpoints

Check freeform copy

Body

Apply compliance fixes

Trigger article compliance check

Path parameters

Request body

Example

Response — `202 Accepted`

Retrieving the compliance report

Status codes

Apply compliance decisions to an article

Body

Error response — Missing scope

​Endpoints

​Check freeform copy

​Body

​Apply compliance fixes

​Trigger article compliance check

​Path parameters

​Request body

​Example

​Response — 202 Accepted

​Retrieving the compliance report

​Status codes

​Apply compliance decisions to an article

​Body

​Error response — Missing scope

Endpoints

Check freeform copy

Body

Apply compliance fixes

Trigger article compliance check

Path parameters

Request body

Example

Response — `202 Accepted`

Retrieving the compliance report

Status codes

Apply compliance decisions to an article

Body

Error response — Missing scope