> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zespan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate an evidence pack

> Creates an `EvidencePack` row in `pending` status and enqueues generation on a background worker — this endpoint returns immediately, before the document exists. Poll `GET /v1/projects/{id}/evidence-packs/{packId}` (or list packs) to watch `status` move through `processing` to `completed` (or `failed`).

`kind: "control_evidence"` requires `framework`; `kind: "agent_card"` ignores it. `periodStart` must be before `periodEnd`, and the period may not exceed 400 days. There is no `"pdf"` value for `format` — this deployment has no headless-browser rendering path, so a PDF request is rejected here rather than silently downgraded to HTML.

**Authenticated with a dashboard session (browser cookie), not `x-api-key`**, and requires both the `compliance:generate` permission (owner/admin only — editor, viewer, and billing roles can read and download but not generate) and the Pro plan or above.




## OpenAPI

````yaml /api-reference/openapi.yaml post /v1/projects/{id}/evidence-packs
openapi: 3.1.0
info:
  title: Zespan Public API
  version: 1.0.0
  description: >
    The Zespan Public API covers the endpoints that customers call directly or
    through the Zespan SDKs: trace ingestion (native and OpenTelemetry), prompt
    management, datasets and dataset runs, and the runtime guardrails check.

    All endpoints authenticate with a project API key sent in the `x-api-key`
    header. Create and manage API keys from the project settings in the Zespan
    dashboard.
servers:
  - url: https://api.zespan.com
    description: Zespan production API
security:
  - ApiKeyAuth: []
tags:
  - name: Ingestion
    description: Send traces and events to Zespan.
  - name: OpenTelemetry
    description: OTLP-compatible ingestion endpoints.
  - name: Prompts
    description: Manage versioned prompts and their labels, tags, and folders.
  - name: Datasets
    description: Read datasets and manage dataset runs used for experiments and scoring.
  - name: Guardrails
    description: Runtime guardrail evaluation.
  - name: SDK / CLI support
    description: >
      Small support endpoints consumed by the SDKs and @zespan/cli rather than
      called directly by application code.
  - name: Blast Radius
    description: >
      The prompt/agent/model/policy/evaluator/alert dependency graph backing the
      pre-release impact check and the evaluator-delete gate in the dashboard.
      Session-authenticated (dashboard cookie), not `x-api-key`.
  - name: Outcomes
    description: >
      Report business outcomes (a deflected ticket, an avoided refund, an SLA
      met) attributed to a trace, and read them back summarized by agent or
      model, joined to real trace cost. Backs the Value dashboard page. The
      ingest endpoint is `x-api-key`-authenticated like the rest of ingestion;
      the two read endpoints are session-authenticated (dashboard cookie) like
      Blast Radius.
  - name: Compliance
    description: >
      Generate audit-ready evidence documents (a per-agent Compliance Card, or
      SOC 2 control evidence) from recorded platform data, and re-verify a
      generated document's citations against live data. Session-authenticated
      (dashboard cookie), not `x-api-key`, gated by `compliance:read` /
      `compliance:generate` permissions and the Pro plan or above (the framework
      listing is the one exception — no project scope and no plan gate, since a
      customer deciding whether to upgrade needs to see what they'd get).
  - name: Models
    description: >
      Per-model usage, cost, latency, and error-rate rollups for a project,
      including the lifecycle overlay described under the Model Lifecycle tag.
      Session-authenticated (dashboard cookie), not `x-api-key`, gated by
      `dashboard:read`.
  - name: Model Lifecycle
    description: >
      Findings from the daily model deprecation scan, which matches models a
      project actually calls against a curated, bundled catalogue of
      provider-announced deprecation and retirement dates. Every figure on a
      finding (call volume, cost, affected agents/prompts, cost comparison
      against a named successor) is measured from real trace data — there is no
      quality-delta or regression-comparison endpoint, because nothing in this
      API invokes a model on the caller's behalf. Session-authenticated
      (dashboard cookie), not `x-api-key`: reading findings and the catalogue
      requires `dashboard:read`, dismissing a finding requires `alerts:manage`.
paths:
  /v1/projects/{id}/evidence-packs:
    post:
      tags:
        - Compliance
      summary: Generate an evidence pack
      description: >
        Creates an `EvidencePack` row in `pending` status and enqueues
        generation on a background worker — this endpoint returns immediately,
        before the document exists. Poll `GET
        /v1/projects/{id}/evidence-packs/{packId}` (or list packs) to watch
        `status` move through `processing` to `completed` (or `failed`).


        `kind: "control_evidence"` requires `framework`; `kind: "agent_card"`
        ignores it. `periodStart` must be before `periodEnd`, and the period may
        not exceed 400 days. There is no `"pdf"` value for `format` — this
        deployment has no headless-browser rendering path, so a PDF request is
        rejected here rather than silently downgraded to HTML.


        **Authenticated with a dashboard session (browser cookie), not
        `x-api-key`**, and requires both the `compliance:generate` permission
        (owner/admin only — editor, viewer, and billing roles can read and
        download but not generate) and the Pro plan or above.
      operationId: generateEvidencePack
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Project id.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateEvidencePackRequest'
      responses:
        '202':
          description: >
            The pack row was created and generation was enqueued. The document
            itself is not ready yet — `status` is `pending`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateEvidencePackResponse'
        '400':
          description: >
            `periodStart` is not before `periodEnd`, the period exceeds 400
            days, `framework` is missing for `kind: "control_evidence"`, or
            another body validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >
            Not authenticated with a dashboard session, lacks
            `compliance:generate`, or the organization's plan is below Pro
            (`code: "PLAN_REQUIRED"` in the error body for the plan case).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: >-
            Evidence pack generation is temporarily unavailable (queue not wired
            up).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security: []
components:
  schemas:
    GenerateEvidencePackRequest:
      type: object
      properties:
        kind:
          type: string
          enum:
            - agent_card
            - control_evidence
          description: >
            `agent_card` produces a Compliance Card for one agent (or all
            agents); `control_evidence` produces a framework-mapped document and
            requires `framework`.
        framework:
          type: string
          enum:
            - soc2
          description: Required when `kind` is `control_evidence`; ignored otherwise.
        scope:
          type: object
          properties:
            agentName:
              type: string
              minLength: 1
              maxLength: 200
              description: >-
                Restricts an `agent_card` document to one agent. Omit for all
                agents in the project.
          default: {}
        periodStart:
          type: string
          format: date-time
        periodEnd:
          type: string
          format: date-time
          description: Must be after `periodStart`; the period may not exceed 400 days.
        format:
          type: string
          enum:
            - json
            - html
          default: html
          description: >
            No `pdf` value — this deployment has no headless-browser rendering
            path, so a PDF request is rejected here rather than silently
            downgraded to HTML.
      required:
        - kind
        - periodStart
        - periodEnd
    GenerateEvidencePackResponse:
      type: object
      properties:
        packId:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - failed
          description: >-
            Always `pending` on this response — generation has just been
            enqueued.
      required:
        - packId
        - status
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message.
          example: Unauthorized
        code:
          type: string
          description: Machine-readable error code, when present.
          example: rate_limit_exceeded
      required:
        - error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Project API key. Manage keys in the Zespan dashboard under project
        settings.

````