> ## 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. # What breaks if this resource changes > Walks the dependency graph from one root node and returns every dependent found (breadth-first, bounded by `maxDepth`/`maxNodes`), summarized into an impact rollup. Backs the pre-release impact card on the Prompts page and the delete-blocking check on Evaluations. Dependency direction: an edge's `to` depends on its `from` — walking dependents from a node answers "what would be affected if I changed this," which is the reverse of the call direction for prompt/model edges (an agent *calls* a prompt or model, but the *prompt or model change* is what affects the agent, so the edge points prompt→agent / model→agent). **Authenticated with a dashboard session (browser cookie), not `x-api-key`**, and requires the `dashboard:read` permission. There is no server-side cache in front of this endpoint today — every request rebuilds the graph, so `computedAt` in the response is effectively "now." ## OpenAPI ````yaml /api-reference/openapi.yaml get /v1/projects/{id}/blast-radius 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}/blast-radius: get: tags: - Blast Radius summary: What breaks if this resource changes description: > Walks the dependency graph from one root node and returns every dependent found (breadth-first, bounded by `maxDepth`/`maxNodes`), summarized into an impact rollup. Backs the pre-release impact card on the Prompts page and the delete-blocking check on Evaluations. Dependency direction: an edge's `to` depends on its `from` — walking dependents from a node answers "what would be affected if I changed this," which is the reverse of the call direction for prompt/model edges (an agent *calls* a prompt or model, but the *prompt or model change* is what affects the agent, so the edge points prompt→agent / model→agent). **Authenticated with a dashboard session (browser cookie), not `x-api-key`**, and requires the `dashboard:read` permission. There is no server-side cache in front of this endpoint today — every request rebuilds the graph, so `computedAt` in the response is effectively "now." operationId: getBlastRadius parameters: - name: id in: path required: true schema: type: string format: uuid description: Project id. - name: node in: query required: true schema: type: string description: > The root node id, `:` — e.g. `prompt:support-reply` or `evaluator:3f9c2b1a-...`. Keys are names for `prompt`/`agent`/ `model`, UUIDs for row-backed kinds (`policy`, `evaluator`, `dataset`, `alert`). Always passed as a query parameter, never a path segment, since a key can itself contain a colon or slash. example: prompt:support-reply - name: maxDepth in: query schema: type: integer minimum: 1 maximum: 5 default: 3 description: Maximum hops from the root to traverse. - name: windowDays in: query schema: type: integer minimum: 1 maximum: 90 default: 30 description: Lookback window for observed (ClickHouse) call volume and cost. - name: maxNodes in: query schema: type: integer minimum: 1 maximum: 2000 default: 500 description: Maximum total dependents returned before truncating. responses: '200': description: The root node, its dependents, and the summarized impact. content: application/json: schema: $ref: '#/components/schemas/BlastRadiusResponse' '400': description: | Malformed `node` — missing the `:` separator. content: application/json: schema: type: object properties: message: type: string example: >- Malformed node id "support-reply" — expected ":" '403': description: >- Not authenticated with a dashboard session, or lacks `dashboard:read`. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: > `node` is well-formed but doesn't exist in this project's graph — including a well-formed id that belongs to a different project. The two cases are indistinguishable in the response on purpose, so a cross-project id can't be used to probe for a resource's existence. content: application/json: schema: type: object properties: message: type: string example: Node "prompt:does-not-exist" not found in this project security: [] components: schemas: BlastRadiusResponse: type: object properties: root: $ref: '#/components/schemas/BlastRadiusGraphNode' dependents: type: array items: $ref: '#/components/schemas/BlastRadiusDependentEntry' impact: $ref: '#/components/schemas/BlastRadiusImpact' truncated: type: boolean description: > True only when the walk hit `maxDepth`/`maxNodes` AND the graph genuinely continues beyond that point — not merely because the walk stopped exactly at the cap with nothing left beyond it. computedAt: type: string format: date-time description: > When this response's graph was built. There is no server-side cache in front of this endpoint today, so this is effectively "now" on every request. required: - root - dependents - impact - truncated - computedAt 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 BlastRadiusGraphNode: type: object properties: id: type: string description: '`:` — stable across rebuilds.' example: prompt:support-reply kind: $ref: '#/components/schemas/BlastRadiusNodeKind' name: type: string example: support-reply href: type: string description: Relative deep link into the dashboard. example: prompts/support-reply environments: type: array items: type: string description: > Environment slugs this node is known to be associated with. An empty array means genuinely unknown, never "not production." example: - prod - staging required: - id - kind - name - href - environments BlastRadiusDependentEntry: type: object properties: node: $ref: '#/components/schemas/BlastRadiusGraphNode' depth: type: integer description: Hops from the root node. example: 1 via: type: array items: $ref: '#/components/schemas/BlastRadiusGraphEdge' description: > The edge chain from the root to this node. On a node reachable through more than one path, this is only the first inbound edge the server's breadth-first walk happened to record — use `totalCallVolume30d`/`totalCostUsd30d`/`hasObservedTraffic` (below) to decide whether this node has real traffic, not this field's last edge. totalCallVolume30d: type: number description: > Sum of call volume across EVERY inbound edge feeding this node from within the blast radius, not just `via`'s last edge. Per-entry values across the response sum to `impact.callVolume30d`. totalCostUsd30d: type: number description: >- Same aggregation as `totalCallVolume30d`, for cost. Sums to `impact.cost30dUsd`. hasObservedTraffic: type: boolean description: > True when at least one inbound edge within the blast radius is `observed` — real call traffic — even if `via`'s own last edge is `declared`. required: - node - depth - via - totalCallVolume30d - totalCostUsd30d - hasObservedTraffic BlastRadiusImpact: type: object properties: agents: type: integer description: Count of distinct agent-kind dependents. environments: type: array items: type: string description: Union of every dependent's (and the root's) known environments. productionAffected: type: boolean description: >- True if any affected environment is marked production for this project. callVolume30d: type: number description: >- Total observed call volume across every dependent, over the queried window. cost30dUsd: type: number description: Total observed cost across every dependent, over the queried window. slosAtRisk: type: array items: type: string description: > Always an empty array today — reserved for an SLO model that hasn't shipped. Present so the response shape won't need to change later. gates: type: array items: type: string description: Same status as `slosAtRisk` — always empty today, reserved. required: - agents - environments - productionAffected - callVolume30d - cost30dUsd - slosAtRisk - gates BlastRadiusNodeKind: type: string enum: - prompt - agent - policy - evaluator - dataset - model - tool - alert description: > `tool` is a reserved value in the type — no node of this kind is emitted yet (MCP tool calls aren't part of the graph today). BlastRadiusGraphEdge: type: object properties: from: type: string description: The upstream node id. `to` depends on `from`. to: type: string description: The downstream node id — what would be affected if `from` changed. origin: type: string enum: - declared - observed description: > `declared` — configured in your project (Postgres). `observed` — actually called, from real ClickHouse trace data in the queried window. callVolume: type: number description: Call count over the window, for `observed` edges. costUsd: type: number description: Cost in USD over the window, for `observed` edges. lastSeenAt: type: string format: date-time required: - from - to - origin securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Project API key. Manage keys in the Zespan dashboard under project settings. ````