Zespan API

openapi: 3.1.0
info:
  title: Zespan API
  version: '2026-10-19'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-10-19: 12 operation(s) read from 16 public documentation page(s) (each
    operation names its page in x-source). This is not the provider''s published contract; Zespan has published no machine-readable contract that
    the pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 5
    documentation: 7
    pages-with-code: 6
    pages-read: 16
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-10-19'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://docs.zespan.com/reference/model-lifecycle-feed.md
  - https://docs.zespan.com/api-reference/introduction
  - https://docs.zespan.com/api-reference/introduction.md
  - https://docs.zespan.com/api-reference/compliance/generate-an-evidence-pack.md
  - https://docs.zespan.com/api-reference/blast-radius/the-raw-dependency-graph-for-a-project.md
  - https://docs.zespan.com/api-reference/outcomes/report-business-outcomes-attributed-to-traces.md
  - https://docs.zespan.com/api-reference/datasets/run-a-dataset-against-a-registered-http-target.md
  - https://docs.zespan.com/api-reference/policies/org-wide-policy-inventory-grouped-by-policy-id.md
  - https://docs.zespan.com/api-reference/sdk-cli-support/resolve-project-identity-from-an-api-key.md
  - https://docs.zespan.com/api-reference/policies/recent-policy-applies-across-every-project-in-the-org.md
  - https://docs.zespan.com/sdk/cli.md
  - https://docs.zespan.com/guides/webhooks.md
  - https://docs.zespan.com/platform/client-ip.md
  - https://docs.zespan.com/sdk/config-propagation.md
  - https://docs.zespan.com/sdk/outcomes.md
  - https://docs.zespan.com/sdk/agent-tracing.md
servers:
- url: https://api.zespan.com
paths:
  /handle:
    post:
      operationId: post_handle
      tags:
      - Handle
      summary: POST /handle
      x-source: https://docs.zespan.com/sdk/agent-tracing.md
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostHandleRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: javascript
        snippet: "fetch(\"https://refunds-service.internal/handle\", {\n    method: \"POST\",\n    headers,\n    body: JSON.stringify({ orderId:\
          \ \"123\" })"
  /v1/auth/device/code:
    post:
      operationId: post_v1_auth_device_code
      tags:
      - Auth
      summary: POST /v1/auth/device/code
      x-source: https://docs.zespan.com/platform/client-ip.md
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1AuthDeviceCodeRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -sS -X POST https://api.yourdomain.com/v1/auth/device/code  -H \"content-type: application/json\"  -H \"x-forwarded-for:\
          \ 203.0.113.9\"  -d '{\"client_id\":\"zespan-cli\"}'\n    ```"
  /v1/ingest:
    post:
      operationId: post_v1_ingest
      tags:
      - Ingest
      summary: Ingest trace events
      description: Send trace and span events with the native NDJSON endpoint, or via OpenTelemetry.
      x-source: https://docs.zespan.com/api-reference/introduction
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/ingest/outcomes:
    post:
      operationId: post_v1_ingest_outcomes
      tags:
      - Ingest
      summary: POST /v1/ingest/outcomes
      x-source: https://docs.zespan.com/sdk/outcomes.md
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: python
        snippet: "requests.post(\n    \"https://api.zespan.com/v1/ingest/outcomes\",\n    headers={\"x-api-key\": os.environ[\"ZESPAN_API_KEY\"\
          ]},\n    json={\n        \"outcomes\": [{\n            \"kind\": \"ticket_deflected\",\n            \"success\": True,\n           \
          \ \"valueUsd\": 12.50,\n            \"traceId\": trace_id,\n        }]\n    },\n    timeout=10,\n)"
  /v1/model-catalogue:
    get:
      operationId: get_v1_model_catalogue
      tags:
      - Model Catalogue
      summary: GET /v1/model-catalogue returns the full bundled feed — every entry, not scoped to a project — for any project member.
      x-source: https://docs.zespan.com/reference/model-lifecycle-feed.md
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/orgs/{orgid}/policies:
    get:
      operationId: get_v1_orgs_orgid_policies
      tags:
      - Orgs
      summary: Org-wide policy inventory, grouped by policy id
      description: Every policy id enforced (or once enforced) anywhere in the organisation, one group per id, with every project/environment
        occurrence underneath it. Backs the rollup cards and table on Organisation view.
      x-source: https://docs.zespan.com/api-reference/policies/org-wide-policy-inventory-grouped-by-policy-id.md
      parameters:
      - name: orgid
        in: path
        required: true
        schema:
          type: string
      - name: environment
        in: query
        required: false
        schema:
          type: string
        description: Narrow to one environment slug. Mutually exclusive with `productionOnly` — passing both is a 400.
      - name: productionOnly
        in: query
        required: false
        schema:
          type: string
        description: 'Only the literal strings "true" and "false" are accepted — any other value is a 400 schema-validation error, not a silent
          fall-through. "true" narrows to environments with `isProduction: true`; "false" or omitting the parameter leaves the scope at every
          environment. Mutually exclusive with `environment` — passing both (with `productionOnly=true`) is also a 400.'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1OrgsOrgidPoliciesResponse'
      x-evidence:
        kind: documentation
  /v1/orgs/{orgid}/policy-applies:
    get:
      operationId: get_v1_orgs_orgid_policy_applies
      tags:
      - Orgs
      summary: Recent policy applies across every project in the org
      description: 'Every policy apply across every project in the organisation, newest first, cursor-paginated. Backs the **Recent applies**
        section on [Organisation view](/dashboard/policies#organisation-view).


        `origin` is the **entrypoint** that ran the apply — `cli` or `ui` — which is a different fact from a policy''s **owner** (`git` or `zespan`,
        returned as `origin` on an occurrence in the policies response above). A dashboard-authored (`zespan`-owned) policy can be applied by
        either entrypoint, and a `git`-owned policy applied in CI still reports `origin: "cli"` here; never read one field as the other.


        `policyIds` is extracted from the apply''s manifest server-side — the manifest itself is the largest column on the row and is never returned.


        `orgId` in the path selects the scope — see the note on the policies endpoint above; the same resolution applies here.


        **Authenticated with a dashboard session (browser cookie), not `x-api-key`**, and requires the `policy:read` permission, which every role
        (including viewer) has.'
      x-source: https://docs.zespan.com/api-reference/policies/recent-policy-applies-across-every-project-in-the-org.md
      parameters:
      - name: orgid
        in: path
        required: true
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: string
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        description: The `id` of the last apply from the previous page.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1OrgsOrgidPolicyAppliesResponse'
      x-evidence:
        kind: documentation
  /v1/prompts:
    get:
      operationId: get_v1_prompts
      tags:
      - Prompts
      summary: GET /v1/prompts
      x-source: https://docs.zespan.com/api-reference/introduction
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl https://api.zespan.com/v1/prompts  -H \"x-api-key: $ZESPAN_API_KEY \" \n Treat your API key like a password. Set it from\
          \ an environment variable or\nsecret store, never commit it to source control, and rotate it from the\ndashboard if it is exposed. \n\
          \ Create and rotate keys from your project settings in the Zespan dashboard. See\n API keys for details. \n ​ Guardrail policy changes\
          \ are not API-key a"
  /v1/prompts/{name}/versions/{version}/gate:
    post:
      operationId: post_v1_prompts_name_versions_version_gate
      tags:
      - Prompts
      summary: Gate a merge or deploy on a prompt version's evaluation quality
      description: Calls the quality‑gate route used by the dashboard to evaluate a prompt version against a dataset run and evaluator.
      x-source: https://docs.zespan.com/sdk/cli.md
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
      - name: version
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1PromptsNameVersionsVersionGateRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/sdk/config:
    get:
      operationId: get_v1_sdk_config
      tags:
      - Sdk
      summary: If the server version is higher, the SDK makes a single background request to GET /v1/sdk/config and applies the returned configuration
        rules immediately.
      x-source: https://docs.zespan.com/sdk/config-propagation.md
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1SdkConfigResponse'
      x-evidence:
        kind: documentation
  /v2/enqueue:
    post:
      operationId: post_v2_enqueue
      tags:
      - Enqueue
      summary: POST /v2/enqueue
      x-source: https://docs.zespan.com/guides/webhooks.md
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: javascript
        snippet: "fetch(\"https://events.pagerduty.com/v2/enqueue\", {\n  method: \"POST\",\n  headers: {\n    \"Content-Type\": \"application/json\"\
          ,\n    \"Authorization\": `Token token=${process.env.PAGERDUTY_API_KEY}`,\n  },\n  body: JSON.stringify({\n    routing_key: process.env.PAGERDUTY_ROUTING_KEY,\n\
          \    event_action: \"trigger\",\n    payload: {\n      summary: `Zespan: ${alert.rule_name}`,\n      source: alert.project_name,\n \
          \   "
  /webhooks/zespan:
    post:
      operationId: post_webhooks_zespan
      tags:
      - Webhooks
      summary: Webhooks — receive real-time alert notifications
      x-source: https://docs.zespan.com/guides/webhooks.md
      parameters:
      - name: X-Zespan-Signature
        in: header
        required: true
        schema:
          type: string
        description: HMAC‑SHA256 signature for verifying the payload
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostWebhooksZespanRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostWebhooksZespanResponse'
      x-evidence:
        kind: documentation
components:
  schemas:
    PostHandleRequest:
      type: object
      properties:
        orderId:
          type: string
    PostV1AuthDeviceCodeRequest:
      type: object
      properties:
        client_id:
          type: string
    GetV1OrgsOrgidPoliciesResponse:
      type: object
      properties:
        '200':
          type: string
          description: The org's policy inventory in the requested scope.
        '400':
          type: string
          description: Both `environment` and `productionOnly` were passed — they narrow the same axis.
        '403':
          type: string
          description: Not authenticated with a dashboard session, or lacks `policy:read`.
    GetV1OrgsOrgidPolicyAppliesResponse:
      type: object
      properties:
        '200':
          type: string
          description: One page of the org's apply history, newest first.
        '403':
          type: string
          description: Not authenticated with a dashboard session, or lacks `policy:read`.
    PostV1PromptsNameVersionsVersionGateRequest:
      type: object
      properties:
        name:
          type: string
          description: The prompt's name.
        version:
          type: number
          description: The candidate prompt version number to gate.
        dataset-run-id:
          type: string
          description: The dataset run — with the candidate version's traces already linked — to score and compare.
        evaluator-id:
          type: string
          description: The evaluator to use as the judge for both the candidate and baseline runs.
        baseline-run-id:
          type: string
          description: A specific dataset run to compare against. Omit this and `--baseline-label` both to default to the run tied to whatever
            currently holds the `production` label.
        baseline-label:
          type: string
          description: Compare against the run tied to this label instead of `production` (e.g. `staging`).
        connection-id:
          type: string
          description: Pin scoring to a specific project LLM connection (BYOK) instead of the project default.
        regression-run-id:
          type: string
          description: 'Advanced: opt into a separate, optional fourth signal — the regression resolution rate. Pass the ID of a dataset run that
            has replay results from the regression-check flow.'
      required:
      - name
      - version
      - dataset-run-id
      - evaluator-id
    GetV1SdkConfigResponse:
      type: object
      properties:
        config:
          type: object
          description: Current SDK configuration snapshot containing rule types such as model_override, ab_test, fallback, retry, timeout, concurrency,
            cache, sampling, guardrail, rate_limit, and prompt_version.
    PostWebhooksZespanRequest:
      type: object
      properties:
        event:
          type: string
          description: Always "alert.fired" for alert webhooks.
        alert_id:
          type: string
          description: The ID of the alert rule that triggered.
        rule_name:
          type: string
          description: The human‑readable name of the alert rule, as set in the dashboard.
        metric:
          type: string
          description: 'The metric that crossed the threshold: error_rate, cost_usd, latency_ms, request_count, or token_count.'
        condition:
          type: string
          description: 'The comparison that triggered: ">" or "<".'
        threshold:
          type: number
          description: The configured threshold value.
        current_value:
          type: number
          description: The actual metric value at the time of firing.
        window_min:
          type: number
          description: The aggregation window in minutes.
        fired_at:
          type: string
          description: ISO 8601 UTC timestamp when the alert fired.
        dashboard_url:
          type: string
          description: Direct link to the traces page for this project.
        signature:
          type: string
          description: HMAC‑SHA256 signature for verifying the payload.
      required:
      - event
      - alert_id
      - rule_name
      - metric
      - condition
      - threshold
      - current_value
      - window_min
      - fired_at
      - dashboard_url
      - signature
    PostWebhooksZespanResponse:
      type: object
      properties:
        received:
          type: boolean
          description: Indicates successful processing of the webhook.
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
security:
- apiKey: []
tags:
- name: Auth
- name: Enqueue
- name: Handle
- name: Ingest
- name: Model Catalogue
- name: Orgs
- name: Prompts
- name: Sdk
- name: Webhooks