> ## 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.

# Invoke a single agent

> Run a single compliance agent directly instead of the full pipeline.
Useful for targeted re-checks or building custom workflows.




## OpenAPI

````yaml /openapi/zebratruth-v1.yaml post /agents/{agentId}
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:
  /agents/{agentId}:
    post:
      tags:
        - Agents
      summary: Invoke a single agent
      description: |
        Run a single compliance agent directly instead of the full pipeline.
        Useful for targeted re-checks or building custom workflows.
      operationId: invokeAgent
      parameters:
        - name: agentId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ComplianceAgentId'
          description: The agent to invoke (use `GET /agents` to discover available IDs)
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentInvokeRequest'
      responses:
        '200':
          description: Agent result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '403':
          description: >
            The agent is not enabled for this workspace's industries, or
            (financial services)

            the review scope is not in the plan — `data.code:
            review_scope_not_entitled`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodedError'
        '404':
          description: >
            Agent not found. A financial-services specialist whose corpus is not
            yet available

            is also reported as not found — `data.code: fs_agent_not_available`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodedError'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    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.
    AgentInvokeRequest:
      type: object
      required:
        - jurisdictions
        - platforms
        - content
      properties:
        jurisdictions:
          type: array
          minItems: 1
          items:
            type: string
            enum:
              - us
              - eu
              - uk
              - india
              - china
        platforms:
          type: array
          minItems: 1
          items:
            type: string
            enum:
              - youtube
              - instagram
              - facebook
              - tiktok
              - linkedin
        content:
          type: object
          required:
            - text
          properties:
            text:
              type: string
        regulatedActor:
          allOf:
            - $ref: '#/components/schemas/RegulatedActor'
          description: Optional. Scopes the agent's rule set to one regulated actor.
    AgentResult:
      type: object
      required:
        - requestId
        - agentId
        - checks
        - annotations
        - cached
        - creditsCharged
        - costBreakdown
      properties:
        requestId:
          type: string
        agentId:
          $ref: '#/components/schemas/ComplianceAgentId'
        checks:
          type: array
          items:
            $ref: '#/components/schemas/ComplianceCheck'
        annotations:
          type: array
          items:
            $ref: '#/components/schemas/ComplianceAnnotation'
        analysisDiagnostics:
          type: array
          items:
            $ref: '#/components/schemas/AnalysisDiagnostic'
          description: Present only when the run produced pipeline diagnostics.
        partial:
          type: boolean
          description: Present and `true` when the agent returned a partial result.
        error:
          type: string
          description: >-
            Present when the agent failed; the findings array is then
            best-effort.
        cached:
          type: boolean
        creditsCharged:
          type: number
        pricing:
          type: object
          description: The pricing row that applied to this invocation.
          properties:
            feature:
              type: string
            baseCredits:
              type: number
            marginMultiplier:
              type: number
            estimatedCredits:
              type: number
        costBreakdown:
          $ref: '#/components/schemas/CostBreakdown'
    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
    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.
    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
    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
    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
    CostBreakdown:
      type: object
      properties:
        totalCredits:
          type: number
        agents:
          type: array
          items:
            $ref: '#/components/schemas/AgentCostEntry'
    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
    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
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        format: uuid
      description: >
        Unique request identifier to prevent duplicate execution and
        double-charging.

        Generate a new UUID for each distinct request. Reuse the same key to
        safely retry.
  responses:
    BadRequest:
      description: |
        Request body failed validation. Standard error envelope. The
        `message` field describes what's wrong (typically a Zod validation error
        message listing the offending fields).
      content:
        application/json:
          schema:
            type: object
            description: Standard error envelope.
            required:
              - statusCode
              - message
            properties:
              error:
                type: boolean
                example: true
              url:
                type: string
                format: uri
              statusCode:
                type: integer
                example: 400
              statusMessage:
                type: string
                example: 'jurisdictions: Required, platforms: Required'
              message:
                type: string
                description: >-
                  Canonical human-readable reason. For Zod failures, lists each
                  invalid field.
                example: 'jurisdictions: Required, platforms: Required'
    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
    InsufficientCredits:
      description: >
        Not enough credits in the tenant's current period to process this
        request.

        Standard error envelope plus a `data` object with credit specifics

        and an upgrade URL.
      content:
        application/json:
          schema:
            type: object
            description: Standard error envelope with a `data` payload.
            required:
              - statusCode
              - message
            properties:
              error:
                type: boolean
                example: true
              url:
                type: string
                format: uri
              statusCode:
                type: integer
                example: 402
              statusMessage:
                type: string
                example: Insufficient credits
              message:
                type: string
                example: Insufficient credits
              data:
                type: object
                description: >-
                  Per-error context. On the wire this is reduced to `{ code }`
                  plus, where documented, a small set of named fields.
                properties:
                  creditsRemaining:
                    type: number
                    example: 3
                  creditsNeeded:
                    type: number
                  upgradeUrl:
                    type: string
                    format: uri
                    example: https://developers.zebratruth.ai/dashboard/billing
    RateLimited:
      description: |
        Per-tenant rate limit exceeded. Read the `Retry-After` header for the
        wait duration. Body is the standard error envelope plus a
        `data` object with limit context.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying.
      content:
        application/json:
          schema:
            type: object
            description: Standard error envelope with a `data` payload.
            required:
              - statusCode
              - message
            properties:
              error:
                type: boolean
                example: true
              url:
                type: string
                format: uri
              statusCode:
                type: integer
                example: 429
              statusMessage:
                type: string
                example: Rate limit exceeded
              message:
                type: string
                example: Rate limit exceeded
              data:
                type: object
                description: >-
                  Per-error context. On the wire this is reduced to `{ code }`
                  plus, where documented, a small set of named fields.
                properties:
                  retryAfter:
                    type: integer
                    description: >-
                      Mirrors the `Retry-After` header for clients that prefer
                      body fields.
                    example: 5
                  limit:
                    type: integer
                    description: Tenant's requests-per-minute cap.
                    example: 60
                  remaining:
                    type: integer
                    description: Requests remaining in the current window.
                    example: 0
  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.