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.
  • Python
  • TypeScript / Node
  • Ruby
  • Go
from deeprails import DeepRails

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

workflow_response = client.defend.create_workflow(
    improvement_action="fixit",
    metrics={
        "completeness": 0.85,
        "instruction_adherence": 0.75,
    },
    name="Test Workflow",
    type="custom",
)
print(workflow_response.workflow_id)

​
Required Parameters

FieldTypeDescription
namestringThe name of the workflow
typestringThe workflow type (either automatic or custom), which determines whether thresholds are specified by the user or set automatically.
metricsobjectThe mapping of guardrail metrics to floating point threshold values. This determines which metrics Defend will evaluate and how strict its hallucination thresholds are.

​
Optional Parameters

FieldTypeDescription
improvement_actionstringThe action (either fixit or regenerate) that Defend uses to remediate outputs when they fail one or more guardrail metrics. If left unspecified, no remediation will take place upon failure.
descriptionstringA description of the use case of the workflow or other additional information.
automatic_tolerancestringThe level used to calibrate thresholds for automatic workflows (either low, medium, or high). An automatic workflow cannot be created without specifying this field, but automatic_tolerance will be ignored for custom workflows.
max_retriesintegerThe maximum number of improvement attempts to be applied to one workflow event before it is considered failed. Defaults to 10.

​
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="defend_xxxxxxxxxxxx",
    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.event_id)

​
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 atleast 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.
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(token="YOUR_API_KEY")

WORKFLOW_ID = "defend_xxxxxxxxxxxx"
EVENT_ID = "wkfl_evt_xxxxxxxxxxx"

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

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

​
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.
⌘I