> ## 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.
# Create a Workflow
> Use this endpoint to create a new guardrail workflow by specifying guardrail thresholds, an improvement action, and optional extended capabilities.
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`, `file_search`, and `context_awareness` 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.
## OpenAPI
````yaml /api-reference/openapi.yaml post /defend
openapi: 3.0.0
info:
title: DeepRails API
description: >
DeepRails is a powerful developer tool with a comprehensive set of adaptive
& accurate guardrails to protect against LLM hallucinations - deploy our
Monitor and Defend APIs in less than 15 minutes for the best out-of-the-box
guardrails available.
version: v3.0
contact:
name: DeepRails Support
email: support@deeprails.ai
servers:
- url: https://api.deeprails.com
description: Production server
security:
- BearerAuth: []
paths:
/defend:
post:
tags:
- Defend
summary: Create a Workflow
description: >
Use this endpoint to create a new guardrail workflow by specifying
guardrail thresholds, an improvement action, and optional extended
capabilities.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Name of the workflow.
description:
type: string
description: Description for the workflow.
threshold_type:
type: string
description: >
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.
enum:
- automatic
- custom
automatic_hallucination_tolerance_levels:
type: object
description: >
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`.
additionalProperties:
type: string
enum:
- low
- medium
- high
custom_hallucination_threshold_values:
type: object
description: >
Mapping of guardrail metrics to floating point threshold
values. Possible metrics are `correctness`, `completeness`,
`instruction_adherence`, `context_adherence`,
`ground_truth_adherence`, or `comprehensive_safety`.
additionalProperties:
type: number
format: float
minimum: 0
maximum: 1
improvement_action:
type: string
description: >
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.
enum:
- regen
- fixit
- do_nothing
nullable: false
max_improvement_attempts:
type: integer
description: >-
Max. number of improvement action attempts until a given
event passes the guardrails. Defaults to 10.
default: 10
web_search:
type: boolean
description: >-
Whether to enable web search for this workflow's
evaluations. Defaults to false.
default: false
file_search:
type: array
description: >-
An array of file IDs to search in the workflow's
evaluations. Files must be uploaded via the DeepRails API
first.
items:
type: string
description: >-
A file ID corresponding to a file to search in the
workflow's evaluations.
context_awareness:
type: boolean
description: >-
Context includes any structured information that directly
relates to the model’s input and expected output—e.g., the
recent turn-by-turn history between an AI tutor and a
student, facts or state passed through an agentic workflow,
or other domain-specific signals your system already knows
and wants the model to condition on. This field determines
whether to enable context awareness for this workflow's
evaluations. Defaults to false.
default: false
required:
- name
- threshold_type
- improvement_action
responses:
'200':
description: Workflow created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DefendCreateResponse'
'400':
description: Invalid request
'401':
description: Unauthorized
security:
- BearerAuth: []
x-codeSamples:
- lang: python
label: Create an Automatic Workflow
source: |
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_xxxxxxxxxxxx"],
context_awareness=True,
)
print(workflow_response)
- lang: python
label: Create a Custom Workflow
source: |
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="custom",
custom_hallucination_threshold_values={
"completeness": 0.85,
"instruction_adherence": 0.75,
},
improvement_action="fixit",
max_improvement_attempts=10,
web_search=True,
file_search=["file_xxxxxxxxxxxx"],
context_awareness=True,
)
print(workflow_response)
components:
schemas:
DefendCreateResponse:
type: object
properties:
workflow_id:
type: string
description: A unique workflow ID.
example: wkfl_xxxxxxxxxxxx
status:
type: string
description: >-
Status of the selected workflow. May be `inactive` or `active`.
Inactive workflows will not accept events.
example: active
enum:
- inactive
- active
created_at:
type: string
format: date-time
description: The time the workflow was created in UTC.
example: '2025-01-15T10:30:00Z'
required:
- workflow_id
- status
- created_at
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````