{
  "openapi": "3.1.0",
  "info": {
    "title": "Cruq AI API",
    "version": "1.0.0",
    "description": "The public REST API for Cruq AI - build, run, and own AI agents. Create agents, run them, and manage prompts, tools, guardrails, memory, knowledge bases, and evals. All endpoints are tenant-scoped and authenticated with a Bearer API key (cruq_sk_...). Timestamps are ISO 8601 strings; cost_usd values are exact-decimal strings.",
    "contact": { "name": "Cruq AI", "email": "hello@cruq.ai", "url": "https://www.cruq.ai/contact" },
    "license": { "name": "Proprietary" }
  },
  "servers": [{ "url": "https://api.cruq.ai", "description": "Production" }],
  "externalDocs": { "description": "Cruq AI documentation", "url": "https://docs.cruq.ai" },
  "security": [{ "bearerAuth": [] }],
  "tags": [
    { "name": "Agents", "description": "Create, version, and run agents" },
    { "name": "Runs", "description": "Inspect agent runs and their tool-call traces" },
    { "name": "Threads", "description": "Conversation threads grouped by agent" },
    { "name": "Tools", "description": "The tenant tool catalog" },
    { "name": "Prompts", "description": "Reusable prompt templates" },
    { "name": "Guardrails", "description": "Input/output guardrails" },
    { "name": "Memory", "description": "Long-term agent memory with semantic recall" },
    { "name": "Knowledge", "description": "Knowledge bases and document ingestion" },
    { "name": "Evals", "description": "Eval suites, cases, and model-comparison experiments" }
  ],
  "paths": {
    "/v1/agents": {
      "get": {
        "operationId": "listAgents",
        "summary": "List agents",
        "tags": ["Agents"],
        "responses": {
          "200": {
            "description": "The tenant's agents",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } } } } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "post": {
        "operationId": "createAgent",
        "summary": "Create an agent (or return the existing one by name)",
        "tags": ["Agents"],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } } }
        },
        "responses": {
          "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentUpsert" } } } },
          "200": { "description": "Already existed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentUpsert" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/agents/{id}": {
      "parameters": [{ "$ref": "#/components/parameters/AgentRef" }],
      "delete": {
        "operationId": "deleteAgent",
        "summary": "Delete an agent by id or name",
        "tags": ["Agents"],
        "responses": {
          "200": { "$ref": "#/components/responses/Deleted" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/v1/agents/{id}/versions": {
      "parameters": [{ "$ref": "#/components/parameters/AgentRef" }],
      "get": {
        "operationId": "getAgentGraph",
        "summary": "Get the agent's current graph (published, else latest draft)",
        "tags": ["Agents"],
        "responses": {
          "200": { "description": "Current version and graph", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string" }, "version": { "type": "integer" }, "version_id": { "type": "string" }, "status": { "type": "string" }, "published": { "type": "boolean" }, "graph": { "type": "object" } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      },
      "post": {
        "operationId": "createAgentVersion",
        "summary": "Create a new agent version from a graph (publishes by default)",
        "tags": ["Agents"],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["graph"], "properties": { "graph": { "type": "object" }, "publish": { "type": "boolean", "default": true } } } } } },
        "responses": {
          "201": { "description": "Version created", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "object" } } } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/v1/agents/{id}/runs": {
      "parameters": [{ "$ref": "#/components/parameters/AgentRef" }],
      "post": {
        "operationId": "runAgent",
        "summary": "Run the agent's published version (Server-Sent Events stream)",
        "description": "Returns a text/event-stream of run events, not JSON. Rate limited to 60 requests / 60s per API key.",
        "tags": ["Agents"],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["input"], "properties": { "input": { "type": "string" }, "thread_id": { "type": "string" } } } } } },
        "responses": {
          "200": { "description": "SSE stream of run events", "content": { "text/event-stream": { "schema": { "type": "string" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "description": "Agent has no published version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/runs": {
      "get": {
        "operationId": "listRuns",
        "summary": "List recent runs",
        "tags": ["Runs"],
        "parameters": [
          { "name": "agent", "in": "query", "schema": { "type": "string" }, "description": "Filter by agent id" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 } }
        ],
        "responses": {
          "200": { "description": "Recent runs", "content": { "application/json": { "schema": { "type": "object", "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/Run" } } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/runs/{runId}": {
      "parameters": [{ "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } }],
      "get": {
        "operationId": "getRun",
        "summary": "Get a run with its tool-call step trace",
        "tags": ["Runs"],
        "responses": {
          "200": { "description": "Run and steps", "content": { "application/json": { "schema": { "type": "object", "properties": { "run": { "$ref": "#/components/schemas/Run" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/Step" } } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/v1/threads": {
      "get": {
        "operationId": "listThreads",
        "summary": "List conversation threads for an agent",
        "tags": ["Threads"],
        "parameters": [{ "name": "agent", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Agent id or name" }],
        "responses": {
          "200": { "description": "Threads newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "threads": { "type": "array", "items": { "type": "object", "properties": { "thread_id": { "type": "string" }, "title": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "run_count": { "type": "integer" } } } } } } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/v1/threads/{threadId}": {
      "parameters": [{ "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" } }],
      "get": {
        "operationId": "getThread",
        "summary": "Get all turns in a thread",
        "tags": ["Threads"],
        "parameters": [{ "name": "agent", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Agent id or name" }],
        "responses": {
          "200": { "description": "Thread turns oldest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "thread_id": { "type": "string" }, "turns": { "type": "array", "items": { "type": "object" } } } } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/v1/tools": {
      "get": {
        "operationId": "listTools",
        "summary": "List the tenant tool catalog",
        "tags": ["Tools"],
        "responses": {
          "200": { "description": "Tools", "content": { "application/json": { "schema": { "type": "object", "properties": { "tools": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "post": {
        "operationId": "createTool",
        "summary": "Create a tool (or return the existing one by name)",
        "tags": ["Tools"],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name", "kind"], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "kind": { "type": "string" }, "builtin": { "type": "string" }, "http": { "type": "object" }, "mcp": { "type": "object" } } } } } },
        "responses": {
          "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolUpsert" } } } },
          "200": { "description": "Already existed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolUpsert" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/prompts": {
      "get": {
        "operationId": "listPrompts",
        "summary": "List prompt templates",
        "tags": ["Prompts"],
        "responses": {
          "200": { "description": "Prompts", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompts": { "type": "array", "items": { "$ref": "#/components/schemas/Prompt" } } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "post": {
        "operationId": "upsertPrompt",
        "summary": "Create a prompt, or update and bump its version (by name)",
        "tags": ["Prompts"],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name", "template"], "properties": { "name": { "type": "string" }, "template": { "type": "string" }, "description": { "type": "string" }, "model": { "type": "string" } } } } } },
        "responses": {
          "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "integer" } } }, "created": { "type": "boolean" } } } } } },
          "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/prompts/{name}": {
      "parameters": [{ "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }],
      "delete": {
        "operationId": "deletePrompt",
        "summary": "Delete a prompt by name",
        "tags": ["Prompts"],
        "responses": {
          "200": { "$ref": "#/components/responses/Deleted" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/v1/guardrails": {
      "get": {
        "operationId": "listGuardrails",
        "summary": "List guardrails",
        "tags": ["Guardrails"],
        "responses": {
          "200": { "description": "Guardrails", "content": { "application/json": { "schema": { "type": "object", "properties": { "guardrails": { "type": "array", "items": { "$ref": "#/components/schemas/Guardrail" } } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "post": {
        "operationId": "upsertGuardrail",
        "summary": "Create or update a guardrail (by name)",
        "tags": ["Guardrails"],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name", "kind"], "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": ["pii", "regex", "keyword", "max_length", "json_schema"] }, "target": { "type": "string", "enum": ["input", "output", "both"], "default": "both" }, "action": { "type": "string", "enum": ["block", "redact", "warn"], "default": "block" }, "enabled": { "type": "boolean", "default": true }, "description": { "type": "string" }, "config": { "type": "object" } } } } } },
        "responses": {
          "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object" } } } },
          "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/guardrails/{name}": {
      "parameters": [{ "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }],
      "delete": {
        "operationId": "deleteGuardrail",
        "summary": "Delete a guardrail by name",
        "tags": ["Guardrails"],
        "responses": {
          "200": { "$ref": "#/components/responses/Deleted" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/v1/memory": {
      "get": {
        "operationId": "listMemories",
        "summary": "List stored memories",
        "tags": ["Memory"],
        "responses": {
          "200": { "description": "Memories", "content": { "application/json": { "schema": { "type": "object", "properties": { "memories": { "type": "array", "items": { "$ref": "#/components/schemas/Memory" } } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "post": {
        "operationId": "createMemory",
        "summary": "Store (embed) a memory",
        "tags": ["Memory"],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["content"], "properties": { "content": { "type": "string" } } } } } },
        "responses": {
          "201": { "description": "Stored", "content": { "application/json": { "schema": { "type": "object", "properties": { "memory": { "type": "object", "properties": { "id": { "type": "string" } } } } } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "502": { "$ref": "#/components/responses/UpstreamError" }
        }
      }
    },
    "/v1/memory/search": {
      "post": {
        "operationId": "searchMemory",
        "summary": "Semantic recall over memories",
        "tags": ["Memory"],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["query"], "properties": { "query": { "type": "string" }, "k": { "type": "integer", "default": 5 } } } } } },
        "responses": {
          "200": { "description": "Hits", "content": { "application/json": { "schema": { "type": "object", "properties": { "hits": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "similarity": { "type": "number" } } } } } } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "502": { "$ref": "#/components/responses/UpstreamError" }
        }
      }
    },
    "/v1/memory/{id}": {
      "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
      "delete": {
        "operationId": "deleteMemory",
        "summary": "Delete a memory by id (idempotent)",
        "tags": ["Memory"],
        "responses": {
          "200": { "$ref": "#/components/responses/Deleted" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/knowledge": {
      "get": {
        "operationId": "listKnowledgeBases",
        "summary": "List knowledge bases",
        "tags": ["Knowledge"],
        "responses": {
          "200": { "description": "Knowledge bases", "content": { "application/json": { "schema": { "type": "object", "properties": { "knowledge_bases": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeBase" } } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "post": {
        "operationId": "createKnowledgeBase",
        "summary": "Create a knowledge base (or return the existing one by name)",
        "tags": ["Knowledge"],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } } } },
        "responses": {
          "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object" } } } },
          "200": { "description": "Already existed", "content": { "application/json": { "schema": { "type": "object" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/knowledge/search": {
      "post": {
        "operationId": "searchKnowledge",
        "summary": "Cosine search over embedded chunks, optionally scoped to one base",
        "tags": ["Knowledge"],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["query"], "properties": { "query": { "type": "string" }, "kb": { "type": "string", "description": "Knowledge base name" }, "k": { "type": "integer", "default": 5 } } } } } },
        "responses": {
          "200": { "description": "Hits", "content": { "application/json": { "schema": { "type": "object", "properties": { "hits": { "type": "array", "items": { "type": "object", "properties": { "content": { "type": "string" }, "document_id": { "type": "string" }, "similarity": { "type": "number" } } } } } } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "502": { "$ref": "#/components/responses/UpstreamError" }
        }
      }
    },
    "/v1/knowledge/{kb}": {
      "parameters": [{ "name": "kb", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Knowledge base name" }],
      "delete": {
        "operationId": "deleteKnowledgeBase",
        "summary": "Delete a knowledge base by name (cascades documents)",
        "tags": ["Knowledge"],
        "responses": {
          "200": { "$ref": "#/components/responses/Deleted" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/v1/knowledge/{kb}/documents": {
      "parameters": [{ "name": "kb", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Knowledge base name" }],
      "get": {
        "operationId": "listKnowledgeDocuments",
        "summary": "List documents in a knowledge base",
        "tags": ["Knowledge"],
        "responses": {
          "200": { "description": "Documents", "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      },
      "post": {
        "operationId": "ingestKnowledgeDocument",
        "summary": "Ingest a document (chunk + embed); accepts JSON or multipart",
        "description": "Returns 202 - the document is queued for a background worker. Poll the document for its status.",
        "tags": ["Knowledge"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "type": "object", "required": ["content"], "properties": { "title": { "type": "string" }, "content": { "type": "string" } } } },
            "multipart/form-data": { "schema": { "type": "object", "required": ["file"], "properties": { "title": { "type": "string" }, "file": { "type": "string", "format": "binary" } } } }
          }
        },
        "responses": {
          "202": { "description": "Queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" } } } } } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "502": { "$ref": "#/components/responses/UpstreamError" }
        }
      }
    },
    "/v1/evals/suites": {
      "get": {
        "operationId": "listEvalSuites",
        "summary": "List eval suites",
        "tags": ["Evals"],
        "parameters": [{ "name": "agent", "in": "query", "schema": { "type": "string" }, "description": "Agent id or name for an agent-scoped listing" }],
        "responses": {
          "200": { "description": "Suites", "content": { "application/json": { "schema": { "type": "object", "properties": { "suites": { "type": "array", "items": { "$ref": "#/components/schemas/Suite" } } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      },
      "post": {
        "operationId": "createEvalSuite",
        "summary": "Create an eval suite",
        "tags": ["Evals"],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "agent": { "type": "string" }, "workspace_wide": { "type": "boolean" } } } } } },
        "responses": {
          "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" }
        }
      }
    },
    "/v1/evals/suites/{ref}": {
      "parameters": [{ "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Suite id or name" }],
      "get": {
        "operationId": "getEvalSuite",
        "summary": "Get a suite with its cases",
        "tags": ["Evals"],
        "responses": {
          "200": { "description": "Suite and cases", "content": { "application/json": { "schema": { "type": "object" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" }
        }
      },
      "patch": {
        "operationId": "renameEvalSuite",
        "summary": "Rename a suite",
        "tags": ["Evals"],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "maxLength": 200 } } } } } },
        "responses": {
          "200": { "description": "Renamed", "content": { "application/json": { "schema": { "type": "object" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" }
        }
      },
      "delete": {
        "operationId": "deleteEvalSuite",
        "summary": "Delete a suite and its cases",
        "tags": ["Evals"],
        "responses": {
          "200": { "$ref": "#/components/responses/Deleted" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/evals/suites/{ref}/cases": {
      "parameters": [{ "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Suite id or name" }],
      "get": {
        "operationId": "listEvalCases",
        "summary": "List a suite's cases",
        "tags": ["Evals"],
        "responses": {
          "200": { "description": "Cases", "content": { "application/json": { "schema": { "type": "object", "properties": { "cases": { "type": "array", "items": { "$ref": "#/components/schemas/EvalCase" } } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "post": {
        "operationId": "createEvalCase",
        "summary": "Add a case to a suite",
        "tags": ["Evals"],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name", "input", "scorers"], "properties": { "name": { "type": "string" }, "input": { "type": "string" }, "scorers": { "type": "array", "items": { "type": "object" } }, "weight": { "type": "number", "default": 1 } } } } } },
        "responses": {
          "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/evals/cases/{id}": {
      "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
      "delete": {
        "operationId": "deleteEvalCase",
        "summary": "Remove a single case",
        "tags": ["Evals"],
        "responses": {
          "200": { "$ref": "#/components/responses/Deleted" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/evals/experiments": {
      "get": {
        "operationId": "listEvalExperiments",
        "summary": "List experiments",
        "tags": ["Evals"],
        "parameters": [
          { "name": "agent", "in": "query", "schema": { "type": "string" }, "description": "Agent id or name" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 } }
        ],
        "responses": {
          "200": { "description": "Experiments", "content": { "application/json": { "schema": { "type": "object", "properties": { "experiments": { "type": "array", "items": { "$ref": "#/components/schemas/Experiment" } } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      },
      "post": {
        "operationId": "createEvalExperiment",
        "summary": "Start a model-comparison experiment",
        "tags": ["Evals"],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["agent", "suite", "name", "variants"], "properties": { "agent": { "type": "string" }, "suite": { "type": "string" }, "name": { "type": "string" }, "variants": { "type": "array", "items": { "type": "object" } }, "judge_model": { "type": "string" }, "budget_usd": { "type": "number" } } } } } },
        "responses": {
          "201": { "description": "Started", "content": { "application/json": { "schema": { "type": "object" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" }
        }
      }
    },
    "/v1/evals/experiments/{id}": {
      "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
      "get": {
        "operationId": "getEvalExperiment",
        "summary": "Get an experiment summary and leaderboard",
        "tags": ["Evals"],
        "parameters": [{ "name": "results", "in": "query", "schema": { "type": "boolean" }, "description": "Include per-cell results" }],
        "responses": {
          "200": { "description": "Experiment", "content": { "application/json": { "schema": { "type": "object" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      },
      "patch": {
        "operationId": "renameEvalExperiment",
        "summary": "Rename an experiment",
        "tags": ["Evals"],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "maxLength": 200 } } } } } },
        "responses": {
          "200": { "description": "Renamed", "content": { "application/json": { "schema": { "type": "object" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      },
      "delete": {
        "operationId": "cancelEvalExperiment",
        "summary": "Cancel an experiment",
        "tags": ["Evals"],
        "responses": {
          "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "cancelled": { "type": "string" } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "cruq_sk_...", "description": "A tenant API key. Send as: Authorization: Bearer cruq_sk_..." }
    },
    "parameters": {
      "AgentRef": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Agent id or name" }
    },
    "responses": {
      "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "BadRequest": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Conflict": { "description": "Conflict (e.g. ambiguous name or name already taken)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "UpstreamError": { "description": "Upstream failure (embedding/search/enqueue)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Deleted": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "oneOf": [{ "type": "boolean" }, { "type": "string" }] } } } } } }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "description": "Standard error envelope. Some validation errors add issues[] or suite_ids[].",
        "required": ["error"],
        "properties": {
          "error": { "type": "string" },
          "code": { "type": "string" },
          "hint": { "type": "string" },
          "issues": { "type": "array", "items": { "type": "string" } }
        }
      },
      "Agent": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "description": { "type": "string" },
          "status": { "type": "string" },
          "published_version_id": { "type": ["string", "null"] }
        }
      },
      "AgentUpsert": {
        "type": "object",
        "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "created": { "type": "boolean" } }
      },
      "Run": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "agent_id": { "type": "string" },
          "agent_version_id": { "type": "string" },
          "thread_id": { "type": ["string", "null"] },
          "status": { "type": "string" },
          "input": { "type": "string" },
          "output": { "type": ["string", "null"] },
          "error": { "type": ["string", "null"] },
          "created_at": { "type": "string", "format": "date-time" },
          "model": { "type": ["string", "null"] },
          "usage": {
            "type": "object",
            "properties": {
              "prompt_tokens": { "type": ["integer", "null"] },
              "completion_tokens": { "type": ["integer", "null"] },
              "total_tokens": { "type": ["integer", "null"] },
              "cost_usd": { "type": ["string", "null"] },
              "duration_ms": { "type": ["integer", "null"] }
            }
          }
        }
      },
      "Step": {
        "type": "object",
        "properties": {
          "seq": { "type": "integer" },
          "type": { "type": "string" },
          "node_id": { "type": ["string", "null"] },
          "tool_name": { "type": ["string", "null"] },
          "tool_call_id": { "type": ["string", "null"] },
          "args": {},
          "result": {},
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "Tool": {
        "type": "object",
        "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "kind": { "type": "string" }, "config": { "type": "object" } }
      },
      "ToolUpsert": {
        "type": "object",
        "properties": { "tool": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "created": { "type": "boolean" } }
      },
      "Prompt": {
        "type": "object",
        "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "template": { "type": "string" }, "variables": { "type": "array", "items": { "type": "string" } }, "model": { "type": ["string", "null"] }, "version": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" } }
      },
      "Guardrail": {
        "type": "object",
        "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "kind": { "type": "string" }, "target": { "type": "string" }, "action": { "type": "string" }, "config": { "type": "object" }, "enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } }
      },
      "Memory": {
        "type": "object",
        "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "source": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }
      },
      "KnowledgeBase": {
        "type": "object",
        "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "embedding_model": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }
      },
      "Document": {
        "type": "object",
        "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "chunk_count": { "type": "integer" }, "error": { "type": ["string", "null"] }, "created_at": { "type": "string", "format": "date-time" } }
      },
      "Suite": {
        "type": "object",
        "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "agent_id": { "type": ["string", "null"] }, "agent_name": { "type": ["string", "null"] }, "case_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } }
      },
      "EvalCase": {
        "type": "object",
        "properties": { "id": { "type": "string" }, "suite_id": { "type": "string" }, "name": { "type": "string" }, "input": { "type": "string" }, "scorers": { "type": "array", "items": { "type": "object" } }, "weight": { "type": "number" }, "order_index": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } }
      },
      "Experiment": {
        "type": "object",
        "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "agent_id": { "type": "string" }, "agent_name": { "type": "string" }, "agent_version_id": { "type": "string" }, "suite_id": { "type": "string" }, "suite_name": { "type": "string" }, "variants": { "type": "array", "items": { "type": "object" } }, "judge_model": { "type": ["string", "null"] }, "budget_usd": { "type": ["number", "null"] }, "note": { "type": ["string", "null"] }, "progress": { "type": "object", "properties": { "total": { "type": "integer" }, "done": { "type": "integer" }, "failed": { "type": "integer" } } }, "created_at": { "type": "string", "format": "date-time" } }
      }
    }
  }
}