API reference

Use the version-one API to inspect capabilities, manage policies, check text, audit logs and read usage. Configure the service origin for your installation.

Contract

The application-mode OpenAPI contract defines exact request, response and error schemas. Every operation is under /v1. Breaking changes require a new major path; additive fields can appear in v1.

Authentication and scope

Use Authorization: Bearer YOUR_SCOPED_KEY. Organization owners create keys in the application workspace's Integration keys area. Keys are revealed once and can be revoked. Never put a key in a URL. Browser sessions additionally require CSRF protection for POSTs.

Implemented endpoints

Method and path	Purpose	Required scope
`GET /v1/auth/test`	Validate credentials and organization	auth:test
`GET /v1/scan-policies`	List authorized policies	scan_policies:read
`GET /v1/scan-policies/{id}`	Read a policy version	scan_policies:read
`POST /v1/scan-policies/{id}/estimate`	Quote the request without scanning	scan_policies:estimate
`POST /v1/check`	Run a complete check	scan:check
`GET /v1/scans/{id}`	Read authorized metadata, without text	scan_policies:read
`GET /v1/capabilities`	Read the current versioned capability catalog and operational availability	catalog:read
`GET /v1/checks`	List check availability	catalog:read
`GET /v1/scan-policy-templates`	List templates	catalog:read
`GET /v1/scan-policy-templates/{slug}`	Read a template	catalog:read
`POST /v1/scan-policy-templates/{slug}/copy`	Create a policy from a template	scan_policies:write
`POST /v1/scan-policies/{id}/versions`	Publish an immutable policy version	scan_policies:write
`POST /v1/audit-sources`	Upload a bounded CSV or JSONL source	audits:write
`POST /v1/audits`	Map, validate and quote an audit	audits:write
`POST /v1/audits/{id}/run`	Queue the quoted audit	audits:write
`POST /v1/audits/{id}/cancel`	Cancel an audit	audits:write
`GET /v1/audits/{id}`	Read audit progress and usage	audits:read
`GET /v1/audits/{id}/findings`	Page content-free findings	audits:read
`GET /v1/usage`	Read balance and page usage	usage:read

Capability and policy versions

GET /v1/capabilities returns capabilities-v1, with readable limits, exact check/runtime versions, review constraints and current availability. The legacy /v1/checks representation keeps its historical status strings for existing clients; those strings are not a product release label or execution authority.

Existing policy versions keep their behavior. To use the newer deterministic checks, explicitly publish a new version with runtime_choice: "rules_v2". This selects deterministic-rules-v2, including suspicious Unicode; it does not add models. The default retain preserves the previous version. Review the changed checks and quote before running them.

Check text

Replace the policy ID and key with values from your organization. This synthetic request shows the supported shape; it is not a live response or executable credential.

POST /v1/check
Authorization: Bearer YOUR_SCOPED_KEY
Idempotency-Key: synthetic-ticket-42
Content-Type: application/json

{
  "content": "Please contact sam@example.test.",
  "scan_policy_id": "YOUR_POLICY_UUID",
  "scan_policy_version": 1,
  "direction": "input",
  "return_redacted_content": true
}

A successful classification returns HTTP 200 with status, decision, safe_to_continue, findings, coverage, policy/runtime identifiers, and usage. An explicitly requested redacted_content is returned in memory only. A review or block result is a successful, billable classification.

Audit uploads and progress

Send one file, source_format and retention as multipart data to /v1/audit-sources. Audit sources allow up to 5 MiB; text fields remain limited to 128 KiB. The service stores a private signed reference internally and returns a source ID with an authoritative expiry time, not a cloud signed-upload URL.

Create an audit with the source ID, Scan Policy and column mapping to receive a quote. Confirm it with the run endpoint. Processing requires an available audit worker; poll with a deadline and use the returned opaque cursor to page content-free findings. Source content becomes unavailable when retention expires.

Input and retry limits

Target plus optional context is limited to 20,000 Unicode code points; scan HTTP bodies to 128 KiB (the multipart audit-source exception is described above). Policies can require smaller model windows. Structured fields are at most 16 named scalar values and 2,000 serialized code points, and must match the policy’s declared types.

Keep the same request key and complete payload for a retry within seven days. A different request using that key returns 409. Replays do not create another debit. Once the retry window expires, the key can represent new work. An omitted policy version is resolved on the first accepted request and retained for that retry window.

Handle errors explicitly

400 / 413 / 422: Correct malformed, oversized, or unsupported input.
401 / 403 / 404: Check credentials, policy scope, and organization access.
402: Insufficient available credits; do not silently bypass checks.
409: Request conflict or work in progress. Reuse an identical request only when retryable.
410: The retained source has expired or is no longer available; upload a new source when needed.
429 / 503 / 504: Respect Retry-After and the response’s retryable flag. Retry the same request; never substitute an allow result.

Error envelopes include schema_version, code, and retryable. Do not log raw text, context, keys, or redacted output as debugging metadata.