openapi: 3.1.0
info:
  title: AgentProvenance read API
  version: "1.0"
  description: >
    Read-only surface of the AgentProvenance daemon, for AI agents and tools to
    query the verifiable provenance graph, signals, and timeline. Maps 1:1 to
    docs/ai-access.md section 1. Write/gate operations are intentionally excluded
    here (see the trust boundary in docs/ai-access.md).
servers:
  - url: http://127.0.0.1:8574
    description: local sidecar daemon (agentprov daemon serve)
security:
  - bearerAuth: []
  - {}
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: optional; set when the daemon runs with --auth-token
  parameters:
    run:
      name: run
      in: query
      required: true
      schema: { type: string }
      description: run id to scope the query to
  schemas:
    VerifyResult:
      type: object
      required: [schema_version, run_id, status, issue_count, error_count, warning_count, issues]
      properties:
        schema_version: { type: string, enum: [agentprovenance.verify/v1] }
        run_id: { type: string }
        status: { type: string, enum: [ok, failed, unavailable] }
        issue_count: { type: integer, minimum: 0 }
        error_count: { type: integer, minimum: 0 }
        warning_count: { type: integer, minimum: 0 }
        error: { type: string, description: Operational error when verification could not finish. Issue counts cover completed checks only. }
        issues:
          type: [array, "null"]
          items:
            type: object
            required: [severity, kind, id, message]
            properties:
              severity: { type: string, enum: [error, warning] }
              kind: { type: string }
              id: { type: string }
              message: { type: string }
    VersionedEnvelope:
      type: object
      description: every response carries a schema_version naming its contract
      properties:
        schema_version: { type: string }
      additionalProperties: true
    DaemonHealth:
      type: object
      required: [schema_version, status, ready, checks, coverage_status]
      properties:
        schema_version: { type: string, enum: [agentprovenance.daemon_health/v1] }
        status: { type: string, enum: [ok, degraded, unavailable] }
        ready: { type: boolean, description: Database queries and schema checks succeeded; independent of historical evidence loss. }
        coverage_status: { type: string, enum: [unknown, not_observed, no_recorded_gaps, pending, gaps_recorded] }
        checks: { type: object, additionalProperties: { type: object } }
        queued_spool: { type: [integer, "null"] }
        queued_spool_bytes: { type: [integer, "null"] }
        native_capture: { type: object, additionalProperties: true }
      additionalProperties: true
paths:
  /v1/telemetry/audit-associations:
    $ref: './audit-associations-api.yaml#/paths/~1v1~1telemetry~1audit-associations'
  /api/audit/associations:
    $ref: './audit-associations-api.yaml#/paths/~1api~1audit~1associations'
  /api/compare/records:
    $ref: './agent-context-api.yaml#/paths/~1api~1compare~1records'
  /api/search/sources:
    $ref: './agent-context-api.yaml#/paths/~1api~1search~1sources'
  /api/artifact:
    $ref: './agent-context-api.yaml#/paths/~1api~1artifact'
  /v1/context/overview:
    $ref: './agent-context-api.yaml#/paths/~1v1~1context~1overview'
  /v1/context/entries:
    $ref: './agent-context-api.yaml#/paths/~1v1~1context~1entries'
  /v1/context/content:
    $ref: './agent-context-api.yaml#/paths/~1v1~1context~1content'
  /v1/context/compare:
    $ref: './agent-context-api.yaml#/paths/~1v1~1context~1compare'
  /v1/context/links:
    $ref: './agent-context-api.yaml#/paths/~1v1~1context~1links'
  /v1/health:
    get:
      operationId: health
      summary: daemon readiness + queue depths (agentprovenance.daemon_health/v1)
      security: [ {} ]
      responses:
        "200": { description: Ready; historical gaps are reported separately, content: { application/json: { schema: { $ref: "#/components/schemas/DaemonHealth" } } } }
        "503": { description: "Storage unavailable, schema mismatch, or the bounded check timed out", content: { application/json: { schema: { $ref: "#/components/schemas/DaemonHealth" } } } }
  /v1/ready:
    get:
      operationId: readiness
      summary: Same readiness contract as /v1/health; checks have a two-second timeout
      security: [ {} ]
      responses:
        "200": { description: Ready or ready with recorded degradation, content: { application/json: { schema: { $ref: "#/components/schemas/DaemonHealth" } } } }
        "503": { description: Not ready, content: { application/json: { schema: { $ref: "#/components/schemas/DaemonHealth" } } } }
  /v1/live:
    get:
      operationId: liveness
      summary: Process responsiveness only; no database or queue checks
      security: [ {} ]
      responses:
        "200":
          description: Process is responding
          content:
            application/json:
              schema:
                type: object
                required: [schema_version, status]
                properties:
                  schema_version: { type: string, enum: [agentprovenance.daemon_liveness/v1] }
                  status: { type: string, enum: [ok] }
  /v1/graph/verify:
    get:
      operationId: verify_run
      summary: verify a run's evidence chain (object hashes, parents, policy->risk->response->signal). agentprovenance.verify/v1
      parameters: [ { $ref: "#/components/parameters/run" } ]
      responses:
        "200": { description: Completed verification with status ok or failed, content: { application/json: { schema: { $ref: "#/components/schemas/VerifyResult" } } } }
        "503": { description: Verification could not finish; status unavailable preserves the operational error, content: { application/json: { schema: { $ref: "#/components/schemas/VerifyResult" } } } }
  /v1/graph/explain:
    get:
      operationId: explain
      summary: explain one graph node (causality path, evidence). agentprovenance.explain/v1
      parameters:
        - { name: event, in: query, schema: { type: string } }
        - { name: process, in: query, schema: { type: string } }
        - { name: tool-call, in: query, schema: { type: string } }
        - { name: file, in: query, schema: { type: string } }
        - { name: risk, in: query, schema: { type: string } }
        - { name: artifact, in: query, schema: { type: string } }
        - { name: run, in: query, schema: { type: string }, description: required with file }
      responses:
        "200": { description: explanation, content: { application/json: { schema: { $ref: "#/components/schemas/VersionedEnvelope" } } } }
  /v1/signals:
    get:
      operationId: get_signals
      summary: unified signals (behavior/cost/quality/security). agentprovenance.signals/v1
      parameters: [ { $ref: "#/components/parameters/run" } ]
      responses:
        "200": { description: signal set, content: { application/json: { schema: { $ref: "#/components/schemas/VersionedEnvelope" } } } }
  /v1/timeline:
    get:
      operationId: get_timeline
      summary: merged app-context + runtime-telemetry timeline. agentprovenance.timeline/v1
      parameters: [ { $ref: "#/components/parameters/run" }, { name: view, in: query, schema: { type: string, enum: [table, causality] } } ]
      responses:
        "200": { description: timeline, content: { application/json: { schema: { $ref: "#/components/schemas/VersionedEnvelope" } } } }
  /v1/observe/summary:
    get:
      operationId: observe_summary
      summary: per-run observability summary. agentprovenance.observability_summary/v1
      parameters: [ { $ref: "#/components/parameters/run" } ]
      responses:
        "200": { description: summary, content: { application/json: { schema: { $ref: "#/components/schemas/VersionedEnvelope" } } } }
  /v1/security/risks:
    get:
      operationId: list_risks
      summary: risk signals for a run. agentprovenance.security_risks/v1
      parameters: [ { $ref: "#/components/parameters/run" } ]
      responses:
        "200": { description: risks, content: { application/json: { schema: { $ref: "#/components/schemas/VersionedEnvelope" } } } }
  /v1/security/responses:
    get:
      operationId: list_responses
      summary: response actions for a run. agentprovenance.security_responses/v1
      parameters: [ { $ref: "#/components/parameters/run" } ]
      responses:
        "200": { description: responses, content: { application/json: { schema: { $ref: "#/components/schemas/VersionedEnvelope" } } } }
  /v1/security/deviations:
    get:
      operationId: list_deviations
      summary: baseline deviations for a run
      parameters: [ { $ref: "#/components/parameters/run" } ]
      responses:
        "200": { description: deviations, content: { application/json: { schema: { $ref: "#/components/schemas/VersionedEnvelope" } } } }
  /v1/telemetry/events:
    get:
      operationId: list_events
      summary: paged runtime telemetry events. agentprovenance.telemetry_events/v1
      parameters:
        - { $ref: "#/components/parameters/run" }
        - { name: type, in: query, schema: { type: string } }
        - { name: limit, in: query, schema: { type: integer } }
        - { name: cursor, in: query, schema: { type: string } }
      responses:
        "200": { description: event page, content: { application/json: { schema: { $ref: "#/components/schemas/VersionedEnvelope" } } } }
  /v1/telemetry/windows:
    get:
      operationId: list_windows
      summary: 10s/60s telemetry aggregation windows. agentprovenance.telemetry_event_windows/v1
      parameters: [ { $ref: "#/components/parameters/run" } ]
      responses:
        "200": { description: windows, content: { application/json: { schema: { $ref: "#/components/schemas/VersionedEnvelope" } } } }
  /v1/telemetry/correlations:
    get:
      operationId: explain_correlations
      summary: how runtime events mapped to ToolCallScope bindings. agentprovenance.telemetry_correlations/v1
      parameters: [ { $ref: "#/components/parameters/run" }, { name: event, in: query, schema: { type: string } } ]
      responses:
        "200": { description: correlation evidence, content: { application/json: { schema: { $ref: "#/components/schemas/VersionedEnvelope" } } } }
  /v1/telemetry/producer-health:
    get:
      operationId: telemetry_producer_health
      summary: bounded spool, drop, source, and correlation coverage health. agentprovenance.producer_health/v1
      parameters:
        - { name: run, in: query, required: false, schema: { type: string } }
      responses:
        "200": { description: producer health report, content: { application/json: { schema: { $ref: "#/components/schemas/VersionedEnvelope" } } } }