Workflows API - CloudShip AI

Workflow Definitions

Endpoints for managing workflow definitions.

Method	Endpoint	Description
`POST`	`/api/v1/workflows`	Create a new workflow
`GET`	`/api/v1/workflows`	List all workflows
`GET`	`/api/v1/workflows/:id`	Get workflow by ID
`PUT`	`/api/v1/workflows/:id`	Update workflow (creates new version)
`DELETE`	`/api/v1/workflows/:id`	Disable workflow
`POST`	`/api/v1/workflows/validate`	Validate definition without saving
`GET`	`/api/v1/workflows/:id/versions`	List all versions
`GET`	`/api/v1/workflows/:id/versions/:v`	Get specific version

Create Workflow

Request Body

{
  "workflowId": "incident-rca",
  "name": "Incident Root Cause Analysis",
  "description": "Parallel investigation with synthesis",
  "definition": {
    "id": "incident-rca",
    "start": "investigate",
    "states": [...]
  }
}

Workflow Runs

Endpoints for executing workflows and tracking their progress.

Method	Endpoint	Description
`POST`	`/api/v1/workflow-runs`	Start a new run
`GET`	`/api/v1/workflow-runs`	List runs (filter by `workflow_id`, `status`)
`GET`	`/api/v1/workflow-runs/:id`	Get run status and output
`GET`	`/api/v1/workflow-runs/:id/stream`	SSE stream of run updates
`GET`	`/api/v1/workflow-runs/:id/steps`	List completed steps
`POST`	`/api/v1/workflow-runs/:id/pause`	Pause execution
`POST`	`/api/v1/workflow-runs/:id/resume`	Resume paused run
`POST`	`/api/v1/workflow-runs/:id/cancel`	Cancel run

Start Run

Request Body

{
  "workflowId": "incident-rca",
  "input": {
    "service_name": "payment-service",
    "namespace": "production"
  }
}

Streaming Updates (SSE)

The /api/v1/workflow-runs/:id/stream endpoint provides a server-sent events (SSE) stream of run updates. Events:

run_started: Emitted when the run begins
step_started: Emitted when a step begins execution
step_completed: Emitted when a step finishes
run_completed: Emitted when the entire workflow finishes
run_failed: Emitted if an error occurs

Human Approvals

Endpoints for managing human_approval steps in workflows.

Method	Endpoint	Description
`GET`	`/api/v1/workflow-approvals`	List pending approvals
`GET`	`/api/v1/workflow-approvals/:id`	Get approval details
`POST`	`/api/v1/workflow-approvals/:id/approve`	Approve with optional comment
`POST`	`/api/v1/workflow-approvals/:id/reject`	Reject with reason

Approve Request

Request Body

{
  "comment": "Reviewed and approved for production rollout"
}

Set X-Approver-ID header to identify the approver. Defaults to api-user if not provided.

​Workflow Definitions

​Create Workflow

​Workflow Runs

​Start Run

​Streaming Updates (SSE)

​Human Approvals

​Approve Request

Workflow Definitions

Create Workflow

Workflow Runs

Start Run

Streaming Updates (SSE)

Human Approvals

Approve Request