{"openapi":"3.1.0","info":{"title":"AgentAudit Ingestion API","version":"1.0.0","summary":"Public HTTP API for submitting agent traces, telemetry events, evaluation reports, audit entries, and running governance promotion checks.","description":"All endpoints authenticate with a tenant ingestion key issued from the AgentAudit portal (Admin → Ingestion keys). Send it as `Authorization: Bearer aa_live_...`. Keys are scoped — a key without the required scope receives 401. Rotate keys any time; audit entries are hash-chained for tamper-evidence.","contact":{"name":"AgentAudit","url":"https://agentauditcentral.co.uk"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://agentauditcentral.co.uk","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Traces","description":"Rich per-step trace ingestion — prompts, tool calls, tokens, cost."},{"name":"Telemetry","description":"Lightweight run-summary events."},{"name":"Evaluations","description":"CI-style evaluation results for agents and harnesses."},{"name":"Audit","description":"Hash-chained governance audit entries."},{"name":"Governance","description":"Pre-deployment / pre-promotion gates."}],"paths":{"/api/public/traces":{"post":{"tags":["Traces"],"summary":"Submit a full trace with spans","description":"Ingest a trace summary plus an ordered array of spans (LLM calls, tool calls, retrieval, guardrails). Token and cost totals are aggregated server-side from spans when not supplied at the trace level. Requires the `telemetry` scope.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Trace"}}}},"responses":{"200":{"description":"Trace ingested","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"id":{"type":"string","format":"uuid"},"trace_id":{"type":"string"},"spans_ingested":{"type":"integer"},"tokens":{"type":"integer","nullable":true},"cost_usd":{"type":"number","nullable":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/api/public/telemetry":{"post":{"tags":["Telemetry"],"summary":"Emit run-summary telemetry event(s)","description":"Legacy lightweight endpoint. Accepts either a single event or `{ events: [...] }` batch (max 200). Prefer `/api/public/traces` when you can capture per-step data. Requires the `telemetry` scope.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/TelemetryEvent"},{"type":"object","required":["events"],"properties":{"events":{"type":"array","minItems":1,"maxItems":200,"items":{"$ref":"#/components/schemas/TelemetryEvent"}}}}]}}}},"responses":{"200":{"description":"Ingested","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"ingested":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/api/public/evaluations":{"post":{"tags":["Evaluations"],"summary":"Report an evaluation result","description":"Post the outcome of an offline eval / harness run. Use `agent_name` for auto-provisioning if the agent is not registered yet. Requires the `evaluations` scope.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Evaluation"}}}},"responses":{"200":{"description":"Recorded","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"id":{"type":"string","format":"uuid"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/api/public/audit":{"post":{"tags":["Audit"],"summary":"Append a hash-chained audit entry","description":"Append an immutable audit entry. Each row's `row_hash` chains to the previous entry's hash for tamper-evidence. Requires the `audit` scope.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditEntry"}}}},"responses":{"200":{"description":"Appended","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"id":{"type":"string","format":"uuid"},"row_hash":{"type":"string"},"prev_hash":{"type":"string","nullable":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/api/public/governance/promotion-check":{"post":{"tags":["Governance"],"summary":"Pre-promotion gate for an agent","description":"Returns `{ allowed: false }` when the agent has no recent passing evaluation. Wire this into CI/CD before deploying an agent to production. Requires the `governance` scope.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromotionCheck"}}}},"responses":{"200":{"description":"Decision","content":{"application/json":{"schema":{"type":"object","properties":{"allowed":{"type":"boolean"},"reason":{"type":"string"},"message":{"type":"string"},"threshold":{"type":"number"},"evaluation":{"type":"object","additionalProperties":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"aa_live_...","description":"Tenant ingestion key issued from Admin → Ingestion keys."}},"responses":{"Unauthorized":{"description":"Missing, invalid, or under-scoped API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ValidationError":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"issues":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"Message":{"type":"object","required":["role"],"properties":{"role":{"type":"string","enum":["system","user","assistant","tool","developer"]},"content":{"oneOf":[{"type":"string"},{"type":"array","items":{}}]},"name":{"type":"string"},"tool_call_id":{"type":"string"},"tool_calls":{"type":"array","items":{}}}},"Span":{"type":"object","required":["span_id","kind","name"],"properties":{"span_id":{"type":"string"},"parent_span_id":{"type":"string"},"kind":{"type":"string","enum":["agent","llm","tool","retrieval","guardrail","other"]},"name":{"type":"string"},"status":{"type":"string","default":"success"},"model":{"type":"string","example":"gpt-5.5"},"provider":{"type":"string","example":"openai"},"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"},"cost_usd":{"type":"number"},"input":{},"output":{},"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"tool_arguments":{},"tool_result":{},"error":{"type":"string"},"latency_ms":{"type":"integer"},"started_at":{"type":"string","format":"date-time"},"ended_at":{"type":"string","format":"date-time"},"metadata":{"type":"object","additionalProperties":true}}},"Trace":{"type":"object","required":["trace_id"],"properties":{"trace_id":{"type":"string","description":"Client-generated stable ID for this run."},"outcome":{"type":"string","enum":["success","failure","escalated","blocked"],"default":"success"},"agent_id":{"type":"string","format":"uuid"},"agent_name":{"type":"string","description":"Auto-provisions an agent record if unknown."},"session_id":{"type":"string"},"external_user_id":{"type":"string","description":"Your app's user identifier — never PII."},"latency_ms":{"type":"integer"},"detail":{"type":"string"},"error":{"type":"string"},"started_at":{"type":"string","format":"date-time"},"ended_at":{"type":"string","format":"date-time"},"metadata":{"type":"object","additionalProperties":true},"spans":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/Span"}}}},"TelemetryEvent":{"type":"object","required":["trace_id","outcome"],"properties":{"trace_id":{"type":"string"},"outcome":{"type":"string"},"status":{"type":"string"},"latency_ms":{"type":"integer"},"tool_count":{"type":"integer"},"detail":{"type":"string"},"agent_id":{"type":"string","format":"uuid"},"agent_name":{"type":"string"},"model":{"type":"string"},"provider":{"type":"string"},"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"},"cost_usd":{"type":"number"},"input":{},"output":{},"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"error":{"type":"string"},"session_id":{"type":"string"},"external_user_id":{"type":"string"},"metadata":{"type":"object","additionalProperties":true},"started_at":{"type":"string","format":"date-time"},"ended_at":{"type":"string","format":"date-time"}}},"Evaluation":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"agent_id":{"type":"string","format":"uuid"},"agent_name":{"type":"string"},"harness_id":{"type":"string","format":"uuid"},"category":{"type":"string","example":"safety"},"status":{"type":"string","enum":["scheduled","running","passing","failing"],"default":"passing"},"pass_rate":{"type":"number","minimum":0,"maximum":100},"notes":{"type":"string"},"severity_threshold":{"type":"number"}}},"AuditEntry":{"type":"object","required":["actor","action"],"properties":{"actor":{"type":"string","example":"ci@example.com"},"action":{"type":"string","example":"agent.promote"},"subject":{"type":"string","example":"agent:billing-copilot"},"rationale":{"type":"string"},"framework":{"type":"string","example":"EU AI Act Art. 15"},"trace_id":{"type":"string"},"agent_id":{"type":"string","format":"uuid"},"retention_until":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"metadata":{"type":"object","additionalProperties":true}}},"PromotionCheck":{"type":"object","properties":{"agent_id":{"type":"string","format":"uuid"},"agent_name":{"type":"string"},"harness_id":{"type":"string","format":"uuid"},"min_pass_rate":{"type":"number","minimum":0,"maximum":100,"default":80},"max_age_hours":{"type":"integer","minimum":1,"maximum":8760,"default":72}},"description":"Provide either agent_id or agent_name."}}}}