{
	"openapi": "3.1.0",
	"info": {
		"title": "WhiteCircle API Backend",
		"version": "2025-06-15"
	},
	"servers": [
		{
			"url": "https://eu.whitecircle.com"
		},
		{
			"url": "https://us.whitecircle.com"
		}
	],
	"paths": {
		"/api/protect/check": {
			"post": {
				"tags": ["Protect"],
				"operationId": "check_v2",
				"parameters": [
					{
						"name": "whitecircle-version",
						"in": "header",
						"description": "API Version",
						"required": true,
						"schema": { "type": "string" },
						"example": "2025-06-15"
					}
				],
				"requestBody": {
					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckRequestV2" } } },
					"required": true
				},
				"responses": {
					"200": {
						"description": "Success",
						"content": {
							"application/json": { "schema": { "$ref": "#/components/schemas/CheckResponseV2" } }
						}
					},
					"400": { "description": "Bad Request" }
				},
				"security": [{ "bearerAuth": [] }]
			}
		},
		"/api/protect/get_by_id": {
			"get": {
				"tags": ["Protect"],
				"operationId": "get_by_id_v2",
				"parameters": [
					{
						"name": "whitecircle-version",
						"in": "header",
						"description": "API Version",
						"required": true,
						"schema": { "type": "string" },
						"example": "2025-06-15"
					},
					{
						"name": "deployment_id",
						"in": "query",
						"description": "Specific deployment ID used for the check. See Deployments.",
						"required": true,
						"schema": { "type": "string" }
					},
					{
						"name": "include_policy_names",
						"in": "query",
						"description": "Whether to include human-readable policy names in the response (default: false)",
						"required": false,
						"schema": { "type": ["boolean", "null"] }
					},
					{
						"name": "external_id",
						"in": "query",
						"description": "Find check results by external ID (your tracking identifier)",
						"required": false,
						"schema": { "type": ["string", "null"] }
					},
					{
						"name": "internal_id",
						"in": "query",
						"description": "Find check results by internal ID (system-generated UUID)",
						"required": false,
						"schema": { "type": ["string", "null"] }
					}
				],
				"responses": {
					"200": {
						"description": "Success",
						"content": {
							"application/json": { "schema": { "$ref": "#/components/schemas/GetByIdResponseV2" } }
						}
					},
					"400": { "description": "Bad Request" }
				},
				"security": [{ "bearerAuth": [] }]
			}
		},
		"/api/radar/risk": {
			"get": {
				"tags": ["Radar"],
				"operationId": "risk",
				"parameters": [
					{
						"name": "whitecircle-version",
						"in": "header",
						"description": "API Version",
						"required": true,
						"schema": { "type": "string" },
						"example": "2025-06-15"
					},
					{
						"name": "email",
						"in": "query",
						"description": "User email address (provide either email or id, not both)",
						"required": false,
						"schema": { "type": ["string", "null"] }
					},
					{
						"name": "id",
						"in": "query",
						"description": "External user ID (provide either email or id, not both)",
						"required": false,
						"schema": { "type": ["string", "null"] }
					}
				],
				"responses": {
					"200": {
						"description": "Success",
						"content": {
							"application/json": { "schema": { "$ref": "#/components/schemas/UserRiskResponse" } }
						}
					},
					"400": { "description": "Bad Request" }
				},
				"security": [{ "bearerAuth": [] }]
			}
		}
	},
	"components": {
		"schemas": {
			"ChatContentV2": {
				"oneOf": [
					{ "type": "string" },
					{ "type": "array", "items": { "$ref": "#/components/schemas/ContentPartV2" } }
				]
			},
			"ChatMessageV2": {
				"type": "object",
				"required": ["role"],
				"properties": {
					"content": { "oneOf": [{ "type": "null" }, { "$ref": "#/components/schemas/ChatContentV2" }] },
					"role": { "$ref": "#/components/schemas/ChatRole" }
				}
			},
			"ChatRole": { "type": "string", "enum": ["system", "assistant", "user"] },
			"CheckRequestV2": {
				"type": "object",
				"required": ["messages"],
				"properties": {
					"external_id": {
						"type": ["string", "null"],
						"description": "Optional external identifier for tracking this session. Useful for correlating results with your own systems"
					},
					"include_context": {
						"type": ["boolean", "null"],
						"description": "Include previous conversation context associated with the same external_id. Default: false."
					},
					"include_policy_names": {
						"type": ["boolean", "null"],
						"description": "Include human-readable policy names in the response. Default: false."
					},
					"messages": {
						"type": "array",
						"items": { "$ref": "#/components/schemas/ChatMessageV2" },
						"description": "Array of chat messages to analyze for policy violations. Required"
					},
					"metadata": {
						"type": "object",
						"description": "Optional metadata object for additional info about session.",
						"additionalProperties": {
							"type": "object",
							"additionalProperties": {},
							"propertyNames": { "type": "string" }
						},
						"propertyNames": { "type": "string" }
					},
					"policies": {
						"type": ["array", "null"],
						"items": { "type": "string" },
						"description": "Optional list of specific policy IDs to check. If omitted, all deployment policies are used."
					}
				},
				"example": {
					"external_id": "user-session-123",
					"include_context": true,
					"include_policy_names": true,
					"messages": [
						{ "content": "Hello, can you help me with something?", "role": "user" },
						{
							"content": [{ "text": "Of course! I'd be happy to help you.", "type": "text" }],
							"role": "assistant"
						}
					],
					"metadata": {
						"model": { "name": "gpt-4.1", "price_per_1m_tokens": 0.1 },
						"user": { "id": "abcd-1234" }
					}
				}
			},
			"CheckResponseV2": {
				"type": "object",
				"required": ["violation", "internal_id", "violations"],
				"properties": {
					"external_id": {
						"type": ["string", "null"],
						"description": "Optional external identifier provided by client"
					},
					"internal_id": { "type": "string", "description": "Unique internal identifier for this check" },
					"violation": { "type": "boolean", "description": "Whether any policy violations were detected" },
					"violations": {
						"type": "object",
						"description": "Map of policy IDs to policy status objects containing violation and optional name",
						"additionalProperties": { "$ref": "#/components/schemas/PolicyStatusV2" },
						"propertyNames": { "type": "string" }
					}
				},
				"example": {
					"external_id": "user-session-001",
					"internal_id": "123e4567-e89b-12d3-a456-426614174000",
					"violation": true,
					"violations": {
						"123e4567-e89b-12d3-a456-426614174000": {
							"name": "NSFW",
							"violation": true,
							"violation_source": ["image"]
						},
						"70289e06-9111-463e-b121-7247c2b7bfbd": {
							"name": "No PII Sharing",
							"violation": false,
							"violation_source": []
						},
						"a4a91875-1e54-42d7-b9b0-a75dfebeb057": {
							"name": "Drugs",
							"violation": true,
							"violation_source": ["text"]
						}
					}
				}
			},
			"ContentPartV2": {
				"oneOf": [
					{
						"type": "object",
						"required": ["text", "type"],
						"properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": ["text"] } }
					},
					{
						"type": "object",
						"required": ["text", "type"],
						"properties": {
							"text": { "type": "string" },
							"type": { "type": "string", "enum": ["input_text"] }
						}
					}
				]
			},
			"GetByIdQuery": {
				"type": "object",
				"properties": {
					"external_id": {
						"type": ["string", "null"],
						"description": "Find check results by external ID (your tracking identifier)"
					},
					"include_policy_names": {
						"type": ["boolean", "null"],
						"description": "Whether to include human-readable policy names in the response (default: false)"
					},
					"internal_id": {
						"type": ["string", "null"],
						"description": "Find check results by internal ID (system-generated UUID)"
					}
				}
			},
			"GetByIdResponseV2": {
				"type": "object",
				"required": ["list"],
				"properties": {
					"list": {
						"type": "array",
						"items": { "$ref": "#/components/schemas/CheckResponseV2" },
						"description": "List of check results matching the query"
					}
				},
				"example": {
					"list": [
						{
							"external_id": "user-session-001",
							"internal_id": "123e4567-e89b-12d3-a456-426614174000",
							"violation": true,
							"violations": {
								"70289e06-9111-463e-b121-7247c2b7bfbd": { "name": "No PII Sharing", "violation": true },
								"a4a91875-1e54-42d7-b9b0-a75dfebeb057": { "name": "Drugs", "violation": false }
							}
						}
					]
				}
			},
			"ImageUrl": {
				"type": "object",
				"required": ["url"],
				"properties": { "detail": { "type": ["string", "null"] }, "url": { "type": "string" } }
			},
			"PolicyStatusV2": {
				"type": "object",
				"required": ["violation", "violation_source"],
				"properties": {
					"name": {
						"type": ["string", "null"],
						"description": "Human-readable policy name (only present if include_policy_names=true)"
					},
					"violation": {
						"type": "boolean",
						"description": "Whether a violation was detected for this policy"
					},
					"violation_source": {
						"type": "array",
						"items": { "$ref": "#/components/schemas/ViolationSource" },
						"description": "Sources where violations were detected (includes only triggered violations)"
					}
				},
				"example": { "name": "No PII Sharing", "violation": true, "violation_source": ["text"] }
			},
			"RiskLevel": { "type": "string", "enum": ["normal", "elevated", "severe"] },
			"UserRiskQuery": {
				"type": "object",
				"properties": {
					"email": {
						"type": ["string", "null"],
						"description": "User email address (provide either email or id, not both)"
					},
					"id": {
						"type": ["string", "null"],
						"description": "External user ID (provide either email or id, not both)"
					}
				}
			},
			"UserRiskResponse": {
				"type": "object",
				"required": ["risk_level"],
				"properties": { "risk_level": { "$ref": "#/components/schemas/RiskLevel" } },
				"example": { "risk_level": "normal" }
			},
			"ViolationSource": { "type": "string", "enum": ["text", "image"] }
		},
		"securitySchemes": {
			"bearerAuth": {
				"type": "http",
				"scheme": "bearer",
				"bearerFormat": "API Key",
				"description": "API Key required. Format: Bearer wc-your-api-key"
			}
		}
	},
	"tags": [
		{ "name": "Protect", "description": "Content protection and policy checking" },
		{ "name": "Radar", "description": "Risk assessment and user scoring" }
	]
}
