{
 "openapi": "3.0.3",
 "info": {
  "title": "NSR AI API",
  "description": "# Neuro-Symbolic Recursive (NSR) AI API\n\nA production-grade API for hybrid AI systems combining neural pattern recognition with symbolic logical reasoning.\n\n## Overview\n\nThe NSR API provides a comprehensive interface for building intelligent systems that combine the interpretability of symbolic AI with the pattern recognition capabilities of neural networks. This API enables:\n\n- **Verified Decisions**: approved/denied/refused verdicts with machine-checkable proofs. An approved decision carries a `verifiable_bundle` you can POST to `/v1/proofs/verify` to confirm the verdict **without trusting this server**; refusals name the exact missing facts to supply and retry\n- **The Outcome Loop**: record what actually happened (`/v1/decisions/{id}/outcome`, or by your own order id via `/v1/decisions/outcome-by-ref`) and read the calibration curve \u2014 how well reported confidence predicts real-world honored rates\n- **Knowledge Graph Management**: Create, query, and manipulate entities, triples, and logical rules\n- **Hybrid Reasoning**: Execute queries using configurable neural-symbolic reasoning strategies\n- **Program Synthesis**: Automatically learn and execute symbolic programs from examples\n- **Metered Marketplace Billing**: pay-as-you-go through AWS / Azure / GCP marketplaces or Stripe (`/v1/metering/*`)\n- **Advanced Features**: Graph-of-Thoughts reasoning, Vector Symbolic Architecture, and metacognition\n\n## API Surface Map\n\nThree URL prefixes, three roles:\n\n| Prefix | Role |\n|--------|------|\n| `/api/v1/*` | The platform API: knowledge base, reasoning, flywheel, billing, operations |\n| `/v1/*` | Product + compatibility surface: **Verified Decisions** (`/v1/decisions*`) and the OpenAI/Anthropic-compatible facades (`/v1/chat/completions`, `/v1/responses`, `/v1/messages`) that mimic provider paths by design |\n| `/api/v2/nsr/*` | The recursive chat solver. `v2` marks the recursive engine generation only \u2014 `/api/v1/*` is NOT deprecated |\n\nThe decisions family is also mounted at `/api/v1/decisions*` as an exact alias,\nso platform integrators can standardize on the single `/api/v1` prefix. The\nfull namespace policy is ADR-013 (`docs/adr/013-url-namespace-map.md`).\n\n**Which endpoint answers questions?** Use this hierarchy:\n\n1. `POST /v1/decisions` \u2014 accountable outcomes: approved/denied/refused with\n   machine-checkable proof, refusal repair (`missing_facts`), billing.\n2. `POST /api/v2/nsr/chat/solve` \u2014 recursive conversational reasoning with\n   grounding, verification, and org-context hydration.\n3. `POST /api/v1/reason` \u2014 direct knowledge-base queries (forward/backward\n   chaining, strategy selection).\n4. `/v1/chat/completions`, `/v1/responses`, `/v1/messages` \u2014 drop-in\n   provider-compatible facades over the same engine.\n\nOther ask-a-question routes (`/api/v1/rag/query`, `/api/v1/nsr/infer`,\n`/api/v1/agents/llm/generate`, streaming variants) are specialized or\nlegacy surfaces \u2014 prefer the four above for new integrations.\n\n**Encoding note:** belief propositions (`GET /api/v1/beliefs/{proposition}`)\nand composite triple IDs (`subject:predicate:object`) appear in URL paths \u2014\npercent-encode them; a proposition containing `/` or an ID segment\ncontaining `:` must be encoded or the route will not match.\n\n**Log-safety note:** `GET /api/v1/reason/stream` carries the query in the\nURL, which lands in access logs and proxies. Route sensitive workloads to\nthe POST variant.\n\n## Getting Started\n\n### 1. Obtain an API Key\nContact [support@stateset.com](mailto:support@stateset.com) or sign up at [stateset.com](https://stateset.com) to receive your API key.\n\n### 2. Make Your First Request\n```bash\ncurl -X GET \"https://api.nsr.stateset.com/health\" \\\n  -H \"X-API-Key: your-api-key\"\n```\n\n### 3. Create an Entity\n```bash\ncurl -X POST \"https://api.nsr.stateset.com/api/v1/entities\" \\\n  -H \"X-API-Key: your-api-key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"Customer\", \"entity_type\": \"class\"}'\n```\n\n## Authentication\n\n All API endpoints require authentication using one of the following methods, except for\npublic endpoints (e.g. `/health`, `/ready`, `/metrics`, `/docs`, `/api-docs`) when\n`public_routes_require_auth` is disabled in server configuration.\n\n### API Key (Recommended)\nInclude your API key in the `X-API-Key` header:\n```\nX-API-Key: your-api-key\n```\n\n### JWT Bearer Token\nFor OAuth2/OIDC integrations, use a JWT bearer token:\n```\nAuthorization: Bearer <your-jwt-token>\n```\n\nEnable JWT authentication by configuring `NSR_JWT_SECRET` and `NSR_JWT_ISSUER` environment variables.\n\n## Authorization Scopes\n\nAPI keys and JWT tokens carry scopes; every request is checked against the\nscope its route requires:\n\n| Scope | Description |\n|-------|-------------|\n| `read` | Read-only access (GET/HEAD/OPTIONS on org-scoped resources) |\n| `write` | Create and update resources (POST, PATCH, PUT) |\n| `admin` | Full access: all DELETEs, API-key management (`/api/v1/auth/keys`), and platform-global operator surfaces (`/api/v1/flywheel/curve`) |\n| `nsr:billing:write` | Billing mutations (`/api/v1/billing/*` writes; billing reads need only `read`) |\n| `models:manage` | Model lifecycle writes (`/api/v1/model*`, `/api/v1/machines`, `/api/v1/nsr/train`, `/api/v1/policy/train`) |\n| `sandbox:execute` | Action execution (`/api/v1/sandbox/*`, `/api/{v1,v2}/nsr/chat/executions/*`) |\n| `agents:admin` | Agent lifecycle management (`/api/v1/agents/*` \u2014 including restarts) |\n\nScope implication: `admin` satisfies every requirement; `write` also\nsatisfies `read`; the specialized scopes (`nsr:billing:write`,\n`models:manage`, `sandbox:execute`, `agents:admin`) satisfy only\nthemselves \u2014 grant them explicitly on keys that need those surfaces\nwithout full admin. Requests failing the scope check return 403.\n\n## Rate Limiting\n\n| Tier | Requests/Minute |\n|------|-----------------|\n| Free | 60 |\n| Starter | 300 |\n| Professional | 1,000 |\n| Enterprise | 10,000+ |\n\nLimits are enforced per key on a per-minute window; there is no separate\nburst allowance.\n\nRate limit headers are included on responses when rate limiting is enforced:\n- `X-RateLimit-Limit`: Maximum requests per window\n- `X-RateLimit-Remaining`: Requests remaining in current window\n- `X-RateLimit-Reset`: Seconds until the current window resets (also sent as `Retry-After` on 429s)\n\n## Error Handling\n\nAll errors return a consistent JSON structure:\n\n```json\n{\n  \"code\": \"validation_error\",\n  \"message\": \"Human-readable error description\",\n  \"request_id\": \"req_abc123\",\n  \"details\": { \"field\": \"name\", \"reason\": \"exceeds maximum length\" }\n}\n```\n\n### HTTP Status Codes\n\n| Code | Description |\n|------|-------------|\n| 200 | Success |\n| 201 | Resource created |\n| 202 | Accepted (async operation started) |\n| 204 | No content (successful deletion) |\n| 400 | Bad request (validation error) |\n| 401 | Unauthorized (missing/invalid credentials) |\n| 403 | Forbidden (insufficient permissions) |\n| 404 | Resource not found |\n| 409 | Conflict (resource state conflict) |\n| 422 | Unprocessable entity (semantic error) |\n| 429 | Too many requests (rate limited) |\n| 500 | Internal server error |\n| 503 | Service unavailable |\n\n## SDKs and Client Libraries\n\nOfficial SDKs (v0.4.3) live in the repo's `sdks/` directory:\n- **Python**: `pip install stateset-nsr`\n- **TypeScript/JavaScript**: `npm install stateset-nsr`\n- **Rust**: `cargo add stateset-nsr-sdk`\n- **Go**: `go get github.com/stateset/stateset-nsr/sdks/go`\n\nAll four ship automatic `Idempotency-Key` handling on decisions, typed\nerror-envelope parsing, and one-line webhook signature verification.\n\n## Changelog\n\n### v0.4.x (Current)\n- **Verified Decisions** (`POST /v1/decisions` + `/batch`): auditable\n  approved/denied/refused outcomes with cited proof chains, per-decision\n  billing headers, batch deadline contract, Stripe-style idempotency\n- **Webhooks**: five event types with HMAC-signed, retried deliveries;\n  durable org-scoped subscriptions; typed schemas throughout\n- **GSS grounding operability**: seed pack embedded in the binary,\n  `NSR_GSS_SEED_PATH` / `NSR_GSS_ORG_ALIASES` overrides,\n  `GET /api/v1/gss/seed` observability\n- Paper benchmarks at 10/10 targets with CI-enforced regression floors\n\n### v0.1.x\n- Initial release: core reasoning APIs, knowledge base management, async\n  jobs, Graph-of-Thoughts, VSA, metacognition, multi-tenant org scoping\n",
  "contact": {
   "name": "StateSet Support",
   "url": "https://stateset.com",
   "email": "support@stateset.com"
  },
  "license": {
   "name": "Business Source License 1.1",
   "url": "https://mariadb.com/bsl11/"
  },
  "version": "0.9.6"
 },
 "servers": [
  {
   "url": "https://api.nsr.stateset.com"
  }
 ],
 "paths": {
  "/api/v1/agents": {
   "get": {
    "tags": [
     "Agents"
    ],
    "description": "**Required scope:** `agents:admin`",
    "operationId": "list_agents_handler",
    "responses": {
     "200": {
      "description": "List all configured agents",
      "content": {
       "application/json": {
        "schema": {
         "type": "array",
         "items": {
          "$ref": "#/components/schemas/AgentRuntimeStatus"
         }
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/agents/llm/generate": {
   "post": {
    "tags": [
     "Reasoning"
    ],
    "summary": "Handler for POST /api/v1/agents/llm/generate",
    "description": "Direct access alias for the NS-RAG generation pipeline.\n\n**Required scope:** `agents:admin`",
    "operationId": "llm_generate_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "description": "Direct NS-RAG generation request",
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/RAGQueryRequest"
       },
       "example": {
        "include_sources": true,
        "query": "Summarize facts about France",
        "verify": true
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Generated response",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/RAGQueryResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "503": {
      "description": "LLM backend unavailable"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/agents/{agent_name}": {
   "get": {
    "tags": [
     "Agents"
    ],
    "description": "**Required scope:** `agents:admin`",
    "operationId": "get_agent_handler",
    "parameters": [
     {
      "name": "agent_name",
      "in": "path",
      "description": "Agent name",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Agent status",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/AgentRuntimeStatus"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Agent not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/agents/{agent_name}/restart": {
   "post": {
    "tags": [
     "Agents"
    ],
    "description": "**Required scope:** `agents:admin`",
    "operationId": "restart_agent_handler",
    "parameters": [
     {
      "name": "agent_name",
      "in": "path",
      "description": "Agent name",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Agent restarted",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/AgentActionResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Agent not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/agents/{agent_name}/start": {
   "post": {
    "tags": [
     "Agents"
    ],
    "description": "**Required scope:** `agents:admin`",
    "operationId": "start_agent_handler",
    "parameters": [
     {
      "name": "agent_name",
      "in": "path",
      "description": "Agent name",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Agent started",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/AgentActionResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Agent not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/agents/{agent_name}/stop": {
   "post": {
    "tags": [
     "Agents"
    ],
    "description": "**Required scope:** `agents:admin`",
    "operationId": "stop_agent_handler",
    "parameters": [
     {
      "name": "agent_name",
      "in": "path",
      "description": "Agent name",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Agent stopped",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/AgentActionResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Agent not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/answer": {
   "post": {
    "tags": [
     "Answer"
    ],
    "summary": "Answer one ticket.",
    "description": "**Required scope:** `write`",
    "operationId": "answer_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/AnswerRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "The answer, its evidence, and any tool call",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/AnswerResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "402": {
      "description": "Quota exhausted"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "422": {
      "description": "Malformed request"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/answer/batch": {
   "post": {
    "tags": [
     "Answer"
    ],
    "summary": "Answer a queue of tickets in one call.",
    "description": "**Required scope:** `write`",
    "operationId": "batch_answer_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/BatchAnswerRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "One answer per ticket",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/BatchAnswerResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/audit/deletions": {
   "get": {
    "tags": [
     "Audit"
    ],
    "summary": "Get deletion audit trail",
    "description": "Retrieve the deletion audit log.\n\n**Required scope:** `read`",
    "operationId": "get_deletion_audit_handler",
    "responses": {
     "200": {
      "description": "Deletion audit trail",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/AuditTrailResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/audit/export": {
   "get": {
    "tags": [
     "Compliance"
    ],
    "description": "**Required scope:** `read`",
    "operationId": "audit_export_handler",
    "parameters": [
     {
      "name": "since_ms",
      "in": "query",
      "description": "Unix millis lower bound",
      "required": false,
      "schema": {
       "type": "integer",
       "format": "int64",
       "nullable": true,
       "minimum": 0
      }
     },
     {
      "name": "until_ms",
      "in": "query",
      "description": "Unix millis upper bound",
      "required": false,
      "schema": {
       "type": "integer",
       "format": "int64",
       "nullable": true,
       "minimum": 0
      }
     },
     {
      "name": "limit",
      "in": "query",
      "description": "Max events (default 1000, capped at 10000)",
      "required": false,
      "schema": {
       "type": "integer",
       "nullable": true,
       "minimum": 0
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Audit events for the caller's org",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/AuditExportResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/auth/keys": {
   "get": {
    "tags": [
     "Authentication"
    ],
    "summary": "List API keys for the current org.",
    "description": "**Required scope:** `admin`",
    "operationId": "list_api_keys_handler",
    "responses": {
     "200": {
      "description": "API keys",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ApiKeyListResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   },
   "post": {
    "tags": [
     "Authentication"
    ],
    "summary": "Create a new API key for the current org.",
    "description": "**Required scope:** `admin`",
    "operationId": "create_api_key_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ApiKeyCreateRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "201": {
      "description": "API key created",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ApiKeyCreateResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/auth/keys/{id}": {
   "delete": {
    "tags": [
     "Authentication"
    ],
    "summary": "Revoke an API key by id.",
    "description": "**Required scope:** `admin`",
    "operationId": "revoke_api_key_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "API key revoked",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ApiKeyRevokeResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/auth/login": {
   "post": {
    "tags": [
     "Authentication"
    ],
    "summary": "Authenticate a user and return a fresh API key.",
    "description": "**Required scope:** `write`",
    "operationId": "auth_login_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/AuthLoginRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Login successful",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/AuthResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/auth/session": {
   "get": {
    "tags": [
     "Authentication"
    ],
    "summary": "Return the current authenticated API session context.",
    "description": "**Required scope:** `read`",
    "operationId": "auth_session_handler",
    "responses": {
     "200": {
      "description": "Authenticated session context",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/AuthSessionResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/auth/signup": {
   "post": {
    "tags": [
     "Authentication"
    ],
    "summary": "Create a new user account and return an API key.",
    "description": "**Required scope:** `write`",
    "operationId": "auth_signup_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/AuthSignupRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "201": {
      "description": "User created",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/AuthResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/backward-chain": {
   "post": {
    "tags": [
     "Reasoning"
    ],
    "summary": "Perform backward chaining to prove a goal",
    "description": "Perform backward-chaining proof search.\n\n**Required scope:** `write`",
    "operationId": "backward_chain_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/BackwardChainRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Backward chaining completed",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/BackwardChainResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "500": {
      "description": "Backward chaining failed"
     }
    }
   }
  },
  "/api/v1/beliefs": {
   "post": {
    "tags": [
     "Beliefs"
    ],
    "summary": "Add a new belief",
    "description": "**Required scope:** `write`",
    "operationId": "add_belief_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/AddBeliefRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "201": {
      "description": "Belief added",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/BeliefResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid belief"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/beliefs/conflicts": {
   "post": {
    "tags": [
     "Beliefs"
    ],
    "summary": "Check if two beliefs are conflicting",
    "description": "**Required scope:** `write`",
    "operationId": "check_conflicts_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CheckConflictsRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Conflict check result",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ConflictsResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/beliefs/contradict": {
   "post": {
    "tags": [
     "Beliefs"
    ],
    "summary": "Contradict a belief (decrease confidence)",
    "description": "**Required scope:** `write`",
    "operationId": "contradict_belief_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ModifyBeliefRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Belief contradicted",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ModifyBeliefResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Belief not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/beliefs/refute/{proposition}": {
   "post": {
    "tags": [
     "Beliefs"
    ],
    "summary": "Refute a belief (set confidence to zero)",
    "description": "**Required scope:** `write`",
    "operationId": "refute_belief_handler",
    "parameters": [
     {
      "name": "proposition",
      "in": "path",
      "description": "The proposition to refute",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Belief refuted",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ModifyBeliefResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/beliefs/support": {
   "post": {
    "tags": [
     "Beliefs"
    ],
    "summary": "Support a belief (increase confidence)",
    "description": "**Required scope:** `write`",
    "operationId": "support_belief_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ModifyBeliefRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Belief supported",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ModifyBeliefResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Belief not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/beliefs/{proposition}": {
   "get": {
    "tags": [
     "Beliefs"
    ],
    "summary": "Get a belief by proposition",
    "description": "**Required scope:** `read`",
    "operationId": "get_belief_handler",
    "parameters": [
     {
      "name": "proposition",
      "in": "path",
      "description": "The proposition",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Belief details",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/BeliefResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Belief not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/beliefs/{proposition}/explain": {
   "get": {
    "tags": [
     "Beliefs"
    ],
    "summary": "Get explanation for a belief",
    "description": "**Required scope:** `read`",
    "operationId": "explain_belief_handler",
    "parameters": [
     {
      "name": "proposition",
      "in": "path",
      "description": "The proposition",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Belief explanation",
      "content": {
       "text/plain": {
        "schema": {
         "type": "string"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/beliefs/{proposition}/history": {
   "get": {
    "tags": [
     "Beliefs"
    ],
    "summary": "Get history of revisions for a belief",
    "description": "**Required scope:** `read`",
    "operationId": "belief_history_handler",
    "parameters": [
     {
      "name": "proposition",
      "in": "path",
      "description": "The proposition",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Belief history",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/BeliefHistoryResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/billing/checkout": {
   "post": {
    "tags": [
     "Billing"
    ],
    "summary": "POST /api/v1/billing/checkout",
    "description": "Creates a Stripe Checkout session for the authenticated tenant.\n\n**Required scope:** `billing:write`",
    "operationId": "create_checkout_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CreateCheckoutRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Checkout session created",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/CreateCheckoutResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "503": {
      "description": "Billing not configured"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/billing/credits": {
   "get": {
    "tags": [
     "Billing"
    ],
    "summary": "GET /api/v1/billing/credits",
    "description": "**Required scope:** `read`",
    "operationId": "get_credits_handler",
    "responses": {
     "200": {
      "description": "Prepaid credit balance for the org"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "No Stripe customer for this org"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/billing/credits/checkout": {
   "post": {
    "tags": [
     "Billing"
    ],
    "summary": "POST /api/v1/billing/credits/checkout",
    "description": "**Required scope:** `billing:write`",
    "operationId": "create_credit_checkout_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CreateCreditCheckoutRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Credit checkout session created",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/CreateCreditCheckoutResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "503": {
      "description": "Billing not configured"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/billing/credits/purchase": {
   "post": {
    "tags": [
     "Billing"
    ],
    "description": "**Required scope:** `billing:write`",
    "operationId": "purchase_credits_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/PurchaseCreditsRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Credit purchase initiated"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "No Stripe customer for this org"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/billing/invoices": {
   "get": {
    "tags": [
     "Billing"
    ],
    "summary": "GET /api/v1/billing/invoices",
    "description": "**Required scope:** `read`",
    "operationId": "list_invoices_handler",
    "responses": {
     "200": {
      "description": "Recent Stripe invoices (latest 12): {invoices: [...]}"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "No Stripe customer for this org"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/billing/payment-methods": {
   "get": {
    "tags": [
     "Billing"
    ],
    "summary": "GET /api/v1/billing/payment-methods",
    "description": "**Required scope:** `read`",
    "operationId": "list_payment_methods_handler",
    "responses": {
     "200": {
      "description": "Stripe payment methods on file: {payment_methods: [...]}"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "No Stripe customer for this org"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/billing/plans": {
   "get": {
    "tags": [
     "Billing"
    ],
    "summary": "GET /api/v1/billing/plans",
    "description": "**Required scope:** `read`",
    "operationId": "list_plans_handler",
    "responses": {
     "200": {
      "description": "Available subscription plans with pricing and limits"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/billing/portal": {
   "post": {
    "tags": [
     "Billing"
    ],
    "summary": "POST /api/v1/billing/portal",
    "description": "Creates a Stripe Billing Portal session for self-service subscription\nmanagement (upgrade, cancel, payment methods, invoices).\n\n**Required scope:** `billing:write`",
    "operationId": "create_portal_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CreatePortalRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Portal session created",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/CreatePortalResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "503": {
      "description": "Billing not configured"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/billing/setup-payment": {
   "post": {
    "tags": [
     "Billing"
    ],
    "summary": "POST /api/v1/billing/setup-payment",
    "description": "**Required scope:** `billing:write`",
    "operationId": "setup_payment_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Stripe SetupIntent for collecting a payment method: {client_secret, setup_intent_id}"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "No Stripe customer for this org"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/billing/subscription": {
   "get": {
    "tags": [
     "Billing"
    ],
    "summary": "GET /api/v1/billing/subscription",
    "description": "Returns the tenant's current subscription details, or 404 if no\nsubscription is on file.\n\n**Required scope:** `read`",
    "operationId": "get_subscription_handler",
    "responses": {
     "200": {
      "description": "Subscription details",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SubscriptionResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "No subscription found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "503": {
      "description": "Billing not configured"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/billing/usage": {
   "get": {
    "tags": [
     "Billing"
    ],
    "summary": "GET /api/v1/billing/usage",
    "description": "Returns the tenant's current usage metrics from the tenancy system.\n\n**Required scope:** `read`",
    "operationId": "get_usage_handler",
    "responses": {
     "200": {
      "description": "Usage metrics",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/UsageResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/billing/webhooks/stripe": {
   "post": {
    "tags": [
     "Billing"
    ],
    "summary": "POST /api/v1/billing/webhooks/stripe",
    "description": "Stripe webhook receiver. This endpoint does NOT require org_id from auth;\nStripe signs the payload so the request is self-authenticating.\n\n**Required scope:** `write`",
    "operationId": "stripe_webhook_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "description": "",
     "content": {
      "application/octet-stream": {
       "schema": {
        "type": "string",
        "format": "binary"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Webhook processed"
     },
     "401": {
      "description": "Invalid signature"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "503": {
      "description": "Billing not configured"
     }
    }
   }
  },
  "/api/v1/compile": {
   "post": {
    "tags": [
     "Reasoning"
    ],
    "summary": "Handler for POST /api/v1/compile",
    "description": "**Required scope:** `write`",
    "operationId": "compile_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "description": "Natural language query to compile, with optional execute flag",
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CompileRequest"
       },
       "example": {
        "execute": false,
        "query": "What is the capital of France?"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Compilation succeeded",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/CompileResponse"
        },
        "example": {
         "bindings": null,
         "evidence": null,
         "ir": {
          "raw_query": "What is the capital of France?"
         },
         "plan": {
          "steps": []
         },
         "stats": {
          "bindings_found": 0,
          "total_us": 0
         }
        }
       }
      }
     },
     "400": {
      "description": "Compilation failed"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/constraints": {
   "get": {
    "tags": [
     "Constraints"
    ],
    "summary": "List all constraints",
    "description": "**Required scope:** `read`",
    "operationId": "list_constraints_handler",
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "description": "Maximum number of items to return (1-1000, default: 50)",
      "required": false,
      "schema": {
       "type": "integer",
       "default": 50,
       "nullable": true,
       "maximum": 1000,
       "minimum": 1
      }
     },
     {
      "name": "offset",
      "in": "query",
      "description": "Number of items to skip (default: 0)",
      "required": false,
      "schema": {
       "type": "integer",
       "default": 0,
       "nullable": true,
       "minimum": 0
      }
     },
     {
      "name": "cursor",
      "in": "query",
      "description": "Cursor for cursor-based pagination (alternative to offset)",
      "required": false,
      "schema": {
       "type": "string",
       "nullable": true
      }
     },
     {
      "name": "sort",
      "in": "query",
      "description": "Sort field with optional direction prefix (- for descending)\nExamples: \"created_at\", \"-name\", \"confidence\"",
      "required": false,
      "schema": {
       "type": "string",
       "nullable": true
      }
     }
    ],
    "responses": {
     "200": {
      "description": "List of constraints",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ListConstraintsResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   },
   "post": {
    "tags": [
     "Constraints"
    ],
    "summary": "Create a new constraint",
    "description": "**Required scope:** `write`",
    "operationId": "create_constraint_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CreateConstraintRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "201": {
      "description": "Constraint created",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ConstraintResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid constraint"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "409": {
      "description": "Constraint already exists"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/constraints/validate": {
   "post": {
    "tags": [
     "Constraints"
    ],
    "summary": "Validate facts against all constraints",
    "description": "**Required scope:** `write`",
    "operationId": "validate_constraints_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ValidateConstraintsRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Validation result",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ValidateConstraintsResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/constraints/{id}": {
   "get": {
    "tags": [
     "Constraints"
    ],
    "summary": "Get a specific constraint by ID",
    "description": "**Required scope:** `read`",
    "operationId": "get_constraint_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "Constraint ID",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Constraint details",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ConstraintResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Constraint not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   },
   "delete": {
    "tags": [
     "Constraints"
    ],
    "summary": "Delete a constraint",
    "description": "**Required scope:** `admin`",
    "operationId": "delete_constraint_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "Constraint ID",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "204": {
      "description": "Constraint deleted"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Constraint not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/conversations": {
   "get": {
    "tags": [
     "Conversations"
    ],
    "summary": "List conversations for the authenticated org.",
    "description": "**Required scope:** `read`",
    "operationId": "list_conversations_handler",
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "description": "Max results (default 50, max 100)",
      "required": false,
      "schema": {
       "type": "integer",
       "format": "int64",
       "nullable": true
      }
     },
     {
      "name": "offset",
      "in": "query",
      "description": "Pagination offset (default 0)",
      "required": false,
      "schema": {
       "type": "integer",
       "format": "int64",
       "nullable": true
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Paginated list of conversations",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ConversationListResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "503": {
      "description": "Database not configured"
     }
    }
   },
   "post": {
    "tags": [
     "Conversations"
    ],
    "summary": "Create a new conversation.",
    "description": "**Required scope:** `write`",
    "operationId": "create_conversation_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CreateConversationRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "201": {
      "description": "Conversation created",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Conversation"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "503": {
      "description": "Database not configured"
     }
    }
   }
  },
  "/api/v1/conversations/{id}": {
   "get": {
    "tags": [
     "Conversations"
    ],
    "summary": "Get a conversation with all its messages.",
    "description": "**Required scope:** `read`",
    "operationId": "get_conversation_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "Conversation ID",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Conversation with messages",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ConversationWithMessages"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Conversation not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "503": {
      "description": "Database not configured"
     }
    }
   },
   "delete": {
    "tags": [
     "Conversations"
    ],
    "summary": "Delete (soft-archive) a conversation.",
    "description": "**Required scope:** `admin`",
    "operationId": "delete_conversation_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "Conversation ID",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "204": {
      "description": "Conversation archived"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Conversation not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "503": {
      "description": "Database not configured"
     }
    }
   },
   "patch": {
    "tags": [
     "Conversations"
    ],
    "summary": "Update a conversation (title and/or archive status).",
    "description": "**Required scope:** `write`",
    "operationId": "update_conversation_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "Conversation ID",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/UpdateConversationRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Updated conversation",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Conversation"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Conversation not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "503": {
      "description": "Database not configured"
     }
    }
   }
  },
  "/api/v1/entities": {
   "get": {
    "tags": [
     "Entities"
    ],
    "summary": "List all entities in the knowledge base with pagination.",
    "description": "# Query Parameters\n- `limit`: Maximum number of results (default: 50)\n- `offset`: Number of results to skip (default: 0)\n\n# Response\nReturns a paginated list of all entities.\nList entities with pagination.\n\n**Required scope:** `read`",
    "operationId": "list_entities_handler",
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "description": "Maximum number of items to return (1-1000, default: 50)",
      "required": false,
      "schema": {
       "type": "integer",
       "default": 50,
       "nullable": true,
       "maximum": 1000,
       "minimum": 1
      }
     },
     {
      "name": "offset",
      "in": "query",
      "description": "Number of items to skip (default: 0)",
      "required": false,
      "schema": {
       "type": "integer",
       "default": 0,
       "nullable": true,
       "minimum": 0
      }
     },
     {
      "name": "cursor",
      "in": "query",
      "description": "Cursor for cursor-based pagination (alternative to offset)",
      "required": false,
      "schema": {
       "type": "string",
       "nullable": true
      }
     },
     {
      "name": "sort",
      "in": "query",
      "description": "Sort field with optional direction prefix (- for descending)\nExamples: \"created_at\", \"-name\", \"confidence\"",
      "required": false,
      "schema": {
       "type": "string",
       "nullable": true
      }
     }
    ],
    "responses": {
     "200": {
      "description": "List of entities",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PaginatedEntityResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   },
   "post": {
    "tags": [
     "Entities"
    ],
    "summary": "Create a new entity in the knowledge graph.",
    "description": "Entities are the fundamental building blocks of the knowledge graph. They\nrepresent concepts, instances, classes, properties, events, actions, or\ncustom types within your domain.\n\n# Request Body\n- `name`: The entity's display name (required, max 256 chars)\n- `entity_type`: Type of entity (concept, instance, class, property, event, action, state, or custom)\n- `properties`: Optional key-value pairs for additional metadata\n\n# Response\nReturns the created entity with its assigned unique identifier and\nautomatically generated embedding vector for semantic similarity search.\n\n# Errors\n- `400 Bad Request`: Invalid input (empty name, exceeds limits, invalid characters)\n- `500 Internal Server Error`: Entity creation or embedding generation failed\n\n## Example (curl)\n```bash\ncurl -X POST \"https://api.nsr.stateset.com/api/v1/entities\" \\\n-H \"X-API-Key: your-api-key\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\"name\": \"Customer\", \"entity_type\": \"class\", \"properties\": {\"description\": \"A person who purchases goods\"}}'\n```\nCreate a new knowledge graph entity.\n\n**Required scope:** `write`",
    "operationId": "create_entity_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "description": "Entity to create in the knowledge graph",
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CreateEntityRequest"
       },
       "example": {
        "entity_type": "class",
        "name": "Customer",
        "properties": {
         "description": "A person who purchases goods or services"
        }
       }
      }
     },
     "required": true
    },
    "responses": {
     "201": {
      "description": "Entity created successfully",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/EntityResponse"
        },
        "example": {
         "confidence": 1.0,
         "entity_type": "class",
         "has_embedding": true,
         "id": "ent_abc123",
         "name": "Customer",
         "properties": {
          "description": "A person who purchases goods or services"
         }
        }
       }
      }
     },
     "400": {
      "description": "Invalid request - validation failed",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ErrorResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/entities/batch": {
   "post": {
    "tags": [
     "Entities"
    ],
    "summary": "Batch create entities",
    "description": "Batch create entities.\n\n**Required scope:** `write`",
    "operationId": "batch_create_entities_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/BatchCreateEntitiesRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Per-item results; failures reported individually",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/BatchCreateEntitiesResponse"
        }
       }
      }
     },
     "400": {
      "description": "Batch exceeds max_batch_size"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   },
   "delete": {
    "tags": [
     "Entities"
    ],
    "summary": "Batch delete entities",
    "description": "Batch delete entities.\n\n**Required scope:** `admin`",
    "operationId": "batch_delete_entities_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/BatchDeleteEntitiesRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Batch deletion completed",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/BatchDeleteResponse"
        }
       }
      }
     },
     "400": {
      "description": "Batch size exceeds the configured maximum"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/entities/search": {
   "get": {
    "tags": [
     "Entities"
    ],
    "summary": "Search for entities matching a query pattern.",
    "description": "# Query Parameters\n- `q`: Search query (supports regex patterns)\n- `limit`: Maximum number of results (default: 10)\n\n# Response\nReturns a list of entities matching the search criteria.\nSearch entities by name/regex.\n\n**Required scope:** `read`",
    "operationId": "search_entities_handler",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "description": "Search query (supports regex patterns)",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "description": "Maximum results (default 10, capped at max_page_size)",
      "required": false,
      "schema": {
       "type": "integer",
       "nullable": true,
       "minimum": 0
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Entities matching the search",
      "content": {
       "application/json": {
        "schema": {
         "type": "array",
         "items": {
          "$ref": "#/components/schemas/EntityResponse"
         }
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/entities/{id}": {
   "get": {
    "tags": [
     "Entities"
    ],
    "summary": "Retrieve an entity by its unique identifier.",
    "description": "# Path Parameters\n- `id`: The entity's unique identifier (UUID format)\n\n# Response\nReturns the entity with all its properties and metadata.\n\n# Errors\n- `404 Not Found`: Entity with the specified ID does not exist\n\n**Required scope:** `read`",
    "operationId": "get_entity_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "Entity ID",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Entity details",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/EntityResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Entity not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   },
   "delete": {
    "tags": [
     "Entities"
    ],
    "summary": "Delete an entity by ID",
    "description": "Hard-delete an entity and its triples.\n\n**Required scope:** `admin`",
    "operationId": "delete_entity_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "Entity id",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Entity and its triples deleted"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "No such entity in this organization"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   },
   "patch": {
    "tags": [
     "Entities"
    ],
    "summary": "Update an entity",
    "description": "Update an entity's fields/properties.\n\n**Required scope:** `write`",
    "operationId": "update_entity_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "Entity ID",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/UpdateEntityRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Entity updated",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/EntityResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Entity not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/entities/{id}/soft": {
   "delete": {
    "tags": [
     "Entities"
    ],
    "summary": "Soft delete an entity (archives for audit trail)",
    "description": "Soft-delete (tombstone) an entity.\n\n**Required scope:** `admin`",
    "operationId": "soft_delete_entity_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "Entity ID",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/SoftDeleteRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Entity soft deleted"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Entity not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/events": {
   "get": {
    "tags": [
     "Reasoning"
    ],
    "summary": "Handler for GET /api/v1/events",
    "description": "Global event stream for monitoring all reasoning activity.\n\n**Required scope:** `read`",
    "operationId": "global_events_handler",
    "responses": {
     "200": {
      "description": "Global SSE event stream"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/evidence": {
   "get": {
    "tags": [
     "Knowledge Base"
    ],
    "summary": "Query evidence by claim or entity",
    "description": "**Required scope:** `read`",
    "operationId": "get_evidence_handler",
    "parameters": [
     {
      "name": "claim",
      "in": "query",
      "description": "Claim key to query evidence for",
      "required": false,
      "schema": {
       "type": "string",
       "nullable": true
      }
     },
     {
      "name": "entity_id",
      "in": "query",
      "description": "Entity ID to query evidence for",
      "required": false,
      "schema": {
       "type": "string",
       "nullable": true
      }
     },
     {
      "name": "q",
      "in": "query",
      "description": "Free-text search over evidence fields",
      "required": false,
      "schema": {
       "type": "string",
       "nullable": true
      }
     },
     {
      "name": "min_confidence",
      "in": "query",
      "description": "Minimum confidence threshold",
      "required": false,
      "schema": {
       "type": "number",
       "format": "float",
       "nullable": true
      }
     },
     {
      "name": "min_similarity",
      "in": "query",
      "description": "Minimum cosine similarity for semantic search (0.0..1.0)",
      "required": false,
      "schema": {
       "type": "number",
       "format": "float",
       "nullable": true
      }
     },
     {
      "name": "embedding_query",
      "in": "query",
      "description": "Natural language query for embedding-based evidence search",
      "required": false,
      "schema": {
       "type": "string",
       "nullable": true
      }
     },
     {
      "name": "query_embedding",
      "in": "query",
      "description": "Explicit query embedding as comma-separated floats",
      "required": false,
      "schema": {
       "type": "string",
       "nullable": true
      }
     },
     {
      "name": "limit",
      "in": "query",
      "description": "Maximum nodes to return (1..1000)",
      "required": false,
      "schema": {
       "type": "integer",
       "nullable": true,
       "minimum": 0
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Evidence nodes",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/EvidenceResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid query parameters"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   },
   "post": {
    "tags": [
     "Knowledge Base"
    ],
    "summary": "Create an evidence node.",
    "description": "**Required scope:** `write`",
    "operationId": "create_evidence_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "description": "Create evidence node request",
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CreateEvidenceRequest"
       },
       "example": {
        "claim": "acme:headquartered_in:sf",
        "confidence": 0.95,
        "evidence_type": "Assertion"
       }
      }
     },
     "required": true
    },
    "responses": {
     "201": {
      "description": "Evidence created",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/EvidenceNode"
        }
       }
      }
     },
     "400": {
      "description": "Invalid payload"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/evidence/stats": {
   "get": {
    "tags": [
     "Knowledge Base"
    ],
    "summary": "Get evidence graph stats",
    "description": "**Required scope:** `read`",
    "operationId": "get_evidence_stats_handler",
    "responses": {
     "200": {
      "description": "Evidence graph stats",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/EvidenceStatsResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/evidence/{id}": {
   "get": {
    "tags": [
     "Knowledge Base"
    ],
    "summary": "Retrieve one evidence node by ID.",
    "description": "**Required scope:** `read`",
    "operationId": "get_evidence_by_id_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "Evidence node ID",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Evidence node",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/EvidenceNode"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Evidence not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   },
   "delete": {
    "tags": [
     "Knowledge Base"
    ],
    "summary": "Delete one evidence node by ID.",
    "description": "**Required scope:** `admin`",
    "operationId": "delete_evidence_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "Evidence node ID",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "204": {
      "description": "Evidence deleted"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Evidence not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   },
   "patch": {
    "tags": [
     "Knowledge Base"
    ],
    "summary": "Update one evidence node by ID.",
    "description": "**Required scope:** `write`",
    "operationId": "update_evidence_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "Evidence node ID",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "description": "Partial evidence update",
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/UpdateEvidenceRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Evidence updated",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/EvidenceNode"
        }
       }
      }
     },
     "400": {
      "description": "Invalid payload"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Evidence not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/evidence/{id}/chain": {
   "get": {
    "tags": [
     "Knowledge Base"
    ],
    "summary": "Get a specific evidence node and trace its full dependency chain",
    "description": "**Required scope:** `read`",
    "operationId": "get_evidence_chain_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "Evidence node ID",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Evidence chain",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/EvidenceChainResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Evidence node not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/explain": {
   "post": {
    "tags": [
     "Reasoning"
    ],
    "summary": "Generate an explanation for a query",
    "description": "Generate a post-hoc explanation for a query.\n\n**Required scope:** `write`",
    "operationId": "explain_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ExplainRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Explanation generated",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ExplainResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "500": {
      "description": "Failed to generate explanation"
     }
    }
   }
  },
  "/api/v1/flywheel/candidates": {
   "get": {
    "tags": [
     "Flywheel"
    ],
    "summary": "GET /api/v1/flywheel/candidates?status=pending",
    "description": "**Required scope:** `read`",
    "operationId": "flywheel_candidates_handler",
    "parameters": [
     {
      "name": "status",
      "in": "query",
      "description": "Filter by candidate status: pending, approved, rejected, auto_promoted",
      "required": false,
      "schema": {
       "type": "string",
       "nullable": true
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Promotion candidates",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/FlywheelCandidatesResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid status filter"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/flywheel/candidates/{id}/review": {
   "post": {
    "tags": [
     "Flywheel"
    ],
    "summary": "POST /api/v1/flywheel/candidates/:id/review",
    "description": "**Required scope:** `write`",
    "operationId": "flywheel_review_candidate_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "Promotion candidate ID",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "description": "Review action",
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ReviewCandidateRequest"
       },
       "example": {
        "approve": true,
        "reviewer": "alice@example.com"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Candidate reviewed",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ReviewCandidateResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid reviewer"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Candidate not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/flywheel/curve": {
   "get": {
    "tags": [
     "Flywheel"
    ],
    "summary": "GET /api/v1/flywheel/curve",
    "description": "The learning curve: one point per active learning cycle (what changed +\nthe recent success rate at that instant). This series is the evidence\nthat the platform improves on real traffic \u2014 the real-traffic validation\nartifact the launch plan calls for.\n\n**Required scope:** `admin`",
    "operationId": "flywheel_curve_handler",
    "responses": {
     "200": {
      "description": "Learning-curve points, oldest first"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/flywheel/demote-noisy": {
   "post": {
    "tags": [
     "Flywheel"
    ],
    "summary": "Noise-based rule demotion \u2014 the pruning counterpart of evidence-based",
    "description": "promotion. Disables mined `flywheel:*` rules that fire on decisions\nwithout ever being relevant (high noise ratio over a minimum sample);\ncurated policy is flagged for an operator but never auto-disabled.\n\n**Required scope:** `write`",
    "operationId": "flywheel_demote_noisy_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/DemoteNoisyRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Demotion result",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/DemoteNoisyResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/flywheel/events": {
   "get": {
    "tags": [
     "Flywheel"
    ],
    "summary": "GET /api/v1/flywheel/events?limit=100",
    "description": "**Required scope:** `read`",
    "operationId": "flywheel_events_handler",
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "description": "Maximum number of events to return (1..1000)",
      "required": false,
      "schema": {
       "type": "integer",
       "nullable": true,
       "minimum": 0
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Recent learning events",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/FlywheelEventsResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/flywheel/feedback": {
   "post": {
    "tags": [
     "Flywheel"
    ],
    "summary": "POST /api/v1/flywheel/feedback",
    "description": "**Required scope:** `write`",
    "operationId": "flywheel_feedback_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "description": "Explicit user feedback event",
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/FeedbackRequest"
       },
       "example": {
        "answer": "Paris",
        "comment": "Correct",
        "positive": true,
        "query": "What is the capital of France?"
       }
      }
     },
     "required": true
    },
    "responses": {
     "202": {
      "description": "Feedback accepted"
     },
     "400": {
      "description": "Query/answer missing"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/flywheel/process": {
   "post": {
    "tags": [
     "Flywheel"
    ],
    "summary": "POST /api/v1/flywheel/process",
    "description": "**Required scope:** `write`",
    "operationId": "flywheel_process_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Processed queue and generated promotion candidates",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/FlywheelProcessResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/flywheel/stats": {
   "get": {
    "tags": [
     "Flywheel"
    ],
    "summary": "GET /api/v1/flywheel/stats",
    "description": "**Required scope:** `read`",
    "operationId": "flywheel_stats_handler",
    "responses": {
     "200": {
      "description": "Flywheel aggregate statistics",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/FlywheelStats"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/flywheel/train": {
   "post": {
    "tags": [
     "Flywheel"
    ],
    "summary": "POST /api/v1/flywheel/train",
    "description": "Trigger flywheel-driven training for the authenticated org.\n\nCollects recent learning events, converts them to training examples,\nand runs a training batch through the NSR Machine's deduction-abduction learner.\n\n**Required scope:** `write`",
    "operationId": "flywheel_train_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Not enough events to train"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/forward-chain": {
   "post": {
    "tags": [
     "Reasoning"
    ],
    "summary": "Forward chaining endpoint with parameters",
    "description": "Derives new facts by applying rules to the knowledge base.\nSupports fine-grained control over inference depth, iterations, and which rules to apply.\nRun forward-chaining inference over the knowledge base.\n\n**Required scope:** `write`",
    "operationId": "forward_chain_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ForwardChainRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Inference completed",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ForwardChainResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid parameters"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/gss/seed": {
   "get": {
    "tags": [
     "GSS"
    ],
    "summary": "Live GSS seed-pack metadata.",
    "description": "**Required scope:** `read`",
    "operationId": "gss_seed_info_handler",
    "responses": {
     "200": {
      "description": "Live seed-pack metadata",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/GssSeedInfoResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/jobs": {
   "get": {
    "tags": [
     "Jobs"
    ],
    "summary": "List all jobs with filtering and pagination",
    "description": "**Required scope:** `read`",
    "operationId": "list_jobs",
    "parameters": [
     {
      "name": "status",
      "in": "query",
      "description": "Filter by status",
      "required": false,
      "schema": {
       "allOf": [
        {
         "$ref": "#/components/schemas/JobStatus"
        }
       ],
       "nullable": true
      }
     },
     {
      "name": "job_type",
      "in": "query",
      "description": "Filter by job type",
      "required": false,
      "schema": {
       "allOf": [
        {
         "$ref": "#/components/schemas/JobType"
        }
       ],
       "nullable": true
      }
     },
     {
      "name": "limit",
      "in": "query",
      "description": "Maximum results (default: 100)",
      "required": false,
      "schema": {
       "type": "integer",
       "nullable": true,
       "minimum": 0
      }
     },
     {
      "name": "offset",
      "in": "query",
      "description": "Pagination offset (default: 0)",
      "required": false,
      "schema": {
       "type": "integer",
       "nullable": true,
       "minimum": 0
      }
     },
     {
      "name": "sort_by",
      "in": "query",
      "description": "Sort field (created_at, updated_at)",
      "required": false,
      "schema": {
       "type": "string",
       "nullable": true
      }
     },
     {
      "name": "sort_order",
      "in": "query",
      "description": "Sort order (asc, desc)",
      "required": false,
      "schema": {
       "type": "string",
       "nullable": true
      }
     },
     {
      "name": "created_after",
      "in": "query",
      "description": "Only jobs created after this timestamp",
      "required": false,
      "schema": {
       "type": "integer",
       "format": "int64",
       "nullable": true,
       "minimum": 0
      }
     },
     {
      "name": "created_before",
      "in": "query",
      "description": "Only jobs created before this timestamp",
      "required": false,
      "schema": {
       "type": "integer",
       "format": "int64",
       "nullable": true,
       "minimum": 0
      }
     }
    ],
    "responses": {
     "200": {
      "description": "List of jobs",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ListJobsResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/jobs/batch-infer": {
   "post": {
    "tags": [
     "Jobs"
    ],
    "summary": "Submit a batch inference job",
    "description": "Submits a batch of queries for asynchronous processing. Returns immediately\nwith a job ID that can be used to track progress and retrieve results.\n\n## Use Cases\n- Processing large datasets that exceed single-request timeouts\n- Running inference on multiple queries in parallel\n- Background processing without blocking the client\n\n## Example\n```bash\ncurl -X POST \"https://api.nsr.stateset.com/api/v1/jobs/batch-infer\" \\\n-H \"X-API-Key: your-api-key\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\"inputs\": [\"query 1\", \"query 2\", \"query 3\"], \"max_depth\": 5}'\n```\n\n**Required scope:** `write`",
    "operationId": "submit_batch_infer_job",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "description": "Batch inference job submission",
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/BatchInferRequest"
       },
       "example": {
        "include_explanation": false,
        "inputs": [
         "What is the capital of France?",
         "Who wrote Hamlet?",
         "What is 2+2?"
        ],
        "max_depth": 5
       }
      }
     },
     "required": true
    },
    "responses": {
     "202": {
      "description": "Job submitted successfully",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/JobSubmitResponse"
        },
        "example": {
         "job_id": "job_0000000000000042",
         "status": "pending",
         "total_items": 3
        }
       }
      }
     },
     "400": {
      "description": "Invalid request - no inputs or too many items",
      "content": {
       "text/plain": {
        "schema": {
         "type": "string"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "503": {
      "description": "Service unavailable - job queue full",
      "content": {
       "text/plain": {
        "schema": {
         "type": "string"
        }
       }
      }
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/jobs/{job_id}": {
   "get": {
    "tags": [
     "Jobs"
    ],
    "summary": "Get job status",
    "description": "Retrieves the current status and results of an asynchronous job.\nPoll this endpoint to track job progress and retrieve results when complete.\n\n## Example\n```bash\ncurl -X GET \"https://api.nsr.stateset.com/api/v1/jobs/job_0000000000000042\" \\\n-H \"X-API-Key: your-api-key\"\n```\n\n**Required scope:** `read`",
    "operationId": "get_job_status",
    "parameters": [
     {
      "name": "job_id",
      "in": "path",
      "description": "Unique job identifier returned from job submission",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Job status and results",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/JobStatusResponse"
        },
        "example": {
         "job": {
          "completed_at": 1702000060000,
          "created_at": 1702000000000,
          "id": "job_0000000000000042",
          "input": {
           "inputs": [
            "query 1",
            "query 2",
            "query 3"
           ]
          },
          "job_type": "batch_infer",
          "progress": 100,
          "result": {
           "results": [],
           "successful": 3,
           "total_processed": 3
          },
          "status": "completed",
          "updated_at": 1702000060000
         }
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Job not found",
      "content": {
       "text/plain": {
        "schema": {
         "type": "string"
        }
       }
      }
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   },
   "delete": {
    "tags": [
     "Jobs"
    ],
    "summary": "Delete a completed job",
    "description": "**Required scope:** `admin`",
    "operationId": "delete_job",
    "parameters": [
     {
      "name": "job_id",
      "in": "path",
      "description": "Job identifier",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "204": {
      "description": "Job deleted"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Job not found"
     },
     "409": {
      "description": "Cannot delete running job"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/jobs/{job_id}/cancel": {
   "post": {
    "tags": [
     "Jobs"
    ],
    "summary": "Cancel a running job",
    "description": "**Required scope:** `write`",
    "operationId": "cancel_job",
    "parameters": [
     {
      "name": "job_id",
      "in": "path",
      "description": "Job identifier",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Job cancelled",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/CancelJobResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Job not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/kb/diff": {
   "get": {
    "tags": [
     "Knowledge Base"
    ],
    "summary": "Handler for GET /api/v1/kb/diff",
    "description": "**Required scope:** `read`",
    "operationId": "kb_diff_handler",
    "parameters": [
     {
      "name": "from",
      "in": "query",
      "description": "RFC3339 start timestamp",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "to",
      "in": "query",
      "description": "RFC3339 end timestamp",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "org_id",
      "in": "query",
      "description": "Optional org filter",
      "required": false,
      "schema": {
       "type": "string",
       "nullable": true
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Diff between two KB snapshots",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/KBDiffResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid timestamp window"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/kb/graph": {
   "post": {
    "tags": [
     "Knowledge Base"
    ],
    "summary": "Perform graph analysis on the knowledge base",
    "description": "Analyze the knowledge graph structure.\n\n**Required scope:** `write`",
    "operationId": "graph_analysis_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "description": "",
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/GraphAnalysisRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Graph analysis result (centrality, clusters, or paths per the requested analysis_type)"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/kb/history": {
   "get": {
    "tags": [
     "Knowledge Base"
    ],
    "summary": "Handler for GET /api/v1/kb/history",
    "description": "**Required scope:** `read`",
    "operationId": "kb_history_handler",
    "parameters": [
     {
      "name": "since",
      "in": "query",
      "description": "RFC3339 lower bound timestamp",
      "required": false,
      "schema": {
       "type": "string",
       "nullable": true
      }
     },
     {
      "name": "until",
      "in": "query",
      "description": "RFC3339 upper bound timestamp",
      "required": false,
      "schema": {
       "type": "string",
       "nullable": true
      }
     },
     {
      "name": "org_id",
      "in": "query",
      "description": "Optional org filter",
      "required": false,
      "schema": {
       "type": "string",
       "nullable": true
      }
     },
     {
      "name": "limit",
      "in": "query",
      "description": "Max events to return (default 100)",
      "required": false,
      "schema": {
       "type": "integer",
       "nullable": true,
       "minimum": 0
      }
     }
    ],
    "responses": {
     "200": {
      "description": "KB history events",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/HistoryResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid timestamp"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/kb/snapshot": {
   "get": {
    "tags": [
     "Knowledge Base"
    ],
    "summary": "Handler for GET /api/v1/kb/snapshot",
    "description": "**Required scope:** `read`",
    "operationId": "kb_snapshot_handler",
    "parameters": [
     {
      "name": "as_of",
      "in": "query",
      "description": "RFC3339 timestamp for snapshot reconstruction",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Point-in-time KB snapshot",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SnapshotResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid timestamp"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/kb/stats": {
   "get": {
    "tags": [
     "Knowledge Base"
    ],
    "summary": "Get detailed knowledge base statistics",
    "description": "Return basic KB statistics.\n\n**Required scope:** `read`",
    "operationId": "kb_stats_handler",
    "responses": {
     "200": {
      "description": "Knowledge-base statistics for the org: entity/triple/rule counts, type breakdowns"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/machines": {
   "get": {
    "tags": [
     "Machines"
    ],
    "summary": "GET /api/v1/machines \u2014 List all provisioned machines for the authenticated org.",
    "description": "**Required scope:** `read`",
    "operationId": "list_machines_handler",
    "responses": {
     "200": {
      "description": "List of provisioned NSR machines",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/MachinesListResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/machines/activate": {
   "post": {
    "tags": [
     "Machines"
    ],
    "summary": "POST /api/v1/machines/activate \u2014 Activate a compiled seed pack into the org KB and brand machine.",
    "description": "**Required scope:** `models:manage`",
    "operationId": "activate_machine_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/MachineActivateRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Machine activated",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/MachineActivateResponse"
        }
       }
      }
     },
     "202": {
      "description": "Machine activation started",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/MachineActivateResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Compiled machine spec not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/machines/compile": {
   "post": {
    "tags": [
     "Machines"
    ],
    "summary": "POST /api/v1/machines/compile \u2014 Compile a seed pack into ingest and training artifacts.",
    "description": "**Required scope:** `models:manage`",
    "operationId": "compile_machine_seed_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/MachineCompileRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "201": {
      "description": "Machine spec compiled",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/MachineCompileResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Seed pack not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/machines/evaluate": {
   "post": {
    "tags": [
     "Machines"
    ],
    "summary": "POST /api/v1/machines/evaluate \u2014 Evaluate the org's machine on test examples.",
    "description": "**Required scope:** `models:manage`",
    "operationId": "evaluate_machine_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/EvaluateRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Evaluation results",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/EvaluateResponse"
        }
       }
      }
     },
     "400": {
      "description": "No test examples provided"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Machine not provisioned"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/machines/evaluate-seed": {
   "post": {
    "tags": [
     "Machines"
    ],
    "summary": "POST /api/v1/machines/evaluate-seed \u2014 Score whether a compiled seed pack is activation-ready.",
    "description": "**Required scope:** `models:manage`",
    "operationId": "evaluate_seed_machine_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/MachineSeedEvaluateRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Seed readiness evaluation",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/MachineSeedEvaluateResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Compiled machine spec not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/machines/infer": {
   "post": {
    "tags": [
     "Machines"
    ],
    "summary": "POST /api/v1/machines/infer \u2014 Run inference on the org's machine directly.",
    "description": "**Required scope:** `models:manage`",
    "operationId": "infer_machine_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/InferRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Inference result",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/InferResponse"
        }
       }
      }
     },
     "400": {
      "description": "No inputs provided"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Machine not provisioned"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/machines/provision": {
   "post": {
    "tags": [
     "Machines"
    ],
    "summary": "POST /api/v1/machines/provision \u2014 Provision (or re-provision) a machine for the authenticated org.",
    "description": "**Required scope:** `models:manage`",
    "operationId": "provision_machine_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ProvisionRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "201": {
      "description": "Machine provisioned successfully",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ProvisionResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "500": {
      "description": "Failed to provision machine"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/machines/seed": {
   "post": {
    "tags": [
     "Machines"
    ],
    "summary": "POST /api/v1/machines/seed \u2014 Create a standard seed pack for a brand/org.",
    "description": "**Required scope:** `models:manage`",
    "operationId": "seed_machine_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/MachineSeedRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "201": {
      "description": "Machine seed pack created",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/MachineSeedResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid seed pack"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/machines/status": {
   "get": {
    "tags": [
     "Machines"
    ],
    "summary": "GET /api/v1/machines/status \u2014 Get machine status for the authenticated org.",
    "description": "**Required scope:** `read`",
    "operationId": "machine_status_handler",
    "responses": {
     "200": {
      "description": "Machine status for the org",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/MachineInfo"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Machine not provisioned"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/machines/train": {
   "post": {
    "tags": [
     "Machines"
    ],
    "summary": "POST /api/v1/machines/train \u2014 Train the org's machine from flywheel events + optional examples.",
    "description": "**Required scope:** `models:manage`",
    "operationId": "train_machine_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/TrainRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Training completed",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/TrainResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Machine not provisioned"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "500": {
      "description": "Training failed"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/macros": {
   "get": {
    "tags": [
     "Macros"
    ],
    "summary": "List this org's macros.",
    "description": "**Required scope:** `read`",
    "operationId": "list_macros_handler",
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "description": "Page size",
      "required": false,
      "schema": {
       "type": "integer",
       "nullable": true,
       "minimum": 0
      }
     },
     {
      "name": "offset",
      "in": "query",
      "description": "Page offset",
      "required": false,
      "schema": {
       "type": "integer",
       "nullable": true,
       "minimum": 0
      }
     },
     {
      "name": "status",
      "in": "query",
      "description": "candidate | approved | archived",
      "required": false,
      "schema": {
       "type": "string",
       "nullable": true
      }
     },
     {
      "name": "rule_name",
      "in": "query",
      "description": "Only macros bound to this policy rule",
      "required": false,
      "schema": {
       "type": "string",
       "nullable": true
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Macros for this organization",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ListMacrosResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   },
   "post": {
    "tags": [
     "Macros"
    ],
    "summary": "Create or replace a macro.",
    "description": "**Required scope:** `write`",
    "operationId": "create_macro_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CreateMacroRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "201": {
      "description": "Macro created or replaced",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Macro"
        }
       }
      }
     },
     "400": {
      "description": "Invalid macro (empty body, unbalanced merge fields)"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/macros/batch": {
   "post": {
    "tags": [
     "Macros"
    ],
    "summary": "Upload a whole library in one call.",
    "description": "**Required scope:** `write`",
    "operationId": "batch_create_macros_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/BatchCreateMacrosRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Batch upload result",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/BatchCreateMacrosResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/macros/{id}": {
   "get": {
    "tags": [
     "Macros"
    ],
    "summary": "Fetch one macro by id.",
    "description": "**Required scope:** `read`",
    "operationId": "get_macro_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "Macro id",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The macro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Macro"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "No such macro in this organization"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   },
   "delete": {
    "tags": [
     "Macros"
    ],
    "summary": "Delete a macro.",
    "description": "**Required scope:** `admin`",
    "operationId": "delete_macro_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "Macro id",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Macro deleted"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "No such macro in this organization"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   },
   "patch": {
    "tags": [
     "Macros"
    ],
    "summary": "Update macro metadata \u2014 approve it, bind it to a rule, toggle auto-send.",
    "description": "**Required scope:** `write`",
    "operationId": "update_macro_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "Macro id",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/UpdateMacroRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Updated macro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Macro"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "No such macro in this organization"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/macros/{id}/render": {
   "post": {
    "tags": [
     "Macros"
    ],
    "summary": "Render a macro against a context \u2014 the dry run before sending.",
    "description": "**Required scope:** `write`",
    "operationId": "render_macro_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "Macro id",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/RenderMacroRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Rendered text and any unfilled slots",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/RenderMacroResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "No such macro in this organization"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/model/checkpoints": {
   "get": {
    "tags": [
     "Model"
    ],
    "summary": "List model checkpoints",
    "description": "**Required scope:** `read`",
    "operationId": "list_checkpoints",
    "responses": {
     "200": {
      "description": "List of checkpoints",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ListCheckpointsResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   },
   "post": {
    "tags": [
     "Model"
    ],
    "summary": "Save model checkpoint",
    "description": "**Required scope:** `models:manage`",
    "operationId": "save_checkpoint",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/SaveCheckpointRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "201": {
      "description": "Checkpoint created",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SaveCheckpointResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/model/checkpoints/{checkpoint_id}": {
   "get": {
    "tags": [
     "Model"
    ],
    "summary": "Get checkpoint details",
    "description": "**Required scope:** `read`",
    "operationId": "get_checkpoint",
    "parameters": [
     {
      "name": "checkpoint_id",
      "in": "path",
      "description": "Checkpoint identifier",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Checkpoint details",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ModelCheckpoint"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Checkpoint not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   },
   "delete": {
    "tags": [
     "Model"
    ],
    "summary": "Delete checkpoint",
    "description": "**Required scope:** `models:manage`",
    "operationId": "delete_checkpoint",
    "parameters": [
     {
      "name": "checkpoint_id",
      "in": "path",
      "description": "Checkpoint identifier",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "204": {
      "description": "Checkpoint deleted"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Checkpoint not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/model/checkpoints/{checkpoint_id}/load": {
   "post": {
    "tags": [
     "Model"
    ],
    "summary": "Load checkpoint (restore model state)",
    "description": "**Required scope:** `models:manage`",
    "operationId": "load_checkpoint",
    "parameters": [
     {
      "name": "checkpoint_id",
      "in": "path",
      "description": "Checkpoint identifier",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Checkpoint loaded"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Checkpoint not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/model/compare": {
   "post": {
    "tags": [
     "Model"
    ],
    "summary": "Compare two model checkpoints",
    "description": "**Required scope:** `models:manage`",
    "operationId": "compare_models",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CompareModelsRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Comparison result",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ModelComparison"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Checkpoint not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/model/export": {
   "post": {
    "tags": [
     "Model"
    ],
    "summary": "Export model",
    "description": "**Required scope:** `models:manage`",
    "operationId": "export_model",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ExportModelRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "501": {
      "description": "Model export is not yet implemented"
     }
    }
   }
  },
  "/api/v1/model/info": {
   "get": {
    "tags": [
     "Model"
    ],
    "summary": "Get current model information",
    "description": "**Required scope:** `read`",
    "operationId": "get_model_info",
    "responses": {
     "200": {
      "description": "Model information",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ModelInfoResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/nsr/chat": {
   "post": {
    "tags": [
     "nsr"
    ],
    "summary": "Analyze a customer message and return a grounded recursive completion.",
    "description": "**Required scope:** `write`",
    "operationId": "nsr_chat_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ChatRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Symbolic analysis plus grounded recursive completion",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ChatResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Org mismatch with authenticated scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "503": {
      "description": "GSS seed not loaded"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/nsr/chat/executions/{receipt_id}": {
   "post": {
    "tags": [
     "nsr"
    ],
    "description": "**Required scope:** `sandbox:execute`",
    "operationId": "nsr_chat_execute_actions_handler",
    "parameters": [
     {
      "name": "receipt_id",
      "in": "path",
      "description": "Execution receipt issued by the chat endpoint",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ChatActionExecutionRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Executed selected chat actions against stored chat context",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ChatResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Receipt does not match authenticated org scope"
     },
     "404": {
      "description": "Receipt not found or expired"
     },
     "422": {
      "description": "Requested actions are not executable for this receipt"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/nsr/chat/stream": {
   "post": {
    "tags": [
     "nsr"
    ],
    "summary": "POST /api/v1/nsr/chat/stream",
    "description": "Accepts a chat message and returns an SSE stream that progressively emits\nsymbolic analysis, grounding status, reply tokens, and the final response.\n\n**Required scope:** `write`",
    "operationId": "nsr_chat_stream_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "description": "Streaming chat request",
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/StreamChatRequest"
       },
       "example": {
        "conversation_id": null,
        "message": "I want to return my order",
        "session_id": null
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "SSE stream of ChatStreamEvent"
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "422": {
      "description": "Message too long"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/nsr/evaluate": {
   "post": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "Evaluate the NSR Machine on test examples",
    "description": "**Required scope:** `write`",
    "operationId": "nsr_evaluate_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/EvaluateRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Evaluation results",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/EvaluateResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "500": {
      "description": "Evaluation failed"
     }
    }
   }
  },
  "/api/v1/nsr/features": {
   "get": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "List all features and their status",
    "description": "Returns the status of all NSR Machine features, indicating which are\ncurrently enabled and which are available for activation.\n\n## Available Features\n- `library_learning`: Extract reusable program components\n- `metacognition`: Uncertainty estimation and strategy selection\n- `explainability`: Generate human-readable explanations\n- `continual_learning`: EWC-based catastrophic forgetting prevention\n- `mcts`: Monte Carlo Tree Search for program synthesis\n- `probabilistic`: Probabilistic reasoning with uncertainty\n- `graph_of_thoughts`: Branching reasoning with thought graphs\n- `inference_scaling`: Compute scaling for better results\n- `vsa`: Vector Symbolic Architecture for compositional semantics\n- `differentiable_logic`: Differentiable logical operations\n\n## Example\n```bash\ncurl -X GET \"https://api.nsr.stateset.com/api/v1/nsr/features\" \\\n-H \"X-API-Key: your-api-key\"\n```\n\n**Required scope:** `read`",
    "operationId": "list_features_handler",
    "responses": {
     "200": {
      "description": "List of features with status",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/FeaturesResponse"
        },
        "example": {
         "available_features": [
          "library_learning",
          "metacognition",
          "explainability",
          "continual_learning",
          "mcts",
          "probabilistic",
          "graph_of_thoughts",
          "inference_scaling",
          "vsa",
          "differentiable_logic"
         ],
         "enabled_features": [
          "library_learning",
          "metacognition",
          "explainability"
         ]
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   },
   "post": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "Toggle a feature on or off",
    "description": "Enable or disable a specific NSR Machine feature. Changes take effect immediately\nand persist across requests within the session.\n\n## Example: Enable Graph-of-Thoughts\n```bash\ncurl -X POST \"https://api.nsr.stateset.com/api/v1/nsr/features\" \\\n-H \"X-API-Key: your-api-key\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\"feature\": \"graph_of_thoughts\", \"enabled\": true}'\n```\n\n**Required scope:** `write`",
    "operationId": "toggle_feature_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "description": "Feature toggle request",
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ToggleFeatureRequest"
       },
       "example": {
        "enabled": true,
        "feature": "graph_of_thoughts"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Feature toggled successfully",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/FeaturesResponse"
        },
        "example": {
         "available_features": [
          "library_learning",
          "metacognition",
          "explainability",
          "continual_learning",
          "mcts",
          "probabilistic",
          "graph_of_thoughts",
          "inference_scaling",
          "vsa",
          "differentiable_logic"
         ],
         "enabled_features": [
          "library_learning",
          "metacognition",
          "graph_of_thoughts"
         ]
        }
       }
      }
     },
     "400": {
      "description": "Invalid feature name",
      "content": {
       "text/plain": {
        "schema": {
         "type": "string"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/nsr/got": {
   "get": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "Get Graph of Thoughts status",
    "description": "**Required scope:** `read`",
    "operationId": "got_status_handler",
    "responses": {
     "200": {
      "description": "GoT status",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/GraphOfThoughtsResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/nsr/got/branch": {
   "post": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "Branch from a parent thought to multiple children",
    "description": "**Required scope:** `write`",
    "operationId": "branch_thoughts_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/BranchThoughtsRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Branched successfully",
      "content": {
       "application/json": {
        "schema": {
         "type": "array",
         "items": {
          "$ref": "#/components/schemas/ThoughtResponse"
         }
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "503": {
      "description": "GoT not enabled"
     }
    }
   }
  },
  "/api/v1/nsr/got/connect": {
   "post": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "Connect two thoughts in the graph",
    "description": "**Required scope:** `write`",
    "operationId": "connect_thoughts_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ConnectThoughtsRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Thoughts connected"
     },
     "400": {
      "description": "Invalid connection"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "503": {
      "description": "GoT not enabled"
     }
    }
   }
  },
  "/api/v1/nsr/got/thoughts": {
   "get": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "List/search Graph-of-Thoughts nodes",
    "description": "**Required scope:** `read`",
    "operationId": "list_thoughts_handler",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "description": "Optional substring filter (case-insensitive)",
      "required": false,
      "schema": {
       "type": "string",
       "nullable": true
      }
     },
     {
      "name": "top_k",
      "in": "query",
      "description": "Maximum number of thoughts to return",
      "required": false,
      "schema": {
       "type": "integer",
       "nullable": true,
       "minimum": 0
      }
     },
     {
      "name": "min_score",
      "in": "query",
      "description": "Optional minimum score threshold",
      "required": false,
      "schema": {
       "type": "number",
       "format": "float",
       "nullable": true
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Thoughts",
      "content": {
       "application/json": {
        "schema": {
         "type": "array",
         "items": {
          "$ref": "#/components/schemas/ThoughtResponse"
         }
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "503": {
      "description": "GoT not enabled"
     }
    }
   },
   "post": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "Add a thought to the reasoning graph",
    "description": "**Required scope:** `write`",
    "operationId": "add_thought_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/AddThoughtRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Thought added",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ThoughtResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "503": {
      "description": "GoT not enabled"
     }
    }
   }
  },
  "/api/v1/nsr/infer": {
   "post": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "Perform inference using the NSR Machine",
    "description": "Processes input sequences through the neural-symbolic reasoning pipeline,\ncombining perception, parsing, and semantic computation to produce outputs.\n\n## Input Types\n- `text`: Natural language or symbolic commands (e.g., \"walk twice\")\n- `number`: Numeric values for mathematical operations\n- `embedding`: Pre-computed vector embeddings\n- `image`: Raw pixel data for visual inputs\n- `composite`: Numeric grounded symbol vectors such as emulator UI-node fields\n\n## Example\n```bash\ncurl -X POST \"https://api.nsr.stateset.com/api/v1/nsr/infer\" \\\n-H \"X-API-Key: your-api-key\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\"inputs\": [{\"type\": \"text\", \"value\": \"walk twice\"}]}'\n```\nPerform inference with the NSR Machine.\n\n**Required scope:** `write`",
    "operationId": "nsr_infer_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "description": "Inference request with input sequence",
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/NSRInferRequest"
       },
       "example": {
        "inputs": [
         {
          "type": "text",
          "value": "walk twice"
         }
        ],
        "session_id": null
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Inference successful",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/NSRInferResponse"
        },
        "example": {
         "confidence": 0.95,
         "output": {
          "type": "list",
          "value": [
           {
            "type": "string",
            "value": "WALK"
           },
           {
            "type": "string",
            "value": "WALK"
           }
          ]
         },
         "processing_time_ms": 12,
         "symbol_distributions": null,
         "symbols": [
          1,
          3,
          1
         ]
        }
       }
      }
     },
     "400": {
      "description": "Invalid request - empty inputs or validation failed",
      "content": {
       "text/plain": {
        "schema": {
         "type": "string"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "500": {
      "description": "Internal server error - inference engine failure"
     },
     "504": {
      "description": "Reasoning budget exhausted before completion"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/nsr/infer/ensemble": {
   "post": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "Perform ensemble inference with input dropout for confidence calibration",
    "description": "**Required scope:** `write`",
    "operationId": "nsr_infer_ensemble_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/NSREnsembleInferRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Ensemble inference successful",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/NSREnsembleInferResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "500": {
      "description": "Internal server error"
     },
     "504": {
      "description": "Reasoning budget exhausted before completion"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/nsr/programs": {
   "post": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "Set a program for a symbol",
    "description": "**Required scope:** `write`",
    "operationId": "set_program_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/SetProgramRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Program set",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ProgramResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/nsr/programs/evaluate": {
   "post": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "Evaluate a program with optional arguments",
    "description": "**Required scope:** `write`",
    "operationId": "nsr_program_evaluate_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ProgramEvaluateRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Program evaluated",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ProgramEvaluateResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/nsr/programs/{symbol_id}": {
   "get": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "Get the program for a symbol",
    "description": "**Required scope:** `read`",
    "operationId": "get_program_handler",
    "parameters": [
     {
      "name": "symbol_id",
      "in": "path",
      "description": "Symbol ID",
      "required": true,
      "schema": {
       "type": "integer",
       "format": "int64",
       "minimum": 0
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Program found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ProgramResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Program not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/nsr/recommend-strategy": {
   "post": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "Get strategy recommendation for a task",
    "description": "**Required scope:** `write`",
    "operationId": "recommend_strategy_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/TaskCharacteristicsRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Strategy recommendation",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/StrategyRecommendationResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "503": {
      "description": "Metacognition not enabled"
     }
    }
   }
  },
  "/api/v1/nsr/stats": {
   "get": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "Get NSR Machine statistics",
    "description": "Returns comprehensive statistics about the NSR Machine, including training\nmetrics, vocabulary size, enabled features, and configuration summary.\n\n## Example\n```bash\ncurl -X GET \"https://api.nsr.stateset.com/api/v1/nsr/stats\" \\\n-H \"X-API-Key: your-api-key\"\n```\n\n**Required scope:** `read`",
    "operationId": "nsr_stats_handler",
    "responses": {
     "200": {
      "description": "NSR Machine statistics",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/NSRStatsResponse"
        },
        "example": {
         "config": {
          "embedding_dim": 256,
          "hidden_size": 512,
          "max_program_depth": 10,
          "max_seq_len": 128,
          "synthesis_enabled": true
         },
         "enabled_features": [
          "library_learning",
          "metacognition",
          "vsa"
         ],
         "programs_learned": 42,
         "successful_inferences": 5432,
         "training_examples": 1000,
         "vocabulary_size": 128
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/nsr/symbols": {
   "get": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "List all symbols in the vocabulary",
    "description": "Returns all symbols currently in the NSR Machine's vocabulary, including\ntheir IDs, names, and whether they have associated programs.\n\n## Example\n```bash\ncurl -X GET \"https://api.nsr.stateset.com/api/v1/nsr/symbols\" \\\n-H \"X-API-Key: your-api-key\"\n```\n\n**Required scope:** `read`",
    "operationId": "list_symbols_handler",
    "responses": {
     "200": {
      "description": "List of all symbols in vocabulary",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ListSymbolsResponse"
        },
        "example": {
         "symbols": [
          {
           "has_program": true,
           "id": 0,
           "name": "has_fur"
          },
          {
           "has_program": true,
           "id": 1,
           "name": "makes_bark"
          },
          {
           "has_program": true,
           "id": 2,
           "name": "dog"
          }
         ],
         "total": 3
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   },
   "post": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "Add a symbol to the NSR Machine vocabulary",
    "description": "Creates a new symbol in the system's vocabulary. Symbols are the atomic units\nof meaning that the NSR system operates on. Each symbol can optionally have\nan associated program that defines its semantic interpretation.\n\n## Example\n```bash\ncurl -X POST \"https://api.nsr.stateset.com/api/v1/nsr/symbols\" \\\n-H \"X-API-Key: your-api-key\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\"name\": \"WALK\", \"program\": {\"type\": \"primitive\", \"name\": \"identity\"}}'\n```\n\n**Required scope:** `write`",
    "operationId": "add_symbol_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "description": "Symbol to add to the vocabulary",
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/AddSymbolRequest"
       },
       "example": {
        "name": "WALK",
        "program": {
         "name": "identity",
         "type": "primitive"
        }
       }
      }
     },
     "required": true
    },
    "responses": {
     "201": {
      "description": "Symbol added successfully",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SymbolResponse"
        },
        "example": {
         "has_program": true,
         "id": 42,
         "name": "WALK"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request - empty name or name too long",
      "content": {
       "text/plain": {
        "schema": {
         "type": "string"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/nsr/symbols/batch": {
   "post": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "Add multiple symbols at once",
    "description": "Efficiently add multiple symbols to the vocabulary in a single request.\nThis is more efficient than making individual requests for each symbol.\n\n## Example\n```bash\ncurl -X POST \"https://api.nsr.stateset.com/api/v1/nsr/symbols/batch\" \\\n-H \"X-API-Key: your-api-key\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\"names\": [\"WALK\", \"RUN\", \"JUMP\", \"TURN_LEFT\", \"TURN_RIGHT\"]}'\n```\n\n**Required scope:** `write`",
    "operationId": "add_symbols_batch_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "description": "List of symbol names to add",
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/AddSymbolsRequest"
       },
       "example": {
        "names": [
         "WALK",
         "RUN",
         "JUMP",
         "TURN_LEFT",
         "TURN_RIGHT"
        ]
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Symbols added successfully",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ListSymbolsResponse"
        },
        "example": {
         "symbols": [
          {
           "has_program": false,
           "id": 10,
           "name": "WALK"
          },
          {
           "has_program": false,
           "id": 11,
           "name": "RUN"
          },
          {
           "has_program": false,
           "id": 12,
           "name": "JUMP"
          }
         ],
         "total": 3
        }
       }
      }
     },
     "400": {
      "description": "Invalid request - empty list or too many symbols",
      "content": {
       "text/plain": {
        "schema": {
         "type": "string"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/nsr/train": {
   "post": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "Train the NSR Machine on examples",
    "description": "Trains the neural-symbolic system using input-output pairs. The system learns\nto map inputs to outputs through both neural perception and symbolic program synthesis.\n\n## Training Process\n1. Neural perception maps inputs to symbol distributions\n2. Parser constructs syntactic structures\n3. Abductive reasoning synthesizes programs that explain the examples\n4. Library learning extracts reusable program components\n\n## Example\n```bash\ncurl -X POST \"https://api.nsr.stateset.com/api/v1/nsr/train\" \\\n-H \"X-API-Key: your-api-key\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\n\"examples\": [\n{\"inputs\": [{\"type\": \"text\", \"value\": \"walk\"}], \"output\": {\"type\": \"list\", \"value\": [{\"type\": \"string\", \"value\": \"WALK\"}]}},\n{\"inputs\": [{\"type\": \"text\", \"value\": \"run\"}], \"output\": {\"type\": \"list\", \"value\": [{\"type\": \"string\", \"value\": \"RUN\"}]}}\n],\n\"epochs\": 5\n}'\n```\n\n**Required scope:** `models:manage`",
    "operationId": "nsr_train_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "description": "Training request with input-output examples",
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/NSRTrainRequest"
       },
       "example": {
        "epochs": 5,
        "examples": [
         {
          "inputs": [
           {
            "type": "text",
            "value": "walk"
           }
          ],
          "output": {
           "type": "list",
           "value": [
            {
             "type": "string",
             "value": "WALK"
            }
           ]
          }
         },
         {
          "inputs": [
           {
            "type": "text",
            "value": "run"
           }
          ],
          "output": {
           "type": "list",
           "value": [
            {
             "type": "string",
             "value": "RUN"
            }
           ]
          }
         }
        ]
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Training completed successfully",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/NSRTrainResponse"
        },
        "example": {
         "final_loss": 0.023,
         "programs_learned": 3,
         "successful_abductions": 8,
         "total_examples": 10,
         "training_time_ms": 1250
        }
       }
      }
     },
     "400": {
      "description": "Invalid request - empty examples or validation failed",
      "content": {
       "text/plain": {
        "schema": {
         "type": "string"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "500": {
      "description": "Internal server error - training failed"
     },
     "504": {
      "description": "Training budget exhausted before completion"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/nsr/uncertainty": {
   "get": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "Get uncertainty estimation",
    "description": "**Required scope:** `read`",
    "operationId": "uncertainty_handler",
    "responses": {
     "200": {
      "description": "Uncertainty estimate",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/UncertaintyResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/nsr/validate": {
   "post": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "Validate a response using NSR-L rules + text signals.",
    "description": "**Required scope:** `write`",
    "operationId": "nsr_validate_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/NSRValidateRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Validation result",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/NSRValidateResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/nsr/validate/batch": {
   "post": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "Batch validate responses using NSR-L rules + text signals.",
    "description": "**Required scope:** `write`",
    "operationId": "nsr_validate_batch_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/NSRValidateBatchRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Batch validation result",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/NSRValidateBatchResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/nsr/validation/cases": {
   "get": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "List persisted validation cases.",
    "description": "**Required scope:** `read`",
    "operationId": "nsr_validation_cases_handler",
    "responses": {
     "200": {
      "description": "Validation cases",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/NSRValidationCasesResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   },
   "post": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "Create a single validation case.",
    "description": "**Required scope:** `write`",
    "operationId": "nsr_validation_case_create_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/NSRValidationCaseInput"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Created case",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/NSRValidationCase"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/nsr/validation/cases/batch": {
   "post": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "Create multiple validation cases in one request.",
    "description": "**Required scope:** `write`",
    "operationId": "nsr_validation_cases_batch_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/NSRValidationCasesBatchRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Batch create result",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/NSRValidationCasesBatchResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/nsr/validation/cases/{id}/replay": {
   "post": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "Replay a stored validation case and persist the run.",
    "description": "**Required scope:** `write`",
    "operationId": "nsr_validation_case_replay_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/NSRValidationReplayRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Validation result",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/NSRValidateResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/nsr/validation/runs": {
   "get": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "List validation runs for the current org.",
    "description": "**Required scope:** `read`",
    "operationId": "nsr_validation_runs_handler",
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "description": "Max runs to return (default 50)",
      "required": false,
      "schema": {
       "type": "integer",
       "nullable": true,
       "minimum": 0
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Validation runs",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/NSRValidationRunsResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/nsr/vsa": {
   "get": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "Get VSA status",
    "description": "**Required scope:** `read`",
    "operationId": "vsa_status_handler",
    "responses": {
     "200": {
      "description": "VSA status",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/VSAResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/nsr/vsa/bind": {
   "post": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "Bind two VSA vectors (role-filler composition)",
    "description": "**Required scope:** `write`",
    "operationId": "vsa_bind_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/VSABindRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Bound successfully",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/VSAResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Concept not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "503": {
      "description": "VSA not enabled"
     }
    }
   }
  },
  "/api/v1/nsr/vsa/bundle": {
   "post": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "Bundle multiple VSA vectors (superposition/set union)",
    "description": "**Required scope:** `write`",
    "operationId": "vsa_bundle_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/VSABundleRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Bundled successfully",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/VSAResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Concept not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "503": {
      "description": "VSA not enabled"
     }
    }
   }
  },
  "/api/v1/nsr/vsa/classify": {
   "post": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "Classify input features using VSA similarity against feature-based class prototypes",
    "description": "**Required scope:** `write`",
    "operationId": "vsa_classify_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/VSAClassifyRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Classification result",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/VSAClassifyResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "503": {
      "description": "VSA not enabled"
     }
    }
   }
  },
  "/api/v1/nsr/vsa/encode": {
   "post": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "Encode a symbol or add a concept to VSA",
    "description": "**Required scope:** `write`",
    "operationId": "vsa_encode_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/VSAEncodeRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Encoded successfully",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/VSAResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "503": {
      "description": "VSA not enabled"
     }
    }
   }
  },
  "/api/v1/nsr/vsa/query": {
   "post": {
    "tags": [
     "NSR Machine"
    ],
    "summary": "Query VSA cleanup memory",
    "description": "**Required scope:** `write`",
    "operationId": "vsa_query_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/VSAQueryRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Query results",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/VSAResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "503": {
      "description": "VSA not enabled"
     }
    }
   }
  },
  "/api/v1/nsrl/assert": {
   "post": {
    "tags": [
     "NSR-L"
    ],
    "summary": "Assert facts and rules from NSR-L code",
    "description": "**Required scope:** `write`",
    "operationId": "nsrl_assert_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/NSRLAssertRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Assertion result",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/NSRLAssertResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/nsrl/execute": {
   "post": {
    "tags": [
     "NSR-L"
    ],
    "summary": "Execute NSR-L code (facts, rules, queries)",
    "description": "**Required scope:** `write`",
    "operationId": "nsrl_execute_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/NSRLExecuteRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Execution result",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/NSRLExecuteResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/nsrl/parse": {
   "post": {
    "tags": [
     "NSR-L"
    ],
    "summary": "Parse NSR-L code without executing",
    "description": "**Required scope:** `write`",
    "operationId": "nsrl_parse_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/NSRLParseRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Parse result",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/NSRLParseResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/nsrl/program": {
   "get": {
    "tags": [
     "NSR-L"
    ],
    "summary": "Fetch the persisted NSR-L program for the current org.",
    "description": "**Required scope:** `read`",
    "operationId": "nsrl_program_handler",
    "responses": {
     "200": {
      "description": "NSR-L program",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/NSRLProgramResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   },
   "put": {
    "tags": [
     "NSR-L"
    ],
    "summary": "Replace the current NSR-L program (creates a new version).",
    "description": "**Required scope:** `write`",
    "operationId": "nsrl_program_update_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/NSRLProgramUpdateRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Program update result",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/NSRLProgramUpdateResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/nsrl/prove": {
   "post": {
    "tags": [
     "NSR-L"
    ],
    "summary": "Prove a query using classical resolution theorem proving over the current NSR-L program.",
    "description": "**Required scope:** `write`",
    "operationId": "nsrl_prove_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/NSRLProveRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Proof result",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/NSRLProveResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/nsrl/versions": {
   "get": {
    "tags": [
     "NSR-L"
    ],
    "summary": "List program versions for the current org.",
    "description": "**Required scope:** `read`",
    "operationId": "nsrl_program_versions_handler",
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "description": "Max versions to return (default 50)",
      "required": false,
      "schema": {
       "type": "integer",
       "nullable": true,
       "minimum": 0
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Program versions",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/NSRLProgramVersionsResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/nsrl/versions/{id}": {
   "get": {
    "tags": [
     "NSR-L"
    ],
    "summary": "Fetch a specific program version.",
    "description": "**Required scope:** `read`",
    "operationId": "nsrl_program_version_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Program version",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/NSRLProgramVersionResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/nsrl/versions/{id}/rollback": {
   "post": {
    "tags": [
     "NSR-L"
    ],
    "summary": "Roll back to a previous program version.",
    "description": "**Required scope:** `write`",
    "operationId": "nsrl_program_rollback_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Rollback result",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/NSRLProgramUpdateResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/policy/evaluate": {
   "post": {
    "tags": [
     "NSR Machine"
    ],
    "description": "**Required scope:** `write`",
    "operationId": "policyEvaluate",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/PolicyEvaluateRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Policy evaluation result for an inquiry/response pair",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PolicyEvaluateResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "500": {
      "description": "Internal server error"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/policy/infer": {
   "post": {
    "tags": [
     "NSR Machine"
    ],
    "description": "**Required scope:** `write`",
    "operationId": "policyInfer",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/PolicyInferRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Policy inference result",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PolicyInferResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "500": {
      "description": "Internal server error"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/policy/sandbox/evaluate": {
   "post": {
    "tags": [
     "NSR Machine"
    ],
    "description": "**Required scope:** `write`",
    "operationId": "sandboxPolicyEvaluate",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/SandboxPolicyRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Sandbox policy evaluation result",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SandboxPolicyApiResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "500": {
      "description": "Internal server error"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/policy/train": {
   "post": {
    "tags": [
     "NSR Machine"
    ],
    "description": "**Required scope:** `models:manage`",
    "operationId": "policyTrain",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/PolicyTrainRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Policy training result",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PolicyTrainResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "500": {
      "description": "Internal server error"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/policy/vocab/init": {
   "post": {
    "tags": [
     "NSR Machine"
    ],
    "description": "**Required scope:** `write`",
    "operationId": "policyVocabInit",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/PolicyVocabInitRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Policy vocabulary initialized",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PolicyVocabResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "500": {
      "description": "Internal server error"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/query": {
   "post": {
    "tags": [
     "Knowledge Base"
    ],
    "summary": "Execute a knowledge base query",
    "description": "Execute a structured pattern query over the KB.\n\n**Required scope:** `write`",
    "operationId": "query_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/QueryRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Query executed",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/QueryResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid query"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/rag/query": {
   "post": {
    "tags": [
     "Reasoning"
    ],
    "summary": "Handler for POST /api/v1/rag/query",
    "description": "**Required scope:** `write`",
    "operationId": "rag_query_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "description": "RAG query request",
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/RAGQueryRequest"
       },
       "example": {
        "include_sources": true,
        "query": "Summarize facts about France",
        "verify": true
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "RAG response",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/RAGQueryResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request (empty query or bad parameters)"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "422": {
      "description": "Query too long"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "503": {
      "description": "RAG unavailable (LLM not configured)"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/reason": {
   "get": {
    "tags": [
     "Reasoning"
    ],
    "description": "**Required scope:** `read`",
    "operationId": "reason_at_time_handler",
    "parameters": [
     {
      "name": "query",
      "in": "query",
      "description": "Query string to evaluate",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "as_of_timestamp",
      "in": "query",
      "description": "RFC3339 timestamp for historical snapshot",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "strategy",
      "in": "query",
      "description": "Optional strategy override",
      "required": false,
      "schema": {
       "type": "string",
       "nullable": true
      }
     },
     {
      "name": "session_id",
      "in": "query",
      "description": "Optional session ID",
      "required": false,
      "schema": {
       "type": "string",
       "nullable": true
      }
     },
     {
      "name": "max_depth",
      "in": "query",
      "description": "Optional max depth override",
      "required": false,
      "schema": {
       "type": "integer",
       "nullable": true,
       "minimum": 0
      }
     },
     {
      "name": "confidence_threshold",
      "in": "query",
      "description": "Optional confidence threshold override",
      "required": false,
      "schema": {
       "type": "number",
       "format": "float",
       "nullable": true
      }
     },
     {
      "name": "include_explanation",
      "in": "query",
      "description": "Whether to include explanation in response",
      "required": false,
      "schema": {
       "type": "boolean",
       "nullable": true
      }
     },
     {
      "name": "neural_weight",
      "in": "query",
      "description": "Neural weight for hybrid reasoning",
      "required": false,
      "schema": {
       "type": "number",
       "format": "float",
       "nullable": true
      }
     },
     {
      "name": "include_evidence",
      "in": "query",
      "description": "Whether to include evidence in response",
      "required": false,
      "schema": {
       "type": "boolean",
       "nullable": true
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Reasoning completed successfully",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ReasonResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid query parameters"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Session not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "500": {
      "description": "Reasoning engine failure"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   },
   "post": {
    "tags": [
     "Reasoning"
    ],
    "summary": "Execute a reasoning query using the NSR engine.",
    "description": "This is the primary endpoint for performing neural-symbolic reasoning.\nIt accepts a query string and optional parameters to control the reasoning\nprocess, including strategy selection and configuration overrides.\n\n# Request Body\n- `query`: The question or goal to reason about\n- `strategy`: Optional reasoning strategy (SymbolicFirst, NeuralFirst, Hybrid, Ensemble, Cascading)\n- `session_id`: Optional session ID for context continuity\n- `options`: Optional configuration overrides (max_depth, confidence_threshold, neural_weight)\n\n# Response\nReturns a `ReasonResponse` containing:\n- `answer`: The reasoning result\n- `confidence`: Confidence score (0.0-1.0)\n- `explanation`: Human-readable explanation of the reasoning path\n- `session_id`: Session ID for follow-up queries\n\n# Errors\n- `400 Bad Request`: Invalid input (empty query, exceeds max length)\n- `500 Internal Server Error`: Reasoning engine failure\n\n# Example\n## Example (curl)\n```bash\ncurl -X POST \"https://api.nsr.stateset.com/api/v1/reason\" \\\n-H \"X-API-Key: your-api-key\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\"query\": \"What are the properties of entity X?\", \"strategy\": \"hybrid\"}'\n```\nExecute a reasoning query.\n\n**Required scope:** `write`",
    "operationId": "reason_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "description": "Reasoning query with optional strategy and configuration",
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ReasonRequest"
       },
       "example": {
        "options": {
         "confidence_threshold": 0.7,
         "include_explanation": true,
         "max_depth": 5
        },
        "query": "What is the relationship between Alice and Bob?",
        "session_id": null,
        "strategy": "hybrid"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Reasoning completed successfully",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ReasonResponse"
        },
        "example": {
         "answer": "Alice is a friend of Bob",
         "confidence": 0.92,
         "explanation": {
          "confidence_factors": [],
          "steps": [
           "Found triple: Alice -> friend_of -> Bob"
          ]
         },
         "metadata": {
          "facts_used": 3,
          "query_time_ms": 45,
          "rules_fired": 1
         },
         "reasoning_type": "hybrid_weighted",
         "session_id": "sess_abc123"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request - empty query or exceeds max length",
      "content": {
       "text/plain": {
        "schema": {
         "type": "string"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "500": {
      "description": "Reasoning engine failure",
      "content": {
       "text/plain": {
        "schema": {
         "type": "string"
        }
       }
      }
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/reason/induce-rules": {
   "post": {
    "tags": [
     "Reasoning"
    ],
    "summary": "Induce candidate rules from labeled examples.",
    "description": "A safe, on-demand generalizer: the caller supplies `{features, label}`\nexamples and gets back candidate `head :- body` rules (association-rule\nmining, minimal antecedents, support/confidence gated). It returns\n*suggestions only* \u2014 nothing is written to the knowledge base. Review the\noutput and add rules you trust via `POST /api/v1/rules`.\n\n**Required scope:** `write`",
    "operationId": "induce_rules_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/InduceRulesRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Candidate rules with support/confidence",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/InduceRulesResponse"
        }
       }
      }
     },
     "400": {
      "description": "No examples provided"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "422": {
      "description": "Too many examples"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/reason/strategy-stats": {
   "get": {
    "tags": [
     "Reasoning"
    ],
    "description": "**Required scope:** `read`",
    "operationId": "strategy_stats_handler",
    "responses": {
     "200": {
      "description": "Learned per-query-class strategy performance",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/StrategyStatsResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/reason/stream": {
   "get": {
    "tags": [
     "Reasoning"
    ],
    "summary": "Handler for GET /api/v1/reason/stream?query=...&strategy=...",
    "description": "Uses a per-request channel so each client receives only its own reasoning trace.\n\n**Required scope:** `read`",
    "operationId": "reason_stream_get_handler",
    "parameters": [
     {
      "name": "query",
      "in": "query",
      "description": "Reasoning query",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "strategy",
      "in": "query",
      "description": "Optional strategy override",
      "required": false,
      "schema": {
       "type": "string",
       "nullable": true
      }
     },
     {
      "name": "as_of_timestamp",
      "in": "query",
      "description": "Optional RFC3339 historical snapshot timestamp",
      "required": false,
      "schema": {
       "type": "string",
       "nullable": true
      }
     }
    ],
    "responses": {
     "200": {
      "description": "SSE stream started"
     },
     "400": {
      "description": "Invalid query or timestamp"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   },
   "post": {
    "tags": [
     "Reasoning"
    ],
    "summary": "Handler for POST /api/v1/reason/stream",
    "description": "Accepts a reasoning query and returns an SSE stream of reasoning events.\n\n**Required scope:** `write`",
    "operationId": "reason_stream_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "description": "Streaming reasoning request",
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/StreamReasonRequest"
       },
       "example": {
        "query": "What is the capital of France?",
        "strategy": "auto"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "SSE stream started"
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/replies": {
   "post": {
    "tags": [
     "Replies"
    ],
    "summary": "Decide, then draft \u2014 one call.",
    "description": "**Required scope:** `write`",
    "operationId": "reply_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ReplyRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Decision plus the macro and tool call it selects",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ReplyResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "402": {
      "description": "Quota exhausted"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "422": {
      "description": "Malformed decision request"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/rules": {
   "get": {
    "tags": [
     "Rules"
    ],
    "summary": "List all rules",
    "description": "List rules with pagination.\n\n**Required scope:** `read`",
    "operationId": "list_rules_handler",
    "parameters": [
     {
      "name": "limit",
      "in": "path",
      "description": "Maximum number of items to return (1-1000, default: 50)",
      "required": true,
      "schema": {
       "type": "integer",
       "default": 50,
       "nullable": true,
       "maximum": 1000,
       "minimum": 1
      }
     },
     {
      "name": "offset",
      "in": "path",
      "description": "Number of items to skip (default: 0)",
      "required": true,
      "schema": {
       "type": "integer",
       "default": 0,
       "nullable": true,
       "minimum": 0
      }
     },
     {
      "name": "cursor",
      "in": "path",
      "description": "Cursor for cursor-based pagination (alternative to offset)",
      "required": true,
      "schema": {
       "type": "string",
       "nullable": true
      }
     },
     {
      "name": "sort",
      "in": "path",
      "description": "Sort field with optional direction prefix (- for descending)\nExamples: \"created_at\", \"-name\", \"confidence\"",
      "required": true,
      "schema": {
       "type": "string",
       "nullable": true
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Paginated list of the org's rules",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PaginatedRuleListResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   },
   "post": {
    "tags": [
     "Rules"
    ],
    "summary": "Create (or upsert) an organization policy rule.",
    "description": "POSTing a name that already exists atomically REPLACES that rule \u2014 this is\nhow a policy pack is re-uploaded without stacking duplicates. Lint errors\n(e.g. RULE007 unbound head variable) reject the write with 400; soft\n`lint_warnings` are returned alongside a successful create.\n\n**Required scope:** `write`",
    "operationId": "create_rule_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CreateRuleRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "201": {
      "description": "Rule created or replaced; body carries id and any lint_warnings"
     },
     "400": {
      "description": "Lint error \u2014 the rule was not installed"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "402": {
      "description": "Tenant rule quota exhausted"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/rules/batch": {
   "post": {
    "tags": [
     "Rules"
    ],
    "summary": "Batch create rules",
    "description": "Creates multiple rules in a single request. Each rule that passes validation\nis created independently -- failures don't roll back successful creations.\nBatch create rules.\n\n**Required scope:** `write`",
    "operationId": "batch_create_rules_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/BatchCreateRulesRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Batch operation completed",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/BatchCreateRulesResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/rules/batch-delete": {
   "post": {
    "tags": [
     "Rules"
    ],
    "summary": "Batch delete rules",
    "description": "Deletes multiple rules by ID. Returns count of successfully deleted rules.\nBatch delete rules.\n\n**Required scope:** `write`",
    "operationId": "batch_delete_rules_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/BatchDeleteRulesRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Batch deletion completed",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/BatchDeleteResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/rules/lint": {
   "post": {
    "tags": [
     "Rules"
    ],
    "summary": "Dry-run lint check for a proposed rule without inserting it.",
    "description": "**Required scope:** `write`",
    "operationId": "lint_rule_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CreateRuleRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Lint diagnostics: {diagnostics: [...], has_errors: bool}; the rule is NOT installed"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/rules/{id}": {
   "get": {
    "tags": [
     "Rules"
    ],
    "summary": "Get a single rule by ID",
    "description": "Retrieve a single rule by id.\n\n**Required scope:** `read`",
    "operationId": "get_rule_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "Rule ID",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Rule details",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/RuleResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Rule not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   },
   "delete": {
    "tags": [
     "Rules"
    ],
    "summary": "Delete a rule by ID",
    "description": "Hard-delete a rule.\n\n**Required scope:** `admin`",
    "operationId": "delete_rule_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "Rule id",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Rule deleted"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "No such rule in this organization"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   },
   "patch": {
    "tags": [
     "Rules"
    ],
    "summary": "Update a rule by ID",
    "description": "Update an existing rule.\n\n**Required scope:** `write`",
    "operationId": "update_rule_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "Rule ID",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/UpdateRuleRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Rule updated",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/RuleResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Rule not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/rules/{id}/soft": {
   "delete": {
    "tags": [
     "Rules"
    ],
    "summary": "Soft delete a rule (archives for audit trail)",
    "description": "Soft-delete (tombstone) a rule.\n\n**Required scope:** `admin`",
    "operationId": "soft_delete_rule_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "Rule ID",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/SoftDeleteRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Rule soft deleted"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Rule not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/sandbox/create": {
   "post": {
    "tags": [
     "Sandbox"
    ],
    "summary": "Create an ephemeral sandbox pod.",
    "description": "**Required scope:** `sandbox:execute`",
    "operationId": "create_sandbox_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CreateSandboxRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "201": {
      "description": "Sandbox created"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "503": {
      "description": "Sandbox infrastructure unavailable"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/sandbox/execute": {
   "post": {
    "tags": [
     "Sandbox"
    ],
    "summary": "Execute a command in an existing sandbox.",
    "description": "**Required scope:** `sandbox:execute`",
    "operationId": "execute_in_sandbox_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ExecuteRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Command executed"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "503": {
      "description": "Sandbox infrastructure unavailable"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/sandbox/run": {
   "post": {
    "tags": [
     "Sandbox"
    ],
    "summary": "Execute code inline \u2014 creates a sandbox, runs the code, returns output.",
    "description": "This is the simplest way to run untrusted code. The sandbox is ephemeral\nand destroyed after execution.\n\n**Required scope:** `sandbox:execute`",
    "operationId": "run_code_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/RunCodeRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Code executed"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "503": {
      "description": "Sandbox infrastructure unavailable"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/sessions": {
   "post": {
    "tags": [
     "Sessions"
    ],
    "summary": "Create a new session",
    "description": "Create a new reasoning session.\n\n**Required scope:** `write`",
    "operationId": "create_session_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "New reasoning session",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SessionResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/sessions/{session_id}": {
   "get": {
    "tags": [
     "Sessions"
    ],
    "summary": "Get session info",
    "description": "Fetch an existing reasoning session.\n\n**Required scope:** `read`",
    "operationId": "get_session_handler",
    "parameters": [
     {
      "name": "session_id",
      "in": "path",
      "description": "Session id returned by POST /api/v1/sessions",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Session info",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SessionResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Session not found or aged out"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/sessions/{session_id}/context": {
   "patch": {
    "tags": [
     "Sessions"
    ],
    "summary": "Update session context",
    "description": "Update stored session context.\n\n**Required scope:** `write`",
    "operationId": "update_session_context_handler",
    "parameters": [
     {
      "name": "session_id",
      "in": "path",
      "description": "Session ID",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/UpdateSessionContextRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Context updated",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/UpdateSessionContextResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Session not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/sessions/{session_id}/history": {
   "get": {
    "tags": [
     "Sessions"
    ],
    "summary": "Get full session history",
    "description": "Fetch session reasoning history.\n\n**Required scope:** `read`",
    "operationId": "get_session_history_handler",
    "parameters": [
     {
      "name": "session_id",
      "in": "path",
      "description": "Session ID",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Session history",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SessionHistoryResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Session not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/sources": {
   "get": {
    "tags": [
     "Knowledge Base"
    ],
    "summary": "List all registered evidence sources.",
    "description": "**Required scope:** `read`",
    "operationId": "list_sources_handler",
    "responses": {
     "200": {
      "description": "Sources",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SourcesResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   },
   "post": {
    "tags": [
     "Knowledge Base"
    ],
    "summary": "Create a new evidence source record.",
    "description": "**Required scope:** `write`",
    "operationId": "create_source_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "description": "Create source request",
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CreateSourceRequest"
       },
       "example": {
        "locator": "file://tmp/doc.txt",
        "snippet": "important fact",
        "source_type": "document",
        "trust_tag": "internal"
       }
      }
     },
     "required": true
    },
    "responses": {
     "201": {
      "description": "Source created",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/EvidenceSourceRecord"
        }
       }
      }
     },
     "400": {
      "description": "Invalid source payload"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/sources/{id}": {
   "get": {
    "tags": [
     "Knowledge Base"
    ],
    "summary": "Retrieve a single source by ID.",
    "description": "**Required scope:** `read`",
    "operationId": "get_source_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "Source ID",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Source record",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/EvidenceSourceRecord"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Source not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   },
   "delete": {
    "tags": [
     "Knowledge Base"
    ],
    "summary": "Delete a source by ID.",
    "description": "**Required scope:** `admin`",
    "operationId": "delete_source_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "Source ID",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "204": {
      "description": "Source deleted"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Source not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   },
   "patch": {
    "tags": [
     "Knowledge Base"
    ],
    "summary": "Update an existing source.",
    "description": "**Required scope:** `write`",
    "operationId": "update_source_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "Source ID",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "description": "Partial source update",
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/UpdateSourceRequest"
       },
       "example": {
        "locator": "https://example.com/doc",
        "source_type": "url",
        "trust_tag": "verified"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Source updated",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/EvidenceSourceRecord"
        }
       }
      }
     },
     "400": {
      "description": "Invalid update payload"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Source not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/status": {
   "get": {
    "tags": [
     "Platform"
    ],
    "operationId": "status_handler",
    "responses": {
     "200": {
      "description": "Service status, SLA metrics, and dependency health",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/StatusResponse"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/templates": {
   "get": {
    "tags": [
     "Templates"
    ],
    "operationId": "list_templates_handler",
    "responses": {
     "200": {
      "description": "List of available industry templates",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/TemplateListResponse"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/templates/{slug}": {
   "get": {
    "tags": [
     "Templates"
    ],
    "operationId": "get_template_handler",
    "parameters": [
     {
      "name": "slug",
      "in": "path",
      "description": "Template slug",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Full template contents",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Template"
        }
       }
      }
     },
     "404": {
      "description": "Template not found"
     }
    }
   }
  },
  "/api/v1/templates/{slug}/apply": {
   "post": {
    "tags": [
     "Templates"
    ],
    "description": "**Required scope:** `write`",
    "operationId": "apply_template_handler",
    "parameters": [
     {
      "name": "slug",
      "in": "path",
      "description": "Template slug",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "mode",
      "in": "query",
      "description": "additive or replace",
      "required": false,
      "schema": {
       "type": "string",
       "nullable": true
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Template applied; returns per-item counts",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ApplyTemplateResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "402": {
      "description": "Quota exceeded"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Template not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/triples": {
   "post": {
    "tags": [
     "Triples"
    ],
    "summary": "Create a new triple (fact) in the knowledge base.",
    "description": "A triple represents a relationship between two entities in the form:\n(subject, predicate, object) - e.g., (\"Socrates\", \"is_a\", \"Human\")\n\n# Request Body\n- `subject_id`: ID of the subject entity (must exist)\n- `predicate`: Relationship name (e.g., \"is_a\", \"has_property\")\n- `object_id`: ID of the object entity (must exist)\n- `confidence`: Optional confidence score (0.0-1.0, default: 1.0)\n\n# Errors\n- `400 Bad Request`: Invalid input or referenced entities don't exist\nCreate a triple (relation) between entities.\n\n**Required scope:** `write`",
    "operationId": "create_triple_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CreateTripleRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "201": {
      "description": "Triple created successfully",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/TripleResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input or referenced entities don't exist"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "402": {
      "description": "Tenant quota exceeded"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   },
   "delete": {
    "tags": [
     "Triples"
    ],
    "summary": "Delete a triple (fact)",
    "description": "Hard-delete a triple.\n\n**Required scope:** `admin`",
    "operationId": "delete_triple_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/DeleteTripleRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Triple deleted"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "No such triple in this organization"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   },
   "patch": {
    "tags": [
     "Triples"
    ],
    "summary": "Update a triple's confidence",
    "description": "Update a triple's confidence.\n\n**Required scope:** `write`",
    "operationId": "update_triple_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/UpdateTripleRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Triple updated",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/TripleResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Triple not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/triples/batch": {
   "post": {
    "tags": [
     "Triples"
    ],
    "summary": "Batch create triples",
    "description": "Batch create triples.\n\n**Required scope:** `write`",
    "operationId": "batch_create_triples_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/BatchCreateTriplesRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Per-item results; failures reported individually",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/BatchCreateTriplesResponse"
        }
       }
      }
     },
     "400": {
      "description": "Batch exceeds max_batch_size"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/triples/{subject_id}": {
   "get": {
    "tags": [
     "Triples"
    ],
    "summary": "Get all triples where the specified entity is the subject.",
    "description": "# Path Parameters\n- `subject_id`: The entity ID to find triples for\n\n# Response\nReturns a paginated list of all triples where this entity is the subject.\nRetrieve triples matching filters.\n\n**Required scope:** `read`",
    "operationId": "get_triples_handler",
    "parameters": [
     {
      "name": "subject_id",
      "in": "path",
      "description": "Subject entity ID to list triples for",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "path",
      "description": "Maximum number of items to return (1-1000, default: 50)",
      "required": true,
      "schema": {
       "type": "integer",
       "default": 50,
       "nullable": true,
       "maximum": 1000,
       "minimum": 1
      }
     },
     {
      "name": "offset",
      "in": "path",
      "description": "Number of items to skip (default: 0)",
      "required": true,
      "schema": {
       "type": "integer",
       "default": 0,
       "nullable": true,
       "minimum": 0
      }
     },
     {
      "name": "cursor",
      "in": "path",
      "description": "Cursor for cursor-based pagination (alternative to offset)",
      "required": true,
      "schema": {
       "type": "string",
       "nullable": true
      }
     },
     {
      "name": "sort",
      "in": "path",
      "description": "Sort field with optional direction prefix (- for descending)\nExamples: \"created_at\", \"-name\", \"confidence\"",
      "required": true,
      "schema": {
       "type": "string",
       "nullable": true
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Paginated triples with this subject",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PaginatedTripleResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/triples/{triple_id}/evidence": {
   "get": {
    "tags": [
     "Triples"
    ],
    "summary": "Get evidence linked to a triple.",
    "description": "**Required scope:** `read`",
    "operationId": "get_triple_evidence_handler",
    "parameters": [
     {
      "name": "triple_id",
      "in": "path",
      "description": "Triple ID as subject:predicate:object or org:subject:predicate:object",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Triple evidence links",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/TripleEvidenceResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid triple_id"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Triple not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   },
   "post": {
    "tags": [
     "Triples"
    ],
    "summary": "Attach an existing evidence node to a triple.",
    "description": "**Required scope:** `write`",
    "operationId": "attach_triple_evidence_handler",
    "parameters": [
     {
      "name": "triple_id",
      "in": "path",
      "description": "Triple ID as subject:predicate:object or org:subject:predicate:object",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/AttachEvidenceRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Evidence attached to triple",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/TripleEvidenceResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Triple or evidence not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/triples/{triple_id}/evidence/{evidence_id}": {
   "delete": {
    "tags": [
     "Triples"
    ],
    "summary": "Detach an evidence node from a triple.",
    "description": "**Required scope:** `admin`",
    "operationId": "detach_triple_evidence_handler",
    "parameters": [
     {
      "name": "triple_id",
      "in": "path",
      "description": "Triple ID as subject:predicate:object or org:subject:predicate:object",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "evidence_id",
      "in": "path",
      "description": "Evidence node ID",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "204": {
      "description": "Evidence detached"
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Triple or evidence link not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/types": {
   "get": {
    "tags": [
     "Types"
    ],
    "summary": "List available primitive types",
    "description": "**Required scope:** `read`",
    "operationId": "list_types_handler",
    "responses": {
     "200": {
      "description": "List of types",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ListTypesResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/types/constraints-prompt": {
   "get": {
    "tags": [
     "Types"
    ],
    "summary": "Generate type constraints prompt for LLM",
    "description": "**Required scope:** `read`",
    "operationId": "generate_constraints_prompt_handler",
    "responses": {
     "200": {
      "description": "Type constraints prompt",
      "content": {
       "text/plain": {
        "schema": {
         "type": "string"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/types/predicates": {
   "get": {
    "tags": [
     "Types"
    ],
    "summary": "List all registered predicates",
    "description": "**Required scope:** `read`",
    "operationId": "list_predicates_handler",
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "description": "Maximum number of items to return (1-1000, default: 50)",
      "required": false,
      "schema": {
       "type": "integer",
       "default": 50,
       "nullable": true,
       "maximum": 1000,
       "minimum": 1
      }
     },
     {
      "name": "offset",
      "in": "query",
      "description": "Number of items to skip (default: 0)",
      "required": false,
      "schema": {
       "type": "integer",
       "default": 0,
       "nullable": true,
       "minimum": 0
      }
     },
     {
      "name": "cursor",
      "in": "query",
      "description": "Cursor for cursor-based pagination (alternative to offset)",
      "required": false,
      "schema": {
       "type": "string",
       "nullable": true
      }
     },
     {
      "name": "sort",
      "in": "query",
      "description": "Sort field with optional direction prefix (- for descending)\nExamples: \"created_at\", \"-name\", \"confidence\"",
      "required": false,
      "schema": {
       "type": "string",
       "nullable": true
      }
     }
    ],
    "responses": {
     "200": {
      "description": "List of predicates",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ListPredicatesResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   },
   "post": {
    "tags": [
     "Types"
    ],
    "summary": "Register a new predicate signature",
    "description": "**Required scope:** `write`",
    "operationId": "register_predicate_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/RegisterPredicateRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "201": {
      "description": "Predicate registered",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PredicateResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid predicate definition"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "409": {
      "description": "Predicate already exists"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/types/predicates/{name}": {
   "get": {
    "tags": [
     "Types"
    ],
    "summary": "Get a specific predicate signature",
    "description": "**Required scope:** `read`",
    "operationId": "get_predicate_handler",
    "parameters": [
     {
      "name": "name",
      "in": "path",
      "description": "Predicate name",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Predicate details",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PredicateResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Predicate not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   },
   "delete": {
    "tags": [
     "Types"
    ],
    "summary": "Delete a predicate signature",
    "description": "**Required scope:** `admin`",
    "operationId": "delete_predicate_handler",
    "parameters": [
     {
      "name": "name",
      "in": "path",
      "description": "Predicate name",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "204": {
      "description": "Predicate deleted"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Predicate not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/types/subtypes": {
   "post": {
    "tags": [
     "Types"
    ],
    "summary": "Register a subtype relationship",
    "description": "**Required scope:** `write`",
    "operationId": "register_subtype_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/RegisterSubtypeRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "201": {
      "description": "Subtype relationship registered"
     },
     "400": {
      "description": "Invalid subtype definition"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/types/subtypes/{subtype}/{supertype}": {
   "get": {
    "tags": [
     "Types"
    ],
    "summary": "Check if one type is a subtype of another",
    "description": "**Required scope:** `read`",
    "operationId": "check_subtype_handler",
    "parameters": [
     {
      "name": "subtype",
      "in": "path",
      "description": "Subtype name",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "supertype",
      "in": "path",
      "description": "Supertype name",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Subtype check result",
      "content": {
       "text/plain": {
        "schema": {
         "type": "boolean"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/types/validate": {
   "post": {
    "tags": [
     "Types"
    ],
    "summary": "Validate a fact against the type registry",
    "description": "**Required scope:** `write`",
    "operationId": "validate_type_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ValidateTypeRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Validation result",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ValidateTypeResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/api/v1/validate": {
   "post": {
    "tags": [
     "Reasoning"
    ],
    "summary": "Handler for POST /api/v1/validate",
    "description": "Validates a typed query IR without executing reasoning.\n\n**Required scope:** `write`",
    "operationId": "validate_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "description": "Provide exactly one of `query` or `ir`; optional strict mode",
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ValidateRequest"
       },
       "example": {
        "query": "What is the capital of France?",
        "strict": false
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Validation finished",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ValidateResponse"
        },
        "example": {
         "errors": [],
         "ir": {
          "raw_query": "What is the capital of France?"
         },
         "plan": {
          "steps": []
         },
         "valid": true,
         "warnings": []
        }
       }
      }
     },
     "400": {
      "description": "Invalid request payload"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/validate_ir": {
   "post": {
    "tags": [
     "Reasoning"
    ],
    "summary": "Handler for POST /api/v1/validate_ir",
    "description": "Alias for IR validation without execution.\n\n**Required scope:** `write`",
    "operationId": "validate_ir_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "description": "Provide exactly one of `query` or `ir`; optional strict mode",
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ValidateRequest"
       },
       "example": {
        "ir": {
         "raw_query": "What is the capital of France?"
        },
        "strict": false
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Validation finished",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ValidateResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request payload"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/webhooks": {
   "get": {
    "tags": [
     "Webhooks"
    ],
    "description": "**Required scope:** `read`",
    "operationId": "list_webhooks_handler",
    "responses": {
     "200": {
      "description": "List of registered webhook endpoints",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ListWebhooksResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   },
   "post": {
    "tags": [
     "Webhooks"
    ],
    "description": "**Required scope:** `write`",
    "operationId": "create_webhook_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CreateWebhookRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "201": {
      "description": "Endpoint registered; signing secret returned ONCE",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/CreateWebhookResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid URL or events"
     },
     "401": {
      "description": "Unauthorized"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/webhooks/{id}": {
   "get": {
    "tags": [
     "Webhooks"
    ],
    "description": "**Required scope:** `read`",
    "operationId": "get_webhook_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "Webhook endpoint id",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Webhook endpoint summary (secret redacted)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/WebhookSummary"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   },
   "delete": {
    "tags": [
     "Webhooks"
    ],
    "description": "**Required scope:** `admin`",
    "operationId": "delete_webhook_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "Webhook endpoint id",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "204": {
      "description": "Endpoint revoked"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/webhooks/{id}/deliveries": {
   "get": {
    "tags": [
     "Webhooks"
    ],
    "description": "**Required scope:** `read`",
    "operationId": "list_deliveries_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "Webhook endpoint id",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "description": "Max deliveries (default 50, max 100)",
      "required": false,
      "schema": {
       "type": "integer",
       "nullable": true,
       "minimum": 0
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Recent delivery attempts, newest first",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/DeliveryListResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v1/webhooks/{id}/test": {
   "post": {
    "tags": [
     "Webhooks"
    ],
    "description": "**Required scope:** `write`",
    "operationId": "test_webhook_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "Webhook endpoint id",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "202": {
      "description": "Test event dispatched (fire-and-forget)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/TestResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/api/v2/nsr/chat/executions/{receipt_id}": {
   "post": {
    "tags": [
     "Reasoning"
    ],
    "description": "**Required scope:** `sandbox:execute`",
    "operationId": "recursive_chat_execute_actions_handler",
    "parameters": [
     {
      "name": "receipt_id",
      "in": "path",
      "description": "Execution receipt issued by the recursive chat solve endpoint",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ChatActionExecutionRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Executed selected recursive chat actions",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/RecursiveChatResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Receipt does not match authenticated org scope"
     },
     "404": {
      "description": "Receipt not found or expired"
     },
     "422": {
      "description": "Requested actions are not executable for this receipt"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     },
     {
      "org_header": []
     }
    ]
   }
  },
  "/api/v2/nsr/chat/solve": {
   "post": {
    "tags": [
     "Reasoning"
    ],
    "description": "**Required scope:** `write`",
    "operationId": "recursive_chat_solve_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/RecursiveChatRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Recursive-first chat inference result with proof, uncertainty, and trace",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/RecursiveChatResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "402": {
      "description": "Tenant is suspended"
     },
     "403": {
      "description": "Org mismatch with authenticated scope"
     },
     "404": {
      "description": "Session not found"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     },
     {
      "org_header": []
     }
    ]
   }
  },
  "/api/v2/nsr/chat/solve/stream": {
   "post": {
    "tags": [
     "Reasoning"
    ],
    "description": "**Required scope:** `write`",
    "operationId": "recursive_chat_solve_stream_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/RecursiveChatRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Server-Sent Events stream of recursive chat progress + final response"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "402": {
      "description": "Account suspended or quota exhausted"
     },
     "403": {
      "description": "org_id mismatch"
     },
     "408": {
      "description": "Solve exceeded wall-clock budget"
     },
     "422": {
      "description": "Malformed input"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     },
     {
      "org_header": []
     }
    ]
   }
  },
  "/health": {
   "get": {
    "tags": [
     "Health"
    ],
    "summary": "Health check endpoint",
    "description": "Returns the health status of the NSR service, including version information,\nuptime, and knowledge base statistics. This endpoint does not require authentication.\n\n## Example\n```bash\ncurl -X GET \"https://api.nsr.stateset.com/health\"\n```\nHealth check endpoint.",
    "operationId": "health_handler",
    "responses": {
     "200": {
      "description": "Service is healthy",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/HealthResponse"
        },
        "example": {
         "knowledge_base": {
          "entity_count": 1000,
          "rule_count": 50,
          "triple_count": 5000
         },
         "status": "healthy",
         "uptime_seconds": 86400,
         "version": "0.4.0"
        }
       }
      }
     }
    }
   }
  },
  "/ready": {
   "get": {
    "tags": [
     "Health"
    ],
    "summary": "Readiness probe for Kubernetes and orchestration systems",
    "description": "Returns 200 when the service is fully configured and ready to handle traffic.\nReturns 503 with a list of issues when the service is degraded or not ready.\n\n## Checks Performed\n- API keys are configured (production safety)\n- Persistence is configured (data safety)\n- Database is reachable when `NSR_DATABASE_URL` is configured\n- Engine is initialized and operational\n\n## Example\n```bash\ncurl -X GET \"https://api.nsr.stateset.com/ready\"\n```",
    "operationId": "readiness_handler",
    "responses": {
     "200": {
      "description": "Service is ready to receive traffic",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ReadyResponse"
        },
        "example": {
         "issues": [],
         "ready": true,
         "status": "ready",
         "version": "0.4.0"
        }
       }
      }
     },
     "503": {
      "description": "Service is not ready",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ReadyResponse"
        },
        "example": {
         "issues": [
          "API keys not configured; set NSR_API_KEYS or NSR_DEFAULT_API_KEY for production."
         ],
         "ready": false,
         "status": "degraded",
         "version": "0.4.0"
        }
       }
      }
     }
    }
   }
  },
  "/v1/chat/completions": {
   "post": {
    "tags": [
     "Provider Compatibility"
    ],
    "summary": "OpenAI-compatible chat completions endpoint backed by the recursive v2",
    "description": "solver.\n\n**Required scope:** `write`",
    "operationId": "nsr_completions_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {}
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "OpenAI-compatible chat completion",
      "content": {
       "application/json": {
        "schema": {}
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/v1/decisions": {
   "post": {
    "tags": [
     "Verified Decisions"
    ],
    "summary": "Produce an auditable, policy-grounded decision with a proof chain.",
    "description": "**Required scope:** `write`",
    "operationId": "decision_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Optional idempotency key (Stripe-style). Retries with the same key within the retention window replay the stored response instead of re-deciding and re-billing.",
      "required": false,
      "schema": {
       "type": "string",
       "nullable": true
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/DecisionRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Verified decision with proof",
      "headers": {
       "idempotent-replayed": {
        "schema": {
         "type": "string"
        },
        "description": "true when this response was replayed from a stored idempotent result; false on first execution (present when Idempotency-Key was sent)"
       },
       "x-nsr-billing-tier": {
        "schema": {
         "type": "string"
        },
        "description": "The org's billing tier applied to this decision"
       },
       "x-nsr-decision": {
        "schema": {
         "type": "string"
        },
        "description": "Outcome label: approved | denied | refused"
       },
       "x-nsr-outcome-billable": {
        "schema": {
         "type": "string"
        },
        "description": "Whether this outcome was billable (true/false)"
       },
       "x-nsr-outcome-cost-micros": {
        "schema": {
         "type": "string"
        },
        "description": "Cost of this outcome in microdollars"
       },
       "x-nsr-outcome-limit": {
        "schema": {
         "type": "string"
        },
        "description": "Included outcomes in the current period (present when a quota applies)"
       },
       "x-nsr-outcome-price-micros": {
        "schema": {
         "type": "string"
        },
        "description": "Per-outcome overage price in microdollars (present when a quota applies)"
       },
       "x-nsr-outcome-remaining": {
        "schema": {
         "type": "string"
        },
        "description": "Outcomes remaining in the current period (present when a quota applies)"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/DecisionResponse"
        }
       }
      }
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "402": {
      "description": "Outcome quota exhausted"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/v1/decisions/batch": {
   "post": {
    "tags": [
     "Verified Decisions"
    ],
    "summary": "Decide over a batch of requests in one call \u2014 for enterprises scoring whole",
    "description": "portfolios (e.g. refund-eligibility across 10k orders). Each item is metered\nindependently (so quota/billing behave exactly as N single calls); a failing\nitem is reported in-place without aborting the rest.\n\n**Required scope:** `write`",
    "operationId": "batch_decision_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Optional idempotency key (Stripe-style). Retries with the same key within the retention window replay the stored batch response instead of re-deciding and re-billing.",
      "required": false,
      "schema": {
       "type": "string",
       "nullable": true
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/BatchDecisionRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Per-item decisions with proofs + batch summary",
      "headers": {
       "idempotent-replayed": {
        "schema": {
         "type": "string"
        },
        "description": "true when this response was replayed from a stored idempotent result; false on first execution (present when Idempotency-Key was sent)"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/BatchDecisionResponse"
        }
       }
      }
     },
     "400": {
      "description": "Empty or oversized batch"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/v1/decisions/calibration": {
   "get": {
    "tags": [
     "Verified Decisions"
    ],
    "summary": "The reliability curve: how well the engine's reported confidence predicts",
    "description": "the real-world honored rate, bucketed by confidence, with an Expected\nCalibration Error. Requires recorded outcomes (see the outcome endpoint) \u2014\nthis is what lets an operator set an auto-send threshold they can trust.\n\n**Required scope:** `read`",
    "operationId": "decision_calibration_handler",
    "responses": {
     "200": {
      "description": "Reliability curve",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Calibration"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/v1/decisions/export": {
   "get": {
    "tags": [
     "Decisions"
    ],
    "summary": "Chronological NDJSON export of the org's durable decision log for",
    "description": "compliance/SIEM pipelines. One `DecisionRecord` JSON object per line;\n`x-export-count` carries the row count. Requires database persistence \u2014\nthere is deliberately no in-memory fallback (a bounded ring would silently\ntruncate an export), so without a configured database this returns 503.\n\n**Required scope:** `read`",
    "operationId": "export_decisions_handler",
    "parameters": [
     {
      "name": "since",
      "in": "query",
      "description": "RFC3339 lower bound (inclusive).",
      "required": false,
      "schema": {
       "type": "string",
       "nullable": true
      }
     },
     {
      "name": "until",
      "in": "query",
      "description": "RFC3339 upper bound (exclusive).",
      "required": false,
      "schema": {
       "type": "string",
       "nullable": true
      }
     },
     {
      "name": "limit",
      "in": "query",
      "description": "Max rows (default 1000, cap 10000).",
      "required": false,
      "schema": {
       "type": "integer",
       "nullable": true,
       "minimum": 0
      }
     }
    ],
    "responses": {
     "200": {
      "description": "NDJSON stream of decision records, oldest first"
     },
     "400": {
      "description": "Malformed since/until bound"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "503": {
      "description": "Durable decision store unavailable"
     }
    }
   }
  },
  "/v1/decisions/impact": {
   "post": {
    "tags": [
     "Verified Decisions"
    ],
    "summary": "POST /v1/decisions/impact \u2014 preview a policy change against logged",
    "description": "decisions. Dry-run: bills nothing, logs nothing, persists nothing.\n\n**Required scope:** `write`",
    "operationId": "policy_impact_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/PolicyImpactRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Counterfactual replay report: outcome flips under the candidate policy",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PolicyImpactResponse"
        }
       }
      }
     },
     "400": {
      "description": "A candidate rule cannot be represented as a stored org rule (multiple conclusions or a declared effect)"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    },
    "security": [
     {
      "api_key": []
     },
     {
      "bearer_auth": []
     }
    ]
   }
  },
  "/v1/decisions/outcome-by-ref": {
   "post": {
    "tags": [
     "Verified Decisions"
    ],
    "summary": "Record a decision's real-world outcome by the client's correlation key",
    "description": "instead of our `decision_id` \u2014 the path a real event takes. A chargeback,\nrefund reversal, or human override knows the order/case id it happened to,\nnot the decision id we returned; this closes the outcome loop from those\nevents. Targets the most-recent decision carrying the ref. 404 if no\ndecision with that ref is in the retained window.\n\n**Required scope:** `write`",
    "operationId": "record_decision_outcome_by_ref_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/RecordOutcomeByRefRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Outcome recorded",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/RecordOutcomeResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/v1/decisions/recent": {
   "get": {
    "tags": [
     "Verified Decisions"
    ],
    "summary": "Most recent decisions for the org, newest first. Ephemeral in-memory",
    "description": "analytics \u2014 billing truth lives in the metering pipeline.\n\n**Required scope:** `read`",
    "operationId": "recent_decisions_handler",
    "responses": {
     "200": {
      "description": "Recent decision records",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/RecentDecisionsResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/v1/decisions/refusal-gaps": {
   "get": {
    "tags": [
     "Verified Decisions"
    ],
    "summary": "Refusal coverage gaps: how often each missing premise blocked a decision",
    "description": "over the window, most-frequent first. A high count means many decisions\nrefused for lack of that premise \u2014 add a rule/fact/connector for it.\n\n**Required scope:** `read`",
    "operationId": "decision_refusal_gaps_handler",
    "responses": {
     "200": {
      "description": "Most-frequent missing premises",
      "content": {
       "application/json": {
        "schema": {
         "type": "array",
         "items": {
          "$ref": "#/components/schemas/RefusalGap"
         }
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/v1/decisions/refusal-roadmap": {
   "get": {
    "tags": [
     "Verified Decisions"
    ],
    "summary": "Integration roadmap: the org's refusal gaps as a prioritized, actionable",
    "description": "list \u2014 each premise the engine keeps asking for, how many refusals it\nblocked, its share of all refusals, and the next step. Turns refusals from\ndead-ends into \"connect this and N% of them resolve\".\n\n**Required scope:** `read`",
    "operationId": "decision_refusal_roadmap_handler",
    "responses": {
     "200": {
      "description": "Prioritized integration roadmap",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/RefusalRoadmap"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/v1/decisions/rule-stats": {
   "get": {
    "tags": [
     "Verified Decisions"
    ],
    "summary": "Per-rule cited-vs-noise usage over a window \u2014 the demotion signal. A rule",
    "description": "with high `noise_count` and near-zero `cited_count` fires on every\ndecision without ever being relevant; the response is ordered\nnoisiest-first.\n\n**Required scope:** `read`",
    "operationId": "decision_rule_stats_handler",
    "responses": {
     "200": {
      "description": "Per-rule cited/noise usage",
      "content": {
       "application/json": {
        "schema": {
         "type": "array",
         "items": {
          "$ref": "#/components/schemas/RuleUsageStat"
         }
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/v1/decisions/stats": {
   "get": {
    "tags": [
     "Verified Decisions"
    ],
    "summary": "Aggregate decision stats over a window: outcome counts, billable volume,",
    "description": "latency percentiles, most-cited rules.\n\n**Required scope:** `read`",
    "operationId": "decision_stats_handler",
    "responses": {
     "200": {
      "description": "Aggregate decision stats",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/DecisionStats"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/v1/decisions/{id}": {
   "get": {
    "tags": [
     "Verified Decisions"
    ],
    "summary": "Look up one recent decision by the `decision_id` from the API response or",
    "description": "the `outcome.produced` webhook. The analytics log is bounded and\nephemeral: a 404 means \"rotated out of the recent window or never\nexisted\" \u2014 billing truth lives in the metering pipeline.\n\n**Required scope:** `read`",
    "operationId": "get_decision_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The decision record",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/DecisionRecord"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "Not in the retained window"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/v1/decisions/{id}/outcome": {
   "post": {
    "tags": [
     "Verified Decisions"
    ],
    "summary": "Record the real-world outcome of a past decision \u2014 the write side of the",
    "description": "outcome loop that makes confidence measurable. `honored` means the decision\nheld up; `reversed` (e.g. an approved refund charged back), `overridden`\n(a human changed it), `escalated`. 404 if the decision has rotated out of\nthe retained window.\n\n**Required scope:** `write`",
    "operationId": "record_decision_outcome_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/RecordOutcomeRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Outcome recorded",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/RecordOutcomeResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/v1/files": {
   "get": {
    "tags": [
     "Ingestion"
    ],
    "description": "**Required scope:** `read`",
    "operationId": "list_files_handler",
    "responses": {
     "200": {
      "description": "Files",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/FileListResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   },
   "post": {
    "tags": [
     "Ingestion"
    ],
    "description": "**Required scope:** `write`",
    "operationId": "create_file_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CreateFileRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "201": {
      "description": "File uploaded",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/FileObject"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/v1/files/{id}": {
   "get": {
    "tags": [
     "Ingestion"
    ],
    "description": "**Required scope:** `read`",
    "operationId": "get_file_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "File ID",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "File metadata",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/FileObject"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/v1/files/{id}/content": {
   "get": {
    "tags": [
     "Ingestion"
    ],
    "description": "**Required scope:** `read`",
    "operationId": "get_file_content_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "File ID",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Raw file content",
      "content": {
       "application/octet-stream": {
        "schema": {
         "type": "string"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/v1/ingest/jobs": {
   "get": {
    "tags": [
     "Ingestion"
    ],
    "description": "**Required scope:** `read`",
    "operationId": "list_ingest_jobs_handler",
    "responses": {
     "200": {
      "description": "Ingest jobs",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/IngestJobListResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   },
   "post": {
    "tags": [
     "Ingestion"
    ],
    "description": "**Required scope:** `write`",
    "operationId": "create_ingest_job_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CreateIngestJobRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "201": {
      "description": "Ingest job created",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/IngestJobResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/v1/ingest/jobs/{id}": {
   "get": {
    "tags": [
     "Ingestion"
    ],
    "description": "**Required scope:** `read`",
    "operationId": "get_ingest_job_handler",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "description": "Ingest job ID",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Ingest job",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/IngestJobResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/v1/messages": {
   "post": {
    "tags": [
     "Provider Compatibility"
    ],
    "summary": "Anthropic-compatible Messages endpoint backed by the recursive NSR solver.",
    "description": "**Required scope:** `write`",
    "operationId": "anthropic_messages_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {}
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Anthropic-compatible message",
      "content": {
       "application/json": {
        "schema": {}
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/v1/messages/count_tokens": {
   "post": {
    "tags": [
     "Provider Compatibility"
    ],
    "summary": "Anthropic-compatible token counting (`POST /v1/messages/count_tokens`).",
    "description": "Claude Code and the Anthropic SDKs call this before sending requests.\n\n**Required scope:** `write`",
    "operationId": "count_tokens_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {}
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Estimated input token count",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/CountTokensResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/v1/metering/aws/register": {
   "post": {
    "tags": [
     "Metering & Marketplace"
    ],
    "summary": "AWS Marketplace SaaS onboarding: resolve the registration token to the",
    "description": "customer's identifiers via ResolveCustomer, then link them to the org so the\nhourly flush bills their AWS account. Requires `NSR_METERING_AWS_*`.\n\n**Required scope:** `admin`",
    "operationId": "aws_register_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/AwsRegisterRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Customer resolved and linked"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "502": {
      "description": "AWS ResolveCustomer failed"
     },
     "503": {
      "description": "AWS marketplace metering not configured"
     }
    }
   }
  },
  "/v1/metering/azure/register": {
   "post": {
    "tags": [
     "Metering & Marketplace"
    ],
    "summary": "Azure Marketplace SaaS onboarding: resolve the marketplace token to the SaaS",
    "description": "subscription, then link it so the flush reports `usageEvent`s against it.\nRequires `NSR_METERING_AZURE_TOKEN`.\n\n**Required scope:** `admin`",
    "operationId": "azure_register_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/AzureRegisterRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Subscription resolved and linked"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     },
     "502": {
      "description": "Azure resolve failed"
     },
     "503": {
      "description": "Azure marketplace metering not configured"
     }
    }
   }
  },
  "/v1/metering/entitlement": {
   "post": {
    "tags": [
     "Metering & Marketplace"
    ],
    "summary": "Link an org to its billing entitlement (admin). Idempotent \u2014 re-linking",
    "description": "updates the mapping.\n\n**Required scope:** `admin`",
    "operationId": "link_entitlement_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/LinkEntitlementRequest"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Entitlement linked"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/v1/metering/entitlement/{org_id}": {
   "get": {
    "tags": [
     "Metering & Marketplace"
    ],
    "summary": "Read an org's current entitlement (admin).",
    "description": "**Required scope:** `admin`",
    "operationId": "get_entitlement_handler",
    "parameters": [
     {
      "name": "org_id",
      "in": "path",
      "description": "The NSR org/tenant",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The org's entitlement"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "404": {
      "description": "No entitlement linked"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/v1/metering/gcp/pubsub": {
   "post": {
    "tags": [
     "Metering & Marketplace"
    ],
    "summary": "GCP Marketplace Pub/Sub push endpoint. GCP delivers Procurement events here",
    "description": "(account/entitlement creation, plan change, cancellation). On an entitlement\nevent whose `account` is already associated with an org (established at\nsign-up via `/v1/metering/entitlement` with `kind:\"gcp\"`, `token:<account>`),\n(re)link the GCP entitlement so the flush reports usage against it. Always\n200 to ack the push (an un-acked message is redelivered). Approving the\nentitlement via the Partner Procurement API is the credentialed follow-on.\n\n**Required scope:** `write`",
    "operationId": "gcp_pubsub_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/PubSubPush"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Event acked (linked=true when the account was pre-associated)"
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/v1/models": {
   "get": {
    "tags": [
     "Provider Compatibility"
    ],
    "summary": "OpenAI-compatible model catalog for the NSR chat facade.",
    "description": "**Required scope:** `read`",
    "operationId": "nsr_models_handler",
    "responses": {
     "200": {
      "description": "Available provider-compatible models",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ModelsListResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/v1/proofs/verify": {
   "post": {
    "tags": [
     "Verified Decisions"
    ],
    "summary": "Independently verify a self-contained proof bundle against nothing but",
    "description": "itself \u2014 no engine, no database, no tenant state. POST an approved\ndecision's `verifiable_bundle` VERBATIM to confirm that verdict without\ntrusting the decision endpoint (the same check ships as the open,\ndependency-light `nsr-proof-core` crate for fully offline verification).\nAlways returns 200 with a verdict: an unsound proof is a valid *answer*\n(`verified:false` + the located reason), not a client error. The body is\nthe raw `knowledge::ProofBundle` \u2014 `{facts, rules, proof, org_id?, as_of?}`\n\u2014 exactly as `verifiable_bundle` emits it; hand-authored bundles are\ndocumented in docs/GETTING_STARTED_SCENARIOS.md.\n\n**Required scope:** `write`",
    "operationId": "verify_proof_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "description": "A self-contained proof bundle: `{facts, rules, proof, org_id?, as_of?}`. Pass a decision's `verifiable_bundle` verbatim.",
     "content": {
      "application/json": {
       "schema": {
        "type": "object"
       }
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "Verification verdict (200 for BOTH verified and unverified proofs)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ProofVerifyResponse"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/v1/responses": {
   "post": {
    "tags": [
     "Provider Compatibility"
    ],
    "description": "**Required scope:** `write`",
    "operationId": "nsr_responses_handler",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "description": "Retry-safe key. Replaying the same key with the same body returns the original response and sets `idempotent-replayed`; a different body with the same key is rejected 422. Use it so a retried write cannot double-execute or double-bill.",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {}
      }
     },
     "required": true
    },
    "responses": {
     "200": {
      "description": "OpenAI-compatible response object",
      "content": {
       "application/json": {
        "schema": {}
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/v1/responses/{response_id}": {
   "get": {
    "tags": [
     "Provider Compatibility"
    ],
    "description": "**Required scope:** `read`",
    "operationId": "get_response_handler",
    "parameters": [
     {
      "name": "response_id",
      "in": "path",
      "description": "Response ID",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Stored response",
      "content": {
       "application/json": {
        "schema": {}
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  },
  "/v1/responses/{response_id}/input_items": {
   "get": {
    "tags": [
     "Provider Compatibility"
    ],
    "description": "**Required scope:** `read`",
    "operationId": "list_response_input_items_handler",
    "parameters": [
     {
      "name": "response_id",
      "in": "path",
      "description": "Response ID",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Normalized input items for a stored response",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ResponseInputItemsList"
        }
       }
      }
     },
     "401": {
      "description": "Unauthorized \u2014 missing or invalid credentials"
     },
     "403": {
      "description": "Forbidden \u2014 the key/token lacks the required scope"
     },
     "429": {
      "description": "Rate limited \u2014 see Retry-After / X-RateLimit-Reset"
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "ActionExecutionResult": {
    "type": "object",
    "required": [
     "action_type",
     "tool_name",
     "status",
     "summary",
     "details",
     "matched_entity_ids"
    ],
    "properties": {
     "action_type": {
      "type": "string"
     },
     "details": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "matched_entity_ids": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "status": {
      "type": "string"
     },
     "summary": {
      "type": "string"
     },
     "tool_name": {
      "type": "string"
     }
    }
   },
   "AddBeliefRequest": {
    "type": "object",
    "description": "Request to add a belief",
    "required": [
     "proposition",
     "confidence"
    ],
    "properties": {
     "confidence": {
      "type": "number",
      "format": "float",
      "description": "Initial confidence (0.0 to 1.0)"
     },
     "proposition": {
      "type": "string",
      "description": "The proposition (belief statement)"
     },
     "source": {
      "type": "string",
      "description": "Source of the belief",
      "nullable": true
     }
    },
    "example": {
     "confidence": 0.95,
     "proposition": "socrates_is_mortal",
     "source": "observation"
    }
   },
   "AddSymbolRequest": {
    "type": "object",
    "description": "Request to add a symbol",
    "required": [
     "name"
    ],
    "properties": {
     "grounded_embedding": {
      "type": "array",
      "items": {
       "type": "number",
       "format": "float"
      },
      "description": "Optional grounded prototype embedding (for emulator centroids / composite symbols).",
      "nullable": true
     },
     "name": {
      "type": "string",
      "description": "Symbol name"
     },
     "program": {
      "allOf": [
       {
        "$ref": "#/components/schemas/ProgramRequest"
       }
      ],
      "nullable": true
     }
    },
    "example": {
     "grounded_embedding": [
      1.0,
      0.0,
      0.0
     ],
     "name": "WALK",
     "program": {
      "name": "identity",
      "type": "primitive"
     }
    }
   },
   "AddSymbolsRequest": {
    "type": "object",
    "description": "Request to add multiple symbols",
    "required": [
     "names"
    ],
    "properties": {
     "names": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "List of symbol names"
     }
    },
    "example": {
     "names": [
      "WALK",
      "RUN",
      "JUMP",
      "TURN_LEFT",
      "TURN_RIGHT"
     ]
    }
   },
   "AddThoughtRequest": {
    "type": "object",
    "description": "Request to add a thought",
    "required": [
     "content",
     "score"
    ],
    "properties": {
     "content": {
      "type": "string",
      "description": "Thought content"
     },
     "parent_id": {
      "type": "integer",
      "description": "Optional parent thought ID to connect from",
      "nullable": true,
      "minimum": 0
     },
     "score": {
      "type": "number",
      "format": "float",
      "description": "Initial score"
     }
    },
    "example": {
     "content": "First, identify the action primitives in the input",
     "parent_id": null,
     "score": 0.85
    }
   },
   "AdvancedReasoningSnapshot": {
    "type": "object",
    "required": [
     "enabled_features",
     "machine_inputs",
     "inferred_symbols",
     "grounded_categories",
     "grounded_domains",
     "grounded_intents",
     "grounded_entities"
    ],
    "properties": {
     "enabled_features": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "explanation_summary": {
      "type": "string",
      "nullable": true
     },
     "grounded_categories": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "grounded_domains": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "grounded_entities": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "grounded_intents": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "inferred_symbols": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "machine_confidence": {
      "type": "number",
      "format": "double",
      "nullable": true
     },
     "machine_inputs": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "machine_output": {
      "type": "string",
      "nullable": true
     },
     "machine_state_version": {
      "type": "integer",
      "format": "int64",
      "description": "The org machine's chat-mutation version this inference ran against.",
      "nullable": true,
      "minimum": 0
     },
     "recommended_strategy": {
      "type": "string",
      "nullable": true
     },
     "thought_count": {
      "type": "integer",
      "nullable": true,
      "minimum": 0
     },
     "uncertainty": {
      "allOf": [
       {
        "$ref": "#/components/schemas/MachineUncertaintySnapshot"
       }
      ],
      "nullable": true
     }
    }
   },
   "AgentActionResponse": {
    "type": "object",
    "required": [
     "name",
     "action",
     "running",
     "status"
    ],
    "properties": {
     "action": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "running": {
      "type": "boolean"
     },
     "status": {
      "type": "string"
     }
    }
   },
   "AgentRuntimeStatus": {
    "type": "object",
    "required": [
     "name",
     "description",
     "enabled",
     "running",
     "interval_secs",
     "confidence_threshold",
     "max_concurrency",
     "require_approval"
    ],
    "properties": {
     "confidence_threshold": {
      "type": "number",
      "format": "float"
     },
     "description": {
      "type": "string"
     },
     "enabled": {
      "type": "boolean"
     },
     "interval_secs": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "max_concurrency": {
      "type": "integer",
      "minimum": 0
     },
     "name": {
      "type": "string"
     },
     "require_approval": {
      "type": "boolean"
     },
     "running": {
      "type": "boolean"
     }
    }
   },
   "AnswerEvidence": {
    "type": "object",
    "description": "Enough evidence to audit an answer without carrying the whole envelope.",
    "required": [
     "decision_id",
     "cited_rules",
     "grounding",
     "because"
    ],
    "properties": {
     "because": {
      "type": "string",
      "description": "Human-readable statement of why, derived from the proof."
     },
     "cited_rules": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "decision_id": {
      "type": "string"
     },
     "grounding": {
      "type": "string"
     },
     "policy_hash": {
      "type": "string",
      "description": "sha256 over the exact policy this answer stands on.",
      "nullable": true
     },
     "replayable": {
      "type": "boolean",
      "description": "True when every cited rule re-fires from the evidence in this response.",
      "nullable": true
     }
    }
   },
   "AnswerGap": {
    "type": "object",
    "description": "A premise that would change the answer if your systems could confirm it.",
    "required": [
     "fact"
    ],
    "properties": {
     "fact": {
      "type": "string"
     },
     "needed_by_rule": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "AnswerRequest": {
    "type": "object",
    "required": [
     "subject"
    ],
    "properties": {
     "context": {
      "type": "object",
      "description": "Merge-field values for the macro and its tool call.",
      "additionalProperties": {}
     },
     "facts": {
      "type": "object",
      "description": "What your systems know about the subject.\n\n`true` asserts `predicate(subject)`; any other scalar asserts\n`predicate(subject, value)` so thresholds work\n(`{\"order_amount\": 620}` -> `order_amount(T-1, 620)`); `false` and\n`null` assert nothing, which is what produces an honest refusal rather\nthan a negative claim the engine never verified.",
      "additionalProperties": {}
     },
     "include_decision": {
      "type": "boolean",
      "description": "Return the full decision envelope alongside the summary."
     },
     "mode": {
      "type": "string",
      "description": "Reasoning profile: `fast` | `accurate` | `safe`. Defaults to `safe`.",
      "nullable": true
     },
     "question": {
      "type": "string",
      "description": "The customer's message. Optional: facts decide the outcome, so a ticket\nwith no prose still answers.",
      "nullable": true
     },
     "rules": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/RecursiveChatRuleInput"
      },
      "description": "Inline policy. Omit to use the rules stored for this org.",
      "nullable": true
     },
     "subject": {
      "type": "string",
      "description": "What this decision is ABOUT \u2014 a ticket id, order id, or case id. First\nclass because the engine binds authorization to it."
     }
    }
   },
   "AnswerResponse": {
    "type": "object",
    "required": [
     "subject",
     "verdict",
     "auto_send",
     "evidence"
    ],
    "properties": {
     "auto_send": {
      "type": "boolean",
      "description": "True when this can ship untouched. False means read `requires_human`."
     },
     "decision": {
      "allOf": [
       {
        "$ref": "#/components/schemas/DecisionResponse"
       }
      ],
      "nullable": true
     },
     "evidence": {
      "$ref": "#/components/schemas/AnswerEvidence"
     },
     "gaps": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/AnswerGap"
      },
      "description": "What to go and find out. Each entry, if confirmed, may change the answer."
     },
     "reply": {
      "allOf": [
       {
        "$ref": "#/components/schemas/DraftedReply"
       }
      ],
      "nullable": true
     },
     "requires_human": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Why a human is needed. Empty means none is."
     },
     "subject": {
      "type": "string"
     },
     "tool_call": {
      "description": "Emitted, NOT executed \u2014 the engine never holds your credentials. Run it\nagainst your own systems.",
      "nullable": true
     },
     "verdict": {
      "type": "string",
      "description": "`approved` | `denied` | `refused`."
     }
    }
   },
   "ApiKeyCreateRequest": {
    "type": "object",
    "required": [
     "name"
    ],
    "properties": {
     "name": {
      "type": "string",
      "description": "Friendly name for the key."
     },
     "org_id": {
      "type": "string",
      "description": "Optional org id. Must match the authenticated org when provided.",
      "nullable": true
     },
     "rate_limit_per_minute": {
      "type": "integer",
      "format": "int32",
      "description": "Optional rate limit override for this key.\n- `0` disables rate limiting for this key.\n- positive values cap requests per minute.\n- values that are not positive are treated as unset.",
      "nullable": true,
      "minimum": 0
     },
     "scopes": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ApiScope"
      },
      "description": "Scopes for the key (defaults to admin).",
      "nullable": true
     }
    }
   },
   "ApiKeyCreateResponse": {
    "type": "object",
    "required": [
     "id",
     "name",
     "org_id",
     "scopes",
     "key",
     "prefix",
     "created_at"
    ],
    "properties": {
     "created_at": {
      "type": "string"
     },
     "expires_at": {
      "type": "string",
      "nullable": true
     },
     "id": {
      "type": "string"
     },
     "key": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "org_id": {
      "type": "string"
     },
     "prefix": {
      "type": "string"
     },
     "rate_limit_per_minute": {
      "type": "integer",
      "format": "int32",
      "nullable": true,
      "minimum": 0
     },
     "scopes": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ApiScope"
      }
     }
    }
   },
   "ApiKeyListItem": {
    "type": "object",
    "required": [
     "id",
     "name",
     "org_id",
     "scopes",
     "prefix",
     "created_at"
    ],
    "properties": {
     "created_at": {
      "type": "string"
     },
     "expires_at": {
      "type": "string",
      "nullable": true
     },
     "id": {
      "type": "string"
     },
     "last_used_at": {
      "type": "string",
      "nullable": true
     },
     "name": {
      "type": "string"
     },
     "org_id": {
      "type": "string"
     },
     "prefix": {
      "type": "string"
     },
     "rate_limit_per_minute": {
      "type": "integer",
      "format": "int32",
      "nullable": true,
      "minimum": 0
     },
     "revoked_at": {
      "type": "string",
      "nullable": true
     },
     "scopes": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ApiScope"
      }
     }
    }
   },
   "ApiKeyListResponse": {
    "type": "object",
    "required": [
     "keys",
     "total"
    ],
    "properties": {
     "keys": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ApiKeyListItem"
      }
     },
     "total": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "ApiKeyRevokeResponse": {
    "type": "object",
    "required": [
     "id",
     "revoked_at"
    ],
    "properties": {
     "id": {
      "type": "string"
     },
     "revoked_at": {
      "type": "string"
     }
    }
   },
   "ApiScope": {
    "type": "string",
    "description": "Permission scopes for API keys",
    "enum": [
     "read",
     "write",
     "admin",
     "billing:write",
     "sandbox:execute",
     "agents:admin",
     "models:manage"
    ]
   },
   "ApplyTemplateResponse": {
    "type": "object",
    "required": [
     "template_slug",
     "mode",
     "entities_created",
     "entities_skipped",
     "rules_created",
     "rules_skipped",
     "errors"
    ],
    "properties": {
     "entities_created": {
      "type": "integer",
      "minimum": 0
     },
     "entities_skipped": {
      "type": "integer",
      "minimum": 0
     },
     "errors": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "input_predicates": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "The facts this rulebook now needs to reach a verdict \u2014 supply these\n(per decision via `facts`, or as KB triples) to drive it. Closes the\napply\u2192supply\u2192decide loop so the caller isn't left guessing."
     },
     "mode": {
      "type": "string"
     },
     "rules_created": {
      "type": "integer",
      "minimum": 0
     },
     "rules_skipped": {
      "type": "integer",
      "minimum": 0
     },
     "template_slug": {
      "type": "string"
     }
    }
   },
   "Arg": {
    "oneOf": [
     {
      "type": "string",
      "description": "A variable (starts with ?)"
     },
     {
      "type": "string",
      "description": "A string value"
     },
     {
      "type": "number",
      "format": "double",
      "description": "A numeric value"
     },
     {
      "type": "boolean",
      "description": "A boolean value"
     },
     {
      "type": "object",
      "default": null,
      "nullable": true
     }
    ],
    "description": "A variable or value in a predicate argument\n\nDeserialization is MANUAL (below): with `#[serde(untagged)]` + derived\nDeserialize, `Variable(String)` \u2014 the first variant \u2014 swallowed every\nwire string, so request-fact args like \"Viewer\" became variables, and\nvariables wildcard-match any rule constant. That minted false\nauthorizations (an Admin-only rule fired for a Viewer). The convention is\nexplicit: strings starting with `?` are variables, everything else is a\nvalue."
   },
   "ArtifactType": {
    "type": "string",
    "enum": [
     "Rule",
     "ParserPattern",
     "Example",
     "StrategyWeight",
     "LowConfidencePattern"
    ]
   },
   "Atom": {
    "type": "object",
    "description": "An atomic formula representing a predicate application",
    "required": [
     "predicate",
     "terms",
     "negated"
    ],
    "properties": {
     "negated": {
      "type": "boolean",
      "description": "Whether this atom is negated"
     },
     "predicate": {
      "type": "string",
      "description": "Predicate name (relation)"
     },
     "terms": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Term"
      },
      "description": "Arguments (terms) of the predicate"
     }
    }
   },
   "AttachEvidenceRequest": {
    "type": "object",
    "required": [
     "evidence_id"
    ],
    "properties": {
     "evidence_id": {
      "type": "string",
      "description": "Existing evidence node ID to link to this triple"
     }
    }
   },
   "AuditEvent": {
    "type": "object",
    "description": "Audit event record",
    "required": [
     "timestamp_ms",
     "timestamp",
     "event_type",
     "request_id",
     "method",
     "path",
     "status",
     "duration_ms"
    ],
    "properties": {
     "api_key_prefix": {
      "type": "string",
      "description": "First 8 chars of API key (for identification without exposure)",
      "nullable": true
     },
     "client_ip": {
      "type": "string",
      "description": "Client IP address",
      "nullable": true
     },
     "context": {
      "description": "Additional context",
      "nullable": true
     },
     "duration_ms": {
      "type": "integer",
      "format": "int64",
      "description": "Request duration in milliseconds",
      "minimum": 0
     },
     "error": {
      "type": "string",
      "description": "Error message if applicable",
      "nullable": true
     },
     "event_type": {
      "$ref": "#/components/schemas/AuditEventType"
     },
     "method": {
      "type": "string",
      "description": "HTTP method"
     },
     "operation": {
      "type": "string",
      "description": "Operation performed",
      "nullable": true
     },
     "path": {
      "type": "string",
      "description": "Request path"
     },
     "request_id": {
      "type": "string",
      "description": "Unique request identifier"
     },
     "resource_type": {
      "type": "string",
      "description": "Type of resource affected",
      "nullable": true
     },
     "status": {
      "type": "integer",
      "format": "int32",
      "description": "Response status code",
      "minimum": 0
     },
     "timestamp": {
      "type": "string",
      "description": "ISO 8601 timestamp string"
     },
     "timestamp_ms": {
      "type": "integer",
      "format": "int64",
      "description": "Unix timestamp in milliseconds",
      "minimum": 0
     }
    }
   },
   "AuditEventType": {
    "type": "string",
    "description": "Types of audit events",
    "enum": [
     "api_request",
     "auth_attempt",
     "rate_limited",
     "resource_created",
     "resource_modified",
     "resource_deleted",
     "config_changed",
     "error"
    ]
   },
   "AuditExportResponse": {
    "type": "object",
    "required": [
     "org_id",
     "event_count",
     "total_available",
     "generated_at",
     "events"
    ],
    "properties": {
     "event_count": {
      "type": "integer",
      "minimum": 0
     },
     "events": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/AuditEvent"
      }
     },
     "generated_at": {
      "type": "string",
      "format": "date-time"
     },
     "org_id": {
      "type": "string"
     },
     "total_available": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "AuditTrailResponse": {
    "type": "object",
    "description": "Audit trail response",
    "required": [
     "deleted_entities",
     "deleted_rules",
     "deleted_triples_count",
     "total_deleted"
    ],
    "properties": {
     "deleted_entities": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/DeletedEntityRecord"
      }
     },
     "deleted_rules": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/DeletedRuleRecord"
      }
     },
     "deleted_triples_count": {
      "type": "integer",
      "minimum": 0
     },
     "total_deleted": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "AuthLoginRequest": {
    "type": "object",
    "required": [
     "email",
     "password"
    ],
    "properties": {
     "email": {
      "type": "string"
     },
     "password": {
      "type": "string"
     }
    }
   },
   "AuthResponse": {
    "type": "object",
    "required": [
     "user_id",
     "email",
     "org_id",
     "api_key",
     "api_key_prefix",
     "api_key_created_at"
    ],
    "properties": {
     "api_key": {
      "type": "string"
     },
     "api_key_created_at": {
      "type": "string"
     },
     "api_key_prefix": {
      "type": "string"
     },
     "email": {
      "type": "string"
     },
     "org_id": {
      "type": "string"
     },
     "user_id": {
      "type": "string"
     }
    }
   },
   "AuthSessionResponse": {
    "type": "object",
    "required": [
     "auth_type",
     "scopes"
    ],
    "properties": {
     "auth_type": {
      "type": "string"
     },
     "email": {
      "type": "string",
      "nullable": true
     },
     "name": {
      "type": "string",
      "nullable": true
     },
     "org_id": {
      "type": "string",
      "nullable": true
     },
     "rate_limit_per_minute": {
      "type": "integer",
      "format": "int32",
      "nullable": true,
      "minimum": 0
     },
     "scopes": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ApiScope"
      }
     },
     "user_id": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "AuthSignupRequest": {
    "type": "object",
    "required": [
     "email",
     "password"
    ],
    "properties": {
     "email": {
      "type": "string"
     },
     "org_id": {
      "type": "string",
      "description": "Reserved for backward compatibility. Public signup does not allow overriding org_id.",
      "nullable": true
     },
     "password": {
      "type": "string"
     }
    }
   },
   "AwsRegisterRequest": {
    "type": "object",
    "required": [
     "org_id",
     "registration_token"
    ],
    "properties": {
     "dimension": {
      "type": "string",
      "description": "Metered dimension to bill against (default `verified_decisions`).",
      "nullable": true
     },
     "org_id": {
      "type": "string",
      "description": "The NSR org/tenant to bill for this subscription."
     },
     "registration_token": {
      "type": "string",
      "description": "The `x-amzn-marketplace-token` the customer's browser POSTs to our\nlanding page right after they subscribe on AWS Marketplace."
     }
    }
   },
   "AzureRegisterRequest": {
    "type": "object",
    "required": [
     "org_id",
     "marketplace_token"
    ],
    "properties": {
     "dimension": {
      "type": "string",
      "nullable": true
     },
     "marketplace_token": {
      "type": "string",
      "description": "The `x-ms-marketplace-token` the customer's browser POSTs to our landing\npage after subscribing to the Azure SaaS offer."
     },
     "org_id": {
      "type": "string"
     }
    }
   },
   "BackwardChainRequest": {
    "type": "object",
    "description": "Request for backward chaining",
    "required": [
     "goal_predicate",
     "goal_args"
    ],
    "properties": {
     "goal_args": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Arguments for the goal"
     },
     "goal_predicate": {
      "type": "string",
      "description": "The goal to prove"
     },
     "max_depth": {
      "type": "integer",
      "description": "Maximum proof depth",
      "nullable": true,
      "minimum": 0
     },
     "use_belief_guard": {
      "type": "boolean",
      "description": "Route the proof through the AGM belief guard: consult entrenchment\nbefore search, expand/revise the belief base with each proof."
     }
    }
   },
   "BackwardChainResponse": {
    "type": "object",
    "description": "Response with backward chaining proofs",
    "required": [
     "proved",
     "proofs",
     "total_proofs"
    ],
    "properties": {
     "belief_actions": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Audit log of AGM belief-base mutations (present iff `use_belief_guard`).",
      "nullable": true
     },
     "proofs": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ProofInfo"
      }
     },
     "proved": {
      "type": "boolean"
     },
     "total_proofs": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "BatchAnswerError": {
    "type": "object",
    "required": [
     "index",
     "subject",
     "error"
    ],
    "properties": {
     "error": {
      "type": "string"
     },
     "index": {
      "type": "integer",
      "minimum": 0
     },
     "subject": {
      "type": "string"
     }
    }
   },
   "BatchAnswerRequest": {
    "type": "object",
    "required": [
     "items"
    ],
    "properties": {
     "items": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/AnswerRequest"
      }
     }
    }
   },
   "BatchAnswerResponse": {
    "type": "object",
    "required": [
     "answers",
     "errors",
     "auto_send_count",
     "human_count"
    ],
    "properties": {
     "answers": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/AnswerResponse"
      }
     },
     "auto_send_count": {
      "type": "integer",
      "minimum": 0
     },
     "errors": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/BatchAnswerError"
      },
      "description": "Per-item failures by index. One bad ticket never sinks a queue."
     },
     "human_count": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "BatchCreateEntitiesRequest": {
    "type": "object",
    "description": "Request for batch entity creation",
    "required": [
     "entities"
    ],
    "properties": {
     "entities": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/CreateEntityRequest"
      }
     }
    }
   },
   "BatchCreateEntitiesResponse": {
    "type": "object",
    "description": "Response for batch entity creation",
    "required": [
     "created",
     "failed",
     "entities",
     "errors"
    ],
    "properties": {
     "created": {
      "type": "integer",
      "minimum": 0
     },
     "entities": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/EntityResponse"
      }
     },
     "errors": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "failed": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "BatchCreateMacrosRequest": {
    "type": "object",
    "required": [
     "macros"
    ],
    "properties": {
     "macros": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/CreateMacroRequest"
      }
     }
    }
   },
   "BatchCreateMacrosResponse": {
    "type": "object",
    "required": [
     "created",
     "replaced",
     "macros",
     "errors"
    ],
    "properties": {
     "created": {
      "type": "integer",
      "minimum": 0
     },
     "errors": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/BatchItemError"
      },
      "description": "Per-item problems, by index. A bad item never aborts the batch \u2014 a\nlibrary upload that fails wholesale on one malformed row is unusable."
     },
     "macros": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Macro"
      }
     },
     "replaced": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "BatchCreateRulesRequest": {
    "type": "object",
    "description": "Request for batch rule creation",
    "required": [
     "rules"
    ],
    "properties": {
     "rules": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/CreateRuleRequest"
      }
     }
    }
   },
   "BatchCreateRulesResponse": {
    "type": "object",
    "description": "Response for batch rule creation",
    "required": [
     "created",
     "failed",
     "rules",
     "errors"
    ],
    "properties": {
     "created": {
      "type": "integer",
      "description": "Number of rules successfully created",
      "minimum": 0
     },
     "errors": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Validation and creation errors"
     },
     "failed": {
      "type": "integer",
      "description": "Number of rules that failed validation or creation",
      "minimum": 0
     },
     "rules": {
      "type": "array",
      "items": {},
      "description": "Created rule information"
     }
    }
   },
   "BatchCreateTriplesRequest": {
    "type": "object",
    "description": "Request for batch triple creation",
    "required": [
     "triples"
    ],
    "properties": {
     "triples": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/CreateTripleRequest"
      }
     }
    }
   },
   "BatchCreateTriplesResponse": {
    "type": "object",
    "description": "Response for batch triple creation",
    "required": [
     "created",
     "failed",
     "triples",
     "errors"
    ],
    "properties": {
     "created": {
      "type": "integer",
      "minimum": 0
     },
     "errors": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "failed": {
      "type": "integer",
      "minimum": 0
     },
     "triples": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/TripleResponse"
      }
     }
    }
   },
   "BatchDecisionItem": {
    "type": "object",
    "required": [
     "index"
    ],
    "properties": {
     "decision": {
      "allOf": [
       {
        "$ref": "#/components/schemas/DecisionResponse"
       }
      ],
      "nullable": true
     },
     "error": {
      "allOf": [
       {
        "$ref": "#/components/schemas/BatchItemError"
       }
      ],
      "nullable": true
     },
     "index": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "BatchDecisionRequest": {
    "type": "object",
    "required": [
     "items"
    ],
    "properties": {
     "items": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/DecisionRequest"
      },
      "description": "Decision requests to evaluate. Each item is metered independently."
     }
    }
   },
   "BatchDecisionResponse": {
    "type": "object",
    "required": [
     "results",
     "summary"
    ],
    "properties": {
     "results": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/BatchDecisionItem"
      }
     },
     "summary": {
      "$ref": "#/components/schemas/BatchSummary"
     }
    }
   },
   "BatchDeleteEntitiesRequest": {
    "type": "object",
    "description": "Request for batch delete entities",
    "required": [
     "ids"
    ],
    "properties": {
     "ids": {
      "type": "array",
      "items": {
       "type": "string"
      }
     }
    }
   },
   "BatchDeleteResponse": {
    "type": "object",
    "description": "Response for batch delete operations",
    "required": [
     "deleted",
     "not_found"
    ],
    "properties": {
     "deleted": {
      "type": "integer",
      "minimum": 0
     },
     "not_found": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "BatchDeleteRulesRequest": {
    "type": "object",
    "description": "Request for batch rule deletion",
    "required": [
     "ids"
    ],
    "properties": {
     "ids": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Rule IDs to delete"
     }
    }
   },
   "BatchInferRequest": {
    "type": "object",
    "description": "Batch inference request",
    "required": [
     "inputs"
    ],
    "properties": {
     "include_explanation": {
      "type": "boolean",
      "description": "Include explanations"
     },
     "inputs": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "List of input queries"
     },
     "max_depth": {
      "type": "integer",
      "description": "Maximum reasoning depth",
      "minimum": 0
     }
    }
   },
   "BatchItemError": {
    "type": "object",
    "required": [
     "code",
     "message"
    ],
    "properties": {
     "code": {
      "type": "string"
     },
     "message": {
      "type": "string"
     }
    }
   },
   "BatchSummary": {
    "type": "object",
    "required": [
     "total",
     "approved",
     "denied",
     "refused",
     "errored",
     "billable_decisions",
     "total_cost_micros"
    ],
    "properties": {
     "approved": {
      "type": "integer",
      "minimum": 0
     },
     "billable_decisions": {
      "type": "integer",
      "description": "Items that consumed a billable outcome.",
      "minimum": 0
     },
     "denied": {
      "type": "integer",
      "minimum": 0
     },
     "errored": {
      "type": "integer",
      "minimum": 0
     },
     "refused": {
      "type": "integer",
      "minimum": 0
     },
     "total": {
      "type": "integer",
      "minimum": 0
     },
     "total_cost_micros": {
      "type": "integer",
      "format": "int64",
      "description": "Aggregate charge for the batch, in microdollars.",
      "minimum": 0
     }
    }
   },
   "BeliefHistoryResponse": {
    "type": "object",
    "description": "History of belief revisions",
    "required": [
     "proposition",
     "events"
    ],
    "properties": {
     "events": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/RevisionEventResponse"
      }
     },
     "proposition": {
      "type": "string"
     }
    }
   },
   "BeliefResponse": {
    "type": "object",
    "description": "Response for a belief",
    "required": [
     "proposition",
     "confidence",
     "belief_interval",
     "uncertainty",
     "is_certain",
     "is_rejected"
    ],
    "properties": {
     "belief_interval": {
      "type": "array",
      "items": {
       "allOf": [
        {
         "type": "number",
         "format": "float"
        },
        {
         "type": "number",
         "format": "float"
        }
       ]
      }
     },
     "confidence": {
      "type": "number",
      "format": "float"
     },
     "is_certain": {
      "type": "boolean"
     },
     "is_rejected": {
      "type": "boolean"
     },
     "proposition": {
      "type": "string"
     },
     "uncertainty": {
      "type": "number",
      "format": "float"
     }
    }
   },
   "BeliefSummary": {
    "type": "object",
    "description": "Summary of a belief for listing",
    "required": [
     "proposition",
     "confidence",
     "is_certain"
    ],
    "properties": {
     "confidence": {
      "type": "number",
      "format": "float"
     },
     "is_certain": {
      "type": "boolean"
     },
     "proposition": {
      "type": "string"
     }
    }
   },
   "BranchThoughtsRequest": {
    "type": "object",
    "description": "Request to branch thoughts",
    "required": [
     "parent_id",
     "children"
    ],
    "properties": {
     "children": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ThoughtChild"
      },
      "description": "Children (content, score) pairs"
     },
     "parent_id": {
      "type": "integer",
      "description": "Parent thought ID",
      "minimum": 0
     }
    },
    "example": {
     "children": [
      {
       "content": "Apply rule: walk -> WALK",
       "score": 0.9
      },
      {
       "content": "Apply rule: twice -> repeat 2x",
       "score": 0.8
      },
      {
       "content": "Apply composition operator",
       "score": 0.7
      }
     ],
     "parent_id": 0
    }
   },
   "Calibration": {
    "type": "object",
    "description": "The reliability curve for an org: how well reported confidence predicts\nreal-world honored rate.",
    "required": [
     "labeled_approvals",
     "expected_calibration_error",
     "bins"
    ],
    "properties": {
     "bins": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/CalibrationBin"
      },
      "description": "Populated confidence buckets, ascending."
     },
     "expected_calibration_error": {
      "type": "number",
      "format": "double",
      "description": "Expected Calibration Error in [0, 1]; 0 = perfectly calibrated."
     },
     "labeled_approvals": {
      "type": "integer",
      "description": "Approved decisions in the window with a recorded outcome (the sample).",
      "minimum": 0
     }
    }
   },
   "CalibrationBin": {
    "type": "object",
    "description": "One confidence bucket of the reliability curve.",
    "required": [
     "confidence_low",
     "confidence_high",
     "approvals",
     "honored",
     "honored_rate"
    ],
    "properties": {
     "approvals": {
      "type": "integer",
      "description": "Approved decisions in this bucket that have a recorded outcome.",
      "minimum": 0
     },
     "confidence_high": {
      "type": "number",
      "format": "double"
     },
     "confidence_low": {
      "type": "number",
      "format": "double"
     },
     "honored": {
      "type": "integer",
      "description": "How many of them were `honored`.",
      "minimum": 0
     },
     "honored_rate": {
      "type": "number",
      "format": "double",
      "description": "`honored / approvals` \u2014 should track the bucket's confidence midpoint\nwhen the engine is well-calibrated."
     }
    }
   },
   "CancelJobResponse": {
    "type": "object",
    "description": "Cancel job response",
    "required": [
     "job_id",
     "cancelled",
     "message"
    ],
    "properties": {
     "cancelled": {
      "type": "boolean",
      "description": "Whether cancellation was successful"
     },
     "job_id": {
      "type": "string",
      "description": "Job identifier"
     },
     "message": {
      "type": "string",
      "description": "Message"
     }
    }
   },
   "CanonicalSandboxAction": {
    "oneOf": [
     {
      "type": "object",
      "required": [
       "type"
      ],
      "properties": {
       "desktop_os": {
        "type": "string",
        "nullable": true
       },
       "image": {
        "type": "string",
        "nullable": true
       },
       "isolation": {
        "type": "string",
        "nullable": true
       },
       "timeout_seconds": {
        "type": "integer",
        "format": "int64",
        "nullable": true,
        "minimum": 0
       },
       "type": {
        "type": "string",
        "enum": [
         "create_sandbox"
        ]
       }
      }
     },
     {
      "type": "object",
      "required": [
       "command",
       "shell_mode",
       "env_keys",
       "type"
      ],
      "properties": {
       "command": {
        "type": "array",
        "items": {
         "type": "string"
        }
       },
       "env_keys": {
        "type": "array",
        "items": {
         "type": "string"
        }
       },
       "shell_mode": {
        "type": "boolean"
       },
       "type": {
        "type": "string",
        "enum": [
         "execute_command"
        ]
       },
       "working_dir": {
        "type": "string",
        "nullable": true
       }
      }
     },
     {
      "type": "object",
      "required": [
       "paths",
       "type"
      ],
      "properties": {
       "paths": {
        "type": "array",
        "items": {
         "type": "string"
        }
       },
       "type": {
        "type": "string",
        "enum": [
         "write_files"
        ]
       }
      }
     },
     {
      "type": "object",
      "required": [
       "path",
       "type"
      ],
      "properties": {
       "path": {
        "type": "string"
       },
       "type": {
        "type": "string",
        "enum": [
         "read_file"
        ]
       }
      }
     },
     {
      "type": "object",
      "required": [
       "path",
       "recursive",
       "type"
      ],
      "properties": {
       "path": {
        "type": "string"
       },
       "recursive": {
        "type": "boolean"
       },
       "type": {
        "type": "string",
        "enum": [
         "list_files"
        ]
       }
      }
     },
     {
      "type": "object",
      "required": [
       "path",
       "recursive",
       "type"
      ],
      "properties": {
       "path": {
        "type": "string"
       },
       "recursive": {
        "type": "boolean"
       },
       "type": {
        "type": "string",
        "enum": [
         "delete_file"
        ]
       }
      }
     },
     {
      "type": "object",
      "required": [
       "source",
       "destination",
       "type"
      ],
      "properties": {
       "destination": {
        "type": "string"
       },
       "source": {
        "type": "string"
       },
       "type": {
        "type": "string",
        "enum": [
         "move_file"
        ]
       }
      }
     },
     {
      "type": "object",
      "required": [
       "source",
       "destination",
       "recursive",
       "type"
      ],
      "properties": {
       "destination": {
        "type": "string"
       },
       "recursive": {
        "type": "boolean"
       },
       "source": {
        "type": "string"
       },
       "type": {
        "type": "string",
        "enum": [
         "copy_file"
        ]
       }
      }
     },
     {
      "type": "object",
      "required": [
       "path",
       "recursive",
       "type"
      ],
      "properties": {
       "path": {
        "type": "string"
       },
       "recursive": {
        "type": "boolean"
       },
       "type": {
        "type": "string",
        "enum": [
         "make_dir"
        ]
       }
      }
     },
     {
      "type": "object",
      "required": [
       "type"
      ],
      "properties": {
       "language": {
        "type": "string",
        "nullable": true
       },
       "session_id": {
        "type": "string",
        "nullable": true
       },
       "type": {
        "type": "string",
        "enum": [
         "repl_execute"
        ]
       }
      }
     },
     {
      "type": "object",
      "required": [
       "kind",
       "type"
      ],
      "properties": {
       "kind": {
        "$ref": "#/components/schemas/GuiActionKind"
       },
       "type": {
        "type": "string",
        "enum": [
         "gui_action"
        ]
       }
      }
     },
     {
      "type": "object",
      "required": [
       "name",
       "command",
       "args",
       "type"
      ],
      "properties": {
       "args": {
        "type": "array",
        "items": {
         "type": "string"
        }
       },
       "command": {
        "type": "string"
       },
       "name": {
        "type": "string"
       },
       "port": {
        "type": "integer",
        "format": "int32",
        "nullable": true,
        "minimum": 0
       },
       "type": {
        "type": "string",
        "enum": [
         "mcp_start"
        ]
       }
      }
     },
     {
      "type": "object",
      "required": [
       "name",
       "type"
      ],
      "properties": {
       "name": {
        "type": "string"
       },
       "type": {
        "type": "string",
        "enum": [
         "mcp_stop"
        ]
       }
      }
     },
     {
      "type": "object",
      "required": [
       "name",
       "tool",
       "type"
      ],
      "properties": {
       "name": {
        "type": "string"
       },
       "tool": {
        "type": "string"
       },
       "type": {
        "type": "string",
        "enum": [
         "mcp_invoke"
        ]
       }
      }
     },
     {
      "type": "object",
      "required": [
       "type"
      ],
      "properties": {
       "type": {
        "type": "string",
        "enum": [
         "answer_only"
        ]
       }
      }
     }
    ],
    "discriminator": {
     "propertyName": "type"
    }
   },
   "CategoryMatch": {
    "type": "object",
    "required": [
     "category",
     "score",
     "domain",
     "intent",
     "matching_rules"
    ],
    "properties": {
     "category": {
      "type": "string"
     },
     "domain": {
      "type": "string"
     },
     "intent": {
      "type": "string"
     },
     "matching_rules": {
      "type": "integer",
      "minimum": 0
     },
     "score": {
      "type": "number",
      "format": "double"
     }
    }
   },
   "ChatActionExecutionRequest": {
    "type": "object",
    "required": [
     "action_types_to_execute"
    ],
    "properties": {
     "action_types_to_execute": {
      "type": "array",
      "items": {
       "type": "string"
      }
     }
    }
   },
   "ChatCompletion": {
    "type": "object",
    "required": [
     "reply",
     "summary",
     "grounded",
     "needs_human_review",
     "tool_calls",
     "suggested_actions",
     "action_results",
     "validation",
     "recursion_trace",
     "grounding",
     "evidence",
     "generation"
    ],
    "properties": {
     "action_results": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ActionExecutionResult"
      },
      "description": "Results from executing ready actions against available adapters."
     },
     "clarifying_question": {
      "type": "string",
      "description": "Optional clarifying question when confidence is limited.",
      "nullable": true
     },
     "evidence": {
      "$ref": "#/components/schemas/GroundingEvidence"
     },
     "execution_receipt": {
      "allOf": [
       {
        "$ref": "#/components/schemas/ChatExecutionReceipt"
       }
      ],
      "nullable": true
     },
     "generation": {
      "$ref": "#/components/schemas/CompletionGeneration"
     },
     "grounded": {
      "type": "boolean",
      "description": "Whether the reply is grounded in matched rules/context rather than pure guesswork."
     },
     "grounding": {
      "$ref": "#/components/schemas/GroundingSnapshot"
     },
     "needs_human_review": {
      "type": "boolean",
      "description": "Whether a human review or warm handoff is recommended."
     },
     "recursion_trace": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/RecursiveTraceStep"
      },
      "description": "Recursive perceive/plan/respond/critique trace."
     },
     "reply": {
      "type": "string",
      "description": "Final customer-facing reply."
     },
     "suggested_actions": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/SuggestedAction"
      },
      "description": "Structured next actions for downstream tooling/UI."
     },
     "summary": {
      "type": "string",
      "description": "Short summary of what the recursive model inferred."
     },
     "tool_calls": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ToolCall"
      },
      "description": "Structured tool calls derived from org rules and detected context.\nEach tool call has a function name, arguments, and the policy justification."
     },
     "validation": {
      "$ref": "#/components/schemas/ChatValidation"
     }
    }
   },
   "ChatExecutionReceipt": {
    "type": "object",
    "required": [
     "receipt_id",
     "expires_at",
     "available_action_types"
    ],
    "properties": {
     "available_action_types": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "expires_at": {
      "type": "string"
     },
     "receipt_id": {
      "type": "string"
     }
    }
   },
   "ChatMessage": {
    "type": "object",
    "description": "A message in the chat conversation",
    "required": [
     "role",
     "content"
    ],
    "properties": {
     "content": {
      "type": "string"
     },
     "role": {
      "type": "string"
     }
    }
   },
   "ChatRequest": {
    "type": "object",
    "required": [
     "message"
    ],
    "properties": {
     "action_types_to_execute": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Optional action types to execute when action execution is enabled.",
      "nullable": true
     },
     "execute_ready_actions": {
      "type": "boolean",
      "description": "Execute ready chat actions against the org-scoped KB adapters. Defaults to true.",
      "nullable": true
     },
     "history": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ChatMessage"
      },
      "description": "Conversation history for contextual follow-ups.",
      "nullable": true
     },
     "max_recursive_steps": {
      "type": "integer",
      "description": "Recursive completion passes to run. Clamped to 1..=4, default 4.",
      "nullable": true,
      "minimum": 0
     },
     "message": {
      "type": "string",
      "description": "The customer message to analyze and respond to."
     },
     "org_id": {
      "type": "string",
      "description": "Deprecated compatibility field. Org scope comes from auth/session.",
      "nullable": true
     },
     "session_id": {
      "type": "string",
      "description": "Optional server-side session for conversation continuity and audit history.",
      "nullable": true
     }
    }
   },
   "ChatResponse": {
    "type": "object",
    "required": [
     "analysis",
     "guidelines",
     "completion",
     "messages"
    ],
    "properties": {
     "analysis": {
      "$ref": "#/components/schemas/SymbolicAnalysis"
     },
     "completion": {
      "$ref": "#/components/schemas/ChatCompletion"
     },
     "guidelines": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Guideline"
      },
      "description": "Suggested response guidelines based on fired rules."
     },
     "messages": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ChatMessage"
      },
      "description": "Conversation history including the new user turn and assistant reply."
     },
     "session_id": {
      "type": "string",
      "description": "Optional session ID used to ground or persist this exchange.",
      "nullable": true
     }
    }
   },
   "ChatValidation": {
    "type": "object",
    "required": [
     "llm_provider",
     "llm_backend_live",
     "grounding_status",
     "grounded_entity_count",
     "cited_rule_count",
     "proof_status",
     "validation_level",
     "action_execution_eligible",
     "action_execution_reason"
    ],
    "properties": {
     "action_execution_eligible": {
      "type": "boolean"
     },
     "action_execution_reason": {
      "type": "string"
     },
     "cited_rule_count": {
      "type": "integer",
      "minimum": 0
     },
     "grounded_entity_count": {
      "type": "integer",
      "minimum": 0
     },
     "grounding_status": {
      "type": "string"
     },
     "llm_backend_live": {
      "type": "boolean"
     },
     "llm_provider": {
      "type": "string"
     },
     "proof_status": {
      "type": "string"
     },
     "validation_level": {
      "type": "string"
     }
    }
   },
   "CheckConflictsRequest": {
    "type": "object",
    "description": "Request to check for conflicting beliefs",
    "required": [
     "prop1",
     "prop2"
    ],
    "properties": {
     "prop1": {
      "type": "string",
      "description": "First proposition"
     },
     "prop2": {
      "type": "string",
      "description": "Second proposition"
     }
    }
   },
   "CircuitBreakerStats": {
    "type": "object",
    "description": "Circuit breaker statistics",
    "required": [
     "state",
     "success_count",
     "failure_count",
     "rejected_count",
     "consecutive_failures",
     "consecutive_successes",
     "time_in_state_secs"
    ],
    "properties": {
     "consecutive_failures": {
      "type": "integer",
      "format": "int32",
      "description": "Consecutive failures in current window",
      "minimum": 0
     },
     "consecutive_successes": {
      "type": "integer",
      "format": "int32",
      "description": "Consecutive successes in half-open state",
      "minimum": 0
     },
     "failure_count": {
      "type": "integer",
      "format": "int64",
      "description": "Total failed calls",
      "minimum": 0
     },
     "rejected_count": {
      "type": "integer",
      "format": "int64",
      "description": "Total rejected calls (circuit open)",
      "minimum": 0
     },
     "state": {
      "type": "string",
      "description": "Current state"
     },
     "success_count": {
      "type": "integer",
      "format": "int64",
      "description": "Total successful calls",
      "minimum": 0
     },
     "time_in_state_secs": {
      "type": "integer",
      "format": "int64",
      "description": "Time since last state change",
      "minimum": 0
     }
    }
   },
   "CompareModelsRequest": {
    "type": "object",
    "description": "Compare models request",
    "required": [
     "checkpoint_a",
     "checkpoint_b"
    ],
    "properties": {
     "checkpoint_a": {
      "type": "string",
      "description": "First checkpoint ID"
     },
     "checkpoint_b": {
      "type": "string",
      "description": "Second checkpoint ID"
     }
    }
   },
   "CompileRequest": {
    "type": "object",
    "description": "Request for compiling a query",
    "required": [
     "query"
    ],
    "properties": {
     "execute": {
      "type": "boolean",
      "nullable": true
     },
     "query": {
      "type": "string"
     }
    }
   },
   "CompileResponse": {
    "type": "object",
    "description": "Response from the compiler",
    "required": [
     "ir",
     "plan",
     "stats"
    ],
    "properties": {
     "bindings": {
      "type": "array",
      "items": {
       "type": "object",
       "additionalProperties": {
        "type": "string"
       }
      },
      "nullable": true
     },
     "evidence": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Evidence"
      },
      "nullable": true
     },
     "ir": {},
     "plan": {},
     "stats": {
      "$ref": "#/components/schemas/CompilerStats"
     }
    }
   },
   "CompilerStats": {
    "type": "object",
    "description": "Compilation statistics",
    "required": [
     "tokenize_us",
     "parse_us",
     "type_check_us",
     "plan_us",
     "execute_us",
     "total_us",
     "bindings_found"
    ],
    "properties": {
     "bindings_found": {
      "type": "integer",
      "minimum": 0
     },
     "execute_us": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "parse_us": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "plan_us": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "tokenize_us": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "total_us": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "type_check_us": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     }
    }
   },
   "CompletionGeneration": {
    "type": "object",
    "required": [
     "mode"
    ],
    "properties": {
     "fallback_reason": {
      "type": "string",
      "description": "Populated when the model path failed and the endpoint fell back.",
      "nullable": true
     },
     "mode": {
      "type": "string",
      "description": "`deterministic`, `llm_refined`, or `deterministic_fallback`."
     },
     "model": {
      "type": "string",
      "description": "Configured model name when LLM refinement was attempted.",
      "nullable": true
     },
     "token_usage": {
      "allOf": [
       {
        "$ref": "#/components/schemas/CompletionTokenUsage"
       }
      ],
      "nullable": true
     }
    }
   },
   "CompletionTokenUsage": {
    "type": "object",
    "required": [
     "prompt_tokens",
     "completion_tokens",
     "total_tokens"
    ],
    "properties": {
     "completion_tokens": {
      "type": "integer",
      "format": "int32",
      "minimum": 0
     },
     "prompt_tokens": {
      "type": "integer",
      "format": "int32",
      "minimum": 0
     },
     "total_tokens": {
      "type": "integer",
      "format": "int32",
      "minimum": 0
     }
    }
   },
   "ConfigChange": {
    "type": "object",
    "description": "Configuration change",
    "required": [
     "field",
     "value_a",
     "value_b"
    ],
    "properties": {
     "field": {
      "type": "string",
      "description": "Field that changed"
     },
     "value_a": {
      "type": "string",
      "description": "Value in checkpoint A"
     },
     "value_b": {
      "type": "string",
      "description": "Value in checkpoint B"
     }
    }
   },
   "ConflictsResponse": {
    "type": "object",
    "description": "Response for conflict check",
    "required": [
     "prop1",
     "prop2",
     "conflicts",
     "explanation"
    ],
    "properties": {
     "conflicts": {
      "type": "boolean"
     },
     "explanation": {
      "type": "string"
     },
     "prop1": {
      "type": "string"
     },
     "prop2": {
      "type": "string"
     }
    }
   },
   "ConnectThoughtsRequest": {
    "type": "object",
    "description": "Request to connect thoughts",
    "required": [
     "from_id",
     "to_id"
    ],
    "properties": {
     "from_id": {
      "type": "integer",
      "description": "Source thought ID",
      "minimum": 0
     },
     "to_id": {
      "type": "integer",
      "description": "Target thought ID",
      "minimum": 0
     }
    }
   },
   "ConstraintResponse": {
    "type": "object",
    "description": "Response for a single constraint",
    "required": [
     "id",
     "description",
     "strength",
     "expression",
     "source"
    ],
    "properties": {
     "description": {
      "type": "string"
     },
     "expression": {
      "type": "string"
     },
     "id": {
      "type": "string"
     },
     "source": {
      "type": "string"
     },
     "strength": {
      "$ref": "#/components/schemas/ConstraintStrengthRequest"
     }
    }
   },
   "ConstraintStrengthRequest": {
    "oneOf": [
     {
      "type": "object",
      "required": [
       "type"
      ],
      "properties": {
       "type": {
        "type": "string",
        "enum": [
         "hard"
        ]
       }
      }
     },
     {
      "type": "object",
      "description": "Soft constraint - violation causes confidence penalty",
      "required": [
       "tolerance",
       "type"
      ],
      "properties": {
       "tolerance": {
        "type": "number",
        "format": "float"
       },
       "type": {
        "type": "string",
        "enum": [
         "soft"
        ]
       }
      }
     },
     {
      "type": "object",
      "description": "Weighted constraint - contributes to optimization score",
      "required": [
       "weight",
       "type"
      ],
      "properties": {
       "type": {
        "type": "string",
        "enum": [
         "weighted"
        ]
       },
       "weight": {
        "type": "number",
        "format": "float"
       }
      }
     }
    ],
    "description": "Constraint strength in request format",
    "discriminator": {
     "propertyName": "type"
    }
   },
   "ConstraintViolationDiffItem": {
    "type": "object",
    "required": [
     "constraint_id",
     "constraint_name",
     "severity",
     "message",
     "entities",
     "entity_names"
    ],
    "properties": {
     "constraint_id": {
      "type": "string"
     },
     "constraint_name": {
      "type": "string"
     },
     "details": {
      "type": "string",
      "nullable": true
     },
     "entities": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "entity_names": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "message": {
      "type": "string"
     },
     "severity": {
      "type": "string"
     }
    }
   },
   "ConstraintViolationDiffSection": {
    "type": "object",
    "required": [
     "introduced",
     "resolved"
    ],
    "properties": {
     "introduced": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ConstraintViolationDiffItem"
      }
     },
     "resolved": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ConstraintViolationDiffItem"
      }
     }
    }
   },
   "ConstraintViolationResponse": {
    "type": "object",
    "description": "A single constraint violation",
    "required": [
     "constraint_id",
     "satisfied",
     "is_hard",
     "confidence_penalty",
     "explanation"
    ],
    "properties": {
     "confidence_penalty": {
      "type": "number",
      "format": "float"
     },
     "constraint_id": {
      "type": "string"
     },
     "explanation": {
      "type": "string"
     },
     "is_hard": {
      "type": "boolean"
     },
     "satisfied": {
      "type": "boolean"
     }
    }
   },
   "Conversation": {
    "type": "object",
    "description": "A conversation as returned by the API.",
    "required": [
     "id",
     "tenant_id",
     "title",
     "workflow_id",
     "metadata",
     "created_at",
     "updated_at"
    ],
    "properties": {
     "archived_at": {
      "type": "string",
      "description": "Archive timestamp (RFC3339), if soft-deleted",
      "nullable": true
     },
     "created_at": {
      "type": "string",
      "description": "Creation timestamp (RFC3339)"
     },
     "id": {
      "type": "string",
      "description": "Unique conversation ID"
     },
     "metadata": {
      "description": "Arbitrary metadata"
     },
     "session_id": {
      "type": "string",
      "description": "Linked reasoning session ID",
      "nullable": true
     },
     "tenant_id": {
      "type": "string",
      "description": "Tenant (organization) that owns this conversation"
     },
     "title": {
      "type": "string",
      "description": "Human-readable title"
     },
     "updated_at": {
      "type": "string",
      "description": "Last update timestamp (RFC3339)"
     },
     "user_id": {
      "type": "string",
      "description": "Optional user who created the conversation",
      "nullable": true
     },
     "workflow_id": {
      "type": "string",
      "description": "Workflow ID controlling agent behavior"
     }
    }
   },
   "ConversationListResponse": {
    "type": "object",
    "description": "Paginated list of conversations.",
    "required": [
     "conversations",
     "total",
     "has_more"
    ],
    "properties": {
     "conversations": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Conversation"
      },
      "description": "Page of conversations"
     },
     "has_more": {
      "type": "boolean",
      "description": "Whether more conversations exist beyond this page"
     },
     "total": {
      "type": "integer",
      "description": "Total number of matching conversations",
      "minimum": 0
     }
    }
   },
   "ConversationMessage": {
    "type": "object",
    "description": "A single message within a conversation.",
    "required": [
     "id",
     "conversation_id",
     "role",
     "content",
     "created_at"
    ],
    "properties": {
     "analysis": {
      "description": "Optional analysis payload from NSR",
      "nullable": true
     },
     "completion": {
      "description": "Optional completion metadata",
      "nullable": true
     },
     "content": {
      "type": "string",
      "description": "Message text content"
     },
     "conversation_id": {
      "type": "string",
      "description": "Parent conversation ID"
     },
     "created_at": {
      "type": "string",
      "description": "Message creation timestamp (RFC3339)"
     },
     "id": {
      "type": "integer",
      "format": "int64",
      "description": "Auto-increment message ID"
     },
     "role": {
      "type": "string",
      "description": "Message role: user, assistant, or system"
     },
     "token_usage": {
      "description": "Optional token usage breakdown",
      "nullable": true
     }
    }
   },
   "ConversationWithMessages": {
    "type": "object",
    "description": "A conversation together with all its messages.",
    "required": [
     "conversation",
     "messages"
    ],
    "properties": {
     "conversation": {
      "$ref": "#/components/schemas/Conversation"
     },
     "messages": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ConversationMessage"
      },
      "description": "Messages ordered by creation time"
     }
    }
   },
   "CountTokensResponse": {
    "type": "object",
    "required": [
     "input_tokens"
    ],
    "properties": {
     "input_tokens": {
      "type": "integer",
      "format": "int32",
      "minimum": 0
     }
    }
   },
   "CreateCheckoutRequest": {
    "type": "object",
    "required": [
     "price_id",
     "success_url",
     "cancel_url"
    ],
    "properties": {
     "cancel_url": {
      "type": "string",
      "description": "URL to redirect to if the customer cancels"
     },
     "price_id": {
      "type": "string",
      "description": "Stripe Price ID to subscribe to (e.g. `price_1Abc...`)"
     },
     "success_url": {
      "type": "string",
      "description": "URL to redirect to after successful checkout"
     }
    }
   },
   "CreateCheckoutResponse": {
    "type": "object",
    "required": [
     "checkout_url"
    ],
    "properties": {
     "checkout_url": {
      "type": "string",
      "description": "Full Stripe Checkout URL to redirect the customer to"
     }
    }
   },
   "CreateConstraintRequest": {
    "type": "object",
    "description": "Request to create a constraint",
    "required": [
     "id",
     "description",
     "strength",
     "expression"
    ],
    "properties": {
     "description": {
      "type": "string",
      "description": "Human-readable description"
     },
     "expression": {
      "type": "string",
      "description": "Logical expression in NSR-L syntax"
     },
     "id": {
      "type": "string",
      "description": "Unique constraint identifier"
     },
     "source": {
      "type": "string",
      "description": "Source of the constraint",
      "nullable": true
     },
     "strength": {
      "$ref": "#/components/schemas/ConstraintStrengthRequest"
     }
    },
    "example": {
     "description": "Cannot ship before payment received",
     "expression": "shipped(X) -> paid(X)",
     "id": "ship_after_payment",
     "source": "domain_rule",
     "strength": {
      "type": "hard"
     }
    }
   },
   "CreateConversationRequest": {
    "type": "object",
    "description": "Create a new conversation.",
    "properties": {
     "metadata": {
      "description": "Optional metadata object",
      "nullable": true
     },
     "title": {
      "type": "string",
      "description": "Optional title (defaults to \"New chat\")",
      "nullable": true
     },
     "workflow_id": {
      "type": "string",
      "description": "Optional workflow ID (defaults to \"support_concierge\")",
      "nullable": true
     }
    }
   },
   "CreateCreditCheckoutRequest": {
    "type": "object",
    "required": [
     "amount_dollars",
     "success_url",
     "cancel_url"
    ],
    "properties": {
     "amount_dollars": {
      "type": "number",
      "format": "double",
      "description": "Dollar amount of prepaid credits to purchase."
     },
     "cancel_url": {
      "type": "string",
      "description": "URL to redirect to if the customer cancels."
     },
     "success_url": {
      "type": "string",
      "description": "URL to redirect to after successful checkout."
     }
    }
   },
   "CreateCreditCheckoutResponse": {
    "type": "object",
    "required": [
     "checkout_url",
     "amount_cents",
     "estimated_outcomes"
    ],
    "properties": {
     "amount_cents": {
      "type": "integer",
      "format": "int64",
      "description": "Purchased amount in cents."
     },
     "checkout_url": {
      "type": "string",
      "description": "Full Stripe Checkout URL to redirect the customer to"
     },
     "estimated_outcomes": {
      "type": "integer",
      "format": "int64",
      "description": "Approximate number of outcomes this credit amount can cover.",
      "minimum": 0
     }
    }
   },
   "CreateEntityRequest": {
    "type": "object",
    "required": [
     "name",
     "entity_type"
    ],
    "properties": {
     "entity_type": {
      "type": "string",
      "description": "Type of entity (concept, instance, class, relation, predicate)"
     },
     "name": {
      "type": "string",
      "description": "Name of the entity"
     },
     "properties": {
      "type": "object",
      "description": "Optional properties as key-value pairs",
      "additionalProperties": {},
      "nullable": true
     }
    }
   },
   "CreateEvidenceRequest": {
    "type": "object",
    "required": [
     "claim"
    ],
    "properties": {
     "claim": {
      "type": "string"
     },
     "compute_embedding": {
      "type": "boolean",
      "nullable": true
     },
     "confidence": {
      "type": "number",
      "format": "float",
      "nullable": true
     },
     "depends_on": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "nullable": true
     },
     "embedding": {
      "type": "array",
      "items": {
       "type": "number",
       "format": "float"
      },
      "nullable": true
     },
     "evidence_type": {
      "allOf": [
       {
        "$ref": "#/components/schemas/EvidenceType"
       }
      ],
      "nullable": true
     },
     "id": {
      "type": "string",
      "nullable": true
     },
     "source": {
      "allOf": [
       {
        "$ref": "#/components/schemas/EvidenceSourceMeta"
       }
      ],
      "nullable": true
     },
     "timestamp": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "CreateFileRequest": {
    "type": "object",
    "required": [
     "filename"
    ],
    "properties": {
     "content": {
      "type": "string",
      "nullable": true
     },
     "content_base64": {
      "type": "string",
      "nullable": true
     },
     "content_type": {
      "type": "string",
      "nullable": true
     },
     "filename": {
      "type": "string"
     },
     "metadata": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      },
      "nullable": true
     },
     "purpose": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "CreateIngestJobRequest": {
    "type": "object",
    "properties": {
     "compute_embeddings": {
      "type": "boolean",
      "nullable": true
     },
     "file_id": {
      "type": "string",
      "nullable": true
     },
     "input_text": {
      "type": "string",
      "nullable": true
     },
     "metadata": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      },
      "nullable": true
     },
     "source_locator": {
      "type": "string",
      "nullable": true
     },
     "source_type": {
      "type": "string",
      "nullable": true
     },
     "structured": {
      "allOf": [
       {
        "$ref": "#/components/schemas/StructuredIngestPayload"
       }
      ],
      "nullable": true
     }
    }
   },
   "CreateMacroRequest": {
    "type": "object",
    "required": [
     "name",
     "body"
    ],
    "properties": {
     "auto_send": {
      "type": "boolean",
      "nullable": true
     },
     "body": {
      "type": "string",
      "description": "The text sent to the customer. `{{slot}}` marks a merge field."
     },
     "channel": {
      "type": "string",
      "nullable": true
     },
     "name": {
      "type": "string",
      "description": "Unique within the org. Re-posting a name REPLACES that macro."
     },
     "rule_name": {
      "type": "string",
      "nullable": true
     },
     "source": {
      "type": "string",
      "nullable": true
     },
     "status": {
      "allOf": [
       {
        "$ref": "#/components/schemas/MacroStatus"
       }
      ],
      "nullable": true
     },
     "tags": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "nullable": true
     },
     "title": {
      "type": "string"
     },
     "tool": {
      "allOf": [
       {
        "$ref": "#/components/schemas/MacroTool"
       }
      ],
      "nullable": true
     }
    }
   },
   "CreatePortalRequest": {
    "type": "object",
    "required": [
     "return_url"
    ],
    "properties": {
     "return_url": {
      "type": "string",
      "description": "URL to return to after the customer finishes in the portal"
     }
    }
   },
   "CreatePortalResponse": {
    "type": "object",
    "required": [
     "portal_url"
    ],
    "properties": {
     "portal_url": {
      "type": "string",
      "description": "Full Stripe Billing Portal URL"
     }
    }
   },
   "CreateRuleRequest": {
    "type": "object",
    "required": [
     "name",
     "head_predicate",
     "head_args",
     "body"
    ],
    "properties": {
     "body": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/RuleAtomRequest"
      }
     },
     "confidence": {
      "type": "number",
      "format": "float",
      "nullable": true
     },
     "description": {
      "type": "string",
      "nullable": true
     },
     "effect": {
      "allOf": [
       {
        "$ref": "#/components/schemas/RuleEffect"
       }
      ],
      "nullable": true
     },
     "head_args": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "head_predicate": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "test_cases": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/RuleTestCaseRequest"
      },
      "nullable": true
     }
    }
   },
   "CreateSandboxRequest": {
    "type": "object",
    "description": "Request to create an ephemeral sandbox.",
    "properties": {
     "env": {
      "type": "object",
      "description": "Environment variables to inject.",
      "additionalProperties": {
       "type": "string"
      },
      "nullable": true
     },
     "profile": {
      "type": "string",
      "description": "Runtime profile (e.g., \"default\", \"python\", \"node\").",
      "nullable": true
     },
     "timeout_seconds": {
      "type": "integer",
      "format": "int32",
      "description": "Maximum lifetime in seconds (default: 300).",
      "nullable": true,
      "minimum": 0
     }
    }
   },
   "CreateSandboxResponse": {
    "type": "object",
    "description": "Response after creating a sandbox.",
    "required": [
     "sandbox_id",
     "status"
    ],
    "properties": {
     "sandbox_id": {
      "type": "string"
     },
     "status": {
      "type": "string"
     }
    }
   },
   "CreateSourceRequest": {
    "type": "object",
    "required": [
     "source_type",
     "locator"
    ],
    "properties": {
     "locator": {
      "type": "string"
     },
     "metadata": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      },
      "nullable": true
     },
     "snippet": {
      "type": "string",
      "nullable": true
     },
     "source_type": {
      "type": "string"
     },
     "trust_tag": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "CreateTripleRequest": {
    "type": "object",
    "required": [
     "subject_id",
     "predicate",
     "object_id"
    ],
    "properties": {
     "confidence": {
      "type": "number",
      "format": "float",
      "description": "Optional confidence score",
      "nullable": true
     },
     "object_id": {
      "type": "string",
      "description": "Object entity ID"
     },
     "predicate": {
      "type": "string",
      "description": "Predicate/relationship name"
     },
     "subject_id": {
      "type": "string",
      "description": "Subject entity ID"
     },
     "valid_from": {
      "type": "string",
      "description": "Optional RFC3339 start of validity interval.",
      "nullable": true
     },
     "valid_to": {
      "type": "string",
      "description": "Optional RFC3339 end of validity interval (must be >= valid_from).",
      "nullable": true
     }
    }
   },
   "CreateWebhookRequest": {
    "type": "object",
    "required": [
     "url",
     "events"
    ],
    "properties": {
     "description": {
      "type": "string",
      "nullable": true
     },
     "events": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Event slugs to subscribe to. Use `[\"*\"]` for all events."
     },
     "url": {
      "type": "string"
     }
    }
   },
   "CreateWebhookResponse": {
    "type": "object",
    "required": [
     "id",
     "url",
     "events",
     "signing_secret",
     "is_active",
     "created_at",
     "secret_shown_once"
    ],
    "properties": {
     "created_at": {
      "type": "string"
     },
     "description": {
      "type": "string",
      "nullable": true
     },
     "events": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "id": {
      "type": "string"
     },
     "is_active": {
      "type": "boolean"
     },
     "secret_shown_once": {
      "type": "boolean",
      "description": "Redaction warning \u2014 this full secret is shown ONLY at creation."
     },
     "signing_secret": {
      "type": "string"
     },
     "url": {
      "type": "string"
     }
    }
   },
   "DecisionAction": {
    "type": "object",
    "required": [
     "name",
     "ready",
     "rule_name",
     "rule_conclusion",
     "confidence",
     "reason"
    ],
    "properties": {
     "confidence": {
      "type": "number",
      "format": "float"
     },
     "name": {
      "type": "string"
     },
     "ready": {
      "type": "boolean"
     },
     "reason": {
      "type": "string"
     },
     "rule_conclusion": {
      "type": "string"
     },
     "rule_name": {
      "type": "string"
     }
    }
   },
   "DecisionDerivation": {
    "type": "object",
    "required": [
     "steps",
     "replayable"
    ],
    "properties": {
     "authorizing_predicate": {
      "type": "string",
      "description": "The decisive conclusion (declared effect or policy-marker head) the\nverdict stood on.",
      "nullable": true
     },
     "cited_org_rules": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/OrgRuleDefinition"
      },
      "description": "Definitions of cited rules that live in the org knowledge base rather\nthan request scope, so an auditor can read the exact policy the\nverdict stood on even when it cannot be replayed from the request\nalone."
     },
     "org_facts_used": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Org-KB facts that served as premises in the replayed chain \u2014 the\norg-side evidence a third party needs to check the derivation."
     },
     "replayable": {
      "type": "boolean",
      "description": "True when every cited rule fired from the evidence carried in this\nresponse (request facts plus the org facts listed in\n`org_facts_used`), i.e. the whole chain replays from the response."
     },
     "steps": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/DerivationStep"
      },
      "description": "Rule firings in derivation order, restricted to the cited dependency\npath."
     }
    }
   },
   "DecisionGrounding": {
    "type": "object",
    "required": [
     "status",
     "grounded_entity_count",
     "grounded_target_count",
     "cited_rule_count"
    ],
    "properties": {
     "cited_rule_count": {
      "type": "integer",
      "minimum": 0
     },
     "grounded_entity_count": {
      "type": "integer",
      "minimum": 0
     },
     "grounded_target_count": {
      "type": "integer",
      "minimum": 0
     },
     "status": {
      "type": "string"
     }
    }
   },
   "DecisionProof": {
    "type": "object",
    "required": [
     "cited_rules",
     "symbolic_steps",
     "neural_steps",
     "planner_steps",
     "proof_score",
     "proof_status"
    ],
    "properties": {
     "cited_rules": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Org rules cited in the derivation (the audit trail)."
     },
     "derivation": {
      "allOf": [
       {
        "$ref": "#/components/schemas/DecisionDerivation"
       }
      ],
      "nullable": true
     },
     "neural_steps": {
      "type": "integer",
      "minimum": 0
     },
     "planner_steps": {
      "type": "integer",
      "minimum": 0
     },
     "proof_score": {
      "type": "number",
      "format": "double",
      "description": "0\u20131 proof strength from the engine's validation pass."
     },
     "proof_status": {
      "type": "string"
     },
     "request_policy_hash": {
      "type": "string",
      "description": "`sha256:<hex>` over the canonicalized request-scoped facts and rules \u2014\npins this decision to the exact policy inputs it was evaluated\nagainst. Absent when the request carried no inline policy.",
      "nullable": true
     },
     "symbolic_steps": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "DecisionRecord": {
    "type": "object",
    "description": "One analytics row per decided outcome.",
    "required": [
     "timestamp",
     "decision",
     "query",
     "latency_ms",
     "billable",
     "cost_micros",
     "cited_rules",
     "batch"
    ],
    "properties": {
     "batch": {
      "type": "boolean",
      "description": "True when the decision came through `/v1/decisions/batch`."
     },
     "billable": {
      "type": "boolean"
     },
     "cited_rules": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Rule ids cited in the proof chain."
     },
     "confidence": {
      "type": "number",
      "format": "double",
      "description": "The confidence the decision reported, in [0, 1]. Stored so calibration\ncan bucket decisions by what they claimed and compare against what\nactually happened (see `outcome`)."
     },
     "cost_micros": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "decision": {
      "type": "string",
      "description": "`approved | denied | refused`."
     },
     "decision_id": {
      "type": "string",
      "description": "The `decision_id` returned in the API response and carried by the\n`outcome.produced` webhook \u2014 the correlation key for audits."
     },
     "dropped_citations": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Org rules that fired during hydration but were dropped from the proof\nas unrelated \u2014 the audit record of standing-rule noise per decision."
     },
     "external_ref": {
      "type": "string",
      "description": "Optional client-supplied correlation key (their order id, case id, claim\nnumber\u2026). This is what closes the outcome loop from REAL events: a\nchargeback or override webhook knows the order id, not our `decision_id`,\nso `POST /v1/decisions/outcome-by-ref` records the outcome by this key.\n`None` when the caller didn't supply one.",
      "nullable": true
     },
     "latency_ms": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "missing_predicates": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Deduped predicate names from a refused decision's\n`refusal.missing_facts` \u2014 the KB coverage gaps that blocked it. Empty\nfor approvals/denials and safety-gated refusals (which carry none)."
     },
     "outcome": {
      "type": "string",
      "description": "The real-world outcome, recorded AFTER the fact via\n`POST /v1/decisions/{id}/outcome`: `honored` (the decision held up),\n`reversed` (e.g. an approved refund was charged back), `overridden` (a\nhuman changed it), or `escalated`. `None` until reported. This is the\nground truth that turns confidence from a heuristic into a calibrated,\nmeasurable number.",
      "nullable": true
     },
     "query": {
      "type": "string",
      "description": "The decision query, truncated to 200 chars for memory hygiene."
     },
     "request": {
      "allOf": [
       {
        "$ref": "#/components/schemas/DecisionRequestSnapshot"
       }
      ],
      "nullable": true
     },
     "request_policy_hash": {
      "type": "string",
      "description": "`sha256:<hex>` over the request-scoped policy the decision was\nevaluated against (see `DecisionProof::request_policy_hash`) \u2014 lets an\naudit confirm a replay uses the same policy inputs.",
      "nullable": true
     },
     "timestamp": {
      "type": "string",
      "format": "date-time"
     }
    }
   },
   "DecisionRefusal": {
    "type": "object",
    "required": [
     "reason",
     "requires_human_review"
    ],
    "properties": {
     "missing_facts": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/MissingFact"
      },
      "description": "Request-scoped premises that would unblock an authorization proof:\nbody atoms on the dependency path to a positive policy conclusion that\nneither the supplied facts nor any derivable conclusion satisfies.\nEmpty for safety-gated refusals, which must not invite resubmission."
     },
     "reason": {
      "type": "string"
     },
     "requires_human_review": {
      "type": "boolean"
     }
    }
   },
   "DecisionRequest": {
    "type": "object",
    "required": [
     "query"
    ],
    "properties": {
     "action": {
      "type": "string",
      "description": "Optional explicit action being authorized (e.g. \"issue_refund\"). When\npresent, the decision reflects whether *this action* is permitted.",
      "nullable": true
     },
     "authorization_goal": {
      "allOf": [
       {
        "$ref": "#/components/schemas/RecursiveChatPredicateInput"
       }
      ],
      "nullable": true
     },
     "confidence_threshold": {
      "type": "number",
      "format": "double",
      "nullable": true
     },
     "external_ref": {
      "type": "string",
      "description": "Optional client correlation key (their order id, case id, claim number).\nStored on the decision so the real-world outcome can later be recorded\nagainst it via `POST /v1/decisions/outcome-by-ref` \u2014 a chargeback or\noverride webhook knows this id, not our `decision_id`.",
      "nullable": true
     },
     "facts": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/RecursiveChatFactInput"
      },
      "description": "Request-scoped facts injected into the working set.",
      "nullable": true
     },
     "hydrate_org_context": {
      "type": "boolean",
      "description": "When false, skip org knowledge-base hydration (default true).",
      "nullable": true
     },
     "include_trace": {
      "type": "boolean",
      "description": "When true, include the full proof trace and raw engine payload.",
      "nullable": true
     },
     "kb_limits": {
      "allOf": [
       {
        "$ref": "#/components/schemas/RecursiveChatKbLimits"
       }
      ],
      "nullable": true
     },
     "max_depth": {
      "type": "integer",
      "description": "Recursion depth / iteration / confidence overrides.",
      "nullable": true,
      "minimum": 0
     },
     "max_iterations": {
      "type": "integer",
      "nullable": true,
      "minimum": 0
     },
     "mode": {
      "type": "string",
      "description": "Reasoning thoroughness: `fast` | `accurate` | `safe`. Decisions default\nto `safe` (highest verification) since they are accountable outputs.",
      "nullable": true
     },
     "query": {
      "type": "string",
      "description": "The decision question, e.g. \"Can order #A1 be refunded for customer C?\"."
     },
     "rules": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/RecursiveChatRuleInput"
      },
      "description": "Request-scoped rules injected into the working set.",
      "nullable": true
     },
     "session_id": {
      "type": "string",
      "description": "Optional caller session id (carried into the solver).",
      "nullable": true
     }
    }
   },
   "DecisionRequestSnapshot": {
    "type": "object",
    "description": "The reproducible inputs of a decision request \u2014 enough to replay the exact\ndecision. Captured on the record so an auditor can reopen a logged decision\nAS ITSELF: reseed the full request (not just the query) and re-run it. The\nrecord's `request_policy_hash` reveals whether the org policy has changed\nsince, so a replay against different policy is detectable rather than silent.\nOnly the outcome-affecting fields are kept; caller session id and trace flags\nare intentionally omitted.",
    "required": [
     "query"
    ],
    "properties": {
     "action": {
      "type": "string",
      "nullable": true
     },
     "authorization_goal": {
      "allOf": [
       {
        "$ref": "#/components/schemas/RecursiveChatPredicateInput"
       }
      ],
      "nullable": true
     },
     "confidence_threshold": {
      "type": "number",
      "format": "double",
      "nullable": true
     },
     "facts": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/RecursiveChatFactInput"
      },
      "nullable": true
     },
     "hydrate_org_context": {
      "type": "boolean",
      "nullable": true
     },
     "max_depth": {
      "type": "integer",
      "nullable": true,
      "minimum": 0
     },
     "mode": {
      "type": "string",
      "nullable": true
     },
     "query": {
      "type": "string"
     },
     "rules": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/RecursiveChatRuleInput"
      },
      "nullable": true
     }
    }
   },
   "DecisionResponse": {
    "type": "object",
    "required": [
     "decision_id",
     "decision",
     "confidence",
     "rationale",
     "plain_explanation",
     "proof",
     "grounding",
     "gss_machine",
     "usage"
    ],
    "properties": {
     "action": {
      "allOf": [
       {
        "$ref": "#/components/schemas/DecisionAction"
       }
      ],
      "nullable": true
     },
     "confidence": {
      "type": "number",
      "format": "double"
     },
     "decision": {
      "type": "string",
      "description": "`approved` | `denied` | `refused`."
     },
     "decision_id": {
      "type": "string"
     },
     "dropped_citations": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Org rules the engine fired during hydration that were dropped from\n`proof.cited_rules` as unrelated to this decision. Persistently\nnon-empty values mean a standing rule with permanently satisfied\npremises fires on every hydrated decision \u2014 scope or prune it."
     },
     "evaluated_goal": {
      "type": "string",
      "description": "Exact predicate evaluated as the permit target. Absent for legacy\nrequests that relied on action/query inference.",
      "nullable": true
     },
     "grounding": {
      "$ref": "#/components/schemas/DecisionGrounding"
     },
     "gss_machine": {
      "$ref": "#/components/schemas/GssMachineGroundingSnapshot"
     },
     "plain_explanation": {
      "type": "string",
      "description": "Deterministic, proof-derived, business-readable \"why\" \u2014 distinct from\n`rationale` (engine narration): \"Approved to issue a refund for order\n9412: the return for order 9412 was received and order 9412 passed\ninspection.\" Always present."
     },
     "proof": {
      "$ref": "#/components/schemas/DecisionProof"
     },
     "rationale": {
      "type": "string"
     },
     "refusal": {
      "allOf": [
       {
        "$ref": "#/components/schemas/DecisionRefusal"
       }
      ],
      "nullable": true
     },
     "trace": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/RecursiveChatTraceStep"
      },
      "description": "Full proof trace, when `include_trace` was set.",
      "nullable": true
     },
     "usage": {
      "$ref": "#/components/schemas/DecisionUsage"
     },
     "verifiable_bundle": {
      "description": "A self-contained, INDEPENDENTLY-VERIFIABLE proof bundle for an approved\ndecision: the exact facts and rules plus a `RuleEngine::backward_chain`\nderivation of the authorization goal, in the `knowledge::ProofBundle`\nwire format. POST it verbatim to `/v1/proofs/verify` (or check it offline\nwith the dependency-light `proof_check`) to confirm the verdict without\ntrusting this server. Present only when the caller declared an\n`authorization_goal` AND the rule engine reproduces the proof; absent\notherwise (the verdict still stands on its own derivation).",
      "nullable": true
     },
     "warnings": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Non-fatal advisories about how the verdict was derived (e.g. the\noutcome rested on predicate-name inference rather than declared rule\neffects). Omitted when empty."
     },
     "x_nsr": {
      "allOf": [
       {
        "$ref": "#/components/schemas/RecursiveChatResponse"
       }
      ],
      "nullable": true
     }
    }
   },
   "DecisionStats": {
    "type": "object",
    "description": "Aggregate stats over a time window.",
    "required": [
     "window_secs",
     "total",
     "approved",
     "denied",
     "refused",
     "billable",
     "total_cost_micros",
     "p50_latency_ms",
     "p95_latency_ms",
     "top_rules"
    ],
    "properties": {
     "approved": {
      "type": "integer",
      "minimum": 0
     },
     "billable": {
      "type": "integer",
      "minimum": 0
     },
     "denied": {
      "type": "integer",
      "minimum": 0
     },
     "p50_latency_ms": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "p95_latency_ms": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "refused": {
      "type": "integer",
      "minimum": 0
     },
     "top_rules": {
      "type": "array",
      "items": {
       "type": "array",
       "items": {
        "allOf": [
         {
          "type": "string"
         },
         {
          "type": "integer",
          "minimum": 0
         }
        ]
       }
      },
      "description": "Most-cited rule ids in the window, descending, max 10."
     },
     "total": {
      "type": "integer",
      "minimum": 0
     },
     "total_cost_micros": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "window_secs": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     }
    }
   },
   "DecisionUsage": {
    "type": "object",
    "required": [
     "billable",
     "outcome_cost_microdollars",
     "billing_tier",
     "elapsed_ms",
     "iterations",
     "max_depth_reached"
    ],
    "properties": {
     "billable": {
      "type": "boolean"
     },
     "billing_tier": {
      "type": "string"
     },
     "elapsed_ms": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "iterations": {
      "type": "integer",
      "minimum": 0
     },
     "max_depth_reached": {
      "type": "integer",
      "minimum": 0
     },
     "outcome_cost_microdollars": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     }
    }
   },
   "DeleteTripleRequest": {
    "type": "object",
    "description": "Request to delete a triple",
    "required": [
     "subject_id",
     "predicate",
     "object_id"
    ],
    "properties": {
     "object_id": {
      "type": "string"
     },
     "predicate": {
      "type": "string"
     },
     "subject_id": {
      "type": "string"
     }
    }
   },
   "DeletedEntityRecord": {
    "type": "object",
    "description": "Deleted record response for API",
    "required": [
     "entity_id",
     "entity_name",
     "entity_type",
     "deleted_at"
    ],
    "properties": {
     "deleted_at": {
      "type": "string"
     },
     "deleted_by": {
      "type": "string",
      "nullable": true
     },
     "entity_id": {
      "type": "string"
     },
     "entity_name": {
      "type": "string"
     },
     "entity_type": {
      "type": "string"
     },
     "reason": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "DeletedRuleRecord": {
    "type": "object",
    "description": "Deleted rule record response",
    "required": [
     "rule_id",
     "rule_name",
     "deleted_at"
    ],
    "properties": {
     "deleted_at": {
      "type": "string"
     },
     "deleted_by": {
      "type": "string",
      "nullable": true
     },
     "reason": {
      "type": "string",
      "nullable": true
     },
     "rule_id": {
      "type": "string"
     },
     "rule_name": {
      "type": "string"
     }
    }
   },
   "DeliveryAttempt": {
    "type": "object",
    "description": "A single delivery attempt \u2014 success or failure \u2014 kept for customer\ndebugging in the ring buffer.",
    "required": [
     "id",
     "endpoint_id",
     "event_id",
     "event_type",
     "attempt",
     "sent_at",
     "duration_ms",
     "succeeded"
    ],
    "properties": {
     "attempt": {
      "type": "integer",
      "format": "int32",
      "minimum": 0
     },
     "duration_ms": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "endpoint_id": {
      "type": "string"
     },
     "error": {
      "type": "string",
      "nullable": true
     },
     "event_id": {
      "type": "string"
     },
     "event_type": {
      "type": "string"
     },
     "id": {
      "type": "string"
     },
     "response_preview": {
      "type": "string",
      "nullable": true
     },
     "sent_at": {
      "type": "string",
      "format": "date-time"
     },
     "status_code": {
      "type": "integer",
      "format": "int32",
      "nullable": true,
      "minimum": 0
     },
     "succeeded": {
      "type": "boolean"
     }
    }
   },
   "DeliveryListResponse": {
    "type": "object",
    "required": [
     "endpoint_id",
     "deliveries",
     "count"
    ],
    "properties": {
     "count": {
      "type": "integer",
      "minimum": 0
     },
     "deliveries": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/DeliveryAttempt"
      }
     },
     "endpoint_id": {
      "type": "string"
     }
    }
   },
   "DemoteNoisyRequest": {
    "type": "object",
    "description": "Request for `POST /api/v1/flywheel/demote-noisy`.",
    "properties": {
     "dry_run": {
      "type": "boolean",
      "description": "Preview only: report what WOULD be demoted without disabling anything.",
      "nullable": true
     },
     "min_noise_ratio": {
      "type": "number",
      "format": "double",
      "description": "Minimum noise ratio to qualify (default 0.9) \u2014 mostly noise.",
      "nullable": true
     },
     "min_sample": {
      "type": "integer",
      "description": "Minimum total observations (cited + noise) before a rule is eligible\n(default 10) \u2014 never demote on thin evidence.",
      "nullable": true,
      "minimum": 0
     },
     "window_secs": {
      "type": "integer",
      "format": "int64",
      "description": "Analytics window in seconds (default 7d, cap 30d).",
      "nullable": true,
      "minimum": 0
     }
    }
   },
   "DemoteNoisyResponse": {
    "type": "object",
    "description": "Response for `POST /api/v1/flywheel/demote-noisy`.",
    "required": [
     "dry_run",
     "evaluated",
     "demoted",
     "flagged_curated"
    ],
    "properties": {
     "demoted": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/DemotedRule"
      },
      "description": "Mined `flywheel:*` rules disabled (reversible; re-enable via PATCH)."
     },
     "dry_run": {
      "type": "boolean"
     },
     "evaluated": {
      "type": "integer",
      "description": "Rules that met the threshold (auto + curated).",
      "minimum": 0
     },
     "flagged_curated": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/DemotionCandidate"
      },
      "description": "Curated/user rules that met the noise threshold but were NOT touched \u2014\nan operator must review these; the system never auto-disables policy."
     }
    }
   },
   "DemotedRule": {
    "type": "object",
    "description": "A rule this call disabled (or, in dry-run, would disable).",
    "required": [
     "rule",
     "rule_id",
     "noise_count",
     "noise_ratio"
    ],
    "properties": {
     "noise_count": {
      "type": "integer",
      "minimum": 0
     },
     "noise_ratio": {
      "type": "number",
      "format": "double"
     },
     "rule": {
      "type": "string"
     },
     "rule_id": {
      "type": "string"
     }
    }
   },
   "DemotionCandidate": {
    "type": "object",
    "description": "A rule whose noise dominates its usage over a sufficient sample \u2014 a\ndemotion candidate.",
    "required": [
     "rule",
     "cited_count",
     "noise_count",
     "noise_ratio",
     "auto_demotable"
    ],
    "properties": {
     "auto_demotable": {
      "type": "boolean",
      "description": "True for mined `flywheel:*` rules (safe to auto-disable); false for\ncurated/user policy (flagged for an operator, never auto-disabled)."
     },
     "cited_count": {
      "type": "integer",
      "minimum": 0
     },
     "noise_count": {
      "type": "integer",
      "minimum": 0
     },
     "noise_ratio": {
      "type": "number",
      "format": "double",
      "description": "`noise / (cited + noise)` at selection time."
     },
     "rule": {
      "type": "string"
     }
    }
   },
   "DependencyStatus": {
    "type": "object",
    "required": [
     "name",
     "healthy"
    ],
    "properties": {
     "healthy": {
      "type": "boolean"
     },
     "latency_ms": {
      "type": "integer",
      "format": "int64",
      "nullable": true,
      "minimum": 0
     },
     "name": {
      "type": "string"
     },
     "note": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "DerivationStep": {
    "type": "object",
    "required": [
     "rule",
     "premises",
     "conclusions"
    ],
    "properties": {
     "conclusions": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "The rule head atoms this firing derived."
     },
     "premises": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "The matched fact atoms that satisfied the rule body."
     },
     "rule": {
      "type": "string"
     }
    }
   },
   "DerivationStepType": {
    "type": "string",
    "enum": [
     "FactRetrieval",
     "RuleApplication",
     "Join",
     "Filter",
     "Projection",
     "Aggregation",
     "NeuralMatch"
    ]
   },
   "DraftedReply": {
    "type": "object",
    "required": [
     "macro_id",
     "macro_name",
     "rule_name",
     "rendered",
     "missing_slots",
     "auto_send"
    ],
    "properties": {
     "auto_send": {
      "type": "boolean",
      "description": "True only when the macro is approved, fully filled, its tool call fully\nbound, and the macro itself armed for auto-send. Anything less is a\ndraft for a human."
     },
     "macro_id": {
      "type": "string"
     },
     "macro_name": {
      "type": "string"
     },
     "missing_slots": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Merge fields with no value supplied. Non-empty blocks sending."
     },
     "rendered": {
      "type": "string"
     },
     "rule_name": {
      "type": "string"
     }
    }
   },
   "EntityDiffItem": {
    "type": "object",
    "required": [
     "id",
     "name",
     "entity_type",
     "org_id"
    ],
    "properties": {
     "entity_type": {
      "type": "string"
     },
     "id": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "org_id": {
      "type": "string"
     }
    }
   },
   "EntityDiffSection": {
    "type": "object",
    "required": [
     "added",
     "removed"
    ],
    "properties": {
     "added": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/EntityDiffItem"
      }
     },
     "removed": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/EntityDiffItem"
      }
     }
    }
   },
   "EntityId": {
    "type": "string",
    "description": "Unique identifier for knowledge base entities"
   },
   "EntityResponse": {
    "type": "object",
    "required": [
     "id",
     "name",
     "entity_type",
     "properties",
     "confidence",
     "has_embedding"
    ],
    "properties": {
     "confidence": {
      "type": "number",
      "format": "float",
      "description": "Confidence score"
     },
     "created_at": {
      "type": "string",
      "description": "Creation timestamp (RFC3339)",
      "nullable": true
     },
     "entity_type": {
      "type": "string",
      "description": "Entity type"
     },
     "has_embedding": {
      "type": "boolean",
      "description": "Whether entity has an embedding vector"
     },
     "id": {
      "type": "string",
      "description": "Unique entity ID"
     },
     "name": {
      "type": "string",
      "description": "Entity name"
     },
     "properties": {
      "type": "object",
      "description": "Entity properties",
      "additionalProperties": {}
     },
     "updated_at": {
      "type": "string",
      "description": "Last update timestamp (RFC3339)",
      "nullable": true
     }
    }
   },
   "ErrorResponse": {
    "type": "object",
    "description": "Standard error envelope for API responses.\n\nAll error responses from the NSR API use this envelope, ensuring clients\ncan handle errors consistently regardless of the endpoint.\n\n# Example\n\n```json\n{\n\"code\": \"not_found\",\n\"message\": \"Entity not found: ent_abc123\",\n\"request_id\": \"req_7f8a9b2c\",\n\"details\": null\n}\n```\n\n# Error Codes\n\n| Code | HTTP Status | Meaning |\n|------|------------|---------|\n| `bad_request` | 400 | Invalid input or parameters |\n| `unauthorized` | 401 | Missing or invalid authentication |\n| `forbidden` | 403 | Insufficient permissions |\n| `not_found` | 404 | Resource does not exist |\n| `conflict` | 409 | State conflict (e.g., duplicate) |\n| `unprocessable_entity` | 422 | Semantically invalid (e.g., payload too large) |\n| `too_many_requests` | 429 | Rate limit exceeded |\n| `internal_error` | 500 | Unexpected server error |\n| `service_unavailable` | 503 | Backend not configured |\n| `request_timeout` | 504 | Request timed out |",
    "required": [
     "code",
     "message"
    ],
    "properties": {
     "code": {
      "type": "string",
      "description": "Stable machine-readable error code (e.g., `\"not_found\"`, `\"bad_request\"`)"
     },
     "details": {
      "description": "Optional structured details for clients (field-level errors, suggestions).\nAlways present in the JSON envelope (`null` when unused).",
      "nullable": true
     },
     "message": {
      "type": "string",
      "description": "Human-friendly error message with context"
     },
     "request_id": {
      "type": "string",
      "description": "Correlation/request ID for tracing (propagated from `X-Request-ID` header).\nAlways present in the JSON envelope (`null` when unavailable) so clients\ncan depend on the key existing \u2014 see ADR-009.",
      "nullable": true
     }
    }
   },
   "EvaluateRequest": {
    "type": "object",
    "required": [
     "examples"
    ],
    "properties": {
     "examples": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ProvisionTrainingExample"
      },
      "description": "Test examples to evaluate the machine on."
     }
    }
   },
   "EvaluateResponse": {
    "type": "object",
    "required": [
     "org_id",
     "accuracy",
     "correct",
     "total"
    ],
    "properties": {
     "accuracy": {
      "type": "number",
      "format": "double"
     },
     "correct": {
      "type": "integer",
      "minimum": 0
     },
     "org_id": {
      "type": "string"
     },
     "total": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "EvaluationDetail": {
    "type": "object",
    "description": "Detail for a single evaluation example",
    "required": [
     "correct",
     "expected"
    ],
    "properties": {
     "correct": {
      "type": "boolean",
      "description": "Whether prediction was correct"
     },
     "expected": {
      "$ref": "#/components/schemas/SemanticValueResponse"
     },
     "interpretation": {
      "type": "string",
      "description": "Interpretation rationale (when available)",
      "nullable": true
     },
     "interpreted_confidence": {
      "type": "number",
      "format": "double",
      "description": "Confidence for the interpreted prediction",
      "nullable": true
     },
     "predicted": {
      "allOf": [
       {
        "$ref": "#/components/schemas/SemanticValueResponse"
       }
      ],
      "nullable": true
     },
     "predicted_interpreted": {
      "allOf": [
       {
        "$ref": "#/components/schemas/SemanticValueResponse"
       }
      ],
      "nullable": true
     }
    }
   },
   "Evidence": {
    "type": "object",
    "description": "Evidence linking an answer to its source facts, rules, and derivation steps",
    "required": [
     "id",
     "claim",
     "sources",
     "derivation",
     "confidence"
    ],
    "properties": {
     "claim": {
      "type": "string",
      "description": "The claim this evidence supports"
     },
     "confidence": {
      "type": "number",
      "format": "float",
      "description": "Overall confidence of the evidence chain"
     },
     "derivation": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/DerivationStep"
      },
      "description": "Derivation steps (rule applications, joins)"
     },
     "id": {
      "type": "string",
      "description": "Unique evidence chain ID"
     },
     "sources": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/EvidenceSource"
      },
      "description": "Source facts that ground this evidence"
     }
    }
   },
   "EvidenceChainResponse": {
    "type": "object",
    "description": "Get evidence by ID with full chain",
    "required": [
     "chain",
     "depth"
    ],
    "properties": {
     "chain": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/EvidenceNode"
      }
     },
     "depth": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "EvidenceNode": {
    "type": "object",
    "description": "An evidence node in the evidence graph",
    "required": [
     "id",
     "claim",
     "evidence_type",
     "confidence",
     "timestamp",
     "depends_on",
     "source"
    ],
    "properties": {
     "claim": {
      "type": "string",
      "description": "The claim or fact this evidence supports"
     },
     "confidence": {
      "type": "number",
      "format": "float",
      "description": "Confidence in this evidence"
     },
     "depends_on": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "IDs of evidence nodes this depends on"
     },
     "embedding": {
      "type": "array",
      "items": {
       "type": "number",
       "format": "float"
      },
      "description": "Optional vector embedding for semantic search.",
      "nullable": true
     },
     "evidence_type": {
      "$ref": "#/components/schemas/EvidenceType"
     },
     "id": {
      "type": "string",
      "description": "Unique node ID"
     },
     "source": {
      "$ref": "#/components/schemas/EvidenceSourceMeta"
     },
     "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp when evidence was recorded"
     }
    }
   },
   "EvidenceResponse": {
    "type": "object",
    "description": "Response wrapper for evidence queries",
    "required": [
     "nodes",
     "total"
    ],
    "properties": {
     "nodes": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/EvidenceNode"
      }
     },
     "total": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "EvidenceSource": {
    "type": "object",
    "description": "A single source of evidence",
    "required": [
     "fact_id",
     "triple",
     "provenance",
     "confidence"
    ],
    "properties": {
     "confidence": {
      "type": "number",
      "format": "float",
      "description": "Confidence of this individual source"
     },
     "fact_id": {
      "type": "string",
      "description": "Triple ID or fact identifier"
     },
     "provenance": {
      "type": "string",
      "description": "Provenance of this fact"
     },
     "triple": {
      "$ref": "#/components/schemas/TripleSummary"
     }
    }
   },
   "EvidenceSourceMeta": {
    "type": "object",
    "description": "Source metadata for evidence",
    "required": [
     "actor",
     "metadata"
    ],
    "properties": {
     "actor": {
      "type": "string",
      "description": "Who/what created this evidence"
     },
     "actor_id": {
      "type": "string",
      "description": "API key or session ID",
      "nullable": true
     },
     "metadata": {
      "type": "object",
      "description": "Free-form metadata",
      "additionalProperties": {
       "type": "string"
      }
     },
     "org_id": {
      "type": "string",
      "description": "Organization",
      "nullable": true
     }
    }
   },
   "EvidenceSourceRecord": {
    "type": "object",
    "description": "A first-class evidence source record.",
    "required": [
     "id",
     "source_type",
     "locator",
     "actor",
     "metadata",
     "created_at",
     "updated_at"
    ],
    "properties": {
     "actor": {
      "type": "string"
     },
     "created_at": {
      "type": "string",
      "format": "date-time"
     },
     "id": {
      "type": "string"
     },
     "locator": {
      "type": "string"
     },
     "metadata": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      }
     },
     "org_id": {
      "type": "string",
      "nullable": true
     },
     "snippet": {
      "type": "string",
      "nullable": true
     },
     "source_type": {
      "type": "string"
     },
     "trust_tag": {
      "type": "string",
      "nullable": true
     },
     "updated_at": {
      "type": "string",
      "format": "date-time"
     }
    }
   },
   "EvidenceStatsResponse": {
    "type": "object",
    "description": "Aggregate stats for an org's evidence graph.",
    "required": [
     "total_nodes"
    ],
    "properties": {
     "total_nodes": {
      "type": "integer",
      "description": "Number of evidence nodes stored for the caller's org.",
      "minimum": 0
     }
    }
   },
   "EvidenceType": {
    "oneOf": [
     {
      "type": "string",
      "description": "Direct assertion by a user or system",
      "enum": [
       "Assertion"
      ]
     },
     {
      "type": "object",
      "required": [
       "Inference"
      ],
      "properties": {
       "Inference": {
        "type": "object",
        "description": "Derived via rule application",
        "required": [
         "rule_id",
         "rule_name"
        ],
        "properties": {
         "rule_id": {
          "type": "string"
         },
         "rule_name": {
          "type": "string"
         }
        }
       }
      }
     },
     {
      "type": "object",
      "required": [
       "NeuralMatch"
      ],
      "properties": {
       "NeuralMatch": {
        "type": "object",
        "description": "Derived via neural similarity",
        "required": [
         "similarity",
         "model_id"
        ],
        "properties": {
         "model_id": {
          "type": "string"
         },
         "similarity": {
          "type": "number",
          "format": "float"
         }
        }
       }
      }
     },
     {
      "type": "object",
      "required": [
       "GraphPath"
      ],
      "properties": {
       "GraphPath": {
        "type": "object",
        "description": "Derived via graph traversal",
        "required": [
         "path_length"
        ],
        "properties": {
         "path_length": {
          "type": "integer",
          "minimum": 0
         }
        }
       }
      }
     },
     {
      "type": "object",
      "required": [
       "Citation"
      ],
      "properties": {
       "Citation": {
        "type": "object",
        "description": "External source citation",
        "properties": {
         "author": {
          "type": "string",
          "nullable": true
         },
         "url": {
          "type": "string",
          "nullable": true
         }
        }
       }
      }
     },
     {
      "type": "object",
      "required": [
       "LLMGenerated"
      ],
      "properties": {
       "LLMGenerated": {
        "type": "object",
        "description": "LLM generation (for RAG)",
        "required": [
         "model",
         "verified"
        ],
        "properties": {
         "model": {
          "type": "string"
         },
         "verified": {
          "type": "boolean"
         }
        }
       }
      }
     }
    ],
    "description": "Types of evidence"
   },
   "ExecuteRequest": {
    "type": "object",
    "description": "Request to execute a command in a sandbox.",
    "required": [
     "sandbox_id",
     "command"
    ],
    "properties": {
     "command": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Command to run (e.g., [\"python3\", \"-c\", \"print('hello')\"])."
     },
     "env": {
      "type": "object",
      "description": "Additional environment variables.",
      "additionalProperties": {
       "type": "string"
      },
      "nullable": true
     },
     "sandbox_id": {
      "type": "string",
      "description": "Sandbox ID to execute in."
     },
     "timeout_seconds": {
      "type": "integer",
      "format": "int32",
      "description": "Execution timeout in seconds (default: 30).",
      "nullable": true,
      "minimum": 0
     },
     "working_dir": {
      "type": "string",
      "description": "Working directory inside the sandbox.",
      "nullable": true
     }
    }
   },
   "ExecuteResponse": {
    "type": "object",
    "description": "Response from executing a command.",
    "required": [
     "execution_id",
     "exit_code",
     "stdout",
     "stderr",
     "duration_ms"
    ],
    "properties": {
     "duration_ms": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "execution_id": {
      "type": "string"
     },
     "exit_code": {
      "type": "integer",
      "format": "int32"
     },
     "stderr": {
      "type": "string"
     },
     "stdout": {
      "type": "string"
     }
    }
   },
   "ExplainRequest": {
    "type": "object",
    "description": "Request for explanation generation",
    "required": [
     "query"
    ],
    "properties": {
     "query": {
      "type": "string",
      "description": "The query to explain"
     },
     "session_id": {
      "type": "string",
      "description": "Session ID for context",
      "nullable": true
     },
     "style": {
      "type": "string",
      "description": "Explanation style: \"symbolic\", \"neural\", \"contrastive\"",
      "nullable": true
     }
    }
   },
   "ExplainResponse": {
    "type": "object",
    "description": "Response for explanation",
    "required": [
     "enabled"
    ],
    "properties": {
     "components": {
      "allOf": [
       {
        "$ref": "#/components/schemas/ExplanationComponents"
       }
      ],
      "nullable": true
     },
     "enabled": {
      "type": "boolean",
      "description": "Whether explainability is enabled"
     },
     "explanation": {
      "type": "string",
      "description": "Human-readable explanation",
      "nullable": true
     }
    }
   },
   "ExplanationComponents": {
    "type": "object",
    "description": "Structured explanation components",
    "required": [
     "perception",
     "syntax",
     "semantics",
     "decision_points"
    ],
    "properties": {
     "decision_points": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Key decision points"
     },
     "perception": {
      "type": "string",
      "description": "Perception explanation"
     },
     "semantics": {
      "type": "string",
      "description": "Semantic computation explanation"
     },
     "syntax": {
      "type": "string",
      "description": "Syntax (parsing) explanation"
     }
    }
   },
   "ExportFormat": {
    "type": "string",
    "description": "Export format",
    "enum": [
     "safe_tensors",
     "json",
     "backup"
    ]
   },
   "ExportModelRequest": {
    "type": "object",
    "description": "Export model request",
    "required": [
     "format"
    ],
    "properties": {
     "checkpoint_id": {
      "type": "string",
      "description": "Checkpoint ID (optional, uses current if not specified)",
      "nullable": true
     },
     "format": {
      "$ref": "#/components/schemas/ExportFormat"
     },
     "include_kb": {
      "type": "boolean",
      "description": "Include knowledge base"
     }
    }
   },
   "ExportModelResponse": {
    "type": "object",
    "description": "Export response",
    "required": [
     "status"
    ],
    "properties": {
     "download_url": {
      "type": "string",
      "description": "Download URL (if ready)",
      "nullable": true
     },
     "job_id": {
      "type": "string",
      "description": "Export job ID (if async)",
      "nullable": true
     },
     "status": {
      "type": "string",
      "description": "Export status"
     }
    }
   },
   "FeaturesResponse": {
    "type": "object",
    "description": "Response listing enabled features",
    "required": [
     "enabled_features",
     "available_features"
    ],
    "properties": {
     "available_features": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "All available features"
     },
     "enabled_features": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "List of enabled features"
     }
    }
   },
   "FeedbackRequest": {
    "type": "object",
    "required": [
     "query",
     "answer",
     "positive"
    ],
    "properties": {
     "answer": {
      "type": "string"
     },
     "comment": {
      "type": "string",
      "nullable": true
     },
     "confidence": {
      "type": "number",
      "format": "float",
      "nullable": true
     },
     "positive": {
      "type": "boolean"
     },
     "query": {
      "type": "string"
     },
     "strategy": {
      "type": "string",
      "nullable": true
     },
     "suggested_rule": {
      "allOf": [
       {
        "$ref": "#/components/schemas/SuggestedRule"
       }
      ],
      "nullable": true
     }
    }
   },
   "FileListResponse": {
    "type": "object",
    "required": [
     "object",
     "data"
    ],
    "properties": {
     "data": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/FileObject"
      }
     },
     "object": {
      "type": "string"
     }
    }
   },
   "FileObject": {
    "type": "object",
    "required": [
     "id",
     "object",
     "bytes",
     "created_at",
     "filename",
     "purpose",
     "status"
    ],
    "properties": {
     "bytes": {
      "type": "integer",
      "minimum": 0
     },
     "content_type": {
      "type": "string",
      "nullable": true
     },
     "created_at": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "filename": {
      "type": "string"
     },
     "id": {
      "type": "string"
     },
     "metadata": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      }
     },
     "object": {
      "type": "string"
     },
     "purpose": {
      "type": "string"
     },
     "status": {
      "type": "string"
     }
    }
   },
   "FlywheelCandidatesResponse": {
    "type": "object",
    "required": [
     "candidates",
     "total"
    ],
    "properties": {
     "candidates": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/PromotionCandidate"
      }
     },
     "total": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "FlywheelEventsResponse": {
    "type": "object",
    "required": [
     "events",
     "total"
    ],
    "properties": {
     "events": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/LearningEvent"
      }
     },
     "total": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "FlywheelProcessResponse": {
    "type": "object",
    "required": [
     "new_candidates",
     "total_new_candidates",
     "stats"
    ],
    "properties": {
     "new_candidates": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/PromotionCandidate"
      }
     },
     "stats": {
      "$ref": "#/components/schemas/FlywheelStats"
     },
     "total_new_candidates": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "FlywheelStats": {
    "type": "object",
    "description": "Flywheel statistics",
    "required": [
     "queued_events",
     "processed_events",
     "pending_candidates",
     "approved_candidates",
     "auto_promoted",
     "rejected_candidates"
    ],
    "properties": {
     "approved_candidates": {
      "type": "integer",
      "minimum": 0
     },
     "auto_promoted": {
      "type": "integer",
      "minimum": 0
     },
     "pending_candidates": {
      "type": "integer",
      "minimum": 0
     },
     "processed_events": {
      "type": "integer",
      "minimum": 0
     },
     "queued_events": {
      "type": "integer",
      "minimum": 0
     },
     "rejected_candidates": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "ForwardChainRequest": {
    "type": "object",
    "description": "Forward chain request with control parameters",
    "properties": {
     "include_details": {
      "type": "boolean",
      "description": "Include full fact details in response (subject, predicate, object)"
     },
     "limit": {
      "type": "integer",
      "description": "Maximum number of results to return (default: 1000)",
      "nullable": true,
      "minimum": 0
     },
     "max_depth": {
      "type": "integer",
      "description": "Maximum depth of rule application (default: config value, max: 100)",
      "nullable": true,
      "minimum": 0
     },
     "max_iterations": {
      "type": "integer",
      "description": "Maximum number of inference iterations (default: config value, max: 10000)",
      "nullable": true,
      "minimum": 0
     },
     "rule_ids": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Optional list of rule IDs to apply (if empty, applies all enabled rules)",
      "nullable": true
     }
    }
   },
   "ForwardChainResponse": {
    "type": "object",
    "description": "Forward chain response",
    "required": [
     "inferred_facts",
     "total_inferred",
     "iterations_used",
     "rules_fired",
     "execution_time_ms"
    ],
    "properties": {
     "execution_time_ms": {
      "type": "integer",
      "format": "int64",
      "description": "Execution time in milliseconds",
      "minimum": 0
     },
     "inferred_facts": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/InferredFactResponse"
      },
      "description": "List of inferred facts"
     },
     "iterations_used": {
      "type": "integer",
      "description": "Number of iterations performed",
      "minimum": 0
     },
     "rules_fired": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Rules that fired during inference"
     },
     "total_inferred": {
      "type": "integer",
      "description": "Total number of facts inferred (before limit)",
      "minimum": 0
     }
    }
   },
   "GraphAnalysisRequest": {
    "type": "object",
    "description": "Request for graph analysis",
    "required": [
     "analysis_type"
    ],
    "properties": {
     "analysis_type": {
      "type": "string",
      "description": "Type of analysis: \"paths\", \"centrality\", \"clusters\""
     },
     "entity_id": {
      "type": "string",
      "description": "Optional entity ID to focus on",
      "nullable": true
     },
     "limit": {
      "type": "integer",
      "description": "Maximum results",
      "nullable": true,
      "minimum": 0
     }
    }
   },
   "GraphOfThoughtsResponse": {
    "type": "object",
    "description": "Response for graph of thoughts status",
    "required": [
     "enabled",
     "thought_count",
     "connection_count",
     "topology"
    ],
    "properties": {
     "connection_count": {
      "type": "integer",
      "description": "Number of connections",
      "minimum": 0
     },
     "enabled": {
      "type": "boolean",
      "description": "Whether GoT is enabled"
     },
     "thought_count": {
      "type": "integer",
      "description": "Number of thoughts in the graph",
      "minimum": 0
     },
     "topology": {
      "type": "string",
      "description": "Topology type"
     }
    }
   },
   "GroundedInputRequest": {
    "oneOf": [
     {
      "type": "object",
      "required": [
       "type",
       "value"
      ],
      "properties": {
       "type": {
        "type": "string",
        "enum": [
         "text"
        ]
       },
       "value": {
        "type": "string",
        "description": "Text input"
       }
      }
     },
     {
      "type": "object",
      "required": [
       "type",
       "value"
      ],
      "properties": {
       "type": {
        "type": "string",
        "enum": [
         "number"
        ]
       },
       "value": {
        "type": "number",
        "format": "double",
        "description": "Numeric input"
       }
      }
     },
     {
      "type": "object",
      "required": [
       "type",
       "value"
      ],
      "properties": {
       "type": {
        "type": "string",
        "enum": [
         "image"
        ]
       },
       "value": {
        "type": "array",
        "items": {
         "type": "number",
         "format": "float"
        },
        "description": "Image input (flat array of pixels)"
       }
      }
     },
     {
      "type": "object",
      "required": [
       "type",
       "value"
      ],
      "properties": {
       "type": {
        "type": "string",
        "enum": [
         "image_with_dims"
        ]
       },
       "value": {
        "type": "object",
        "description": "Image with dimensions",
        "required": [
         "data",
         "width",
         "height",
         "channels"
        ],
        "properties": {
         "channels": {
          "type": "integer",
          "minimum": 0
         },
         "data": {
          "type": "array",
          "items": {
           "type": "number",
           "format": "float"
          }
         },
         "height": {
          "type": "integer",
          "minimum": 0
         },
         "width": {
          "type": "integer",
          "minimum": 0
         }
        }
       }
      }
     },
     {
      "type": "object",
      "required": [
       "type",
       "value"
      ],
      "properties": {
       "type": {
        "type": "string",
        "enum": [
         "embedding"
        ]
       },
       "value": {
        "type": "array",
        "items": {
         "type": "number",
         "format": "float"
        },
        "description": "Vector embedding"
       }
      }
     },
     {
      "type": "object",
      "required": [
       "type",
       "value"
      ],
      "properties": {
       "type": {
        "type": "string",
        "enum": [
         "composite"
        ]
       },
       "value": {
        "type": "array",
        "items": {
         "type": "number",
         "format": "double"
        },
        "description": "Numeric composite symbol, such as a grounded UI node vector."
       }
      }
     }
    ],
    "description": "A single grounded input",
    "discriminator": {
     "propertyName": "type"
    }
   },
   "GroundingEntityEvidence": {
    "type": "object",
    "required": [
     "id",
     "name",
     "entity_type",
     "confidence",
     "score"
    ],
    "properties": {
     "confidence": {
      "type": "number",
      "format": "float"
     },
     "entity_type": {
      "type": "string"
     },
     "id": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "score": {
      "type": "number",
      "format": "double"
     }
    }
   },
   "GroundingEvidence": {
    "type": "object",
    "required": [
     "seed_rules",
     "kb_rules",
     "kb_entities",
     "kb_facts"
    ],
    "properties": {
     "kb_entities": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/GroundingEntityEvidence"
      }
     },
     "kb_facts": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/GroundingFactEvidence"
      }
     },
     "kb_rules": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/SupportingKbRule"
      }
     },
     "seed_rules": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/SupportingSeedRule"
      }
     }
    }
   },
   "GroundingFactEvidence": {
    "type": "object",
    "required": [
     "subject",
     "predicate",
     "object",
     "confidence",
     "provenance",
     "score"
    ],
    "properties": {
     "confidence": {
      "type": "number",
      "format": "float"
     },
     "object": {
      "type": "string"
     },
     "predicate": {
      "type": "string"
     },
     "provenance": {
      "type": "string"
     },
     "score": {
      "type": "number",
      "format": "double"
     },
     "subject": {
      "type": "string"
     }
    }
   },
   "GroundingSnapshot": {
    "type": "object",
    "required": [
     "org_id",
     "history_turns_used",
     "kb_entity_count",
     "kb_rule_count",
     "seed_rule_count",
     "strategy",
     "strategy_reason"
    ],
    "properties": {
     "advanced_reasoning": {
      "allOf": [
       {
        "$ref": "#/components/schemas/AdvancedReasoningSnapshot"
       }
      ],
      "nullable": true
     },
     "history_turns_used": {
      "type": "integer",
      "minimum": 0
     },
     "kb_entity_count": {
      "type": "integer",
      "minimum": 0
     },
     "kb_rule_count": {
      "type": "integer",
      "minimum": 0
     },
     "org_id": {
      "type": "string"
     },
     "seed_rule_count": {
      "type": "integer",
      "minimum": 0
     },
     "strategy": {
      "type": "string"
     },
     "strategy_reason": {
      "type": "string"
     }
    }
   },
   "GssMachineGroundingSnapshot": {
    "type": "object",
    "description": "Grounded Symbol System evidence produced by an actual `NSRMachine`\ninference pass. Decision endpoints expose this separately from the\nrecursive solver proof so callers can audit both reasoning layers.",
    "required": [
     "authority",
     "seed_source",
     "seed_grounded",
     "categories",
     "domains",
     "intents",
     "horn_clauses_fired",
     "safety_gate_triggered",
     "escalation_triggered",
     "classification_confidence",
     "machine_confidence",
     "inferred_symbols"
    ],
    "properties": {
     "authority": {
      "type": "string"
     },
     "categories": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "classification_confidence": {
      "type": "number",
      "format": "double",
      "description": "Confidence of the GSS perception/classification stage."
     },
     "domains": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "escalation_triggered": {
      "type": "boolean"
     },
     "explanation": {
      "type": "string",
      "nullable": true
     },
     "grounded_symbol": {
      "type": "string",
      "description": "Best-aligned canonical symbol under the variance-aware alignment.",
      "nullable": true
     },
     "gss_v3_shadow": {
      "allOf": [
       {
        "$ref": "#/components/schemas/GssV3Shadow"
       }
      ],
      "nullable": true
     },
     "horn_clauses_fired": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "inferred_symbols": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "intents": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "machine_confidence": {
      "type": "number",
      "format": "double",
      "description": "Confidence that NSRMachine recognized and executed the supplied\ngrounded symbols. This is not an end-to-end decision confidence."
     },
     "machine_output": {
      "type": "string",
      "nullable": true
     },
     "machine_state_version": {
      "type": "integer",
      "format": "int64",
      "description": "Chat-mutation version of the org's NSRMachine this decision inferred\nagainst, alongside `request_policy_hash` in spirit: two runs of the\nsame request stamped with the same version had the same machine view;\ndiffering stamps make cross-run drift auditable rather than silent\n(FINDING-nondeterministic-outcome, option 3).",
      "nullable": true,
      "minimum": 0
     },
     "safety_gate_triggered": {
      "type": "boolean"
     },
     "seed_grounded": {
      "type": "boolean"
     },
     "seed_source": {
      "type": "string"
     },
     "symbol_alignment": {
      "type": "number",
      "format": "double",
      "description": "Variance-aware (isotropic Mahalanobis) alignment of the message\ncomposite to that symbol's centroid, in (0,1]: `exp(\u2212d\u00b2/2\u03c3\u00b2)` with \u03c3\u00b2\nthe symbol's learned seed variance. Use this to assess grounding\nuncertainty \u2014 unlike the classification mixture score, it reflects the\nsymbol's observed spread, not lexical overlap.",
      "nullable": true
     }
    }
   },
   "GssSeedInfo": {
    "type": "object",
    "description": "Point-in-time metadata about the live seed pack, for ops observability\n(`GET /api/v1/gss/seed`). Computed once per process.",
    "required": [
     "source",
     "bytes",
     "rules",
     "symbol_vocabulary",
     "horn_clauses",
     "unique_orgs",
     "grounded"
    ],
    "properties": {
     "bytes": {
      "type": "integer",
      "minimum": 0
     },
     "grounded": {
      "type": "boolean",
      "description": "True when the pack parsed and carries at least one rule \u2014 the\n\"grounding is live\" signal that used to fail silently."
     },
     "horn_clauses": {
      "type": "integer",
      "minimum": 0
     },
     "rules": {
      "type": "integer",
      "minimum": 0
     },
     "source": {
      "type": "string",
      "description": "Where the pack was resolved from: `env:NSR_GSS_SEED_PATH`,\n`cwd:data/rules/rules_gss_seed.json`, or `embedded`."
     },
     "symbol_vocabulary": {
      "type": "integer",
      "minimum": 0
     },
     "unique_orgs": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "GssSeedInfoResponse": {
    "allOf": [
     {
      "$ref": "#/components/schemas/GssSeedInfo"
     },
     {
      "type": "object",
      "properties": {
       "v3": {
        "allOf": [
         {
          "$ref": "#/components/schemas/GssSeedV3Info"
         }
        ],
        "nullable": true
       }
      }
     }
    ],
    "description": "Seed-info response: the always-present v2 pack metadata, plus an\noptional `v3` block that only appears once a v3 seed is loaded\n(`skip_serializing_if`, so pre-v3 API consumers see no change)."
   },
   "GssSeedV3Info": {
    "type": "object",
    "description": "Seed-info block surfaced on `GET /api/v1/gss/seed`'s optional `v3` field.",
    "required": [
     "source",
     "bytes",
     "schema_version",
     "symbols",
     "predicates",
     "rules",
     "citable_rules",
     "org_bindings",
     "loaded"
    ],
    "properties": {
     "bytes": {
      "type": "integer",
      "minimum": 0
     },
     "citable_rules": {
      "type": "integer",
      "minimum": 0
     },
     "loaded": {
      "type": "boolean",
      "description": "Always `true` when this block is present; the block itself is\nomitted from the response (`skip_serializing_if`) when no v3 seed\nis loaded, so callers never see `loaded: false`."
     },
     "org_bindings": {
      "type": "integer",
      "minimum": 0
     },
     "predicates": {
      "type": "integer",
      "minimum": 0
     },
     "rules": {
      "type": "integer",
      "minimum": 0
     },
     "schema_version": {
      "type": "string"
     },
     "source": {
      "type": "string",
      "description": "Where the pack was resolved from: `env:NSR_GSS_SEED_V3_PATH` or\n`cwd:data/rules/rules_gss_seed_v3.json`."
     },
     "symbols": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "GssV3Shadow": {
    "type": "object",
    "description": "Shadow-mode v3 grounding observations attached to a decision snapshot\nwhen a v3 seed is loaded. Purely additive; never consulted by decision\nlogic.",
    "required": [
     "matched_symbols",
     "candidate_rules",
     "matched_predicates",
     "org_scoped"
    ],
    "properties": {
     "candidate_rules": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/GssV3ShadowRule"
      }
     },
     "matched_predicates": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "matched_symbols": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/GssV3ShadowSymbolMatch"
      }
     },
     "org_scoped": {
      "type": "boolean",
      "description": "`true` when `candidate_rules` was filtered to rules with an\nACTIVATED `org_bindings` entry for the requesting org. `false` when\nthe org has zero bindings anywhere in the seed (unknown org) and the\nshadow matcher fell back to the unfiltered rulebook. Matched symbols\nare never org-filtered \u2014 they are shared vocabulary by design."
     }
    }
   },
   "GssV3ShadowRule": {
    "type": "object",
    "description": "A citable-rule candidate surfaced by the shadow lexical matcher.",
    "required": [
     "id",
     "canonical_name",
     "citable"
    ],
    "properties": {
     "canonical_name": {
      "type": "string"
     },
     "citable": {
      "type": "boolean"
     },
     "gate_tier": {
      "type": "string",
      "description": "Serialized `gate_tier` enum as a lowercase string (`permit`/`deny`/`review`),\nor absent when the rule declares none.",
      "nullable": true
     },
     "id": {
      "type": "string"
     }
    }
   },
   "GssV3ShadowSymbolMatch": {
    "type": "object",
    "description": "A symbol matched by one or both shadow-matcher channels.",
    "required": [
     "symbol",
     "score",
     "channel"
    ],
    "properties": {
     "channel": {
      "type": "string",
      "description": "`\"lexical\"`, `\"embedding\"`, or `\"both\"`."
     },
     "score": {
      "type": "number",
      "format": "float",
      "description": "`max(lexical_hit as f32, max cosine over the symbol's exemplar +\nsurface-form vectors)`."
     },
     "symbol": {
      "type": "string"
     }
    }
   },
   "GuiActionKind": {
    "type": "string",
    "enum": [
     "screenshot",
     "mouse",
     "keyboard",
     "screen_size"
    ]
   },
   "Guideline": {
    "type": "object",
    "required": [
     "category",
     "directive",
     "priority",
     "polarity"
    ],
    "properties": {
     "category": {
      "type": "string"
     },
     "directive": {
      "type": "string"
     },
     "polarity": {
      "type": "string"
     },
     "priority": {
      "type": "string"
     }
    }
   },
   "HallucinationReport": {
    "type": "object",
    "description": "A reported hallucination",
    "required": [
     "claim",
     "status"
    ],
    "properties": {
     "claim": {
      "type": "string"
     },
     "correction": {
      "type": "string",
      "nullable": true
     },
     "status": {
      "$ref": "#/components/schemas/HallucinationStatus"
     }
    }
   },
   "HallucinationStatus": {
    "type": "string",
    "enum": [
     "Verified",
     "Unverified",
     "Contradicted"
    ]
   },
   "HealthResponse": {
    "type": "object",
    "required": [
     "status",
     "version",
     "uptime_seconds"
    ],
    "properties": {
     "checks": {
      "nullable": true
     },
     "circuit_breakers": {
      "type": "object",
      "additionalProperties": {
       "$ref": "#/components/schemas/CircuitBreakerStats"
      },
      "nullable": true
     },
     "knowledge_base": {
      "allOf": [
       {
        "$ref": "#/components/schemas/KnowledgeBaseStats"
       }
      ],
      "nullable": true
     },
     "status": {
      "type": "string"
     },
     "uptime_seconds": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "version": {
      "type": "string"
     },
     "warnings": {
      "type": "array",
      "items": {
       "type": "string"
      }
     }
    }
   },
   "HistoryEventView": {
    "type": "object",
    "required": [
     "id",
     "timestamp",
     "org_id",
     "actor",
     "event_type",
     "summary",
     "entity_ids",
     "entity_names",
     "metadata"
    ],
    "properties": {
     "actor": {
      "type": "string"
     },
     "entity_ids": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "entity_names": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "event_type": {
      "type": "string"
     },
     "id": {
      "type": "string"
     },
     "metadata": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      }
     },
     "object": {
      "type": "string",
      "nullable": true
     },
     "object_name": {
      "type": "string",
      "nullable": true
     },
     "org_id": {
      "type": "string"
     },
     "predicate": {
      "type": "string",
      "nullable": true
     },
     "subject": {
      "type": "string",
      "nullable": true
     },
     "subject_name": {
      "type": "string",
      "nullable": true
     },
     "summary": {
      "type": "string"
     },
     "timestamp": {
      "type": "string",
      "format": "date-time"
     }
    }
   },
   "HistoryResponse": {
    "type": "object",
    "description": "Response for history endpoint",
    "required": [
     "events",
     "enriched_events",
     "total"
    ],
    "properties": {
     "enriched_events": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/HistoryEventView"
      }
     },
     "events": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/KBEvent"
      }
     },
     "total": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "IncidentSummary": {
    "type": "object",
    "required": [
     "id",
     "title",
     "severity",
     "opened_at",
     "status"
    ],
    "properties": {
     "id": {
      "type": "string"
     },
     "opened_at": {
      "type": "string",
      "format": "date-time"
     },
     "severity": {
      "type": "string"
     },
     "status": {
      "type": "string"
     },
     "title": {
      "type": "string"
     }
    }
   },
   "InduceExample": {
    "type": "object",
    "description": "One labeled observation for rule induction.",
    "required": [
     "features",
     "label"
    ],
    "properties": {
     "features": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Predicate strings that held, e.g. `[\"loan_type(sba_7a)\", \"amount_ok\"]`."
     },
     "label": {
      "type": "string",
      "description": "The resulting outcome/label, e.g. `\"approved\"`."
     }
    }
   },
   "InduceRulesRequest": {
    "type": "object",
    "description": "Request for on-demand rule induction over caller-supplied examples.",
    "required": [
     "examples"
    ],
    "properties": {
     "examples": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/InduceExample"
      }
     },
     "min_confidence": {
      "type": "number",
      "format": "float",
      "description": "Minimum fraction of matches sharing the label (default 0.8).",
      "nullable": true
     },
     "min_support": {
      "type": "integer",
      "description": "Minimum examples matching a body before a rule is proposed (default 3).",
      "nullable": true,
      "minimum": 0
     }
    }
   },
   "InduceRulesResponse": {
    "type": "object",
    "description": "Response from rule induction: candidate rules, strongest first.",
    "required": [
     "examples_analyzed",
     "rules"
    ],
    "properties": {
     "examples_analyzed": {
      "type": "integer",
      "minimum": 0
     },
     "rules": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/InducedRuleView"
      }
     }
    }
   },
   "InducedRuleView": {
    "type": "object",
    "description": "A proposed rule with its supporting evidence.",
    "required": [
     "head",
     "body",
     "support",
     "confidence"
    ],
    "properties": {
     "body": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "confidence": {
      "type": "number",
      "format": "float"
     },
     "head": {
      "type": "string"
     },
     "support": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "InferRequest": {
    "type": "object",
    "required": [
     "inputs"
    ],
    "properties": {
     "inputs": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Input strings to run inference on."
     }
    }
   },
   "InferResponse": {
    "type": "object",
    "required": [
     "org_id",
     "symbol_count",
     "confidence",
     "abstained",
     "source",
     "model_coverage"
    ],
    "properties": {
     "abstained": {
      "type": "boolean"
     },
     "abstention_reason": {
      "type": "string",
      "description": "Machine-readable reason when `abstained` is true.",
      "nullable": true
     },
     "confidence": {
      "type": "number",
      "format": "double"
     },
     "matched_rule": {
      "type": "string",
      "nullable": true
     },
     "model_coverage": {
      "type": "number",
      "format": "double",
      "description": "Fraction of the learned factor schema grounded by this input."
     },
     "org_id": {
      "type": "string"
     },
     "output": {
      "type": "string",
      "nullable": true
     },
     "source": {
      "type": "string"
     },
     "symbol_count": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "InferredFactResponse": {
    "type": "object",
    "description": "An inferred fact from forward chaining",
    "required": [
     "predicate",
     "terms",
     "rule_id",
     "confidence"
    ],
    "properties": {
     "confidence": {
      "type": "number",
      "format": "double",
      "description": "Confidence score of the inference"
     },
     "predicate": {
      "type": "string",
      "description": "The predicate of the inferred fact"
     },
     "rule_id": {
      "type": "string",
      "description": "The rule ID that produced this fact"
     },
     "substitution": {
      "type": "object",
      "description": "Variable substitutions used (if applicable)",
      "additionalProperties": {
       "type": "string"
      },
      "nullable": true
     },
     "terms": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Arguments/terms of the fact"
     }
    }
   },
   "IngestEntityRecord": {
    "type": "object",
    "required": [
     "name",
     "entity_type"
    ],
    "properties": {
     "entity_type": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "properties": {
      "type": "object",
      "additionalProperties": {},
      "nullable": true
     }
    }
   },
   "IngestJobListResponse": {
    "type": "object",
    "required": [
     "object",
     "data"
    ],
    "properties": {
     "data": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/IngestJobResponse"
      }
     },
     "object": {
      "type": "string"
     }
    }
   },
   "IngestJobResponse": {
    "type": "object",
    "required": [
     "id",
     "object",
     "status",
     "created_at",
     "summary"
    ],
    "properties": {
     "completed_at": {
      "type": "integer",
      "format": "int64",
      "nullable": true,
      "minimum": 0
     },
     "created_at": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "entity_ids": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "errors": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "evidence_ids": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "file_id": {
      "type": "string",
      "nullable": true
     },
     "id": {
      "type": "string"
     },
     "object": {
      "type": "string"
     },
     "rule_ids": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "status": {
      "type": "string"
     },
     "summary": {
      "$ref": "#/components/schemas/IngestJobSummary"
     },
     "warnings": {
      "type": "array",
      "items": {
       "type": "string"
      }
     }
    }
   },
   "IngestJobSummary": {
    "type": "object",
    "required": [
     "files_processed",
     "evidence_nodes_created",
     "entities_created",
     "triples_created",
     "rules_created"
    ],
    "properties": {
     "entities_created": {
      "type": "integer",
      "minimum": 0
     },
     "evidence_nodes_created": {
      "type": "integer",
      "minimum": 0
     },
     "files_processed": {
      "type": "integer",
      "minimum": 0
     },
     "rules_created": {
      "type": "integer",
      "minimum": 0
     },
     "source_id": {
      "type": "string",
      "nullable": true
     },
     "triples_created": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "IngestRuleAtomRecord": {
    "type": "object",
    "required": [
     "predicate"
    ],
    "properties": {
     "args": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "negated": {
      "type": "boolean",
      "nullable": true
     },
     "predicate": {
      "type": "string"
     }
    }
   },
   "IngestRuleRecord": {
    "type": "object",
    "required": [
     "name",
     "head_predicate"
    ],
    "properties": {
     "body": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/IngestRuleAtomRecord"
      }
     },
     "confidence": {
      "type": "number",
      "format": "float",
      "nullable": true
     },
     "description": {
      "type": "string",
      "nullable": true
     },
     "head_args": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "head_predicate": {
      "type": "string"
     },
     "name": {
      "type": "string"
     }
    }
   },
   "IngestTripleRecord": {
    "type": "object",
    "required": [
     "subject_id",
     "predicate",
     "object_id"
    ],
    "properties": {
     "confidence": {
      "type": "number",
      "format": "float",
      "nullable": true
     },
     "object_id": {
      "type": "string"
     },
     "predicate": {
      "type": "string"
     },
     "subject_id": {
      "type": "string"
     }
    }
   },
   "Job": {
    "type": "object",
    "description": "Async job record",
    "required": [
     "id",
     "job_type",
     "status",
     "progress",
     "created_at",
     "updated_at",
     "input"
    ],
    "properties": {
     "completed_at": {
      "type": "integer",
      "format": "int64",
      "description": "Completion timestamp (Unix ms, if completed)",
      "nullable": true,
      "minimum": 0
     },
     "created_at": {
      "type": "integer",
      "format": "int64",
      "description": "Creation timestamp (Unix ms)",
      "minimum": 0
     },
     "error": {
      "type": "string",
      "description": "Error message if failed",
      "nullable": true
     },
     "id": {
      "type": "string",
      "description": "Unique job identifier"
     },
     "input": {
      "description": "Input parameters"
     },
     "job_type": {
      "$ref": "#/components/schemas/JobType"
     },
     "progress": {
      "type": "integer",
      "format": "int32",
      "description": "Progress percentage (0-100)",
      "minimum": 0
     },
     "result": {
      "description": "Result data (JSON)",
      "nullable": true
     },
     "status": {
      "$ref": "#/components/schemas/JobStatus"
     },
     "updated_at": {
      "type": "integer",
      "format": "int64",
      "description": "Last update timestamp (Unix ms)",
      "minimum": 0
     }
    }
   },
   "JobStatus": {
    "type": "string",
    "description": "Job status",
    "enum": [
     "pending",
     "running",
     "completed",
     "failed",
     "cancelled"
    ]
   },
   "JobStatusResponse": {
    "type": "object",
    "description": "Job status response",
    "required": [
     "job"
    ],
    "properties": {
     "job": {
      "$ref": "#/components/schemas/Job"
     }
    }
   },
   "JobSubmitResponse": {
    "type": "object",
    "description": "Job submission response",
    "required": [
     "job_id",
     "status",
     "total_items"
    ],
    "properties": {
     "job_id": {
      "type": "string",
      "description": "Job identifier for tracking"
     },
     "status": {
      "$ref": "#/components/schemas/JobStatus"
     },
     "total_items": {
      "type": "integer",
      "description": "Estimated items to process",
      "minimum": 0
     }
    }
   },
   "JobType": {
    "type": "string",
    "description": "Job type",
    "enum": [
     "batch_infer",
     "train",
     "export",
     "import",
     "evaluate"
    ]
   },
   "KBDiffResponse": {
    "type": "object",
    "description": "Response for diff endpoint",
    "required": [
     "from",
     "to",
     "snapshots",
     "summary",
     "entities",
     "triples",
     "rules",
     "constraint_violations",
     "truncated"
    ],
    "properties": {
     "constraint_violations": {
      "$ref": "#/components/schemas/ConstraintViolationDiffSection"
     },
     "entities": {
      "$ref": "#/components/schemas/EntityDiffSection"
     },
     "from": {
      "type": "string"
     },
     "org_id": {
      "type": "string",
      "nullable": true
     },
     "rules": {
      "$ref": "#/components/schemas/RuleDiffSection"
     },
     "snapshots": {
      "$ref": "#/components/schemas/KBDiffSnapshots"
     },
     "summary": {
      "$ref": "#/components/schemas/KBDiffSummary"
     },
     "to": {
      "type": "string"
     },
     "triples": {
      "$ref": "#/components/schemas/TripleDiffSection"
     },
     "truncated": {
      "type": "boolean",
      "description": "True when any section was truncated by the `limit` parameter"
     }
    }
   },
   "KBDiffSnapshots": {
    "type": "object",
    "required": [
     "from",
     "to"
    ],
    "properties": {
     "from": {
      "$ref": "#/components/schemas/KBSnapshot"
     },
     "to": {
      "$ref": "#/components/schemas/KBSnapshot"
     }
    }
   },
   "KBDiffSummary": {
    "type": "object",
    "required": [
     "added_entities",
     "removed_entities",
     "added_triples",
     "removed_triples",
     "added_rules",
     "removed_rules",
     "modified_rules",
     "introduced_constraint_violations",
     "resolved_constraint_violations"
    ],
    "properties": {
     "added_entities": {
      "type": "integer",
      "minimum": 0
     },
     "added_rules": {
      "type": "integer",
      "minimum": 0
     },
     "added_triples": {
      "type": "integer",
      "minimum": 0
     },
     "introduced_constraint_violations": {
      "type": "integer",
      "minimum": 0
     },
     "modified_rules": {
      "type": "integer",
      "minimum": 0
     },
     "removed_entities": {
      "type": "integer",
      "minimum": 0
     },
     "removed_rules": {
      "type": "integer",
      "minimum": 0
     },
     "removed_triples": {
      "type": "integer",
      "minimum": 0
     },
     "resolved_constraint_violations": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "KBEvent": {
    "type": "object",
    "description": "A single KB mutation event",
    "required": [
     "id",
     "timestamp",
     "org_id",
     "event_type",
     "actor",
     "metadata"
    ],
    "properties": {
     "actor": {
      "type": "string",
      "description": "Who/what caused this event"
     },
     "event_type": {
      "$ref": "#/components/schemas/KBEventType"
     },
     "id": {
      "type": "string",
      "description": "Unique event ID"
     },
     "metadata": {
      "type": "object",
      "description": "Optional metadata",
      "additionalProperties": {
       "type": "string"
      }
     },
     "org_id": {
      "type": "string",
      "description": "Organization scope"
     },
     "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "When this event occurred"
     }
    }
   },
   "KBEventType": {
    "oneOf": [
     {
      "type": "object",
      "required": [
       "entity_id",
       "name",
       "entity_type",
       "type"
      ],
      "properties": {
       "entity_id": {
        "type": "string"
       },
       "entity_type": {
        "type": "string"
       },
       "name": {
        "type": "string"
       },
       "type": {
        "type": "string",
        "enum": [
         "EntityAdded"
        ]
       }
      }
     },
     {
      "type": "object",
      "required": [
       "entity_id",
       "type"
      ],
      "properties": {
       "entity_id": {
        "type": "string"
       },
       "type": {
        "type": "string",
        "enum": [
         "EntityRemoved"
        ]
       }
      }
     },
     {
      "type": "object",
      "required": [
       "subject",
       "predicate",
       "object",
       "confidence",
       "type"
      ],
      "properties": {
       "confidence": {
        "type": "number",
        "format": "float"
       },
       "object": {
        "type": "string"
       },
       "predicate": {
        "type": "string"
       },
       "subject": {
        "type": "string"
       },
       "type": {
        "type": "string",
        "enum": [
         "TripleAsserted"
        ]
       },
       "valid_from": {
        "type": "string",
        "format": "date-time",
        "nullable": true
       },
       "valid_to": {
        "type": "string",
        "format": "date-time",
        "nullable": true
       }
      }
     },
     {
      "type": "object",
      "required": [
       "subject",
       "predicate",
       "object",
       "type"
      ],
      "properties": {
       "object": {
        "type": "string"
       },
       "predicate": {
        "type": "string"
       },
       "subject": {
        "type": "string"
       },
       "type": {
        "type": "string",
        "enum": [
         "TripleRetracted"
        ]
       }
      }
     },
     {
      "type": "object",
      "required": [
       "rule_id",
       "name",
       "type"
      ],
      "properties": {
       "name": {
        "type": "string"
       },
       "rule": {
        "allOf": [
         {
          "$ref": "#/components/schemas/Rule"
         }
        ],
        "nullable": true
       },
       "rule_id": {
        "type": "string"
       },
       "type": {
        "type": "string",
        "enum": [
         "RuleAdded"
        ]
       }
      }
     },
     {
      "type": "object",
      "required": [
       "rule_id",
       "type"
      ],
      "properties": {
       "rule_id": {
        "type": "string"
       },
       "type": {
        "type": "string",
        "enum": [
         "RuleRemoved"
        ]
       }
      }
     },
     {
      "type": "object",
      "required": [
       "entity_id",
       "old_confidence",
       "new_confidence",
       "type"
      ],
      "properties": {
       "entity_id": {
        "type": "string"
       },
       "new_confidence": {
        "type": "number",
        "format": "float"
       },
       "old_confidence": {
        "type": "number",
        "format": "float"
       },
       "type": {
        "type": "string",
        "enum": [
         "BeliefRevised"
        ]
       }
      }
     },
     {
      "type": "object",
      "required": [
       "source_triple",
       "retracted_triples",
       "type"
      ],
      "properties": {
       "retracted_triples": {
        "type": "array",
        "items": {
         "type": "string"
        }
       },
       "source_triple": {
        "type": "string"
       },
       "type": {
        "type": "string",
        "enum": [
         "CascadingRetraction"
        ]
       }
      }
     }
    ],
    "description": "Types of KB mutations",
    "discriminator": {
     "propertyName": "type"
    }
   },
   "KBSnapshot": {
    "type": "object",
    "description": "Summary of KB state at a point in time",
    "required": [
     "as_of",
     "entity_count",
     "triple_count",
     "rule_count",
     "events_applied"
    ],
    "properties": {
     "as_of": {
      "type": "string",
      "format": "date-time"
     },
     "entity_count": {
      "type": "integer",
      "minimum": 0
     },
     "events_applied": {
      "type": "integer",
      "minimum": 0
     },
     "rule_count": {
      "type": "integer",
      "minimum": 0
     },
     "triple_count": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "KBStats": {
    "type": "object",
    "description": "Knowledge base statistics",
    "required": [
     "entity_count",
     "triple_count",
     "rule_count",
     "symbol_count"
    ],
    "properties": {
     "entity_count": {
      "type": "integer",
      "description": "Number of entities",
      "minimum": 0
     },
     "rule_count": {
      "type": "integer",
      "description": "Number of rules",
      "minimum": 0
     },
     "symbol_count": {
      "type": "integer",
      "description": "Number of symbols",
      "minimum": 0
     },
     "triple_count": {
      "type": "integer",
      "description": "Number of triples",
      "minimum": 0
     }
    }
   },
   "KnowledgeBaseStats": {
    "type": "object",
    "required": [
     "entity_count",
     "triple_count",
     "rule_count"
    ],
    "properties": {
     "entity_count": {
      "type": "integer",
      "minimum": 0
     },
     "rule_count": {
      "type": "integer",
      "minimum": 0
     },
     "triple_count": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "LearningEvent": {
    "type": "object",
    "description": "A learning event generated from production reasoning",
    "required": [
     "id",
     "timestamp",
     "event_type",
     "query",
     "strategy",
     "confidence",
     "success",
     "metadata"
    ],
    "properties": {
     "confidence": {
      "type": "number",
      "format": "float",
      "description": "Outcome confidence"
     },
     "event_type": {
      "$ref": "#/components/schemas/LearningEventType"
     },
     "id": {
      "type": "string",
      "description": "Unique event ID"
     },
     "metadata": {
      "description": "Additional metadata"
     },
     "org_id": {
      "type": "string",
      "description": "Organization context",
      "nullable": true
     },
     "query": {
      "type": "string",
      "description": "The query that triggered this event"
     },
     "strategy": {
      "type": "string",
      "description": "Strategy used"
     },
     "success": {
      "type": "boolean",
      "description": "Whether the outcome was successful"
     },
     "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "When this event occurred"
     }
    }
   },
   "LearningEventType": {
    "oneOf": [
     {
      "type": "object",
      "description": "Query that couldn't be parsed by the compiler",
      "required": [
       "raw_query",
       "error",
       "type"
      ],
      "properties": {
       "error": {
        "type": "string"
       },
       "raw_query": {
        "type": "string"
       },
       "type": {
        "type": "string",
        "enum": [
         "ParseFailure"
        ]
       }
      }
     },
     {
      "type": "object",
      "description": "Query that failed during reasoning execution (non-parse failure)",
      "required": [
       "error",
       "type"
      ],
      "properties": {
       "error": {
        "type": "string"
       },
       "type": {
        "type": "string",
        "enum": [
         "ExecutionFailure"
        ]
       }
      }
     },
     {
      "type": "object",
      "description": "Low-confidence reasoning result",
      "required": [
       "result_confidence",
       "strategy",
       "type"
      ],
      "properties": {
       "result_confidence": {
        "type": "number",
        "format": "float"
       },
       "strategy": {
        "type": "string"
       },
       "type": {
        "type": "string",
        "enum": [
         "LowConfidence"
        ]
       }
      }
     },
     {
      "type": "object",
      "description": "Strategy escalation (e.g., Auto \u2192 Ensemble)",
      "required": [
       "from_strategy",
       "to_strategy",
       "reason",
       "type"
      ],
      "properties": {
       "from_strategy": {
        "type": "string"
       },
       "reason": {
        "type": "string"
       },
       "to_strategy": {
        "type": "string"
       },
       "type": {
        "type": "string",
        "enum": [
         "StrategyEscalation"
        ]
       }
      }
     },
     {
      "type": "object",
      "description": "Hallucination detected by RAG verification",
      "required": [
       "claim",
       "type"
      ],
      "properties": {
       "claim": {
        "type": "string"
       },
       "correction": {
        "type": "string",
        "nullable": true
       },
       "type": {
        "type": "string",
        "enum": [
         "HallucinationDetected"
        ]
       }
      }
     },
     {
      "type": "object",
      "description": "User feedback (explicit thumbs up/down)",
      "required": [
       "query",
       "answer",
       "positive",
       "type"
      ],
      "properties": {
       "answer": {
        "type": "string"
       },
       "comment": {
        "type": "string",
        "nullable": true
       },
       "positive": {
        "type": "boolean"
       },
       "query": {
        "type": "string"
       },
       "type": {
        "type": "string",
        "enum": [
         "UserFeedback"
        ]
       }
      }
     },
     {
      "type": "object",
      "description": "New rule candidate discovered via abduction",
      "required": [
       "rule_head",
       "rule_body",
       "evidence_count",
       "type"
      ],
      "properties": {
       "evidence_count": {
        "type": "integer",
        "minimum": 0
       },
       "rule_body": {
        "type": "array",
        "items": {
         "type": "string"
        }
       },
       "rule_head": {
        "type": "string"
       },
       "type": {
        "type": "string",
        "enum": [
         "RuleCandidate"
        ]
       }
      }
     },
     {
      "type": "object",
      "description": "Contradiction detected between facts",
      "required": [
       "fact_a",
       "fact_b",
       "type"
      ],
      "properties": {
       "fact_a": {
        "type": "string"
       },
       "fact_b": {
        "type": "string"
       },
       "type": {
        "type": "string",
        "enum": [
         "ContradictionDetected"
        ]
       }
      }
     }
    ],
    "description": "Types of learning events",
    "discriminator": {
     "propertyName": "type"
    }
   },
   "LinkEntitlementRequest": {
    "type": "object",
    "required": [
     "org_id",
     "token",
     "entitlement"
    ],
    "properties": {
     "entitlement": {
      "type": "object",
      "description": "Which billing backend + the identifiers it reports against."
     },
     "org_id": {
      "type": "string",
      "description": "The NSR org/tenant to bill."
     },
     "token": {
      "type": "string",
      "description": "The marketplace subscription token, so a later lifecycle event resolves\nback to this org."
     }
    }
   },
   "ListBeliefsResponse": {
    "type": "object",
    "description": "Response listing all beliefs",
    "required": [
     "beliefs",
     "total"
    ],
    "properties": {
     "beliefs": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/BeliefSummary"
      }
     },
     "total": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "ListCheckpointsResponse": {
    "type": "object",
    "description": "List checkpoints response",
    "required": [
     "checkpoints",
     "total"
    ],
    "properties": {
     "checkpoints": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ModelCheckpoint"
      },
      "description": "Available checkpoints"
     },
     "total": {
      "type": "integer",
      "description": "Total count",
      "minimum": 0
     }
    }
   },
   "ListConstraintsResponse": {
    "type": "object",
    "description": "Response listing all constraints",
    "required": [
     "constraints",
     "total",
     "hard_count",
     "soft_count"
    ],
    "properties": {
     "constraints": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ConstraintResponse"
      }
     },
     "hard_count": {
      "type": "integer",
      "minimum": 0
     },
     "soft_count": {
      "type": "integer",
      "minimum": 0
     },
     "total": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "ListJobsQuery": {
    "type": "object",
    "description": "Query parameters for listing jobs",
    "properties": {
     "created_after": {
      "type": "integer",
      "format": "int64",
      "description": "Only jobs created after this timestamp (Unix ms)",
      "nullable": true,
      "minimum": 0
     },
     "created_before": {
      "type": "integer",
      "format": "int64",
      "description": "Only jobs created before this timestamp (Unix ms)",
      "nullable": true,
      "minimum": 0
     },
     "job_type": {
      "allOf": [
       {
        "$ref": "#/components/schemas/JobType"
       }
      ],
      "nullable": true
     },
     "limit": {
      "type": "integer",
      "description": "Maximum number of results (default: 100)",
      "nullable": true,
      "minimum": 0
     },
     "offset": {
      "type": "integer",
      "description": "Offset for pagination (default: 0)",
      "nullable": true,
      "minimum": 0
     },
     "sort_by": {
      "type": "string",
      "description": "Sort by field (created_at, updated_at)",
      "nullable": true
     },
     "sort_order": {
      "type": "string",
      "description": "Sort order (asc, desc)",
      "nullable": true
     },
     "status": {
      "allOf": [
       {
        "$ref": "#/components/schemas/JobStatus"
       }
      ],
      "nullable": true
     }
    }
   },
   "ListJobsResponse": {
    "type": "object",
    "description": "List jobs response",
    "required": [
     "jobs",
     "total",
     "count",
     "offset",
     "limit"
    ],
    "properties": {
     "count": {
      "type": "integer",
      "description": "Number of jobs returned",
      "minimum": 0
     },
     "jobs": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Job"
      },
      "description": "List of jobs"
     },
     "limit": {
      "type": "integer",
      "description": "Limit used",
      "minimum": 0
     },
     "offset": {
      "type": "integer",
      "description": "Offset used",
      "minimum": 0
     },
     "total": {
      "type": "integer",
      "description": "Total count (before pagination)",
      "minimum": 0
     }
    }
   },
   "ListMacrosResponse": {
    "type": "object",
    "required": [
     "macros",
     "total",
     "limit",
     "offset"
    ],
    "properties": {
     "limit": {
      "type": "integer",
      "minimum": 0
     },
     "macros": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Macro"
      }
     },
     "offset": {
      "type": "integer",
      "minimum": 0
     },
     "total": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "ListPredicatesResponse": {
    "type": "object",
    "description": "Response listing all predicates",
    "required": [
     "predicates",
     "total"
    ],
    "properties": {
     "predicates": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/PredicateResponse"
      }
     },
     "total": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "ListSymbolsResponse": {
    "type": "object",
    "description": "Response listing all symbols",
    "required": [
     "symbols",
     "total"
    ],
    "properties": {
     "symbols": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/SymbolResponse"
      },
      "description": "List of symbols"
     },
     "total": {
      "type": "integer",
      "description": "Total count",
      "minimum": 0
     }
    }
   },
   "ListThoughtsQuery": {
    "type": "object",
    "description": "Query parameters for listing/searching GoT thoughts",
    "properties": {
     "min_score": {
      "type": "number",
      "format": "float",
      "description": "Optional minimum score filter",
      "nullable": true
     },
     "q": {
      "type": "string",
      "description": "Optional substring filter (case-insensitive)",
      "nullable": true
     },
     "top_k": {
      "type": "integer",
      "description": "Maximum number of thoughts to return (default: 10)",
      "nullable": true,
      "minimum": 0
     }
    }
   },
   "ListTypesResponse": {
    "type": "object",
    "description": "Response listing available primitive types",
    "required": [
     "primitive_types",
     "subtypes"
    ],
    "properties": {
     "primitive_types": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "subtypes": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/SubtypeRelation"
      }
     }
    }
   },
   "ListWebhooksResponse": {
    "type": "object",
    "required": [
     "endpoints",
     "count"
    ],
    "properties": {
     "count": {
      "type": "integer",
      "minimum": 0
     },
     "endpoints": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/WebhookSummary"
      }
     }
    }
   },
   "MachineActionContract": {
    "type": "object",
    "required": [
     "name"
    ],
    "properties": {
     "description": {
      "type": "string",
      "nullable": true
     },
     "method": {
      "type": "string",
      "nullable": true
     },
     "name": {
      "type": "string"
     },
     "path": {
      "type": "string",
      "nullable": true
     },
     "required_entities": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "requires_approval": {
      "type": "boolean",
      "nullable": true
     }
    }
   },
   "MachineActivateRequest": {
    "type": "object",
    "required": [
     "compiled_id"
    ],
    "properties": {
     "compiled_id": {
      "type": "string"
     }
    }
   },
   "MachineActivateResponse": {
    "type": "object",
    "required": [
     "compiled_id",
     "org_id",
     "status",
     "activated_at",
     "summary"
    ],
    "properties": {
     "activated_at": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "compiled_id": {
      "type": "string"
     },
     "org_id": {
      "type": "string"
     },
     "status": {
      "type": "string"
     },
     "summary": {
      "$ref": "#/components/schemas/MachineActivationSummary"
     }
    }
   },
   "MachineActivationSummary": {
    "type": "object",
    "required": [
     "entities_created",
     "triples_created",
     "rules_created",
     "training_examples_used",
     "vocabulary_size",
     "programs_learned"
    ],
    "properties": {
     "entities_created": {
      "type": "integer",
      "minimum": 0
     },
     "errors": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "programs_learned": {
      "type": "integer",
      "minimum": 0
     },
     "rules_created": {
      "type": "integer",
      "minimum": 0
     },
     "training_examples_used": {
      "type": "integer",
      "minimum": 0
     },
     "triples_created": {
      "type": "integer",
      "minimum": 0
     },
     "vocabulary_size": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "MachineBrandVoice": {
    "type": "object",
    "required": [
     "guidance"
    ],
    "properties": {
     "agent_name": {
      "type": "string",
      "nullable": true
     },
     "guidance": {
      "type": "string"
     },
     "tone": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "MachineCatalogItem": {
    "type": "object",
    "required": [
     "name"
    ],
    "properties": {
     "aliases": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "availability": {
      "type": "string",
      "nullable": true
     },
     "category": {
      "type": "string",
      "nullable": true
     },
     "description": {
      "type": "string",
      "nullable": true
     },
     "name": {
      "type": "string"
     },
     "price": {
      "type": "string",
      "nullable": true
     },
     "properties": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      }
     },
     "sku": {
      "type": "string",
      "nullable": true
     },
     "subscription_price": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "MachineCompilePreview": {
    "type": "object",
    "properties": {
     "entity_names": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "rule_names": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "training_labels": {
      "type": "array",
      "items": {
       "type": "string"
      }
     }
    }
   },
   "MachineCompileRequest": {
    "type": "object",
    "required": [
     "seed_id"
    ],
    "properties": {
     "seed_id": {
      "type": "string"
     }
    }
   },
   "MachineCompileResponse": {
    "type": "object",
    "required": [
     "id",
     "object",
     "org_id",
     "seed_id",
     "brand_name",
     "status",
     "created_at",
     "summary",
     "preview"
    ],
    "properties": {
     "activated_at": {
      "type": "integer",
      "format": "int64",
      "nullable": true,
      "minimum": 0
     },
     "activation": {
      "allOf": [
       {
        "$ref": "#/components/schemas/MachineActivationSummary"
       }
      ],
      "nullable": true
     },
     "brand_name": {
      "type": "string"
     },
     "candidate_symbols": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "created_at": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "id": {
      "type": "string"
     },
     "object": {
      "type": "string"
     },
     "org_id": {
      "type": "string"
     },
     "preview": {
      "$ref": "#/components/schemas/MachineCompilePreview"
     },
     "review_items": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "seed_id": {
      "type": "string"
     },
     "status": {
      "type": "string"
     },
     "summary": {
      "$ref": "#/components/schemas/MachineCompileSummary"
     }
    }
   },
   "MachineCompileSummary": {
    "type": "object",
    "required": [
     "entities",
     "triples",
     "rules",
     "training_examples",
     "action_contracts",
     "policy_documents"
    ],
    "properties": {
     "action_contracts": {
      "type": "integer",
      "minimum": 0
     },
     "entities": {
      "type": "integer",
      "minimum": 0
     },
     "policy_documents": {
      "type": "integer",
      "minimum": 0
     },
     "rules": {
      "type": "integer",
      "minimum": 0
     },
     "training_examples": {
      "type": "integer",
      "minimum": 0
     },
     "triples": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "MachineCoverageBreakdown": {
    "type": "object",
    "required": [
     "ticket_label_coverage",
     "catalog_readiness",
     "policy_readiness",
     "action_readiness"
    ],
    "properties": {
     "action_readiness": {
      "type": "number",
      "format": "float"
     },
     "catalog_readiness": {
      "type": "number",
      "format": "float"
     },
     "policy_readiness": {
      "type": "number",
      "format": "float"
     },
     "ticket_label_coverage": {
      "type": "number",
      "format": "float"
     }
    }
   },
   "MachineHistoricalTicket": {
    "type": "object",
    "required": [
     "input"
    ],
    "properties": {
     "extracted_entities": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      }
     },
     "input": {
      "type": "string"
     },
     "outcome_action": {
      "type": "string",
      "nullable": true
     },
     "outcome_status": {
      "type": "string",
      "nullable": true
     },
     "requires_human_review": {
      "type": "boolean",
      "nullable": true
     },
     "resolved_intent": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "MachineInfo": {
    "type": "object",
    "description": "Summary information for a provisioned NSR machine.",
    "required": [
     "org_id",
     "status",
     "vocabulary_size",
     "programs_learned",
     "training_examples",
     "successful_inferences",
     "has_snapshot"
    ],
    "properties": {
     "has_snapshot": {
      "type": "boolean"
     },
     "org_id": {
      "type": "string"
     },
     "programs_learned": {
      "type": "integer",
      "minimum": 0
     },
     "status": {
      "type": "string",
      "description": "One of `\"active\"`, `\"activating\"`, `\"activation_failed\"`, `\"compiled\"`, `\"training\"`, or `\"not_provisioned\"`."
     },
     "successful_inferences": {
      "type": "integer",
      "minimum": 0
     },
     "training_examples": {
      "type": "integer",
      "minimum": 0
     },
     "vocabulary_size": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "MachinePolicyDocument": {
    "type": "object",
    "required": [
     "name",
     "text"
    ],
    "properties": {
     "category": {
      "type": "string",
      "nullable": true
     },
     "escalation_required": {
      "type": "boolean",
      "nullable": true
     },
     "name": {
      "type": "string"
     },
     "text": {
      "type": "string"
     }
    }
   },
   "MachineSeedEvaluateRequest": {
    "type": "object",
    "required": [
     "compiled_id"
    ],
    "properties": {
     "compiled_id": {
      "type": "string"
     }
    }
   },
   "MachineSeedEvaluateResponse": {
    "type": "object",
    "required": [
     "compiled_id",
     "org_id",
     "readiness_score",
     "activation_recommended",
     "coverage"
    ],
    "properties": {
     "activation_recommended": {
      "type": "boolean"
     },
     "compiled_id": {
      "type": "string"
     },
     "coverage": {
      "$ref": "#/components/schemas/MachineCoverageBreakdown"
     },
     "gaps": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "org_id": {
      "type": "string"
     },
     "readiness_score": {
      "type": "number",
      "format": "float"
     }
    }
   },
   "MachineSeedRequest": {
    "type": "object",
    "required": [
     "brand_name"
    ],
    "properties": {
     "actions": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/MachineActionContract"
      }
     },
     "brand_name": {
      "type": "string"
     },
     "brand_voice": {
      "allOf": [
       {
        "$ref": "#/components/schemas/MachineBrandVoice"
       }
      ],
      "nullable": true
     },
     "catalog": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/MachineCatalogItem"
      }
     },
     "file_ids": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "historical_tickets": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/MachineHistoricalTicket"
      }
     },
     "metadata": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      }
     },
     "policies": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/MachinePolicyDocument"
      }
     },
     "structured": {
      "allOf": [
       {
        "$ref": "#/components/schemas/StructuredIngestPayload"
       }
      ],
      "nullable": true
     }
    }
   },
   "MachineSeedResponse": {
    "type": "object",
    "required": [
     "id",
     "object",
     "org_id",
     "brand_name",
     "status",
     "created_at",
     "summary",
     "next_step"
    ],
    "properties": {
     "brand_name": {
      "type": "string"
     },
     "candidate_actions": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "candidate_intents": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "created_at": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "id": {
      "type": "string"
     },
     "next_step": {
      "type": "string"
     },
     "object": {
      "type": "string"
     },
     "org_id": {
      "type": "string"
     },
     "review_items": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "status": {
      "type": "string"
     },
     "summary": {
      "$ref": "#/components/schemas/MachineSeedSummary"
     }
    }
   },
   "MachineSeedSummary": {
    "type": "object",
    "required": [
     "catalog_items",
     "policies",
     "actions",
     "historical_tickets",
     "labeled_tickets",
     "unlabeled_tickets",
     "file_ids",
     "explicit_rules"
    ],
    "properties": {
     "actions": {
      "type": "integer",
      "minimum": 0
     },
     "catalog_items": {
      "type": "integer",
      "minimum": 0
     },
     "explicit_rules": {
      "type": "integer",
      "minimum": 0
     },
     "file_ids": {
      "type": "integer",
      "minimum": 0
     },
     "historical_tickets": {
      "type": "integer",
      "minimum": 0
     },
     "labeled_tickets": {
      "type": "integer",
      "minimum": 0
     },
     "policies": {
      "type": "integer",
      "minimum": 0
     },
     "unlabeled_tickets": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "MachineUncertaintySnapshot": {
    "type": "object",
    "required": [
     "epistemic",
     "aleatoric",
     "total",
     "calibration_score"
    ],
    "properties": {
     "aleatoric": {
      "type": "number",
      "format": "double"
     },
     "calibration_score": {
      "type": "number",
      "format": "double"
     },
     "epistemic": {
      "type": "number",
      "format": "double"
     },
     "total": {
      "type": "number",
      "format": "double"
     }
    }
   },
   "MachinesListResponse": {
    "type": "object",
    "required": [
     "machines",
     "total"
    ],
    "properties": {
     "machines": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/MachineInfo"
      }
     },
     "total": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "Macro": {
    "type": "object",
    "required": [
     "id",
     "org_id",
     "name",
     "body",
     "slots",
     "status",
     "auto_send",
     "created_at",
     "updated_at"
    ],
    "properties": {
     "auto_send": {
      "type": "boolean"
     },
     "body": {
      "type": "string"
     },
     "channel": {
      "type": "string",
      "nullable": true
     },
     "created_at": {
      "type": "string"
     },
     "id": {
      "type": "string"
     },
     "name": {
      "type": "string",
      "description": "Upsert key within an org, matching the rules convention."
     },
     "org_id": {
      "type": "string"
     },
     "rule_name": {
      "type": "string",
      "description": "The policy rule whose citation selects this macro.",
      "nullable": true
     },
     "slots": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Merge fields parsed from `body` at write time."
     },
     "source": {
      "type": "string",
      "nullable": true
     },
     "status": {
      "$ref": "#/components/schemas/MacroStatus"
     },
     "tags": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "title": {
      "type": "string"
     },
     "tool": {
      "allOf": [
       {
        "$ref": "#/components/schemas/MacroTool"
       }
      ],
      "nullable": true
     },
     "updated_at": {
      "type": "string"
     }
    }
   },
   "MacroStatus": {
    "type": "string",
    "description": "Lifecycle of a macro. Anything mined or bulk-uploaded arrives as\n`Candidate`: a person decides what may be said to a customer, never an\nimport job.",
    "enum": [
     "candidate",
     "approved",
     "archived"
    ]
   },
   "MacroTool": {
    "type": "object",
    "description": "A state change bound to a macro. Argument values may carry `{{slot}}` refs\nresolved from the decision's grounded facts at send time.",
    "required": [
     "name"
    ],
    "properties": {
     "arguments": {
      "type": "object",
      "additionalProperties": {}
     },
     "name": {
      "type": "string"
     }
    }
   },
   "MetricDiff": {
    "type": "object",
    "description": "Metric difference between models",
    "required": [
     "accuracy_diff",
     "f1_diff",
     "loss_diff"
    ],
    "properties": {
     "accuracy_diff": {
      "type": "number",
      "format": "double",
      "description": "Accuracy difference (B - A)"
     },
     "f1_diff": {
      "type": "number",
      "format": "double",
      "description": "F1 score difference"
     },
     "loss_diff": {
      "type": "number",
      "format": "double",
      "description": "Loss difference"
     }
    }
   },
   "MissingFact": {
    "type": "object",
    "required": [
     "predicate",
     "args",
     "needed_by_rule",
     "question"
    ],
    "properties": {
     "args": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "needed_by_rule": {
      "type": "string"
     },
     "predicate": {
      "type": "string"
     },
     "question": {
      "type": "string",
      "description": "A natural-language question that, answered affirmatively, yields this\npremise \u2014 so a refusal is turnkey to resolve instead of a dead end."
     },
     "resolves_with": {
      "allOf": [
       {
        "$ref": "#/components/schemas/RetryFact"
       }
      ],
      "nullable": true
     }
    }
   },
   "ModelCard": {
    "type": "object",
    "required": [
     "id",
     "object",
     "created",
     "owned_by"
    ],
    "properties": {
     "created": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "id": {
      "type": "string"
     },
     "object": {
      "type": "string"
     },
     "owned_by": {
      "type": "string"
     }
    }
   },
   "ModelCheckpoint": {
    "type": "object",
    "description": "Model checkpoint metadata",
    "required": [
     "id",
     "name",
     "version",
     "created_at",
     "config",
     "metrics"
    ],
    "properties": {
     "config": {
      "$ref": "#/components/schemas/ModelConfig"
     },
     "created_at": {
      "type": "integer",
      "format": "int64",
      "description": "Creation timestamp (Unix ms)",
      "minimum": 0
     },
     "description": {
      "type": "string",
      "description": "Optional description",
      "nullable": true
     },
     "id": {
      "type": "string",
      "description": "Unique checkpoint identifier"
     },
     "metrics": {
      "$ref": "#/components/schemas/ModelMetrics"
     },
     "name": {
      "type": "string",
      "description": "Human-readable name"
     },
     "tags": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Tags for organization"
     },
     "version": {
      "type": "string",
      "description": "Version string (semver)"
     }
    }
   },
   "ModelComparison": {
    "type": "object",
    "description": "Model comparison result",
    "required": [
     "checkpoint_a",
     "checkpoint_b",
     "metric_diffs",
     "config_changes",
     "recommendation"
    ],
    "properties": {
     "checkpoint_a": {
      "type": "string",
      "description": "Checkpoint A identifier"
     },
     "checkpoint_b": {
      "type": "string",
      "description": "Checkpoint B identifier"
     },
     "config_changes": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ConfigChange"
      },
      "description": "Configuration changes"
     },
     "metric_diffs": {
      "$ref": "#/components/schemas/MetricDiff"
     },
     "recommendation": {
      "type": "string",
      "description": "Recommendation"
     }
    }
   },
   "ModelConfig": {
    "type": "object",
    "description": "Model configuration",
    "required": [
     "embedding_dim",
     "hidden_dims",
     "attention_heads",
     "max_sequence_length",
     "dropout",
     "features"
    ],
    "properties": {
     "attention_heads": {
      "type": "integer",
      "description": "Number of attention heads",
      "minimum": 0
     },
     "dropout": {
      "type": "number",
      "format": "float",
      "description": "Dropout rate"
     },
     "embedding_dim": {
      "type": "integer",
      "description": "Embedding dimension",
      "minimum": 0
     },
     "features": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Feature flags enabled"
     },
     "hidden_dims": {
      "type": "array",
      "items": {
       "type": "integer",
       "minimum": 0
      },
      "description": "Hidden layer dimensions"
     },
     "max_sequence_length": {
      "type": "integer",
      "description": "Maximum sequence length",
      "minimum": 0
     }
    }
   },
   "ModelInfoResponse": {
    "type": "object",
    "description": "Model info response",
    "required": [
     "config",
     "metrics",
     "parameter_count",
     "memory_bytes",
     "active_features",
     "kb_stats"
    ],
    "properties": {
     "active_features": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Active features"
     },
     "config": {
      "$ref": "#/components/schemas/ModelConfig"
     },
     "kb_stats": {
      "$ref": "#/components/schemas/KBStats"
     },
     "memory_bytes": {
      "type": "integer",
      "description": "Memory usage (bytes)",
      "minimum": 0
     },
     "metrics": {
      "$ref": "#/components/schemas/ModelMetrics"
     },
     "parameter_count": {
      "type": "integer",
      "description": "Number of parameters",
      "minimum": 0
     }
    }
   },
   "ModelMetrics": {
    "type": "object",
    "description": "Model training metrics",
    "required": [
     "train_loss",
     "val_loss",
     "accuracy",
     "f1_score",
     "epochs",
     "training_time_secs"
    ],
    "properties": {
     "accuracy": {
      "type": "number",
      "format": "double",
      "description": "Accuracy on test set"
     },
     "epochs": {
      "type": "integer",
      "description": "Training epochs completed",
      "minimum": 0
     },
     "f1_score": {
      "type": "number",
      "format": "double",
      "description": "F1 score"
     },
     "train_loss": {
      "type": "number",
      "format": "double",
      "description": "Training loss"
     },
     "training_time_secs": {
      "type": "integer",
      "format": "int64",
      "description": "Total training time (seconds)",
      "minimum": 0
     },
     "val_loss": {
      "type": "number",
      "format": "double",
      "description": "Validation loss"
     }
    }
   },
   "ModelsListResponse": {
    "type": "object",
    "required": [
     "object",
     "data"
    ],
    "properties": {
     "data": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ModelCard"
      }
     },
     "object": {
      "type": "string"
     }
    }
   },
   "ModifiedRuleDiffItem": {
    "type": "object",
    "required": [
     "id",
     "name",
     "before",
     "after"
    ],
    "properties": {
     "after": {
      "$ref": "#/components/schemas/RuleDiffItem"
     },
     "before": {
      "$ref": "#/components/schemas/RuleDiffItem"
     },
     "id": {
      "type": "string"
     },
     "name": {
      "type": "string"
     }
    }
   },
   "ModifyBeliefRequest": {
    "type": "object",
    "description": "Request to support/contradict a belief",
    "required": [
     "proposition",
     "strength"
    ],
    "properties": {
     "proposition": {
      "type": "string",
      "description": "The proposition to modify"
     },
     "source": {
      "type": "string",
      "description": "Source of the evidence",
      "nullable": true
     },
     "strength": {
      "type": "number",
      "format": "float",
      "description": "Strength of the support/contradiction (0.0 to 1.0)"
     }
    },
    "example": {
     "proposition": "socrates_is_mortal",
     "source": "inference",
     "strength": 0.3
    }
   },
   "ModifyBeliefResponse": {
    "type": "object",
    "description": "Response after modifying a belief",
    "required": [
     "proposition",
     "previous_confidence",
     "new_confidence",
     "change"
    ],
    "properties": {
     "change": {
      "type": "number",
      "format": "float"
     },
     "new_confidence": {
      "type": "number",
      "format": "float"
     },
     "previous_confidence": {
      "type": "number",
      "format": "float"
     },
     "proposition": {
      "type": "string"
     }
    }
   },
   "NSRConfigSummary": {
    "type": "object",
    "description": "Summary of NSR configuration",
    "required": [
     "embedding_dim",
     "hidden_size",
     "max_seq_len",
     "synthesis_enabled",
     "max_program_depth"
    ],
    "properties": {
     "embedding_dim": {
      "type": "integer",
      "description": "Embedding dimension",
      "minimum": 0
     },
     "hidden_size": {
      "type": "integer",
      "description": "Hidden size",
      "minimum": 0
     },
     "max_program_depth": {
      "type": "integer",
      "description": "Max program depth",
      "minimum": 0
     },
     "max_seq_len": {
      "type": "integer",
      "description": "Max sequence length",
      "minimum": 0
     },
     "synthesis_enabled": {
      "type": "boolean",
      "description": "Program synthesis enabled"
     }
    }
   },
   "NSREnsembleInferRequest": {
    "type": "object",
    "description": "Request for ensemble inference (calibration via input dropout)",
    "required": [
     "inputs"
    ],
    "properties": {
     "drop_count": {
      "type": "integer",
      "description": "Number of random tokens to drop per run (default: 1)",
      "nullable": true,
      "minimum": 0
     },
     "inputs": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/GroundedInputRequest"
      },
      "description": "Input sequence for inference"
     },
     "runs": {
      "type": "integer",
      "description": "Number of ensemble runs (default: 5, max: 25)",
      "nullable": true,
      "minimum": 0
     },
     "session_id": {
      "type": "string",
      "description": "Optional session ID for context persistence",
      "nullable": true
     }
    }
   },
   "NSREnsembleInferResponse": {
    "type": "object",
    "description": "Response from ensemble inference",
    "required": [
     "confidence",
     "agreement",
     "runs",
     "results",
     "processing_time_ms"
    ],
    "properties": {
     "agreement": {
      "type": "number",
      "format": "double",
      "description": "Agreement ratio for the consensus (0.0 to 1.0)"
     },
     "confidence": {
      "type": "number",
      "format": "double",
      "description": "Calibrated confidence based on agreement and mean per-run confidence (0.0 to 1.0)"
     },
     "output": {
      "allOf": [
       {
        "$ref": "#/components/schemas/SemanticValueResponse"
       }
      ],
      "nullable": true
     },
     "processing_time_ms": {
      "type": "integer",
      "format": "int64",
      "description": "Processing time in milliseconds",
      "minimum": 0
     },
     "results": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/NSREnsembleRunResponse"
      },
      "description": "Per-run outputs and diagnostics"
     },
     "runs": {
      "type": "integer",
      "description": "Number of runs performed",
      "minimum": 0
     }
    }
   },
   "NSREnsembleRunResponse": {
    "type": "object",
    "description": "Per-run summary for ensemble inference",
    "required": [
     "confidence",
     "inputs_used"
    ],
    "properties": {
     "confidence": {
      "type": "number",
      "format": "double",
      "description": "Confidence score for this run"
     },
     "error": {
      "type": "string",
      "description": "Error string when the run fails",
      "nullable": true
     },
     "inputs_used": {
      "type": "integer",
      "description": "Inputs used in this run (after dropout)",
      "minimum": 0
     },
     "output": {
      "allOf": [
       {
        "$ref": "#/components/schemas/SemanticValueResponse"
       }
      ],
      "nullable": true
     }
    }
   },
   "NSRInferRequest": {
    "type": "object",
    "description": "Request for NSR inference",
    "required": [
     "inputs"
    ],
    "properties": {
     "inputs": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/GroundedInputRequest"
      },
      "description": "Input sequence for inference"
     },
     "session_id": {
      "type": "string",
      "description": "Optional session ID for context persistence",
      "nullable": true
     }
    },
    "example": {
     "inputs": [
      {
       "type": "text",
       "value": "walk twice"
      }
     ],
     "session_id": null
    }
   },
   "NSRInferResponse": {
    "type": "object",
    "description": "Response from NSR inference",
    "required": [
     "symbols",
     "confidence",
     "processing_time_ms"
    ],
    "properties": {
     "confidence": {
      "type": "number",
      "format": "double",
      "description": "Confidence score (0.0 to 1.0)"
     },
     "interpreted_confidence": {
      "type": "number",
      "format": "double",
      "description": "Confidence for the interpreted output (0.0 to 1.0)",
      "nullable": true
     },
     "interpreted_output": {
      "allOf": [
       {
        "$ref": "#/components/schemas/SemanticValueResponse"
       }
      ],
      "nullable": true
     },
     "interpreted_rationale": {
      "type": "string",
      "description": "Short rationale for how the interpreted output was chosen",
      "nullable": true
     },
     "output": {
      "allOf": [
       {
        "$ref": "#/components/schemas/SemanticValueResponse"
       }
      ],
      "nullable": true
     },
     "processing_time_ms": {
      "type": "integer",
      "format": "int64",
      "description": "Processing time in milliseconds",
      "minimum": 0
     },
     "symbol_distributions": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/SymbolDistributionResponse"
      },
      "description": "Symbol distributions for each input",
      "nullable": true
     },
     "symbols": {
      "type": "array",
      "items": {
       "type": "integer",
       "format": "int64",
       "minimum": 0
      },
      "description": "Symbol sequence identified"
     }
    },
    "example": {
     "confidence": 0.95,
     "output": {
      "type": "list",
      "value": [
       {
        "type": "string",
        "value": "WALK"
       },
       {
        "type": "string",
        "value": "WALK"
       }
      ]
     },
     "processing_time_ms": 12,
     "symbol_distributions": null,
     "symbols": [
      1,
      3,
      1
     ]
    }
   },
   "NSRLAssertRequest": {
    "type": "object",
    "description": "Request to assert facts/rules from NSR-L",
    "required": [
     "code"
    ],
    "properties": {
     "code": {
      "type": "string",
      "description": "NSR-L facts/rules to assert"
     }
    },
    "example": {
     "code": "philosopher(socrates). taught(socrates, plato)."
    }
   },
   "NSRLAssertResponse": {
    "type": "object",
    "description": "Response from asserting",
    "required": [
     "success",
     "facts_added",
     "rules_added",
     "errors"
    ],
    "properties": {
     "errors": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "facts_added": {
      "type": "integer",
      "minimum": 0
     },
     "rules_added": {
      "type": "integer",
      "minimum": 0
     },
     "success": {
      "type": "boolean"
     }
    }
   },
   "NSRLExecuteRequest": {
    "type": "object",
    "description": "Request to execute NSR-L code",
    "required": [
     "code"
    ],
    "properties": {
     "code": {
      "type": "string",
      "description": "NSR-L code to execute"
     },
     "persist": {
      "type": "boolean",
      "description": "Whether to persist facts/rules to the org-scoped NSR-L program store (and mirror compatible items into the KB)"
     }
    },
    "example": {
     "code": "human(socrates). mortal(X) :- human(X). ?- mortal(socrates).",
     "persist": true
    }
   },
   "NSRLExecuteResponse": {
    "type": "object",
    "description": "Response from executing NSR-L code",
    "required": [
     "success",
     "query_results",
     "facts_added",
     "rules_added",
     "execution_time_ms",
     "errors"
    ],
    "properties": {
     "errors": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Errors (if any)"
     },
     "execution_time_ms": {
      "type": "integer",
      "format": "int64",
      "description": "Execution time in milliseconds",
      "minimum": 0
     },
     "facts_added": {
      "type": "integer",
      "description": "Facts added",
      "minimum": 0
     },
     "query_results": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/QueryResultResponse"
      },
      "description": "Query results (for ?- queries)"
     },
     "rules_added": {
      "type": "integer",
      "description": "Rules added",
      "minimum": 0
     },
     "success": {
      "type": "boolean",
      "description": "Whether execution succeeded"
     }
    }
   },
   "NSRLParseRequest": {
    "type": "object",
    "description": "Request to parse NSR-L code",
    "required": [
     "code"
    ],
    "properties": {
     "code": {
      "type": "string",
      "description": "NSR-L code to parse"
     }
    },
    "example": {
     "code": "human(socrates). mortal(X) :- human(X)."
    }
   },
   "NSRLParseResponse": {
    "type": "object",
    "description": "Response from parsing NSR-L code",
    "required": [
     "success",
     "facts",
     "rules",
     "queries",
     "errors"
    ],
    "properties": {
     "errors": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Parse errors (if any)"
     },
     "facts": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ParsedFact"
      },
      "description": "Parsed facts"
     },
     "queries": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Parsed queries"
     },
     "rules": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ParsedRule"
      },
      "description": "Parsed rules"
     },
     "success": {
      "type": "boolean",
      "description": "Whether parsing succeeded"
     }
    }
   },
   "NSRLProgramResponse": {
    "type": "object",
    "description": "Response containing the persisted NSR-L program for an org.",
    "required": [
     "code"
    ],
    "properties": {
     "code": {
      "type": "string",
      "description": "Full NSR-L program source (facts + rules)."
     },
     "updated_at": {
      "type": "string",
      "description": "Last update time (RFC3339), if available.",
      "nullable": true
     }
    }
   },
   "NSRLProgramUpdateRequest": {
    "type": "object",
    "description": "Request to replace the current NSR-L program.",
    "required": [
     "code"
    ],
    "properties": {
     "code": {
      "type": "string"
     },
     "message": {
      "type": "string",
      "nullable": true
     }
    },
    "example": {
     "code": "human(socrates). mortal(X) :- human(X).",
     "message": "Initial policy load"
    }
   },
   "NSRLProgramUpdateResponse": {
    "type": "object",
    "required": [
     "success",
     "errors"
    ],
    "properties": {
     "errors": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "success": {
      "type": "boolean"
     },
     "updated_at": {
      "type": "string",
      "nullable": true
     },
     "version_id": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "NSRLProgramVersion": {
    "type": "object",
    "required": [
     "id",
     "created_at"
    ],
    "properties": {
     "created_at": {
      "type": "string"
     },
     "id": {
      "type": "string"
     },
     "message": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "NSRLProgramVersionResponse": {
    "type": "object",
    "required": [
     "id",
     "created_at",
     "code"
    ],
    "properties": {
     "code": {
      "type": "string"
     },
     "created_at": {
      "type": "string"
     },
     "id": {
      "type": "string"
     },
     "message": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "NSRLProgramVersionsQuery": {
    "type": "object",
    "properties": {
     "limit": {
      "type": "integer",
      "nullable": true,
      "minimum": 0
     }
    }
   },
   "NSRLProgramVersionsResponse": {
    "type": "object",
    "required": [
     "versions",
     "total"
    ],
    "properties": {
     "total": {
      "type": "integer",
      "minimum": 0
     },
     "versions": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/NSRLProgramVersion"
      }
     }
    }
   },
   "NSRLProveRequest": {
    "type": "object",
    "description": "Request to prove a query using resolution",
    "required": [
     "query"
    ],
    "properties": {
     "max_iterations": {
      "type": "integer",
      "description": "Maximum resolution iterations",
      "minimum": 0
     },
     "query": {
      "type": "string",
      "description": "Query to prove (in NSR-L syntax)"
     }
    },
    "example": {
     "max_iterations": 100,
     "query": "mortal(socrates)"
    }
   },
   "NSRLProveResponse": {
    "type": "object",
    "description": "Response from proof attempt",
    "required": [
     "proved",
     "confidence",
     "proof_steps",
     "explanation",
     "time_ms"
    ],
    "properties": {
     "confidence": {
      "type": "number",
      "format": "double",
      "description": "Confidence (1.0 if proved symbolically)"
     },
     "explanation": {
      "type": "string",
      "description": "Explanation"
     },
     "proof_steps": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Proof steps (if successful)"
     },
     "proved": {
      "type": "boolean",
      "description": "Whether the query was proved"
     },
     "time_ms": {
      "type": "integer",
      "format": "int64",
      "description": "Time taken in milliseconds",
      "minimum": 0
     }
    }
   },
   "NSRStatsResponse": {
    "type": "object",
    "description": "Response for NSR Machine statistics",
    "required": [
     "training_examples",
     "successful_inferences",
     "programs_learned",
     "vocabulary_size",
     "enabled_features",
     "config"
    ],
    "properties": {
     "config": {
      "$ref": "#/components/schemas/NSRConfigSummary"
     },
     "enabled_features": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Enabled features"
     },
     "programs_learned": {
      "type": "integer",
      "description": "Programs learned",
      "minimum": 0
     },
     "successful_inferences": {
      "type": "integer",
      "description": "Successful inferences",
      "minimum": 0
     },
     "training_examples": {
      "type": "integer",
      "description": "Training examples processed",
      "minimum": 0
     },
     "vocabulary_size": {
      "type": "integer",
      "description": "Vocabulary size",
      "minimum": 0
     }
    }
   },
   "NSRTrainRequest": {
    "type": "object",
    "description": "Request for NSR training",
    "required": [
     "examples"
    ],
    "properties": {
     "epochs": {
      "type": "integer",
      "description": "Number of epochs (optional, default 1)",
      "nullable": true,
      "minimum": 0
     },
     "examples": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/TrainingExampleRequest"
      },
      "description": "Training examples"
     }
    },
    "example": {
     "epochs": 5,
     "examples": [
      {
       "inputs": [
        {
         "type": "text",
         "value": "walk"
        }
       ],
       "output": {
        "type": "list",
        "value": [
         {
          "type": "string",
          "value": "WALK"
         }
        ]
       }
      },
      {
       "inputs": [
        {
         "type": "text",
         "value": "run"
        }
       ],
       "output": {
        "type": "list",
        "value": [
         {
          "type": "string",
          "value": "RUN"
         }
        ]
       }
      }
     ]
    }
   },
   "NSRTrainResponse": {
    "type": "object",
    "description": "Response from NSR training",
    "required": [
     "total_examples",
     "successful_abductions",
     "final_loss",
     "programs_learned",
     "training_time_ms"
    ],
    "properties": {
     "final_loss": {
      "type": "number",
      "format": "double",
      "description": "Final training loss"
     },
     "programs_learned": {
      "type": "integer",
      "description": "Programs learned during training",
      "minimum": 0
     },
     "successful_abductions": {
      "type": "integer",
      "description": "Successful abductions",
      "minimum": 0
     },
     "total_examples": {
      "type": "integer",
      "description": "Total examples processed",
      "minimum": 0
     },
     "training_time_ms": {
      "type": "integer",
      "format": "int64",
      "description": "Training time in milliseconds",
      "minimum": 0
     }
    },
    "example": {
     "final_loss": 0.023,
     "programs_learned": 3,
     "successful_abductions": 8,
     "total_examples": 10,
     "training_time_ms": 1250
    }
   },
   "NSRValidateBatchItem": {
    "type": "object",
    "description": "Single item for batch validation.",
    "required": [
     "inquiry",
     "response"
    ],
    "properties": {
     "case_id": {
      "type": "string",
      "description": "Optional validation case id (used when replaying test cases).",
      "nullable": true
     },
     "inquiry": {
      "type": "string",
      "description": "Customer inquiry text."
     },
     "response": {
      "type": "string",
      "description": "Draft response to validate."
     }
    }
   },
   "NSRValidateBatchItemResult": {
    "type": "object",
    "description": "Batch validation item result.",
    "required": [
     "index",
     "inquiry",
     "response",
     "result"
    ],
    "properties": {
     "case_id": {
      "type": "string",
      "nullable": true
     },
     "index": {
      "type": "integer",
      "minimum": 0
     },
     "inquiry": {
      "type": "string"
     },
     "response": {
      "type": "string"
     },
     "result": {
      "$ref": "#/components/schemas/NSRValidateResponse"
     }
    }
   },
   "NSRValidateBatchRequest": {
    "type": "object",
    "description": "Batch validation request.",
    "required": [
     "cases"
    ],
    "properties": {
     "cases": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/NSRValidateBatchItem"
      },
      "description": "Items to validate."
     },
     "include_neural_signals": {
      "type": "boolean",
      "description": "Include NSR Machine neural signals in the response."
     },
     "max_ngram": {
      "type": "integer",
      "description": "Max n-gram length used for contains_text assertions.",
      "nullable": true,
      "minimum": 0
     },
     "max_phrases": {
      "type": "integer",
      "description": "Cap on total phrases asserted per text.",
      "nullable": true,
      "minimum": 0
     },
     "persist": {
      "type": "boolean",
      "description": "Persist validation runs for history/auditing.",
      "nullable": true
     }
    }
   },
   "NSRValidateBatchResponse": {
    "type": "object",
    "description": "Batch validation response.",
    "required": [
     "total",
     "valid",
     "invalid",
     "results"
    ],
    "properties": {
     "invalid": {
      "type": "integer",
      "minimum": 0
     },
     "results": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/NSRValidateBatchItemResult"
      }
     },
     "total": {
      "type": "integer",
      "minimum": 0
     },
     "valid": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "NSRValidateRequest": {
    "type": "object",
    "description": "Request payload for neuro-symbolic validation.",
    "required": [
     "inquiry",
     "response"
    ],
    "properties": {
     "case_id": {
      "type": "string",
      "description": "Optional validation case id (used when replaying test cases).",
      "nullable": true
     },
     "include_neural_signals": {
      "type": "boolean",
      "description": "Include NSR Machine neural signals in the response."
     },
     "inquiry": {
      "type": "string",
      "description": "Customer inquiry text."
     },
     "max_ngram": {
      "type": "integer",
      "description": "Max n-gram length used for contains_text assertions.",
      "nullable": true,
      "minimum": 0
     },
     "max_phrases": {
      "type": "integer",
      "description": "Cap on total phrases asserted per text.",
      "nullable": true,
      "minimum": 0
     },
     "persist": {
      "type": "boolean",
      "description": "Persist this validation run for history/auditing.",
      "nullable": true
     },
     "response": {
      "type": "string",
      "description": "Draft response to validate."
     }
    },
    "example": {
     "include_neural_signals": false,
     "inquiry": "Can I return my order?",
     "max_ngram": 6,
     "max_phrases": 2000,
     "response": "Hi, I'm Dottie. You can return within 30 days."
    }
   },
   "NSRValidateResponse": {
    "type": "object",
    "description": "Validation response.",
    "required": [
     "valid",
     "response_invalid",
     "violations",
     "missing_links",
     "escalations",
     "topics",
     "execution_time_ms"
    ],
    "properties": {
     "escalations": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Escalation topics detected."
     },
     "execution_time_ms": {
      "type": "integer",
      "format": "int64",
      "description": "Execution time in milliseconds.",
      "minimum": 0
     },
     "missing_links": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Missing required links."
     },
     "neural": {
      "allOf": [
       {
        "$ref": "#/components/schemas/NeuralSignals"
       }
      ],
      "nullable": true
     },
     "program_version_id": {
      "type": "string",
      "description": "Optional NSR-L program version id used for this validation.",
      "nullable": true
     },
     "response_invalid": {
      "type": "boolean",
      "description": "Response is explicitly invalid (response_invalid/1)."
     },
     "run_id": {
      "type": "string",
      "description": "Optional persisted run id when stored.",
      "nullable": true
     },
     "topics": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Topics detected in the inquiry."
     },
     "valid": {
      "type": "boolean",
      "description": "Overall validity (no violations/missing links/escalations and not response_invalid)."
     },
     "violations": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Prohibited phrases detected."
     }
    }
   },
   "NSRValidationCase": {
    "type": "object",
    "description": "Stored validation test case.",
    "required": [
     "id",
     "name",
     "inquiry",
     "response",
     "created_at"
    ],
    "properties": {
     "created_at": {
      "type": "string"
     },
     "expected_valid": {
      "type": "boolean",
      "nullable": true
     },
     "id": {
      "type": "string"
     },
     "inquiry": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "response": {
      "type": "string"
     }
    }
   },
   "NSRValidationCaseInput": {
    "type": "object",
    "description": "Input for creating validation test cases.",
    "required": [
     "name",
     "inquiry",
     "response"
    ],
    "properties": {
     "expected_valid": {
      "type": "boolean",
      "nullable": true
     },
     "inquiry": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "response": {
      "type": "string"
     }
    }
   },
   "NSRValidationCasesBatchRequest": {
    "type": "object",
    "required": [
     "cases"
    ],
    "properties": {
     "cases": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/NSRValidationCaseInput"
      }
     }
    }
   },
   "NSRValidationCasesBatchResponse": {
    "type": "object",
    "required": [
     "created",
     "errors"
    ],
    "properties": {
     "created": {
      "type": "integer",
      "minimum": 0
     },
     "errors": {
      "type": "array",
      "items": {
       "type": "string"
      }
     }
    }
   },
   "NSRValidationCasesResponse": {
    "type": "object",
    "required": [
     "cases",
     "total"
    ],
    "properties": {
     "cases": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/NSRValidationCase"
      }
     },
     "total": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "NSRValidationReplayRequest": {
    "type": "object",
    "properties": {
     "include_neural_signals": {
      "type": "boolean"
     }
    }
   },
   "NSRValidationRun": {
    "type": "object",
    "required": [
     "id",
     "inquiry",
     "response",
     "valid",
     "response_invalid",
     "violations",
     "missing_links",
     "escalations",
     "topics",
     "execution_time_ms",
     "created_at"
    ],
    "properties": {
     "case_id": {
      "type": "string",
      "nullable": true
     },
     "case_name": {
      "type": "string",
      "nullable": true
     },
     "created_at": {
      "type": "string"
     },
     "escalations": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "execution_time_ms": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "id": {
      "type": "string"
     },
     "inquiry": {
      "type": "string"
     },
     "missing_links": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "program_version_id": {
      "type": "string",
      "nullable": true
     },
     "response": {
      "type": "string"
     },
     "response_invalid": {
      "type": "boolean"
     },
     "topics": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "valid": {
      "type": "boolean"
     },
     "violations": {
      "type": "array",
      "items": {
       "type": "string"
      }
     }
    }
   },
   "NSRValidationRunsQuery": {
    "type": "object",
    "properties": {
     "limit": {
      "type": "integer",
      "nullable": true,
      "minimum": 0
     }
    }
   },
   "NSRValidationRunsResponse": {
    "type": "object",
    "required": [
     "runs",
     "total"
    ],
    "properties": {
     "runs": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/NSRValidationRun"
      }
     },
     "total": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "NeuralSignals": {
    "type": "object",
    "description": "Neural signal summary (optional).",
    "required": [
     "confidence",
     "symbols"
    ],
    "properties": {
     "confidence": {
      "type": "number",
      "format": "double",
      "description": "Inference confidence."
     },
     "interpreted_confidence": {
      "type": "number",
      "format": "double",
      "description": "Interpreted class confidence (if any).",
      "nullable": true
     },
     "interpreted_output": {
      "allOf": [
       {
        "$ref": "#/components/schemas/SemanticValueResponse"
       }
      ],
      "nullable": true
     },
     "output": {
      "allOf": [
       {
        "$ref": "#/components/schemas/SemanticValueResponse"
       }
      ],
      "nullable": true
     },
     "symbols": {
      "type": "array",
      "items": {
       "type": "integer",
       "format": "int64",
       "minimum": 0
      },
      "description": "Symbol sequence from the NSR Machine."
     }
    }
   },
   "OrgRuleDefinition": {
    "type": "object",
    "required": [
     "name",
     "conditions",
     "conclusions"
    ],
    "properties": {
     "conclusions": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "conditions": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "name": {
      "type": "string"
     }
    }
   },
   "OutcomeUsage": {
    "type": "object",
    "description": "Outcome-based billing metrics.",
    "required": [
     "outcomes_month",
     "outcomes_included",
     "outcomes_billable",
     "price_per_outcome",
     "outcome_charges",
     "base_fee",
     "estimated_total"
    ],
    "properties": {
     "base_fee": {
      "type": "number",
      "format": "double",
      "description": "Base platform fee in dollars."
     },
     "estimated_total": {
      "type": "number",
      "format": "double",
      "description": "Total estimated bill (base + outcome charges)."
     },
     "outcome_charges": {
      "type": "number",
      "format": "double",
      "description": "Total outcome charges this month in dollars."
     },
     "outcomes_billable": {
      "type": "integer",
      "format": "int64",
      "description": "Billable outcomes (beyond included quota).",
      "minimum": 0
     },
     "outcomes_included": {
      "type": "integer",
      "format": "int64",
      "description": "Outcomes included in the tier (no extra charge).",
      "minimum": 0
     },
     "outcomes_month": {
      "type": "integer",
      "format": "int64",
      "description": "Total resolved outcomes this month.",
      "minimum": 0
     },
     "price_per_outcome": {
      "type": "number",
      "format": "double",
      "description": "Price per billable outcome in dollars."
     }
    }
   },
   "PaginatedEntityResponse": {
    "type": "object",
    "required": [
     "items",
     "pagination"
    ],
    "properties": {
     "items": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/EntityResponse"
      },
      "description": "The items in this page"
     },
     "pagination": {
      "$ref": "#/components/schemas/PaginationMeta"
     }
    }
   },
   "PaginatedRuleListResponse": {
    "type": "object",
    "required": [
     "items",
     "pagination"
    ],
    "properties": {
     "items": {
      "type": "array",
      "items": {},
      "description": "The items in this page"
     },
     "pagination": {
      "$ref": "#/components/schemas/PaginationMeta"
     }
    }
   },
   "PaginatedTripleResponse": {
    "type": "object",
    "required": [
     "items",
     "pagination"
    ],
    "properties": {
     "items": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/TripleResponse"
      },
      "description": "The items in this page"
     },
     "pagination": {
      "$ref": "#/components/schemas/PaginationMeta"
     }
    }
   },
   "PaginationMeta": {
    "type": "object",
    "description": "Pagination metadata in response",
    "required": [
     "limit",
     "offset",
     "has_more"
    ],
    "properties": {
     "has_more": {
      "type": "boolean",
      "description": "Whether there are more items after this page"
     },
     "limit": {
      "type": "integer",
      "description": "Current page limit",
      "minimum": 0
     },
     "next_cursor": {
      "type": "string",
      "description": "Cursor for the next page (if using cursor-based pagination)",
      "nullable": true
     },
     "offset": {
      "type": "integer",
      "description": "Current offset",
      "minimum": 0
     },
     "prev_cursor": {
      "type": "string",
      "description": "Cursor for the previous page",
      "nullable": true
     },
     "total": {
      "type": "integer",
      "description": "Total number of items (if available)",
      "nullable": true,
      "minimum": 0
     }
    }
   },
   "ParsedFact": {
    "type": "object",
    "description": "A parsed fact",
    "required": [
     "predicate",
     "arguments"
    ],
    "properties": {
     "arguments": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "predicate": {
      "type": "string"
     }
    }
   },
   "ParsedRule": {
    "type": "object",
    "description": "A parsed rule",
    "required": [
     "head",
     "body"
    ],
    "properties": {
     "body": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ParsedFact"
      }
     },
     "head": {
      "$ref": "#/components/schemas/ParsedFact"
     }
    }
   },
   "PatternRequest": {
    "type": "object",
    "required": [
     "subject",
     "predicate",
     "object"
    ],
    "properties": {
     "object": {
      "type": "string"
     },
     "predicate": {
      "type": "string"
     },
     "subject": {
      "type": "string"
     }
    }
   },
   "PolicyEvaluateRequest": {
    "type": "object",
    "required": [
     "inquiry",
     "response"
    ],
    "properties": {
     "executed_tools": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "inquiry": {
      "type": "string"
     },
     "org_id": {
      "type": "string",
      "nullable": true
     },
     "response": {
      "type": "string"
     }
    }
   },
   "PolicyEvaluateResponse": {
    "type": "object",
    "required": [
     "decision",
     "rule_decision",
     "machine_decision",
     "confidence",
     "policy_score",
     "triggered_signals",
     "proof_trace",
     "processing_time_ms"
    ],
    "properties": {
     "confidence": {
      "type": "number",
      "format": "double"
     },
     "decision": {
      "type": "string"
     },
     "machine_decision": {
      "type": "string"
     },
     "policy_score": {
      "type": "integer",
      "format": "int32"
     },
     "processing_time_ms": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "proof_trace": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ProofNode"
      }
     },
     "rule_decision": {
      "type": "string"
     },
     "triggered_signals": {
      "type": "array",
      "items": {
       "type": "string"
      }
     }
    }
   },
   "PolicyExample": {
    "type": "object",
    "required": [
     "tool_name",
     "tool_input",
     "correct_decision"
    ],
    "properties": {
     "correct_decision": {
      "type": "string"
     },
     "tool_input": {},
     "tool_name": {
      "type": "string"
     }
    }
   },
   "PolicyImpactFlip": {
    "type": "object",
    "description": "One decision whose policy-layer outcome differs under the candidate.",
    "required": [
     "decision_id",
     "query",
     "original_outcome",
     "baseline",
     "candidate"
    ],
    "properties": {
     "baseline": {
      "$ref": "#/components/schemas/PolicyVerdict"
     },
     "candidate": {
      "$ref": "#/components/schemas/PolicyVerdict"
     },
     "decision_id": {
      "type": "string"
     },
     "original_outcome": {
      "type": "string",
      "description": "The outcome the platform originally returned (includes neural\ncontext; shown for reference, not the comparison baseline)."
     },
     "query": {
      "type": "string"
     }
    }
   },
   "PolicyImpactRequest": {
    "type": "object",
    "description": "Candidate policy change to preview.",
    "properties": {
     "add_rules": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/RecursiveChatRuleInput"
      },
      "description": "Rules to ADD to the org policy for the candidate replay. Evaluated\norg-side (target-binding and declared-effect semantics identical to a\nstored org rule). Each rule must have exactly one conclusion.",
      "nullable": true
     },
     "limit": {
      "type": "integer",
      "description": "Max logged decisions to replay, newest first (default 100, cap 500).",
      "nullable": true,
      "minimum": 0
     },
     "remove_rules": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Names of existing org rules to REMOVE for the candidate replay.",
      "nullable": true
     }
    }
   },
   "PolicyImpactResponse": {
    "type": "object",
    "required": [
     "evaluated",
     "skipped_no_snapshot",
     "flips",
     "candidate_outcomes",
     "scope"
    ],
    "properties": {
     "candidate_outcomes": {
      "type": "object",
      "description": "Verdict counts under the candidate policy, flipped or not.",
      "additionalProperties": {
       "type": "integer",
       "minimum": 0
      }
     },
     "evaluated": {
      "type": "integer",
      "description": "Records replayed (had a request snapshot).",
      "minimum": 0
     },
     "flips": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/PolicyImpactFlip"
      }
     },
     "scope": {
      "type": "string",
      "description": "What this replay does and does not evaluate."
     },
     "skipped_no_snapshot": {
      "type": "integer",
      "description": "Records skipped because they carried no request snapshot.",
      "minimum": 0
     }
    }
   },
   "PolicyInferRequest": {
    "type": "object",
    "required": [
     "tool_name",
     "tool_input"
    ],
    "properties": {
     "org_id": {
      "type": "string",
      "nullable": true
     },
     "tool_input": {},
     "tool_name": {
      "type": "string"
     }
    }
   },
   "PolicyInferResponse": {
    "type": "object",
    "required": [
     "decision",
     "confidence",
     "proof_trace",
     "processing_time_ms"
    ],
    "properties": {
     "confidence": {
      "type": "number",
      "format": "double"
     },
     "decision": {
      "type": "string"
     },
     "processing_time_ms": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "proof_trace": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ProofNode"
      }
     }
    }
   },
   "PolicyTrainRequest": {
    "type": "object",
    "required": [
     "examples"
    ],
    "properties": {
     "examples": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/PolicyExample"
      }
     },
     "org_id": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "PolicyTrainResponse": {
    "type": "object",
    "required": [
     "total_examples",
     "successful_abductions",
     "training_time_ms"
    ],
    "properties": {
     "successful_abductions": {
      "type": "integer",
      "minimum": 0
     },
     "total_examples": {
      "type": "integer",
      "minimum": 0
     },
     "training_time_ms": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     }
    }
   },
   "PolicyVerdict": {
    "type": "object",
    "description": "The policy-layer verdict for one replayed decision under one rule set.",
    "required": [
     "outcome",
     "reason",
     "cited_rules"
    ],
    "properties": {
     "cited_rules": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "outcome": {
      "type": "string",
      "description": "`approved | denied | refused` \u2014 from the same outcome gate as live."
     },
     "reason": {
      "type": "string"
     }
    }
   },
   "PolicyVocabInitRequest": {
    "type": "object",
    "properties": {
     "custom_tool_names": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "nullable": true
     },
     "org_id": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "PolicyVocabResponse": {
    "type": "object",
    "required": [
     "org_id",
     "symbols_registered",
     "programs_set"
    ],
    "properties": {
     "org_id": {
      "type": "string"
     },
     "programs_set": {
      "type": "integer",
      "minimum": 0
     },
     "symbols_registered": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "PredicateResponse": {
    "type": "object",
    "description": "Response for a predicate signature",
    "required": [
     "name",
     "arg_types",
     "arity"
    ],
    "properties": {
     "arg_types": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "arity": {
      "type": "integer",
      "minimum": 0
     },
     "doc": {
      "type": "string",
      "nullable": true
     },
     "name": {
      "type": "string"
     },
     "return_type": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "ProgramEvaluateRequest": {
    "type": "object",
    "description": "Request to evaluate a program with arguments",
    "required": [
     "program"
    ],
    "properties": {
     "args": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/SemanticValueRequest"
      },
      "description": "Optional arguments to bind as variables",
      "nullable": true
     },
     "children": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/SemanticValueRequest"
      },
      "description": "Optional child values for `child` lookups",
      "nullable": true
     },
     "program": {
      "$ref": "#/components/schemas/ProgramRequest"
     }
    }
   },
   "ProgramEvaluateResponse": {
    "type": "object",
    "description": "Response from program evaluation",
    "required": [
     "output",
     "depth",
     "execution_time_ms"
    ],
    "properties": {
     "depth": {
      "type": "integer",
      "description": "Program depth",
      "minimum": 0
     },
     "execution_time_ms": {
      "type": "integer",
      "format": "int64",
      "description": "Evaluation time in milliseconds",
      "minimum": 0
     },
     "output": {
      "$ref": "#/components/schemas/SemanticValueResponse"
     }
    }
   },
   "ProgramRequest": {
    "oneOf": [
     {
      "type": "object",
      "description": "Variable reference",
      "required": [
       "index",
       "type"
      ],
      "properties": {
       "index": {
        "type": "integer",
        "minimum": 0
       },
       "type": {
        "type": "string",
        "enum": [
         "var"
        ]
       }
      }
     },
     {
      "type": "object",
      "description": "Constant value",
      "required": [
       "value",
       "type"
      ],
      "properties": {
       "type": {
        "type": "string",
        "enum": [
         "const"
        ]
       },
       "value": {
        "$ref": "#/components/schemas/SemanticValueRequest"
       }
      }
     },
     {
      "type": "object",
      "description": "Primitive operation",
      "required": [
       "name",
       "type"
      ],
      "properties": {
       "args": {
        "type": "array",
        "items": {
         "$ref": "#/components/schemas/ProgramRequest"
        },
        "description": "Optional arguments for variadic primitive calls (e.g., `and`, `add`).\n\nWhen omitted, the primitive is constructed with an empty argument list.",
        "nullable": true
       },
       "name": {
        "type": "string"
       },
       "type": {
        "type": "string",
        "enum": [
         "primitive"
        ]
       }
      }
     },
     {
      "type": "object",
      "description": "Function application",
      "required": [
       "function",
       "argument",
       "type"
      ],
      "properties": {
       "argument": {
        "$ref": "#/components/schemas/ProgramRequest"
       },
       "function": {
        "$ref": "#/components/schemas/ProgramRequest"
       },
       "type": {
        "type": "string",
        "enum": [
         "apply"
        ]
       }
      }
     },
     {
      "type": "object",
      "description": "Lambda abstraction",
      "required": [
       "body",
       "type"
      ],
      "properties": {
       "body": {
        "$ref": "#/components/schemas/ProgramRequest"
       },
       "type": {
        "type": "string",
        "enum": [
         "lambda"
        ]
       }
      }
     },
     {
      "type": "object",
      "description": "Conditional",
      "required": [
       "condition",
       "then_branch",
       "else_branch",
       "type"
      ],
      "properties": {
       "condition": {
        "$ref": "#/components/schemas/ProgramRequest"
       },
       "else_branch": {
        "$ref": "#/components/schemas/ProgramRequest"
       },
       "then_branch": {
        "$ref": "#/components/schemas/ProgramRequest"
       },
       "type": {
        "type": "string",
        "enum": [
         "if"
        ]
       }
      }
     },
     {
      "type": "object",
      "description": "Let binding",
      "required": [
       "value",
       "body",
       "type"
      ],
      "properties": {
       "body": {
        "$ref": "#/components/schemas/ProgramRequest"
       },
       "type": {
        "type": "string",
        "enum": [
         "let"
        ]
       },
       "value": {
        "$ref": "#/components/schemas/ProgramRequest"
       }
      }
     }
    ],
    "description": "Program representation in requests",
    "discriminator": {
     "propertyName": "type"
    }
   },
   "ProgramResponse": {
    "type": "object",
    "description": "Response for program operations",
    "required": [
     "symbol_id",
     "program",
     "depth"
    ],
    "properties": {
     "depth": {
      "type": "integer",
      "description": "Program depth",
      "minimum": 0
     },
     "program": {
      "type": "string",
      "description": "Program representation (simplified)"
     },
     "symbol_id": {
      "type": "integer",
      "format": "int64",
      "description": "Symbol ID",
      "minimum": 0
     }
    }
   },
   "PromotionCandidate": {
    "type": "object",
    "description": "An artifact proposed for promotion into the system",
    "required": [
     "id",
     "created_at",
     "artifact_type",
     "content",
     "evidence_events",
     "status"
    ],
    "properties": {
     "artifact_type": {
      "$ref": "#/components/schemas/ArtifactType"
     },
     "content": {},
     "created_at": {
      "type": "string",
      "format": "date-time"
     },
     "evidence_events": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "id": {
      "type": "string"
     },
     "org_id": {
      "type": "string",
      "nullable": true
     },
     "reviewed_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true
     },
     "reviewed_by": {
      "type": "string",
      "nullable": true
     },
     "status": {
      "$ref": "#/components/schemas/PromotionStatus"
     }
    }
   },
   "PromotionStatus": {
    "type": "string",
    "enum": [
     "Pending",
     "Approved",
     "Rejected",
     "AutoPromoted"
    ]
   },
   "ProofInfo": {
    "type": "object",
    "description": "Information about a single proof",
    "required": [
     "steps",
     "substitution",
     "confidence"
    ],
    "properties": {
     "confidence": {
      "type": "number",
      "format": "float"
     },
     "steps": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "substitution": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      }
     }
    }
   },
   "ProofNode": {
    "type": "object",
    "required": [
     "position",
     "input",
     "symbol",
     "log_prob"
    ],
    "properties": {
     "input": {
      "type": "string"
     },
     "log_prob": {
      "type": "number",
      "format": "double"
     },
     "position": {
      "type": "integer",
      "minimum": 0
     },
     "symbol": {
      "type": "string"
     }
    }
   },
   "ProofVerifyResponse": {
    "type": "object",
    "required": [
     "verified"
    ],
    "properties": {
     "failed_step": {
      "type": "integer",
      "description": "The step index the failure anchors to, when the failure is step-local.",
      "nullable": true,
      "minimum": 0
     },
     "reason": {
      "type": "string",
      "description": "Present only on failure: the located reason the proof did not check.",
      "nullable": true
     },
     "verified": {
      "type": "boolean",
      "description": "True iff the derivation checks against the bundle's own facts and rules."
     }
    }
   },
   "ProvisionRequest": {
    "type": "object",
    "properties": {
     "seed_from_gss": {
      "type": "boolean",
      "description": "Whether to seed with the org's GSS rules from the seed file (default: true).",
      "nullable": true
     },
     "training_examples": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ProvisionTrainingExample"
      },
      "description": "Optional custom training examples to include during provisioning.",
      "nullable": true
     }
    }
   },
   "ProvisionResponse": {
    "type": "object",
    "required": [
     "org_id",
     "status",
     "training_examples_used",
     "total_examples",
     "successful_abductions",
     "vocabulary_size",
     "programs_learned"
    ],
    "properties": {
     "org_id": {
      "type": "string"
     },
     "programs_learned": {
      "type": "integer",
      "minimum": 0
     },
     "status": {
      "type": "string"
     },
     "successful_abductions": {
      "type": "integer",
      "minimum": 0
     },
     "total_examples": {
      "type": "integer",
      "minimum": 0
     },
     "training_examples_used": {
      "type": "integer",
      "minimum": 0
     },
     "vocabulary_size": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "ProvisionTrainingExample": {
    "type": "object",
    "required": [
     "input",
     "expected_category"
    ],
    "properties": {
     "expected_category": {
      "type": "string"
     },
     "input": {
      "type": "string"
     }
    }
   },
   "PubSubMessage": {
    "type": "object",
    "required": [
     "data"
    ],
    "properties": {
     "data": {
      "type": "string",
      "description": "Base64 (standard) of the GCP Marketplace event JSON."
     }
    }
   },
   "PubSubPush": {
    "type": "object",
    "required": [
     "message"
    ],
    "properties": {
     "message": {
      "$ref": "#/components/schemas/PubSubMessage"
     }
    }
   },
   "PurchaseCreditsRequest": {
    "type": "object",
    "description": "POST /api/v1/billing/credits/purchase",
    "required": [
     "amount_dollars"
    ],
    "properties": {
     "amount_dollars": {
      "type": "number",
      "format": "double",
      "description": "Amount in dollars to purchase as prepaid credits."
     }
    }
   },
   "QueryRequest": {
    "type": "object",
    "required": [
     "patterns"
    ],
    "properties": {
     "limit": {
      "type": "integer",
      "nullable": true,
      "minimum": 0
     },
     "patterns": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/PatternRequest"
      }
     }
    }
   },
   "QueryResponse": {
    "type": "object",
    "required": [
     "bindings",
     "total_count",
     "execution_time_ms"
    ],
    "properties": {
     "bindings": {
      "type": "array",
      "items": {
       "type": "object",
       "additionalProperties": {}
      }
     },
     "execution_time_ms": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "total_count": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "QueryResultResponse": {
    "type": "object",
    "description": "Result of a single query",
    "required": [
     "query",
     "result",
     "confidence",
     "bindings"
    ],
    "properties": {
     "bindings": {
      "type": "array",
      "items": {
       "type": "object",
       "additionalProperties": {
        "type": "string"
       }
      }
     },
     "confidence": {
      "type": "number",
      "format": "double"
     },
     "proof_steps": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "nullable": true
     },
     "query": {
      "type": "string"
     },
     "result": {
      "type": "boolean"
     }
    }
   },
   "RAGQueryRequest": {
    "type": "object",
    "description": "Request body for RAG query",
    "required": [
     "query"
    ],
    "properties": {
     "include_sources": {
      "type": "boolean",
      "nullable": true
     },
     "max_context_triples": {
      "type": "integer",
      "nullable": true,
      "minimum": 0
     },
     "model": {
      "type": "string",
      "nullable": true
     },
     "query": {
      "type": "string"
     },
     "strategy": {
      "type": "string",
      "nullable": true
     },
     "verify": {
      "type": "boolean",
      "nullable": true
     }
    }
   },
   "RAGQueryResponse": {
    "type": "object",
    "description": "Response for RAG query",
    "required": [
     "answer",
     "verified",
     "confidence",
     "hallucinations",
     "sources",
     "context_triples_used"
    ],
    "properties": {
     "answer": {
      "type": "string"
     },
     "confidence": {
      "type": "number",
      "format": "float"
     },
     "context_triples_used": {
      "type": "integer",
      "minimum": 0
     },
     "hallucinations": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/HallucinationReport"
      }
     },
     "sources": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/SourceTriple"
      }
     },
     "verified": {
      "type": "boolean"
     }
    }
   },
   "ReadyResponse": {
    "type": "object",
    "description": "Readiness probe response for Kubernetes",
    "required": [
     "status",
     "ready",
     "version"
    ],
    "properties": {
     "issues": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "List of issues blocking readiness"
     },
     "ready": {
      "type": "boolean"
     },
     "status": {
      "type": "string",
      "description": "ready | degraded"
     },
     "version": {
      "type": "string"
     },
     "warnings": {
      "type": "array",
      "items": {
       "type": "string"
      }
     }
    }
   },
   "ReasonRequest": {
    "type": "object",
    "properties": {
     "as_of_timestamp": {
      "type": "string",
      "description": "Optional RFC3339 timestamp for time-travel reasoning against a historical KB snapshot",
      "nullable": true
     },
     "include_evidence": {
      "type": "boolean",
      "description": "Include evidence/citation objects in the response",
      "nullable": true
     },
     "ir": {
      "description": "Optional pre-compiled IR. Provide exactly one of `query` or `ir`.",
      "nullable": true
     },
     "options": {
      "allOf": [
       {
        "$ref": "#/components/schemas/ReasoningOptions"
       }
      ],
      "nullable": true
     },
     "query": {
      "type": "string",
      "description": "The query to reason about",
      "nullable": true
     },
     "session_id": {
      "type": "string",
      "description": "Session ID for context persistence",
      "nullable": true
     },
     "strategy": {
      "allOf": [
       {
        "$ref": "#/components/schemas/ReasoningStrategyParam"
       }
      ],
      "nullable": true
     }
    }
   },
   "ReasonResponse": {
    "type": "object",
    "required": [
     "confidence",
     "reasoning_type",
     "metadata"
    ],
    "properties": {
     "answer": {
      "type": "string",
      "description": "The answer to the query",
      "nullable": true
     },
     "confidence": {
      "type": "number",
      "format": "float",
      "description": "Confidence score (0.0 to 1.0)"
     },
     "evidence": {
      "type": "array",
      "items": {},
      "description": "Optional evidence/citation objects supporting the answer",
      "nullable": true
     },
     "explanation": {
      "description": "Detailed explanation of reasoning steps",
      "nullable": true
     },
     "metadata": {
      "$ref": "#/components/schemas/ResponseMetadata"
     },
     "reasoning_type": {
      "type": "string",
      "description": "Type of reasoning used (symbolic, neural, hybrid)"
     },
     "session_id": {
      "type": "string",
      "description": "Session ID for follow-up queries",
      "nullable": true
     }
    }
   },
   "ReasoningOptions": {
    "type": "object",
    "properties": {
     "confidence_threshold": {
      "type": "number",
      "format": "float",
      "description": "Minimum confidence threshold",
      "nullable": true
     },
     "include_explanation": {
      "type": "boolean",
      "description": "Include detailed explanation in response",
      "nullable": true
     },
     "max_depth": {
      "type": "integer",
      "description": "Maximum reasoning depth",
      "nullable": true,
      "minimum": 0
     },
     "neural_weight": {
      "type": "number",
      "format": "float",
      "description": "Weight for neural vs symbolic (0.0 = fully symbolic, 1.0 = fully neural)",
      "nullable": true
     }
    }
   },
   "ReasoningStrategyParam": {
    "type": "string",
    "enum": [
     "symbolic_first",
     "neural_first",
     "hybrid",
     "cascading",
     "ensemble",
     "auto",
     "ns_rag"
    ]
   },
   "RecentDecisionsResponse": {
    "type": "object",
    "description": "A page of recent decision analytics rows.",
    "required": [
     "records",
     "limit"
    ],
    "properties": {
     "has_more": {
      "type": "boolean",
      "description": "True when more records exist beyond this page, so a caller knows to\nkeep going rather than guessing from a short page."
     },
     "limit": {
      "type": "integer",
      "description": "The effective limit applied to this page.",
      "minimum": 0
     },
     "offset": {
      "type": "integer",
      "description": "The offset this page started at.",
      "minimum": 0
     },
     "records": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/DecisionRecord"
      }
     }
    }
   },
   "RecordOutcomeByRefRequest": {
    "type": "object",
    "description": "Body for `POST /v1/decisions/outcome-by-ref`.",
    "required": [
     "external_ref",
     "outcome"
    ],
    "properties": {
     "external_ref": {
      "type": "string",
      "description": "The client correlation key the decision was made about (order id, case\nid, claim number) \u2014 supplied as `external_ref` on the decision request."
     },
     "outcome": {
      "type": "string",
      "description": "`honored` | `reversed` | `overridden` | `escalated`."
     }
    }
   },
   "RecordOutcomeRequest": {
    "type": "object",
    "description": "Body for `POST /v1/decisions/{id}/outcome`.",
    "required": [
     "outcome"
    ],
    "properties": {
     "outcome": {
      "type": "string",
      "description": "`honored` | `reversed` | `overridden` | `escalated`."
     }
    }
   },
   "RecordOutcomeResponse": {
    "type": "object",
    "required": [
     "recorded"
    ],
    "properties": {
     "recorded": {
      "type": "boolean"
     }
    }
   },
   "RecursiveChatActionRuntime": {
    "type": "object",
    "required": [
     "lifecycle_stage",
     "prepared_action_types",
     "approved_action_types",
     "review_required_action_types",
     "blocked_action_types",
     "executed_action_types"
    ],
    "properties": {
     "approved_action_types": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "blocked_action_types": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "executed_action_types": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "execution_receipt": {
      "allOf": [
       {
        "$ref": "#/components/schemas/ChatExecutionReceipt"
       }
      ],
      "nullable": true
     },
     "lifecycle_stage": {
      "type": "string"
     },
     "prepared_action_types": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "review_required_action_types": {
      "type": "array",
      "items": {
       "type": "string"
      }
     }
    }
   },
   "RecursiveChatContextSummary": {
    "type": "object",
    "required": [
     "hydrated_entities",
     "hydrated_triples",
     "hydrated_rules",
     "request_facts",
     "request_rules"
    ],
    "properties": {
     "hydrated_entities": {
      "type": "integer",
      "minimum": 0
     },
     "hydrated_rules": {
      "type": "integer",
      "minimum": 0
     },
     "hydrated_triples": {
      "type": "integer",
      "minimum": 0
     },
     "request_facts": {
      "type": "integer",
      "minimum": 0
     },
     "request_rules": {
      "type": "integer",
      "minimum": 0
     },
     "skipped_rule_names": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Names of the skipped rules, capped for response size."
     },
     "skipped_rules": {
      "type": "integer",
      "description": "Org rules that could NOT be represented in the chat rule language and\nwere therefore not applied \u2014 today, rules with a negated head (the\nchat engine has no negated conclusion) and rules with terms that do\nnot convert. Reported rather than silently dropped: a caller reasoning\nabout a policy needs to know part of it was not in force, especially\nwhen the dropped part is a prohibition.",
      "minimum": 0
     }
    }
   },
   "RecursiveChatCost": {
    "type": "object",
    "required": [
     "estimated_cost_units",
     "elapsed_ms",
     "iterations",
     "max_depth_reached",
     "symbolic_steps",
     "neural_steps",
     "planner_steps",
     "billable_outcome",
     "outcome_cost_microdollars",
     "billing_tier",
     "api_surface"
    ],
    "properties": {
     "api_surface": {
      "type": "string"
     },
     "billable_outcome": {
      "type": "boolean"
     },
     "billing_tier": {
      "type": "string"
     },
     "elapsed_ms": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "estimated_cost_units": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "iterations": {
      "type": "integer",
      "minimum": 0
     },
     "max_depth_reached": {
      "type": "integer",
      "minimum": 0
     },
     "neural_steps": {
      "type": "integer",
      "minimum": 0
     },
     "outcome_cost_microdollars": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "planner_steps": {
      "type": "integer",
      "minimum": 0
     },
     "symbolic_steps": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "RecursiveChatDecomposition": {
    "type": "object",
    "required": [
     "goal",
     "subtasks"
    ],
    "properties": {
     "goal": {
      "type": "string"
     },
     "subtasks": {
      "type": "array",
      "items": {
       "type": "string"
      }
     }
    }
   },
   "RecursiveChatFactInput": {
    "type": "object",
    "required": [
     "predicate"
    ],
    "properties": {
     "confidence": {
      "type": "number",
      "format": "double",
      "nullable": true
     },
     "predicate": {
      "$ref": "#/components/schemas/RecursiveChatPredicateInput"
     },
     "source": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "RecursiveChatFactView": {
    "type": "object",
    "required": [
     "predicate",
     "args",
     "confidence"
    ],
    "properties": {
     "args": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "confidence": {
      "type": "number",
      "format": "double"
     },
     "predicate": {
      "type": "string"
     },
     "source": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "RecursiveChatKbLimits": {
    "type": "object",
    "properties": {
     "max_entities": {
      "type": "integer",
      "nullable": true,
      "minimum": 0
     },
     "max_properties_per_entity": {
      "type": "integer",
      "nullable": true,
      "minimum": 0
     },
     "max_rules": {
      "type": "integer",
      "nullable": true,
      "minimum": 0
     },
     "max_triples": {
      "type": "integer",
      "nullable": true,
      "minimum": 0
     }
    }
   },
   "RecursiveChatMessage": {
    "type": "object",
    "required": [
     "role",
     "content"
    ],
    "properties": {
     "content": {
      "type": "string"
     },
     "role": {
      "type": "string"
     }
    }
   },
   "RecursiveChatMode": {
    "type": "string",
    "enum": [
     "fast",
     "accurate",
     "safe"
    ]
   },
   "RecursiveChatPredicateInput": {
    "type": "object",
    "required": [
     "name",
     "args"
    ],
    "properties": {
     "args": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Arg"
      }
     },
     "name": {
      "type": "string"
     },
     "negated": {
      "type": "boolean",
      "description": "Negation-as-failure for a rule CONDITION: `not fraud_flagged(?o, ?r)`.\nMeaningful only on rule conditions (ignored on facts and conclusions).\nDefaulted and skipped-when-false so existing payloads are unchanged.\nWithout this the negation was silently dropped and the condition read as\nPOSITIVE \u2014 a fraud-flagged subject slipped a `not fraud_flagged` guard."
     }
    }
   },
   "RecursiveChatProof": {
    "type": "object",
    "required": [
     "cited_rules",
     "symbolic_steps",
     "neural_steps",
     "planner_steps",
     "completed_tasks"
    ],
    "properties": {
     "cited_rules": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "completed_tasks": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "neural_steps": {
      "type": "integer",
      "minimum": 0
     },
     "planner_steps": {
      "type": "integer",
      "minimum": 0
     },
     "symbolic_steps": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "RecursiveChatRequest": {
    "type": "object",
    "required": [
     "messages"
    ],
    "properties": {
     "api_surface": {
      "type": "string",
      "nullable": true
     },
     "confidence_threshold": {
      "type": "number",
      "format": "double",
      "nullable": true
     },
     "decompositions": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/RecursiveChatDecomposition"
      },
      "nullable": true
     },
     "facts": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/RecursiveChatFactInput"
      },
      "nullable": true
     },
     "goal": {
      "type": "string",
      "nullable": true
     },
     "hydrate_org_context": {
      "type": "boolean",
      "nullable": true
     },
     "include_facts": {
      "type": "boolean",
      "nullable": true
     },
     "include_trace": {
      "type": "boolean",
      "nullable": true
     },
     "kb_limits": {
      "allOf": [
       {
        "$ref": "#/components/schemas/RecursiveChatKbLimits"
       }
      ],
      "nullable": true
     },
     "max_depth": {
      "type": "integer",
      "nullable": true,
      "minimum": 0
     },
     "max_iterations": {
      "type": "integer",
      "nullable": true,
      "minimum": 0
     },
     "messages": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/RecursiveChatMessage"
      }
     },
     "mode": {
      "allOf": [
       {
        "$ref": "#/components/schemas/RecursiveChatMode"
       }
      ],
      "nullable": true
     },
     "org_id": {
      "type": "string",
      "nullable": true
     },
     "rules": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/RecursiveChatRuleInput"
      },
      "nullable": true
     },
     "session_id": {
      "type": "string",
      "nullable": true
     },
     "target": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "RecursiveChatResponse": {
    "type": "object",
    "required": [
     "trace_id",
     "org_id",
     "goal",
     "mode",
     "success",
     "assistant_message",
     "explanation",
     "proof",
     "uncertainty",
     "cost",
     "context",
     "suggested_actions",
     "tool_calls",
     "action_results",
     "action_runtime"
    ],
    "properties": {
     "action_results": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ActionExecutionResult"
      }
     },
     "action_runtime": {
      "$ref": "#/components/schemas/RecursiveChatActionRuntime"
     },
     "answer": {
      "nullable": true
     },
     "assistant_message": {
      "type": "string"
     },
     "audit_trace": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/RecursiveChatTraceStep"
      },
      "nullable": true
     },
     "context": {
      "$ref": "#/components/schemas/RecursiveChatContextSummary"
     },
     "cost": {
      "$ref": "#/components/schemas/RecursiveChatCost"
     },
     "explanation": {
      "type": "string"
     },
     "facts": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/RecursiveChatFactView"
      },
      "nullable": true
     },
     "goal": {
      "type": "string"
     },
     "mode": {
      "$ref": "#/components/schemas/RecursiveChatMode"
     },
     "org_id": {
      "type": "string"
     },
     "proof": {
      "$ref": "#/components/schemas/RecursiveChatProof"
     },
     "session_id": {
      "type": "string",
      "nullable": true
     },
     "success": {
      "type": "boolean"
     },
     "suggested_actions": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/SuggestedAction"
      }
     },
     "tool_calls": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ToolCall"
      }
     },
     "trace": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/RecursiveChatTraceStep"
      },
      "nullable": true
     },
     "trace_id": {
      "type": "string"
     },
     "uncertainty": {
      "$ref": "#/components/schemas/RecursiveChatUncertainty"
     },
     "validation": {
      "$ref": "#/components/schemas/RecursiveChatValidation"
     }
    }
   },
   "RecursiveChatRuleInput": {
    "type": "object",
    "required": [
     "name",
     "if",
     "then"
    ],
    "properties": {
     "category": {
      "type": "string",
      "nullable": true
     },
     "constraints": {
      "type": "array",
      "items": {}
     },
     "description": {
      "type": "string",
      "nullable": true
     },
     "effect": {
      "allOf": [
       {
        "$ref": "#/components/schemas/RuleEffect"
       }
      ],
      "nullable": true
     },
     "enabled": {
      "type": "boolean",
      "nullable": true
     },
     "id": {
      "type": "string",
      "nullable": true
     },
     "if": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/RecursiveChatPredicateInput"
      }
     },
     "name": {
      "type": "string"
     },
     "priority": {
      "type": "integer",
      "format": "int32",
      "nullable": true
     },
     "then": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/RecursiveChatPredicateInput"
      }
     }
    }
   },
   "RecursiveChatTraceStep": {
    "type": "object",
    "required": [
     "step_type",
     "description",
     "duration_ms"
    ],
    "properties": {
     "description": {
      "type": "string"
     },
     "duration_ms": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "input": {
      "nullable": true
     },
     "output": {
      "nullable": true
     },
     "step_type": {
      "type": "string"
     },
     "task_id": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "RecursiveChatUncertainty": {
    "type": "object",
    "required": [
     "epistemic",
     "aleatoric",
     "total",
     "requires_human_review"
    ],
    "properties": {
     "aleatoric": {
      "type": "number",
      "format": "double"
     },
     "epistemic": {
      "type": "number",
      "format": "double"
     },
     "mandatory_review": {
      "type": "boolean",
      "description": "True when review is required for a reason a symbolic proof must NOT\noverride: a safety emergency (medical-emergency language) or the solver\nexplicitly declining. A strong, request-bound symbolic permit may suppress\na review driven only by the soft uncertainty threshold, but never this \u2014\napproving a grounded refund is fine, but a message also reporting a severe\nreaction still escalates to a human."
     },
     "requires_human_review": {
      "type": "boolean"
     },
     "total": {
      "type": "number",
      "format": "double"
     }
    }
   },
   "RecursiveChatValidation": {
    "type": "object",
    "required": [
     "llm_provider",
     "llm_backend_live",
     "grounding_status",
     "grounded_target_count",
     "grounded_entity_count",
     "cited_rule_count",
     "symbolic_step_count",
     "proof_score",
     "proof_status",
     "validation_level",
     "action_execution_eligible",
     "action_execution_reason"
    ],
    "properties": {
     "action_execution_eligible": {
      "type": "boolean"
     },
     "action_execution_reason": {
      "type": "string"
     },
     "cited_rule_count": {
      "type": "integer",
      "minimum": 0
     },
     "grounded_entity_count": {
      "type": "integer",
      "minimum": 0
     },
     "grounded_target_count": {
      "type": "integer",
      "minimum": 0
     },
     "grounding_status": {
      "type": "string"
     },
     "llm_backend_live": {
      "type": "boolean"
     },
     "llm_provider": {
      "type": "string"
     },
     "proof_score": {
      "type": "number",
      "format": "double"
     },
     "proof_status": {
      "type": "string"
     },
     "symbolic_step_count": {
      "type": "integer",
      "minimum": 0
     },
     "validation_level": {
      "type": "string"
     }
    }
   },
   "RecursiveTraceStep": {
    "type": "object",
    "required": [
     "step",
     "stage",
     "focus",
     "output",
     "confidence"
    ],
    "properties": {
     "confidence": {
      "type": "number",
      "format": "double"
     },
     "focus": {
      "type": "string"
     },
     "output": {
      "type": "string"
     },
     "stage": {
      "type": "string"
     },
     "step": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "RecursiveUsage": {
    "type": "object",
    "description": "Recursive runtime usage metrics for the current tenant.",
    "required": [
     "requests_month",
     "review_required_responses_month",
     "tool_call_responses_month",
     "ready_action_responses_month",
     "grounded_outcome_rate",
     "review_required_rate"
    ],
    "properties": {
     "grounded_outcome_rate": {
      "type": "number",
      "format": "double",
      "description": "Grounded outcome rate across recursive requests."
     },
     "ready_action_responses_month": {
      "type": "integer",
      "format": "int64",
      "description": "Number of recursive responses that returned one or more ready actions.",
      "minimum": 0
     },
     "requests_month": {
      "type": "integer",
      "format": "int64",
      "description": "Number of recursive chat requests this month.",
      "minimum": 0
     },
     "review_required_rate": {
      "type": "number",
      "format": "double",
      "description": "Review-required rate across recursive requests."
     },
     "review_required_responses_month": {
      "type": "integer",
      "format": "int64",
      "description": "Number of recursive responses that required human review.",
      "minimum": 0
     },
     "tool_call_responses_month": {
      "type": "integer",
      "format": "int64",
      "description": "Number of recursive responses that returned one or more tool calls.",
      "minimum": 0
     }
    }
   },
   "RefusalGap": {
    "type": "object",
    "description": "A recurring missing premise across refused decisions \u2014 a KB coverage gap.\nHigh `count` = many decisions refused for lack of this premise; add a\nrule/fact/connector for it or seed the data.",
    "required": [
     "predicate",
     "count"
    ],
    "properties": {
     "count": {
      "type": "integer",
      "minimum": 0
     },
     "predicate": {
      "type": "string"
     }
    }
   },
   "RefusalRoadmap": {
    "type": "object",
    "description": "The integration roadmap for an org over a window.",
    "required": [
     "refused_decisions",
     "gaps"
    ],
    "properties": {
     "gaps": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/RefusalRoadmapGap"
      },
      "description": "Gaps, highest-leverage first."
     },
     "refused_decisions": {
      "type": "integer",
      "description": "Total refused decisions in the window (the denominator for shares).",
      "minimum": 0
     }
    }
   },
   "RefusalRoadmapGap": {
    "type": "object",
    "description": "One prioritized entry in the integration roadmap.",
    "required": [
     "predicate",
     "blocked_refusals",
     "share_of_refusals",
     "recommendation",
     "count"
    ],
    "properties": {
     "blocked_refusals": {
      "type": "integer",
      "description": "How many refused decisions this premise blocked in the window.",
      "minimum": 0
     },
     "count": {
      "type": "integer",
      "description": "Back-compat alias of `blocked_refusals`.",
      "minimum": 0
     },
     "predicate": {
      "type": "string",
      "description": "The premise the engine kept asking for and not getting."
     },
     "recommendation": {
      "type": "string",
      "description": "Plain-language, actionable next step."
     },
     "share_of_refusals": {
      "type": "number",
      "format": "double",
      "description": "Its share of all refusals in the window, in [0, 1]."
     }
    }
   },
   "RegisterPredicateRequest": {
    "type": "object",
    "description": "Request to register a predicate signature",
    "required": [
     "name",
     "arg_types"
    ],
    "properties": {
     "arg_types": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Argument types"
     },
     "doc": {
      "type": "string",
      "description": "Documentation",
      "nullable": true
     },
     "name": {
      "type": "string",
      "description": "Predicate name"
     },
     "return_type": {
      "type": "string",
      "description": "Optional return type (for functional predicates)",
      "nullable": true
     }
    },
    "example": {
     "arg_types": [
      "entity",
      "location"
     ],
     "doc": "Entity X lived in location Y",
     "name": "lived_in"
    }
   },
   "RegisterSubtypeRequest": {
    "type": "object",
    "description": "Request to register a subtype relationship",
    "required": [
     "subtype",
     "supertype"
    ],
    "properties": {
     "subtype": {
      "type": "string",
      "description": "The subtype"
     },
     "supertype": {
      "type": "string",
      "description": "The supertype"
     }
    },
    "example": {
     "subtype": "philosopher",
     "supertype": "person"
    }
   },
   "RenderMacroRequest": {
    "type": "object",
    "properties": {
     "context": {
      "type": "object",
      "description": "Values for the macro's merge fields.",
      "additionalProperties": {}
     }
    }
   },
   "RenderMacroResponse": {
    "type": "object",
    "required": [
     "macro_name",
     "rendered",
     "missing_slots",
     "ready_to_send",
     "tool_blocked_on"
    ],
    "properties": {
     "macro_name": {
      "type": "string"
     },
     "missing_slots": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Slots with no value supplied. Non-empty means DO NOT SEND: a macro is\nonly safe once every field it promises is filled."
     },
     "ready_to_send": {
      "type": "boolean"
     },
     "rendered": {
      "type": "string"
     },
     "tool_blocked_on": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Unresolvable tool arguments. A partially-bound refund is worse than no\nrefund, so the call is withheld rather than sent incomplete."
     },
     "tool_call": {
      "nullable": true
     }
    }
   },
   "ReplyRequest": {
    "allOf": [
     {
      "$ref": "#/components/schemas/DecisionRequest"
     },
     {
      "type": "object",
      "properties": {
       "context": {
        "type": "object",
        "description": "Merge-field values for the macro and its tool call: customer name,\norder id, amount. These are the caller's own data, never inferred from\nthe customer's message.",
        "additionalProperties": {}
       }
      }
     }
    ]
   },
   "ReplyResponse": {
    "type": "object",
    "required": [
     "decision"
    ],
    "properties": {
     "decision": {
      "$ref": "#/components/schemas/DecisionResponse"
     },
     "reply": {
      "allOf": [
       {
        "$ref": "#/components/schemas/DraftedReply"
       }
      ],
      "nullable": true
     },
     "requires_human": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Why a human is needed, when one is. Empty means this can ship."
     },
     "tool_blocked_on": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Tool arguments that could not be bound. Non-empty means the tool was\nwithheld \u2014 and so was the reply, if it announces that action."
     },
     "tool_call": {
      "nullable": true
     }
    }
   },
   "ResponseInputItemsList": {
    "type": "object",
    "required": [
     "object",
     "data"
    ],
    "properties": {
     "data": {
      "type": "array",
      "items": {}
     },
     "object": {
      "type": "string"
     }
    }
   },
   "ResponseMetadata": {
    "type": "object",
    "required": [
     "query_time_ms",
     "facts_used",
     "rules_fired"
    ],
    "properties": {
     "facts_used": {
      "type": "integer",
      "description": "Number of facts used in reasoning",
      "minimum": 0
     },
     "query_time_ms": {
      "type": "integer",
      "format": "int64",
      "description": "Query processing time in milliseconds",
      "minimum": 0
     },
     "rules_fired": {
      "type": "integer",
      "description": "Number of rules fired during inference",
      "minimum": 0
     }
    }
   },
   "RetryFact": {
    "type": "object",
    "description": "The fact shape to echo back on retry to satisfy a missing premise \u2014\nmirrors a request `facts` element.",
    "required": [
     "predicate"
    ],
    "properties": {
     "predicate": {
      "$ref": "#/components/schemas/RetryPredicate"
     }
    }
   },
   "RetryPredicate": {
    "type": "object",
    "required": [
     "name",
     "args"
    ],
    "properties": {
     "args": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "name": {
      "type": "string"
     }
    }
   },
   "ReviewCandidateRequest": {
    "type": "object",
    "required": [
     "approve"
    ],
    "properties": {
     "approve": {
      "type": "boolean"
     },
     "reviewer": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "ReviewCandidateResponse": {
    "type": "object",
    "required": [
     "candidate_id",
     "status"
    ],
    "properties": {
     "candidate_id": {
      "type": "string"
     },
     "status": {
      "type": "string"
     }
    }
   },
   "RevisionEventResponse": {
    "type": "object",
    "description": "A single revision event",
    "required": [
     "revision_type",
     "old_confidence",
     "new_confidence",
     "source",
     "timestamp"
    ],
    "properties": {
     "new_confidence": {
      "type": "number",
      "format": "float"
     },
     "old_confidence": {
      "type": "number",
      "format": "float"
     },
     "revision_type": {
      "type": "string"
     },
     "source": {
      "type": "string"
     },
     "timestamp": {
      "type": "string"
     }
    }
   },
   "Rule": {
    "type": "object",
    "description": "A logical rule in Horn clause form: head :- body\nIf all conditions in body are satisfied, head is inferred",
    "required": [
     "id",
     "name",
     "org_id",
     "head",
     "body",
     "confidence",
     "priority",
     "enabled"
    ],
    "properties": {
     "body": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Atom"
      },
      "description": "The conditions (body) of the rule"
     },
     "confidence": {
      "type": "number",
      "format": "float",
      "description": "Confidence factor for this rule (0.0 - 1.0)"
     },
     "description": {
      "type": "string",
      "nullable": true
     },
     "effect": {
      "allOf": [
       {
        "$ref": "#/components/schemas/RuleEffect"
       }
      ],
      "nullable": true
     },
     "enabled": {
      "type": "boolean",
      "description": "Whether this rule is enabled"
     },
     "head": {
      "$ref": "#/components/schemas/Atom"
     },
     "id": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "org_id": {
      "type": "string",
      "description": "Organization ID for multi-tenant isolation"
     },
     "priority": {
      "type": "integer",
      "format": "int32",
      "description": "Priority for rule ordering"
     },
     "test_cases": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/RuleTestCase"
      },
      "description": "First-class rule tests used for quality gates and regression checks."
     }
    }
   },
   "RuleAtomRequest": {
    "type": "object",
    "required": [
     "predicate",
     "args"
    ],
    "properties": {
     "args": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "negated": {
      "type": "boolean",
      "nullable": true
     },
     "predicate": {
      "type": "string"
     }
    }
   },
   "RuleDiffItem": {
    "type": "object",
    "required": [
     "id",
     "name",
     "org_id",
     "enabled",
     "priority",
     "confidence",
     "head_predicate",
     "body_predicates"
    ],
    "properties": {
     "body_predicates": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "confidence": {
      "type": "number",
      "format": "float"
     },
     "enabled": {
      "type": "boolean"
     },
     "head_predicate": {
      "type": "string"
     },
     "id": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "org_id": {
      "type": "string"
     },
     "priority": {
      "type": "integer",
      "format": "int32"
     }
    }
   },
   "RuleDiffSection": {
    "type": "object",
    "required": [
     "added",
     "removed",
     "modified"
    ],
    "properties": {
     "added": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/RuleDiffItem"
      }
     },
     "modified": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ModifiedRuleDiffItem"
      }
     },
     "removed": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/RuleDiffItem"
      }
     }
    }
   },
   "RuleEffect": {
    "type": "string",
    "description": "Explicit policy intent of a rule: what a satisfied rule *means* for the\naction under authorization. Preferred over inferring intent from\npredicate-name conventions (`may_*`, `denied`, \u2026), which breaks for\ntenant-specific or non-English vocabularies.",
    "enum": [
     "permit",
     "deny",
     "review"
    ]
   },
   "RuleResponse": {
    "type": "object",
    "description": "Response for rule operations",
    "required": [
     "id",
     "name",
     "enabled",
     "priority",
     "confidence",
     "head_predicate",
     "head_args",
     "body_count",
     "test_case_count",
     "test_cases"
    ],
    "properties": {
     "body_count": {
      "type": "integer",
      "minimum": 0
     },
     "confidence": {
      "type": "number",
      "format": "float"
     },
     "description": {
      "type": "string",
      "nullable": true
     },
     "enabled": {
      "type": "boolean"
     },
     "head_args": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "head_predicate": {
      "type": "string"
     },
     "id": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "priority": {
      "type": "integer",
      "format": "int32"
     },
     "test_case_count": {
      "type": "integer",
      "minimum": 0
     },
     "test_cases": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/RuleTestCaseResponse"
      }
     }
    }
   },
   "RuleTestCase": {
    "type": "object",
    "description": "A rule-level test case with explicit bindings and expected output.",
    "required": [
     "id",
     "should_fire"
    ],
    "properties": {
     "expected_output": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      }
     },
     "id": {
      "type": "string"
     },
     "input_bindings": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      }
     },
     "name": {
      "type": "string",
      "nullable": true
     },
     "should_fire": {
      "type": "boolean"
     }
    }
   },
   "RuleTestCaseRequest": {
    "type": "object",
    "properties": {
     "expected_output": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      },
      "nullable": true
     },
     "input_bindings": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      },
      "nullable": true
     },
     "name": {
      "type": "string",
      "nullable": true
     },
     "should_fire": {
      "type": "boolean",
      "nullable": true
     }
    }
   },
   "RuleTestCaseResponse": {
    "type": "object",
    "required": [
     "id",
     "input_bindings",
     "expected_output",
     "should_fire"
    ],
    "properties": {
     "expected_output": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      }
     },
     "id": {
      "type": "string"
     },
     "input_bindings": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      }
     },
     "name": {
      "type": "string",
      "nullable": true
     },
     "should_fire": {
      "type": "boolean"
     }
    }
   },
   "RuleUsageStat": {
    "type": "object",
    "description": "Per-rule usage over a window: how often a rule was CITED on a proof vs\nDROPPED as noise (fired during hydration but unrelated to the decision).\nA rule with high `noise_count` and near-zero `cited_count` is a standing\nrule firing on every decision without ever being relevant \u2014 a demotion\ncandidate (mined `flywheel:*` rules can be auto-disabled; curated policy\nis operator-gated).",
    "required": [
     "rule",
     "cited_count",
     "noise_count"
    ],
    "properties": {
     "cited_count": {
      "type": "integer",
      "minimum": 0
     },
     "noise_count": {
      "type": "integer",
      "minimum": 0
     },
     "rule": {
      "type": "string"
     }
    }
   },
   "RunCodeRequest": {
    "type": "object",
    "description": "Request to execute code inline (creates sandbox, runs, destroys).",
    "required": [
     "language",
     "code"
    ],
    "properties": {
     "code": {
      "type": "string",
      "description": "Source code to execute."
     },
     "env": {
      "type": "object",
      "description": "Environment variables.",
      "additionalProperties": {
       "type": "string"
      },
      "nullable": true
     },
     "language": {
      "type": "string",
      "description": "Programming language (\"python\", \"node\", \"bash\", \"rust\")."
     },
     "timeout_seconds": {
      "type": "integer",
      "format": "int32",
      "description": "Execution timeout in seconds (default: 30).",
      "nullable": true,
      "minimum": 0
     }
    }
   },
   "RunCodeResponse": {
    "type": "object",
    "description": "Response from inline code execution.",
    "required": [
     "execution_id",
     "exit_code",
     "stdout",
     "stderr",
     "duration_ms",
     "language"
    ],
    "properties": {
     "duration_ms": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "execution_id": {
      "type": "string"
     },
     "exit_code": {
      "type": "integer",
      "format": "int32"
     },
     "language": {
      "type": "string"
     },
     "stderr": {
      "type": "string"
     },
     "stdout": {
      "type": "string"
     }
    }
   },
   "SandboxActionCandidate": {
    "type": "object",
    "properties": {
     "action": {
      "allOf": [
       {
        "$ref": "#/components/schemas/CanonicalSandboxAction"
       }
      ],
      "nullable": true
     },
     "payload": {},
     "raw_text": {
      "type": "string",
      "nullable": true
     },
     "route": {
      "type": "string",
      "nullable": true
     },
     "tool_name": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "SandboxExpectedEffects": {
    "type": "object",
    "required": [
     "touched_paths",
     "egress_domains",
     "requires_confirmation",
     "may_execute_code"
    ],
    "properties": {
     "egress_domains": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "may_execute_code": {
      "type": "boolean"
     },
     "recommended_runtime": {
      "type": "string",
      "nullable": true
     },
     "requires_confirmation": {
      "type": "boolean"
     },
     "touched_paths": {
      "type": "array",
      "items": {
       "type": "string"
      }
     }
    }
   },
   "SandboxMachineProofNode": {
    "type": "object",
    "required": [
     "position",
     "input",
     "symbol",
     "value"
    ],
    "properties": {
     "input": {
      "type": "string"
     },
     "position": {
      "type": "integer",
      "minimum": 0
     },
     "symbol": {
      "type": "string"
     },
     "value": {
      "type": "string"
     }
    }
   },
   "SandboxObservedResult": {
    "type": "object",
    "properties": {
     "changed_paths": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "contacted_domains": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "exit_code": {
      "type": "integer",
      "format": "int32",
      "nullable": true
     },
     "output_truncated": {
      "type": "boolean"
     }
    }
   },
   "SandboxPolicyApiResponse": {
    "type": "object",
    "required": [
     "evaluation",
     "machine_verdict",
     "final_verdict",
     "machine_confidence",
     "machine_score",
     "machine_override",
     "grounded_inputs",
     "machine_proof",
     "evidence_ids",
     "processing_time_ms"
    ],
    "properties": {
     "evaluation": {
      "$ref": "#/components/schemas/SandboxPolicyEvaluation"
     },
     "evidence_ids": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "final_verdict": {
      "$ref": "#/components/schemas/SandboxPolicyVerdict"
     },
     "grounded_inputs": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "machine_confidence": {
      "type": "number",
      "format": "double"
     },
     "machine_override": {
      "type": "boolean"
     },
     "machine_proof": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/SandboxMachineProofNode"
      }
     },
     "machine_score": {
      "type": "integer",
      "format": "int32"
     },
     "machine_verdict": {
      "$ref": "#/components/schemas/SandboxPolicyVerdict"
     },
     "processing_time_ms": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     }
    }
   },
   "SandboxPolicyContext": {
    "type": "object",
    "properties": {
     "active_repl_sessions": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "allowed_egress_domains": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "allowed_read_roots": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "allowed_write_roots": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "budget_available": {
      "type": "boolean",
      "nullable": true
     },
     "enabled_mcp_servers": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "gui_grounded": {
      "type": "boolean",
      "nullable": true
     },
     "mounted_secrets": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "requested_runtime": {
      "type": "string",
      "nullable": true
     },
     "runtime_class": {
      "type": "string",
      "nullable": true
     },
     "sandbox_role": {
      "type": "string",
      "nullable": true
     },
     "sandbox_state": {
      "type": "string",
      "nullable": true
     },
     "workspace_root": {
      "type": "string"
     }
    }
   },
   "SandboxPolicyEvaluation": {
    "type": "object",
    "required": [
     "canonical_action",
     "rule_verdict",
     "rule_score",
     "canonical_action_hash",
     "triggered_rules",
     "proof_trace",
     "evidence",
     "expected_effects"
    ],
    "properties": {
     "canonical_action": {
      "$ref": "#/components/schemas/CanonicalSandboxAction"
     },
     "canonical_action_hash": {
      "type": "string"
     },
     "evidence": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/SandboxPolicyEvidence"
      }
     },
     "expected_effects": {
      "$ref": "#/components/schemas/SandboxExpectedEffects"
     },
     "proof_trace": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/SandboxProofStep"
      }
     },
     "recommended_runtime": {
      "type": "string",
      "nullable": true
     },
     "rewritten_action": {
      "allOf": [
       {
        "$ref": "#/components/schemas/CanonicalSandboxAction"
       }
      ],
      "nullable": true
     },
     "rule_score": {
      "type": "integer",
      "format": "int32"
     },
     "rule_verdict": {
      "$ref": "#/components/schemas/SandboxPolicyVerdict"
     },
     "triggered_rules": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/SandboxPolicyRuleMatch"
      }
     }
    }
   },
   "SandboxPolicyEvidence": {
    "type": "object",
    "required": [
     "key",
     "value"
    ],
    "properties": {
     "key": {
      "type": "string"
     },
     "value": {
      "type": "string"
     }
    }
   },
   "SandboxPolicyPhase": {
    "type": "string",
    "enum": [
     "admission",
     "verification"
    ]
   },
   "SandboxPolicyRequest": {
    "type": "object",
    "required": [
     "org_id"
    ],
    "properties": {
     "candidate": {
      "$ref": "#/components/schemas/SandboxActionCandidate"
     },
     "context": {
      "$ref": "#/components/schemas/SandboxPolicyContext"
     },
     "observed": {
      "allOf": [
       {
        "$ref": "#/components/schemas/SandboxObservedResult"
       }
      ],
      "nullable": true
     },
     "org_id": {
      "type": "string"
     },
     "phase": {
      "$ref": "#/components/schemas/SandboxPolicyPhase"
     },
     "sandbox_id": {
      "type": "string",
      "nullable": true
     },
     "session_id": {
      "type": "string",
      "nullable": true
     },
     "user_id": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "SandboxPolicyRuleMatch": {
    "type": "object",
    "required": [
     "rule_id",
     "verdict",
     "reason",
     "weight"
    ],
    "properties": {
     "reason": {
      "type": "string"
     },
     "rule_id": {
      "type": "string"
     },
     "verdict": {
      "$ref": "#/components/schemas/SandboxPolicyVerdict"
     },
     "weight": {
      "type": "integer",
      "format": "int32"
     }
    }
   },
   "SandboxPolicyVerdict": {
    "type": "string",
    "enum": [
     "allow",
     "rewrite",
     "ask_user",
     "deny"
    ]
   },
   "SandboxProofStep": {
    "type": "object",
    "required": [
     "stage",
     "outcome",
     "detail"
    ],
    "properties": {
     "detail": {
      "type": "string"
     },
     "outcome": {
      "type": "string"
     },
     "stage": {
      "type": "string"
     }
    }
   },
   "SaveCheckpointRequest": {
    "type": "object",
    "description": "Request to save model checkpoint",
    "required": [
     "name",
     "version"
    ],
    "properties": {
     "description": {
      "type": "string",
      "description": "Optional description",
      "nullable": true
     },
     "name": {
      "type": "string",
      "description": "Checkpoint name"
     },
     "tags": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Tags for organization"
     },
     "version": {
      "type": "string",
      "description": "Version string"
     }
    }
   },
   "SaveCheckpointResponse": {
    "type": "object",
    "description": "Response for save checkpoint",
    "required": [
     "checkpoint_id",
     "checkpoint"
    ],
    "properties": {
     "checkpoint": {
      "$ref": "#/components/schemas/ModelCheckpoint"
     },
     "checkpoint_id": {
      "type": "string",
      "description": "Created checkpoint ID"
     }
    }
   },
   "SemanticValueRequest": {
    "oneOf": [
     {
      "type": "object",
      "required": [
       "type"
      ],
      "properties": {
       "type": {
        "type": "string",
        "enum": [
         "null"
        ]
       }
      }
     },
     {
      "type": "object",
      "required": [
       "type",
       "value"
      ],
      "properties": {
       "type": {
        "type": "string",
        "enum": [
         "integer"
        ]
       },
       "value": {
        "type": "integer",
        "format": "int64"
       }
      }
     },
     {
      "type": "object",
      "required": [
       "type",
       "value"
      ],
      "properties": {
       "type": {
        "type": "string",
        "enum": [
         "float"
        ]
       },
       "value": {
        "type": "number",
        "format": "double"
       }
      }
     },
     {
      "type": "object",
      "required": [
       "type",
       "value"
      ],
      "properties": {
       "type": {
        "type": "string",
        "enum": [
         "string"
        ]
       },
       "value": {
        "type": "string"
       }
      }
     },
     {
      "type": "object",
      "required": [
       "type",
       "value"
      ],
      "properties": {
       "type": {
        "type": "string",
        "enum": [
         "boolean"
        ]
       },
       "value": {
        "type": "boolean"
       }
      }
     },
     {
      "type": "object",
      "required": [
       "type",
       "value"
      ],
      "properties": {
       "type": {
        "type": "string",
        "enum": [
         "list"
        ]
       },
       "value": {
        "type": "array",
        "items": {
         "$ref": "#/components/schemas/SemanticValueRequest"
        }
       }
      }
     }
    ],
    "description": "Semantic value in request format",
    "discriminator": {
     "propertyName": "type"
    }
   },
   "SemanticValueResponse": {
    "oneOf": [
     {
      "type": "object",
      "required": [
       "type"
      ],
      "properties": {
       "type": {
        "type": "string",
        "enum": [
         "null"
        ]
       }
      }
     },
     {
      "type": "object",
      "required": [
       "type",
       "value"
      ],
      "properties": {
       "type": {
        "type": "string",
        "enum": [
         "integer"
        ]
       },
       "value": {
        "type": "integer",
        "format": "int64"
       }
      }
     },
     {
      "type": "object",
      "required": [
       "type",
       "value"
      ],
      "properties": {
       "type": {
        "type": "string",
        "enum": [
         "float"
        ]
       },
       "value": {
        "type": "number",
        "format": "double"
       }
      }
     },
     {
      "type": "object",
      "required": [
       "type",
       "value"
      ],
      "properties": {
       "type": {
        "type": "string",
        "enum": [
         "string"
        ]
       },
       "value": {
        "type": "string"
       }
      }
     },
     {
      "type": "object",
      "required": [
       "type",
       "value"
      ],
      "properties": {
       "type": {
        "type": "string",
        "enum": [
         "boolean"
        ]
       },
       "value": {
        "type": "boolean"
       }
      }
     },
     {
      "type": "object",
      "required": [
       "type",
       "value"
      ],
      "properties": {
       "type": {
        "type": "string",
        "enum": [
         "list"
        ]
       },
       "value": {
        "type": "array",
        "items": {
         "$ref": "#/components/schemas/SemanticValueResponse"
        }
       }
      }
     },
     {
      "type": "object",
      "required": [
       "type",
       "value"
      ],
      "properties": {
       "type": {
        "type": "string",
        "enum": [
         "function"
        ]
       },
       "value": {
        "type": "object",
        "required": [
         "name"
        ],
        "properties": {
         "name": {
          "type": "string"
         }
        }
       }
      }
     }
    ],
    "description": "Semantic value in response format",
    "discriminator": {
     "propertyName": "type"
    }
   },
   "SessionHistoryEntry": {
    "type": "object",
    "description": "Session history entry",
    "required": [
     "query",
     "confidence",
     "strategy",
     "timestamp"
    ],
    "properties": {
     "answer": {
      "type": "string",
      "description": "The answer provided (if any)",
      "nullable": true
     },
     "confidence": {
      "type": "number",
      "format": "float",
      "description": "Confidence score"
     },
     "query": {
      "type": "string",
      "description": "The query that was asked"
     },
     "strategy": {
      "type": "string",
      "description": "Strategy or mode used to answer the query"
     },
     "timestamp": {
      "type": "string",
      "description": "Timestamp of the exchange"
     }
    }
   },
   "SessionHistoryResponse": {
    "type": "object",
    "description": "Session history response",
    "required": [
     "session_id",
     "created_at",
     "last_activity",
     "history",
     "context",
     "exchange_count"
    ],
    "properties": {
     "context": {
      "type": "object",
      "description": "Current context variables",
      "additionalProperties": {
       "type": "string"
      }
     },
     "created_at": {
      "type": "string",
      "description": "Session creation time"
     },
     "exchange_count": {
      "type": "integer",
      "description": "Total number of exchanges",
      "minimum": 0
     },
     "history": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/SessionHistoryEntry"
      },
      "description": "Full conversation history"
     },
     "last_activity": {
      "type": "string",
      "description": "Last activity time"
     },
     "session_id": {
      "type": "string",
      "description": "Session ID"
     }
    }
   },
   "SessionResponse": {
    "type": "object",
    "description": "Session response returned by create/get handlers.",
    "required": [
     "session_id",
     "created_at",
     "last_activity",
     "context",
     "focus_entities"
    ],
    "properties": {
     "context": {
      "type": "object",
      "description": "Current context variables",
      "additionalProperties": {
       "type": "string"
      }
     },
     "created_at": {
      "type": "string",
      "description": "Session creation time"
     },
     "focus_entities": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Current focus entities"
     },
     "last_activity": {
      "type": "string",
      "description": "Last activity time"
     },
     "session_id": {
      "type": "string",
      "description": "Session ID"
     }
    }
   },
   "SetProgramRequest": {
    "type": "object",
    "description": "Request to set a program for a symbol",
    "required": [
     "symbol_id",
     "program"
    ],
    "properties": {
     "program": {
      "$ref": "#/components/schemas/ProgramRequest"
     },
     "symbol_id": {
      "type": "integer",
      "format": "int64",
      "description": "Symbol ID",
      "minimum": 0
     }
    }
   },
   "SlaSnapshot": {
    "type": "object",
    "description": "Point-in-time SLA metrics snapshot. Serialized by the `/status` endpoint.",
    "required": [
     "window_minutes",
     "target_uptime",
     "observed_uptime",
     "error_rate",
     "latency_p50_ms",
     "latency_p95_ms",
     "latency_p99_ms",
     "total_requests",
     "error_count",
     "client_error_count",
     "health_checks",
     "health_failures",
     "error_budget_burn_rate",
     "server_started_at",
     "generated_at"
    ],
    "properties": {
     "client_error_count": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "error_budget_burn_rate": {
      "type": "number",
      "format": "double",
      "description": "How fast we're consuming the error budget. 1.0 = on pace to exactly\nburn the entire SLA budget. >1.0 = we'll breach the SLA. <1.0 = we're\nunder budget."
     },
     "error_count": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "error_rate": {
      "type": "number",
      "format": "double"
     },
     "generated_at": {
      "type": "string",
      "format": "date-time"
     },
     "health_checks": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "health_failures": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "latency_p50_ms": {
      "type": "integer",
      "format": "int32",
      "minimum": 0
     },
     "latency_p95_ms": {
      "type": "integer",
      "format": "int32",
      "minimum": 0
     },
     "latency_p99_ms": {
      "type": "integer",
      "format": "int32",
      "minimum": 0
     },
     "observed_uptime": {
      "type": "number",
      "format": "double"
     },
     "server_started_at": {
      "type": "string",
      "format": "date-time"
     },
     "target_uptime": {
      "type": "number",
      "format": "double"
     },
     "total_requests": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "window_minutes": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "SnapshotResponse": {
    "type": "object",
    "description": "Response for snapshot endpoint",
    "required": [
     "snapshot"
    ],
    "properties": {
     "snapshot": {
      "$ref": "#/components/schemas/KBSnapshot"
     }
    }
   },
   "SoftDeleteRequest": {
    "type": "object",
    "description": "Soft delete request with reason",
    "properties": {
     "reason": {
      "type": "string",
      "description": "Reason for deletion (for audit trail)",
      "nullable": true
     }
    }
   },
   "SourceTriple": {
    "type": "object",
    "description": "A source triple used in the response",
    "required": [
     "subject",
     "predicate",
     "object",
     "confidence"
    ],
    "properties": {
     "confidence": {
      "type": "number",
      "format": "float"
     },
     "object": {
      "type": "string"
     },
     "predicate": {
      "type": "string"
     },
     "subject": {
      "type": "string"
     }
    }
   },
   "SourcesResponse": {
    "type": "object",
    "required": [
     "sources",
     "total"
    ],
    "properties": {
     "sources": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/EvidenceSourceRecord"
      }
     },
     "total": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "StatusResponse": {
    "type": "object",
    "required": [
     "state",
     "summary",
     "version",
     "region",
     "sla",
     "dependencies",
     "incidents",
     "generated_at"
    ],
    "properties": {
     "dependencies": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/DependencyStatus"
      },
      "description": "Per-dependency health breakdown."
     },
     "generated_at": {
      "type": "string",
      "format": "date-time",
      "description": "When this status document was generated."
     },
     "incidents": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/IncidentSummary"
      },
      "description": "Currently open incidents (none if empty)."
     },
     "region": {
      "type": "string",
      "description": "Deployment region (GKE cluster region or explicit NSR_REGION env)."
     },
     "sla": {
      "$ref": "#/components/schemas/SlaSnapshot"
     },
     "state": {
      "$ref": "#/components/schemas/StatusState"
     },
     "summary": {
      "type": "string",
      "description": "Single human-readable summary for a status page."
     },
     "version": {
      "type": "string",
      "description": "Service version (Cargo package version)."
     }
    }
   },
   "StatusState": {
    "type": "string",
    "enum": [
     "operational",
     "degraded",
     "outage"
    ]
   },
   "StrategyRecommendationResponse": {
    "type": "object",
    "description": "Response for strategy recommendation",
    "required": [
     "strategy",
     "confidence",
     "alternatives"
    ],
    "properties": {
     "alternatives": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Alternative strategies"
     },
     "confidence": {
      "type": "number",
      "format": "double",
      "description": "Confidence in the recommendation"
     },
     "strategy": {
      "type": "string",
      "description": "Recommended strategy"
     }
    },
    "example": {
     "alternatives": [
      "symbolic_first",
      "neural_first"
     ],
     "confidence": 0.92,
     "strategy": "hybrid_weighted"
    }
   },
   "StrategyStat": {
    "type": "object",
    "description": "A flattened, operator-facing view of one learned (query-class, strategy) pair.",
    "required": [
     "query_class",
     "strategy",
     "samples",
     "mean_confidence",
     "success_rate",
     "mean_latency_ms",
     "trusted"
    ],
    "properties": {
     "mean_confidence": {
      "type": "number",
      "format": "float"
     },
     "mean_latency_ms": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "query_class": {
      "type": "string"
     },
     "samples": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "strategy": {
      "type": "string"
     },
     "success_rate": {
      "type": "number",
      "format": "float"
     },
     "trusted": {
      "type": "boolean",
      "description": "True once the pair has enough samples for the bandit to exploit it."
     }
    }
   },
   "StrategyStatsResponse": {
    "type": "object",
    "description": "Inspect what the auto-strategy bandit has learned: per (query-class, strategy)\nsample counts, mean confidence, success rate and latency, plus the current\nexploration rate. Makes the platform's strategy learning observable so\noperators can see it improving and which strategies win for which queries.\nObservable snapshot of the auto-strategy bandit's learned state.",
    "required": [
     "epsilon",
     "learned_pairs",
     "learned"
    ],
    "properties": {
     "epsilon": {
      "type": "number",
      "format": "float",
      "description": "Current exploration rate (probability of trying a non-best strategy)."
     },
     "learned": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/StrategyStat"
      },
      "description": "Per-pair performance rows, one for each observed (query-class, strategy)."
     },
     "learned_pairs": {
      "type": "integer",
      "description": "Number of learned (query-class, strategy) pairs in `learned`.",
      "minimum": 0
     }
    }
   },
   "StreamChatRequest": {
    "type": "object",
    "description": "Request body for the streaming chat endpoint.",
    "required": [
     "message"
    ],
    "properties": {
     "conversation_id": {
      "type": "string",
      "description": "Existing conversation ID. A new UUID is generated when absent.",
      "nullable": true
     },
     "execute_ready_actions": {
      "type": "boolean",
      "description": "Execute ready chat actions against KB adapters. Defaults to true.",
      "nullable": true
     },
     "history": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ChatMessage"
      },
      "description": "Conversation history for contextual follow-ups.",
      "nullable": true
     },
     "max_recursive_steps": {
      "type": "integer",
      "description": "Recursive completion passes (1..=4, default 4).",
      "nullable": true,
      "minimum": 0
     },
     "message": {
      "type": "string",
      "description": "The customer message to analyze and respond to."
     },
     "session_id": {
      "type": "string",
      "description": "Optional server-side session for conversation continuity.",
      "nullable": true
     },
     "workflow_id": {
      "type": "string",
      "description": "Optional workflow identifier for tracing.",
      "nullable": true
     }
    }
   },
   "StreamReasonRequest": {
    "type": "object",
    "description": "Request for streaming reasoning (POST body)",
    "required": [
     "query"
    ],
    "properties": {
     "as_of_timestamp": {
      "type": "string",
      "nullable": true
     },
     "query": {
      "type": "string"
     },
     "strategy": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "StructuredIngestPayload": {
    "type": "object",
    "properties": {
     "entities": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/IngestEntityRecord"
      }
     },
     "rules": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/IngestRuleRecord"
      }
     },
     "triples": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/IngestTripleRecord"
      }
     }
    }
   },
   "SubscriptionResponse": {
    "type": "object",
    "required": [
     "tier",
     "status",
     "cancel_at_period_end"
    ],
    "properties": {
     "cancel_at_period_end": {
      "type": "boolean"
     },
     "current_period_end": {
      "type": "string",
      "nullable": true
     },
     "status": {
      "type": "string"
     },
     "subscription_id": {
      "type": "string",
      "nullable": true
     },
     "tier": {
      "type": "string"
     }
    }
   },
   "SubtypeRelation": {
    "type": "object",
    "description": "A subtype relationship",
    "required": [
     "subtype",
     "supertype"
    ],
    "properties": {
     "subtype": {
      "type": "string"
     },
     "supertype": {
      "type": "string"
     }
    }
   },
   "SuggestedAction": {
    "type": "object",
    "required": [
     "action_type",
     "label",
     "reason",
     "execution_status",
     "required_inputs",
     "missing_inputs",
     "can_auto_execute"
    ],
    "properties": {
     "action_type": {
      "type": "string"
     },
     "can_auto_execute": {
      "type": "boolean"
     },
     "execution_status": {
      "type": "string"
     },
     "label": {
      "type": "string"
     },
     "missing_inputs": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "reason": {
      "type": "string"
     },
     "required_inputs": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "tool_name": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "SuggestedRule": {
    "type": "object",
    "description": "A rule head + body proposed via feedback, in the flywheel's\n`predicate(arg, ...)` atom string shape.",
    "required": [
     "head",
     "body"
    ],
    "properties": {
     "body": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "evidence_count": {
      "type": "integer",
      "description": "Deprecated compatibility field. Public feedback always contributes one\nuntrusted observation; callers cannot self-certify independent evidence\nor trigger autonomous promotion by increasing this value.",
      "nullable": true,
      "minimum": 0
     },
     "head": {
      "type": "string"
     }
    }
   },
   "SupportingKbRule": {
    "type": "object",
    "required": [
     "id",
     "name",
     "conclusion",
     "confidence",
     "priority",
     "score"
    ],
    "properties": {
     "conclusion": {
      "type": "string"
     },
     "confidence": {
      "type": "number",
      "format": "float"
     },
     "description": {
      "type": "string",
      "nullable": true
     },
     "id": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "priority": {
      "type": "integer",
      "format": "int32"
     },
     "score": {
      "type": "number",
      "format": "double"
     }
    }
   },
   "SupportingSeedRule": {
    "type": "object",
    "required": [
     "id",
     "name",
     "category",
     "domain",
     "intent",
     "score"
    ],
    "properties": {
     "category": {
      "type": "string"
     },
     "domain": {
      "type": "string"
     },
     "id": {
      "type": "string"
     },
     "intent": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "score": {
      "type": "number",
      "format": "double"
     }
    }
   },
   "SymbolDistributionResponse": {
    "type": "object",
    "description": "Symbol probability distribution",
    "required": [
     "argmax_symbol",
     "argmax_log_prob",
     "top_k"
    ],
    "properties": {
     "argmax_log_prob": {
      "type": "number",
      "format": "double",
      "description": "Log probability of the argmax"
     },
     "argmax_symbol": {
      "type": "integer",
      "format": "int64",
      "description": "Symbol ID with highest probability",
      "minimum": 0
     },
     "top_k": {
      "type": "array",
      "items": {
       "type": "array",
       "items": {
        "allOf": [
         {
          "type": "integer",
          "format": "int64",
          "minimum": 0
         },
         {
          "type": "number",
          "format": "double"
         }
        ]
       }
      },
      "description": "Top-k symbols with their probabilities"
     }
    }
   },
   "SymbolResponse": {
    "type": "object",
    "description": "Response for symbol operations",
    "required": [
     "id",
     "name",
     "has_program"
    ],
    "properties": {
     "has_program": {
      "type": "boolean",
      "description": "Whether the symbol has an associated program"
     },
     "id": {
      "type": "integer",
      "format": "int64",
      "description": "Symbol ID",
      "minimum": 0
     },
     "name": {
      "type": "string",
      "description": "Symbol name"
     }
    }
   },
   "SymbolicAnalysis": {
    "type": "object",
    "required": [
     "categories",
     "domains",
     "intents",
     "horn_clauses_fired",
     "escalation_triggered",
     "safety_gate_triggered",
     "confidence",
     "matching_rule_count",
     "composite_symbol",
     "supporting_seed_rules"
    ],
    "properties": {
     "categories": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/CategoryMatch"
      },
      "description": "Canonical categories that fired (ranked by score)."
     },
     "composite_symbol": {
      "type": "array",
      "items": {
       "type": "number",
       "format": "double"
      },
      "description": "The GSS composite symbol for this message (24-field vector)."
     },
     "confidence": {
      "type": "number",
      "format": "double",
      "description": "Overall confidence score."
     },
     "domains": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Active domains."
     },
     "escalation_triggered": {
      "type": "boolean",
      "description": "Whether escalation was triggered."
     },
     "horn_clauses_fired": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Horn clauses that fired."
     },
     "intents": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Active intents."
     },
     "matching_rule_count": {
      "type": "integer",
      "description": "Number of matching rules.",
      "minimum": 0
     },
     "safety_gate_triggered": {
      "type": "boolean",
      "description": "Whether a safety gate was triggered."
     },
     "supporting_seed_rules": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/SupportingSeedRule"
      },
      "description": "Top supporting seed rules that matched this message."
     }
    }
   },
   "TaskCharacteristicsRequest": {
    "type": "object",
    "description": "Task characteristics for strategy recommendation",
    "required": [
     "complexity"
    ],
    "properties": {
     "complexity": {
      "type": "number",
      "format": "double",
      "description": "Task complexity (0.0 to 1.0)"
     },
     "domain": {
      "type": "string",
      "description": "Domain name (optional)",
      "nullable": true
     },
     "is_compositional": {
      "type": "boolean",
      "description": "Whether the task is compositional",
      "nullable": true
     },
     "requires_logic": {
      "type": "boolean",
      "description": "Whether the task requires logical reasoning",
      "nullable": true
     },
     "requires_patterns": {
      "type": "boolean",
      "description": "Whether the task requires pattern matching",
      "nullable": true
     },
     "sequence_length": {
      "type": "integer",
      "description": "Input sequence length",
      "nullable": true,
      "minimum": 0
     },
     "vocabulary_size": {
      "type": "integer",
      "description": "Vocabulary size",
      "nullable": true,
      "minimum": 0
     }
    },
    "example": {
     "complexity": 0.7,
     "domain": "SCAN",
     "is_compositional": true,
     "requires_logic": true,
     "requires_patterns": true,
     "sequence_length": 10,
     "vocabulary_size": 50
    }
   },
   "Template": {
    "type": "object",
    "required": [
     "slug",
     "name",
     "description",
     "industry",
     "entity_count",
     "rule_count",
     "entities",
     "rules"
    ],
    "properties": {
     "description": {
      "type": "string"
     },
     "entities": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/TemplateEntity"
      }
     },
     "entity_count": {
      "type": "integer",
      "minimum": 0
     },
     "industry": {
      "type": "string"
     },
     "input_predicates": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Predicates the rules CONSUME but never PRODUCE \u2014 the facts a caller must\nsupply (per decision or via the KB) for this rulebook to reach a verdict.\nDerived from the rules so it can never drift from them."
     },
     "name": {
      "type": "string"
     },
     "rule_count": {
      "type": "integer",
      "minimum": 0
     },
     "rules": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/TemplateRule"
      }
     },
     "slug": {
      "type": "string"
     }
    }
   },
   "TemplateEntity": {
    "type": "object",
    "required": [
     "name",
     "entity_type"
    ],
    "properties": {
     "entity_type": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "properties": {
      "type": "object",
      "additionalProperties": {}
     }
    }
   },
   "TemplateListResponse": {
    "type": "object",
    "required": [
     "templates"
    ],
    "properties": {
     "templates": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/TemplateSummary"
      }
     }
    }
   },
   "TemplateRule": {
    "type": "object",
    "required": [
     "name",
     "description",
     "head_predicate",
     "head_args",
     "body"
    ],
    "properties": {
     "body": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/TemplateRuleAtom"
      }
     },
     "confidence": {
      "type": "number",
      "format": "float"
     },
     "description": {
      "type": "string"
     },
     "head_args": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "head_predicate": {
      "type": "string"
     },
     "name": {
      "type": "string"
     }
    }
   },
   "TemplateRuleAtom": {
    "type": "object",
    "required": [
     "predicate",
     "args"
    ],
    "properties": {
     "args": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "negated": {
      "type": "boolean"
     },
     "predicate": {
      "type": "string"
     }
    }
   },
   "TemplateSummary": {
    "type": "object",
    "required": [
     "slug",
     "name",
     "description",
     "industry",
     "entity_count",
     "rule_count"
    ],
    "properties": {
     "description": {
      "type": "string"
     },
     "entity_count": {
      "type": "integer",
      "minimum": 0
     },
     "industry": {
      "type": "string"
     },
     "input_predicates": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "The facts a caller must supply for this rulebook to fire (see\n[`Template::input_predicates`]). Surfaced in the list so integrators can\nsee a template's required inputs without fetching each one."
     },
     "name": {
      "type": "string"
     },
     "rule_count": {
      "type": "integer",
      "minimum": 0
     },
     "slug": {
      "type": "string"
     }
    }
   },
   "Term": {
    "oneOf": [
     {
      "type": "object",
      "required": [
       "Constant"
      ],
      "properties": {
       "Constant": {
        "type": "string",
        "description": "A constant value"
       }
      }
     },
     {
      "type": "object",
      "required": [
       "Variable"
      ],
      "properties": {
       "Variable": {
        "type": "string",
        "description": "A variable (starts with ?)"
       }
      }
     },
     {
      "type": "object",
      "required": [
       "EntityRef"
      ],
      "properties": {
       "EntityRef": {
        "$ref": "#/components/schemas/EntityId"
       }
      }
     },
     {
      "type": "object",
      "required": [
       "Function"
      ],
      "properties": {
       "Function": {
        "type": "array",
        "items": {
         "type": "object"
        },
        "description": "A function application",
        "maxItems": 2,
        "minItems": 2
       }
      }
     }
    ],
    "description": "A term in a logical expression"
   },
   "TestResponse": {
    "type": "object",
    "required": [
     "endpoint_id",
     "status",
     "note"
    ],
    "properties": {
     "endpoint_id": {
      "type": "string"
     },
     "note": {
      "type": "string"
     },
     "status": {
      "type": "string"
     }
    }
   },
   "ThoughtChild": {
    "type": "object",
    "description": "A child thought in branching",
    "required": [
     "content",
     "score"
    ],
    "properties": {
     "content": {
      "type": "string",
      "description": "Thought content"
     },
     "score": {
      "type": "number",
      "format": "float",
      "description": "Initial score"
     }
    }
   },
   "ThoughtResponse": {
    "type": "object",
    "description": "Response for thought operations",
    "required": [
     "id",
     "content",
     "score"
    ],
    "properties": {
     "content": {
      "type": "string",
      "description": "Content"
     },
     "id": {
      "type": "integer",
      "description": "Thought ID",
      "minimum": 0
     },
     "score": {
      "type": "number",
      "format": "float",
      "description": "Score"
     }
    }
   },
   "ToggleFeatureRequest": {
    "type": "object",
    "description": "Request to toggle a feature",
    "required": [
     "feature",
     "enabled"
    ],
    "properties": {
     "enabled": {
      "type": "boolean",
      "description": "Whether to enable (true) or disable (false)"
     },
     "feature": {
      "type": "string",
      "description": "Feature name"
     }
    }
   },
   "ToolCall": {
    "type": "object",
    "description": "A structured tool/function call produced by neuro-symbolic reasoning.\nSimilar to OpenAI/Anthropic tool_use but grounded in org-specific rules.",
    "required": [
     "id",
     "function",
     "arguments",
     "policy",
     "status"
    ],
    "properties": {
     "arguments": {
      "description": "Structured arguments extracted from the message and KB context."
     },
     "function": {
      "type": "string",
      "description": "Function name to invoke (e.g., \"issue_refund\", \"create_return\", \"escalate\")."
     },
     "id": {
      "type": "string",
      "description": "Unique ID for this tool call."
     },
     "policy": {
      "$ref": "#/components/schemas/ToolCallPolicy"
     },
     "status": {
      "type": "string",
      "description": "Whether this call is ready to execute or needs more context."
     }
    }
   },
   "ToolCallPolicy": {
    "type": "object",
    "description": "Policy justification for a tool call \u2014 traces back to the org's rules.",
    "required": [
     "rule_name",
     "rule_conclusion",
     "confidence",
     "reason"
    ],
    "properties": {
     "confidence": {
      "type": "number",
      "format": "float",
      "description": "Confidence from the matching rule."
     },
     "reason": {
      "type": "string",
      "description": "Human-readable reason."
     },
     "rule_conclusion": {
      "type": "string",
      "description": "Rule conclusion (the head of the Horn clause)."
     },
     "rule_name": {
      "type": "string",
      "description": "Rule name from the org's KB that triggered this call."
     }
    }
   },
   "TrainRequest": {
    "type": "object",
    "properties": {
     "examples": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ProvisionTrainingExample"
      },
      "description": "Additional training examples (optional).",
      "nullable": true
     },
     "include_flywheel": {
      "type": "boolean",
      "description": "Whether to include flywheel events (default: true).",
      "nullable": true
     }
    }
   },
   "TrainResponse": {
    "type": "object",
    "required": [
     "org_id",
     "total_examples",
     "successful_abductions",
     "flywheel_examples",
     "custom_examples",
     "concept_models_learned",
     "concept_rules_learned",
     "training_time_ms"
    ],
    "properties": {
     "concept_models_learned": {
      "type": "integer",
      "minimum": 0
     },
     "concept_rules_learned": {
      "type": "integer",
      "minimum": 0
     },
     "custom_examples": {
      "type": "integer",
      "minimum": 0
     },
     "flywheel_examples": {
      "type": "integer",
      "minimum": 0
     },
     "org_id": {
      "type": "string"
     },
     "successful_abductions": {
      "type": "integer",
      "minimum": 0
     },
     "total_examples": {
      "type": "integer",
      "minimum": 0
     },
     "training_time_ms": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     }
    }
   },
   "TrainingExampleRequest": {
    "type": "object",
    "description": "A single training example",
    "required": [
     "inputs",
     "output"
    ],
    "properties": {
     "inputs": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/GroundedInputRequest"
      },
      "description": "Input sequence"
     },
     "output": {
      "$ref": "#/components/schemas/SemanticValueRequest"
     }
    }
   },
   "TripleDiffItem": {
    "type": "object",
    "required": [
     "subject",
     "subject_name",
     "predicate",
     "object",
     "object_name",
     "org_id",
     "confidence"
    ],
    "properties": {
     "confidence": {
      "type": "number",
      "format": "float"
     },
     "object": {
      "type": "string"
     },
     "object_name": {
      "type": "string"
     },
     "org_id": {
      "type": "string"
     },
     "predicate": {
      "type": "string"
     },
     "subject": {
      "type": "string"
     },
     "subject_name": {
      "type": "string"
     },
     "valid_from": {
      "type": "string",
      "nullable": true
     },
     "valid_to": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "TripleDiffSection": {
    "type": "object",
    "required": [
     "added",
     "removed"
    ],
    "properties": {
     "added": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/TripleDiffItem"
      }
     },
     "removed": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/TripleDiffItem"
      }
     }
    }
   },
   "TripleEvidenceResponse": {
    "type": "object",
    "required": [
     "triple_id",
     "claim",
     "subject",
     "subject_name",
     "predicate",
     "object",
     "object_name",
     "evidence_ids",
     "evidence_nodes"
    ],
    "properties": {
     "claim": {
      "type": "string"
     },
     "evidence_ids": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "evidence_nodes": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/EvidenceNode"
      }
     },
     "object": {
      "type": "string"
     },
     "object_name": {
      "type": "string"
     },
     "predicate": {
      "type": "string"
     },
     "subject": {
      "type": "string"
     },
     "subject_name": {
      "type": "string"
     },
     "triple_id": {
      "type": "string"
     }
    }
   },
   "TripleResponse": {
    "type": "object",
    "required": [
     "subject",
     "subject_name",
     "predicate",
     "object",
     "object_name",
     "confidence"
    ],
    "properties": {
     "confidence": {
      "type": "number",
      "format": "float"
     },
     "object": {
      "type": "string"
     },
     "object_name": {
      "type": "string"
     },
     "predicate": {
      "type": "string"
     },
     "subject": {
      "type": "string"
     },
     "subject_name": {
      "type": "string"
     },
     "valid_from": {
      "type": "string",
      "nullable": true
     },
     "valid_to": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "TripleSummary": {
    "type": "object",
    "description": "Compact triple representation for evidence",
    "required": [
     "subject",
     "predicate",
     "object"
    ],
    "properties": {
     "object": {
      "type": "string"
     },
     "predicate": {
      "type": "string"
     },
     "subject": {
      "type": "string"
     }
    }
   },
   "UncertaintyResponse": {
    "type": "object",
    "description": "Response for uncertainty estimation",
    "required": [
     "enabled",
     "epistemic",
     "aleatoric",
     "total",
     "calibration_score"
    ],
    "properties": {
     "aleatoric": {
      "type": "number",
      "format": "double",
      "description": "Aleatoric uncertainty (data uncertainty)"
     },
     "calibration_score": {
      "type": "number",
      "format": "double",
      "description": "Calibration score"
     },
     "enabled": {
      "type": "boolean",
      "description": "Whether metacognition is enabled"
     },
     "epistemic": {
      "type": "number",
      "format": "double",
      "description": "Epistemic uncertainty (model uncertainty)"
     },
     "total": {
      "type": "number",
      "format": "double",
      "description": "Total uncertainty"
     }
    },
    "example": {
     "aleatoric": 0.08,
     "calibration_score": 0.87,
     "enabled": true,
     "epistemic": 0.15,
     "total": 0.23
    }
   },
   "UpdateConversationRequest": {
    "type": "object",
    "description": "Update an existing conversation.",
    "properties": {
     "archived": {
      "type": "boolean",
      "description": "Set to true to archive, false to unarchive",
      "nullable": true
     },
     "title": {
      "type": "string",
      "description": "New title",
      "nullable": true
     }
    }
   },
   "UpdateEntityRequest": {
    "type": "object",
    "description": "Update entity request",
    "properties": {
     "name": {
      "type": "string",
      "description": "New name (optional)",
      "nullable": true
     },
     "properties": {
      "type": "object",
      "description": "Properties to add or update",
      "additionalProperties": {},
      "nullable": true
     },
     "remove_properties": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Property keys to remove",
      "nullable": true
     }
    }
   },
   "UpdateEvidenceRequest": {
    "type": "object",
    "properties": {
     "claim": {
      "type": "string",
      "nullable": true
     },
     "clear_embedding": {
      "type": "boolean",
      "nullable": true
     },
     "compute_embedding": {
      "type": "boolean",
      "nullable": true
     },
     "confidence": {
      "type": "number",
      "format": "float",
      "nullable": true
     },
     "depends_on": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "nullable": true
     },
     "embedding": {
      "type": "array",
      "items": {
       "type": "number",
       "format": "float"
      },
      "nullable": true
     },
     "evidence_type": {
      "allOf": [
       {
        "$ref": "#/components/schemas/EvidenceType"
       }
      ],
      "nullable": true
     },
     "source": {
      "allOf": [
       {
        "$ref": "#/components/schemas/EvidenceSourceMeta"
       }
      ],
      "nullable": true
     },
     "timestamp": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "UpdateMacroRequest": {
    "type": "object",
    "description": "Partial update. Deliberately EXCLUDES `body`: changing what a customer\nreceives is a new approval decision, so it goes through create/upsert and\nresets status rather than being edited in place under an existing approval.",
    "properties": {
     "auto_send": {
      "type": "boolean",
      "nullable": true
     },
     "channel": {
      "type": "string",
      "nullable": true
     },
     "rule_name": {
      "type": "string",
      "nullable": true
     },
     "status": {
      "allOf": [
       {
        "$ref": "#/components/schemas/MacroStatus"
       }
      ],
      "nullable": true
     },
     "tags": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "nullable": true
     },
     "title": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "UpdateRuleRequest": {
    "type": "object",
    "description": "Request to update a rule",
    "properties": {
     "confidence": {
      "type": "number",
      "format": "float",
      "description": "Confidence factor (0.0 - 1.0)",
      "nullable": true
     },
     "description": {
      "type": "string",
      "description": "New description for the rule",
      "nullable": true
     },
     "enabled": {
      "type": "boolean",
      "description": "Whether the rule is enabled",
      "nullable": true
     },
     "priority": {
      "type": "integer",
      "format": "int32",
      "description": "Priority for rule ordering (higher = more priority)",
      "nullable": true
     },
     "test_cases": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/RuleTestCaseRequest"
      },
      "description": "Replace rule test cases.",
      "nullable": true
     }
    }
   },
   "UpdateSessionContextRequest": {
    "type": "object",
    "description": "Update session context request",
    "properties": {
     "focus_entities": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Focus entities to set",
      "nullable": true
     },
     "remove": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Context variable keys to remove"
     },
     "set": {
      "type": "object",
      "description": "Context variables to add or update",
      "additionalProperties": {
       "type": "string"
      }
     }
    }
   },
   "UpdateSessionContextResponse": {
    "type": "object",
    "description": "Update session context response",
    "required": [
     "session_id",
     "context",
     "focus_entities"
    ],
    "properties": {
     "context": {
      "type": "object",
      "description": "Updated context variables",
      "additionalProperties": {
       "type": "string"
      }
     },
     "focus_entities": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Updated focus entities"
     },
     "session_id": {
      "type": "string",
      "description": "Session ID"
     }
    }
   },
   "UpdateSourceRequest": {
    "type": "object",
    "properties": {
     "locator": {
      "type": "string",
      "nullable": true
     },
     "metadata": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      },
      "nullable": true
     },
     "snippet": {
      "type": "string",
      "nullable": true
     },
     "source_type": {
      "type": "string",
      "nullable": true
     },
     "trust_tag": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "UpdateTripleRequest": {
    "type": "object",
    "description": "Update triple request",
    "required": [
     "subject_id",
     "predicate",
     "object_id"
    ],
    "properties": {
     "clear_valid_time": {
      "type": "boolean",
      "description": "If true, clear the validity interval on this triple.",
      "nullable": true
     },
     "confidence": {
      "type": "number",
      "format": "float",
      "description": "New confidence score",
      "nullable": true
     },
     "object_id": {
      "type": "string",
      "description": "Object entity ID (to identify the triple)"
     },
     "predicate": {
      "type": "string",
      "description": "Predicate name (to identify the triple)"
     },
     "subject_id": {
      "type": "string",
      "description": "Subject entity ID (to identify the triple)"
     },
     "valid_from": {
      "type": "string",
      "description": "Optional RFC3339 start of validity interval.",
      "nullable": true
     },
     "valid_to": {
      "type": "string",
      "description": "Optional RFC3339 end of validity interval.",
      "nullable": true
     }
    }
   },
   "UsageAccount": {
    "type": "object",
    "description": "Tenant account posture for outcome production and prepaid runway.",
    "required": [
     "status",
     "can_produce_outcome",
     "included_outcomes_remaining",
     "trial_credits_remaining_cents"
    ],
    "properties": {
     "can_produce_outcome": {
      "type": "boolean",
      "description": "Whether the tenant can currently produce another billable outcome."
     },
     "included_outcomes_remaining": {
      "type": "integer",
      "format": "int64",
      "description": "Included outcomes remaining before billable overage starts.",
      "minimum": 0
     },
     "prepaid_credits_remaining_cents": {
      "type": "integer",
      "format": "int64",
      "description": "Prepaid (purchased) credits remaining in cents. Never expire."
     },
     "status": {
      "type": "string",
      "description": "Tenant status from the tenancy system."
     },
     "trial_credits_remaining_cents": {
      "type": "integer",
      "format": "int64",
      "description": "Trial credits remaining in cents."
     }
    }
   },
   "UsageLimits": {
    "type": "object",
    "required": [
     "max_entities",
     "max_triples",
     "max_rules",
     "max_requests_per_minute"
    ],
    "properties": {
     "max_entities": {
      "type": "integer",
      "minimum": 0
     },
     "max_requests_per_minute": {
      "type": "integer",
      "format": "int32",
      "minimum": 0
     },
     "max_rules": {
      "type": "integer",
      "minimum": 0
     },
     "max_triples": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "UsagePercentages": {
    "type": "object",
    "description": "Usage as percentages of limits",
    "required": [
     "entities_percent",
     "triples_percent",
     "rules_percent"
    ],
    "properties": {
     "entities_percent": {
      "type": "number",
      "format": "double"
     },
     "rules_percent": {
      "type": "number",
      "format": "double"
     },
     "triples_percent": {
      "type": "number",
      "format": "double"
     }
    }
   },
   "UsageResponse": {
    "type": "object",
    "required": [
     "api_requests_month",
     "inference_requests_month",
     "entities",
     "triples",
     "rules",
     "storage_bytes",
     "tier",
     "limits",
     "outcomes",
     "recursive",
     "account"
    ],
    "properties": {
     "account": {
      "$ref": "#/components/schemas/UsageAccount"
     },
     "api_requests_month": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "entities": {
      "type": "integer",
      "minimum": 0
     },
     "inference_requests_month": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "limits": {
      "$ref": "#/components/schemas/UsageLimits"
     },
     "outcomes": {
      "$ref": "#/components/schemas/OutcomeUsage"
     },
     "recursive": {
      "$ref": "#/components/schemas/RecursiveUsage"
     },
     "rules": {
      "type": "integer",
      "minimum": 0
     },
     "storage_bytes": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
     },
     "tier": {
      "type": "string"
     },
     "triples": {
      "type": "integer",
      "minimum": 0
     }
    }
   },
   "VSABindRequest": {
    "type": "object",
    "description": "Request for VSA bind operation",
    "required": [
     "a",
     "b"
    ],
    "properties": {
     "a": {
      "$ref": "#/components/schemas/VSAVectorRef"
     },
     "b": {
      "$ref": "#/components/schemas/VSAVectorRef"
     },
     "output_concept": {
      "type": "string",
      "description": "Optional concept name to store the bound result under",
      "nullable": true
     }
    }
   },
   "VSABundleRequest": {
    "type": "object",
    "description": "Request for VSA bundle operation (superposition/set union)",
    "required": [
     "vectors"
    ],
    "properties": {
     "output_concept": {
      "type": "string",
      "description": "Optional concept name to store the bundled result under",
      "nullable": true
     },
     "vectors": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/VSAVectorRef"
      },
      "description": "Vectors to bundle (as concept names or raw vectors)"
     }
    }
   },
   "VSAClassPrototype": {
    "type": "object",
    "description": "Prototype definition for VSA-based classification",
    "required": [
     "label",
     "features"
    ],
    "properties": {
     "features": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Feature concept names that define the class"
     },
     "label": {
      "type": "string",
      "description": "Class label (e.g., \"CLASS:CAT\")"
     }
    }
   },
   "VSAClassifyRequest": {
    "type": "object",
    "description": "Request for VSA-based classification using vector similarity",
    "required": [
     "input_features",
     "class_prototypes"
    ],
    "properties": {
     "class_prototypes": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/VSAClassPrototype"
      },
      "description": "Class prototypes expressed as feature bundles"
     },
     "input_features": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Input feature concept names (e.g., [\"has_fur\", \"meows\"])"
     },
     "top_k": {
      "type": "integer",
      "description": "Number of results to return (default: 5)",
      "nullable": true,
      "minimum": 0
     }
    }
   },
   "VSAClassifyResponse": {
    "type": "object",
    "description": "Response for VSA-based classification",
    "required": [
     "enabled",
     "results",
     "dimension"
    ],
    "properties": {
     "dimension": {
      "type": "integer",
      "description": "Vector dimension",
      "minimum": 0
     },
     "enabled": {
      "type": "boolean",
      "description": "Whether VSA is enabled"
     },
     "prediction": {
      "type": "string",
      "description": "Predicted class label (highest similarity)",
      "nullable": true
     },
     "results": {
      "type": "array",
      "items": {
       "type": "array",
       "items": {
        "allOf": [
         {
          "type": "string"
         },
         {
          "type": "number",
          "format": "double"
         }
        ]
       }
      },
      "description": "Ranked results (label, similarity)"
     },
     "score": {
      "type": "number",
      "format": "double",
      "description": "Similarity score for the predicted class",
      "nullable": true
     }
    }
   },
   "VSAEncodeRequest": {
    "type": "object",
    "description": "Request to encode a symbol in VSA",
    "properties": {
     "concept_name": {
      "type": "string",
      "description": "Or concept name to add",
      "nullable": true
     },
     "symbol_id": {
      "type": "integer",
      "format": "int64",
      "description": "Symbol ID to encode",
      "nullable": true,
      "minimum": 0
     }
    },
    "example": {
     "concept_name": "WALK",
     "symbol_id": null
    }
   },
   "VSAQueryRequest": {
    "type": "object",
    "description": "Request for VSA query",
    "required": [
     "query"
    ],
    "properties": {
     "query": {
      "$ref": "#/components/schemas/VSAVectorRef"
     },
     "top_k": {
      "type": "integer",
      "description": "Number of results to return",
      "nullable": true,
      "minimum": 0
     }
    }
   },
   "VSAResponse": {
    "type": "object",
    "description": "Response for VSA operations",
    "required": [
     "enabled",
     "dimension"
    ],
    "properties": {
     "dimension": {
      "type": "integer",
      "description": "Vector dimension",
      "minimum": 0
     },
     "enabled": {
      "type": "boolean",
      "description": "Whether VSA is enabled"
     },
     "results": {
      "type": "array",
      "items": {
       "type": "array",
       "items": {
        "allOf": [
         {
          "type": "string"
         },
         {
          "type": "number",
          "format": "double"
         }
        ]
       }
      },
      "description": "Query results (if applicable)",
      "nullable": true
     },
     "vector": {
      "type": "array",
      "items": {
       "type": "number",
       "format": "float"
      },
      "description": "Result vector (if applicable)",
      "nullable": true
     }
    }
   },
   "VSAVectorRef": {
    "oneOf": [
     {
      "type": "object",
      "description": "Reference by concept name",
      "required": [
       "concept"
      ],
      "properties": {
       "concept": {
        "type": "string"
       }
      }
     },
     {
      "type": "object",
      "description": "Raw vector values",
      "required": [
       "values"
      ],
      "properties": {
       "values": {
        "type": "array",
        "items": {
         "type": "number",
         "format": "float"
        }
       }
      }
     }
    ],
    "description": "Reference to a VSA vector"
   },
   "ValidateConstraintsRequest": {
    "type": "object",
    "description": "Request to validate facts against constraints",
    "required": [
     "facts"
    ],
    "properties": {
     "facts": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Facts to validate (in NSR-L syntax)"
     }
    }
   },
   "ValidateConstraintsResponse": {
    "type": "object",
    "description": "Response from constraint validation",
    "required": [
     "valid",
     "has_refutation",
     "hard_violations",
     "soft_violations",
     "total_penalty",
     "violations"
    ],
    "properties": {
     "hard_violations": {
      "type": "integer",
      "minimum": 0
     },
     "has_refutation": {
      "type": "boolean"
     },
     "soft_violations": {
      "type": "integer",
      "minimum": 0
     },
     "total_penalty": {
      "type": "number",
      "format": "float"
     },
     "valid": {
      "type": "boolean"
     },
     "violations": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ConstraintViolationResponse"
      }
     }
    }
   },
   "ValidateRequest": {
    "type": "object",
    "description": "Request for validating a query IR.\n\nProvide either `query` (raw NL query to compile+validate) or `ir` (serialized QueryIR).",
    "properties": {
     "ir": {
      "nullable": true
     },
     "query": {
      "type": "string",
      "nullable": true
     },
     "strict": {
      "type": "boolean",
      "nullable": true
     }
    }
   },
   "ValidateResponse": {
    "type": "object",
    "required": [
     "valid",
     "errors",
     "warnings"
    ],
    "properties": {
     "errors": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ValidationIssue"
      }
     },
     "ir": {
      "nullable": true
     },
     "plan": {
      "nullable": true
     },
     "valid": {
      "type": "boolean"
     },
     "warnings": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ValidationIssue"
      }
     }
    }
   },
   "ValidateTypeRequest": {
    "type": "object",
    "description": "Request to validate a fact against the type registry",
    "required": [
     "predicate",
     "arg_types"
    ],
    "properties": {
     "arg_types": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Argument types to validate"
     },
     "predicate": {
      "type": "string",
      "description": "Predicate name"
     }
    },
    "example": {
     "arg_types": [
      "entity",
      "location"
     ],
     "predicate": "lived_in"
    }
   },
   "ValidateTypeResponse": {
    "type": "object",
    "description": "Response from type validation",
    "required": [
     "valid"
    ],
    "properties": {
     "error": {
      "type": "string",
      "nullable": true
     },
     "expected_signature": {
      "allOf": [
       {
        "$ref": "#/components/schemas/PredicateResponse"
       }
      ],
      "nullable": true
     },
     "valid": {
      "type": "boolean"
     }
    }
   },
   "ValidationIssue": {
    "type": "object",
    "required": [
     "code",
     "message"
    ],
    "properties": {
     "code": {
      "type": "string"
     },
     "message": {
      "type": "string"
     },
     "path": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "WebhookSummary": {
    "type": "object",
    "required": [
     "id",
     "url",
     "events",
     "signing_secret_prefix",
     "is_active",
     "created_at"
    ],
    "properties": {
     "created_at": {
      "type": "string"
     },
     "description": {
      "type": "string",
      "nullable": true
     },
     "events": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "id": {
      "type": "string"
     },
     "is_active": {
      "type": "boolean"
     },
     "signing_secret_prefix": {
      "type": "string"
     },
     "url": {
      "type": "string"
     }
    }
   }
  },
  "securitySchemes": {
   "api_key": {
    "type": "apiKey",
    "in": "header",
    "name": "X-API-Key"
   },
   "bearer_auth": {
    "type": "http",
    "scheme": "bearer",
    "bearerFormat": "JWT",
    "description": "JWT Bearer token. Obtain from your identity provider. Required claims: `sub` (subject), `scope` (permissions)."
   },
   "org_header": {
    "type": "apiKey",
    "in": "header",
    "name": "X-Org-ID",
    "description": "Organization/Tenant ID for multi-tenant deployments. Required for enterprise tier."
   }
  }
 },
 "security": [
  {
   "api_key": []
  },
  {
   "bearer_auth": []
  }
 ],
 "tags": [
  {
   "name": "Health",
   "description": "Health and readiness probes for monitoring and orchestration"
  },
  {
   "name": "Metering & Marketplace",
   "description": "Usage-metered billing through cloud marketplaces (AWS / Azure / GCP) or Stripe: entitlement onboarding and fulfillment endpoints. Per-cloud wiring: docs/MARKETPLACE_METERING.md"
  },
  {
   "name": "Reasoning",
   "description": "Neural-symbolic reasoning endpoints for query processing, forward/backward chaining, and explanations"
  },
  {
   "name": "Knowledge Base",
   "description": "Query the knowledge graph and analyze relationships"
  },
  {
   "name": "Entities",
   "description": "CRUD operations for knowledge graph entities with soft-delete support"
  },
  {
   "name": "Triples",
   "description": "Manage subject-predicate-object relationships in the knowledge graph"
  },
  {
   "name": "Rules",
   "description": "Define and manage logical inference rules"
  },
  {
   "name": "Flywheel",
   "description": "The learning flywheel: feedback ingestion, rule induction, lifecycle stats, and noise-based demotion"
  },
  {
   "name": "Sessions",
   "description": "Stateful reasoning sessions with context persistence"
  },
  {
   "name": "Audit",
   "description": "Access audit trails for compliance and debugging"
  },
  {
   "name": "Jobs",
   "description": "Submit and track asynchronous batch operations"
  },
  {
   "name": "Model",
   "description": "Model lifecycle management: checkpoints, export, and comparison"
  },
  {
   "name": "Agents",
   "description": "Agent lifecycle management for autonomous NSR background processes"
  },
  {
   "name": "NSR Machine",
   "description": "Core NSR engine: inference, training, symbols, programs, VSA, Graph-of-Thoughts, and metacognition"
  },
  {
   "name": "Machines",
   "description": "Per-org machine provisioning, brand seeding, compile, evaluation, and activation workflows"
  },
  {
   "name": "NSR-L",
   "description": "NSR-L Language: parse, execute, assert, and prove queries using the Neuro-Symbolic Reasoning Language"
  },
  {
   "name": "Constraints",
   "description": "Constraint Management: define hard/soft/weighted constraints for verified reasoning"
  },
  {
   "name": "Types",
   "description": "Type Registry: manage predicate type signatures and type validation"
  },
  {
   "name": "Beliefs",
   "description": "Belief Revision: Bayesian belief updating and Dempster-Shafer uncertainty handling"
  },
  {
   "name": "Provider Compatibility",
   "description": "OpenAI-compatible chat and responses surfaces backed by NSR recursion and grounded tool calling"
  },
  {
   "name": "Ingestion",
   "description": "File upload and ingestion endpoints for grounding enterprise data into evidence and the knowledge base"
  }
 ],
 "externalDocs": {
  "url": "https://docs.stateset.com/nsr",
  "description": "Full documentation and guides"
 }
}