{
  "openapi": "3.1.0",
  "info": {
    "title": "behave.run API",
    "version": "1.0.0",
    "summary": "Automate observable agent decision experiments.",
    "description": "The behave.run JSON API creates and manages tenant-scoped experiments, reports, evidence, raw exchanges, artifacts, and personal API keys. Authenticate with a signed user session or a bearer API key. Personal keys can be issued and revoked in Connection settings; key-management endpoints themselves require a signed user session."
  },
  "externalDocs": { "description": "API guide and runnable examples", "url": "/docs/api" },
  "servers": [
    { "url": "/", "description": "Current deployment" },
    { "url": "http://127.0.0.1:8787", "description": "Local development" }
  ],
  "tags": [
    { "name": "Authentication", "description": "Account entry and current-session information." },
    { "name": "Account", "description": "Account profile and personal API-key management." },
    { "name": "Experiments", "description": "Experiment lifecycle, polling, retries, and archival." },
    { "name": "Evidence", "description": "Tenant-scoped raw exchanges and retained artifacts." },
    { "name": "System", "description": "Provider, queue, harness, and isolation readiness." },
    { "name": "Credentials", "description": "Legacy tenant credential vault operations." },
    { "name": "Administration", "description": "Administrator-only deployment operations." }
  ],
  "security": [{ "bearerAuth": [] }],
  "paths": {
    "/api/auth/config": {
      "get": {
        "tags": ["Authentication"],
        "operationId": "getAuthenticationConfig",
        "summary": "Get public account-entry configuration",
        "security": [],
        "responses": {
          "200": {
            "description": "Authentication configuration",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthConfig" }, "example": { "registrationEnabled": true } } }
          }
        }
      }
    },
    "/api/auth/register": {
      "post": {
        "tags": ["Authentication"],
        "operationId": "registerUser",
        "summary": "Register an account",
        "description": "Creates an isolated tenant account when registration is enabled.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterRequest" }, "example": { "name": "Ada Lovelace", "email": "ada@example.com", "password": "a-long-unique-password" } } }
        },
        "responses": {
          "201": { "$ref": "#/components/responses/AuthSuccess" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/auth/login": {
      "post": {
        "tags": ["Authentication"],
        "operationId": "loginUser",
        "summary": "Create a signed user session",
        "security": [],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" }, "example": { "email": "ada@example.com", "password": "a-long-unique-password" } } }
        },
        "responses": {
          "200": { "$ref": "#/components/responses/AuthSuccess" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/auth/me": {
      "get": {
        "tags": ["Authentication"],
        "operationId": "getCurrentAccount",
        "summary": "Get the current authentication context",
        "description": "A signed user session receives a renewed token. API-key authentication never returns a user-session token.",
        "responses": {
          "200": {
            "description": "Current authentication context",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentAccount" } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/account": {
      "patch": {
        "tags": ["Account"],
        "operationId": "updateAccount",
        "summary": "Update the current account profile",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 100 } } }, "example": { "name": "Ada Lovelace" } } }
        },
        "responses": {
          "200": { "description": "Updated account", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/PublicUser" } } } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/account/password": {
      "put": {
        "tags": ["Account"],
        "operationId": "changePassword",
        "summary": "Change the current account password",
        "description": "Requires a signed user session. Changing a password invalidates prior sessions.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "required": ["currentPassword", "nextPassword"], "properties": { "currentPassword": { "type": "string" }, "nextPassword": { "type": "string", "minLength": 10, "maxLength": 256 } } } } }
        },
        "responses": {
          "200": { "$ref": "#/components/responses/AuthSuccess" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/api/account/api-keys": {
      "get": {
        "tags": ["Account"],
        "operationId": "listApiKeys",
        "summary": "List personal API keys",
        "description": "Requires a signed user session. Secret values and key digests are never returned.",
        "responses": {
          "200": { "description": "Personal API keys", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountApiKey" } } } } },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      },
      "post": {
        "tags": ["Account"],
        "operationId": "issueApiKey",
        "summary": "Issue a personal API key",
        "description": "Requires a signed user session. The secret is returned exactly once. Store it securely before dismissing the response.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueApiKeyRequest" }, "example": { "name": "Release automation" } } }
        },
        "responses": {
          "201": {
            "description": "API key issued",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueApiKeyResponse" }, "example": { "apiKey": { "id": "key_0123456789abcdef", "name": "Release automation", "prefix": "brk_example1…", "createdAt": "2026-01-01T00:00:00.000Z", "scopes": ["artifacts:read", "experiments:read", "experiments:write", "traces:raw"] }, "secret": "brk_example_one_time_secret" } } }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "409": { "$ref": "#/components/responses/Conflict" }
        }
      }
    },
    "/api/account/api-keys/{keyId}": {
      "delete": {
        "tags": ["Account"],
        "operationId": "revokeApiKey",
        "summary": "Revoke a personal API key",
        "description": "Requires a signed user session. Revocation takes effect immediately.",
        "parameters": [{ "$ref": "#/components/parameters/KeyId" }],
        "responses": {
          "204": { "description": "API key revoked" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/health": {
      "get": {
        "tags": ["System"],
        "operationId": "getHealth",
        "summary": "Get provider and execution readiness",
        "parameters": [{ "name": "refresh", "in": "query", "description": "Set to 1 to bypass the tenant health cache.", "schema": { "type": "string", "enum": ["1"] } }],
        "responses": {
          "200": { "description": "Health and capability report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/experiments": {
      "get": {
        "tags": ["Experiments"],
        "operationId": "listExperiments",
        "summary": "List tenant experiments",
        "description": "Use view=summary for bounded pagination. Without it, the endpoint returns complete records for compatibility.",
        "parameters": [
          { "name": "view", "in": "query", "schema": { "type": "string", "enum": ["summary"] } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 50 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }
        ],
        "responses": {
          "200": {
            "description": "Summary page or complete experiment records",
            "content": { "application/json": { "schema": { "oneOf": [{ "$ref": "#/components/schemas/ExperimentSummaryPage" }, { "type": "array", "items": { "$ref": "#/components/schemas/ExperimentRecord" } }] } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      },
      "post": {
        "tags": ["Experiments"],
        "operationId": "createExperiment",
        "summary": "Validate and enqueue an experiment",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateExperimentRequest" },
              "examples": {
                "packageSelection": {
                  "summary": "Compare TypeScript MCP SDKs with npm verification",
                  "value": {
                    "scenario": {
                      "task": "Choose an MCP TypeScript SDK for a new server.",
                      "alternatives": ["Model Context Protocol SDK", "FastMCP"],
                      "successCriteria": "Must support TypeScript and stdio transports.",
                      "executionContract": {
                        "kind": "npm-package",
                        "method": "GET",
                        "requireHttp2xx": true,
                        "requireJson": true,
                        "requireNonEmpty": true,
                        "forbidErrorEnvelope": false,
                        "requiredJsonFields": [],
                        "productTargets": {
                          "Model Context Protocol SDK": ["npm:@modelcontextprotocol/sdk"],
                          "FastMCP": ["npm:fastmcp"]
                        }
                      }
                    },
                    "config": { "trials": 3, "agent": "codex", "provider": "openai-codex", "model": "gpt-5.6-luna", "thinkingLevel": "low", "maxRunMs": 300000, "maxBudgetUsd": 5 }
                  }
                },
                "selectionOnly": {
                  "summary": "Selection-only experiment",
                  "value": {
                    "scenario": {
                      "task": "Choose a documented hosted search API.",
                      "successCriteria": "Must support a read-only prototype.",
                      "executionContract": { "kind": "selection-only", "method": "GET", "requireHttp2xx": true, "requireJson": false, "requireNonEmpty": true, "forbidErrorEnvelope": false, "requiredJsonFields": [], "productTargets": {} }
                    },
                    "config": { "trials": 3, "model": "gpt-5.6-luna", "thinkingLevel": "low" }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": { "description": "Experiment accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentRecord" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "402": { "description": "Insufficient experiment credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "409": { "$ref": "#/components/responses/Conflict" }
        }
      }
    },
    "/api/experiments/{experimentId}": {
      "get": {
        "tags": ["Experiments"],
        "operationId": "getExperiment",
        "summary": "Get a complete experiment record",
        "parameters": [{ "$ref": "#/components/parameters/ExperimentId" }],
        "responses": {
          "200": { "description": "Experiment, runs, report, evidence references, and lineage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentRecord" } } } },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/experiments/{experimentId}/cancel": {
      "post": {
        "tags": ["Experiments"],
        "operationId": "cancelExperiment",
        "summary": "Cancel an experiment",
        "parameters": [{ "$ref": "#/components/parameters/ExperimentId" }],
        "responses": {
          "200": { "description": "Updated experiment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentRecord" } } } },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/experiments/{experimentId}/archive": {
      "post": {
        "tags": ["Experiments"],
        "operationId": "setExperimentArchived",
        "summary": "Archive or restore a terminal experiment",
        "parameters": [{ "$ref": "#/components/parameters/ExperimentId" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["archived"], "properties": { "archived": { "type": "boolean" } } }, "example": { "archived": true } } } },
        "responses": {
          "200": { "description": "Updated experiment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentRecord" } } } },
          "409": { "$ref": "#/components/responses/Conflict" }
        }
      }
    },
    "/api/experiments/{experimentId}/runs/{runId}/retry": {
      "post": {
        "tags": ["Experiments"],
        "operationId": "retryExperimentRun",
        "summary": "Retry one failed logical run",
        "description": "Schedules one clean replacement attempt and consumes one additional account credit.",
        "parameters": [{ "$ref": "#/components/parameters/ExperimentId" }, { "$ref": "#/components/parameters/RunId" }],
        "responses": {
          "202": { "description": "Retry accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentRecord" } } } },
          "402": { "description": "Insufficient experiment credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" }
        }
      }
    },
    "/api/experiments/{experimentId}/runs/{runId}/exchanges": {
      "get": {
        "tags": ["Evidence"],
        "operationId": "listRunExchanges",
        "summary": "List raw exchanges retained for a run",
        "description": "Requires the traces:raw scope.",
        "parameters": [{ "$ref": "#/components/parameters/ExperimentId" }, { "$ref": "#/components/parameters/RunId" }],
        "responses": {
          "200": { "description": "Raw exchange records", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RawExchangeRecord" } } } } },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/artifacts/{artifactId}": {
      "get": {
        "tags": ["Evidence"],
        "operationId": "getArtifact",
        "summary": "Decrypt and integrity-check an artifact",
        "description": "Requires the artifacts:read scope.",
        "parameters": [{ "$ref": "#/components/parameters/ArtifactId" }],
        "responses": {
          "200": { "description": "Artifact metadata and body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactResponse" } } } },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/credentials/{provider}": {
      "put": {
        "tags": ["Credentials"],
        "operationId": "saveTenantCredential",
        "summary": "Store a legacy tenant credential",
        "description": "Requires the credentials:write scope. Secret values are never returned.",
        "parameters": [{ "$ref": "#/components/parameters/Provider" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["secret"], "properties": { "secret": { "type": "string" } } } } } },
        "responses": {
          "201": { "description": "Credential stored", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string" }, "stored": { "const": true } } } } } },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      },
      "delete": {
        "tags": ["Credentials"],
        "operationId": "deleteTenantCredential",
        "summary": "Delete a legacy tenant credential",
        "parameters": [{ "$ref": "#/components/parameters/Provider" }],
        "responses": { "204": { "description": "Credential deleted" }, "403": { "$ref": "#/components/responses/Forbidden" } }
      }
    },
    "/api/assistant/chat": {
      "post": {
        "tags": ["Experiments"],
        "operationId": "chatWithAssistant",
        "summary": "Request bounded tenant-scoped experiment assistance",
        "description": "Requires experiments:read. Send Accept: text/event-stream for progress events, or application/json for a single response.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["messages", "context"], "properties": { "messages": { "type": "array", "items": { "type": "object", "required": ["role", "content"], "properties": { "role": { "type": "string", "enum": ["user", "assistant"] }, "content": { "type": "string" } } } }, "context": { "type": "object", "additionalProperties": true } } } } } },
        "responses": {
          "200": { "description": "Assistant response or server-sent progress stream", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/event-stream": { "schema": { "type": "string" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/api/admin/overview": {
      "get": {
        "tags": ["Administration"],
        "operationId": "getAdminOverview",
        "summary": "Get deployment-wide user, run, credit, and queue activity",
        "responses": {
          "200": { "description": "Administrator overview", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/api/admin/users": {
      "get": {
        "tags": ["Administration"],
        "operationId": "listUsers",
        "summary": "List user accounts",
        "responses": { "200": { "description": "Users", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicUser" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } }
      },
      "post": {
        "tags": ["Administration"],
        "operationId": "createUser",
        "summary": "Create a user with a one-time temporary password",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name", "email"], "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" } } } } } },
        "responses": { "201": { "description": "User created", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/PublicUser" }, "temporaryPassword": { "type": "string", "writeOnly": true } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } }
      }
    },
    "/api/admin/users/{userId}": {
      "patch": {
        "tags": ["Administration"],
        "operationId": "updateUser",
        "summary": "Change a user's role or status",
        "parameters": [{ "$ref": "#/components/parameters/UserId" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": ["user", "admin"] }, "status": { "type": "string", "enum": ["active", "disabled"] } } } } } },
        "responses": { "200": { "description": "Updated user", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/PublicUser" } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }
      }
    },
    "/api/admin/users/{userId}/credits": {
      "post": {
        "tags": ["Administration"],
        "operationId": "assignUserCredits",
        "summary": "Assign experiment credits",
        "parameters": [{ "$ref": "#/components/parameters/UserId" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["amount"], "properties": { "amount": { "type": "integer", "minimum": 1 }, "note": { "type": "string", "maxLength": 500 } } }, "example": { "amount": 10, "note": "Evaluation allocation" } } } },
        "responses": { "200": { "description": "Updated user", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/PublicUser" } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }
      }
    },
    "/api/admin/queue-configuration": {
      "get": {
        "tags": ["Administration"],
        "operationId": "getQueueConfiguration",
        "summary": "Get execution concurrency",
        "responses": { "200": { "description": "Queue configuration", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "$ref": "#/components/responses/Forbidden" } }
      },
      "put": {
        "tags": ["Administration"],
        "operationId": "setQueueConfiguration",
        "summary": "Set execution concurrency",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["concurrency"], "properties": { "concurrency": { "type": "integer", "minimum": 1, "maximum": 16 } } } } } },
        "responses": { "200": { "description": "Updated queue configuration", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } }
      }
    },
    "/api/admin/agent-auth": {
      "get": {
        "tags": ["Administration"],
        "operationId": "listAgentAuthentication",
        "summary": "List deployment agent-authentication status",
        "responses": { "200": { "description": "Credential status without secret values", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgentAuthStatus" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } }
      }
    },
    "/api/admin/agent-auth/{target}": {
      "put": {
        "tags": ["Administration"],
        "operationId": "saveAgentApiKey",
        "summary": "Store a deployment provider API key",
        "parameters": [{ "$ref": "#/components/parameters/AgentAuthTarget" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["apiKey"], "properties": { "apiKey": { "type": "string", "writeOnly": true } } } } } },
        "responses": { "200": { "description": "Updated authentication statuses", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgentAuthStatus" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } }
      },
      "delete": {
        "tags": ["Administration"],
        "operationId": "removeAgentAuthentication",
        "summary": "Remove deployment provider authentication",
        "parameters": [{ "$ref": "#/components/parameters/AgentAuthTarget" }],
        "responses": { "204": { "description": "Authentication removed" }, "403": { "$ref": "#/components/responses/Forbidden" } }
      }
    },
    "/api/admin/agent-auth/test": {
      "post": {
        "tags": ["Administration"],
        "operationId": "testAllAgentAuthentication",
        "summary": "Test every configured deployment agent credential",
        "responses": { "200": { "description": "Bounded authentication test results", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } }
      }
    },
    "/api/admin/agent-auth/{target}/test": {
      "post": {
        "tags": ["Administration"],
        "operationId": "testAgentAuthentication",
        "summary": "Test one deployment agent credential",
        "parameters": [{ "$ref": "#/components/parameters/AgentAuthTarget" }],
        "responses": { "200": { "description": "Bounded authentication test result", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } }
      }
    },
    "/api/admin/assistant-configuration": {
      "get": {
        "tags": ["Administration"],
        "operationId": "getAssistantConfiguration",
        "summary": "Get Ada assistant model configuration",
        "responses": { "200": { "description": "Assistant configuration", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "$ref": "#/components/responses/Forbidden" } }
      },
      "put": {
        "tags": ["Administration"],
        "operationId": "setAssistantConfiguration",
        "summary": "Set Ada assistant model configuration",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["model", "thinkingLevel"], "properties": { "model": { "type": "string", "enum": ["luna", "terra", "sol"] }, "thinkingLevel": { "type": "string", "enum": ["minimal", "low", "medium", "high"] } } } } } },
        "responses": { "200": { "description": "Updated assistant configuration", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } }
      }
    },
    "/api/admin/agent-auth/{target}/oauth": {
      "post": {
        "tags": ["Administration"],
        "operationId": "startAgentOAuth",
        "summary": "Start provider subscription OAuth",
        "parameters": [{ "$ref": "#/components/parameters/AgentAuthTarget" }],
        "responses": { "202": { "description": "OAuth flow started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentOAuthFlow" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } }
      }
    },
    "/api/admin/agent-auth/oauth/{flowId}": {
      "get": {
        "tags": ["Administration"],
        "operationId": "getAgentOAuthFlow",
        "summary": "Poll a provider OAuth flow",
        "parameters": [{ "$ref": "#/components/parameters/OAuthFlowId" }],
        "responses": { "200": { "description": "OAuth flow status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentOAuthFlow" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }
      },
      "post": {
        "tags": ["Administration"],
        "operationId": "completeAgentOAuthFlow",
        "summary": "Submit a provider OAuth code",
        "parameters": [{ "$ref": "#/components/parameters/OAuthFlowId" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["code"], "properties": { "code": { "type": "string" } } } } } },
        "responses": { "200": { "description": "Updated OAuth flow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentOAuthFlow" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "behave.run user session or API key",
        "description": "Use a signed usr.* session or a tenant/personal API key. Prefer the BEHAVE_API_KEY environment variable for CLI automation."
      }
    },
    "parameters": {
      "ExperimentId": { "name": "experimentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^exp_[A-Za-z0-9]+$" } },
      "RunId": { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^run_[A-Za-z0-9]+$" } },
      "ArtifactId": { "name": "artifactId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^art_[A-Za-z0-9]+$" } },
      "KeyId": { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^key_[A-Za-z0-9]+$" } },
      "UserId": { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^usr_[A-Za-z0-9]+$" } },
      "Provider": { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" } },
      "AgentAuthTarget": { "name": "target", "in": "path", "required": true, "schema": { "type": "string", "enum": ["pi-codex", "pi-claude", "codex", "claude"] } },
      "OAuthFlowId": { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^oauth_[A-Za-z0-9]+$" } }
    },
    "responses": {
      "AuthSuccess": { "description": "Authenticated account and signed session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } },
      "BadRequest": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "Request validation failed" } } } },
      "Unauthorized": { "description": "Missing, invalid, or expired authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "Bearer authentication required" } } } },
      "Forbidden": { "description": "Authenticated but not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "Missing scope: experiments:write" } } } },
      "NotFound": { "description": "Tenant-scoped resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "Experiment not found" } } } },
      "Conflict": { "description": "Request conflicts with current resource state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } },
      "RateLimited": { "description": "Authentication or request rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }
    },
    "schemas": {
      "ApiError": {
        "type": "object",
        "required": ["error"],
        "properties": { "error": { "type": "string" } }
      },
      "AuthConfig": {
        "type": "object",
        "required": ["registrationEnabled"],
        "properties": { "registrationEnabled": { "type": "boolean" } }
      },
      "RegisterRequest": {
        "type": "object",
        "required": ["name", "email", "password"],
        "properties": {
          "name": { "type": "string", "minLength": 2, "maxLength": 100 },
          "email": { "type": "string", "format": "email", "maxLength": 254 },
          "password": { "type": "string", "minLength": 10, "maxLength": 256, "writeOnly": true }
        }
      },
      "LoginRequest": {
        "type": "object",
        "required": ["email", "password"],
        "properties": {
          "email": { "type": "string", "format": "email" },
          "password": { "type": "string", "writeOnly": true }
        }
      },
      "AuthResponse": {
        "type": "object",
        "required": ["token", "user"],
        "properties": { "token": { "type": "string", "writeOnly": true }, "user": { "$ref": "#/components/schemas/PublicUser" } }
      },
      "CurrentAccount": {
        "type": "object",
        "required": ["user", "authType"],
        "properties": {
          "user": { "oneOf": [{ "$ref": "#/components/schemas/PublicUser" }, { "type": "null" }] },
          "authType": { "type": "string", "enum": ["local", "api-key", "user"] },
          "token": { "type": "string", "description": "Renewed token, present only for signed user sessions.", "writeOnly": true }
        }
      },
      "PublicUser": {
        "type": "object",
        "required": ["id", "tenantId", "email", "name", "role", "status", "credits", "creditsGranted", "creditsUsed", "createdAt", "updatedAt"],
        "properties": {
          "id": { "type": "string" },
          "tenantId": { "type": "string" },
          "email": { "type": "string", "format": "email" },
          "name": { "type": "string" },
          "role": { "type": "string", "enum": ["user", "admin"] },
          "status": { "type": "string", "enum": ["active", "disabled"] },
          "credits": { "type": "integer" },
          "creditsGranted": { "type": "integer" },
          "creditsUsed": { "type": "integer" },
          "createdAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" },
          "lastLoginAt": { "type": "string", "format": "date-time" },
          "recentCreditTransactions": { "type": "array", "items": { "type": "object", "additionalProperties": true } }
        }
      },
      "AccountApiKey": {
        "type": "object",
        "required": ["id", "name", "prefix", "createdAt", "scopes"],
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "prefix": { "type": "string", "description": "Non-secret display prefix." },
          "createdAt": { "type": "string", "format": "date-time" },
          "scopes": { "type": "array", "items": { "type": "string" } }
        }
      },
      "IssueApiKeyRequest": {
        "type": "object",
        "required": ["name"],
        "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 } }
      },
      "IssueApiKeyResponse": {
        "type": "object",
        "required": ["apiKey", "secret"],
        "properties": { "apiKey": { "$ref": "#/components/schemas/AccountApiKey" }, "secret": { "type": "string", "writeOnly": true, "description": "One-time API-key secret." } }
      },
      "ExecutionContract": {
        "type": "object",
        "required": ["kind", "method", "requireHttp2xx", "requireJson", "requireNonEmpty", "forbidErrorEnvelope", "requiredJsonFields", "productTargets"],
        "properties": {
          "kind": { "type": "string", "enum": ["selection-only", "http-json", "http-response", "npm-package", "pypi-package"] },
          "method": { "const": "GET" },
          "requireHttp2xx": { "const": true },
          "requireJson": { "type": "boolean" },
          "requireNonEmpty": { "const": true },
          "forbidErrorEnvelope": { "type": "boolean" },
          "requiredJsonFields": { "type": "array", "items": { "type": "string" } },
          "productTargets": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }
        }
      },
      "Scenario": {
        "type": "object",
        "required": ["task", "successCriteria", "executionContract"],
        "properties": {
          "task": { "type": "string" },
          "preferredProduct": { "type": "string" },
          "alternatives": { "type": "array", "items": { "type": "string" } },
          "successCriteria": { "type": "string" },
          "context": { "type": "object", "additionalProperties": { "type": "string" } },
          "version": { "type": "string" },
          "executionContract": { "$ref": "#/components/schemas/ExecutionContract" }
        }
      },
      "RunnerVariant": {
        "type": "object",
        "required": ["id", "label", "agent", "provider", "model", "thinkingLevel"],
        "properties": {
          "id": { "type": "string" },
          "label": { "type": "string" },
          "agent": { "type": "string", "enum": ["model-control", "codex", "claude-code"] },
          "provider": { "type": "string", "enum": ["openai", "openai-codex", "anthropic"] },
          "model": { "type": "string" },
          "thinkingLevel": { "type": "string", "enum": ["off", "minimal", "low", "medium", "high"] }
        }
      },
      "ExperimentConfigInput": {
        "type": "object",
        "properties": {
          "trials": { "type": "integer", "minimum": 1, "maximum": 12, "default": 3 },
          "agent": { "type": "string", "enum": ["model-control", "codex", "claude-code"] },
          "provider": { "type": "string", "enum": ["openai", "openai-codex", "anthropic"] },
          "model": { "type": "string" },
          "thinkingLevel": { "type": "string", "enum": ["off", "minimal", "low", "medium", "high"] },
          "variants": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "$ref": "#/components/schemas/RunnerVariant" } },
          "maxRunMs": { "type": "integer" },
          "maxBudgetUsd": { "type": "number", "minimum": 0 },
          "maxConcurrency": { "type": "integer" },
          "taskPromptVariations": { "type": "boolean" },
          "taskPrompts": { "type": "array", "items": { "type": "string" } }
        }
      },
      "EvidencePolicy": {
        "type": "object",
        "required": ["id", "version", "mode", "rules", "defaultAction"],
        "properties": {
          "id": { "type": "string" },
          "version": { "type": "string" },
          "mode": { "type": "string", "enum": ["live-recording", "recorded-replay", "counterfactual"] },
          "snapshotExperimentId": { "type": "string" },
          "rules": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
          "defaultAction": { "type": "string", "enum": ["allow-get", "deny"] }
        }
      },
      "ExperimentArm": {
        "type": "object",
        "required": ["id", "label", "kind", "policy"],
        "properties": {
          "id": { "type": "string" },
          "label": { "type": "string" },
          "kind": { "type": "string", "enum": ["baseline", "treatment"] },
          "policy": { "$ref": "#/components/schemas/EvidencePolicy" }
        }
      },
      "CreateExperimentRequest": {
        "type": "object",
        "required": ["scenario"],
        "properties": {
          "scenario": { "$ref": "#/components/schemas/Scenario" },
          "config": { "$ref": "#/components/schemas/ExperimentConfigInput" },
          "arms": { "type": "array", "items": { "$ref": "#/components/schemas/ExperimentArm" } }
        }
      },
      "ExperimentRecord": {
        "type": "object",
        "required": ["id", "tenantId", "status", "createdAt", "scenario", "config", "runs"],
        "properties": {
          "id": { "type": "string" },
          "tenantId": { "type": "string" },
          "number": { "type": "integer" },
          "status": { "type": "string", "enum": ["queued", "running", "completed", "failed", "cancelled"] },
          "createdAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" },
          "scenario": { "$ref": "#/components/schemas/Scenario" },
          "config": { "type": "object", "additionalProperties": true },
          "progress": { "type": "object", "additionalProperties": true },
          "runs": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
          "report": { "type": "object", "additionalProperties": true },
          "manifest": { "type": "object", "additionalProperties": true },
          "lineage": { "type": "object", "additionalProperties": true }
        },
        "additionalProperties": true
      },
      "ExperimentSummary": {
        "type": "object",
        "required": ["id", "number", "status", "createdAt", "scenario", "config", "runCounts"],
        "properties": {
          "id": { "type": "string" },
          "number": { "type": "integer" },
          "status": { "type": "string", "enum": ["queued", "running", "completed", "failed", "cancelled"] },
          "createdAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" },
          "scenario": { "type": "object", "additionalProperties": true },
          "config": { "type": "object", "additionalProperties": true },
          "runCounts": { "type": "object", "additionalProperties": { "type": "integer" } },
          "totalCost": { "type": "number" },
          "reportStatus": { "type": "string", "enum": ["provisional", "final", "unavailable"] }
        },
        "additionalProperties": true
      },
      "ExperimentSummaryPage": {
        "type": "object",
        "required": ["items", "total", "hasMore"],
        "properties": {
          "items": { "type": "array", "items": { "$ref": "#/components/schemas/ExperimentSummary" } },
          "total": { "type": "integer" },
          "hasMore": { "type": "boolean" }
        }
      },
      "RawExchangeRecord": {
        "type": "object",
        "required": ["id", "runId"],
        "properties": { "id": { "type": "string" }, "runId": { "type": "string" } },
        "additionalProperties": true
      },
      "ArtifactResponse": {
        "type": "object",
        "required": ["metadata", "body"],
        "properties": {
          "metadata": {
            "type": "object",
            "required": ["id", "runId", "kind", "sha256", "bytes", "capturedAt"],
            "properties": {
              "id": { "type": "string" },
              "runId": { "type": "string" },
              "kind": { "type": "string" },
              "source": { "type": "string" },
              "contentType": { "type": "string" },
              "status": { "type": "integer" },
              "sha256": { "type": "string" },
              "bytes": { "type": "integer" },
              "capturedAt": { "type": "string", "format": "date-time" },
              "redactions": { "type": "array", "items": { "type": "string" } }
            }
          },
          "body": { "type": "string" }
        }
      },
      "HealthResponse": {
        "type": "object",
        "required": ["status", "queue", "provider", "capabilities", "security"],
        "properties": {
          "status": { "type": "string", "example": "ok" },
          "checkedAt": { "type": "string", "format": "date-time" },
          "cached": { "type": "boolean" },
          "queue": { "type": "object", "additionalProperties": true },
          "provider": { "type": "object", "additionalProperties": true },
          "capabilities": { "type": "object", "additionalProperties": true },
          "security": { "type": "object", "additionalProperties": { "type": "string" } }
        }
      },
      "AgentOAuthFlow": {
        "type": "object",
        "required": ["id", "target", "state"],
        "properties": {
          "id": { "type": "string" },
          "target": { "type": "string", "enum": ["pi-codex", "pi-claude", "codex", "claude"] },
          "state": { "type": "string", "enum": ["starting", "waiting", "complete", "failed"] },
          "authorizationUrl": { "type": "string", "format": "uri" },
          "instructions": { "type": "string" },
          "userCode": { "type": "string" },
          "verificationUri": { "type": "string", "format": "uri" },
          "prompt": { "type": "string" },
          "error": { "type": "string" }
        }
      },
      "AgentAuthStatus": {
        "type": "object",
        "required": ["target", "name", "harness", "provider", "configured"],
        "properties": {
          "target": { "type": "string", "enum": ["pi-codex", "pi-claude", "codex", "claude"] },
          "name": { "type": "string" },
          "harness": { "type": "string" },
          "provider": { "type": "string" },
          "configured": { "type": "boolean" },
          "method": { "type": "string", "enum": ["api_key", "oauth"] },
          "subscription": { "type": "boolean" },
          "updatedAt": { "type": "string", "format": "date-time" },
          "expiresAt": { "type": "string", "format": "date-time" },
          "expired": { "type": "boolean" }
        }
      }
    }
  }
}