> ## Documentation Index
> Fetch the complete documentation index at: https://docs.glider.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# tRPC v2 Workflows API

> Feature-gated workflow authoring and lifecycle APIs for staged workflow rollout

The `v2.workflows.*` namespace is the staged workflow authoring surface for
agentic workflow drafts.

* Base endpoint: `POST /v1/trpc`
* Namespace: `v2.workflows.*`
* Auth: wallet session or API key
* Rollout: gated behind the `agentic_workflows_v1` feature flag

## Enabled Procedure Groups

* `v2.workflows.list`
* `v2.workflows.get`
* `v2.workflows.drafts.*`
  * `list`
  * `start`
  * `startFromWorkflow`
  * `get`
  * `answer`
  * `cancel`
* `v2.workflows.authoring.*`
  * `validate`
  * `preview`
  * `commit`
* `v2.workflows.drafts.commit`
* `v2.workflows.create`
* `v2.workflows.update`
* `v2.workflows.pause`
* `v2.workflows.resume`
* `v2.workflows.runNow`
* `v2.workflows.archive`
* `v2.workflows.monitor.*`
  * `tick`
  * `record`
* `v2.workflows.executions.*`
  * `list`
  * `get`
  * `getByWorkflow`

## Rollout Notes

* The namespace is exposed only when `agentic_workflows_v1=true` for the
  caller.
* `authored_agent_sdk` still independently gates authored-source validation,
  preview, and commit flows.
* `bounded_multi_asset_buys` still independently gates authored preview support
  for bounded multi-asset buy programs.

## Lifecycle Notes

The current public lifecycle supports:

1. Starting and iterating on workflow drafts from free text or existing
   workflows. Authored drafts can now include a source-derived graph preview on
   the draft plan before commit.
2. Validating, previewing, and committing authored workflow modules when the
   authored SDK flag is enabled.
   When `platform-api` is configured with the Cloudflare control-plane worker,
   authored commit now also activates the portfolio-scoped `StrategyFacet`
   runtime from the compiler-produced `AuthoredAgentMetadata` envelope before
   the workflow is treated as committed.
3. Creating, updating, listing, and inspecting canonical workflows.
4. Pausing, resuming, running, archiving, and monitoring workflows.
5. Reading workflow execution history for canonical workflows.

Direct `create/update` currently target the canonical workflow rail for:

* `rebalance_portfolio`
* `buy_asset`
* `sell_asset`
* `cash_sweep`
* `recurring_deposit`
* `withdraw_funds`

Other schema-valid workflow kinds may still return unsupported-operation errors
from the facade until later slices land.

`v2.workflows.list` supports workflow-kind filtering via `kind` and
trigger-kind filtering via `triggerKind`. Monitor discovery should use
`triggerKind` for trigger semantics such as `price_condition` and
`authored_sdk`.

This keeps the rollout centered on the top-level workflow surface flag, with
additional authored-SDK gating only for authored-module flows.

## Workflow Detail Runtime Notes

`v2.workflows.get` exposes monitor-state runtime annotations for trigger-driven
workflows, and now overlays live automation-engine runtime when the committed
workflow execution ref points at an automation run.

* `monitorState.waitingUntil` remains the source for time-based sleeps and wait
  windows.
* `monitorState.waitingForEventType` is the explicit event-driven wait surface:
  * `trigger_matched` for armed trigger waits
  * `execution_completed` for in-flight execution continuations
* `monitorState.metadata.triggerEventKind` and
  `monitorState.metadata.routeKey` remain auxiliary runtime annotations for the
  authored graph and workflow detail UI.
* `currentAutomationRun` is the canonical live authored-run overlay when the
  workflow has been dispatched into `automation-engine`.
* `executionHistory[*].automationRun` mirrors the same automation-engine handle
  per workflow execution ref, so UI surfaces can show step-level authored
  progress without re-querying `v2.automationRuns.*`.