openapi: 3.0.1
info:
  title: Cleanlab Codex TLM 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
security:
- bearerAuth: []
tags:
- name: TLM
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.
components:
  schemas:
    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
    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
  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.