Skip to main content
A workflow definition is a reusable template that describes a processing pipeline — what sources to read from, what instructions to follow, where to write output, and how to run it. When you invoke a definition it produces a Workflow Run. Workflow definitions use a self-hosted runner model: you provide the runner URL and a webhook secret, and Knowledge Stack calls your runner when a workflow is triggered.

​
Create definition

Creates a new workflow definition. 
POST https://api-staging.knowledgestack.ai/v1/workflow-definitions
​
name
string
required
Display name for the definition (up to 255 characters).
​
description
string
Optional description.
​
runner_type
string
required
The runner that will execute the workflow. Currently the only supported value is SELF_HOSTED.
​
runner_config
object
Configuration for the self-hosted runner.
​
source_path_part_ids
string[]
required
UUIDs of path parts (folders or documents) that serve as the workflow’s input sources. Between 1 and 20 items.
​
instruction_path_part_ids
string[]
required
UUIDs of path parts containing the instructions or prompts the workflow uses. Between 1 and 20 items.
​
output_path_part_ids
string[]
required
UUIDs of path parts where the workflow writes its output. Between 1 and 20 items.
​
template_path_part_id
string
UUID of an optional template path part.
​
max_run_duration_seconds
integer
Maximum number of seconds a single run may take before timing out. Between 60 and 86400 (24 hours). Defaults to 300.
Example 
curl -X POST https://api-staging.knowledgestack.ai/v1/workflow-definitions \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Document Summarizer",
    "description": "Summarizes documents from the source folder into the output folder",
    "runner_type": "SELF_HOSTED",
    "runner_config": {
      "url": "https://runner.example.com/webhook",
      "webhook_secret": "your-webhook-secret"
    },
    "source_path_part_ids": ["src-path-uuid-..."],
    "instruction_path_part_ids": ["instr-path-uuid-..."],
    "output_path_part_ids": ["out-path-uuid-..."],
    "max_run_duration_seconds": 600
  }'
Response — WorkflowDefinitionResponse
​
id
string
UUID of the workflow definition.
​
name
string
Display name.
​
description
string | null
Optional description.
​
runner_type
string
Runner type. Currently always SELF_HOSTED.
​
runner_config
object | null
Response-safe runner configuration. The webhook_secret is never returned.
​
source_path_part_ids
string[]
UUIDs of source path parts.
​
instruction_path_part_ids
string[]
UUIDs of instruction path parts.
​
output_path_part_ids
string[]
UUIDs of output path parts.
​
template_path_part_id
string | null
UUID of the template path part, if set.
​
max_run_duration_seconds
integer
Timeout for each run in seconds.
​
is_active
boolean
Whether the definition can be invoked. Inactive definitions reject new runs.
​
created_at
string
ISO 8601 timestamp of creation.
​
updated_at
string
ISO 8601 timestamp of the last update.

​
List definitions

Returns all workflow definitions in the current tenant. 
GET https://api-staging.knowledgestack.ai/v1/workflow-definitions
​
page
integer
Page number (1-indexed).
​
page_size
integer
Number of results per page.
Example 
curl https://api-staging.knowledgestack.ai/v1/workflow-definitions \
  -H "Authorization: Bearer <your-api-key>"
Response — PaginatedResponse[WorkflowDefinitionResponse]

​
Get definition

Returns a single workflow definition. 
GET https://api-staging.knowledgestack.ai/v1/workflow-definitions/{definition_id}
​
definition_id
string
required
UUID of the workflow definition.
Example 
curl https://api-staging.knowledgestack.ai/v1/workflow-definitions/def-uuid-... \
  -H "Authorization: Bearer <your-api-key>"
Response — WorkflowDefinitionResponse

​
Update definition

Fully replaces a workflow definition. This is a PUT operation — all required fields must be included even if you only want to change one. 
PUT https://api-staging.knowledgestack.ai/v1/workflow-definitions/{definition_id}
​
definition_id
string
required
UUID of the workflow definition to update.
​
name
string
required
Display name (up to 255 characters).
​
description
string
Optional description.
​
runner_type
string
required
Runner type. Currently only SELF_HOSTED.
​
runner_config
object
Self-hosted runner configuration (url and webhook_secret).
​
source_path_part_ids
string[]
required
Replacement list of source path part UUIDs (1–20 items).
​
instruction_path_part_ids
string[]
required
Replacement list of instruction path part UUIDs (1–20 items).
​
output_path_part_ids
string[]
required
Replacement list of output path part UUIDs (1–20 items).
​
template_path_part_id
string
UUID of the template path part.
​
max_run_duration_seconds
integer
Timeout in seconds (60–86400). Defaults to 300.
​
is_active
boolean
Set to false to prevent new runs from being triggered. Defaults to true.
Example 
curl -X PUT https://api-staging.knowledgestack.ai/v1/workflow-definitions/def-uuid-... \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Document Summarizer v2",
    "runner_type": "SELF_HOSTED",
    "runner_config": {"url": "https://runner.example.com/webhook", "webhook_secret": "secret"},
    "source_path_part_ids": ["src-path-uuid-..."],
    "instruction_path_part_ids": ["instr-path-uuid-..."],
    "output_path_part_ids": ["out-path-uuid-..."],
    "is_active": true
  }'
Response — WorkflowDefinitionResponse

​
Delete definition

Permanently deletes a workflow definition. Existing run records are not deleted. 
DELETE https://api-staging.knowledgestack.ai/v1/workflow-definitions/{definition_id}
​
definition_id
string
required
UUID of the workflow definition to delete.
Example 
curl -X DELETE https://api-staging.knowledgestack.ai/v1/workflow-definitions/def-uuid-... \
  -H "Authorization: Bearer <your-api-key>"

​
Invoke workflow

Triggers a new run of a workflow definition. Returns a workflow run object. 
POST https://api-staging.knowledgestack.ai/v1/workflow-definitions/{definition_id}/invoke
​
definition_id
string
required
UUID of the workflow definition to invoke.
​
idempotency_key
string
An optional string (up to 255 characters) that prevents duplicate runs. If you retry a request with the same key, the API returns the original run instead of creating a new one.
Example 
curl -X POST https://api-staging.knowledgestack.ai/v1/workflow-definitions/def-uuid-.../invoke \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"idempotency_key": "run-2026-04-04-001"}'
Response — WorkflowRunResponse See Workflow Runs for the full response field reference.

​
List runs for definition

Returns all runs associated with a specific workflow definition. 
GET https://api-staging.knowledgestack.ai/v1/workflow-definitions/{definition_id}/runs
​
definition_id
string
required
UUID of the workflow definition.
​
page
integer
Page number (1-indexed).
​
page_size
integer
Number of results per page.
Example 
curl https://api-staging.knowledgestack.ai/v1/workflow-definitions/def-uuid-.../runs \
  -H "Authorization: Bearer <your-api-key>"
Response — PaginatedResponse[WorkflowRunResponse]