Create Workflow

Creates a new workflow associated with a knowledge engine

POST /api/v1/workflows

Create a new workflow

cURL

curl --request POST \
  --url https://api.getdecisional.ai/api/v1/workflows \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "$ref": "#/components/examples/CreateWorkflowRequest"
}
'

import requests

url = "https://api.getdecisional.ai/api/v1/workflows"

payload = { "$ref": "#/components/examples/CreateWorkflowRequest" }
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({$ref: '#/components/examples/CreateWorkflowRequest'})
};

fetch('https://api.getdecisional.ai/api/v1/workflows', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.getdecisional.ai/api/v1/workflows",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '$ref' => '#/components/examples/CreateWorkflowRequest'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.getdecisional.ai/api/v1/workflows"

	payload := strings.NewReader("{\n  \"$ref\": \"#/components/examples/CreateWorkflowRequest\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Basic <encoded-value>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.getdecisional.ai/api/v1/workflows")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"$ref\": \"#/components/examples/CreateWorkflowRequest\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getdecisional.ai/api/v1/workflows")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"$ref\": \"#/components/examples/CreateWorkflowRequest\"\n}"

response = http.request(request)
puts response.read_body

201

Example

{
  "$ref": "#/components/examples/WorkflowResponse"
}

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

Knowledge Engine Not Ready (400)

{
  "error": "knowledge engine is not ready, current status: processing"
}

Resolution: Wait for the knowledge engine to finish processing uploaded documents before creating workflows.

No Active Data Sources (400)

{
  "error": "knowledge engine has no active data sources"
}

Resolution: Upload at least one document to the knowledge engine before creating workflows.

Invalid Model (400)

{
  "error": "Model unsupported-model not supported"
}

Resolution: Use a supported model name or omit the field to use the default model.

Model Not Enabled (400)

{
  "error": "Model Claude 3.5 Sonnet is not enabled"
}

Resolution: Contact support to enable the model or use a different enabled model.

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;
    }
  }
}

Authorizations

Authorization · string · header · required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Body

application/json

name · string · required

Name of the workflow

Maximum string 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-4.5-sonnet, llama-v3-70b, llama-4-scout, llama-4-maverick, gemini-2.5, gpt-5.4, claude-4.6-haiku, gpt-4.1

Example:

"llama-v3-70b"

Response

201

application/json

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-4.5-sonnet, llama-v3-70b, llama-4-scout, llama-4-maverick, gemini-2.5, gpt-5.4, claude-4.6-haiku, gpt-4.1

Example:

"llama-v3-70b"

citations · object[]

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

Show child attributes

status · enum<string>

Current status of the workflow

Available options: PROCESSING, PROCESSED

Example:

"PROCESSED"

created_at · integer<int64>

Unix timestamp when this entity was created

Example:

1679644800