> ## Documentation Index > Fetch the complete documentation index at: https://docs.deeprails.com/llms.txt > Use this file to discover all available pages before exploring further. # 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.
API Keys – placeholder
### Install the SDK ```python theme={null} pip install deeprails ``` ```ts theme={null} npm install deeprails ``` ```Ruby theme={null} gem install deeprails ``` ```go theme={null} 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 theme={null} 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) ``` ```ts theme={null} 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); ``` ```Ruby theme={null} 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 ``` ```go theme={null} 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 theme={null} 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) ``` ```ts theme={null} 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); ``` ```Ruby theme={null} 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 ``` ```go theme={null} 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 theme={null} 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!") ``` ```ts theme={null} 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); ``` ```Ruby theme={null} 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 ``` ```go theme={null} 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 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 ### Next Steps Explore the metrics behind evaluations—correctness, safety, completeness, and more. Learn how workflows, metrics, and remediation work together.