@graph8/sdk 0.303.0 → 0.357.0

package/blocks/workbench/lib/workbench-types.ts

@@ -0,0 +1,191 @@
+"use client";
+
+/**
+ * Shapes and small helpers for the workbench components.
+ *
+ * A workbench table is a spreadsheet of records (rows) with columns that are either plain data or the output of
+ * a recipe (AI prompt, enrichment waterfall, formula). Rows and columns are open dictionaries because every
+ * customer defines their own columns: read a cell with `cellValue(row, column)`, never by guessing a key.
+ *
+ * The table id is a UUID string; row and column ids are integers. Credits: the free quote endpoints return the
+ * exact `required_credits` and the live `available_credits`; every run needs the quote's numbers echoed back.
+ */
+
+export interface WorkbenchTable {
+  id: string;
+  name: string;
+  description?: string | null;
+  entity_type?: string | null;
+  status?: string | null;
+  row_count?: number | null;
+  column_count?: number | null;
+  auto_enrich?: boolean | null;
+  created_at?: string | null;
+  updated_at?: string | null;
+}
+
+export type ColumnType = "data" | "formula" | "raw_json" | string;
+
+export interface WorkbenchColumn {
+  id: number;
+  /** Machine name: rows are keyed by it. `^[a-z][a-z0-9_]*$`. */
+  name: string;
+  display_name?: string | null;
+  column_type?: ColumnType;
+  data_type?: string | null;
+  mapping_target?: string | null;
+  /** Set when a recipe fills the column: "ai" or "waterfall". */
+  enrichment_type?: "ai" | "waterfall" | null;
+  enrichment_group_id?: string | null;
+  enrichment_config_id?: string | null;
+}
+
+export interface WorkbenchRow {
+  id: number;
+  raw_data?: Record<string, unknown> | null;
+  extracted_data?: Record<string, unknown> | null;
+  status?: string | null;
+  error_message?: string | null;
+  /** false means the row is LOCKED: sensitive cells are masked until it is unlocked (1 credit per row). */
+  credit_charged?: boolean | null;
+  source_type?: string | null;
+  enriched_at?: string | null;
+}
+
+/** The pages the API returns for rows and columns. */
+export interface Page<T> {
+  items: T[];
+  total?: number;
+}
+
+export interface CreditQuote {
+  can_run?: boolean;
+  can_unlock?: boolean;
+  required_credits: number;
+  available_credits?: number;
+  estimated_records?: number;
+  locked_count?: number;
+  shortfall?: number | null;
+  message?: string;
+  quote_id?: string;
+  operation_id?: string;
+  quote_expires_at?: string;
+  credits_per_record?: number | null;
+}
+
+export interface OperationReceipt {
+  id: string;
+  operation_type: string;
+  status: "running" | "completed" | "partial" | "failed" | "cancelled" | string;
+  counts?: Record<string, unknown>;
+  credits_charged?: number;
+  error_message?: string | null;
+  external_ref?: string | null;
+  started_at: string;
+  completed_at?: string | null;
+}
+
+export interface TableAnalytics {
+  total_rows?: number;
+  status_distribution?: Record<string, number>;
+}
+
+/** What a run targets. */
+export type RunTarget =
+  | { kind: "ai-column"; columnId: number }
+  | { kind: "ai-default" }
+  | { kind: "waterfall"; columnId: number };
+
+const SENSITIVE_MASK = "***";
+
+/** The value to show for a cell: a recipe writes `extracted_data`, imports write `raw_data`. */
+export function cellValue(row: WorkbenchRow, column: Pick<WorkbenchColumn, "name">): unknown {
+  const extracted = row.extracted_data?.[column.name];
+  return extracted !== undefined && extracted !== null && extracted !== "" ? extracted : row.raw_data?.[column.name];
+}
+
+export function formatCell(value: unknown): string {
+  if (value == null) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  return JSON.stringify(value);
+}
+
+/** A locked row has masked cells: do not edit, enrich or export them as if they were real values. */
+export function isLocked(row: WorkbenchRow): boolean {
+  return row.credit_charged === false;
+}
+
+export function isMasked(value: unknown): boolean {
+  return value === SENSITIVE_MASK;
+}
+
+/** Turn a header such as "Company Domain" into a legal machine name: `company_domain`. */
+export function toMachineName(label: string): string {
+  const base = label.trim().toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+  return /^[a-z]/.test(base) ? base.slice(0, 60) : `c_${base}`.replace(/_$/, "").slice(0, 60);
+}
+
+/** Split pasted spreadsheet text (tabs, else commas; quoted cells allowed) into a header row and body rows. */
+export function parsePasted(text: string): { headers: string[]; rows: string[][] } {
+  const clean = text.replace(/\r\n?/g, "\n").trim();
+  if (!clean) return { headers: [], rows: [] };
+  const delimiter = clean.split("\n")[0].includes("\t") ? "\t" : ",";
+  const table: string[][] = [];
+  let row: string[] = [];
+  let cell = "";
+  let quoted = false;
+  for (let i = 0; i < clean.length; i++) {
+    const ch = clean[i];
+    if (quoted) {
+      if (ch === '"' && clean[i + 1] === '"') { cell += '"'; i++; }
+      else if (ch === '"') quoted = false;
+      else cell += ch;
+    } else if (ch === '"') quoted = true;
+    else if (ch === delimiter) { row.push(cell); cell = ""; }
+    else if (ch === "\n") { row.push(cell); table.push(row); row = []; cell = ""; }
+    else cell += ch;
+  }
+  row.push(cell);
+  table.push(row);
+  const [headers, ...rows] = table;
+  return { headers: headers.map((h) => h.trim()), rows: rows.filter((r) => r.some((c) => c.trim() !== "")) };
+}
+
+const TERMINAL = new Set(["completed", "partial", "failed", "cancelled"]);
+
+/** A receipt in one of these states will not change any more. */
+export function isReceiptTerminal(status: string | undefined | null): boolean {
+  return TERMINAL.has(String(status ?? "").toLowerCase());
+}
+
+/**
+ * The receipt that belongs to a run: matched by job id when the history echoes it (AI runs do), else the newest receipt of
+ * the right type that was NOT in the history before the run started. That comparison uses receipt ids, never the browser's
+ * clock, so a fast or slow client clock cannot hide the run's receipt or pick up another run's.
+ */
+export function findRunReceipt(items: OperationReceipt[], jobId: string, knownIds: readonly string[], types: string[]): OperationReceipt | undefined {
+  const byJob = items.find((r) => r.external_ref === jobId);
+  if (byJob) return byJob;
+  const known = new Set(knownIds);
+  return items
+    .filter((r) => types.includes(r.operation_type) && !known.has(r.id))
+    .sort((a, b) => Date.parse(b.started_at) - Date.parse(a.started_at))[0];
+}
+
+export function runTypes(target: RunTarget): string[] {
+  return target.kind === "waterfall" ? ["waterfall"] : ["ai"];
+}
+
+/** Pick the array out of whichever envelope the endpoint used: `{items}`, `{rows}`, `{columns}` or a bare array. */
+export function pageItems<T>(data: unknown): T[] {
+  if (Array.isArray(data)) return data as T[];
+  const d = (data ?? {}) as Record<string, unknown>;
+  for (const key of ["items", "rows", "columns", "tables", "results"]) if (Array.isArray(d[key])) return d[key] as T[];
+  return [];
+}
+
+export function pageTotal(data: unknown, fallback: number): number {
+  const total = (data as { total?: unknown } | null | undefined)?.total;
+  return typeof total === "number" ? total : fallback;
+}

package/blocks/workbench/recipes/build-enriched-table.ts

@@ -0,0 +1,65 @@
+/**
+ * @title Build a workbench: rows in, an AI column, a quote, a run, the results
+ * @when Starting a Clay-style table from a pasted list. Order: create the table -> paste rows (the header line
+ * creates the columns) -> add a column and its AI prompt (free) -> QUOTE the run (free) -> a human approves the
+ * price -> run it with the quote's numbers -> poll the history until the run's receipt is final -> read the rows.
+ * A run with no `row_ids` runs EVERY row, and the quote prices exactly that: read it before approving.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function createAndFill(name: string, headers: string[], rows: string[][]) {
+  const table = await g8.api.workbench.createWorkbenchTable({ body: { name, entity_type: "company" } });
+  const tableId = (table.data as { id: string }).id;
+  await g8.api.workbench.pasteImportWorkbenchRows({ path: { table_id: tableId }, body: { headers, rows } });
+  return tableId;
+}
+
+/** Free: a column plus its prompt. `{{column_name}}` in the prompt reads another column of the same row. */
+export async function addAiColumn(tableId: string, machineName: string, displayName: string, prompt: string) {
+  const col = await g8.api.workbench.addWorkbenchColumn({ path: { table_id: tableId }, body: { name: machineName, display_name: displayName, data_type: "text" } });
+  const columnId = (col.data as { id: number }).id;
+  await g8.api.workbench.saveWorkbenchColumnAiConfig({ path: { table_id: tableId, col_id: columnId }, body: { prompt, usecase: "content_generation" } });
+  return columnId;
+}
+
+export interface Quote { required_credits: number; available_credits?: number; estimated_records?: number; can_run?: boolean; quote_id?: string; quote_expires_at?: string }
+
+/** Free. Show `required_credits` and `estimated_records` to a person before calling `runColumn`. */
+export async function quoteColumn(tableId: string, columnId: number, rowIds?: number[]): Promise<Quote> {
+  const res = await g8.api.workbench.quoteWorkbenchAiRun({ path: { table_id: tableId }, body: { column_id: columnId, ...(rowIds ? { row_ids: rowIds } : {}) } });
+  return res.data as unknown as Quote;
+}
+
+/** Billable. Only with a quote a human approved; the same numbers go back as the cap. */
+type Receipt = { id: string; status: string; external_ref?: string; operation_type: string; started_at: string; credits_charged?: number };
+async function receipts(tableId: string) {
+  const history = await g8.api.workbench.getWorkbenchHistory({ path: { table_id: tableId }, query: { limit: 50 } });
+  return ((history.data as { items?: Receipt[] }).items) ?? [];
+}
+
+export async function runColumn(tableId: string, columnId: number, quote: Quote, rowIds?: number[]) {
+  const before = new Set((await receipts(tableId)).map((r) => r.id)); // clock-free matching: the run's receipt is the new one
+  const started = await g8.api.workbench.runWorkbenchColumnAi({
+    path: { table_id: tableId, col_id: columnId },
+    body: { approved_max_credits: quote.required_credits, quote_expires_at: quote.quote_expires_at, quote_id: quote.quote_id, ...(rowIds ? { row_ids: rowIds } : {}) },
+  });
+  const jobId = (started.data as { job_id: string }).job_id;
+
+  let delay = 2000;
+  for (let i = 0; i < 100; i++) {
+    const items = await receipts(tableId);
+    const receipt = items.find((r) => r.external_ref === jobId) ?? items.find((r) => r.operation_type === "ai" && !before.has(r.id));
+    if (receipt && ["completed", "partial", "failed", "cancelled"].includes(receipt.status)) return { jobId, receipt };
+    await new Promise((r) => setTimeout(r, delay));
+    delay = Math.min(15000, Math.round(delay * 1.5));
+  }
+  throw new Error(`run ${jobId} did not finish in time; keep polling the history later`);
+}
+
+/** Cells: a recipe writes `extracted_data`, imports write `raw_data`. Rows with credit_charged false are locked and masked. */
+export async function readRows(tableId: string, endRow = 100) {
+  const res = await g8.api.workbench.listWorkbenchRows({ path: { table_id: tableId }, query: { start_row: 0, end_row: endRow } });
+  return (res.data as { items: Array<{ id: number; raw_data?: Record<string, unknown>; extracted_data?: Record<string, unknown>; credit_charged?: boolean }> }).items;
+}

package/blocks/workbench/recipes/import-from-search.ts

@@ -0,0 +1,42 @@
+/**
+ * @title Import people from a prospect search, unlock the ones you want, send them to a list
+ * @when Filling a workbench from graph8's people index. The preview is free; the import is BILLABLE and lands
+ * LOCKED rows (names and companies visible, emails and phones masked as "***"). Order: preview (free) ->
+ * a human approves -> import -> quote the unlock (free) -> a human approves -> unlock (1 credit per row) ->
+ * export the rows to a list. Never treat "***" as a real value, and never unlock more rows than were approved.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const FILTERS = [
+  { field: "job_title", operator: "any_of", value: ["VP Sales", "Head of Sales"] },
+  { field: "company_industry", operator: "any_of", value: ["computer software"] },
+];
+
+export async function preview(tableId: string) {
+  const res = await g8.api.workbench.previewWorkbenchSearchImport({ path: { table_id: tableId }, body: { filters: FILTERS, sample_size: 10 } });
+  return res.data;
+}
+
+/** Billable. `max_result` is the ceiling on the rows imported. */
+export async function importPeople(tableId: string, maxResult = 100) {
+  return g8.api.workbench.importWorkbenchFromSearch({ path: { table_id: tableId }, body: { filters: FILTERS, max_result: maxResult, skip_duplicates: true } });
+}
+
+export async function quoteUnlock(tableId: string, rowIds: number[]) {
+  const res = await g8.api.workbench.quoteWorkbenchUnlock({ path: { table_id: tableId }, body: { row_ids: rowIds } });
+  return res.data as unknown as { operation_id: string; locked_count: number; required_credits: number; available_credits: number; can_unlock: boolean; quote_expires_at: string };
+}
+
+/** Billable, 1 credit per locked row. Send the SAME row_ids the quote priced. */
+export async function unlock(tableId: string, rowIds: number[], quote: Awaited<ReturnType<typeof quoteUnlock>>) {
+  return g8.api.workbench.unlockWorkbenchRows({
+    path: { table_id: tableId },
+    body: { row_ids: rowIds, approved_max_credits: quote.required_credits, quote_expires_at: quote.quote_expires_at, operation_id: quote.operation_id },
+  });
+}
+
+export async function exportToNewList(tableId: string, rowIds: number[], listName: string) {
+  return g8.api.workbench.exportWorkbenchTable({ path: { table_id: tableId }, body: { row_ids: rowIds, create_new_list: true, new_list_name: listName, entity_type: "contact" } });
+}

package/blocks/workbench/recipes/scrape-into-table.ts

@@ -0,0 +1,36 @@
+/**
+ * @title Scrape the web into a table with the built-in scraper
+ * @when Collecting a list of companies or people from a description ("seed-stage fintechs in Berlin"). The
+ * scraper charges per result and `auto_enrich` adds enrichment of every result on top, so quote first. Order:
+ * credit estimate (free) -> a human approves -> run with the estimate as the cap -> poll the run -> read the rows.
+ * The estimate has no quote id: the cap and an expiry you choose go back on the run.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function estimate(tableId: string, maxResults: number, autoEnrich = false) {
+  const res = await g8.api.workbench.estimateWorkbenchScraperCredits({ query: { table_id: tableId, max_results: maxResults, auto_enrich: autoEnrich } });
+  return (res.data as { estimated_credits: number }).estimated_credits;
+}
+
+/** Billable. Only after a person approved `credits`. */
+export async function run(tableId: string, prompt: string, maxResults: number, credits: number, autoEnrich = false) {
+  const started = await g8.api.workbench.runWorkbenchScraper({
+    path: { table_id: tableId },
+    body: { prompt, max_results: maxResults, auto_enrich: autoEnrich, approved_max_credits: credits, quote_expires_at: new Date(Date.now() + 4 * 60_000).toISOString() },
+  });
+  return started.data as { run_id?: string; status?: string };
+}
+
+export async function waitForRun(tableId: string, runId: string) {
+  let delay = 3000;
+  for (let i = 0; i < 80; i++) {
+    const res = await g8.api.workbench.getWorkbenchScraperRun({ path: { table_id: tableId, run_id: runId } });
+    const status = String((res.data as { status?: string }).status ?? "");
+    if (status && !["pending", "running"].includes(status)) return res.data;
+    await new Promise((r) => setTimeout(r, delay));
+    delay = Math.min(20000, Math.round(delay * 1.4));
+  }
+  throw new Error(`scraper run ${runId} did not finish in time`);
+}

package/blocks/workbench/recipes/waterfall-column.ts

@@ -0,0 +1,55 @@
+/**
+ * @title Add an enrichment waterfall column, price it, run it
+ * @when Finding work emails (or phones) for a table of people. Map the table's columns to graph8 targets
+ * first (first name, last name, website): a step whose inputs are not mapped finds nothing. Saving a waterfall
+ * is free and never runs it. Order: map columns -> save the waterfall (steps copied from graph8's own templates)
+ * -> QUOTE (free) -> a human approves -> run with the quote's numbers. Providers on graph8's key spend credits;
+ * providers on your own key do not (check `GET /enrichment/providers`).
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+/** columns: { column id -> graph8 target }, for example { 12: "CONTACT_FIRST_NAME", 13: "CONTACT_LAST_NAME", 14: "COMPANY_WEBSITE" }. */
+export async function mapColumns(tableId: string, columns: Record<number, string>) {
+  for (const [id, target] of Object.entries(columns)) {
+    await g8.api.workbench.mapWorkbenchColumn({ path: { table_id: tableId, column_id: Number(id) }, body: { mapping_target: target } });
+  }
+}
+
+const NAMES = { first_name: "CONTACT_FIRST_NAME", last_name: "CONTACT_LAST_NAME", domain: "COMPANY_WEBSITE" };
+
+export async function saveWorkEmailWaterfall(tableId: string, name = "Work email") {
+  const step = (provider: string, action: string, display: string, output: string, order: number) => ({
+    id: `step_${provider}_${order}`, provider, action, action_display_name: display, output_field: output,
+    input_mapping: NAMES, order, enabled: true, is_system_provider: true, stop_on_success: true,
+  });
+  return g8.api.workbench.saveWorkbenchWaterfall({
+    path: { table_id: tableId },
+    body: {
+      config: {
+        name, column_id: `waterfall_${crypto.randomUUID().replace(/-/g, "_")}`, field_to_enrich: name, data_type: "text",
+        steps: [step("leadmagic", "email_finder", "Find Email", "email", 0), step("hunter", "find_email", "Find Email", "data.email", 1)],
+        skip_existing_values: true, auto_update: false,
+      },
+    },
+  });
+}
+
+/** After saving, read the columns: the waterfall column has enrichment_type "waterfall" and a numeric id. */
+export async function waterfallColumnId(tableId: string) {
+  const cols = await g8.api.workbench.listWorkbenchColumns({ path: { table_id: tableId } });
+  const items = (cols.data as { items: Array<{ id: number; enrichment_type?: string }> }).items;
+  return items.find((c) => c.enrichment_type === "waterfall")?.id;
+}
+
+export async function quoteAndRun(tableId: string, columnId: number, approve: (credits: number, rows: number) => Promise<boolean>) {
+  const quote = (await g8.api.workbench.quoteWorkbenchWaterfallRun({ path: { table_id: tableId, column_id: columnId }, body: { column_id: columnId } })).data as unknown as {
+    required_credits: number; estimated_records?: number; quote_id?: string; quote_expires_at?: string; can_run?: boolean;
+  };
+  if (quote.can_run === false || !(await approve(quote.required_credits, quote.estimated_records ?? 0))) return null;
+  return g8.api.workbench.runWorkbenchWaterfall({
+    path: { table_id: tableId, column_id: columnId },
+    body: { approved_max_credits: quote.required_credits, quote_expires_at: quote.quote_expires_at, quote_id: quote.quote_id },
+  });
+}

package/blocks/workflows/README.md

@@ -0,0 +1,100 @@
+# workflows
+
+Editable React screens for automations: a workflow list, a step-list editor (not a canvas), trigger
+configuration and run history. Install with `npx @graph8/sdk add workflows`.
+
+| Component | What it is |
+|---|---|
+| `WorkflowList` | Workflows with run (plan preview + JSON input), enable/disable, create, delete. |
+| `WorkflowEditor` | Ordered steps: rename, edit JSON config, and on linear workflows add/move/remove steps. Save is confirmed. |
+| `TriggerConfig` | Trigger type, polling interval, filters, live trigger status, reset cursor. |
+| `RunHistory` | Runs with status filter, polled detail, pause / resume / stop / restart. |
+| `useWorkflow` (hook) | Loads one workflow and saves its graph. |
+
+## Flow, in order (and the ids passed between steps)
+
+1. `GET /workflows` returns `{ actions: [...], total }`. Each row's `action_id` is the **workflow id** for every later call.
+2. Create: `POST /workflows` with `{ name, description, config }` (`external`, confirmed). The new workflow starts as a manual
+   (`tool_call`) trigger and an end step; the response `action_id` goes to `onOpen`.
+3. Edit: `GET /workflows/{action_id}` -> `config` = `{ nodes, edges, startNodeId | start_node_id, ... }`. Saving sends the whole `config`
+   back with `PUT /workflows/{action_id}`. Structure lives in two places (per-node `connections` and top-level `edges`); `lib/graph.ts`
+   rewrites both together. The "Add step" list comes from `GET /workflows/node-types/schema` (deprecated types are hidden).
+4. Trigger: `GET /workflows/{action_id}/trigger-status` (type, interval, cursor); `POST .../trigger-reset` skips unprocessed events.
+5. Run: `POST /workflows/{action_id}/plan` (free preview) -> confirm -> `POST /workflows/{action_id}/execute` with `{ input_data }`.
+   The response `execution_id` is the **run id**; pass it to `RunHistory initialExecutionId`.
+6. Runs: `GET /workflows/executions?action_id=...` -> row `execution_id` -> `GET /workflows/executions/{id}` (polled while `pending`/`running`).
+   `paused` and `pending_approval` wait for a person; they are not terminal.
+
+Workflow routes return the service's JSON as-is (no `{ data }` wrapper); the components accept both shapes.
+
+## Mounting
+
+```tsx
+// app/workflows/page.tsx
+"use client";
+import { useRouter } from "next/navigation";
+import { WorkflowList } from "@/components/g8/workflows/components/workflow-list";
+export default function Workflows() {
+  const router = useRouter();
+  return <WorkflowList onOpen={(id) => router.push(`/workflows/${id}`)} onRunStarted={(id, run) => router.push(`/workflows/${id}/runs?run=${run}`)} />;
+}
+```
+
+`WorkflowEditor`, `TriggerConfig` take `actionId`; `RunHistory` takes an optional `actionId` and `initialExecutionId`.
+
+## Prerequisites
+
+- `foundation` installed; proxy `allowedPrefixes` includes `workflows`.
+- `where: "api"`: everything a step references (list, sequence, mailbox, form, workbench) exists. Validate with `POST /workflows/validate`.
+- `where: "app"`: Slack / Roam / LinkedIn steps need those integrations connected by a person in graph8.
+
+## Tiers: why so many confirmations
+
+Saving or creating a workflow, running it, and every run control are `external` tier in the contract: a saved workflow can start acting on
+live events, and a run can message people. Each goes through `ConfirmSpendDialog`. Deleting is `destructive`. `POST /workflows/validate` is
+also tiered `external` by the contract although it only checks the graph, so the screens do not call it; the recipe `create-workflow.ts` does,
+server side.
+
+## Defaults the agent should use without asking
+
+- New workflow = manual trigger + end step; the person adds steps.
+- Branching workflows: edit names and configs only; the shape is changed in the graph8 canvas.
+- Run input `{}` unless the workflow needs inputs. 25 rows per page of run history.
+
+## Ask the person first
+
+- **Enabling** a workflow that sends messages (leave it disabled until they saw the plan).
+- **Resetting a trigger cursor** (skips events) and **restarting** a run (steps that message people run again).
+
+## Known limits
+
+- No canvas. Branches (`condition`, `loop`, `human`) are shown as steps in run order and their config is editable, but not rewired here.
+- Step config is edited as JSON; the node catalog (`GET /workflows/node-types/schema?node_type=...&detail=full`) documents every field.
+
+## Operations
+
+| SDK method (`g8.api.*`) | Route | Tier | Scope |
+|---|---|---|---|
+| `listWorkflows` | GET `/api/v1/workflows` | read | `workflows:read` |
+| `createWorkflow` | POST `/api/v1/workflows` | external | `workflows:run` |
+| `planWorkflow` | POST `/api/v1/workflows/{action_id}/plan` | read | `workflows:read` |
+| `executeWorkflow` | POST `/api/v1/workflows/{action_id}/execute` | external | `workflows:run` |
+| `updateWorkflow` | PUT `/api/v1/workflows/{action_id}` | external | `workflows:run` |
+| `deleteWorkflow` | DELETE `/api/v1/workflows/{action_id}` | destructive | `workflows:delete` |
+| `getWorkflow` | GET `/api/v1/workflows/{action_id}` | read | `workflows:read` |
+| `getNodeTypesSchema` | GET `/api/v1/workflows/node-types/schema` | read | `workflows:read` |
+| `getTriggerStatus` | GET `/api/v1/workflows/{action_id}/trigger-status` | read | `workflows:read` |
+| `resetTriggerCursor` | POST `/api/v1/workflows/{action_id}/trigger-reset` | external | `workflows:run` |
+| `listWorkflowExecutions` | GET `/api/v1/workflows/executions` | read | `workflows:read` |
+| `getExecution` | GET `/api/v1/workflows/executions/{execution_id}` | read | `workflows:read` |
+| `pauseExecution` | POST `/api/v1/workflows/executions/{execution_id}/pause` | external | `workflows:run` |
+| `resumeExecution` | POST `/api/v1/workflows/executions/{execution_id}/resume` | external | `workflows:run` |
+| `stopExecution` | POST `/api/v1/workflows/executions/{execution_id}/stop` | external | `workflows:run` |
+| `restartExecution` | POST `/api/v1/workflows/executions/{execution_id}/restart` | external | `workflows:run` |
+
+## Recipes
+
+- `recipes/create-workflow.ts`: Create a workflow from a list of steps, validate it, and save it
+- `recipes/run-workflow-and-wait.ts`: Preview a workflow run, start it, and wait for the result
+- `recipes/find-failed-runs.ts`: List a workflow's failed runs with their errors
+- `recipes/set-trigger.ts`: Change a workflow's trigger and skip the backlog