> ## 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.
# Submit a Workflow Event
> Use this endpoint to submit a model input and output pair to a workflow for evaluation
Workflow events represent individual LLM calls in your production use case. Whenever you receive a new LLM response, you can submit it, along with the input, to the workflow for evaluation and remediation. The `model_input` field in the request must be a dictionary (containing at least a `system_prompt` field or a `user_prompt` field), and the request must also include the `model_used` to generate the output (Ex. `gpt-5-mini`), the selected `run_mode` that determines speed/accuracy/cost for evaluation, and optionally a `nametag` for the workflow event.
The run mode determines which models power the evaluation (fastest to most thorough):
- `super_fast` - High-speed lightweight checks
- `fast` - Balanced speed and accuracy (default)
- `precision` - Deep multi-model analysis
- `precision_codex` - Code-optimized deep analysis
- `precision_max` - Exhaustive multi-pass verification
- `precision_max_codex` - Ultimate code-aware verification
Note: `super_fast` does not support Web Search or File Search capabilities. Requests using this mode on workflows with Web Search or File Search enabled will be rejected.
The event's evaluations will be run with the guardrail metrics and improvement action configured in its associated workflow.
When you create a workflow event, you'll receive an event ID. Use this ID to track the event's progress and retrieve all evaluations and improvement results.
## OpenAPI
````yaml /api-reference/openapi.yaml post /defend/{workflow_id}/events
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/{workflow_id}/events:
post:
tags:
- Defend
summary: Submit a Workflow Event
description: >
Use this endpoint to submit a model input and output pair to a workflow
for evaluation
parameters:
- name: workflow_id
in: path
description: Workflow ID associated with this event.
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
model_input:
type: object
description: >
A dictionary of inputs sent to the LLM to generate output.
The dictionary must contain a `user_prompt` field. For the
ground_truth_adherence guardrail metric, `ground_truth`
should be provided.
properties:
system_prompt:
type: string
description: The system prompt used to generate the output.
user_prompt:
type: string
description: The user prompt used to generate the output.
ground_truth:
type: string
description: >-
The ground truth for evaluating the Ground Truth
Adherence guardrail.
context:
type: array
description: >-
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.
items:
type: object
properties:
role:
type: string
description: The role of the speaker.
example: user
content:
type: string
description: The content of the message.
required:
- user_prompt
additionalProperties: false
model_output:
type: string
description: Output generated by the LLM to be evaluated.
model_used:
type: string
description: Model ID used to generate the output, like `gpt-4o` or `o3`.
run_mode:
type: string
description: >
Run mode for the workflow event. The run mode allows the
user to optimize for speed, accuracy, and cost by
determining 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 capabilities
enabled, use a different run mode or edit the workflow to
disable them.
enum:
- super_fast
- fast
- precision
- precision_codex
- precision_max
- precision_max_codex
nametag:
type: string
description: An optional, user-defined tag for the event.
required:
- model_input
- model_output
- model_used
- run_mode
responses:
'200':
description: Workflow event created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowEventResponse'
'400':
description: Invalid request
'401':
description: Unauthorized
'404':
description: Workflow not found
security:
- BearerAuth: []
x-codeSamples:
- lang: python
label: Submit a Workflow Event
source: |
from deeprails import DeepRails
DEEPRAILS_API_KEY = "YOUR_API_KEY"
client = DeepRails(
api_key=DEEPRAILS_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.",
"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)
components:
schemas:
WorkflowEventResponse:
type: object
properties:
event_id:
type: string
description: A unique workflow event ID.
example: evt_xxxxxxxxxxxx
workflow_id:
type: string
description: Workflow ID associated with the event.
example: wkfl_xxxxxxxxxxxx
created_at:
type: string
format: date-time
description: The time the event was created in UTC.
example: '2025-11-10T01:32:44.591Z'
status:
type: string
description: Status of the event.
example: In Progress
enum:
- In Progress
- Completed
billing_request_id:
type: string
description: The ID of the billing request for the event.
example: bill_0123456789abcdefabcd
required:
- event_id
- workflow_id
- created_at
- status
- billing_request_id
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````