Skip to main content

​
Create an API Key

  1. In your organization’s DeepRails API Console, go to API Keys.
  2. Click Create key, name it, then copy the key.
  3. (Optional) Save it as the DEEPRAILS_API_KEY environment variable.
API Keys – placeholder

Create and manage API keys in the API Console.

​
Install the SDK

  • Python
  • TypeScript / Node
  • Ruby
  • Go
pip install deeprails

​
Create your first Defend workflow

Before you can submit events to be evaluated and potentially remediated, you have to create and configure a workflow.

A workflow is an abstraction for a specific production use of Gen AI, and its configurations determine which guardrail metrics are evaluated, at what thresholds, and how issues are remediated.
Types of workflows
Workflows can either have custom or automatic thresholds, set by the threshold_type. Automatic workflows have adaptive thresholds that change as events are recorded, starting at low, medium, or high values in a automatic_hallucination_tolerance_values dictionary. Custom workflows have static, fully customizable thresholds for each selected metric set as floating point values in a custom_hallucination_threshold_values dictionary.

Note that workflows set to automatic must have automatic_hallucination_tolerance_values specified and custom_hallucination_threshold_values is not needed, and vice versa for those set to custom.
  • Python
  • TypeScript / Node
  • Ruby
  • Go
from deeprails import DeepRails

# Initialize (env var DEEPRAILS_API_KEY is recommended)
client = DeepRails(api_key="YOUR_API_KEY")

workflow_response = client.defend.create_workflow(
    name="Test Workflow",
    description="A workflow used to test the DeepRails API",
    threshold_type="custom",
    custom_hallucination_threshold_values={
        "completeness": 0.85,
        "instruction_adherence": 0.75,
    },
    improvement_action="fixit",
    max_improvement_attempts=5,
    web_search=True,
    file_search=["file_xxxxxxxx"]
)
print(workflow_response)
Required Parameters
FieldTypeDescription
namestringThe name of the workflow
threshold_typestringThe workflow type (either automatic or custom), which determines whether thresholds are specified by the user or set automatically.
improvement_actionstringThe action (either fixit, regen, or do_nothing) that Defend uses to remediate outputs when they fail one or more guardrail metrics.
Optional Parameters
FieldTypeDescription
descriptionstringA description of the use case of the workflow or other additional information.
custom_hallucination_ threshold_valuesobjectThe mapping of guardrail metrics to floating point threshold values. This determines which metrics Defend will evaluate and how strict each threshold is for custom workflows.
automatic_hallucination_ tolerance_levelsobjectThe mapping of guardrail metrics to strings representing the level used to calibrate thresholds (either low, medium, or high). This determines for automatic workflows which metrics Defend will evaluate and how strict each threshold is for automatic workflows.
max_improvement_attemptsintegerThe maximum number of improvement attempts to be applied to one workflow event before it is considered failed. Defaults to 10.
web_searchbooleanWhether or not the extended AI capability, web search, is available to the evaluation and remediation models.
file_searchstring[]A list of files for the evaluation and remediation models to search using the extended AI capability, file search, if non-empty.

​
Submit a Workflow Event

Use the SDK to log a production event (input + output). This creates a workflow event and automatically triggers an associated evaluation using the guardrail metrics you pass.

If the evaluation fails for one or more metrics, the improvement action specified for the affliated workflow will be used to remediate the output. Then, that improved output will be evaluated and potentially improved again, if needed.

The improvement process will repeat for that event until all guardrails pass or the maximum number of retries is reached.
Tip: You can also submit a workflow event via the DeepRails API Playground.
  • Python
  • TypeScript / Node
  • Ruby
  • Go
from deeprails import DeepRails

# Initialize (env var DEEPRAILS_API_KEY is recommended)
client = DeepRails(api_key="YOUR_API_KEY")

event_response = client.defend.submit_event(
    workflow_id="wkfl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    model_input={
            "user_prompt": "Hello, how are you?",
    },
    model_output="I am good, thank you!",
    model_used="gpt-4o-mini",
    run_mode="smart",
    nametag="test",
)
print(event_response)
Required Parameters
FieldTypeDescription
workflow_idstringThe ID of the Defend workflow associated with this event. (find it in Console → Defend → Manage Workflows)
model_inputobjectYour prompt + optional context. Must include at least system_prompt or user_prompt.
model_outputstringThe LLM output to be evaluated and recorded with the event.
model_usedstringThe model used to generate the output, like gpt-4o or o3.
run_modestringRun mode for the workflow event that determines which models are used to evaluate the event. Available run modes include precision_plus, precision, smart, and economy. Defaults to smart.
Optional Parameters
FieldTypeDescription
nametagstringA user-defined tag for the event.

​
Retrieve Workflow Data

You can retrieve workflow details and fetch events from a specific workflow.
  • Python
  • TypeScript / Node
  • Ruby
  • Go
from deeprails import DeepRails

# Initialize (env var DEEPRAILS_API_KEY is recommended)
client = DeepRails(api_key="YOUR_API_KEY")

WORKFLOW_ID = "wkfl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
EVENT_ID = "evt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

workflow_response = client.defend.retrieve_workflow(
    workflow_id=WORKFLOW_ID
)
print(workflow_response.status)

event_response = client.defend.retrieve_event(
    workflow_id=WORKFLOW_ID,
    event_id=EVENT_ID
)
print(event_response)

​
Check Defend Outcomes via the API Console

  1. Open DeepRails API Console → Defend → Data.
  2. Filter by time range or search by workflow_id or nametag to find events.
  3. Open any event to see guardrail scores and remediation chains (FixIt/ReGen).
Defend data – placeholder

Browse real-time Defend events, filters, and remediation details in the Defend API Control Panel.

​
Next Steps

Configure Guardrails

Explore the metrics behind evaluations—correctness, safety, completeness, and more.

Defend Overview

Learn how workflows, metrics, and remediation work together.