# Workflows

Workflows (internally "flows") are the orchestration mechanism for longer-running,
multi-step content operations. Where individual API calls handle atomic short-lived
operations, Workflows wire multiple service calls together into a **composite action** —
for example: ingest content from a Channel → extract metadata → apply Document Rules →
publish to a destination.

The platform's services are designed around short-lived RPC calls. Workflows bridge them
into durable, sequenced processes managed by the Action & Media Flows service, with each
step tracked as a [Job](#tag/Jobs).

- **Create / Update** — define a workflow, its steps, and step configuration
- **Retrieve / List** — inspect workflow definitions; `list-default-groups` returns
  platform-provided workflow templates as a starting point
- **Enable / Disable** — activate or pause a workflow without deleting it
- **Purge** — permanently remove a workflow definition

Running instances of a workflow are tracked as [Jobs](#tag/Jobs). Use the Jobs API
to monitor progress, handle failures, and restart or cancel executions.


## Create a workflow

 - [POST /api/v1/flow/create](https://api.tenovos.com/openapi/content-intelligence/workflows/tenovos.action.flowservice.create.md): Creates one or more flows, each defined by a name, optional description, and a hierarchical task tree.

Request:
items      - List of flow definitions to create. Each item includes a name, optional description,
and a taskTree defining the root action and any child/reference tasks. All flows
are created in DRAFT status.
groupId   - Optional ID of a workflow template group. When provided, the platform also provisions any standard flows defined for that group, giving the organization a pre-configured starting set of workflows.

Response:
items      - The fully hydrated Flow objects that were created, including their assigned IDs
and complete task tree structures.

## Get a workflow

 - [POST /api/v1/flow/retrieve](https://api.tenovos.com/openapi/content-intelligence/workflows/tenovos.action.flowservice.retrieve.md): Retrieves one or more flows by their IDs, returning full flow definitions including task trees.

Request:
ids        - List of flow IDs to retrieve.

Response:
items      - The fully hydrated Flow objects, each including the complete task tree with
nested children, conditions, mappings, and configurations.

## Search workflows

 - [POST /api/v1/flow/list](https://api.tenovos.com/openapi/content-intelligence/workflows/tenovos.action.flowservice.list.md): Lists available flows as lightweight summaries, with optional filtering and pagination.

Request:
includeDisabled - When true, includes flows with DISABLED status in the results.
Defaults to false (only DRAFT and ENABLED flows are returned).
pagination       - Optional Pagination cursor and page size for iterating large result sets.

Response:
items            - List of FlowSummary objects (id, name, description, status, timestamps)
ordered by name. Does not include full task tree details.
pageCursor      - Opaque cursor to pass in a subsequent request to retrieve the next page.
Absent when there are no further results.

## Update a workflow

 - [POST /api/v1/flow/update](https://api.tenovos.com/openapi/content-intelligence/workflows/tenovos.action.flowservice.update.md): Updates the name, description, and task tree of one or more existing flows.

Request:
updates    - List of flow updates. Each update must include the flow ID and the full
replacement name and task tree. Flows with active running jobs cannot be updated.

Response:
items      - The fully hydrated Flow objects reflecting the applied updates.

## Permanently remove a workflow

 - [POST /api/v1/flow/purge](https://api.tenovos.com/openapi/content-intelligence/workflows/tenovos.action.flowservice.purge.md): Permanently deletes one or more flows. Only flows that are not in ENABLED status can be purged.

Request:
ids        - List of flow IDs to permanently delete. Enabled flows are excluded from deletion.

Response:
ids        - List of IDs of the flows that were successfully deleted.

## Enable a workflow

 - [POST /api/v1/flow/enable](https://api.tenovos.com/openapi/content-intelligence/workflows/tenovos.action.flowservice.enable.md): Activates one or more flows, allowing them to be triggered by events and create jobs.

Request:
ids        - List of flow IDs to enable. Each flow transitions from DRAFT or DISABLED to ENABLED.
Enabling registers the flow's root task as a trigger on the appropriate event subject,
including any conditional trigger expressions.

Response:
ids        - List of IDs of the flows that were successfully enabled.

## Disable a workflow

 - [POST /api/v1/flow/disable](https://api.tenovos.com/openapi/content-intelligence/workflows/tenovos.action.flowservice.disable.md): Deactivates one or more flows, preventing them from creating new jobs.

Request:
ids        - List of flow IDs to disable. Flows with active running jobs cannot be disabled.
Disabling removes the associated event triggers so no new jobs will be created.

Response:
ids        - List of IDs of the flows that were successfully disabled.

## Get default workflow groups

 - [POST /api/v1/flow/list-default-groups](https://api.tenovos.com/openapi/content-intelligence/workflows/tenovos.action.flowservice.listdefaultgroups.md): Returns the set of system-defined default flow groups, each containing their associated flows.

Request:
(no parameters)

Response:
groups     - List of Group objects, each containing a groupId and a list of FlowSummary
objects belonging to that group. Only system-level (non-org-specific) flows
are included. Used to seed default workflows when onboarding a new organization.