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

Response

201
application/json

Workflow created successfully

The response is of type object.