Guardrails API Client

Common errors

• ModuleNotFoundError: No module named 'guardrails_api_client'

  cause The `guardrails-api-client` library is not installed in your current Python environment.
  fix Run `pip install guardrails-api-client`.

• guardrails_api_client.errors.V1CreateRunError: (401 Client Error: Unauthorized for url: https://api.guardrails.ai/v1/run)

  cause The provided `api_key` is either missing or invalid, leading to an authentication failure with the Guardrails API.
  fix Verify that your `GUARDRAILS_API_KEY` environment variable is set correctly and contains a valid API key. If running locally, restart your terminal/IDE after setting the variable.

• AttributeError: 'V1Endpoints' object has no attribute 'create_run'

  cause The method name `create_run` or its access path (`v1`) has changed, or you are calling an endpoint that does not exist in your client's version.
  fix Check the official Guardrails API Client documentation or GitHub repository for the correct method names and API structure for your installed version (0.4.0).

Warnings

• breaking As a 0.x.x library, the API surface (e.g., client methods, parameters, response types, error handling) is subject to breaking changes in minor versions (e.g., 0.3.x to 0.4.x).
  Fix: Always consult the official documentation and release notes when upgrading between minor versions. Pin your dependency to `guardrails-api-client~=0.4` to avoid unexpected upgrades.
• gotcha Authentication failures (e.g., HTTP 401 Unauthorized) commonly occur if the `GUARDRAILS_API_KEY` is missing, invalid, or expired.
  Fix: Ensure the `GUARDRAILS_API_KEY` environment variable is correctly set and contains a valid API key. Verify the key's validity in your Guardrails account settings.
• gotcha Specific API endpoint methods and their parameters (e.g., `client.v1.create_run`) can change or be renamed across versions, especially in pre-1.0 releases.
  Fix: Refer to the latest official documentation or the `guardrails-api-client` GitHub repository for the correct and most up-to-date API endpoint usage for your installed version.

Install

• pip install guardrails-api-client Install stable version

Imports

• Client

  from guardrails_api_client import Client

• errors

  from guardrails_api_client import errors

  Useful for catching specific API error types.

Quickstart

Initializes the Guardrails API client, authenticates using an environment variable, and demonstrates a basic call to the `create_run` endpoint. This example checks an LLM output against a specified guard.

import guardrails_api_client
import os

# Ensure GUARDRAILS_API_KEY is set in your environment
# Example: export GUARDRAILS_API_KEY="your_api_key_here"
api_key = os.environ.get("GUARDRAILS_API_KEY", "")

if not api_key:
    print("Error: GUARDRAILS_API_KEY environment variable is not set.")
    print("Please set it before running the quickstart.")
else:
    client = guardrails_api_client.Client(
        base_url="https://api.guardrails.ai", # Or your custom base URL
        api_key=api_key,
    )

    try:
        # Replace 'your-guard-id' with an actual guard ID from your Guardrails account
        response = client.v1.create_run(
            llm_output="Hello, I am an AI model.",
            guard_id="your-guard-id",
            # ... other parameters like metadata, stream etc.
        ).result

        print(f"Is valid: {response.is_valid}")
        if not response.is_valid:
            print(f"Reasons: {response.reasons}")
            print(f"Fixed output: {response.fixed_output}")

    except guardrails_api_client.errors.V1CreateRunError as e:
        print(f"API Error: {e.response.json() if e.response else e}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")