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

# Coverage preview for a framework and period, without generating

> Runs the same evidence queries a control-evidence document would for the given framework and period, and reports per-control record counts — without rendering or storing anything. This is what the Compliance page calls before you commit to generating a pack, so a gap in the underlying data is visible before a document leaves the building, not after.

**Authenticated with a dashboard session (browser cookie), not `x-api-key`**, and requires `compliance:read` plus the Pro plan or above.




## OpenAPI

````yaml /api-reference/openapi.yaml get /v1/projects/{id}/compliance/coverage
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}/compliance/coverage:
    get:
      tags:
        - Compliance
      summary: Coverage preview for a framework and period, without generating
      description: >
        Runs the same evidence queries a control-evidence document would for the
        given framework and period, and reports per-control record counts —
        without rendering or storing anything. This is what the Compliance page
        calls before you commit to generating a pack, so a gap in the underlying
        data is visible before a document leaves the building, not after.


        **Authenticated with a dashboard session (browser cookie), not
        `x-api-key`**, and requires `compliance:read` plus the Pro plan or
        above.
      operationId: getComplianceCoverage
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Project id.
        - name: framework
          in: query
          required: true
          schema:
            type: string
            enum:
              - soc2
        - name: periodStart
          in: query
          required: true
          schema:
            type: string
            format: date-time
        - name: periodEnd
          in: query
          required: true
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Per-control coverage for the requested period.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComplianceCoverageResponse'
        '400':
          description: '`periodStart` is not before `periodEnd`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            Not authenticated with a dashboard session, lacks `compliance:read`,
            or plan below Pro.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security: []
components:
  schemas:
    ComplianceCoverageResponse:
      type: object
      properties:
        framework:
          type: string
          enum:
            - soc2
        label:
          type: string
        controls:
          type: array
          items:
            $ref: '#/components/schemas/ControlCoverage'
      required:
        - framework
        - label
        - controls
    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
    ControlCoverage:
      type: object
      properties:
        controlId:
          type: string
          example: CC6.1
        title:
          type: string
        status:
          type: string
          enum:
            - evidence
            - no_evidence
        recordCount:
          type: integer
        sectionsWithEvidence:
          type: array
          items:
            type: string
        sectionsWithoutEvidence:
          type: array
          items:
            type: string
      required:
        - controlId
        - title
        - status
        - recordCount
        - sectionsWithEvidence
        - sectionsWithoutEvidence
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Project API key. Manage keys in the Zespan dashboard under project
        settings.

````