openapi: "3.1.0"
info:
  title: Guardrails API
  version: "0.0.0"
  description: Guardrails CRUD API
paths:
  /health-check:
    get:
      tags:
        - Service Health
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      responses:
        "200":
          description: Returns the status of the server
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthCheck"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HttpError"
  /guards:
    get:
      operationId: getGuards
      tags:
        - guard
      summary: Fetches the configuration for all Guards the user has access to.
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      responses:
        "200":
          description: A list of Guards.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Guard"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HttpError"
    post:
      operationId: createGuard
      tags:
        - guard
      summary: Creates a Guard
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Guard"
      responses:
        "200":
          description: the new Guard
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Guard"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HttpError"
  /guards/{guardName}:
    get:
      operationId: getGuard
      tags:
        - guard
      summary: Fetches a specific Guard
      parameters:
        - $ref: "#/components/parameters/GuardName"
        - $ref: "#/components/parameters/AsOf"
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      responses:
        "200":
          description: the fetched Guard
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Guard"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HttpError"
    put:
      operationId: updateGuard
      tags:
        - guard
      summary: Updates a Guard
      parameters:
        - $ref: "#/components/parameters/GuardName"
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Guard"
      responses:
        "200":
          description: the updated Guard
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Guard"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HttpError"
    delete:
      operationId: deleteGuard
      tags:
        - guard
      summary: Deletes a Guard
      parameters:
        - $ref: "#/components/parameters/GuardName"
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      responses:
        "200":
          description: the deleted Guard
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Guard"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HttpError"
  /guards/{guardName}/openai/v1/chat/completions:
    post:
      operationId: openaiChatCompletion
      tags:
        - openai
      summary: OpenAI SDK compatible endpoint for Chat Completions
      parameters:
        - $ref: "#/components/parameters/GuardName"
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OpenAIChatCompletionPayload"
      responses:
        "200":
          description: The output of the completion
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OpenAIChatCompletion"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HttpError"
  /guards/{guardName}/validate:
    post:
      operationId: validate
      tags:
        - validate
      summary: Runs the validations specified in a Guard
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/GuardName"
        - $ref: "#/components/parameters/OpenAiApiKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ValidatePayload"
      responses:
        "200":
          description: The output of the validation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationOutcome"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HttpError"
  /guards/{guardName}/history/{callId}:
    get:
      operationId: getGuardHistory
      tags:
        - guard
      summary: Fetches the history for a specific Guard execution by using the id for the most recent Call
      parameters:
        - $ref: "#/components/parameters/GuardName"
        - $ref: "#/components/parameters/CallId"
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      responses:
        "200":
          description: the fetched Guard History
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/call"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HttpError"
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:
      type: apiKey
      in: header
      name: authorization
  parameters:
    GuardName:
      name: guardName
      in: path
      description: Guard name
      required: true
      schema:
        type: string
    CallId:
      name: callId
      in: path
      description: Call id
      required: true
      schema:
        type: string
    AsOf:
      name: asOf
      in: query
      description: Used to query for data as it existed at this date and time
      required: false
      schema:
        type: string
        format: date-time
    OpenAiApiKey:
      name: x-openai-api-key
      in: header
      description: A valid OpenAI API Key for calling LLM's on your behalf
      required: false
      schema:
        type: string
        format: password
  schemas:
    OpenAIChatCompletionPayload:
      type: object
      properties:
        model:
          type: string
          description: The model to use for the completion
          example: gpt-3.5-turbo
        messages:
          type: array
          items:
            type: object
            properties:
              role:
                type: string
                description: The role of the message
              content:
                type: string
                description: The content of the message
          description: The messages to use for the completion
        max_tokens:
          type: integer
          description: The maximum number of tokens to generate
        temperature:
          type: number
          description: The sampling temperature
    OpenAIChatCompletion:
      type: object
      properties:
        id:
          type: string
          description: The id
        created:
          type: string
          description: The created date
        model_name:
          type: string
          description: The model name
        choices:
          type: array
          items:
            type: object
            properties:
              role:
                type: string
                description: The role of the message
              content:
                type: string
                description: The content of the message
      required:
        - id
        - created
        - model_name
        - choices
    HttpError:
      type: object
      properties:
        status:
          type: integer
          description: A valid http status code
        message:
          type: string
          description: A message explaining the status
        cause:
          type: string
          description: Used to describe the origin of an error if that original error has meaning to the client.  This field should add specificity to 'message'.
        fields:
          type: object
          description: Used to identify specific fields in a JSON body that caused the error.  Typically only used for 4xx type responses.  The key should be the json path to the invalid property and the value should be a list of error messages specific to that property.
          additionalProperties:
            type: array
            items:
              type: string
        context:
          type: string
          description: Used to identify what part of the request caused the error for non-JSON payloads.
      required:
        - status
        - message
    HealthCheck:
      type: object
      properties:
        status:
          type: integer
          description: A valid http status code
        message:
          type: string
          description: A message explaining the status
      required:
        - status
        - message
    ValidationOutcome:
      $ref: "https://raw.githubusercontent.com/guardrails-ai/interfaces/main/schemas/core/validation-outcome.json"
    Guard:
      $ref: "https://raw.githubusercontent.com/guardrails-ai/interfaces/main/schemas/core/guard.json"
    ValidatePayload:
      type: object
      properties:
        llmOutput:
          type: string
          description: The LLM output as a string or the input prompts for the LLM
          example: stubbed llm output
        numReasks:
          type: integer
          description: An override for the number of re-asks to perform
        promptParams:
          type: object
          description: additional params for llm prompts
          properties: {}
          additionalProperties: {}
        llmApi:
          $ref: "#/$defs/LLMResource"
      additionalProperties: {}
      $defs:
        LLMResource:
          type: string
          enum:
            [
              "openai.Completion.create",
              "openai.completions.create",
              "openai.ChatCompletion.create",
              "openai.chat.completions.create",
              "openai.Completion.acreate",
              "openai.ChatCompletion.acreate",
              "litellm.completion",
              "litellm.acompletion"
            ]