Batch audits

Queue a population with shared context, follow its progress and retrieve the findings for review.

Prepare the population

An audit accepts 1–10,000 items from one use case and up to 50,000 context records. Request-size limits and account quotas also apply. Replace the single item field with an items array, keeping one shared context and optional options object.

Every item needs a unique type/ID pair. Related items in the same audit are available to population checks; additional related history can be sent in context.records. Splitting a population into independent requests without preserving needed context can change duplicate, cap and history checks.

Submitting an item also declares its type as a supplied population. Relevant batch peers remain visible when the matching context.records list is empty or absent. Even a one-item audit therefore differs from /v1/verify, which needs an explicit comparison population for population checks. An empty list does not assert completeness of the source ledger or hide other batch items.

To make a one-item trial from the quickstart’s invoice.json:

python3 -c 'import json; r=json.load(open("invoice.json")); r["items"]=[r.pop("item")]; print(json.dumps(r))' > audit.json

Create the audit

curl "https://openauditor.ai/api/v1/audits" \
  -H "Authorization: Bearer $OPENAUDITOR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @audit.json

A valid submission returns 202 with an audit ID and queued status. Store the ID as soon as it arrives. Acceptance is not completion, and resubmitting the same JSON creates another audit.

If submission times out, the outcome may be unknown. The API has no idempotency-key mechanism, so a blind retry can create another job. Preserve the response and request ID when available and make this case explicit in your application’s recovery flow.

Follow progress

Set AUDIT_ID to the returned ID and poll the status at a modest interval, within the account’s request limit.

curl "https://openauditor.ai/api/v1/audits/$AUDIT_ID" \
  -H "Authorization: Bearer $OPENAUDITOR_API_KEY"

The status response also carries summary, configuration, timestamps, expires_at and review-mark counts. Some values are null until execution has finished.

Filter and page the results

GET /v1/audits/{id}/items is available after completion. An earlier request returns 409 not_completed.

curl "https://openauditor.ai/api/v1/audits/$AUDIT_ID/items?verdict=uncertain&limit=100" \
  -H "Authorization: Bearer $OPENAUDITOR_API_KEY"

The response contains a data array of Verification objects and next_cursor. Keep the same filters when requesting each next page; stop when the cursor is null. To read the whole population, omit the verdict filter.

Resolve returned paths correctly

Audit body links start with /v1/. For the public host, prepend /api, producing https://openauditor.ai/api/v1/…. The Location response header has already been rewritten to the public API path.

Retain or delete the results

Download what your process needs before the returned expires_at. The hosted retention period is seven days after completion or failure. Original request bodies are removed when execution ends; retained findings may still contain evidence details. Keep the source request in your own workflow. Use DELETE /v1/audits/{id} to delete an audit’s stored inputs, results and review marks earlier; success returns 204 with no response body.

curl "https://openauditor.ai/api/v1/audits/$AUDIT_ID" -X DELETE \
  -H "Authorization: Bearer $OPENAUDITOR_API_KEY"

Only the owning account can read or delete an audit. Preserve any findings you must keep in your own system before deletion. Read data handling and retention.

Continue reading

• Verification results — interpret each item returned from the audit.
• Review marks — record whether sampled verdicts were correct.
• Limits — plan the population and polling rate.