{
  "openapi": "3.0.3",
  "info": {
    "title": "Intertrace Telemetry API",
    "version": "0.1.0",
    "description": "Ingest observable traces (spans) for policy evaluation and scoring. Authenticate with Authorization: Bearer and your Bastion API key."
  },
  "servers": [{ "url": "/", "description": "Same origin as the Next.js app" }],
  "paths": {
    "/api/v1/telemetry/traces": {
      "post": {
        "summary": "Ingest a trace",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "schema": { "type": "string" },
            "description": "Optional idempotency token for safe retries"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/TelemetryTraceBody" }
            }
          }
        },
        "responses": {
          "201": { "description": "Created" },
          "200": { "description": "Idempotent replay — trace already existed" },
          "401": { "description": "Unauthorized" },
          "422": { "description": "Validation error" }
        }
      },
      "get": {
        "summary": "List recent traces (session cookie)",
        "responses": {
          "200": { "description": "OK" },
          "401": { "description": "Unauthorized" }
        }
      }
    },
    "/api/v1/telemetry/traces/{id}": {
      "get": {
        "summary": "Trace detail with spans (session cookie)",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": {
          "200": { "description": "OK" },
          "404": { "description": "Not found" }
        }
      }
    },
    "/api/v1/telemetry/test-connection": {
      "post": {
        "summary": "Verify API key",
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": { "description": "ok: true" },
          "401": { "description": "Invalid key" }
        }
      }
    },
    "/api/cron/baseline-rollup": {
      "post": {
        "summary": "Daily baseline rollup (CRON_SECRET)",
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "schema": { "type": "string" },
            "description": "Bearer CRON_SECRET"
          }
        ],
        "responses": {
          "200": { "description": "OK" },
          "401": { "description": "Unauthorized" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "bst_…"
      }
    },
    "schemas": {
      "TelemetryTraceBody": {
        "type": "object",
        "required": ["trace", "spans"],
        "properties": {
          "trace": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "metadata": { "type": "object", "additionalProperties": true },
              "asset_id": { "type": "string", "format": "uuid" },
              "intent": { "type": "object", "additionalProperties": true }
            }
          },
          "spans": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["name", "kind", "start_time", "end_time"],
              "properties": {
                "name": { "type": "string" },
                "kind": { "type": "string", "enum": ["llm", "tool", "chain", "retrieval"] },
                "start_time": { "type": "string", "format": "date-time" },
                "end_time": { "type": "string", "format": "date-time" },
                "attributes": { "type": "object", "additionalProperties": true },
                "parent_span_id": { "type": "string", "format": "uuid", "nullable": true }
              }
            }
          },
          "policy": { "type": "object", "additionalProperties": true }
        }
      }
    }
  }
}