{
  "openapi": "3.1.0",
  "info": {
    "title": "Construct Metrics API",
    "version": "1.0.0-private-beta",
    "summary": "Deterministic metrics for customer-executed AI-agent and LLM evaluations.",
    "description": "The customer runs its own AI agent or LLM workflow and submits only bounded structured observations. Observation status, latency, token counts, cost and check outcomes are customer-reported; Construct does not independently verify their factual truth, execution provenance or provider billing. The API never executes customer commands, calls caller-selected target URLs, accepts prompts or model responses, or relays customer credentials. It returns machine-readable metrics only, never a full report, recommendation, certification or legal opinion."
  },
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
  "servers": [
    {
      "url": "https://www.consilience.work",
      "description": "Production private-beta service"
    }
  ],
  "tags": [
    {
      "name": "Contract",
      "description": "Authenticated schema discovery."
    },
    {
      "name": "Access",
      "description": "Prepaid 60-minute access windows and usage."
    },
    {
      "name": "Metrics",
      "description": "Metrics calculated from customer-reported structured observations."
    }
  ],
  "paths": {
    "/api/construct/v1/schema": {
      "get": {
        "operationId": "getConstructMetricsSchema",
        "tags": ["Contract"],
        "summary": "Read the accepted observation contract",
        "description": "Requires a provisioned client API key. Reading the schema does not consume an evaluation-hour credit.",
        "security": [
          {
            "ClientApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Current closed schema, operations and service boundaries.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SchemaDocument"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/api/construct/v1/sessions": {
      "post": {
        "operationId": "openConstructMetricsSession",
        "tags": ["Access"],
        "summary": "Open one prepaid 60-minute access window",
        "description": "Consumes exactly one prepaid evaluation-hour credit through an atomic ledger update. The access window is consecutive and includes idle time. This operation accepts no request body. Retry with the same Idempotency-Key to receive the same session token without consuming another credit.",
        "security": [
          {
            "ClientApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "201": {
            "description": "Access window opened, or an idempotent replay of the same opening operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "description": "No prepaid evaluation-hour credits remain.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/api/construct/v1/metrics": {
      "post": {
        "operationId": "calculateConstructMetrics",
        "tags": ["Metrics"],
        "summary": "Calculate metrics from structured observations",
        "description": "Requires an active session token. The JSON body is limited to 262144 bytes and 500 cases. Every accepted value is customer-reported. Construct computes deterministic aggregates but does not execute, observe or attest the underlying AI run. The returned SHA-256 identifies the canonical validated payload; it does not prove factual truth, authorship, authenticity, execution provenance or chain of custody.",
        "security": [
          {
            "SessionToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MetricsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculated metrics or an idempotent replay. A full report is never included.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetricsEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "description": "The Idempotency-Key was already used with a different canonical request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "413": {
            "description": "The request body exceeds 262144 bytes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "415": {
            "description": "The request does not use application/json.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "422": {
            "description": "A structured field is invalid, unknown or outside its boundary.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/api/construct/v1/usage": {
      "get": {
        "operationId": "getConstructMetricsUsage",
        "tags": ["Access"],
        "summary": "Read the prepaid evaluation-hour ledger",
        "description": "Returns allocated, consumed and remaining hour credits plus the number of currently active sessions. Reading usage consumes no credit.",
        "security": [
          {
            "ClientApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Current client ledger totals.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UsageEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ClientApiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "opaque client API key",
        "description": "Provisioned manually after the written Order and payment. Send only in the HTTPS Authorization header. Never place the key in a URL, request body, source code or this public contract."
      },
      "SessionToken": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "opaque 60-minute session token",
        "description": "Returned once by POST /sessions for use with POST /metrics during that paid access window. Send only in the HTTPS Authorization header."
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "description": "A unique operation identifier. Use 16 to 128 characters from A-Z, a-z, 0-9, period, underscore, colon and hyphen. Reuse only when retrying the exact same operation.",
        "schema": {
          "type": "string",
          "minLength": 16,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]{16,128}$"
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "The query, body, URL or idempotency contract is invalid.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "The Bearer credential is missing, invalid or expired.",
        "headers": {
          "WWW-Authenticate": {
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "Forbidden": {
        "description": "The client access agreement has expired.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "Unavailable": {
        "description": "The service, configuration or strong-consistency ledger is temporarily unavailable.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      }
    },
    "schemas": {
      "ErrorEnvelope": {
        "type": "object",
        "additionalProperties": false,
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "additionalProperties": false,
            "required": ["code", "message"],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "field": {
                "type": "string"
              }
            }
          }
        }
      },
      "SchemaDocument": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schema_version",
          "service",
          "purpose",
          "accepted_content",
          "prohibited_content",
          "limits",
          "operations",
          "metrics_request",
          "output"
        ],
        "properties": {
          "schema_version": {
            "const": "1.0"
          },
          "service": {
            "const": "Construct Metrics API"
          },
          "purpose": {
            "type": "string"
          },
          "accepted_content": {
            "type": "string"
          },
          "prohibited_content": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "limits": {
            "type": "object",
            "additionalProperties": false,
            "required": ["body_bytes", "cases_per_request", "access_window_minutes"],
            "properties": {
              "body_bytes": {
                "const": 262144
              },
              "cases_per_request": {
                "const": 500
              },
              "access_window_minutes": {
                "const": 60
              }
            }
          },
          "operations": {
            "type": "object",
            "minProperties": 4,
            "maxProperties": 4,
            "additionalProperties": {
              "type": "string"
            }
          },
          "metrics_request": {
            "type": "object",
            "additionalProperties": true
          },
          "output": {
            "type": "object",
            "additionalProperties": false,
            "required": ["report_included", "full_report"],
            "properties": {
              "report_included": {
                "const": false
              },
              "full_report": {
                "type": "string"
              }
            }
          }
        }
      },
      "MetricsRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["run_id", "cases"],
        "description": "Closed, structured observation payload. All observations are supplied by the customer and are not independently witnessed or verified by Construct. Maximum encoded request body: 262144 bytes.",
        "properties": {
          "run_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
            "description": "Opaque non-sensitive customer run identifier."
          },
          "cost_currency": {
            "type": "string",
            "enum": ["EUR", "USD", "GBP"],
            "description": "Required when any case reports cost. Cost remains customer-reported."
          },
          "cases": {
            "type": "array",
            "minItems": 1,
            "maxItems": 500,
            "items": {
              "$ref": "#/components/schemas/CaseObservation"
            }
          }
        }
      },
      "CaseObservation": {
        "type": "object",
        "additionalProperties": false,
        "required": ["case_id", "status", "latency_ms"],
        "description": "A bounded customer-reported observation. It is an input to aggregation, not an independent Construct attestation of an AI execution.",
        "properties": {
          "case_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
          },
          "status": {
            "type": "string",
            "enum": ["pass", "fail", "error", "timeout"],
            "description": "Customer-reported case outcome. Construct does not independently verify its factual truth or provenance."
          },
          "latency_ms": {
            "type": "number",
            "minimum": 0,
            "maximum": 86400000,
            "description": "Finite customer-reported latency in milliseconds."
          },
          "repeat_group": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
          },
          "input_tokens": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000000000,
            "description": "Customer-reported provider token count."
          },
          "output_tokens": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000000000,
            "description": "Customer-reported provider token count."
          },
          "cost": {
            "type": "number",
            "minimum": 0,
            "maximum": 1000000,
            "description": "Customer-reported cost in the request-level cost_currency. Construct does not verify provider billing."
          },
          "tool_checks": {
            "type": "array",
            "maxItems": 32,
            "items": {
              "$ref": "#/components/schemas/ToolCheck"
            }
          },
          "boundary_violations": {
            "type": "array",
            "maxItems": 32,
            "description": "Customer-reported enumerated violations. Duplicate codes in one case are de-duplicated before aggregation.",
            "items": {
              "type": "string",
              "enum": [
                "scope_escape",
                "unauthorized_tool",
                "data_boundary",
                "policy_boundary",
                "instruction_override"
              ]
            }
          },
          "trace": {
            "$ref": "#/components/schemas/TraceObservation"
          }
        }
      },
      "ToolCheck": {
        "type": "object",
        "additionalProperties": false,
        "required": ["name", "passed"],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80,
            "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,79}$"
          },
          "passed": {
            "type": "boolean",
            "description": "Customer-reported check outcome."
          }
        }
      },
      "TraceObservation": {
        "type": "object",
        "additionalProperties": false,
        "required": ["expected_steps", "observed_steps"],
        "description": "Customer-reported trace counts. observed_steps must not exceed expected_steps.",
        "properties": {
          "expected_steps": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100000
          },
          "observed_steps": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100000
          }
        }
      },
      "SessionEnvelope": {
        "type": "object",
        "additionalProperties": false,
        "required": ["session", "idempotent_replay"],
        "properties": {
          "session": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id",
              "token",
              "issued_at",
              "expires_at",
              "access_window_minutes",
              "hours_consumed"
            ],
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^sess_[a-f0-9]{24}$"
              },
              "token": {
                "type": "string",
                "writeOnly": true,
                "description": "Opaque session credential. Store securely and send only in the Authorization header."
              },
              "issued_at": {
                "type": "string",
                "format": "date-time"
              },
              "expires_at": {
                "type": "string",
                "format": "date-time"
              },
              "access_window_minutes": {
                "const": 60
              },
              "hours_consumed": {
                "const": 1
              }
            }
          },
          "idempotent_replay": {
            "type": "boolean"
          }
        }
      },
      "UsageEnvelope": {
        "type": "object",
        "additionalProperties": false,
        "required": ["usage"],
        "properties": {
          "usage": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "client_id",
              "allocated_hours",
              "consumed_hours",
              "remaining_hours",
              "active_sessions",
              "metering"
            ],
            "properties": {
              "client_id": {
                "type": "string"
              },
              "allocated_hours": {
                "type": "integer",
                "minimum": 0
              },
              "consumed_hours": {
                "type": "integer",
                "minimum": 0
              },
              "remaining_hours": {
                "type": "integer",
                "minimum": 0
              },
              "active_sessions": {
                "type": "integer",
                "minimum": 0
              },
              "metering": {
                "type": "string"
              }
            }
          }
        }
      },
      "MetricsEnvelope": {
        "type": "object",
        "additionalProperties": false,
        "required": ["metrics", "idempotent_replay"],
        "properties": {
          "metrics": {
            "$ref": "#/components/schemas/MetricsResult"
          },
          "idempotent_replay": {
            "type": "boolean"
          }
        }
      },
      "MetricsResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schema_version",
          "run_id",
          "case_count",
          "status",
          "latency_ms",
          "repeat_stability",
          "tokens_reported",
          "cost_reported",
          "tool_checks",
          "boundary_violations",
          "trace_completeness",
          "integrity",
          "report_included"
        ],
        "properties": {
          "schema_version": {
            "const": "1.0"
          },
          "run_id": {
            "type": "string"
          },
          "case_count": {
            "type": "integer",
            "minimum": 1,
            "maximum": 500
          },
          "status": {
            "$ref": "#/components/schemas/StatusMetrics"
          },
          "latency_ms": {
            "type": "object",
            "additionalProperties": false,
            "required": ["p50", "p95", "max"],
            "properties": {
              "p50": {
                "type": "number",
                "minimum": 0
              },
              "p95": {
                "type": "number",
                "minimum": 0
              },
              "max": {
                "type": "number",
                "minimum": 0
              }
            }
          },
          "repeat_stability": {
            "type": "object",
            "additionalProperties": false,
            "required": ["eligible_groups", "stable_groups", "stability_rate"],
            "properties": {
              "eligible_groups": {
                "type": "integer",
                "minimum": 0
              },
              "stable_groups": {
                "type": "integer",
                "minimum": 0
              },
              "stability_rate": {
                "type": ["number", "null"],
                "minimum": 0,
                "maximum": 1
              }
            }
          },
          "tokens_reported": {
            "type": "object",
            "additionalProperties": false,
            "required": ["cases", "input", "output", "total"],
            "description": "Sums of customer-reported token values; not independently verified provider usage.",
            "properties": {
              "cases": {"type": "integer", "minimum": 0},
              "input": {"type": "integer", "minimum": 0},
              "output": {"type": "integer", "minimum": 0},
              "total": {"type": "integer", "minimum": 0}
            }
          },
          "cost_reported": {
            "type": "object",
            "additionalProperties": false,
            "required": ["cases", "currency", "total"],
            "description": "Sum of customer-reported cost values; not independently verified provider billing.",
            "properties": {
              "cases": {"type": "integer", "minimum": 0},
              "currency": {
                "type": ["string", "null"],
                "enum": ["EUR", "USD", "GBP", null]
              },
              "total": {"type": "number", "minimum": 0}
            }
          },
          "tool_checks": {
            "type": "object",
            "additionalProperties": false,
            "required": ["total", "passed", "failed", "pass_rate"],
            "properties": {
              "total": {"type": "integer", "minimum": 0},
              "passed": {"type": "integer", "minimum": 0},
              "failed": {"type": "integer", "minimum": 0},
              "pass_rate": {"type": ["number", "null"], "minimum": 0, "maximum": 1}
            }
          },
          "boundary_violations": {
            "type": "object",
            "additionalProperties": false,
            "required": ["total", "cases_affected", "by_code"],
            "properties": {
              "total": {"type": "integer", "minimum": 0},
              "cases_affected": {"type": "integer", "minimum": 0},
              "by_code": {
                "$ref": "#/components/schemas/BoundaryCounts"
              }
            }
          },
          "trace_completeness": {
            "type": "object",
            "additionalProperties": false,
            "required": ["cases", "expected_steps", "observed_steps", "completeness_rate"],
            "properties": {
              "cases": {"type": "integer", "minimum": 0},
              "expected_steps": {"type": "integer", "minimum": 0},
              "observed_steps": {"type": "integer", "minimum": 0},
              "completeness_rate": {"type": ["number", "null"], "minimum": 0, "maximum": 1}
            }
          },
          "integrity": {
            "type": "object",
            "additionalProperties": false,
            "required": ["algorithm", "canonical_sha256"],
            "description": "Payload identity only. The digest detects a changed canonical validated payload; it does not prove factual truth, authenticity, authorship, execution provenance or chain of custody.",
            "properties": {
              "algorithm": {
                "const": "SHA-256"
              },
              "canonical_sha256": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              }
            }
          },
          "report_included": {
            "const": false,
            "description": "Always false. Human-reviewed analysis and the full report are separate Construct services."
          }
        }
      },
      "StatusMetrics": {
        "type": "object",
        "additionalProperties": false,
        "required": ["counts", "pass_rate", "failure_rate", "error_rate", "timeout_rate"],
        "description": "Aggregates customer-reported statuses. They are not independent execution evidence.",
        "properties": {
          "counts": {
            "type": "object",
            "additionalProperties": false,
            "required": ["pass", "fail", "error", "timeout"],
            "properties": {
              "pass": {"type": "integer", "minimum": 0},
              "fail": {"type": "integer", "minimum": 0},
              "error": {"type": "integer", "minimum": 0},
              "timeout": {"type": "integer", "minimum": 0}
            }
          },
          "pass_rate": {"type": "number", "minimum": 0, "maximum": 1},
          "failure_rate": {"type": "number", "minimum": 0, "maximum": 1},
          "error_rate": {"type": "number", "minimum": 0, "maximum": 1},
          "timeout_rate": {"type": "number", "minimum": 0, "maximum": 1}
        }
      },
      "BoundaryCounts": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "data_boundary",
          "instruction_override",
          "policy_boundary",
          "scope_escape",
          "unauthorized_tool"
        ],
        "properties": {
          "data_boundary": {"type": "integer", "minimum": 0},
          "instruction_override": {"type": "integer", "minimum": 0},
          "policy_boundary": {"type": "integer", "minimum": 0},
          "scope_escape": {"type": "integer", "minimum": 0},
          "unauthorized_tool": {"type": "integer", "minimum": 0}
        }
      }
    }
  },
  "x-construct-limits": {
    "max_body_bytes": 262144,
    "max_cases": 500,
    "access_window_minutes": 60,
    "report_included": false
  },
  "x-construct-boundaries": {
    "accepts_structured_observations_only": true,
    "executes_customer_commands": false,
    "calls_customer_targets": false,
    "accepts_prompts_or_model_responses": false,
    "accepts_customer_credentials_in_payload": false,
    "customer_reported_observations": true,
    "sha256_proves_payload_identity_only": true
  }
}