> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getdecisional.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Workflow

> Creates a new workflow associated with a knowledge engine

## 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](/api-reference/workflows/error-handling).

### Common Error Scenarios

<AccordionGroup>
  <Accordion title="Knowledge Engine Not Ready (400)">
    ```json theme={null}
    {
      "error": "knowledge engine is not ready, current status: processing"
    }
    ```

    **Resolution**: Wait for the knowledge engine to finish processing uploaded documents before creating workflows.
  </Accordion>

  <Accordion title="No Active Data Sources (400)">
    ```json theme={null}
    {
      "error": "knowledge engine has no active data sources"
    }
    ```

    **Resolution**: Upload at least one document to the knowledge engine before creating workflows.
  </Accordion>

  <Accordion title="Invalid Model (400)">
    ```json theme={null}
    {
      "error": "Model unsupported-model not supported"
    }
    ```

    **Resolution**: Use a supported model name or omit the field to use the default model.
  </Accordion>

  <Accordion title="Model Not Enabled (400)">
    ```json theme={null}
    {
      "error": "Model Claude 3.5 Sonnet is not enabled"
    }
    ```

    **Resolution**: Contact support to enable the model or use a different enabled model.
  </Accordion>
</AccordionGroup>

## Best Practices

### Pre-flight Validation

Always validate the knowledge engine status before creating workflows:

```javascript theme={null}
// 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:

```javascript theme={null}
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;
    }
  }
}
```


## OpenAPI

````yaml POST /api/v1/workflows
openapi: 3.0.1
info:
  title: Knowledge Engine API
  description: Public API endpoints for managing knowledge engines
  version: 1.0.0
servers:
  - url: https://api.getdecisional.ai
security: []
paths:
  /api/v1/workflows:
    post:
      summary: Create a new workflow
      description: Creates a new workflow associated with a knowledge engine
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkflow'
            example:
              $ref: '#/components/examples/CreateWorkflowRequest'
      responses:
        '201':
          description: Workflow created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowResponse'
              example:
                $ref: '#/components/examples/WorkflowResponse'
        '400':
          description: Bad Request - Various validation and state errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_knowledge_engine_id:
                  summary: Invalid Knowledge Engine ID
                  value:
                    error: Invalid knowledge engine ID
                knowledge_engine_not_ready:
                  summary: Knowledge Engine Not Ready
                  value:
                    error: 'knowledge engine is not ready, current status: processing'
                no_active_data_sources:
                  summary: No Active Data Sources
                  value:
                    error: knowledge engine has no active data sources
                invalid_model:
                  summary: Invalid Model
                  value:
                    error: Model unsupported-model not supported
                model_not_enabled:
                  summary: Model Not Enabled
                  value:
                    error: Model Claude 3.5 Sonnet is not enabled
                missing_required_field:
                  summary: Missing Required Field
                  value:
                    error: >-
                      Key: 'WorkflowRequest.Name' Error:Field validation for
                      'Name' failed on the 'required' tag
                invalid_json:
                  summary: Invalid JSON
                  value:
                    error: >-
                      invalid character '}' looking for beginning of object key
                      string
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Unauthorized
        '500':
          description: Internal Server Error - Processing failures
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                rag_service_failure:
                  summary: RAG Service Failure
                  value:
                    error: 'Failed to process query: connection timeout'
                database_error:
                  summary: Database Transaction Error
                  value:
                    error: 'Failed to create workflow: database connection lost'
                document_retrieval_error:
                  summary: Document Retrieval Error
                  value:
                    error: 'Failed to retrieve documents: vector database unavailable'
components:
  schemas:
    CreateWorkflow:
      type: object
      required:
        - name
        - query
        - knowledge_engine_id
        - type
      properties:
        name:
          type: string
          maxLength: 50
          description: Name of the workflow
          example: Fintech Companies
        query:
          type: string
          description: The query to ask the knowledge engine
          example: What is the latest revenue of Square?
        knowledge_engine_id:
          type: string
          description: ID of the knowledge engine this workflow belongs to
          example: kng_abc123xyz789
        type:
          type: string
          enum:
            - query
          description: Type of the workflow
          example: query
        description:
          type: string
          description: Short description of what the workflow is comprised of
          example: Workflow for processing and analyzing fintech companies
        context_id:
          type: string
          description: Context ID used in case of thread mode for chat based workflows
          example: ctx_abc123xyz78910
        advanced_reasoning:
          type: boolean
          description: Flag to enable advanced reasoning for the workflow
          example: true
        model:
          type: string
          description: LLM to use for the query
          enum:
            - 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
    WorkflowResponse:
      type: object
      properties:
        id:
          type: string
          description: Alphanumeric 14 character string identifier
          example: wfl_abc123xyz78910
        name:
          type: string
          description: Name of the workflow
          example: Fintech Companies
        query:
          type: string
          description: The query to ask the knowledge engine
          example: What is the latest revenue of Square?
        response:
          type: string
          description: The response from the knowledge engine
          example: Square's latest revenue is $1.2 billion
        context_id:
          type: string
          description: Context ID used in case of thread mode for chat based workflows
          example: ctx_abc123xyz78910
        advanced_reasoning:
          type: boolean
          description: Flag to enable advanced reasoning for the workflow
          example: true
        model:
          type: string
          description: LLM to use for the query
          enum:
            - 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:
          type: array
          description: >-
            List of citations referenced in the response, or null if no
            citations are available
          items:
            type: object
            properties:
              citation_key:
                type: string
                description: Key used to reference this citation in the response
                example: <source_id=1>
              data_source_id:
                type: string
                description: ID of the data source containing this citation
                example: dsc_n5kdefxua5fnrd
              file_name:
                type: string
                description: Name of the source file
                example: report.pdf
              page_number:
                type: integer
                description: Page number where the citation appears
                example: 4
        status:
          type: string
          enum:
            - PROCESSING
            - PROCESSED
          description: Current status of the workflow
          example: PROCESSED
        created_at:
          type: integer
          format: int64
          description: Unix timestamp when this entity was created
          example: 1679644800
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
          example: >-
            Invalid knowledge engine name: exceeds maximum length of 50
            characters

````