openapi: 3.0.1 info: title: Cleanlab API description: >- Specification of the Cleanlab data-and-AI trust platform APIs. Covers the Trustworthy Language Model (TLM) OpenAI-compatible Chat Completions endpoint, the Codex / Cleanlab AI Platform project validation (guardrail and remediation) endpoint, and the Cleanlab Studio deployed-model REST inference endpoint. All endpoints are HTTPS REST and authenticate with a Cleanlab API key (or project access key) supplied as a Bearer token. termsOfService: https://cleanlab.ai/legal/terms-of-service/ contact: name: Cleanlab Support email: support@cleanlab.ai version: '1.0' servers: - url: https://api.cleanlab.ai description: Cleanlab platform API paths: /api/v1/openai_trustworthy_llm/v1/chat/completions: post: operationId: createTrustworthyChatCompletion tags: - TLM summary: Trustworthy chat completion (OpenAI-compatible) description: >- OpenAI-compatible Chat Completions endpoint that returns a standard completion plus a Cleanlab trustworthiness score. Point the OpenAI client base_url at https://api.cleanlab.ai/api/v1/openai_trustworthy_llm/ and the client appends /v1/chat/completions automatically. The trustworthiness score (0-1) is returned in tlm_metadata on the response. Set stream=true to receive the completion as Server-Sent Events; the final SSE chunk carries the tlm_metadata. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ChatCompletionRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ChatCompletionResponse' text/event-stream: schema: type: string description: Server-Sent Events stream of chat completion chunks (stream=true). '401': description: Invalid or missing API key. '422': description: Invalid request parameters. '429': description: Rate limit exceeded. /api/v1/codex/projects/{project_id}/validate: post: operationId: validateResponse tags: - Codex summary: Validate an AI response (guardrail + remediation) description: >- Validates an AI application's response against a Codex project. Returns whether the response should be guardrailed, eval scores across configured criteria, whether it was escalated to a subject-matter expert, and an expert answer to remediate the response when a semantically similar verified answer exists in the project. Authenticate with the project access key as a Bearer token. parameters: - name: project_id in: path required: true description: The Cleanlab Codex project identifier. schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ValidateRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ValidateResponse' '401': description: Invalid or missing access key. '404': description: Project not found. '422': description: Invalid request parameters. /api/v1/deployment/{model_id}/predict: post: operationId: predict tags: - Studio summary: Predict with a deployed Cleanlab Studio model description: >- Runs real-time inference against a model trained and deployed in Cleanlab Studio. Submit one or more text/tabular records and receive predicted labels and (optionally) predicted class probabilities. Authenticate with the Cleanlab Studio API key as a Bearer token. parameters: - name: model_id in: path required: true description: The deployed Cleanlab Studio model identifier. schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PredictRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/PredictResponse' '401': description: Invalid or missing API key. '404': description: Model not found. '422': description: Invalid request parameters. components: securitySchemes: bearerAuth: type: http scheme: bearer description: >- Cleanlab API key (TLM / Studio) or Codex project access key, supplied as a Bearer token in the Authorization header. schemas: ChatCompletionRequest: type: object required: - model - messages properties: model: type: string description: >- Base LLM to wrap, e.g. gpt-4.1-mini, gpt-5.1, gpt-4.1, o3, claude-opus-4-0, claude-sonnet-4-0, nova-pro, and most LLMs that support the Chat Completions API. example: gpt-4.1-mini messages: type: array description: Conversation messages in OpenAI Chat Completions format. items: $ref: '#/components/schemas/ChatMessage' temperature: type: number format: float nullable: true max_tokens: type: integer nullable: true stream: type: boolean default: false description: When true, the response is delivered as Server-Sent Events. extra_body: type: object description: >- Cleanlab-specific options, e.g. quality_preset and log. Use "log": ["explanation"] to also return a natural-language explanation of the trustworthiness score. additionalProperties: true ChatMessage: type: object required: - role - content properties: role: type: string enum: - system - user - assistant - tool content: type: string ChatCompletionResponse: type: object properties: id: type: string object: type: string example: chat.completion created: type: integer model: type: string choices: type: array items: $ref: '#/components/schemas/ChatCompletionChoice' usage: $ref: '#/components/schemas/Usage' tlm_metadata: $ref: '#/components/schemas/TLMMetadata' ChatCompletionChoice: type: object properties: index: type: integer message: $ref: '#/components/schemas/ChatMessage' finish_reason: type: string TLMMetadata: type: object description: Cleanlab trustworthiness metadata attached to the completion. properties: trustworthiness_score: type: number format: float description: Trustworthiness of the response on a 0-1 scale. example: 0.9873 log: type: object description: Optional extra metadata such as a trust-score explanation. additionalProperties: true Usage: type: object properties: prompt_tokens: type: integer completion_tokens: type: integer total_tokens: type: integer ValidateRequest: type: object required: - response properties: query: type: string description: The core user question. context: type: string description: Retrieved context supplied to the LLM (for RAG). response: type: string description: The AI-generated response being validated. messages: type: array description: Full prompt / conversation history in Chat Completions format. items: $ref: '#/components/schemas/ChatMessage' rewritten_query: type: string nullable: true eval_scores: type: object description: Pre-computed eval scores to pass through instead of recomputing. additionalProperties: type: number metadata: type: object additionalProperties: true ValidateResponse: type: object properties: should_guardrail: type: boolean description: Whether the response should be suppressed or replaced. escalated_to_sme: type: boolean description: Whether the query was escalated to a subject-matter expert. eval_scores: type: object description: Numeric scores across configured evaluation criteria. additionalProperties: type: object additionalProperties: true expert_answer: type: string nullable: true description: A verified expert answer to remediate the response, if available. log_id: type: string description: Identifier of the logged query record. PredictRequest: type: object required: - data properties: data: type: array description: Records to score (text strings or row objects). items: type: object additionalProperties: true return_pred_proba: type: boolean default: false description: Whether to also return predicted class probabilities. PredictResponse: type: object properties: predictions: type: array description: Predicted label for each input record. items: type: string pred_proba: type: array description: Per-class probabilities for each record (when requested). items: type: array items: type: number format: float security: - bearerAuth: []