Portkey Guardrails API

openapi: 3.0.0
info:
  title: Portkey Analytics > Graphs Guardrails API
  description: The Portkey REST API. Please see https://portkey.ai/docs/api-reference for more details.
  version: 2.0.0
  termsOfService: https://portkey.ai/terms
  contact:
    name: Portkey Developer Forum
    url: https://portkey.wiki/community
  license:
    name: MIT
    url: https://github.com/Portkey-AI/portkey-openapi/blob/master/LICENSE
servers:
- url: https://api.portkey.ai/v1
  description: Portkey API Public Endpoint
security:
- Portkey-Key: []
tags:
- name: Guardrails
  description: Create, List, Retrieve, Update, and Delete prompt Guardrails.
paths:
  /guardrails:
    post:
      summary: Create a new guardrail
      description: Creates a new guardrail with specified checks and actions
      operationId: createGuardrail
      tags:
      - Guardrails
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGuardrailRequest'
            examples:
              jwt_authentication:
                summary: '[BASIC] JWT Token Validation'
                value:
                  name: JWT Authentication Guard
                  organisation_id: 550e8400-e29b-41d4-a716-446655440001
                  checks:
                  - id: default.jwt
                    parameters:
                      jwksUri: https://example.com/.well-known/jwks.json
                      headerKey: Authorization
                      algorithms:
                      - RS256
                      cacheMaxAge: 86400
                      clockTolerance: 5
                      maxTokenAge: 1d
                  actions:
                    onFail: block
                    message: Invalid JWT token
              model_whitelist:
                summary: '[BASIC] Model Whitelist Control'
                value:
                  name: Allowed Models Only
                  workspace_id: 550e8400-e29b-41d4-a716-446655440000
                  checks:
                  - id: default.modelWhitelist
                    parameters:
                      models:
                      - gpt-4
                      - gpt-3.5-turbo
                      - claude-3-sonnet
                      - claude-3-haiku
                  actions:
                    onFail: block
                    message: Model not in approved whitelist
              allowed_request_types:
                summary: '[BASIC] Restrict to Chat and Embed Only'
                value:
                  name: Restrict to Chat and Embed Only
                  checks:
                  - id: default.allowedRequestTypes
                    parameters:
                      allowedTypes:
                      - chatComplete
                      - embed
                  actions:
                    on_fail: deny
                    on_success: continue
              case_validation:
                summary: '[BASIC] Case Validation Checks'
                value:
                  name: Text Case Validation
                  workspace_id: 550e8400-e29b-41d4-a716-446655440000
                  checks:
                  - id: default.isAllLowerCase
                  - id: default.alluppercase
                    parameters:
                      not: true
                  actions:
                    onFail: log
                    message: Text case validation failed
              content_regex:
                summary: '[BASIC] Regex Pattern Matching'
                value:
                  name: Content Pattern Validation
                  workspace_id: 550e8400-e29b-41d4-a716-446655440000
                  checks:
                  - id: default.regexMatch
                    parameters:
                      rule: \b(inappropriate|banned|harmful|offensive)\b
                      not: false
                  - id: default.endsWith
                    parameters:
                      suffix: .
                      not: false
                  actions:
                    onFail: block
                    message: Content violates pattern rules
              length_controls:
                summary: '[BASIC] Content Length Controls'
                value:
                  name: Content Length Validation
                  workspace_id: 550e8400-e29b-41d4-a716-446655440000
                  checks:
                  - id: default.wordCount
                    parameters:
                      minWords: 5
                      maxWords: 500
                      not: false
                  - id: default.sentenceCount
                    parameters:
                      minSentences: 1
                      maxSentences: 20
                      not: false
                  - id: default.characterCount
                    parameters:
                      minCharacters: 10
                      maxCharacters: 4000
                      not: false
                  actions:
                    onFail: block
                    message: Content length out of bounds
              json_validation:
                summary: '[BASIC] JSON Structure Validation'
                value:
                  name: JSON Response Validation
                  workspace_id: 550e8400-e29b-41d4-a716-446655440000
                  checks:
                  - id: default.jsonSchema
                    parameters:
                      schema:
                        type: object
                        properties:
                          result:
                            type: string
                          confidence:
                            type: number
                            minimum: 0
                            maximum: 1
                          metadata:
                            type: object
                        required:
                        - result
                      not: false
                  - id: default.jsonKeys
                    parameters:
                      keys:
                      - result
                      - timestamp
                      - id
                      operator: all
                  actions:
                    onFail: block
                    message: Response does not match expected format
              content_analysis:
                summary: '[BASIC] Content Analysis Checks'
                value:
                  name: Content Quality Checks
                  workspace_id: 550e8400-e29b-41d4-a716-446655440000
                  checks:
                  - id: default.contains
                    parameters:
                      words:
                      - please
                      - thank you
                      - help
                      operator: any
                  - id: default.validUrls
                    parameters:
                      onlyDNS: true
                      not: false
                  - id: default.containsCode
                    parameters:
                      format: SQL
                      not: true
                  actions:
                    onFail: warn
                    message: Content quality check failed
              webhook_integration:
                summary: '[BASIC] Custom Webhook Validation'
                value:
                  name: External Validation Service
                  workspace_id: 550e8400-e29b-41d4-a716-446655440000
                  checks:
                  - id: default.webhook
                    parameters:
                      webhookURL: https://api.example.com/validate-content
                      headers:
                        Authorization: Bearer token123
                        Content-Type: application/json
                        X-API-Version: v1
                      timeout: 5000
                      failOnError: true
                  actions:
                    onFail: block
                    message: External validation failed
              metadata_validation:
                summary: '[BASIC] Required Metadata Keys'
                value:
                  name: Metadata Requirement Check
                  workspace_id: 550e8400-e29b-41d4-a716-446655440000
                  checks:
                  - id: default.requiredMetadataKeys
                    parameters:
                      metadataKeys:
                      - user_id
                      - session_id
                      - request_type
                      operator: all
                  actions:
                    onFail: block
                    message: Required metadata missing
              portkey_moderation:
                summary: '[PRO] OpenAI Content Moderation'
                value:
                  name: Advanced Content Moderation
                  workspace_id: 550e8400-e29b-41d4-a716-446655440000
                  checks:
                  - id: portkey.moderateContent
                    parameters:
                      categories:
                      - hate/threatening
                      - harassment/threatening
                      - self-harm/intent
                      - sexual/minors
                      - violence/graphic
                      timeout: 5000
                  actions:
                    onFail: block
                    message: Content flagged by moderation system
              portkey_language:
                summary: '[PRO] Language Detection & Validation'
                value:
                  name: Multi-Language Support
                  workspace_id: 550e8400-e29b-41d4-a716-446655440000
                  checks:
                  - id: portkey.language
                    parameters:
                      language: eng_Latn
                      not: false
                      timeout: 5000
                  actions:
                    onFail: block
                    message: Content not in expected language
              portkey_pii:
                summary: '[PRO] Advanced PII Detection'
                value:
                  name: PII Protection System
                  workspace_id: 550e8400-e29b-41d4-a716-446655440000
                  checks:
                  - id: portkey.pii
                    parameters:
                      redact: true
                      categories:
                      - EMAIL_ADDRESS
                      - PHONE_NUMBER
                      - SSN
                      - CREDIT_CARD
                      - NAME
                      timeout: 5000
                  actions:
                    onFail: block
                    message: PII detected and redacted
              portkey_gibberish:
                summary: '[PRO] Gibberish Detection'
                value:
                  name: Content Quality Filter
                  workspace_id: 550e8400-e29b-41d4-a716-446655440000
                  checks:
                  - id: portkey.gibberish
                    parameters:
                      timeout: 5000
                  actions:
                    onFail: block
                    message: Content appears to be gibberish
              sydelabs_security:
                summary: '[PARTNER] SydeLabs AI Security'
                value:
                  name: AI Security Suite
                  workspace_id: 550e8400-e29b-41d4-a716-446655440000
                  checks:
                  - id: sydelabs.sydeguard
                    parameters:
                      prompt_injection_threshold: 0.5
                      toxicity_threshold: 0.3
                      evasion_threshold: 0.6
                      timeout: 5000
                  actions:
                    onFail: block
                    message: AI security check failed
              aporia_validation:
                summary: '[PARTNER] Aporia Project Validation'
                value:
                  name: Aporia Policy Enforcement
                  workspace_id: 550e8400-e29b-41d4-a716-446655440000
                  checks:
                  - id: aporia.validateProject
                    parameters:
                      projectID: proj_abc123
                      timeout: 5000
                  actions:
                    onFail: block
                    message: Aporia validation failed
              pillar_scanning:
                summary: '[PARTNER] Pillar Security Scanning'
                value:
                  name: Comprehensive Security Scan
                  workspace_id: 550e8400-e29b-41d4-a716-446655440000
                  checks:
                  - id: pillar.scanPrompt
                    parameters:
                      scanners:
                      - prompt_injection
                      - pii
                      - secrets
                      - toxic_language
                      - invisible_characters
                      timeout: 5000
                  - id: pillar.scanResponse
                    parameters:
                      scanners:
                      - pii
                      - secrets
                      - toxic_language
                      timeout: 5000
                  actions:
                    onFail: block
                    message: Security scan detected issues
              patronus_comprehensive:
                summary: '[PARTNER] Patronus AI Complete Suite'
                value:
                  name: Patronus Content Analysis
                  workspace_id: 550e8400-e29b-41d4-a716-446655440000
                  checks:
                  - id: patronus.pii
                    parameters:
                      redact: true
                      timeout: 5000
                  - id: patronus.toxicity
                    parameters:
                      timeout: 5000
                  - id: patronus.noGenderBias
                    parameters:
                      timeout: 15000
                  - id: patronus.isHelpful
                    parameters:
                      timeout: 15000
                  - id: patronus.custom
                    parameters:
                      profile: system:is-concise
                      timeout: 15000
                  actions:
                    onFail: block
                    message: Content failed Patronus analysis
              azure_content_safety:
                summary: '[PARTNER] Azure Content Safety Suite'
                value:
                  name: Microsoft Azure Safety
                  workspace_id: 550e8400-e29b-41d4-a716-446655440000
                  checks:
                  - id: azure.contentSafety
                    parameters:
                      blocklistNames:
                      - company_blocklist
                      apiVersion: '2024-09-01'
                      severity: 2
                      categories:
                      - Hate
                      - SelfHarm
                      - Sexual
                      - Violence
                      timeout: 5000
                  - id: azure.pii
                    parameters:
                      domain: phi
                      apiVersion: '2024-11-01'
                      modelVersion: latest
                      redact: true
                      timeout: 5000
                  actions:
                    onFail: block
                    message: Azure safety checks failed
              mistral_moderation:
                summary: '[PARTNER] Mistral Content Moderation'
                value:
                  name: Mistral AI Moderation
                  workspace_id: 550e8400-e29b-41d4-a716-446655440000
                  checks:
                  - id: mistral.moderateContent
                    parameters:
                      categories:
                      - sexual
                      - hate_and_discrimination
                      - violence_and_threats
                      - selfharm
                      - pii
                      timeout: 5000
                  actions:
                    onFail: block
                    message: Mistral moderation flagged content
              bedrock_enterprise:
                summary: '[PARTNER] AWS Bedrock Guardrails'
                value:
                  name: Enterprise AWS Security
                  workspace_id: 550e8400-e29b-41d4-a716-446655440000
                  checks:
                  - id: bedrock.guard
                    parameters:
                      guardrailVersion: DRAFT
                      guardrailId: gdrail123abc
                      redact: true
                      timeout: 5000
                  actions:
                    onFail: block
                    message: AWS Bedrock guardrail violation
              promptfoo_testing:
                summary: '[PARTNER] Promptfoo Security Testing'
                value:
                  name: Security Testing Suite
                  workspace_id: 550e8400-e29b-41d4-a716-446655440000
                  checks:
                  - id: promptfoo.guard
                    parameters:
                      timeout: 5000
                  - id: promptfoo.pii
                    parameters:
                      redact: true
                      timeout: 5000
                  - id: promptfoo.harm
                    parameters:
                      timeout: 5000
                  actions:
                    onFail: block
                    message: Promptfoo security tests failed
              acuvity_comprehensive:
                summary: '[PARTNER] Acuvity Multi-Vector Security'
                value:
                  name: Complete Security Analysis
                  workspace_id: 550e8400-e29b-41d4-a716-446655440000
                  checks:
                  - id: acuvity.scan
                    parameters:
                      prompt_injection: true
                      prompt_injection_threshold: 0.5
                      toxic: true
                      toxic_threshold: 0.3
                      jail_break: true
                      jail_break_threshold: 0.6
                      malicious_url: true
                      biased: true
                      harmful: true
                      language: true
                      language_values: english
                      pii: true
                      pii_redact: true
                      pii_categories:
                      - email_address
                      - ssn
                      - credit_card
                      secrets: true
                      secrets_redact: true
                      secrets_categories:
                      - aws_secret_key
                      - openai
                      - github
                      timeout: 5000
                  actions:
                    onFail: block
                    message: Comprehensive security scan failed
              lasso_classification:
                summary: '[PARTNER] Lasso Security Classification'
                value:
                  name: Content Classification
                  workspace_id: 550e8400-e29b-41d4-a716-446655440000
                  checks:
                  - id: lasso.classify
                    parameters:
                      timeout: 5000
                  actions:
                    onFail: block
                    message: Lasso classification failed
              panw_prisma:
                summary: '[PARTNER] PANW Prisma AIRS Enterprise'
                value:
                  name: Enterprise Security Runtime
                  workspace_id: 550e8400-e29b-41d4-a716-446655440000
                  checks:
                  - id: panw-prisma-airs.intercept
                    parameters:
                      profile_name: enterprise_profile
                      ai_model: gpt-4
                      app_user: api_user_123
                  actions:
                    onFail: block
                    message: Prisma AIRS blocked request
      responses:
        '200':
          description: Guardrail created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateGuardrailResponse'
        '400':
          description: Bad request - validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - insufficient permissions or guardrail not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      summary: List guardrails
      description: Retrieves a paginated list of guardrails for the specified workspace or organisation
      operationId: listGuardrails
      tags:
      - Guardrails
      parameters:
      - name: workspace_id
        in: query
        description: Workspace UUID to filter guardrails
        schema:
          type: string
          format: uuid
      - name: organisation_id
        in: query
        description: Organisation UUID to filter guardrails
        schema:
          type: string
          format: uuid
      - name: page_size
        in: query
        description: Number of items per page
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 100
      - name: current_page
        in: query
        description: Current page number (0-indexed)
        schema:
          type: integer
          minimum: 0
          default: 0
      responses:
        '200':
          description: List of guardrails retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListGuardrailsResponse'
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /guardrails/{guardrailId}:
    get:
      summary: Get a specific guardrail
      description: Retrieves details of a specific guardrail by ID or slug
      operationId: getGuardrail
      tags:
      - Guardrails
      parameters:
      - name: guardrailId
        in: path
        required: true
        description: Guardrail UUID or slug (with guard_ prefix)
        schema:
          type: string
        examples:
          uuid:
            summary: Using UUID
            value: 550e8400-e29b-41d4-a716-446655440000
          slug:
            summary: Using slug
            value: guard_abc123
      responses:
        '200':
          description: Guardrail details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GuardrailDetails'
        '403':
          description: Forbidden - guardrail not found or insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      summary: Update a guardrail
      description: Updates an existing guardrail's name, checks, or actions
      operationId: updateGuardrail
      tags:
      - Guardrails
      parameters:
      - name: guardrailId
        in: path
        required: true
        description: Guardrail UUID or slug to update
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateGuardrailRequest'
      responses:
        '200':
          description: Guardrail updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateGuardrailResponse'
        '400':
          description: Bad request - validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - guardrail not found or insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      summary: Delete a guardrail
      description: Deletes an existing guardrail
      operationId: deleteGuardrail
      tags:
      - Guardrails
      parameters:
      - name: guardrailId
        in: path
        required: true
        description: Guardrail UUID or slug to delete
        schema:
          type: string
      responses:
        '200':
          description: Guardrail deleted successfully
        '403':
          description: Forbidden - guardrail not found or insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    PatronusParameters:
      title: Patronus Parameters
      type: object
      properties:
        redact:
          type: boolean
          description: Whether to redact detected content
          default: false
        timeout:
          type: number
          description: Timeout in milliseconds
          default: 5000
    AcuvityScanParameters:
      title: Acuvity Scan Parameters
      type: object
      properties:
        prompt_injection:
          type: boolean
          description: Enable prompt injection detection
          default: true
        prompt_injection_threshold:
          type: number
          minimum: 0
          maximum: 1
          multipleOf: 0.01
          description: Threshold for prompt injection detection
          default: 0.5
        toxic:
          type: boolean
          description: Enable toxicity detection
          default: true
        toxic_threshold:
          type: number
          minimum: 0
          maximum: 1
          multipleOf: 0.01
          description: Threshold for toxicity detection
          default: 0.5
        jail_break:
          type: boolean
          description: Enable jailbreak detection
          default: true
        jail_break_threshold:
          type: number
          minimum: 0
          maximum: 1
          multipleOf: 0.01
          description: Threshold for jailbreak detection
          default: 0.5
        malicious_url:
          type: boolean
          description: Enable malicious URL detection
          default: true
        malicious_url_threshold:
          type: number
          minimum: 0
          maximum: 1
          multipleOf: 0.01
          description: Threshold for malicious URL detection
          default: 0.5
        biased:
          type: boolean
          description: Enable bias detection
          default: true
        biased_threshold:
          type: number
          minimum: 0
          maximum: 1
          multipleOf: 0.01
          description: Threshold for bias detection
          default: 0.5
        harmful:
          type: boolean
          description: Enable harmful content detection
          default: true
        harmful_threshold:
          type: number
          minimum: 0
          maximum: 1
          multipleOf: 0.01
          description: Threshold for harmful content detection
          default: 0.5
        language:
          type: boolean
          description: Enable language check
          default: true
        language_values:
          type: string
          enum:
          - english
          - chinese
          - spanish
          - french
          - german
          - japanese
          - gibberish
          description: Language to check
          default: english
        pii:
          type: boolean
          description: Enable PII detection
          default: true
        pii_redact:
          type: boolean
          description: Enable PII redaction
          default: false
        pii_categories:
          type: array
          items:
            type: string
            enum:
            - email_address
            - ssn
            - person
            - aba_routing_number
            - address
            - bank_account
            - bitcoin_wallet
            - credit_card
            - driver_license
            - itin_number
            - location
            - medical_license
            - money_amount
            - passport_number
            - phone_number
          description: PII categories to detect
        secrets:
          type: boolean
          description: Enable secrets detection
          default: true
        secrets_redact:
          type: boolean
          description: Enable secrets redaction
          default: false
        secrets_categories:
          type: array
          items:
            type: string
            enum:
            - credentials
            - aws_secret_key
            - github
            - openai
            - stripe
            - jwt
            - private_key
          description: Secret categories to detect
        timeout:
          type: number
          description: Timeout in milliseconds
          default: 5000
    WordCountParameters:
      title: Word Count Parameters
      type: object
      properties:
        minWords:
          type: number
          description: Minimum number of words to allow
          default: 0
        maxWords:
          type: number
          description: Maximum number of words to allow
          default: 99999
        not:
          type: boolean
          description: If true, the verdict will be inverted
          default: false
    GuardrailActions:
      type: object
      description: Actions to take when guardrail checks fail or pass
      properties:
        deny:
          type: boolean
          description: Whether to deny the request when guardrail check fails
          default: false
        async:
          type: boolean
          description: Whether the guardrail check should be performed asynchronously
          default: false
        on_success:
          type: object
          description: Actions to take when guardrail check passes
          properties:
            feedback:
              type: object
              description: Feedback configuration for successful checks
              properties:
                value:
                  type: number
                  description: Feedback value for successful checks
                  default: 5
                weight:
                  type: number
                  description: Weight of the feedback
                  default: 1
                metadata:
                  type: string
                  description: Additional metadata for the feedback
                  default: ''
              required:
              - value
              - weight
              - metadata
          required:
          - feedback
        on_fail:
          type: object
          description: Actions to take when guardrail check fails
          properties:
            feedback:
              type: object
              description: Feedback configuration for failed checks
              properties:
                value:
                  type: number
                  description: Feedback value for failed checks
                  default: -5
                weight:
                  type: number
                  description: Weight of the feedback
                  default: 1
                metadata:
                  type: string
                  description: Additional metadata for the feedback
                  default: ''
              required:
              - value
              - weight
              - metadata
          required:
          - feedback
      required:
      - deny
      - async
      - on_success
      - on_fail
    AllowedRequestTypesParameters:
      title: Allowed Request Types Parameters
      type: object
      description: Parameters for default.allowedRequestTypes check. Restrict which request types are allowed or blocked. You can use either or both; when both are specified, blocked types take precedence.


# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/portkey/refs/heads/main/openapi/portkey-guardrails-api-openapi.yml