POST
/
api
/
v1
/
workflows
Create a new workflow
curl --request POST \
  --url https://api.getdecisional.ai/api/v1/workflows \
  --header 'Content-Type: application/json' \
  --data '{
  "value": {
    "name": "Revenue Analysis",
    "query": "What is the latest revenue of Square?",
    "description": "Workflow to analyze financial metrics of fintech companies",
    "context_id": "ctx_abc123xyz789",
    "advanced_reasoning": true,
    "model": "llama-v3-70b"
  }
}'
{
"value": {
"id": "wfl_abc123xyz789",
"name": "Revenue Analysis",
"query": "What is the latest revenue of Square?",
"response": "Square's latest revenue is $1.2 billion <source_id=1>",
"context_id": "ctx_abc123xyz789",
"advanced_reasoning": true,
"model": "llama-v3-70b",
"citations": [
{
"citation_key": "<source_id=1>",
"data_source_id": "dsc_n5kdefxua5fnrd",
"file_name": "report.pdf",
"page_number": 4
}
],
"status": "PROCESSED",
"created_at": 1679644800
}
}

Overview

Create a new workflow to process queries against a knowledge engine. Workflows represent individual question-answer sessions that leverage your uploaded documents and data sources.

Error Handling

This endpoint can return various error responses. For comprehensive error handling information, see the Workflows Error Handling Guide.

Common Error Scenarios

Best Practices

Pre-flight Validation

Always validate the knowledge engine status before creating workflows:
// Check knowledge engine status first
const keResponse = await fetch(`/api/v1/knowledge-engines/${knowledgeEngineId}`, {
  headers: {
    'Authorization': 'Basic ' + btoa(apiKey + ':')
  }
});

const ke = await keResponse.json();

if (ke.status !== 'ready') {
  throw new Error(`Knowledge engine not ready: ${ke.status}`);
}

if (ke.data_source_count === 0) {
  throw new Error('No data sources available');
}

// Now create the workflow
const workflowResponse = await fetch('/api/v1/workflows', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa(apiKey + ':'),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    type: 'query',
    name: 'Revenue Analysis',
    query: 'What was the revenue growth in Q4?',
    knowledge_engine_id: knowledgeEngineId
  })
});

Error Handling

Implement proper error handling with retry logic for transient failures:
async function createWorkflowWithRetry(workflowData, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch('/api/v1/workflows', {
        method: 'POST',
        headers: {
          'Authorization': 'Basic ' + btoa(apiKey + ':'),
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(workflowData)
      });
      
      if (response.ok) {
        return await response.json();
      }
      
      const errorData = await response.json();
      
      // Don't retry client errors (4xx)
      if (response.status >= 400 && response.status < 500) {
        throw new Error(errorData.error);
      }
      
      // Retry server errors (5xx) with exponential backoff
      if (attempt < maxRetries) {
        await new Promise(resolve => 
          setTimeout(resolve, Math.pow(2, attempt) * 1000)
        );
        continue;
      }
      
      throw new Error(errorData.error);
    } catch (error) {
      if (attempt === maxRetries) throw error;
    }
  }
}

Body

application/json
name
string
required

Name of the workflow

Maximum length: 50
Example:

"Fintech Companies"

query
string
required

The query to ask the knowledge engine

Example:

"What is the latest revenue of Square?"

knowledge_engine_id
string
required

ID of the knowledge engine this workflow belongs to

Example:

"kng_abc123xyz789"

type
enum<string>
required

Type of the workflow

Available options:
query
Example:

"query"

description
string

Short description of what the workflow is comprised of

Example:

"Workflow for processing and analyzing fintech companies"

context_id
string

Context ID used in case of thread mode for chat based workflows

Example:

"ctx_abc123xyz78910"

advanced_reasoning
boolean

Flag to enable advanced reasoning for the workflow

Example:

true

model
enum<string>

LLM to use for the query

Available options:
auto,
claude-3.5-sonnet,
llama-v3-70b,
o1,
o3-mini,
gpt-4o,
gpt-5
Example:

"llama-v3-70b"

Response

Workflow created successfully

id
string

Alphanumeric 14 character string identifier

Example:

"wfl_abc123xyz78910"

name
string

Name of the workflow

Example:

"Fintech Companies"

query
string

The query to ask the knowledge engine

Example:

"What is the latest revenue of Square?"

response
string

The response from the knowledge engine

Example:

"Square's latest revenue is $1.2 billion"

context_id
string

Context ID used in case of thread mode for chat based workflows

Example:

"ctx_abc123xyz78910"

advanced_reasoning
boolean

Flag to enable advanced reasoning for the workflow

Example:

true

model
enum<string>

LLM to use for the query

Available options:
auto,
claude-3.5-sonnet,
llama-v3-70b,
o1,
o3-mini,
gpt-4o,
gpt-5,
gpt-5-mini,
gpt-5-nano,
gpt-5-chat
Example:

"llama-v3-70b"

citations
object[]

List of citations referenced in the response, or null if no citations are available

status
enum<string>

Current status of the workflow

Available options:
PROCESSING,
PROCESSED
Example:

"PROCESSED"

created_at
integer

Unix timestamp when this entity was created

Example:

1679644800