GET

List Workflows

Retrieve all configured workflows with their associated statuses and settings.

Endpoint

HTTP Request

GET /v1/workflows

Authentication

This endpoint requires a valid API key with canViewStatuses permission. The API key must be passed in the X-API-Key header.

Required Header

X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Response

Returns a JSON object with the list of workflows:

200 OK - Success Response

{
  "success": true,
  "data": {
    "workflows": [
      {
        "id": "string",
        "name": "string",
        "description": null,
        "color": "string",
        "order": 0,
        "relationship_type": "string",
        "relationship_configured": true,
        "previous_workflow_id": "string",
        "next_workflow_id": "string",
        "statuses": [
          {
            "id": "string",
            "name": "string",
            "public_name": null,
            "use_public_name": true,
            "display_name": "string",
            "color": "string",
            "order": 0,
            "is_independent": true,
            "is_addon": true
          }
        ],
        "status_count": 0
      }
    ],
    "workflows_enabled": true,
    "enforce_workflow_order": true,
    "workflow_transitions": [
      {
        "from_workflow_id": "string",
        "to_workflow_id": "string",
        "trigger": "string"
      }
    ],
    "summary": {
      "total": 0,
      "total_statuses": 0
    }
  }
}

At 1.5 each workflow also carries relationship fields and the response adds workflow_transitions. Requests with 1.3/1.4 keep the original response.

Response Fields

Root Response Object

Field	Type	Description
`success`	boolean	Always true on a successful response.
`data`	object	The endpoint's payload. Its fields are listed in the tables below.
`workflows`	array	Array of workflow objects
`workflows_enabled`	boolean	Whether multi-workflow mode is active
`enforce_workflow_order`	boolean	Whether workflow order enforcement is active. When true, orders must progress through workflows in sequence and cannot move backwards.
`workflow_transitions`	array	Array of derived one-way workflow handoffs (v1.5 only)
`summary`	object	Summary information including totals

Workflow Object Fields

Field	Type	Description
`id`	string	Unique identifier for the workflow
`name`	string	Display name of the workflow
`description`	string \| null	Optional description of the workflow's purpose
`color`	string	Hex color code for UI display
`order`	number	Display order position (ascending)
`statuses`	array	Array of status objects assigned to this workflow (ordered by order ascending)
`status_count`	number	Number of statuses in this workflow
`relationship_type`	string	sequential or isolated (v1.5 only).
`relationship_configured`	boolean	Whether the shop has an explicit relationship setting (v1.5 only).
`previous_workflow_id`	string \| null	Previous workflow in the chain, or null (v1.5 only).
`next_workflow_id`	string \| null	Next workflow in the chain, or null (v1.5 only).

Status Object Fields (within workflow)

Field	Type	Description
`id`	string	Unique identifier for the status
`name`	string	Display name of the status
`public_name`	string \| null	Public-facing name of the status, or null
`use_public_name`	boolean	Whether to use the public name instead of the internal name
`display_name`	string	The resolved display name (public_name if use_public_name is true, otherwise name)
`color`	string	Hex color code for the status
`order`	number	Position of the status within the workflow sequence
`is_independent`	boolean	Whether this status is independent (not part of the main chain)
`is_addon`	boolean	Whether this status is an addon status

Workflow Transition Object Fields

Field	Type	Description
`from_workflow_id`	string	Workflow the handoff starts from.
`to_workflow_id`	string	Workflow the handoff leads to.
`trigger`	string	What triggers the handoff — on_final_status.

Summary Object Fields

Field	Type	Description
`total`	number	Total number of workflows
`total_statuses`	number	Total number of statuses across all workflows

Examples

Basic Request

cURL Request

curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/workflows" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.5"

Rate Limiting

This endpoint is subject to per-minute and per-day rate limits based on your API key. Rate limit information is returned in the response headers:

X-RateLimit-Limit-Minute: Maximum requests per minute
X-RateLimit-Remaining-Minute: Remaining requests in current minute
X-RateLimit-Reset-Minute: Unix timestamp when minute window resets
X-RateLimit-Limit-Day: Maximum requests per day
X-RateLimit-Remaining-Day: Remaining requests in current day
X-RateLimit-Reset-Day: Unix timestamp when day window resets
Retry-After: Seconds to wait before retrying (when rate limited)

Error Responses

401 Unauthorized

Missing or invalid API key

401 Unauthorized

{
  "success": false,
  "error": "Missing API key. Include it in the X-API-Key header"
}

403 Forbidden

API key lacks required permissions

403 Forbidden

{
  "success": false,
  "error": "Insufficient permissions. Required: canViewStatuses"
}

500 Internal Server Error

Server error occurred

500 Internal Server Error

{
  "success": false,
  "error": "Internal server error",
  "details": {
    "message": "An unexpected error occurred"
  }
}