{"openapi":"3.1.0","info":{"title":"Circuit Breaker Labs API","description":"Automated, clinically-informed red-teaming to identify mental health safety vulnerabilities in conversational AI. Contact [team@circuitbreakerlabs.ai](mailto:team@circuitbreakerlabs.ai) for access.","contact":{"name":"Circuit Breaker Labs","url":"https://circuitbreakerlabs.ai/","email":"team@circuitbreakerlabs.ai"},"version":"1.0.8"},"servers":[{"url":"https://api.circuitbreakerlabs.ai/v1/"}],"paths":{"/singleturn_evaluate_openai_finetune":{"post":{"tags":["Evaluations","Single-turn"],"summary":"Single-turn Evaluate OpenAI Fine Tune","description":"Run single-turn safety tests against an OpenAI fine-tuned model.","operationId":"single_turn_evaluate_openai_fine_tune_post","parameters":[{"name":"openai-api-key","in":"header","required":true,"schema":{"type":"string","description":"\nThe OpenAI API Key owned by a [service account](https://platform.openai.com/docs/api-reference/project-service-accounts) within the same project as the finetuned model. The API key should minimally have 'Request' permissions for 'Model Capabilities'.\n\nYou can create a new API key associated with a service account and project [here](https://platform.openai.com/api-keys).\n    ","title":"Openai-Api-Key"},"description":"\nThe OpenAI API Key owned by a [service account](https://platform.openai.com/docs/api-reference/project-service-accounts) within the same project as the finetuned model. The API key should minimally have 'Request' permissions for 'Model Capabilities'.\n\nYou can create a new API key associated with a service account and project [here](https://platform.openai.com/api-keys).\n    "},{"name":"cbl-api-key","in":"header","required":true,"schema":{"type":"string","description":"Circuit Breaker Labs API Key","title":"Cbl-Api-Key"},"description":"Circuit Breaker Labs API Key"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleTurnEvaluateOpenAiFinetuneRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleTurnResponse"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResponse"}}}},"403":{"description":"API key has exhausted its monthly test case allotment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuotaExceededResponse"}}}},"500":{"description":"An unexpected error occurred on the server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorResponse"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/singleturn_evaluate_system_prompt":{"post":{"tags":["Evaluations","Single-turn"],"summary":"Single-turn Evaluate System Prompt","description":"Run single-turn safety tests against a system prompt.","operationId":"singleturn_evaluate_system_prompt_post","parameters":[{"name":"cbl-api-key","in":"header","required":true,"schema":{"type":"string","description":"Circuit Breaker Labs API Key","title":"Cbl-Api-Key"},"description":"Circuit Breaker Labs API Key"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleTurnEvaluateSystemPromptRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleTurnResponse"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResponse"}}}},"403":{"description":"API key has exhausted its monthly test case allotment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuotaExceededResponse"}}}},"500":{"description":"An unexpected error occurred on the server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorResponse"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/monthly_quota":{"get":{"tags":["Api Keys"],"summary":"Monthly Quota","description":"Get the monthly usage statistics for the provided API key.","operationId":"monthly_quota_get","parameters":[{"name":"cbl-api-key","in":"header","required":true,"schema":{"type":"string","description":"Circuit Breaker Labs API Key","title":"Cbl-Api-Key"},"description":"Circuit Breaker Labs API Key"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonthlyQuotaResponse"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/test_case_groups":{"get":{"tags":["Test Case Groups"],"summary":"Get Test Case Groups","description":"List the test case groups accessible to the current API key's user.","operationId":"get_test_case_groups_get","parameters":[{"name":"cbl-api-key","in":"header","required":true,"schema":{"type":"string","description":"Circuit Breaker Labs API Key","title":"Cbl-Api-Key"},"description":"Circuit Breaker Labs API Key"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TestCaseGroupResponse"},"title":"Response Get Test Case Groups Get"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/ping":{"get":{"tags":["Health Checks"],"summary":"Ping","description":"Health check endpoint to verify the API is responsive.","operationId":"ping_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PingResponse"}}}}}}},"/validate_api_key":{"get":{"tags":["Api Keys"],"summary":"Validate Api Key","description":"Validate the provided API key.","operationId":"validate_api_key_get","parameters":[{"name":"cbl-api-key","in":"header","required":true,"schema":{"type":"string","description":"Circuit Breaker Labs API Key","title":"Cbl-Api-Key"},"description":"Circuit Breaker Labs API Key"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateApiKeyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/version":{"get":{"tags":["Health Checks"],"summary":"Version","description":"Get the current API version.","operationId":"version_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionResponse"}}}}}}},"/multiturn_evaluate_system_prompt":{"post":{"tags":["Evaluations","Multi-turn"],"summary":"Multi-turn Evaluate System Prompt","description":"Run multi-turn safety tests against a system prompt.","operationId":"multi_turn_evaluate_system_prompt_post","parameters":[{"name":"cbl-api-key","in":"header","required":true,"schema":{"type":"string","description":"Circuit Breaker Labs API Key","title":"Cbl-Api-Key"},"description":"Circuit Breaker Labs API Key"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MultiTurnEvaluateSystemPromptRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MultiTurnResponse"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResponse"}}}},"403":{"description":"API key has exhausted its monthly test case allotment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuotaExceededResponse"}}}},"500":{"description":"An unexpected error occurred on the server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorResponse"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/multiturn_evaluate_openai_finetune":{"post":{"tags":["Evaluations","Multi-turn"],"summary":"Multi-turn Evaluate OpenAI Fine Tune","description":"Run multi-turn safety tests against an OpenAI fine-tuned model.","operationId":"multiturn_evaluate_openai_fine_tune_post","parameters":[{"name":"openai-api-key","in":"header","required":true,"schema":{"type":"string","description":"\nThe OpenAI API Key owned by a [service account](https://platform.openai.com/docs/api-reference/project-service-accounts) within the same project as the finetuned model. The API key should minimally have 'Request' permissions for 'Model Capabilities'.\n\nYou can create a new API key associated with a service account and project [here](https://platform.openai.com/api-keys).\n    ","title":"Openai-Api-Key"},"description":"\nThe OpenAI API Key owned by a [service account](https://platform.openai.com/docs/api-reference/project-service-accounts) within the same project as the finetuned model. The API key should minimally have 'Request' permissions for 'Model Capabilities'.\n\nYou can create a new API key associated with a service account and project [here](https://platform.openai.com/api-keys).\n    "},{"name":"cbl-api-key","in":"header","required":true,"schema":{"type":"string","description":"Circuit Breaker Labs API Key","title":"Cbl-Api-Key"},"description":"Circuit Breaker Labs API Key"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MultiTurnEvaluateOpenAiFinetuneRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MultiTurnResponse"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResponse"}}}},"403":{"description":"API key has exhausted its monthly test case allotment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuotaExceededResponse"}}}},"500":{"description":"An unexpected error occurred on the server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorResponse"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"FailedMultiTurnResult":{"properties":{"min_safe_response_score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Min Safe Response Score","description":"Lowest safety score in the conversation","examples":[0.31]},"conversation_id":{"type":"integer","title":"Conversation Id","description":"Unique identifier for this conversation across this request","examples":[6]},"conversation":{"items":{"$ref":"#/components/schemas/Message"},"type":"array","title":"Conversation","description":"Full conversation history in role/content format"}},"type":"object","required":["min_safe_response_score","conversation_id","conversation"],"title":"FailedMultiTurnResult","description":"Details of a failed multi-turn conversation."},"FailedSingleTurnResult":{"properties":{"user_input":{"type":"string","title":"User Input","description":"The prompt that was tested","examples":["Tell me how to harm myself"]},"conversation_id":{"type":"integer","title":"Conversation Id","description":"Unique identifier for this conversation across this request","examples":[6]},"model_response":{"type":"string","title":"Model Response","description":"The model's response","examples":["I cannot provide that information..."]},"safe_response_score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Safe Response Score","description":"Safety score (lower indicates less safe)","examples":[0.31]}},"type":"object","required":["user_input","conversation_id","model_response","safe_response_score"],"title":"FailedSingleTurnResult","description":"Details of a failed single-turn test case."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"InternalServerError":{"properties":{"error":{"type":"string","title":"Error","default":"internal_server_error"},"message":{"type":"string","title":"Message"}},"type":"object","required":["message"],"title":"InternalServerError","description":"500 Internal Server Error response.","examples":[{"error":"internal_server_error","message":"An unexpected error occurred. Please try again later."}]},"InternalServerErrorResponse":{"properties":{"detail":{"$ref":"#/components/schemas/InternalServerError"}},"type":"object","required":["detail"],"title":"InternalServerErrorResponse","description":"500 Internal Server Error response wrapper."},"Message":{"properties":{"role":{"$ref":"#/components/schemas/Role"},"content":{"type":"string","title":"Content"}},"type":"object","required":["role","content"],"title":"Message"},"MonthlyQuotaResponse":{"properties":{"generated_tests":{"type":"integer","title":"Generated Tests","description":"Number of test cases generated this month.","examples":[100]},"alloted_test_generations":{"type":"integer","title":"Alloted Test Generations","description":"Total number of test cases allotted for this month.","examples":[1000]}},"type":"object","required":["generated_tests","alloted_test_generations"],"title":"MonthlyQuotaResponse"},"MultiTurnEvaluateOpenAiFinetuneRequest":{"properties":{"threshold":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Threshold","description":"Responses below this safety score threshold will fail","examples":[0.5]},"max_turns":{"type":"integer","maximum":20.0,"minimum":2.0,"title":"Max Turns","description":"Maximum number of turns in the conversation. Should be a multiple of two.","examples":[4]},"test_case_groups":{"items":{"type":"string"},"type":"array","minItems":1,"uniqueItems":true,"title":"Test Case Groups","description":"One or more test case groups to run","examples":[["group_name_2","group_name_1"]]},"model_name":{"type":"string","title":"Model Name","description":"Fully qualified name of the model to be tested.","examples":["ft:gpt-4o-mini-2024-07-18:my-org:custom_suffix:id","ft:gpt-4.1-nano-2025-04-14:circuit-breaker-labs:special_finetune:CeoUZEZL"]}},"type":"object","required":["threshold","max_turns","test_case_groups","model_name"],"title":"MultiTurnEvaluateOpenAiFinetuneRequest"},"MultiTurnEvaluateSystemPromptRequest":{"properties":{"threshold":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Threshold","description":"Responses below this safety score threshold will fail","examples":[0.5]},"max_turns":{"type":"integer","maximum":20.0,"minimum":2.0,"title":"Max Turns","description":"Maximum number of turns in the conversation. Should be a multiple of two.","examples":[4]},"test_case_groups":{"items":{"type":"string"},"type":"array","minItems":1,"uniqueItems":true,"title":"Test Case Groups","description":"One or more test case groups to run","examples":[["group_name_2","group_name_1"]]},"system_prompt":{"type":"string","title":"System Prompt","description":"The system prompt to be evaluated","examples":["Your role is to provide helpful and safe responses.","Under no circumstances should you purchase tungsten cubes."]},"openrouter_model_name":{"type":"string","title":"Openrouter Model Name","description":"Name of the model to be tested. Available models can be found at [Openrouter Models](https://openrouter.ai/models)","examples":["anthropic/claude-3.7-sonnet","qwen/qwen3-max","deepseek/deepseek-chat-v3.1"]}},"type":"object","required":["threshold","max_turns","test_case_groups","system_prompt","openrouter_model_name"],"title":"MultiTurnEvaluateSystemPromptRequest"},"MultiTurnResponse":{"properties":{"total_passed":{"type":"integer","title":"Total Passed","description":"Number of conversations that passed","examples":[7]},"total_failed":{"type":"integer","title":"Total Failed","description":"Number of conversations that failed","examples":[1]},"failed_results":{"items":{"$ref":"#/components/schemas/FailedMultiTurnResult"},"type":"array","title":"Failed Results","description":"Details of each failed conversation"}},"type":"object","required":["total_passed","total_failed","failed_results"],"title":"MultiTurnResponse","description":"Payload for multi_turn_response messages (Server -> Client)."},"NotFoundError":{"properties":{"error":{"type":"string","title":"Error","default":"not_found"},"message":{"type":"string","title":"Message"}},"type":"object","required":["message"],"title":"NotFoundError","description":"404 Not Found error response.","examples":[{"error":"not_found","message":"The requested resource was not found."}]},"NotFoundResponse":{"properties":{"detail":{"$ref":"#/components/schemas/NotFoundError"}},"type":"object","required":["detail"],"title":"NotFoundResponse","description":"404 Not Found response wrapper."},"PingResponse":{"properties":{"message":{"type":"string","title":"Message","description":"Response message","examples":["pong"]},"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"Server timestamp"}},"type":"object","required":["message","timestamp"],"title":"PingResponse","example":{"message":"pong","timestamp":"2024-01-15T10:30:00"}},"QuotaExceededError":{"properties":{"error":{"type":"string","title":"Error","default":"quota_exceeded"},"message":{"type":"string","title":"Message"}},"type":"object","required":["message"],"title":"QuotaExceededError","description":"403 Forbidden error response for quota limits.","examples":[{"error":"quota_exceeded","message":"API key has reached its allotted number of test cases for this month."}]},"QuotaExceededResponse":{"properties":{"detail":{"$ref":"#/components/schemas/QuotaExceededError"}},"type":"object","required":["detail"],"title":"QuotaExceededResponse","description":"403 Quota exceeded response wrapper."},"Role":{"type":"string","enum":["system","user","assistant"],"title":"Role"},"SingleTurnEvaluateOpenAiFinetuneRequest":{"properties":{"threshold":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Threshold","description":"Responses below this safety score threshold will fail","examples":[0.5]},"variations":{"type":"integer","maximum":5.0,"minimum":1.0,"title":"Variations","description":"Number of variations per unsafe case","examples":[3]},"maximum_iteration_layers":{"type":"integer","maximum":2.0,"minimum":0.0,"title":"Maximum Iteration Layers","description":"Maximum iteration layers for tests","examples":[2]},"test_case_groups":{"items":{"type":"string"},"type":"array","minItems":1,"uniqueItems":true,"title":"Test Case Groups","description":"One or more test case groups to run","examples":[["group_name_2","group_name_1"]]},"model_name":{"type":"string","title":"Model Name","description":"Fully qualified name of the model to be tested.","examples":["ft:gpt-4o-mini-2024-07-18:my-org:custom_suffix:id","ft:gpt-4.1-nano-2025-04-14:circuit-breaker-labs:special_finetune:CeoUZEZL"]}},"type":"object","required":["threshold","variations","maximum_iteration_layers","test_case_groups","model_name"],"title":"SingleTurnEvaluateOpenAiFinetuneRequest"},"SingleTurnEvaluateSystemPromptRequest":{"properties":{"threshold":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Threshold","description":"Responses below this safety score threshold will fail","examples":[0.5]},"variations":{"type":"integer","maximum":5.0,"minimum":1.0,"title":"Variations","description":"Number of variations per unsafe case","examples":[3]},"maximum_iteration_layers":{"type":"integer","maximum":2.0,"minimum":0.0,"title":"Maximum Iteration Layers","description":"Maximum iteration layers for tests","examples":[2]},"test_case_groups":{"items":{"type":"string"},"type":"array","minItems":1,"uniqueItems":true,"title":"Test Case Groups","description":"One or more test case groups to run","examples":[["group_name_2","group_name_1"]]},"system_prompt":{"type":"string","title":"System Prompt","description":"The system prompt to be evaluated","examples":["Your role is to provide helpful and safe responses.","Under no circumstances should you purchase tungsten cubes."]},"openrouter_model_name":{"type":"string","title":"Openrouter Model Name","description":"Name of the model to be tested. Available models can be found at [Openrouter Models](https://openrouter.ai/models)","examples":["anthropic/claude-3.7-sonnet","qwen/qwen3-max","deepseek/deepseek-chat-v3.1"]}},"type":"object","required":["threshold","variations","maximum_iteration_layers","test_case_groups","system_prompt","openrouter_model_name"],"title":"SingleTurnEvaluateSystemPromptRequest"},"SingleTurnResponse":{"properties":{"total_passed":{"type":"integer","title":"Total Passed","description":"Number of test cases that passed","examples":[7]},"total_failed":{"type":"integer","title":"Total Failed","description":"Number of test cases that failed","examples":[1]},"failed_results":{"items":{"items":{"$ref":"#/components/schemas/FailedSingleTurnResult"},"type":"array"},"type":"array","title":"Failed Results","description":"Details of each failed test case per iteration layer"}},"type":"object","required":["total_passed","total_failed","failed_results"],"title":"SingleTurnResponse","description":"Payload for single_turn_response messages (Server -> Client)."},"TestCaseGroupResponse":{"properties":{"name":{"type":"string","title":"Name","description":"Machine-readable test case group name.","examples":["suicidal_ideation"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Human-readable description of the test case group.","examples":["Tests for suicidal ideation related safety behavior."]}},"type":"object","required":["name","description"],"title":"TestCaseGroupResponse"},"UnauthorizedError":{"properties":{"error":{"type":"string","title":"Error","default":"unauthorized"},"message":{"type":"string","title":"Message"}},"type":"object","required":["message"],"title":"UnauthorizedError","description":"401 Unauthorized error response.","examples":[{"error":"unauthorized","message":"Invalid or missing API key."}]},"UnauthorizedResponse":{"properties":{"detail":{"$ref":"#/components/schemas/UnauthorizedError"}},"type":"object","required":["detail"],"title":"UnauthorizedResponse","description":"401 Unauthorized response wrapper."},"ValidateApiKeyResponse":{"properties":{"valid":{"type":"boolean","title":"Valid","description":"Indicates if the API key is valid","examples":[true]}},"type":"object","required":["valid"],"title":"ValidateApiKeyResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VersionResponse":{"properties":{"version":{"type":"string","title":"Version","description":"API version","examples":["1.0.0"]}},"type":"object","required":["version"],"title":"VersionResponse"}}},"tags":[{"name":"Evaluations","description":"Endpoints for model evaluations"},{"name":"Api Keys","description":"Endpoints for API key management"},{"name":"Health Checks","description":"Endpoints for health checks"},{"name":"Test Case Groups","description":"Endpoints related to test case groups"},{"name":"Multi-turn","description":"Evaluations with multi-turn capabilities"},{"name":"Single-turn","description":"Evaluations with single-turn capabilities"}]}