Workflow Rules

The /workflows/rules endpoint allows you to manage your Workflow Rules. A Workflow Rule defines an automated action that is triggered when a specific event occurs. For example, you can create a Workflow Rule that automatically transcribes an audio file when it is uploaded to the platform.

Workflow Rules DSL

Workflow Rules are defined using a DSL (Domain Specific Language) that is based on JSON. The DSL allows you to define the following:

The name of the rule.
The description (optional) of the rule.
The endpoint of the workflow to be executed.
The input_type of the rule, which can be single, multiple, or none.
The match criteria, which is a JSON object that defines the events that will trigger the rule.
The config for the workflow, which is a JSON object that contains the parameters to be passed to the workflow.
The task_queue (optional), which specifies the task queue name to use when starting workflows for this rule.
The debug flag (optional), which enables debug mode for the rule.
The customer_override flag (optional), which when set to true prevents the system from auto-updating the rule.

Example Workflow Rule

{
  "name": "Transcribe Audio",
  "description": "Automatically transcribe audio files when uploaded",
  "endpoint": "transcribe_audio",
  "input_type": "single",
  "match": {
    "event.name": "create",
    "event.data.type.name": "Audio"
  },
  "config": {
    "language": "en-US"
  },
  "task_queue": "transcription-queue"
}

This rule will be triggered when a new ContentObject of type "Audio" is created. The transcribe_audio workflow will be executed with the language parameter set to en-US and routed to the transcription-queue task queue.

Match Field Syntax

The match field uses MongoDB query syntax against the event object structure:

event.name - The event type (create, update, delete, etc.)
event.data.type.name - The ContentObject type name
event.data.type.id - The ContentObject type ID (alternative to name)
event.data.properties.* - Match on ContentObject properties
event.data.content.type - Match on MIME type (e.g., {"$regex": "^image"} for images)

Create a Workflow Rule

Endpoint: /workflows/rules

Method: POST

Requirements: User must have workflow:admin permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`
`Content-Type`	`application/json`

Input Parameters

Parameter	Data Type	Description
name (Required)	`string`	The name of the workflow rule.
endpoint (Required)	`string`	The endpoint of the workflow to be executed.
description	`string`	Optional description of the workflow rule.
input_type	`WorkflowRuleInputType`	The input type of the rule. Values: `single`, `multiple`, `none`. Defaults to `single`.
match	`Record<string, any>`	The match criteria for the rule using MongoDB query syntax.
config	`Record<string, any>`	The configuration parameters to pass to the workflow.
task_queue	`string`	The task queue name to use when starting workflows for this rule.
tags	`string[]`	Optional array of categorization tags.
debug	`boolean`	Enable debug mode for the rule. Defaults to `false`.
customer_override	`boolean`	When `true`, prevents the system from auto-updating the rule. Defaults to `false`.

Example Request

{
  "name": "Transcribe Audio",
  "description": "Automatically transcribe audio files",
  "endpoint": "transcribe_audio",
  "input_type": "single",
  "match": {
    "event.name": "create",
    "event.data.type.name": "Audio"
  },
  "config": {
    "language": "en-US"
  },
  "tags": ["audio", "transcription"]
}

Example Response

{
  "id": "<RULE_ID>",
  "name": "Transcribe Audio",
  "description": "Automatically transcribe audio files",
  "endpoint": "transcribe_audio",
  "input_type": "single",
  "match": {
    "event.name": "create",
    "event.data.type.name": "Audio"
  },
  "config": {
    "language": "en-US"
  },
  "tags": ["audio", "transcription"],
  "debug": false,
  "customer_override": false,
  "created_by": "user:<USER_ID>",
  "updated_by": "user:<USER_ID>",
  "created_at": "2023-10-26T15:12:42.202Z",
  "updated_at": "2023-10-26T15:12:42.202Z"
}

Code Example

Create Workflow Rule

curl --location 'https://api.vertesia.io/api/v1/workflows/rules' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--request POST \
--data-raw '{
    "name": "Transcribe Audio",
    "description": "Automatically transcribe audio files",
    "endpoint": "transcribe_audio",
    "input_type": "single",
    "match": {
        "event.name": "create",
        "event.data.type.name": "Audio"
    },
    "config": {
        "language": "en-US"
    }
}'

Retrieve a Workflow Rule

Endpoint: /workflows/rules/<RULE_ID>

Method: GET

Requirements: User must be authenticated.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Description
`<RULE_ID>`	(Required) The ID of the workflow rule to retrieve.

Example Request

There is no JSON body with this request.

Example Response

{
  "id": "<RULE_ID>",
  "name": "Transcribe Audio",
  "description": "Automatically transcribe audio files",
  "endpoint": "transcribe_audio",
  "input_type": "single",
  "match": {
    "event.name": "create",
    "event.data.type.name": "Audio"
  },
  "config": {
    "language": "en-US"
  },
  "task_queue": "transcription-queue",
  "tags": ["audio", "transcription"],
  "debug": false,
  "customer_override": false,
  "created_by": "user:<USER_ID>",
  "updated_by": "user:<USER_ID>",
  "created_at": "2023-10-26T15:12:42.202Z",
  "updated_at": "2023-10-26T15:12:42.202Z"
}

Code Example

Retrieve Workflow Rule

curl --location 'https://api.vertesia.io/api/v1/workflows/rules/<RULE_ID>' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--request GET

Update a Workflow Rule

Endpoint: /workflows/rules/<RULE_ID>

Method: PUT

Requirements: User must be authenticated.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`
`Content-Type`	`application/json`

Path Parameters

Parameter	Description
`<RULE_ID>`	(Required) The ID of the workflow rule to update.

Input Parameters

Parameter	Data Type	Description
name	`string`	The name of the workflow rule.
description	`string`	Description of the workflow rule.
endpoint	`string`	The endpoint of the workflow to be executed.
input_type	`WorkflowRuleInputType`	The input type of the rule. Values: `single`, `multiple`, `none`.
match	`Record<string, any>`	The match criteria for the rule using MongoDB query syntax.
config	`Record<string, any>`	The configuration parameters to pass to the workflow.
task_queue	`string`	The task queue name to use when starting workflows for this rule.
tags	`string[]`	Array of categorization tags.
debug	`boolean`	Enable debug mode for the rule.
customer_override	`boolean`	When `true`, prevents the system from auto-updating the rule.

Example Request

{
  "name": "Transcribe Audio",
  "endpoint": "transcribe_audio",
  "input_type": "single",
  "match": {
    "event.name": "create",
    "event.data.type.name": "Audio"
  },
  "config": {
    "language": "fr-FR"
  }
}

Example Response

{
  "id": "<RULE_ID>",
  "name": "Transcribe Audio",
  "description": "Automatically transcribe audio files",
  "endpoint": "transcribe_audio",
  "input_type": "single",
  "match": {
    "event.name": "create",
    "event.data.type.name": "Audio"
  },
  "config": {
    "language": "fr-FR"
  },
  "task_queue": "transcription-queue",
  "debug": false,
  "customer_override": false,
  "created_by": "user:<USER_ID>",
  "updated_by": "user:<USER_ID>",
  "created_at": "2023-10-26T15:12:42.202Z",
  "updated_at": "2023-10-26T15:17:12.934Z"
}

Code Example

Update Workflow Rule

curl --location 'https://api.vertesia.io/api/v1/workflows/rules/<RULE_ID>' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--request PUT \
--data-raw '{
    "name": "Transcribe Audio",
    "endpoint": "transcribe_audio",
    "input_type": "single",
    "match": {
        "event.name": "create",
        "event.data.type.name": "Audio"
    },
    "config": {
        "language": "fr-FR"
    }
}'

Delete a Workflow Rule

Endpoint: /workflows/rules/<RULE_ID>

Method: DELETE

Requirements: User must be authenticated.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Description
`<RULE_ID>`	(Required) The ID of the workflow rule to delete.

Example Request

There is no JSON body with this request.

Example Response

{
    "id": "<RULE_ID>",
    "count": 1
}

Code Example

Delete Workflow Rule

curl --location 'https://api.vertesia.io/api/v1/workflows/rules/<RULE_ID>' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--request DELETE

List Workflow Rules

Endpoint: /workflows/rules

Method: GET

Requirements: User must be authenticated.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Example Request

There is no JSON body with this request.

Example Response

[
  {
    "id": "<RULE_ID_1>",
    "name": "Transcribe Audio",
    "description": "Automatically transcribe audio files",
    "endpoint": "transcribe_audio",
    "input_type": "single",
    "match": {
      "event.name": "create",
      "event.data.type.name": "Audio"
    },
    "config": {
      "language": "en-US"
    },
    "task_queue": "transcription-queue",
    "debug": false,
    "customer_override": false,
    "created_by": "user:<USER_ID>",
    "updated_by": "user:<USER_ID>",
    "created_at": "2023-10-26T15:12:42.202Z",
    "updated_at": "2023-10-26T15:12:42.202Z"
  },
  {
    "id": "<RULE_ID_2>",
    "name": "Generate Embeddings",
    "endpoint": "generate_embeddings",
    "input_type": "multiple",
    "match": {
      "event.name": "create",
      "event.data.type.name": "Document"
    },
    "config": {
      "embeddingType": "text"
    },
    "debug": false,
    "customer_override": false,
    "created_by": "user:<USER_ID>",
    "updated_by": "user:<USER_ID>",
    "created_at": "2023-10-26T15:13:23.971Z",
    "updated_at": "2023-10-26T15:13:23.971Z"
  }
]

Code Example

List Workflow Rules

curl --location 'https://api.vertesia.io/api/v1/workflows/rules' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--request GET

Execute Workflow Rule

Endpoint: /workflows/rules/<RULE_ID>/execute

Method: POST

Requirements: User must have workflow:run permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`
`Content-Type`	`application/json`

Path Parameters

Parameter	Description
`<RULE_ID>`	(Required) The ID of the workflow rule to execute.

Input Parameters

Parameter	Data Type	Description
vars	`Record<string, any>`	Parameters to pass to the workflow. These will be merged with the rule's config.
objectIds	`string[]`	Array of document IDs to process.

Example Request

{
  "vars": {
    "custom_param": "value"
  },
  "objectIds": ["doc123"]
}

Example Response

{
  "runId": "<WORKFLOW_RUN_ID>",
  "workflowId": "<WORKFLOW_ID>"
}

Note: When executing via a rule, the workflow receives the rule's configuration merged with any additional vars provided in the request. The rule's config properties are applied first, then overlaid with the request vars.

Code Example

Execute Workflow Rule

curl --location 'https://api.vertesia.io/api/v1/workflows/rules/<RULE_ID>/execute' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--request POST \
--data-raw '{
  "vars": {
    "custom_param": "value"
  },
  "objectIds": ["doc123"]
}'

List Runs for a Workflow Rule

Endpoint: /workflows/rules/<RULE_ID>/runs

Method: GET

Requirements: User must have workflow:admin permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Description
`<RULE_ID>`	(Required) The ID of the workflow rule.

Note: This endpoint returns workflow runs filtered by the specific rule ID. The response format matches the List Workflow Runs endpoint with automatic filtering by rule_id.

Example Response

{
  "runs": [
    {
      "status": "COMPLETED",
      "started_at": 1678886400,
      "closed_at": 1678886460,
      "execution_duration": 60,
      "run_id": "<RUN_ID>",
      "workflow_id": "<WORKFLOW_ID>",
      "type": "StandardContentIngestion",
      "initiated_by": "user:123",
      "vertesia_workflow_type": "Transcribe Audio"
    }
  ],
  "next_page_token": "base64EncodedToken",
  "has_more": false
}

Code Example

List Runs for Workflow Rule

curl --location 'https://api.vertesia.io/api/v1/workflows/rules/<RULE_ID>/runs' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--request GET