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 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.

Example Workflow Rule

{
  "name": "Transcribe Audio",
  "endpoint": "transcribe_audio",
  "input_type": "single",
  "match": {
    "event": "create",
    "type": "Audio"
  },
  "config": {
    "language": "en-US"
  },
  "task_queue": "transcription-queue"
}

This rule will be triggered when a new audio file 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.

Create a Workflow Rule

Endpoint: /workflows/rules

Method: POST

Headers

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

Input Parameters

Parameter	Data Type	Description
`name`	`string`	The name of the workflow rule.
`endpoint`	`string`	The endpoint of the workflow to be executed.
`input_type`	`WorkflowRuleInputType`	The input type of the rule.
`match`	`Record<string, any>`	The match criteria for the rule.
`config`	`Record<string, any>`	The configuration for the workflow.
`task_queue`	`string`	(Optional) The task queue name to use when starting workflows for this rule.

Example Request

{
  "name": "Transcribe Audio",
  "endpoint": "transcribe_audio",
  "input_type": "single",
  "match": {
    "event": "create",
    "type": "Audio"
  },
  "config": {
    "language": "en-US"
  }
}

Example Response

{
  "id": "<RULE_ID>",
  "name": "Transcribe Audio",
  "endpoint": "transcribe_audio",
  "input_type": "single",
  "match": {
    "event": "create",
    "type": "Audio"
  },
  "config": {
    "language": "en-US"
  },
  "task_queue": "transcription-queue",
  "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 Examples

Create Workflow Rule

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

Retrieve a Workflow Rule

Endpoint: /workflows/rules/<RULE_ID>

Method: GET

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Description
`<RULE_ID>`	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",
  "endpoint": "transcribe_audio",
  "input_type": "single",
  "match": {
    "event": "create",
    "type": "Audio"
  },
  "config": {
    "language": "en-US"
  },
  "task_queue": "transcription-queue",
  "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 Examples

Retrieve Workflow Rule

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

Update a Workflow Rule

Endpoint: /workflows/rules/<RULE_ID>

Method: PUT

Headers

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

Path Parameters

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

Input Parameters

Parameter	Data Type	Description
`name`	`string`	The name of the workflow rule.
`endpoint`	`string`	The endpoint of the workflow to be executed.
`input_type`	`WorkflowRuleInputType`	The input type of the rule.
`match`	`Record<string, any>`	The match criteria for the rule.
`config`	`Record<string, any>`	The configuration for the workflow.
`task_queue`	`string`	(Optional) The task queue name to use when starting workflows for this rule.

Example Request

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

Example Response

{
  "id": "<RULE_ID>",
  "name": "Transcribe Audio",
  "endpoint": "transcribe_audio",
  "input_type": "single",
  "match": {
    "event": "create",
    "type": "Audio"
  },
  "config": {
    "language": "fr-FR"
  },
  "task_queue": "transcription-queue",
  "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 Examples

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' \
--data-raw '{
    "name": "Transcribe Audio",
    "endpoint": "transcribe_audio",
    "input_type": "single",
    "match": {
        "event": "create",
        "type": "Audio"
    },
    "config": {
        "language": "fr-FR"
    }
}'

Delete a Workflow Rule

Endpoint: /workflows/rules/<RULE_ID>

Method: DELETE

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

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

Example Response

{
    "id": "<RULE_ID>"
}

Code Examples

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

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",
    "endpoint": "transcribe_audio",
    "input_type": "single",
    "match": {
      "event": "create",
      "type": "Audio"
    },
    "config": {
      "language": "en-US"
    },
    "task_queue": "transcription-queue",
    "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": "create",
      "type": "Document"
    },
    "config": {
      "embeddingType": "text"
    },
    "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 Examples

List Workflow Rules

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

Execute Workflow Rule

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

Method: POST

Headers

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

Path Parameters

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

Input Parameters

Parameter	Data Type	Description
`vars`	`Record<string, any>`	(Optional) Parameters to pass to the workflow. These will be merged with the rule's config.
`objectIds`	`string[]`	(Optional) 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 Examples

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' \
--data-raw '{
  "vars": {
    "custom_param": "value"
  },
  "objectIds": ["doc123"]
}'

List Runs for a Workflow Rule

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

Method: GET

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Description
`<RULE_ID>`	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 Examples

List Runs for Workflow Rule

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