Workflows

Workflows are automated sequences of steps that can be triggered in multiple ways. On this page, we'll dive into the different workflow endpoints you can use to manage workflows programmatically. We'll look at how to query, create, update, delete, and run workflows.

Workflows can also be managed with Terraform using the official provider: https://registry.terraform.io/providers/devhub-tools/devhub/latest/docs/resources/workflow

The workflow model

The workflow model contains all the information about your workflows, such as their name, inputs, steps, and trigger configuration. It also contains references to the organization and any associated Linear labels.

Properties

Name
id
Type
string
Description
Unique identifier for the workflow.
Name
name
Type
string
Description
The name of the workflow.
Name
cron_schedule
Type
string
Description
A cron expression evaluated using UTC time to trigger the workflow (e.g. 0 0 * * *).
Name
trigger_linear_label
Type
object
Description
The Linear label that should trigger the workflow.
Name
inputs
Type
array
Description
Array of input definitions for the workflow.
Name
key
Type
string
Description
The key for this input.
Name
description
Type
string
Description
A description of what this input is for.
Name
type
Type
string
Description
The type of this input (string, float, integer, boolean).
Name
steps
Type
array
Description
Array of workflow steps to execute.
Name
id
Type
string
Description
Unique identifier for the step.
Name
name
Type
string
Description
The name of the step.
Name
condition
Type
string
Description
Expression to evaluate if this step should run. If evaluated as true step will run, otherwise it will be skipped.
Name
action
Type
object
Description
The action to perform in this step (api, approval, condition, query, slack, slack_reply).
Name
permissions
Type
array
Description
Array of permissions for approval steps.
Name
created_at
Type
timestamp
Description
Timestamp of when the workflow was created.
Name
updated_at
Type
timestamp
Description
Timestamp of when the workflow was last updated.

POST/api/v1/workflows

Create a workflow

This endpoint allows you to create a new workflow in your organization.

Required attributes

Name
name
Type
string
Description
The name of the workflow.

Optional attributes

Name
cron_schedule
Type
string
Description
A cron expression evaluated using UTC time to trigger the workflow.
Name
trigger_linear_label
Type
object
Description
The Linear label that should trigger the workflow.
Name
inputs
Type
array
Description
Array of input definitions for the workflow.
Name
steps
Type
array
Description
Array of workflow steps to execute.

Request

POST

/api/v1/workflows

curl https://api.devhub.sh/api/v1/workflows \
  -H "x-api-key: dh_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Workflow",
    "trigger_linear_label": {
      "name": "deploy"
    },
    "inputs": [
      {
        "key": "user_id",
        "description": "User ID",
        "type": "string"
      }
    ],
    "steps": [
      {
        "name": "approval",
        "action": {
          "reviews_required": 1,
          "__type__": "approval"
        }
      }
    ]
  }'

Response

{
  "id": "wf_xxx",
  "name": "My Workflow",
  "cron_schedule": null,
  "trigger_linear_label": {
    "id": "lin_lbl_xxx",
    "name": "deploy"
  },
  "inputs": [
    {
      "key": "user_id",
      "description": "User ID",
      "type": "string"
    }
  ],
  "steps": [
    {
      "id": "wfs_xxx",
      "name": "approval",
      "condition": null,
      "action": {
        "reviews_required": 1,
        "__type__": "approval"
      },
      "permissions": []
    }
  ]
}

GET/api/v1/workflows/:id

Retrieve a workflow

This endpoint allows you to retrieve a workflow by providing its ID.

Request

GET

/api/v1/workflows/wf_xxx

curl https://api.devhub.sh/api/v1/workflows/wf_xxx \
  -H "x-api-key: dh_xxx"

Response

{
  "id": "wf_xxx",
  "name": "My Workflow",
  "cron_schedule": "0 0 * * *",
  "trigger_linear_label": {
    "id": "lin_lbl_xxx",
    "name": "deploy"
  },
  "inputs": [
    {
      "key": "user_id",
      "description": "User ID",
      "type": "string"
    }
  ],
  "steps": [
    {
      "id": "wfs_xxx",
      "name": "approval",
      "condition": "true",
      "action": {
        "reviews_required": 1,
        "__type__": "approval"
      },
      "permissions": []
    }
  ]
}

PATCH/api/v1/workflows/:id

Update a workflow

This endpoint allows you to update an existing workflow.

Optional attributes

Name
name
Type
string
Description
The name of the workflow.
Name
cron_schedule
Type
string
Description
A cron expression evaluated using UTC time to trigger the workflow.
Name
trigger_linear_label
Type
object
Description
The Linear label that should trigger the workflow.
Name
inputs
Type
array
Description
Array of input definitions for the workflow.
Name
steps
Type
array
Description
Array of workflow steps to execute.

Request

PATCH

/api/v1/workflows/wf_xxx

curl -X PATCH https://api.devhub.sh/api/v1/workflows/wf_xxx \
  -H "x-api-key: dh_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Workflow",
    "steps": [
      {
        "name": "slack",
        "action": {
          "slack_channel": "#reviews",
          "message": "Please review this",
          "link_text": "Review",
          "__type__": "slack"
        }
      }
    ]
  }'

Response

{
  "id": "wf_xxx",
  "name": "Updated Workflow",
  "cron_schedule": "0 0 * * *",
  "trigger_linear_label": {
    "id": "lin_lbl_xxx",
    "name": "deploy"
  },
  "inputs": [
    {
      "key": "user_id",
      "description": "User ID",
      "type": "string"
    }
  ],
  "steps": [
    {
      "id": "wfs_xxx",
      "name": "slack",
      "condition": null,
      "action": {
        "slack_channel": "#reviews",
        "message": "Please review this",
        "link_text": "Review",
        "__type__": "slack"
      },
      "permissions": []
    }
  ]
}

DELETE/api/v1/workflows/:id

Delete a workflow

This endpoint allows you to delete a workflow from your organization.

Request

DELETE

/api/v1/workflows/wf_xxx

curl -X DELETE https://api.devhub.sh/api/v1/workflows/wf_xxx \
  -H "x-api-key: dh_xxx"

POST/api/v1/workflows/:id/run

Run a workflow

This endpoint allows you to manually trigger a workflow execution with the provided inputs.

Required attributes

Name
inputs
Type
object
Description
The input values for the workflow execution.

Request

POST

/api/v1/workflows/wf_xxx/run

curl https://api.devhub.sh/api/v1/workflows/wf_xxx/run \
  -H "x-api-key: dh_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "123"
  }'

Response

workflow started