API Overview

Base Path
/workflow
Authentication
API Key via X-API-KEY header
Content Types
  • Request: application/yaml (definitions), application/json (executions)
  • Response: application/json, application/yaml, application/problem+json

Workflow Definitions Endpoints

GET /api/definitions

List all workflow definitions with pagination.

Parameters:

  • cursor - Pagination cursor
  • limit - Results per page (1-100, default: 20)
curl -X 'GET' \
  'https://app.yworkflow.com/api/definitions?limit=20' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: wkf_123456789012'

POST /api/definitions

Create a new workflow definition. If ID exists, creates a new version.

curl -X 'POST' \
  'https://app.yworkflow.com/api/definitions' \
  -H 'accept: */*' \
  -H 'X-API-KEY: wkf_123456789012' \
  -H 'Content-Type: application/yaml' \
  --data-binary @workflow.yml

Errors: 400 (Bad Request), 409 (Conflict), 422 (Unprocessable Entity)

GET /api/definitions/{workflowDefinitionId}

Retrieve a specific workflow definition.

Accept Header:application/yaml or application/json

curl -X 'GET' \
  'https://app.yworkflow.com/api/definitions/leave-request' \
  -H 'accept: application/yaml' \
  -H 'X-API-KEY: wkf_123456789012'

PUT /api/definitions/{workflowDefinitionId}

Create or update a workflow definition (upsert). Path ID takes precedence over body ID.

DELETE /api/definitions/{workflowDefinitionId}

Delete a workflow definition. Returns 204 (No Content) on success.

GET /api/definitions/{workflowDefinitionId}/versions

List version history for a workflow definition. Returns array of WorkflowSummary objects.

Workflow Executions Endpoints

GET /api/executions

List all workflow executions with pagination.

curl -X 'GET' \
  'https://app.yworkflow.com/api/executions?limit=20' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: wkf_123456789012'

POST /api/executions

Start a new workflow instance.

curl -X 'POST' \
  'https://app.yworkflow.com/api/executions' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: wkf_123456789012' \
  -H 'Content-Type: application/json' \
  -d '{
  "definitionId": "leave-request",
  "version": "v1",
  "input": {}
}'

Errors: 400 (Bad Request), 404 (Not Found), 422 (Unprocessable Entity)

GET /api/executions/{executionId}

Get execution status and details, including current states and available transitions.

curl -X 'GET' \
  'https://app.yworkflow.com/api/executions/{executionId}' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: wkf_123456789012'

POST /api/executions/{executionId}/transitions

Trigger a transition to move the workflow from current state to next state.

curl -X 'POST' \
  'https://app.yworkflow.com/api/executions/{executionId}/transitions' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: wkf_123456789012' \
  -H 'Content-Type: application/json' \
  -d '{
  "transitionId": "submit",
  "inputs": {}
}'

Errors: 400 (Bad Request), 404 (Not Found), 409 (Conflict)

Data Models

ExecutionResponse

{
  "id": "string",
  "definitionId": "string",
  "version": "string",
  "status": "created" | "started" | "processing" | "stopped" | "killed" | "completed",
  "inputs": {},
  "currentStates": ["string"],
  "availableTransitions": ["string"]
}

ProblemDetail (Error Response)

All errors follow RFC 9457 Problem Detail format:

{
  "type": "string (URI)",
  "title": "string",
  "status": "integer",
  "detail": "string",
  "instance": "string (URI)",
  "additionalProperties": {}
}

Error Handling

400 Bad Request

Malformed request or transition logic error

404 Not Found

Resource doesn't exist

409 Conflict

State conflict (e.g., workflow locked, definition conflict)

422 Unprocessable Entity

Validation failed (input doesn't match schema)

503 Service Unavailable

Maintenance mode

Authentication

All API endpoints require authentication via API Key:

  • Include your API key in the X-API-KEY header
  • API keys are obtained from the frontend API Keys tab
  • Keys are organization-scoped
  • All endpoints require authentication except public documentation
curl -H "X-API-KEY: wkf_123456789012" \
  https://app.yworkflow.com/api/definitions

Interactive Documentation

For the most up-to-date API documentation with interactive testing capabilities, visit the Swagger UI:

Open Swagger UI

Tip: From the API keys creation page, there's a link to Swagger UI that automatically configures your API key.

Previous: Organization Management Back to App Documentation