Quickstart Guide

Get started with the Defend API in minutes.

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.
   

Install the SDK

Python

pip install deeprails

TypeScript / Node

npm install deeprails

Ruby

gem install deeprails

Go

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.

Python

from deeprails import DeepRails

# Initialize (env var DEEPRAILS_API_KEY is recommended)
client = DeepRails(token="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)

TypeScript / Node

import { DeepRails } from "deeprails";

// 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_xxxxxxxx"]
});

console.log(workflowResponse);

Ruby

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_xxxxxxxx"]
)
puts workflow_response

Go

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"),
			Type: deeprails.F(deeprails.DefendNewWorkflowParamsTypeCustom),
			CustomHallucinationThresholdValues: deeprails.F(map[string]float64{
				"completeness":          0.850000,
				"instruction_adherence": 0.750000,
			}),
			ImprovementAction: deeprails.F(deeprails.DefendNewWorkflowParamsImprovementActionFixit),
      MaxImprovementAttempts: deeprails.F(5),
      WebSearch: deeprails.F(true),
      FileSearch: deeprails.F([]string{"file_xxxxxxxx"}),
    },
	)

	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 action (either fixit, regen, or do_nothing) that Defend uses to remediate outputs when they fail one or more guardrail metrics.

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. This determines which metrics Defend will evaluate and how strict each threshold is for custom workflows.
automatic_hallucination_ tolerance_levels	object	The 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_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 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

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_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)

TypeScript / Node

import { DeepRails } from "deeprails";

// 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({
  workflow_id: "defend_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",
});

console.log(eventResponse);

Ruby

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(
  workflow_id: "defend_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"
)
puts event_response

Go

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(),
		"defend_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
		deeprails.DefendSubmitEventParams{
			ModelInput: deeprails.F(deeprails.DefendSubmitEventParamsModelInput{
				UserPrompt: deeprails.F("Hello, how are you?"),
			}),
			ModelOutput: deeprails.F("I am good, thank you!"),
			ModelUsed:   deeprails.F("gpt-4o-mini"),
			RunMode:     deeprails.F(deeprails.DefendSubmitEventParamsRunModeSmart),
			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 system_prompt or user_prompt.
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 include precision_plus, precision, smart, and economy. Defaults to smart.

Optional Parameters

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

Retrieve Workflow Data

You can retrieve workflow details and fetch events from a specific workflow.

Python

from deeprails import DeepRails

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

WORKFLOW_ID = "defend_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)

TypeScript / Node

import { DeepRails } from "deeprails";

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

const WORKFLOW_ID = "defend_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
const EVENT_ID = "evt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";

const workflowResponse = await client.defend.retrieveWorkflow({
  workflow_id: WORKFLOW_ID
});
console.log(workflowResponse.status);

const eventResponse = await client.defend.retrieveEvent({
  workflow_id: WORKFLOW_ID,
  event_id: EVENT_ID
});
console.log(eventResponse);

Ruby

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 = "defend_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
EVENT_ID = "evt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

workflow_response = deeprails.defend.retrieve_workflow(
  workflow_id: WORKFLOW_ID
)
puts workflow_response.status

event_response = deeprails.defend.retrieve_event(
  workflow_id: WORKFLOW_ID,
  event_id: EVENT_ID
)
puts event_response

Go

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))

	WORKFLOW_ID := "defend_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
	EVENT_ID := "evt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

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

	fmt.Printf("%s\n", workflow.Status)

	// Retrieve event details
	event, err := client.Defend.GetEvent(
		context.TODO(),
		WORKFLOW_ID,
		EVENT_ID,
	)
	if err != nil {
		log.Fatal(err)
	}

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

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).
   

Next Steps

Configure Guardrails

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

Defend Overview

Learn how workflows, metrics, and remediation work together.