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

> Workflow authoring and lifecycle APIs for webapp-v2

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

* Base endpoint: `POST /v1/trpc`
* Namespace: `v2.workflows.*`
* Auth: wallet session or API key
* Auth gates: wallet/API authentication plus owner checks in the workflow
  facade

## 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.construction.*`
  * `start`
  * `refine`
  * `answer`
  * `setExecutionPolicy`
  * `read`
  * `validate`
  * `simulate`
  * `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`

## Availability Notes

* `v2.workflows.construction.*` is the canonical workflow construction draft
  facade for webapp-v2. It returns typed construction drafts, readiness,
  diagnostics, and simulation placeholders; activation remains blocked until
  readiness explicitly allows it.
* Older authored-source procedure groups may still use their existing runtime
  feature gates while they are being consolidated into the construction facade.

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

The `construction.*` procedures are the platform-owned draft boundary for the
new workflow construction AI rail. `start`, `refine`, `answer`, and
`setExecutionPolicy` return canonical typed construction drafts for the
collaborative rail. Simulation and commit are gated by typed readiness and
return diagnostics when the current draft version cannot be enabled.

`v2.workflows.construction.refine` accepts structured rail edits through
`field` and `fieldValue`. Asset edits may also pass `fieldLabel` as an optional
display-label fallback when `fieldValue` is a canonical asset id or CAIP-style
machine id that resolves without token-list symbol metadata. `fieldLabel` does
not replace the canonical asset id used for validation, preview, or execution.

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