API Reference

Overview

The Workflow86 Public API allows you to programmatically run workflows and interact with your Workflow86 components. This REST API uses JSON for request and response bodies and standard HTTP response codes.

Base URL: https://rest.workflow86.com

API Version: 1.0.0

OpenAPI Specification: For the complete OpenAPI 3.0 specification, see https://rest.workflow86.com/v3/api-docs

Authentication

All API requests require authentication using an API key. API keys can be generated by organization admins from the Organization Settings page.

API Key Header

Include your API key in the x-api-key header with every request:

x-api-key: your-api-key-here

Endpoints

Run Workflow

Runs a workflow component with specified parameters.

Endpoint: POST /v1/workflow/run

Content-Type: application/json

Request Body

Field	Type	Required	Description
workflowId	string	Yes	UUID identifier of the workflow to run
componentId	string	Yes	UUID identifier of the component to start running from
mode	string	No	Production or Test Mode. Values: PROD, TEST
placeholderValues	object	No	Object containing placeholder keys and values

Placeholder Values

The placeholderValues object allows you to pass data to your workflow:

• Keys must be from the set of placeholders available to the specified component
• All keys are optional at the API level, but omitting them may cause the workflow to fail
• Values are validated against the placeholder type
• DateTime placeholders must be in ISO-8601 format (timezone/offset/time portion may be omitted)
• List placeholders can be sent as JSON List or Bracketed String format
• Object values should use dotted notation instead of nested objects

Example Request

{
  "workflowId": "3fa85f64-5717-4562-b3fc-2c960000afa6",
  "componentId": "3fa85f64-5717-4562-b3fc-2c960000afa6",
  "mode": "PROD",
  "placeholderValues": {
    "aDate": "2025-05-27",
    "aDateTime": "2025-05-27T23:04:16Z",
    "aOffsetDateTime": "2025-05-27T23:04:16−12:00",
    "aDateTimeWithTimeZone": "2025-05-27T23:04:16−12:00[Australia/Sydney]",
    "aJsonList": ["blue", "green", "black"],
    "aBracketedString": "[blue,green,black]",
    "aDottedField.answer": "input"
  }
}

Success Response (200 OK)

{
  "workflowId": "5fc4c4f9-cef0-44d5-861c-c0af00008b28",
  "componentId": "e1170860-0b58-44d7-8e21-49fb00009c7f",
  "placeholderValues": {
    "key": "value"
  },
  "sessionId": "3aa378d1-c45f-448f-b543-d5490000742a"
}

Response Fields:

Field	Type	Description
workflowId	string	UUID identifier of the workflow started (echoed from request)
componentId	string	UUID identifier of the component started (echoed from request)
placeholderValues	object	Normalized values of the placeholders provided in the input
sessionId	string	UUID identifier of the session started

Error Handling

All errors follow a standard format and include an error ID for support requests.

Error Response Format

{
  "httpStatus": 400,
  "errorId": "383eeb2e-0a38-4005-a102-dd1500004c1d",
  "message": "Workflow ID is required"
}

HTTP Status Codes

Status Code	Description	Common Causes
400	Bad Request	General validation errors (e.g., missing required fields)
401	Unauthorized	No API Key header provided
403	Forbidden	Invalid or deleted API Key
410	Gone	Workflow or Component ID not found or deleted
500	Internal Server Error	Unexpected errors and system outages

Error Examples

400 - Bad Request

{
  "httpStatus": 400,
  "errorId": "383eeb2e-0a38-4005-a102-dd1500004c1d",
  "message": "Workflow ID is required"
}

401 - Unauthorized

{
  "httpStatus": 401,
  "errorId": "383eeb2e-0a38-4005-a102-dd1500004c1d",
  "message": "Unauthorized"
}

403 - Forbidden

{
  "httpStatus": 403,
  "errorId": "383eeb2e-0a38-4005-a102-dd1500004c1d",
  "message": "Permission Denied"
}

410 - Gone

{
  "httpStatus": 410,
  "errorId": "383eeb2e-0a38-4005-a102-dd1500004c1d",
  "message": "Entity 'x' not found"
}

500 - Internal Server Error

{
  "httpStatus": 500,
  "errorId": "383eeb2e-0a38-4005-a102-dd1500004c1d",
  "message": "Cripes! Something's gone wrong. If the problem persists please quote: 383eeb2e-0a38-4005-a102-dd1500004c1d"
}

Complete Example

Here's a complete example using curl:

curl -X POST https://rest.workflow86.com/v1/workflow/run \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{
    "workflowId": "3fa85f64-5717-4562-b3fc-2c960000afa6",
    "componentId": "3fa85f64-5717-4562-b3fc-2c960000afa6",
    "mode": "PROD",
    "placeholderValues": {
      "customerName": "John Doe",
      "orderDate": "2025-01-15",
      "items": ["widget", "gadget"]
    }
  }'

Support

If you encounter errors, please quote the errorId from the error response when contacting support. This helps our team quickly identify and resolve issues.