> ## Documentation Index > Fetch the complete documentation index at: https://docs.zebratruth.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get a past check with its full report > The persisted envelope for one check, with the report inlined. Not billed. Requires the `logs:read` key scope (company employees: `reports:read`). ## OpenAPI ````yaml /openapi/zebratruth-v1.yaml get /compliance/checks/{requestId} openapi: 3.1.0 info: title: ZebraTruth Compliance API version: 1.0.0 description: > AI-powered compliance checking for advertising content. Check text and images against jurisdiction laws, platform policies, and rights clearance requirements. Results include embeddable annotations mapped to content locations (text spans, video timestamps, image regions). contact: name: ZebraTruth Support email: support@zebratruth.ai url: https://developers.zebratruth.ai license: name: MIT url: https://opensource.org/licenses/MIT servers: - url: https://api.zebratruth.ai/v1 description: Production security: - bearerAuth: [] tags: - name: Video Compliance description: > **Primary endpoint.** Async compliance analysis for video ads. 3-step flow: get an upload URL, upload the video bytes, submit for analysis. Poll or receive an HMAC-signed webhook with the report. Returns timestamped findings citing stable evidence IDs (`audio_NNN`, `frame_NNN`, `ocr_NNN`, `signal_NNN`). 3-180 second videos. mp4 / webm / quicktime. Built for ad agencies and creators. - name: Authentication description: Validate API keys and check account status - name: Compliance description: >- Run compliance checks on text + image content (sync). For video, use the Video Compliance endpoints above. - name: Agents description: Discover and invoke individual compliance agents - name: Jobs description: Poll async job status and view execution traces - name: Reports description: Retrieve and replay compliance reports - name: Observability description: Request logs and webhook delivery status - name: Billing description: Subscriptions, plan changes, and credit balance - name: Documents description: Extract text from PDF and Word documents before or as part of a check - name: Check History description: List and retrieve past compliance checks for the workspace - name: Provenance description: Inspect and sign Content Credentials (C2PA) on images and video - name: Corpus description: >- Review queue for proposed changes to the governed legal corpus (dashboard session) - name: Webhooks description: Saved webhook endpoints (dashboard session) and delivery logs paths: /compliance/checks/{requestId}: get: tags: - Check History summary: Get a past check with its full report description: > The persisted envelope for one check, with the report inlined. Not billed. Requires the `logs:read` key scope (company employees: `reports:read`). operationId: getCheck parameters: - name: requestId in: path required: true schema: type: string responses: '200': description: Persisted check content: application/json: schema: $ref: '#/components/schemas/CheckHistoryDetail' '401': $ref: '#/components/responses/Unauthorized' '403': description: >- Workspace denial codes, or `data.code: output_quarantined` — the video job's output was withheld after an authority change. content: application/json: schema: $ref: '#/components/schemas/CodedError' '404': description: No such check, or not visible to this reader. '409': description: >- `data.code`: `report_unavailable` — the check exists but its report was not persisted, or the video job has not reached a reportable state. content: application/json: schema: $ref: '#/components/schemas/CodedError' '410': description: >- `data.code`: `retention_expired` — older than the plan's retention window. content: application/json: schema: $ref: '#/components/schemas/CodedError' components: schemas: CheckHistoryDetail: type: object description: >- The persisted check envelope, returned verbatim, with the full report inlined. properties: schemaVersion: type: string enum: - v1 tenantId: type: string requestId: type: string createdAt: type: string format: date-time kind: type: string enum: - text - image - video - pdf - word_doc mode: type: string enum: - fast - full description: Absent for image checks. responseMode: type: string enum: - sync - stream - async description: Absent for video checks. externalId: type: string nullable: true jurisdictions: type: array items: type: string platforms: type: array items: type: string industryOverlays: type: array items: type: string regulatedActor: type: string executionMetadata: type: object description: > How the check was answered: routing snapshot, corpus versions, and for financial-services checks the legal-context snapshot (which rules each specialist was given). Shape is versioned and may grow. additionalProperties: true report: allOf: - $ref: '#/components/schemas/ComplianceReport' description: For video checks this is the video report (see `VideoReport`). CodedError: type: object description: > Standard error envelope. `data.code` is the stable discriminator to branch on; `statusMessage` is the human-readable reason. Unless a response documents extra named fields, `data` is reduced to `{ code }` before it is sent. required: - statusCode - message properties: error: type: boolean example: true url: type: string format: uri statusCode: type: integer statusMessage: type: string message: type: string data: type: object required: - code properties: code: type: string example: review_scope_not_enabled additionalProperties: true ComplianceReport: type: object properties: requestId: type: string description: >- Identifier of this check, usable with `GET /compliance/checks/{requestId}` and in request logs. reportId: type: string example: rpt_abc123 score: type: integer minimum: 0 maximum: 100 example: 72 decision: $ref: '#/components/schemas/ComplianceDecision' checks: type: array items: $ref: '#/components/schemas/ComplianceCheck' description: | All compliance findings. Each check has structured classification metadata (id, jurisdictions, platforms, scope, primaryCategory, categories) added inline. Combine `bySeverity` + `byJurisdiction` etc. via the `indexes` field for filtered views. checksById: type: object additionalProperties: $ref: '#/components/schemas/ComplianceCheck' description: | O(1) lookup map keyed by stable `id`. Same data as `checks[]`, indexed for direct access (e.g. when resolving an annotation's `checkId` to its parent check). indexes: $ref: '#/components/schemas/CheckIndexes' annotations: type: array items: $ref: '#/components/schemas/ComplianceAnnotation' profile: $ref: '#/components/schemas/ComplianceProfile' agentSummaries: type: object additionalProperties: $ref: '#/components/schemas/AgentSummary' versionInfo: $ref: '#/components/schemas/ComplianceVersionInfo' costBreakdown: $ref: '#/components/schemas/CostBreakdown' creditsCharged: type: number description: Credits debited for this request. `0` on a cache hit. cached: type: boolean description: > `true` when the result was served from the response cache or an idempotent replay. coverageIncomplete: type: boolean description: > `true` when at least one agent could not consult its legal corpus. Always equals `coverageGaps.length > 0`. coverageGaps: type: array items: $ref: '#/components/schemas/CoverageGap' analysisDiagnostics: type: array items: $ref: '#/components/schemas/AnalysisDiagnostic' description: Pipeline diagnostics that are not compliance findings. regulatedActors: type: array items: $ref: '#/components/schemas/RegulatedActor' description: Present when the check was evaluated for specific regulated actors. agentsRun: type: array items: $ref: '#/components/schemas/AgentRunRecord' description: > One record per financial-services specialist selected for this check, with how it finished. Absent on checks that ran no specialist and on cached results produced before this field existed. decisionReasons: type: array items: $ref: '#/components/schemas/DecisionReason' description: > Every rule that contributed to `decision`, in evaluation order. Present on checks that ran a financial-services specialist. _meta: type: object description: Present only for test mode (zt_test_ keys) properties: mode: type: string enum: - test sandbox: type: boolean creditsCharged: type: number estimatedProductionCost: type: number scenarioId: type: string example: claim-violation ComplianceDecision: type: string enum: - PUBLISH - HOLD - BLOCK description: | - `PUBLISH` — Score 80-100, safe to publish - `HOLD` — Score 60-79, or any high-severity flag - `BLOCK` — Score 0-59, or any critical-severity check ComplianceCheck: type: object description: > A single compliance finding. Includes both the raw finding fields (checkName, severity, message, recommendation, citation) and structured classification metadata added by the engine (id, jurisdictions, platforms, scope, primaryCategory, categories). properties: id: $ref: '#/components/schemas/CheckId' agentId: $ref: '#/components/schemas/ComplianceAgentId' checkName: type: string description: Human-readable check name example: Unsubstantiated Health Claim - 'Cure Cancer' status: $ref: '#/components/schemas/ComplianceStatus' severity: $ref: '#/components/schemas/ComplianceSeverity' message: type: string description: Human-readable description of the issue example: >- 'Guaranteed to cure cancer' is an unsubstantiated health claim under FTC and EU UCPD. recommendation: type: string description: Specific action to fix the issue example: >- Remove the guarantee or substantiate with peer-reviewed clinical evidence. citation: type: string description: Legal or policy reference example: FTC Endorsement Guides, 16 CFR Part 255 metadata: type: string description: Optional JSON string with agent-specific data jurisdictions: type: array items: type: string description: > Canonical jurisdiction codes (us, eu, uk, india, china) this check applies to. May be empty when `scope` is `global` or `platform-specific`. Always a subset of the request's jurisdiction list. example: - us - eu platforms: type: array items: type: string description: > Canonical platform codes (youtube, instagram, facebook, tiktok, linkedin) this check applies to. May be empty when `scope` is `global` or `jurisdiction-specific`. Always a subset of the request's platform list. example: - youtube - instagram scope: $ref: '#/components/schemas/CheckScope' primaryCategory: $ref: '#/components/schemas/CheckCategory' categories: type: array minItems: 1 items: $ref: '#/components/schemas/CheckCategory' description: > All matched categories, with `primaryCategory` first. A finding may apply to multiple categories (e.g. a deepfake celebrity check matches both `deepfake-impersonation` and `right-of-publicity`). example: - unsubstantiated-health-claim - performance-claim CheckIndexes: type: object description: | Pre-computed reference indexes — pure ID lists, no content duplication. Tenants pick whichever organization fits their UI. Combine via set intersection (e.g., critical EU findings = bySeverity.critical ∩ byJurisdiction.eu). All seven dimensions always present; empty buckets are included so client code can do `indexes.byJurisdiction.us ?? []` without optional-chaining on the bucket itself. properties: byJurisdiction: type: object additionalProperties: type: array items: $ref: '#/components/schemas/CheckId' description: Keyed by jurisdiction code (us, eu, uk, india, china). byPlatform: type: object additionalProperties: type: array items: $ref: '#/components/schemas/CheckId' description: >- Keyed by platform code (youtube, instagram, facebook, tiktok, linkedin). bySeverity: type: object additionalProperties: type: array items: $ref: '#/components/schemas/CheckId' description: Keyed by severity (info, low, medium, high, critical). byStatus: type: object additionalProperties: type: array items: $ref: '#/components/schemas/CheckId' description: Keyed by status (pass, flag, block, escalate). byCategory: type: object additionalProperties: type: array items: $ref: '#/components/schemas/CheckId' description: >- Keyed by `primaryCategory` only — each check appears in exactly one bucket. byCategoryAll: type: object additionalProperties: type: array items: $ref: '#/components/schemas/CheckId' description: >- Keyed by every category in `categories[]` — a check may appear in multiple buckets. byAgent: type: object additionalProperties: type: array items: $ref: '#/components/schemas/CheckId' description: Keyed by agentId. ComplianceAnnotation: type: object required: - type - agentId - severity - message properties: type: $ref: '#/components/schemas/AnnotationType' checkRef: type: string description: > DEPRECATED. Legacy link to `ComplianceCheck.checkName`. Use `checkId` instead — it's a stable hash that survives prompt wording changes. Retained for backward compatibility; will be removed in a future major version. checkId: $ref: '#/components/schemas/CheckId' agentId: $ref: '#/components/schemas/ComplianceAgentId' severity: $ref: '#/components/schemas/ComplianceSeverity' message: type: string example: '''Guaranteed results'' may violate FTC endorsement guides' suggestion: type: string description: Actionable fix example: Consider 'may help' instead of 'guaranteed' textLocation: type: object description: For text-span annotations properties: start: type: integer description: Character offset (0-indexed) example: 120 end: type: integer example: 138 matchedText: type: string example: guaranteed results timelineLocation: type: object description: For timeline annotations (video) properties: startMs: type: integer example: 15000 endMs: type: integer example: 28000 track: type: string enum: - audio - video - subtitle imageLocation: type: object description: For image-region annotations properties: imageUrl: type: string format: uri boundingBox: type: object properties: x: type: number 'y': type: number width: type: number height: type: number ComplianceProfile: type: object properties: detectedJurisdictions: type: array items: type: string applicableRules: type: array items: type: object targetPlatforms: type: array items: type: string confidence: type: number minimum: 0 maximum: 1 reasoning: type: string AgentSummary: type: object properties: status: $ref: '#/components/schemas/ComplianceStatus' checkCount: type: integer passCount: type: integer flagCount: type: integer blockCount: type: integer summary: type: string example: 2 advertising claim issues found ComplianceVersionInfo: type: object properties: engineVersion: type: string example: 1.3.2 rulesVersion: type: string description: >- Timestamp of last rules update. Bumps when the compiled law set changes. example: '2026-04-01' agentVersions: type: object additionalProperties: type: string description: Version per compliance agent. Bumps when an agent's logic changes. example: advertising-law: 1.1.0 ai-laws: 1.3.0 stackVersion: type: string description: > Opaque identifier for the internal model/prompt stack. Bumps whenever the underlying model pipeline changes. Use it for client-side change detection (e.g. invalidate cached results, trigger replays). The format is intentionally opaque — treat it as a black-box string and pattern-match only for equality, never parse its structure. example: 2026.04-a7f3 CostBreakdown: type: object properties: totalCredits: type: number agents: type: array items: $ref: '#/components/schemas/AgentCostEntry' CoverageGap: type: object required: - agentId - reason properties: agentId: type: string reason: type: string enum: - memory_disabled - lookup_unavailable - no_compatible_card - legacy_unclassified description: Why the agent could not consult its governed corpus for this check. AnalysisDiagnostic: type: object description: | First-class pipeline diagnostic. Surfaces non-compliance signals like renderer overflow or boundary-validation drops without polluting the compliance findings array. required: - code - message - severity properties: code: type: string description: >- Stable machine-readable code (e.g. `evidence_truncated`, `video_check_missing_evidence_ids`). example: evidence_truncated message: type: string description: Human-readable explanation. severity: type: string enum: - info - warning - error evidenceIds: type: array items: type: string RegulatedActor: type: string enum: - advertiser - manufacturer - platform - provider - payer - pharmacy - HCP - telehealth_provider - adviser - broker_dealer - bank - lender - servicer - debt_collector - fund_manager - payment_service_provider - insurer description: > The regulated party a check is evaluating. Corpus rules tagged with an incompatible actor are excluded from asserted citations and cannot drive blocking findings. AgentRunRecord: type: object required: - id - outcome properties: id: $ref: '#/components/schemas/ComplianceAgentId' outcome: $ref: '#/components/schemas/AgentOutcome' reason: type: string enum: - timeout - agent_error - invalid_model_output - legal_context_unavailable - legal_context_overflow - fs_agent_not_available description: >- Present when `outcome` is a failure. `legal_context_unavailable` means the scope's corpus is not yet served. DecisionReason: type: string enum: - blocking_check - required_review_incomplete - legal_context_overflow - flagged_check description: > Why the decision is what it is. `blocking_check`: a blocking finding forced BLOCK. `required_review_incomplete`: a required specialist did not complete, so the check is HOLD. `legal_context_overflow`: the applicable rule set exceeded what one run can evaluate. `flagged_check`: a flagged finding produced HOLD. CheckId: type: string pattern: ^chk_[0-9a-f]{8}$ description: | Stable check identifier. Format: `chk_<8 lowercase hex>`. Generated as a SHA-256 hash of (agentId, checkName, citation, sorted jurisdictions, sorted platforms, primaryCategory) — stable across reruns of identical content + scope + engine version. NOT stable across taxonomy reclassifications (primaryCategory change) or content/scope changes. example: chk_a1b2c3d4 ComplianceAgentId: type: string enum: - ai-laws - jurisdiction-detection - advertising-law - platform-policy - metadata-labeling - rights-clearance - rights-clearance-text - rights-clearance-image - compliance-score - fs-compliance-financial-promotion - fs-compliance-advisory-suitability - fs-compliance-credit-servicing - fs-compliance-markets-trading - fs-compliance-financial-crime - fs-compliance-ai-governance - financial-services-compliance - pharma-healthcare-compliance description: > Agent identifier. Use `GET /agents` to discover all available agents dynamically. The list is filtered to the industries your workspace has selected. **Financial services.** The six `fs-compliance-*` agents correspond one-to-one to the review scopes (`financial_promotion` → `fs-compliance-financial-promotion`, and so on). In a full check they are selected with `reviewScopes`. Via `POST /agents/{agentId}` only `fs-compliance-financial-promotion` can be invoked directly today; the other five return 400 `review_scope_not_enabled` on direct invocation and must run through `POST /compliance/check`. `financial-services-compliance` is a read-only alias of `fs-compliance-financial-promotion` accepted for older clients. **Pharma and healthcare.** `pharma-healthcare-compliance` runs for workspaces on the `pharma_healthcare` industry and honours `regulatedActor`. `ai-laws` is the canonical id; `jurisdiction-detection` is accepted as an input alias for backward compatibility with historical clients. New integrations should use `ai-laws`. **Note on rights-clearance variants.** `GET /agents` exposes two registered agents for rights clearance: `rights-clearance-text` and `rights-clearance-image` — invoke them via `POST /agents/{agentId}` using those qualified IDs. On **check response objects**, however, text rights-clearance findings carry the bare `agentId: "rights-clearance"`. Treat bare `rights-clearance` and `rights-clearance-text` as the same logical pipeline — the bare form is the value that appears on `checks[]` entries from that agent. ComplianceStatus: type: string enum: - pass - flag - block - escalate description: | - `pass` — No issue found - `flag` — Issue found, review recommended - `block` — Critical issue, must fix - `escalate` — Needs human review ComplianceSeverity: type: string enum: - critical - high - medium - low - info description: | - `critical` — Legal liability risk (-25 points) - `high` — Likely violation (-15 points) - `medium` — Potential issue (-8 points) - `low` — Minor concern (-3 points) - `info` — Informational only (0 points) CheckScope: type: string enum: - global - jurisdiction-specific - platform-specific - cross-cutting description: | Disambiguates the empty-array case for `jurisdictions` and `platforms`: - `global` — universal; both arrays empty - `jurisdiction-specific` — jurisdictions populated, platforms empty - `platform-specific` — platforms populated, jurisdictions empty - `cross-cutting` — both populated; check applies at the intersection CheckCategory: type: string enum: - celebrity-endorsement - expert-authority - fabricated-testimonial - material-connection-disclosure - unsubstantiated-health-claim - medical-efficacy-claim - safety-claim - performance-claim - comparative-advertising - right-of-publicity - trademark-infringement - copyright-infringement - music-licensing - ai-disclosure-missing - watermark-missing - c2pa-missing - deepfake-impersonation - disguised-advertising - sponsored-content-labeling - consumer-information-disclosure - scarcity-urgency - aggressive-practice - algorithmic-amplification - minor-targeting - vulnerable-audience - platform-policy-violation - data-privacy - jurisdiction-coverage-gap - other description: | Top-level breach taxonomy. New categories may be added in minor versions (additive only); renaming and removal are forbidden. Clients MUST accept unknown enum values gracefully (forward-compat). `other` is the fallback bucket for findings that don't fit any specific category. AnnotationType: type: string enum: - text-span - timeline - image-region - global AgentCostEntry: type: object properties: agent: type: string example: jurisdiction stage: type: string enum: - A - B - C description: > Pipeline stage — the agent's work is decomposed into three sub-steps: - **A** — Legal research (retrieves applicable law; cacheable with a 30-day TTL) - **B** — Risk interpretation (maps law to content-specific risk) - **C** — Compliance composition (writes structured output) credits: type: number cached: type: boolean description: Whether the research cache was used example: false AgentOutcome: type: string enum: - completed - completed_no_findings - not_applicable - failed_required - failed_optional - insufficient_evidence description: > How a specialist agent finished. `completed` and `completed_no_findings` are charged; the other four release the agent's reservation. responses: Unauthorized: description: | Invalid, missing, or expired API key. Standard error envelope — read `message` for the human-readable reason. content: application/json: schema: type: object description: Standard error envelope. required: - statusCode - message properties: error: type: boolean example: true url: type: string format: uri example: https://api.zebratruth.ai/v1/whoami statusCode: type: integer example: 401 statusMessage: type: string example: Invalid API key message: type: string description: Canonical human-readable reason — pattern-match on this field. example: Invalid API key securitySchemes: bearerAuth: type: http scheme: bearer description: | API key starting with `zt_live_` (production) or `zt_test_` (sandbox). Get your key at https://developers.zebratruth.ai ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.