# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0

openapi: 3.0.3
info:
  title: NVIDIA NeMo Guardrails Library API Server
  version: 0.22.0
  description: |
    REST API for the NVIDIA NeMo Guardrails library server.

    The server exposes an OpenAI-compatible chat completions endpoint with
    Guardrails-specific request and response extensions.
servers:
  - url: http://localhost:8000
    description: Local Guardrails server
tags:
  - name: Chat Completions
    description: Generate guarded chat completions.
  - name: Models
    description: List upstream models exposed through the configured provider.
  - name: Configurations
    description: Discover available guardrails configurations.
  - name: Challenges
    description: List registered red teaming challenges.
  - name: Health
    description: Check server health or load the chat UI.
paths:
  /v1/chat/completions:
    post:
      operationId: createGuardrailsChatCompletion
      tags:
        - Chat Completions
      summary: Create a guarded chat completion
      description: |
        Generate a chat completion with guardrails applied.

        The request shape is compatible with the OpenAI Chat Completions API and
        accepts Guardrails-specific options in the `guardrails` object.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GuardrailsChatCompletionRequest"
            examples:
              basic:
                summary: Basic guarded completion
                value:
                  model: meta/llama-3.1-8b-instruct
                  messages:
                    - role: user
                      content: What is the capital of France?
                  guardrails:
                    config_id: content_safety
              streaming:
                summary: Streaming guarded completion
                value:
                  model: meta/llama-3.1-8b-instruct
                  messages:
                    - role: user
                      content: Tell me a short story.
                  stream: true
                  guardrails:
                    config_id: content_safety
      responses:
        "200":
          description: Chat completion response or server-sent event stream.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GuardrailsChatCompletion"
              examples:
                success:
                  summary: Basic guarded completion
                  value:
                    id: chatcmpl-abc123
                    object: chat.completion
                    created: 1709424000
                    model: meta/llama-3.1-8b-instruct
                    choices:
                      - index: 0
                        message:
                          role: assistant
                          content: Paris is the capital of France.
                        finish_reason: stop
                    guardrails:
                      config_id: content_safety
                      llm_output: null
                      output_data: null
                      log: null
                      state: null
            text/event-stream:
              schema:
                type: string
                description: |
                  Server-sent events containing chat completion chunks. A
                  downstream failure before the first chunk is returned as an
                  HTTP error so clients can retry it. If generation fails after
                  streaming begins, the final JSON event is an error envelope
                  whose `type` is an internal streaming marker and whose `code`
                  carries the downstream HTTP status or generation error code.
              examples:
                completion:
                  value: |
                    data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1700000000,"model":"meta/llama-3.1-8b-instruct","choices":[{"delta":{"content":"Paris"},"index":0,"finish_reason":null}]}

                    data: [DONE]
                error:
                  value: |
                    data: {"error":{"message":"The upstream model is unavailable.","type":"downstream_error","param":null,"code":503}}

                    data: [DONE]
        "422":
          description: Invalid request or unsupported state continuation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                missingConfig:
                  value:
                    error:
                      message: No guardrails config_id provided and server has no default configuration
                      type: invalid_request_error
                      param: null
                      code: null
                unsupportedColangState:
                  value:
                    error:
                      message: Stateful continuation over HTTP is not supported for Colang 2.0.
                      type: invalid_request_error
                      param: null
                      code: null
  /v1/models:
    get:
      operationId: listModels
      tags:
        - Models
      summary: List models
      description: |
        List available LLM models from the configured upstream provider.

        The server forwards the `Authorization` header to the upstream provider
        when the request includes one.
      responses:
        "200":
          description: OpenAI-compatible models list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OpenAIModelsList"
              examples:
                success:
                  value:
                    data:
                      - id: meta/llama-3.1-8b-instruct
                        object: model
                        created: 1700000000
                        owned_by: system
        "502":
          description: The upstream provider is unreachable or returned an error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/rails/configs:
    get:
      operationId: listRailsConfigs
      tags:
        - Configurations
      summary: List guardrails configurations
      description: |
        List available guardrails configurations. In single-config mode, the
        response contains the single configured ID.
      responses:
        "200":
          description: Array of available configuration IDs.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/RailsConfigInfo"
              examples:
                success:
                  value:
                    - id: content_safety
                    - id: customer-service
  /v1/challenges:
    get:
      operationId: listChallenges
      tags:
        - Challenges
      summary: List red teaming challenges
      description: |
        List registered red teaming challenges. The response structure depends
        on the challenges registered by the application.
      responses:
        "200":
          description: Array of registered challenges.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
              examples:
                success:
                  value:
                    - id: jailbreak-1
                      description: Attempt to bypass safety guardrails.
                      category: jailbreak
  /v1/health:
    get:
      operationId: getHealth
      tags:
        - Health
      summary: Liveness health check
      description: |
        Shallow liveness check. Returns HTTP 200 while the server process is
        running and able to serve requests. It does not verify guardrails
        configurations, the model provider, or any datastore.
      responses:
        "200":
          description: The server process is up and able to serve requests.
          content:
            application/health+json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: pass
              example:
                status: pass
  /healthz:
    get:
      operationId: getHealthz
      tags:
        - Health
      summary: Liveness health check (alias)
      description: |
        Kubernetes-style alias for `GET /v1/health`. Returns the same shallow
        liveness response.
      responses:
        "200":
          description: The server process is up and able to serve requests.
          content:
            application/health+json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: pass
              example:
                status: pass
  /:
    get:
      operationId: getRoot
      tags:
        - Health
      summary: Get server health or chat UI
      description: |
        Returns a health payload when the chat UI is disabled. Otherwise, serves
        the interactive chat interface.
      responses:
        "200":
          description: Health payload or chat UI HTML.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
              example:
                status: ok
            text/html:
              schema:
                type: string
components:
  schemas:
    ChatMessage:
      type: object
      additionalProperties: true
      required:
        - role
        - content
      properties:
        role:
          type: string
          description: Message role, such as `system`, `user`, `assistant`, `tool`, or `context`.
          example: user
        content:
          description: Message content.
          oneOf:
            - type: string
            - type: array
              items:
                type: object
                additionalProperties: true
    GuardrailsChatCompletionRequest:
      type: object
      required:
        - model
      properties:
        model:
          type: string
          description: LLM model to use for the completion.
          example: meta/llama-3.1-8b-instruct
        messages:
          type: array
          description: Chat messages in the current conversation.
          items:
            $ref: "#/components/schemas/ChatMessage"
        stream:
          type: boolean
          default: false
          description: Return partial message deltas as server-sent events.
        max_tokens:
          type: integer
          description: Maximum number of tokens to generate.
        temperature:
          type: number
          format: float
          description: Sampling temperature.
        top_p:
          type: number
          format: float
          description: Top-p sampling parameter.
        stop:
          description: Stop sequence or sequences.
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        presence_penalty:
          type: number
          format: float
          description: Presence penalty parameter.
        frequency_penalty:
          type: number
          format: float
          description: Frequency penalty parameter.
        function_call:
          type: object
          additionalProperties: true
          description: Function call parameter.
        logit_bias:
          type: object
          additionalProperties: true
          description: Logit bias parameter.
        logprobs:
          type: boolean
          description: Log probabilities parameter.
        guardrails:
          $ref: "#/components/schemas/GuardrailsRequestOptions"
    GuardrailsRequestOptions:
      type: object
      description: Guardrails-specific request options.
      properties:
        config_id:
          type: string
          description: Guardrails configuration ID to use. Mutually exclusive with `config_ids`.
        config_ids:
          type: array
          description: List of configuration IDs to combine. Mutually exclusive with `config_id`.
          items:
            type: string
        thread_id:
          type: string
          minLength: 16
          maxLength: 255
          description: Existing thread ID for Colang 1.0 conversation persistence.
        context:
          type: object
          additionalProperties: true
          description: Additional context data for the conversation.
        options:
          $ref: "#/components/schemas/GenerationOptions"
        state:
          type: object
          additionalProperties: true
          description: Colang 1.0 transcript state for continuing a previous interaction.
    GenerationOptions:
      type: object
      properties:
        rails:
          $ref: "#/components/schemas/GenerationRailsOptions"
        llm_params:
          type: object
          additionalProperties: true
          description: Additional parameters to pass to the LLM call.
        llm_output:
          type: boolean
          default: false
          description: Include custom LLM output in the response.
        output_vars:
          description: Context variables to return.
          oneOf:
            - type: boolean
            - type: array
              items:
                type: string
        log:
          $ref: "#/components/schemas/GenerationLogOptions"
    GenerationRailsOptions:
      type: object
      properties:
        input:
          $ref: "#/components/schemas/RailSelection"
        output:
          $ref: "#/components/schemas/RailSelection"
        retrieval:
          $ref: "#/components/schemas/RailSelection"
        dialog:
          type: boolean
          default: true
          description: Enable dialog rails.
        tool_input:
          $ref: "#/components/schemas/RailSelection"
        tool_output:
          $ref: "#/components/schemas/RailSelection"
    RailSelection:
      description: Enable, disable, or select named rails.
      oneOf:
        - type: boolean
        - type: array
          items:
            type: string
    GenerationLogOptions:
      type: object
      properties:
        activated_rails:
          type: boolean
          default: false
          description: Include information about activated rails.
        llm_calls:
          type: boolean
          default: false
          description: Include details about LLM calls.
        internal_events:
          type: boolean
          default: false
          description: Include internal generated events.
        colang_history:
          type: boolean
          default: false
          description: Include conversation history in Colang format.
    GuardrailsChatCompletion:
      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"
        guardrails:
          $ref: "#/components/schemas/GuardrailsResponseData"
    ChatCompletionChoice:
      type: object
      properties:
        index:
          type: integer
        message:
          $ref: "#/components/schemas/ChatMessage"
        finish_reason:
          type: string
          nullable: true
    GuardrailsResponseData:
      type: object
      properties:
        config_id:
          type: string
          nullable: true
        state:
          type: object
          nullable: true
          additionalProperties: true
        llm_output:
          type: object
          nullable: true
          additionalProperties: true
        output_data:
          type: object
          nullable: true
          additionalProperties: true
        log:
          type: object
          nullable: true
          additionalProperties: true
    OpenAIModelsList:
      type: object
      required:
        - data
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/OpenAIModel"
    OpenAIModel:
      type: object
      required:
        - id
        - object
        - created
      properties:
        id:
          type: string
          description: Model identifier.
        object:
          type: string
          enum:
            - model
        created:
          type: integer
          description: Unix timestamp in seconds.
        owned_by:
          type: string
          nullable: true
          description: Organization that owns the model.
    RailsConfigInfo:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: Guardrails configuration ID.
    ErrorResponse:
      type: object
      description: |
        OpenAI-compatible error envelope. Every error response from the server
        uses this shape, so an OpenAI SDK raises the matching APIStatusError
        subclass.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
            - type
            - param
            - code
          properties:
            message:
              type: string
              description: Human-readable error message, with secrets and upstream URLs redacted.
            type:
              type: string
              description: |
                OpenAI error category, derived from the HTTP status
                (for example `invalid_request_error`, `authentication_error`,
                `permission_error`, `not_found_error`, `rate_limit_error`,
                `server_error`).
            param:
              type: string
              nullable: true
              description: The request field the error relates to, when known.
            code:
              nullable: true
              description: |
                Provider-supplied error code when available. Streaming error
                events use an integer downstream HTTP status or a string
                generation error code.
              oneOf:
                - type: string
                - type: integer