Create Workflow

Create a new workflow

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

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

POST

api

workflows

Create a new workflow

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

{
  "$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

Workflow created successfully

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

Knowledge Engines

Data Sources

Workflows

Tool Runs

Overview

Error Handling

Common Error Scenarios

Best Practices

Pre-flight Validation

Error Handling

Authorizations

Body

Response

​Overview

​Error Handling

​Common Error Scenarios

​Best Practices

​Pre-flight Validation

​Error Handling

Authorizations

Body

Response

Overview

Error Handling

Common Error Scenarios

Best Practices

Pre-flight Validation

Error Handling