AuditCakeDevelopersBook a walkthrough

AI Review

Run AuditCake's AI Review on one of your audits — the same document & exposure check AuditCake runs when an audit is submitted, callable on demand. It reads the audit's reported figures and its documents and returns a recommendation: PRODUCTIVE, REDO, WRONG_DOCS, or SUBMITTED (needs a human look), with a short explanation and per-check findings.

POSThttps://auditcake.com/api/v1/ai/review

Reference an audit you've already created and driven to SUBMITTED (see Create an audit, Update an audit, and Add & read documents). AuditCake assembles the review from the audit's reported figures and its uploaded documents — you don't resend them.

Request

FieldRequiredNotes
auditCodeYesThe audit to review — its auditCode or your own carrierControlId.
webhookUrlNoAn https URL AuditCake will POST the result to when the review completes. If omitted, poll instead (below).
curl -X POST https://auditcake.com/api/v1/ai/review \
  -H "x-api-key: ack_live_<api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "auditCode": "K7M4PQ",
    "webhookUrl": "https://example.com/hooks/ai-review"
  }'

The review is queued and a job id comes back right away (202):

{
  "jobId": "aij_4bb79e79d69f0446054a7661",
  "status": "queued",
  "pollUrl": "/api/v1/ai/review/aij_4bb79e79d69f0446054a7661",
  "readiness": []
}

readiness is an up-front triage of the audit's data (the same checks AuditCake runs at intake) — an array of { code, severity, field, message } findings, empty when nothing is flagged. It doesn't block the review; it tells you what AuditCake noticed about the inputs.

Getting the result

Webhook (recommended)

If you passed a webhookUrl, AuditCake POSTs the completed result there as { jobId, status: "completed", result } — no polling needed.

Polling

GEThttps://auditcake.com/api/v1/ai/review/:jobId
curl https://auditcake.com/api/v1/ai/review/aij_4bb79e79d69f0446054a7661 \
  -H "x-api-key: ack_live_<api-key>"

While the review runs, status is queued. When it finishes:

{
  "jobId": "aij_4bb79e79d69f0446054a7661",
  "status": "completed",
  "result": {
    "status": "Pass",
    "recommendation": "PRODUCTIVE",
    "reason": "Reported sales reconcile with the documents within tolerance.",
    "score": 100,
    "findings": [
      { "status": "pass", "label": "Sales reconcile" },
      { "status": "pass", "label": "Documents acceptable" }
    ]
  }
}

Result fields

FieldNotes
statusPass, Fail, or Review.
recommendationPRODUCTIVE / REDO / WRONG_DOCS / SUBMITTED.
reasonA plain-language explanation of the verdict.
scoreA confidence score (0–100).
findingsPer-check results — { status: "pass" | "warn" | "fail", label }.

Error responses

StatusMeaning
400The webhookUrl isn't a valid http(s) URL.
401The x-api-key header is missing or not recognized.
404No audit (or job) with that id falls within the calling key's scope.
500An unexpected error on AuditCake's side. Safe to retry.