{ "/policies": { "post": { "tags": [ "Policies" ], "summary": "Create Policy", "description": "Create a new policy.\n\nExample Request:\n```bash\ncurl -X POST \"http://localhost:4000/policies\" \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"policy_name\": \"global-baseline\",\n \"description\": \"Base guardrails for all requests\",\n \"guardrails_add\": [\"pii_masking\", \"prompt_injection\"],\n \"guardrails_remove\": []\n }'\n```\n\nExample Response:\n```json\n{\n \"policy_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"policy_name\": \"global-baseline\",\n \"inherit\": null,\n \"description\": \"Base guardrails for all requests\",\n \"guardrails_add\": [\"pii_masking\", \"prompt_injection\"],\n \"guardrails_remove\": [],\n \"condition\": null,\n \"created_at\": \"2024-01-01T00:00:00Z\",\n \"updated_at\": \"2024-01-01T00:00:00Z\"\n}\n```", "operationId": "create_policy_policies_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyCreateRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyDBResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/policies/attachments": { "post": { "tags": [ "Policies" ], "summary": "Create Policy Attachment", "description": "Create a new policy attachment.\n\nExample Request:\n```bash\ncurl -X POST \"http://localhost:4000/policies/attachments\" \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"policy_name\": \"global-baseline\",\n \"scope\": \"*\"\n }'\n```\n\nExample with team-specific attachment:\n```bash\ncurl -X POST \"http://localhost:4000/policies/attachments\" \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"policy_name\": \"healthcare-compliance\",\n \"teams\": [\"healthcare-team\", \"medical-research\"]\n }'\n```\n\nExample Response:\n```json\n{\n \"attachment_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"policy_name\": \"global-baseline\",\n \"scope\": \"*\",\n \"teams\": [],\n \"keys\": [],\n \"models\": [],\n \"created_at\": \"2024-01-01T00:00:00Z\",\n \"updated_at\": \"2024-01-01T00:00:00Z\"\n}\n```", "operationId": "create_policy_attachment_policies_attachments_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyAttachmentCreateRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyAttachmentDBResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/policies/attachments/estimate-impact": { "post": { "tags": [ "Policies" ], "summary": "Estimate Attachment Impact", "description": "Estimate how many keys and teams would be affected by a policy attachment.\n\nUse this before creating an attachment to preview the blast radius.\n\nExample Request:\n```bash\ncurl -X POST \"http://localhost:4000/policies/attachments/estimate-impact\" \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"policy_name\": \"hipaa-compliance\",\n \"tags\": [\"healthcare\", \"health-*\"]\n }'\n```", "operationId": "estimate_attachment_impact_policies_attachments_estimate_impact_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyAttachmentCreateRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentImpactResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/policies/attachments/list": { "get": { "tags": [ "Policies" ], "summary": "List Policy Attachments", "description": "List all policy attachments from the database.\n\nExample Request:\n```bash\ncurl -X GET \"http://localhost:4000/policies/attachments/list\" \\\n -H \"Authorization: Bearer \"\n```\n\nExample Response:\n```json\n{\n \"attachments\": [\n {\n \"attachment_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"policy_name\": \"global-baseline\",\n \"scope\": \"*\",\n \"teams\": [],\n \"keys\": [],\n \"models\": [],\n \"created_at\": \"2024-01-01T00:00:00Z\",\n \"updated_at\": \"2024-01-01T00:00:00Z\"\n }\n ],\n \"total_count\": 1\n}\n```", "operationId": "list_policy_attachments_policies_attachments_list_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyAttachmentListResponse" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/policies/attachments/{attachment_id}": { "get": { "tags": [ "Policies" ], "summary": "Get Policy Attachment", "description": "Get a policy attachment by ID.\n\nExample Request:\n```bash\ncurl -X GET \"http://localhost:4000/policies/attachments/123e4567-e89b-12d3-a456-426614174000\" \\\n -H \"Authorization: Bearer \"\n```", "operationId": "get_policy_attachment_policies_attachments__attachment_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "attachment_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Attachment Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyAttachmentDBResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Policies" ], "summary": "Delete Policy Attachment", "description": "Delete a policy attachment.\n\nExample Request:\n```bash\ncurl -X DELETE \"http://localhost:4000/policies/attachments/123e4567-e89b-12d3-a456-426614174000\" \\\n -H \"Authorization: Bearer \"\n```\n\nExample Response:\n```json\n{\n \"message\": \"Attachment 123e4567-e89b-12d3-a456-426614174000 deleted successfully\"\n}\n```", "operationId": "delete_policy_attachment_policies_attachments__attachment_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "attachment_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Attachment Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/policies/compare": { "get": { "tags": [ "Policies" ], "summary": "Compare Policy Versions", "description": "Compare two policy versions. Query params: version_a, version_b (policy version IDs).", "operationId": "compare_policy_versions_policies_compare_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "version_a", "in": "query", "required": true, "schema": { "type": "string", "title": "Version A" } }, { "name": "version_b", "in": "query", "required": true, "schema": { "type": "string", "title": "Version B" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyVersionCompareResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/policies/list": { "get": { "tags": [ "Policies" ], "summary": "List Policies", "description": "List all policies from the database. Optionally filter by version_status.\n\nQuery params:\n- version_status: Optional. One of \"draft\", \"published\", \"production\".\n If omitted, all versions are returned.\n\nExample Request:\n```bash\ncurl -X GET \"http://localhost:4000/policies/list\" \\\n -H \"Authorization: Bearer \"\ncurl -X GET \"http://localhost:4000/policies/list?version_status=production\" \\\n -H \"Authorization: Bearer \"\n```\n\nExample Response:\n```json\n{\n \"policies\": [\n {\n \"policy_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"policy_name\": \"global-baseline\",\n \"version_number\": 1,\n \"version_status\": \"production\",\n \"inherit\": null,\n \"description\": \"Base guardrails for all requests\",\n \"guardrails_add\": [\"pii_masking\"],\n \"guardrails_remove\": [],\n \"condition\": null,\n \"created_at\": \"2024-01-01T00:00:00Z\",\n \"updated_at\": \"2024-01-01T00:00:00Z\"\n }\n ],\n \"total_count\": 1\n}\n```", "operationId": "list_policies_policies_list_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "version_status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Version Status" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyListDBResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/policies/name/{policy_name}/all-versions": { "delete": { "tags": [ "Policies" ], "summary": "Delete All Policy Versions", "description": "Delete all versions of a policy. Also removes from in-memory registry.", "operationId": "delete_all_policy_versions_policies_name__policy_name__all_versions_delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "policy_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Policy Name" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/policies/name/{policy_name}/versions": { "get": { "tags": [ "Policies" ], "summary": "List Policy Versions", "description": "List all versions of a policy by name, ordered by version_number descending.", "operationId": "list_policy_versions_policies_name__policy_name__versions_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "policy_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Policy Name" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyVersionListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "Policies" ], "summary": "Create Policy Version", "description": "Create a new draft version of a policy. Copies all fields from the source.\nSource is current production if source_policy_id is not provided.", "operationId": "create_policy_version_policies_name__policy_name__versions_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "policy_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Policy Name" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyVersionCreateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyDBResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/policies/resolve": { "post": { "tags": [ "Policies" ], "summary": "Resolve Policies For Context", "description": "Resolve which policies and guardrails apply for a given context.\n\nUse this endpoint to debug \"what guardrails would apply to a request\nwith this team/key/model/tags combination?\"\n\nExample Request:\n```bash\ncurl -X POST \"http://localhost:4000/policies/resolve\" \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"tags\": [\"healthcare\"],\n \"model\": \"gpt-4\"\n }'\n```", "operationId": "resolve_policies_for_context_policies_resolve_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "force_sync", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Force a DB sync before resolving. Default uses in-memory cache.", "default": false, "title": "Force Sync" }, "description": "Force a DB sync before resolving. Default uses in-memory cache." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyResolveRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyResolveResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/policies/test-pipeline": { "post": { "tags": [ "Policies" ], "summary": "Test Pipeline", "description": "Test a guardrail pipeline with sample messages.\n\nExecutes the pipeline steps against the provided test messages and returns\nstep-by-step results showing which guardrails passed/failed, actions taken,\nand timing information.\n\nExample Request:\n```bash\ncurl -X POST \"http://localhost:4000/policies/test-pipeline\" \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"pipeline\": {\n \"mode\": \"pre_call\",\n \"steps\": [\n {\"guardrail\": \"pii-guard\", \"on_pass\": \"next\", \"on_fail\": \"block\"}\n ]\n },\n \"test_messages\": [{\"role\": \"user\", \"content\": \"My SSN is 123-45-6789\"}]\n }'\n```", "operationId": "test_pipeline_policies_test_pipeline_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineTestRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/policies/usage/overview": { "get": { "tags": [ "Policies" ], "summary": "Policies Usage Overview", "description": "Return policy performance overview for the dashboard.", "operationId": "policies_usage_overview_policies_usage_overview_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YYYY-MM-DD", "title": "Start Date" }, "description": "YYYY-MM-DD" }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YYYY-MM-DD", "title": "End Date" }, "description": "YYYY-MM-DD" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageOverviewResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/policies/{policy_id}": { "get": { "tags": [ "Policies" ], "summary": "Get Policy", "description": "Get a policy by ID.\n\nExample Request:\n```bash\ncurl -X GET \"http://localhost:4000/policies/123e4567-e89b-12d3-a456-426614174000\" \\\n -H \"Authorization: Bearer \"\n```", "operationId": "get_policy_policies__policy_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "policy_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Policy Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyDBResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "Policies" ], "summary": "Update Policy", "description": "Update an existing policy.\n\nExample Request:\n```bash\ncurl -X PUT \"http://localhost:4000/policies/123e4567-e89b-12d3-a456-426614174000\" \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"description\": \"Updated description\",\n \"guardrails_add\": [\"pii_masking\", \"toxicity_filter\"]\n }'\n```", "operationId": "update_policy_policies__policy_id__put", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "policy_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Policy Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyDBResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Policies" ], "summary": "Delete Policy", "description": "Delete a policy.\n\nExample Request:\n```bash\ncurl -X DELETE \"http://localhost:4000/policies/123e4567-e89b-12d3-a456-426614174000\" \\\n -H \"Authorization: Bearer \"\n```\n\nExample Response:\n```json\n{\n \"message\": \"Policy 123e4567-e89b-12d3-a456-426614174000 deleted successfully\"\n}\n```", "operationId": "delete_policy_policies__policy_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "policy_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Policy Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/policies/{policy_id}/resolved-guardrails": { "get": { "tags": [ "Policies" ], "summary": "Get Resolved Guardrails", "description": "Get the resolved guardrails for a policy (including inherited guardrails).\n\nThis endpoint resolves the full inheritance chain and returns the final\nset of guardrails that would be applied for this policy.\n\nExample Request:\n```bash\ncurl -X GET \"http://localhost:4000/policies/123e4567-e89b-12d3-a456-426614174000/resolved-guardrails\" \\\n -H \"Authorization: Bearer \"\n```\n\nExample Response:\n```json\n{\n \"policy_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"policy_name\": \"healthcare-compliance\",\n \"resolved_guardrails\": [\"pii_masking\", \"prompt_injection\", \"toxicity_filter\"]\n}\n```", "operationId": "get_resolved_guardrails_policies__policy_id__resolved_guardrails_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "policy_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Policy Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/policies/{policy_id}/status": { "put": { "tags": [ "Policies" ], "summary": "Update Policy Version Status", "description": "Update a policy version's status. Valid transitions:\n- draft -> published\n- published -> production (demotes current production to published)\n- production -> published (demotes, policy becomes inactive)", "operationId": "update_policy_version_status_policies__policy_id__status_put", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "policy_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Policy Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyVersionStatusUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyDBResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }