{
  "openapi": "3.1.0",
  "info": {
    "title": "WhiteCircle API Backend",
    "description": "Authentication: Bearer API Key Required",
    "license": {
      "name": ""
    },
    "version": "2026-04-15"
  },
  "servers": [
    {
      "url": "https://eu.whitecircle.com"
    },
    {
      "url": "https://us.whitecircle.com"
    }
  ],
  "paths": {
    "/api/artifact": {
      "get": {
        "tags": [
          "Artifact"
        ],
        "operationId": "artifact_get_by_external_id_v4",
        "parameters": [
          {
            "name": "whitecircle-version",
            "in": "header",
            "description": "API Version",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-04-15"
          },
          {
            "name": "external_artifact_id",
            "in": "query",
            "description": "Find the latest artifact by your external artifact ID within the deployment",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "deployment_id",
            "in": "query",
            "description": "Optional deployment ID to validate artifact ownership",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArtifactCheckResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "post": {
        "tags": [
          "Artifact"
        ],
        "operationId": "artifact_check_v4",
        "parameters": [
          {
            "name": "whitecircle-version",
            "in": "header",
            "description": "API Version",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-04-15"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ArtifactCheckRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArtifactCheckResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/artifact/{internal_artifact_id}": {
      "get": {
        "tags": [
          "Artifact"
        ],
        "operationId": "artifact_get_by_id_v4",
        "parameters": [
          {
            "name": "whitecircle-version",
            "in": "header",
            "description": "API Version",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-04-15"
          },
          {
            "name": "internal_artifact_id",
            "in": "path",
            "description": "Find an artifact by its internal artifact ID",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "deployment_id",
            "in": "query",
            "description": "Optional deployment ID to validate artifact ownership",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArtifactCheckResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/metric/create": {
      "post": {
        "tags": [
          "Metric"
        ],
        "operationId": "create_metric_v1",
        "parameters": [
          {
            "name": "whitecircle-version",
            "in": "header",
            "description": "API Version",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-04-15"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePolicyRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicPolicy"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/metric/delete": {
      "post": {
        "tags": [
          "Metric"
        ],
        "operationId": "delete_metric_v1",
        "parameters": [
          {
            "name": "whitecircle-version",
            "in": "header",
            "description": "API Version",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-04-15"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeletePolicyPublicRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicPolicy"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/metric/get_by_id": {
      "get": {
        "tags": [
          "Metric"
        ],
        "operationId": "get_by_id_metric_v1",
        "parameters": [
          {
            "name": "whitecircle-version",
            "in": "header",
            "description": "API Version",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-04-15"
          },
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicPolicy"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/metric/list": {
      "get": {
        "tags": [
          "Metric"
        ],
        "operationId": "list_metric_v1",
        "parameters": [
          {
            "name": "whitecircle-version",
            "in": "header",
            "description": "API Version",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-04-15"
          },
          {
            "name": "deployment_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "content_type",
            "in": "query",
            "required": false,
            "schema": {
              "oneOf": [
                {
                  "type": "null"
                },
                {
                  "$ref": "#/components/schemas/PublicContentType"
                }
              ]
            }
          },
          {
            "name": "applies_to",
            "in": "query",
            "required": false,
            "schema": {
              "oneOf": [
                {
                  "type": "null"
                },
                {
                  "$ref": "#/components/schemas/PublicAppliesTo"
                }
              ]
            }
          },
          {
            "name": "mode",
            "in": "query",
            "required": false,
            "schema": {
              "oneOf": [
                {
                  "type": "null"
                },
                {
                  "$ref": "#/components/schemas/PublicPolicyMode"
                }
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PublicPolicy"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/metric/update": {
      "post": {
        "tags": [
          "Metric"
        ],
        "operationId": "update_metric_v1",
        "parameters": [
          {
            "name": "whitecircle-version",
            "in": "header",
            "description": "API Version",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-04-15"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdatePolicyRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicPolicy"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/policy/create": {
      "post": {
        "tags": [
          "Policy"
        ],
        "operationId": "create_v1",
        "parameters": [
          {
            "name": "whitecircle-version",
            "in": "header",
            "description": "API Version",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-04-15"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePolicyRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicPolicy"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/policy/delete": {
      "post": {
        "tags": [
          "Policy"
        ],
        "operationId": "delete_v1",
        "parameters": [
          {
            "name": "whitecircle-version",
            "in": "header",
            "description": "API Version",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-04-15"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeletePolicyPublicRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicPolicy"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/policy/get_by_id": {
      "get": {
        "tags": [
          "Policy"
        ],
        "operationId": "get_by_id_v1",
        "parameters": [
          {
            "name": "whitecircle-version",
            "in": "header",
            "description": "API Version",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-04-15"
          },
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicPolicy"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/policy/list": {
      "get": {
        "tags": [
          "Policy"
        ],
        "operationId": "list_v1",
        "parameters": [
          {
            "name": "whitecircle-version",
            "in": "header",
            "description": "API Version",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-04-15"
          },
          {
            "name": "deployment_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "content_type",
            "in": "query",
            "required": false,
            "schema": {
              "oneOf": [
                {
                  "type": "null"
                },
                {
                  "$ref": "#/components/schemas/PublicContentType"
                }
              ]
            }
          },
          {
            "name": "applies_to",
            "in": "query",
            "required": false,
            "schema": {
              "oneOf": [
                {
                  "type": "null"
                },
                {
                  "$ref": "#/components/schemas/PublicAppliesTo"
                }
              ]
            }
          },
          {
            "name": "mode",
            "in": "query",
            "required": false,
            "schema": {
              "oneOf": [
                {
                  "type": "null"
                },
                {
                  "$ref": "#/components/schemas/PublicPolicyMode"
                }
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PublicPolicy"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/policy/update": {
      "post": {
        "tags": [
          "Policy"
        ],
        "operationId": "update_v1",
        "parameters": [
          {
            "name": "whitecircle-version",
            "in": "header",
            "description": "API Version",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-04-15"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdatePolicyRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicPolicy"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/session": {
      "get": {
        "tags": [
          "Session"
        ],
        "operationId": "get_by_external_id_v4",
        "parameters": [
          {
            "name": "whitecircle-version",
            "in": "header",
            "description": "API Version",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-04-15"
          },
          {
            "name": "external_session_id",
            "in": "query",
            "description": "Find the latest session by your external session ID within the deployment",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "deployment_id",
            "in": "query",
            "description": "Optional deployment ID to validate session ownership",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionEnvelopeV4"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "post": {
        "tags": [
          "Session"
        ],
        "operationId": "check_v4",
        "parameters": [
          {
            "name": "whitecircle-version",
            "in": "header",
            "description": "API Version",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-04-15"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CheckRequestV4"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionEnvelopeV4"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/session/{internal_session_id}": {
      "get": {
        "tags": [
          "Session"
        ],
        "operationId": "get_by_id_v4",
        "parameters": [
          {
            "name": "whitecircle-version",
            "in": "header",
            "description": "API Version",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-04-15"
          },
          {
            "name": "internal_session_id",
            "in": "path",
            "description": "Find a session by its internal session ID",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "deployment_id",
            "in": "query",
            "description": "Optional deployment ID to validate session ownership",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionEnvelopeV4"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/user/risk": {
      "get": {
        "tags": [
          "User"
        ],
        "operationId": "risk_v3",
        "parameters": [
          {
            "name": "whitecircle-version",
            "in": "header",
            "description": "API Version",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-04-15"
          },
          {
            "name": "email",
            "in": "query",
            "description": "User email address (provide exactly one of email or id)",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "name": "id",
            "in": "query",
            "description": "External user ID (provide exactly one of email or id)",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserRiskResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/user/strike": {
      "post": {
        "tags": [
          "User"
        ],
        "operationId": "strike_v3",
        "parameters": [
          {
            "name": "whitecircle-version",
            "in": "header",
            "description": "API Version",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-04-15"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateUserStrikeRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateUserStrikeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/user/strike/appeal": {
      "get": {
        "tags": [
          "User"
        ],
        "operationId": "get_strike_appeal_v3",
        "parameters": [
          {
            "name": "whitecircle-version",
            "in": "header",
            "description": "API Version",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-04-15"
          },
          {
            "name": "strike_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ],
              "format": "uuid"
            }
          },
          {
            "name": "appeal_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ],
              "format": "uuid"
            }
          },
          {
            "name": "session_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserStrikeAppealResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "post": {
        "tags": [
          "User"
        ],
        "operationId": "create_strike_appeal_v3",
        "parameters": [
          {
            "name": "whitecircle-version",
            "in": "header",
            "description": "API Version",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-04-15"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateUserStrikeAppealRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateUserStrikeAppealResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "ArtifactCheckRequest": {
        "type": "object",
        "required": [
          "content"
        ],
        "properties": {
          "content": {
            "$ref": "#/components/schemas/ArtifactContent"
          },
          "deployment_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "external_artifact_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "external_session_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "internal_session_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "metadata": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/IndexMap"
              }
            ]
          },
          "role": {
            "type": [
              "string",
              "null"
            ]
          },
          "span_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "trace_id": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "ArtifactCheckResponse": {
        "type": "object",
        "required": [
          "status",
          "kind",
          "internal_artifact_id",
          "policies"
        ],
        "properties": {
          "flagged": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "policies": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/ArtifactPolicyStatus"
            },
            "propertyNames": {
              "type": "string"
            }
          },
          "kind": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "updated_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "internal_artifact_id": {
            "type": "string"
          },
          "external_artifact_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "external_session_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "internal_session_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "note": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "ArtifactContent": {
        "type": "object",
        "required": [
          "kind"
        ],
        "properties": {
          "data": {
            "type": [
              "string",
              "null"
            ]
          },
          "kind": {
            "type": "string"
          },
          "mime_type": {
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "ArtifactGetByExternalIdQueryV4": {
        "type": "object",
        "required": [
          "external_artifact_id"
        ],
        "properties": {
          "external_artifact_id": {
            "type": "string"
          },
          "deployment_id": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "ArtifactGetByIdPathV4": {
        "type": "object",
        "required": [
          "internal_artifact_id"
        ],
        "properties": {
          "internal_artifact_id": {
            "type": "string"
          }
        }
      },
      "ArtifactGetByIdQueryV4": {
        "type": "object",
        "properties": {
          "deployment_id": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "ArtifactPolicyStatus": {
        "type": "object",
        "required": [
          "flagged",
          "flagged_source",
          "name"
        ],
        "properties": {
          "flagged": {
            "type": "boolean"
          },
          "flagged_source": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "name": {
            "type": "string"
          }
        }
      },
      "AssistantInfoV3": {
        "type": "object",
        "properties": {
          "latency": {
            "type": [
              "number",
              "null"
            ],
            "format": "double"
          },
          "model_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "provider_url": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "CheckRequestV4": {
        "type": "object",
        "required": [
          "messages"
        ],
        "properties": {
          "messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RequestChatMessageV3"
            }
          },
          "external_session_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "include_context": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "additionalProperties": {},
              "propertyNames": {
                "type": "string"
              }
            },
            "propertyNames": {
              "type": "string"
            }
          },
          "deployment_id": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "example": {
          "messages": [
            {
              "content": "Hello, can you help me with something?",
              "metadata": {
                "message": {
                  "id": "msg-123"
                },
                "user": {
                  "email": "user@example.com",
                  "id": "user-456"
                }
              },
              "role": "user"
            },
            {
              "content": [
                {
                  "text": "Of course! I'd be happy to help you.",
                  "type": "text"
                }
              ],
              "metadata": {
                "assistant": {
                  "latency": 1.2,
                  "model_name": "gpt-4o-mini"
                }
              },
              "role": "assistant"
            }
          ],
          "external_session_id": "user-session-123",
          "include_context": true,
          "metadata": {
            "session": {
              "timestamp": "2026-04-15T10:00:00Z"
            }
          },
          "deployment_id": "your-deployment-id"
        }
      },
      "CheckResponseV4": {
        "type": "object",
        "required": [
          "flagged",
          "internal_session_id",
          "policies"
        ],
        "properties": {
          "flagged": {
            "type": "boolean"
          },
          "internal_session_id": {
            "type": "string"
          },
          "external_session_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "policies": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/PolicyStatusV3"
            },
            "propertyNames": {
              "type": "string"
            }
          },
          "note": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "example": {
          "flagged": true,
          "internal_session_id": "123e4567-e89b-12d3-a456-426614174000",
          "external_session_id": "user-session-001",
          "policies": {
            "70289e06-9111-463e-b121-7247c2b7bfbd": {
              "flagged": true,
              "flagged_source": [
                "text"
              ],
              "name": "No PII Sharing"
            }
          }
        }
      },
      "CreatePolicyRequest": {
        "type": "object",
        "required": [
          "name",
          "flagged_content"
        ],
        "properties": {
          "allowed_content": {
            "type": [
              "string",
              "null"
            ]
          },
          "applies_to": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/PublicAppliesTo"
              }
            ]
          },
          "content_type": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/PublicContentType"
              }
            ]
          },
          "country_codes": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "deployment_ids": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "flagged_content": {
            "type": "string"
          },
          "mode": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/PublicPolicyMode"
              }
            ]
          },
          "name": {
            "type": "string"
          },
          "rollout_percentage": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32"
          },
          "severity_level_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          }
        }
      },
      "CreateUserStrikeAppealRequest": {
        "type": "object",
        "required": [
          "reason"
        ],
        "properties": {
          "reason": {
            "type": "string"
          },
          "session_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "strike_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          }
        }
      },
      "CreateUserStrikeAppealResponse": {
        "type": "object",
        "required": [
          "appeal_id",
          "status"
        ],
        "properties": {
          "appeal_id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        }
      },
      "CreateUserStrikeRequest": {
        "type": "object",
        "required": [
          "policy_id",
          "severity_level_id"
        ],
        "properties": {
          "email": {
            "type": [
              "string",
              "null"
            ]
          },
          "external_session_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "type": [
              "string",
              "null"
            ]
          },
          "internal_session_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "policy_id": {
            "type": "string"
          },
          "severity_level_id": {
            "type": "string",
            "format": "uuid"
          }
        },
        "additionalProperties": false
      },
      "CreateUserStrikeResponse": {
        "type": "object",
        "required": [
          "strike"
        ],
        "properties": {
          "action": {
            "type": [
              "string",
              "null"
            ]
          },
          "action_expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "strike": {
            "$ref": "#/components/schemas/PublicStrikeItem"
          }
        }
      },
      "DeletePolicyPublicRequest": {
        "type": "object",
        "required": [
          "id"
        ],
        "properties": {
          "id": {
            "type": "string"
          }
        }
      },
      "GetByExternalIdQueryV4": {
        "type": "object",
        "required": [
          "external_session_id"
        ],
        "properties": {
          "deployment_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional deployment ID to validate session ownership"
          },
          "external_session_id": {
            "type": "string",
            "description": "Find the latest session by your external session ID within the deployment"
          }
        }
      },
      "GetByIdPathV4": {
        "type": "object",
        "required": [
          "internal_session_id"
        ],
        "properties": {
          "internal_session_id": {
            "type": "string",
            "description": "Find a session by its internal session ID"
          }
        }
      },
      "GetByIdQueryV4": {
        "type": "object",
        "properties": {
          "deployment_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional deployment ID to validate session ownership"
          }
        }
      },
      "IndexMap": {
        "type": "object",
        "additionalProperties": {
          "type": "object",
          "additionalProperties": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "number",
                "format": "double"
              },
              {
                "type": "boolean"
              }
            ]
          },
          "propertyNames": {
            "type": "string"
          }
        },
        "propertyNames": {
          "type": "string"
        }
      },
      "MessageInfoV3": {
        "type": "object",
        "properties": {
          "id": {
            "type": [
              "string",
              "null"
            ]
          },
          "timestamp": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "MessageMetadataV3": {
        "type": "object",
        "properties": {
          "assistant": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/AssistantInfoV3"
              }
            ]
          },
          "message": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/MessageInfoV3"
              }
            ]
          },
          "user": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/UserInfoV3"
              }
            ]
          }
        }
      },
      "PolicyStatusV3": {
        "type": "object",
        "required": [
          "flagged",
          "flagged_source",
          "name"
        ],
        "properties": {
          "flagged": {
            "type": "boolean"
          },
          "flagged_source": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ViolationSource"
            }
          },
          "name": {
            "type": "string"
          }
        }
      },
      "PublicAppliesTo": {
        "type": "string",
        "enum": [
          "input",
          "output",
          "any"
        ],
        "example": "input"
      },
      "PublicContentType": {
        "type": "string",
        "enum": [
          "session",
          "artifact",
          "any"
        ],
        "example": "session"
      },
      "PublicPolicy": {
        "type": "object",
        "required": [
          "id",
          "name",
          "flagged_content",
          "content_type",
          "applies_to",
          "mode",
          "rollout_percentage",
          "revision_id",
          "created_at",
          "deployment_ids",
          "country_codes"
        ],
        "properties": {
          "allowed_content": {
            "type": [
              "string",
              "null"
            ]
          },
          "applies_to": {
            "$ref": "#/components/schemas/PublicAppliesTo"
          },
          "content_type": {
            "$ref": "#/components/schemas/PublicContentType"
          },
          "country_codes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "deleted_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "deployment_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "flagged_content": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "mode": {
            "$ref": "#/components/schemas/PublicPolicyMode"
          },
          "name": {
            "type": "string"
          },
          "revision_id": {
            "type": "string"
          },
          "rollout_percentage": {
            "type": "integer",
            "format": "int32",
            "minimum": 0
          },
          "severity_level_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          }
        }
      },
      "PublicPolicyMode": {
        "type": "string",
        "enum": [
          "prod",
          "shadow"
        ],
        "example": "prod"
      },
      "PublicStrikeAppeal": {
        "type": "object",
        "required": [
          "time",
          "status"
        ],
        "properties": {
          "status": {
            "type": "string"
          },
          "time": {
            "type": "integer",
            "format": "int64"
          }
        }
      },
      "PublicStrikeItem": {
        "type": "object",
        "required": [
          "points",
          "created_at",
          "reason",
          "internal_session_id",
          "policy"
        ],
        "properties": {
          "appeal": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/PublicStrikeAppeal"
              }
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "external_session_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "internal_session_id": {
            "type": "string"
          },
          "points": {
            "type": "integer",
            "format": "int32"
          },
          "policy": {
            "$ref": "#/components/schemas/PublicStrikePolicy"
          },
          "reason": {
            "type": "string"
          }
        }
      },
      "PublicStrikePolicy": {
        "type": "object",
        "required": [
          "id",
          "name",
          "severity"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "severity": {
            "type": "string"
          }
        }
      },
      "RequestChatContent": {
        "oneOf": [
          {
            "type": "string"
          },
          {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RequestContentPart"
            }
          }
        ]
      },
      "RequestChatMessageV3": {
        "type": "object",
        "required": [
          "role"
        ],
        "properties": {
          "content": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/RequestChatContent"
              }
            ]
          },
          "metadata": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/MessageMetadataV3"
              }
            ]
          },
          "role": {
            "type": "string"
          }
        }
      },
      "RequestChatRole": {
        "type": "string",
        "enum": [
          "system",
          "assistant",
          "user",
          "tool",
          "developer"
        ]
      },
      "RequestContentPart": {
        "oneOf": [
          {
            "type": "object",
            "required": [
              "text",
              "type"
            ],
            "properties": {
              "text": {
                "type": "string"
              },
              "type": {
                "type": "string",
                "enum": [
                  "text"
                ]
              }
            }
          },
          {
            "type": "object",
            "required": [
              "image_url",
              "type"
            ],
            "properties": {
              "image_url": {
                "$ref": "#/components/schemas/RequestImageUrl"
              },
              "type": {
                "type": "string",
                "enum": [
                  "image_url"
                ]
              }
            }
          },
          {
            "type": "object",
            "required": [
              "text",
              "type"
            ],
            "properties": {
              "text": {
                "type": "string"
              },
              "type": {
                "type": "string",
                "enum": [
                  "input_text"
                ]
              }
            }
          },
          {
            "type": "object",
            "required": [
              "image_url",
              "type"
            ],
            "properties": {
              "image_url": {
                "type": "string"
              },
              "type": {
                "type": "string",
                "enum": [
                  "input_image"
                ]
              }
            }
          },
          {
            "type": "object",
            "required": [
              "type"
            ],
            "properties": {
              "content": {
                "oneOf": [
                  {
                    "type": "null"
                  },
                  {
                    "$ref": "#/components/schemas/ArtifactContent"
                  }
                ]
              },
              "external_artifact_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "internal_artifact_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "type": {
                "type": "string",
                "enum": [
                  "artifact"
                ]
              }
            }
          }
        ]
      },
      "RequestImageUrl": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "detail": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": "string"
          }
        }
      },
      "RiskLevel": {
        "type": "string",
        "enum": [
          "normal",
          "elevated",
          "severe"
        ]
      },
      "SessionEnvelopeV4": {
        "type": "object",
        "required": [
          "session",
          "artifacts"
        ],
        "properties": {
          "session": {
            "$ref": "#/components/schemas/CheckResponseV4"
          },
          "artifacts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ArtifactCheckResponse"
            }
          }
        },
        "example": {
          "session": {
            "flagged": true,
            "internal_session_id": "123e4567-e89b-12d3-a456-426614174000",
            "external_session_id": "user-session-001",
            "policies": {
              "70289e06-9111-463e-b121-7247c2b7bfbd": {
                "flagged": true,
                "flagged_source": [
                  "text"
                ],
                "name": "No PII Sharing"
              }
            }
          },
          "artifacts": [
            {
              "flagged": true,
              "policies": {
                "70289e06-9111-463e-b121-7247c2b7bfbd": {
                  "flagged": true,
                  "flagged_source": [
                    "image"
                  ],
                  "name": "No PII Sharing"
                }
              },
              "kind": "image",
              "status": "completed",
              "updated_at": "2026-04-15T12:00:00Z",
              "internal_artifact_id": "223e4567-e89b-12d3-a456-426614174000",
              "external_artifact_id": "artifact-001",
              "external_session_id": "user-session-001",
              "internal_session_id": "123e4567-e89b-12d3-a456-426614174000",
              "created_at": "2026-04-15T12:00:00Z"
            }
          ]
        }
      },
      "UpdatePolicyRequest": {
        "type": "object",
        "required": [
          "id"
        ],
        "properties": {
          "allowed_content": {
            "type": [
              "string",
              "null"
            ]
          },
          "applies_to": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/PublicAppliesTo"
              }
            ]
          },
          "content_type": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/PublicContentType"
              }
            ]
          },
          "country_codes": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "deployment_ids": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "flagged_content": {
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "type": "string"
          },
          "mode": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/PublicPolicyMode"
              }
            ]
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "rollout_percentage": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32"
          },
          "severity_level_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          }
        }
      },
      "UserInfoV3": {
        "type": "object",
        "properties": {
          "city": {
            "type": [
              "string",
              "null"
            ],
            "description": "City name",
            "example": "San Francisco"
          },
          "country": {
            "type": [
              "string",
              "null"
            ],
            "description": "Full country name",
            "example": "United States"
          },
          "country_code": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB')",
            "example": "US"
          },
          "email": {
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "type": [
              "string",
              "null"
            ]
          },
          "ip": {
            "type": [
              "string",
              "null"
            ],
            "description": "User's IP address for geolocation lookup",
            "example": "8.8.8.8"
          },
          "latitude": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Latitude coordinate",
            "example": 37.7749
          },
          "longitude": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Longitude coordinate",
            "example": -122.4194
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "state": {
            "type": [
              "string",
              "null"
            ],
            "description": "State/province name or code",
            "example": "California"
          }
        }
      },
      "UserRiskQuery": {
        "type": "object",
        "properties": {
          "email": {
            "type": [
              "string",
              "null"
            ],
            "description": "User email address (provide exactly one of email or id)"
          },
          "id": {
            "type": [
              "string",
              "null"
            ],
            "description": "External user ID (provide exactly one of email or id)"
          }
        },
        "additionalProperties": false
      },
      "UserRiskResponse": {
        "type": "object",
        "properties": {
          "action": {
            "type": [
              "string",
              "null"
            ]
          },
          "action_expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "strikes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicStrikeItem"
            }
          },
          "total_strike_points": {
            "type": "integer",
            "format": "int32"
          }
        },
        "example": {
          "action": null,
          "action_expires_at": null,
          "strikes": [],
          "total_strike_points": 0
        }
      },
      "UserStrikeAppealResponse": {
        "type": "object",
        "required": [
          "appeal_id",
          "status",
          "current_points"
        ],
        "properties": {
          "appeal_id": {
            "type": "string"
          },
          "current_level": {
            "type": [
              "string",
              "null"
            ]
          },
          "current_points": {
            "type": "integer",
            "format": "int32"
          },
          "status": {
            "type": "string"
          },
          "updated_by": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "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": "Session",
      "description": "Session-based content checking and moderation"
    },
    {
      "name": "User",
      "description": "User risk assessment and scoring"
    },
    {
      "name": "Policy",
      "description": "Policy management CRUD"
    },
    {
      "name": "Metric",
      "description": "Metric management CRUD"
    },
    {
      "name": "Artifact",
      "description": "Standalone artifact moderation"
    }
  ]
}
