Skip to main content
POST
/
api
/
v1
/
workflows
Create and start a workflow
curl --request POST \
  --url https://app.dimred.com/api/v1/workflows \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "project_id": "proj_abc123",
  "dataset_id": "ds_xyz456",
  "prompt_id": "prompt_def789",
  "metric_id": "metric_ghi012",
  "model_name": "gpt-4o-mini",
  "provider": "openai",
  "num_iterations": 3,
  "includeProjectMetrics": false,
  "mode": "tune"
}'
{
  "id": "<string>",
  "project_id": "<string>",
  "dataset_id": "<string>",
  "prompt_id": "<string>",
  "metric_id": "<string>",
  "model_name": "<string>",
  "provider": "<string>",
  "target_metric_name": "<string>",
  "target_metric_value": 123,
  "num_iterations": 123,
  "status": "queued",
  "task_id": "<string>",
  "metrics": {},
  "error_message": "<string>",
  "config": {},
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "started_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "is_billed": true,
  "project_name": "<string>"
}

Authorizations

​
x-api-key
string
header
required

API key for authentication. Obtain from your DimRed dashboard. The organization context is automatically derived from the API key.

Body

application/json
​
project_id
string
required

Project identifier

​
dataset_id
string
required

Dataset identifier for evaluation

​
prompt_id
string
required

Initial prompt identifier to use or optimize

​
model_name
string
required

Name of the model (e.g., 'gpt-4o-mini', 'claude-3-5-sonnet')

​
provider
enum<string>
required

LLM provider

Available options:
openai,
anthropic,
openrouter
​
metric_id
string

Metric identifier for optimization (required unless mode is 'inference')

​
num_iterations
integer
default:1

Number of optimization iterations

Required range: x >= 1
​
includeProjectMetrics
boolean
default:true

Whether to include all project metrics in evaluation

​
mode
enum<string>

Workflow mode: tune (optimize prompt), evaluate (single run), inference (no metrics)

Available options:
tune,
evaluate,
inference
​
config
object

Additional configuration (e.g., include_icl, icl_session_id)

Response

Workflow created and started successfully

​
id
string

Unique identifier for the workflow

​
project_id
string

Project identifier

​
dataset_id
string | null

Dataset identifier

​
prompt_id
string

Initial prompt identifier

​
metric_id
string

Metric identifier for evaluation

​
model_name
string

Name of the model (e.g., 'gpt-4o-mini', 'claude-3-5-sonnet')

​
provider
string

LLM provider (e.g., 'openai', 'anthropic')

​
target_metric_name
string

Deprecated field

​
target_metric_value
number

Deprecated field

​
num_iterations
integer

Number of optimization iterations

​
status
enum<string>

Current status of the workflow

Available options:
queued,
in_progress,
completed,
failed,
cancelled
​
task_id
string | null

Background task identifier

​
metrics
object | null

Performance metrics and results

​
error_message
string | null

Error details if failed

​
config
object | null

Additional configuration (e.g., mode, include_icl, icl_session_id)

​
created_at
string<date-time>

ISO 8601 timestamp of creation

​
updated_at
string<date-time>

ISO 8601 timestamp of last update

​
started_at
string<date-time> | null

ISO 8601 timestamp when workflow started

​
completed_at
string<date-time> | null

ISO 8601 timestamp when workflow completed

​
is_billed
boolean

Whether the workflow has been billed

​
project_name
string | null

Project name (denormalized)