Skip to main content
POST
/
defend
from deeprails import DeepRails

DEEPRAILS_API_KEY = "YOUR_API_KEY"

client = DeepRails(
    api_key=DEEPRAILS_API_KEY, 
)

workflow_response = client.defend.create_workflow(
  name="Test Workflow",
  description="A workflow used to test the DeepRails API",
  threshold_type="automatic",
  automatic_hallucination_tolerance_levels={
    "completeness": "low",
    "instruction_adherence": "medium",
  },
  improvement_action="fixit",
  max_improvement_attempts=10,
  web_search=True,
  file_search=["file_xxxxxxxx"]
)
print(workflow_response)
{
  "workflow_id": "wkfl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "status": "active",
  "created_at": "2025-01-15T10:30:00Z"
}
Workflows correspond to a production LLM use case, and will contain evaluations and improvement attempts for inputs and outputs from that use case. The guardrails to be measured, the method of remediation, and other evaluation details must all be configured at the time of the workflow’s creation

When polling this endpoint, the request body must include a name for the workflow, a workflow threshold_type, either a custom_hallucination_threshold_values or an automatic_hallucination_tolerance_levels object specifying which guardrail metrics to evaluate against and their corresponding hallucination thresholds, and an improvement_action. Optionally, extended AI capabilities like web_search can be included as tools for the evaluation.

Workflows created with this endpoint will be displayed in the console and can be accessed at other endpoints using the workflow_id returned.

The type of the workflow determines how hallucination thresholds are configured:
- automatic - Uses internal threshold logic based on tolerance level. The automatic_hallucination_tolerance_levels dictionary must be specified as low, medium, or high to indicate how strict the thresholds should be.
- custom - Allows the user to set custom thresholds (0.0-1.0) for each metric using the custom_hallucination_threshold_values dictionary.

The improvement action determines the remediation step for events where one or more metric evaluations fail below the threshold.
- regen - Re-runs the user’s prompt with minor variance
- fixit - Directly addresses shortcomings using the guardrail failure rationale(s)
- do_nothing - No improvement is attempted by DeepRails

When you create a workflow, you’ll receive a workflow ID. Use this ID to submit new events for evaluation and remediation for the defend workflow.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
name
string
required

Name of the workflow.

​
threshold_type
enum<string>
required

Type of thresholds to use for the workflow, either automatic or custom. Automatic thresholds are assigned internally after the user specifies a qualitative tolerance for the metrics, whereas custom metrics allow the user to set the threshold for each metric as a floating point number between 0.0 and 1.0.

Available options:
automatic,
custom
​
improvement_action
enum<string>
required

The action used to improve outputs that fail one or more guardrail metrics for the workflow events. May be regen, fixit, or do_nothing. ReGen runs the user's input prompt with minor induced variance. FixIt attempts to directly address the shortcomings of the output using the guardrail failure rationale. Do Nothing does not attempt any improvement.

Available options:
regen,
fixit,
do_nothing
​
description
string

Description for the workflow.

​
automatic_hallucination_tolerance_levels
object

Mapping of guardrail metrics to hallucination tolerance levels (either low, medium, or high). Possible metrics are completeness, instruction_adherence, context_adherence, ground_truth_adherence, or comprehensive_safety.

​
custom_hallucination_threshold_values
object

Mapping of guardrail metrics to floating point threshold values. Possible metrics are correctness, completeness, instruction_adherence, context_adherence, ground_truth_adherence, or comprehensive_safety.

​
max_improvement_attempts
integer
default:10

Max. number of improvement action attempts until a given event passes the guardrails. Defaults to 10.

​
web_search
boolean
default:false

Whether to enable web search for this workflow's evaluations. Defaults to false.

​
file_search
string[]

An array of file IDs to search in the workflow's evaluations. Files must be uploaded via the DeepRails API first.

A file ID corresponding to a file to search in the workflow's evaluations.

Response

Workflow created successfully

​
workflow_id
string
required

A unique workflow ID.

Example:

"wkfl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

​
status
enum<string>
required

Status of the selected workflow. May be inactive or active. Inactive workflows will not accept events.

Available options:
inactive,
active
Example:

"active"

​
created_at
string<date-time>
required

The time the workflow was created in UTC.

Example:

"2025-01-15T10:30:00Z"