Skip to main content
A workflow run is a single execution of a workflow definition. Runs track lifecycle status, a snapshot of the configuration at trigger time, and any errors that occurred. This page also covers document version ingestion workflows — dedicated pipelines that track how documents are processed into the knowledge base.

​
WorkflowRunStatus values

ValueDescription
PENDINGThe run has been created but not yet started.
RUNNINGThe runner is actively executing the workflow.
COMPLETEDThe workflow finished successfully.
FAILEDThe workflow encountered an unrecoverable error.

​
WorkflowRunnerType values

ValueDescription
SELF_HOSTEDThe workflow runs on your own self-hosted runner.

​
Get run

Returns the current state of a single workflow run. 
GET https://api-staging.knowledgestack.ai/v1/workflow-runs/{run_id}
​
run_id
string
required
UUID of the workflow run.
Example 
curl https://api-staging.knowledgestack.ai/v1/workflow-runs/run-uuid-... \
  -H "Authorization: Bearer <your-api-key>"
Response — WorkflowRunResponse
​
id
string
UUID of the run.
​
workflow_definition_id
string
UUID of the workflow definition that produced this run.
​
user_id
string
UUID of the user who triggered the run.
​
runner_type
string
The runner that executed this run. Currently always SELF_HOSTED.
​
status
string
Current lifecycle status. One of PENDING, RUNNING, COMPLETED, FAILED.
​
started_at
string
ISO 8601 timestamp when execution began.
​
completed_at
string | null
ISO 8601 timestamp when execution finished. null if still in progress.
​
run_snapshot
object
A frozen copy of the workflow configuration captured at trigger time, including sources, instructions, outputs, and template. This ensures the run record is self-contained even if the definition changes later.
​
error
string | null
Error message if the run failed. null otherwise.
​
created_at
string
ISO 8601 timestamp when the run record was created.
​
updated_at
string
ISO 8601 timestamp of the last status update.

​
Delete run

Deletes the record of a workflow run. This removes the run from the API — it does not cancel an in-progress execution. 
DELETE https://api-staging.knowledgestack.ai/v1/workflow-runs/{run_id}
​
run_id
string
required
UUID of the run to delete.
Example 
curl -X DELETE https://api-staging.knowledgestack.ai/v1/workflow-runs/run-uuid-... \
  -H "Authorization: Bearer <your-api-key>"

​
Run callback

Called by your self-hosted runner to report the outcome of a run. Use this endpoint to signal completion or failure once your runner has finished processing. 
POST https://api-staging.knowledgestack.ai/v1/workflow-runs/{run_id}/callback
​
run_id
string
required
UUID of the run to update.
​
status
string
required
Final status to set on the run. One of COMPLETED or FAILED.
​
error
string
Error description if status is FAILED. Up to 8192 characters.
This endpoint is intended for your self-hosted runner, not for end-user clients. Secure the callback using your runner’s webhook secret.
Example — successful run 
curl -X POST https://api-staging.knowledgestack.ai/v1/workflow-runs/run-uuid-.../callback \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"status": "COMPLETED"}'
Example — failed run 
curl -X POST https://api-staging.knowledgestack.ai/v1/workflow-runs/run-uuid-.../callback \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"status": "FAILED", "error": "Timeout reading source document"}'
Response — WorkflowCallbackResponse

​
List document version ingestion workflows

Returns ingestion workflows for document versions. These track how documents were processed into the knowledge base. 
GET https://api-staging.knowledgestack.ai/v1/workflows/document_versions
​
page
integer
Page number (1-indexed).
​
page_size
integer
Number of results per page.
Example 
curl https://api-staging.knowledgestack.ai/v1/workflows/document_versions \
  -H "Authorization: Bearer <your-api-key>"
Response — PaginatedResponse[WorkflowSummaryResponse]
​
workflow_id
string
Workflow ID for this ingestion job.
​
document_id
string
UUID of the document associated with this ingestion.
​
document_version_id
string
UUID of the document version being ingested.
​
status
string
Ingestion pipeline status. One of pending, processing, completed, failed, cancelled.
​
last_activity
string | null
Description of the last recorded activity.
​
error
string | null
Error message if the ingestion failed.
​
last_run_timestamp
string
ISO 8601 timestamp of the most recent run.
​
last_state_update_timestamp
string | null
ISO 8601 timestamp of the last state change.
​
created_at
string
ISO 8601 timestamp of record creation.

​
Get document version ingestion workflow

Returns detailed information about a specific document version ingestion workflow. 
GET https://api-staging.knowledgestack.ai/v1/workflows/document_versions/{workflow_id}
​
workflow_id
string
required
The workflow ID returned when the ingestion was triggered.
Example 
curl https://api-staging.knowledgestack.ai/v1/workflows/document_versions/<workflow-id> \
  -H "Authorization: Bearer <your-api-key>"
Response — WorkflowDetailResponse Returns all fields from WorkflowSummaryResponse plus:
​
execution_status
string
Live execution status of the ingestion pipeline.
​
start_time
string
ISO 8601 timestamp when the pipeline started.
​
close_time
string | null
ISO 8601 timestamp when the pipeline completed. null if still running.
​
chunks_processed
integer | null
Number of content chunks processed during ingestion.

​
Rerun document version ingestion

Re-triggers the ingestion pipeline for a specific document version. Use this to retry a failed ingestion or reprocess after updating extraction settings. Knowledge Stack reuses the existing uploaded file — no re-upload needed. 
POST https://api-staging.knowledgestack.ai/v1/workflows/document_versions/{workflow_id}
​
workflow_id
string
required
The workflow ID of the ingestion to rerun.
Example 
curl -X POST https://api-staging.knowledgestack.ai/v1/workflows/document_versions/<workflow-id> \
  -H "Authorization: Bearer <your-api-key>"
Response — WorkflowActionResponse

​
Get workflow status

Returns the current execution status of any active workflow by its ID. 
GET https://api-staging.knowledgestack.ai/v1/workflows/{workflow_id}
​
workflow_id
string
required
The workflow ID to query.
Example 
curl https://api-staging.knowledgestack.ai/v1/workflows/<workflow-id> \
  -H "Authorization: Bearer <your-api-key>"
Response — WorkflowStatusResponse
​
workflow_id
string
The workflow ID.
​
execution_status
string
Current execution status of the workflow.
​
start_time
string
ISO 8601 timestamp when the workflow started.
​
close_time
string | null
ISO 8601 timestamp when the workflow completed. null if still running.

​
Cancel workflow

Cancels an in-progress workflow. 
DELETE https://api-staging.knowledgestack.ai/v1/workflows/{workflow_id}
​
workflow_id
string
required
The workflow ID to cancel.
Cancellation is best-effort. If the workflow has already completed or failed it cannot be cancelled. Check the status before cancelling.
Example 
curl -X DELETE https://api-staging.knowledgestack.ai/v1/workflows/<workflow-id> \
  -H "Authorization: Bearer <your-api-key>"
Response — WorkflowCancelResponse