Quickstart Guide

Create an API Key

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

Install the SDK

Python
TypeScript / Node
Ruby
Go

pip install deeprails

npm install deeprails

gem install deeprails

go get github.com/deeprails/deeprails-go-sdk@latest

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 an automatic_hallucination_tolerance_levels 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_levels 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_xxxxxxxxxxxx"],
    context_awareness=True,
)
print(workflow_response)

import { DeepRails } from "deeprails";

async function main() {
  // Initialize (env var DEEPRAILS_API_KEY is recommended)
  const client = new DeepRails(process.env.DEEPRAILS_API_KEY || "YOUR_API_KEY");

  const workflowResponse = await client.defend.createWorkflow({
    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_xxxxxxxxxxxx"],
    context_awareness: true,
  });

  console.log(workflowResponse);
}

main().catch(console.error);

require "deeprails"

# Initialize (env var DEEPRAILS_API_KEY is recommended)
deeprails = Deeprails::Client.new(
  api_key: ENV["DEEPRAILS_API_KEY"] || "YOUR_API_KEY"
)

workflow_response = deeprails.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_xxxxxxxxxxxx"],
  context_awareness: true,
)
puts workflow_response

package main

import (
	"context"
	"fmt"
	"log"
	"github.com/deeprails/deeprails-go-sdk"
	"github.com/deeprails/deeprails-go-sdk/option"
)

func main() {
	apiKey := "YOUR_API_KEY"

  // NewClient will use the api key set under DEEPRAILS_API_KEY if option.WithAPIKey is not specified
	client := deeprails.NewClient(option.WithAPIKey(apiKey))

	workflow, err := client.Defend.NewWorkflow(
		context.TODO(),
		deeprails.DefendNewWorkflowParams{
      Name: deeprails.F("Test Workflow"),
      Description: deeprails.F("A workflow used to test the DeepRails API"),
			ThresholdType: deeprails.F(deeprails.DefendNewWorkflowParamsThresholdTypeCustom),
			CustomHallucinationThresholdValues: deeprails.F(map[string]float64{
				"completeness":          0.850000,
				"instruction_adherence": 0.750000,
			}),
			ImprovementAction: deeprails.F(deeprails.DefendNewWorkflowParamsImprovementActionFixit),
      MaxImprovementAttempts: deeprails.F(int64(5)),
      WebSearch: deeprails.F(true),
      FileSearch: deeprails.F([]string{"file_xxxxxxxxxxxx"}),
      ContextAwareness: deeprails.F(true),
    },
	)

	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Created workflow with ID: %s\n", workflow.WorkflowID)

}

Required Parameters

Field	Type	Description
`name`	string	The name of the workflow.
`threshold_type`	string	The workflow type (either `automatic` or `custom`), which determines whether thresholds are specified by the user or set automatically.
`improvement_action`	string	The remediation strategy when outputs fail guardrail metrics. `fixit` rewrites the failing output to pass the metrics. `regen` prompts the LLM to regenerate the output from scratch. `do_nothing` records the failure without attempting remediation.

Optional Parameters

Field	Type	Description
`description`	string	A description of the use case of the workflow or other additional information.
`custom_hallucination_threshold_values`	object	The mapping of guardrail metrics to floating point threshold values (0.0-1.0). Required when `threshold_type` is `custom`. This determines which metrics Defend will evaluate and how strict each threshold is.
`automatic_hallucination_tolerance_levels`	object	The mapping of guardrail metrics to tolerance levels (`low`, `medium`, or `high`). Required when `threshold_type` is `automatic`. This determines which metrics Defend will evaluate and how strict the adaptive thresholds start.
`max_improvement_attempts`	integer	The maximum number of improvement attempts to be applied to one workflow event before it is considered failed. Defaults to 10.
`web_search`	boolean	Whether or not the extended AI capability, web search, is available to the evaluation and remediation models.
`file_search`	string[]	A list of uploaded file IDs for the evaluation and remediation models to search using the extended AI capability, file search. Upload files first via `/files/upload`.
`context_awareness`	boolean	Whether or not the extended AI capability, context awareness, is available to the evaluation and remediation models.

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 affiliated 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_xxxxxxxxxxxx",
    model_input={
        "system_prompt": "You are a helpful tutor specializing in AP science classes.",
        "user_prompt": "Explain the difference between mitosis and meiosis in one sentence.",
        "ground_truth": "Mitosis produces two identical diploid daughter cells for growth and repair, while meiosis produces four genetically unique haploid gametes for sexual reproduction.",
        "context": [
            {"role": "user", "content": "I have an AP Bio exam tomorrow, can you help me study?"},
            {"role": "tutor", "content": "Sure, I'll help you study."}
        ]
    },
    model_output="Mitosis produces two genetically identical diploid cells for growth and tissue repair, whereas meiosis generates four genetically varied haploid gametes for sexual reproduction.",
    model_used="gpt-4o-mini",
    run_mode="precision",
    nametag="test",
)
print(event_response)

import { DeepRails } from "deeprails";

async function main() {
  // Initialize (env var DEEPRAILS_API_KEY is recommended)
  const client = new DeepRails(process.env.DEEPRAILS_API_KEY || "YOUR_API_KEY");

  const eventResponse = await client.defend.submitEvent(
    "wkfl_xxxxxxxxxxxx",
    {
      model_input: {
        system_prompt: "You are a helpful tutor specializing in AP science classes.",
        user_prompt: "Explain the difference between mitosis and meiosis in one sentence.",
        ground_truth: "Mitosis produces two identical diploid daughter cells for growth and repair, while meiosis produces four genetically unique haploid gametes for sexual reproduction.",
        context: [
          { role: "user", content: "I have an AP Bio exam tomorrow, can you help me study?" },
          { role: "tutor", content: "Sure, I'll help you study." },
        ],
      },
      model_output: "Mitosis produces two genetically identical diploid cells for growth and tissue repair, whereas meiosis generates four genetically varied haploid gametes for sexual reproduction.",
      model_used: "gpt-4o-mini",
      run_mode: "precision",
      nametag: "test",
    }
  );

  console.log(eventResponse);
}

main().catch(console.error);

require "deeprails"

# Initialize (env var DEEPRAILS_API_KEY is recommended)
deeprails = Deeprails::Client.new(
  api_key: ENV["DEEPRAILS_API_KEY"] || "YOUR_API_KEY"
)

event_response = deeprails.defend.submit_event(
  "wkfl_xxxxxxxxxxxx",
  {
    model_input: {
      system_prompt: "You are a helpful tutor specializing in AP science classes.",
      user_prompt: "Explain the difference between mitosis and meiosis in one sentence.",
      ground_truth: "Mitosis produces two identical diploid daughter cells for growth and repair, while meiosis produces four genetically unique haploid gametes for sexual reproduction.",
      context: [
        { role: "user", content: "I have an AP Bio exam tomorrow, can you help me study?" },
        { role: "tutor", content: "Sure, I'll help you study." }
      ]
    },
    model_output: "Mitosis produces two genetically identical diploid cells for growth and tissue repair, whereas meiosis generates four genetically varied haploid gametes for sexual reproduction.",
    model_used: "gpt-4o-mini",
    run_mode: "precision",
    nametag: "test"
  }
)
puts event_response

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/deeprails/deeprails-go-sdk"
	"github.com/deeprails/deeprails-go-sdk/option"
)

func main() {
	apiKey := "YOUR_API_KEY"

	client := deeprails.NewClient(option.WithAPIKey(apiKey))

	// Submit a workflow event
	event, err := client.Defend.SubmitEvent(
		context.TODO(),
		"wkfl_xxxxxxxxxxxx",
		deeprails.DefendSubmitEventParams{
			ModelInput: deeprails.F(deeprails.DefendSubmitEventParamsModelInput{
        SystemPrompt: deeprails.F("You are a helpful tutor specializing in AP science classes."),
        UserPrompt: deeprails.F("Explain the difference between mitosis and meiosis in one sentence."),
        GroundTruth: deeprails.F("Mitosis produces two identical diploid daughter cells for growth and repair, while meiosis produces four genetically unique haploid gametes for sexual reproduction."),
        Context: deeprails.F([]string{
          "user: I have an AP Bio exam tomorrow, can you help me study?",
          "tutor: Sure, I'll help you study.",
        }),
			}),
		  ModelOutput: deeprails.F("Mitosis produces two genetically identical diploid cells for growth and tissue repair, whereas meiosis generates four genetically varied haploid gametes for sexual reproduction."),
			ModelUsed:   deeprails.F("gpt-4o-mini"),
			RunMode:     deeprails.F(deeprails.DefendSubmitEventParamsRunModePrecision),
			Nametag:     deeprails.F("test"),
		},
	)

	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("%+v\n", event)
}

Required Parameters

Field	Type	Description
`workflow_id`	string	The ID of the Defend workflow associated with this event. (find it in Console → Defend → Manage Workflows)
`model_input`	object	Your prompt + optional context. Must include at least a `user_prompt`. See model_input fields below.
`model_output`	string	The LLM output to be evaluated and recorded with the event.
`model_used`	string	The model used to generate the output, like `gpt-4o` or `o3`.
`run_mode`	string	Run mode for the workflow event that determines which models are used to evaluate the event. Available run modes (fastest to most thorough): `super_fast`, `fast`, `precision`, `precision_codex`, `precision_max`, and `precision_max_codex`. Defaults to `fast`. Note: `super_fast` does not support Web Search or File Search — if your workflow has these enabled, use a different run mode or edit the workflow to disable them.

model_input Fields

Field	Type	Required	Description
`user_prompt`	string	Yes	The user prompt sent to the LLM.
`system_prompt`	string	No	The system prompt used to configure the LLM’s behavior.
`ground_truth`	string	No	The expected correct answer. Required when the workflow evaluates the `ground_truth_adherence` metric.
`context`	array	No	Structured context for the evaluation, such as conversation history or domain-specific facts. Each item should have `role` and `content` fields. Required when `context_awareness` is enabled on the workflow.

Optional Parameters

Field	Type	Description
`nametag`	string	A user-defined tag for the event.

Retrieve Workflow and Event Details

You can retrieve workflow details and fetch events from a specific workflow. Events are processed asynchronously, so you will need to poll using the event ID until the status is Completed.

Python
TypeScript / Node
Ruby
Go

import time
from deeprails import DeepRails

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

WORKFLOW_ID = "wkfl_xxxxxxxxxxxx"
EVENT_ID = "evt_xxxxxxxxxxxx"

# Retrieve workflow details
workflow_response = client.defend.retrieve_workflow(
    workflow_id=WORKFLOW_ID
)
print(workflow_response)

# Poll event until completion
event_response = None
while True:
    event_response = client.defend.retrieve_event(
        workflow_id=WORKFLOW_ID,
        event_id=EVENT_ID,
    )
    if event_response.status == "Completed":
        break
    print(f"Event status: {event_response.status} — waiting...")
    time.sleep(2)

# Check the improvement outcome
tool_status = event_response.improvement_tool_status
if tool_status == "improved":
    print(f"Improved model output: {event_response.improved_model_output}")
elif tool_status == "improvement_failed":
    print("Improvement action failed to improve output")
elif tool_status == "no_improvement_required":
    print("Improvement not needed!")

import { DeepRails } from "deeprails";

async function main() {
  // Initialize (env var DEEPRAILS_API_KEY is recommended)
  const client = new DeepRails(process.env.DEEPRAILS_API_KEY || "YOUR_API_KEY");

  const WORKFLOW_ID = "wkfl_xxxxxxxxxxxx";
  const EVENT_ID = "evt_xxxxxxxxxxxx";

  // Retrieve workflow details
  const workflowResponse = await client.defend.retrieveWorkflow(WORKFLOW_ID);
  console.log(workflowResponse);

  // Poll event until completion
  let eventResponse: any = null;
  while (true) {
    eventResponse = await client.defend.retrieveEvent(WORKFLOW_ID, EVENT_ID);
    if (eventResponse.status === "Completed") break;
    console.log(`Event status: ${eventResponse.status} — waiting...`);
    await new Promise((resolve) => setTimeout(resolve, 2000));
  }

  // Check the improvement outcome
  const toolStatus = eventResponse.improvement_tool_status;
  if (toolStatus === "improved") {
    console.log(`Improved model output: ${eventResponse.improved_model_output}`);
  } else if (toolStatus === "improvement_failed") {
    console.log("Improvement action failed to improve output");
  } else if (toolStatus === "no_improvement_required") {
    console.log("Improvement not needed!");
  }
}

main().catch(console.error);

require "deeprails"

# Initialize (env var DEEPRAILS_API_KEY is recommended)
deeprails = Deeprails::Client.new(
  api_key: ENV["DEEPRAILS_API_KEY"] || "YOUR_API_KEY"
)

WORKFLOW_ID = "wkfl_xxxxxxxxxxxx"
EVENT_ID = "evt_xxxxxxxxxxxx"

# Retrieve workflow details
workflow_response = deeprails.defend.retrieve_workflow(WORKFLOW_ID)
puts workflow_response

# Poll event until completion
event_response = nil
loop do
  event_response = deeprails.defend.retrieve_event(EVENT_ID, workflow_id: WORKFLOW_ID)
  break if event_response.status == "Completed"
  puts "Event status: #{event_response.status} — waiting..."
  sleep(2)
end

# Check the improvement outcome
tool_status = event_response.improvement_tool_status
if tool_status == "improved"
  puts "Improved model output: #{event_response.improved_model_output}"
elsif tool_status == "improvement_failed"
  puts "Improvement action failed to improve output"
elsif tool_status == "no_improvement_required"
  puts "Improvement not needed!"
end

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/deeprails/deeprails-go-sdk"
	"github.com/deeprails/deeprails-go-sdk/option"
)

func main() {
	apiKey := "YOUR_API_KEY"

	client := deeprails.NewClient(option.WithAPIKey(apiKey))

	WORKFLOW_ID := "wkfl_xxxxxxxxxxxx"
	EVENT_ID := "evt_xxxxxxxxxxxx"

	// Retrieve workflow details
	workflow, err := client.Defend.GetWorkflow(
		context.TODO(),
		WORKFLOW_ID,
		deeprails.DefendGetWorkflowParams{},
	)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("%+v\n", workflow)

	// Poll event until completion
	var event *deeprails.WorkflowEventDetailResponse
	for {
		event, err = client.Defend.GetEvent(
			context.TODO(),
			WORKFLOW_ID,
			EVENT_ID,
		)
		if err != nil {
			log.Fatal(err)
		}
		if string(event.Status) == "Completed" {
			break
		}
		fmt.Printf("Event status: %s — waiting...\n", event.Status)
		time.Sleep(2 * time.Second)
	}

	// Check the improvement outcome
	toolStatus := event.ImprovementToolStatus
	if toolStatus == "improved" {
		fmt.Printf("Improved model output: %s\n", event.ImprovedModelOutput)
	} else if toolStatus == "improvement_failed" {
		fmt.Println("Improvement action failed to improve output")
	} else if toolStatus == "no_improvement_required" {
		fmt.Println("Improvement not needed!")
	}
}

Check Defend Outcomes via the API Console

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

Next Steps

Configure Guardrails

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

Defend Overview

Learn how workflows, metrics, and remediation work together.

Get Started

Monitor API

Defend API

Evaluation Engine

Guardrail Metrics

Create an API Key

Install the SDK

Create your first Defend workflow

Types of Workflows

Required Parameters

Optional Parameters

Submit a Workflow Event

Required Parameters

model_input Fields

Optional Parameters

Retrieve Workflow and Event Details

Check Defend Outcomes via the API Console

Next Steps

Configure Guardrails

Defend Overview

Get Started

Monitor API

Defend API

Evaluation Engine

Guardrail Metrics

​Create an API Key

​Install the SDK

​Create your first Defend workflow

​Types of Workflows

​Required Parameters

​Optional Parameters

​Submit a Workflow Event

​Required Parameters

​model_input Fields

​Optional Parameters

​Retrieve Workflow and Event Details

​Check Defend Outcomes via the API Console

​Next Steps

Configure Guardrails

Defend Overview

Create an API Key

Install the SDK

Create your first Defend workflow

Types of Workflows

Required Parameters

Optional Parameters

Submit a Workflow Event

Required Parameters

model_input Fields

Optional Parameters

Retrieve Workflow and Event Details

Check Defend Outcomes via the API Console

Next Steps