@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/workflows.md

@@ -0,0 +1,2302 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.workflows`: Workflows
+
+59 operations (30 read, 10 write, 4 destructive, 15 external).
+
+21 of these also have a hand-written method (`g8.workflows`), marked **★** below. Prefer the hand-written method when one exists: it unwraps the `data` envelope and takes friendlier arguments. See [../sdk-clients.md](../sdk-clients.md).
+
+Every example below assumes this setup (server-side, API key):
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+Example values are placeholders that match each field's type. Only required fields are shown. Every example is type-checked against the SDK in CI.
+
+Exact TypeScript types for every operation on this page, and every schema they use: [workflows.d.ts](workflows.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`approveExecution`](#op-approveexecution) | `POST /api/v1/workflows/executions/approve` | external | `workflows:run` | Approve a run waiting on a human |
+| [`attachSkillCollections`](#op-attachskillcollections) | `POST /api/v1/skills/{action_id}/collections` | write | `workflows:write` | Give a skill collections to retrieve from |
+| [`bulkRestartExecutions`](#op-bulkrestartexecutions) | `POST /api/v1/workflows/executions/bulk-restart` | external | `workflows:run` | Restart many workflow executions |
+| [`createSkillTestCase`](#op-createskilltestcase) | `POST /api/v1/skills/{action_id}/test-cases` | write | `workflows:write` | Save a test case for a skill |
+| [`createWorkbench`](#op-createworkbench) | `POST /api/v1/workflows/workbenches` | external | `workflows:run` | Create a workbench (so a workflow has somewhere to write) |
+| [`createWorkflow`](#op-createworkflow) ★ | `POST /api/v1/workflows` | external | `workflows:run` | Create a workflow |
+| [`deleteSkillTestCase`](#op-deleteskilltestcase) | `DELETE /api/v1/skills/{action_id}/test-cases/{test_case_id}` | destructive | `workflows:delete` | Delete a test case |
+| [`deleteWorkflow`](#op-deleteworkflow) ★ | `DELETE /api/v1/workflows/{action_id}` | destructive | `workflows:delete` | Delete a workflow |
+| [`deleteWorkflowIntegration`](#op-deleteworkflowintegration) | `DELETE /api/v1/workflows/integrations/{provider_name}` | destructive | `workflows:delete` | Disconnect a workflow integration |
+| [`describeFormFields`](#op-describeformfields) ★ | `GET /api/v1/workflows/forms/{form_id}/fields` | read | `workflows:read` | Discover form field names from recent submissions (resolver helper) |
+| [`detachSkillCollection`](#op-detachskillcollection) | `DELETE /api/v1/skills/{action_id}/collections/{collection_id}` | destructive | `workflows:delete` | Stop a skill retrieving from a collection |
+| [`diffSkillVersions`](#op-diffskillversions) | `GET /api/v1/skills/{action_id}/versions/{version_id}/diff` | read | `workflows:read` | Diff two versions of a skill |
+| [`executeWorkflow`](#op-executeworkflow) ★ | `POST /api/v1/workflows/{action_id}/execute` | external | `workflows:run` | Execute a workflow |
+| [`getExecution`](#op-getexecution) ★ | `GET /api/v1/workflows/executions/{execution_id}` | read | `workflows:read` | Get execution status / result |
+| [`getExecutionStats`](#op-getexecutionstats) | `GET /api/v1/workflows/stats/executions` | read | `workflows:read` | Run health for the organisation or one skill |
+| [`getNodeTypesSchema`](#op-getnodetypesschema) ★ | `GET /api/v1/workflows/node-types/schema` | read | `workflows:read` | Catalog of all workflow node types and their config schemas |
+| [`getTriggerActivity`](#op-gettriggeractivity) | `GET /api/v1/workflows/stats/trigger-activity` | read | `workflows:read` | Whether workflow triggers are being evaluated |
+| [`getTriggerStatus`](#op-gettriggerstatus) ★ | `GET /api/v1/workflows/{action_id}/trigger-status` | read | `workflows:read` | Trigger status (cursor + config) for a workflow |
+| [`getWorkflow`](#op-getworkflow) ★ | `GET /api/v1/workflows/{action_id}` | read | `workflows:read` | Get a workflow's full graph |
+| [`getWorkflowIntegration`](#op-getworkflowintegration) | `GET /api/v1/workflows/integrations/{provider_name}` | read | `workflows:read` | Get one workflow integration |
+| [`getWorkflowNodeStats`](#op-getworkflownodestats) | `GET /api/v1/workflows/node-stats` | read | `workflows:read` | Per-node success and failure rates for a workflow |
+| [`getWorkflowRunSummary`](#op-getworkflowrunsummary) | `GET /api/v1/workflows/run-summary` | read | `workflows:read` | Has this workflow ever run? |
+| [`inferSkillVariable`](#op-inferskillvariable) | `POST /api/v1/skills/infer-variable` | write | `workflows:write` | Infer one skill variable from a record |
+| [`listDispositions`](#op-listdispositions) ★ | `GET /api/v1/workflows/dispositions` | read | `workflows:read` | List valid call disposition values (system + this org's custom) |
+| [`listInboxTags`](#op-listinboxtags) | `GET /api/v1/workflows/inbox-tags` | read | `workflows:read` | List AI Inbox tags for the org (resolver helper) |
+| [`listLinkedinSenders`](#op-listlinkedinsenders) | `GET /api/v1/workflows/integrations/linkedin/senders` | read | `workflows:read` | List LinkedIn sender accounts for the org (resolver helper) |
+| [`listMcpServers`](#op-listmcpservers) ★ | `GET /api/v1/workflows/mcp-servers` | read | `workflows:read` | List MCP servers connected to the org (resolver helper) |
+| [`listRecentWorkflowRuns`](#op-listrecentworkflowruns) | `GET /api/v1/workflows/{action_id}/runs/recent` | read | `workflows:read` | Recent runs of one workflow |
+| [`listRoamGroups`](#op-listroamgroups) ★ | `GET /api/v1/workflows/integrations/roam/groups` | read | `workflows:read` | List Roam groups connected to the org (resolver helper) |
+| [`listRoamUsers`](#op-listroamusers) ★ | `GET /api/v1/workflows/integrations/roam/users` | read | `workflows:read` | List Roam users connected to the org (resolver helper) |
+| [`listSkillCollections`](#op-listskillcollections) | `GET /api/v1/skills/{action_id}/collections` | read | `workflows:read` | Collections a skill retrieves from |
+| [`listSkillTestCases`](#op-listskilltestcases) | `GET /api/v1/skills/{action_id}/test-cases` | read | `workflows:read` | List a skill's saved test cases |
+| [`listSkillTestRuns`](#op-listskilltestruns) | `GET /api/v1/skills/{action_id}/test-runs` | read | `workflows:read` | A skill's test-run history |
+| [`listSkillVersions`](#op-listskillversions) | `GET /api/v1/skills/{action_id}/versions` | read | `workflows:read` | A skill's versions |
+| [`listSlackChannels`](#op-listslackchannels) ★ | `GET /api/v1/workflows/integrations/slack/channels` | read | `workflows:read` | List Slack channels for the org (resolver helper) |
+| [`listSlackUsers`](#op-listslackusers) ★ | `GET /api/v1/workflows/integrations/slack/users` | read | `workflows:read` | List Slack users for the org (resolver helper) |
+| [`listWorkbenches`](#op-listworkbenches) | `GET /api/v1/workflows/workbenches` | read | `workflows:read` | List workbenches for the org (resolver helper) |
+| [`listWorkflowExecutions`](#op-listworkflowexecutions) | `GET /api/v1/workflows/executions` | read | `workflows:read` | List workflow executions for the caller's org (recover a lost execution_id) |
+| [`listWorkflowIntegrations`](#op-listworkflowintegrations) | `GET /api/v1/workflows/integrations` | read | `workflows:read` | List connected workflow integrations |
+| [`listWorkflows`](#op-listworkflows) ★ | `GET /api/v1/workflows` | read | `workflows:read` | List workflows for the caller's org |
+| [`parseScriptParameters`](#op-parsescriptparameters) | `POST /api/v1/skills/parse-script-parameters` | write | `workflows:write` | Detect a script's parameters from its code |
+| [`pauseExecution`](#op-pauseexecution) ★ | `POST /api/v1/workflows/executions/{execution_id}/pause` | external | `workflows:run` | Pause a running execution (tenant-checked) |
+| [`planInlineWorkflow`](#op-planinlineworkflow) | `POST /api/v1/workflows/plan` | read | `workflows:read` | Preview a normalized execution plan for an inline workflow graph |
+| [`planWorkflow`](#op-planworkflow) | `POST /api/v1/workflows/{action_id}/plan` | read | `workflows:read` | Preview a normalized execution plan for a saved workflow |
+| [`rejectExecution`](#op-rejectexecution) | `POST /api/v1/workflows/executions/reject` | write | `workflows:write` | Reject a run waiting on a human |
+| [`requestExecutionChanges`](#op-requestexecutionchanges) | `POST /api/v1/workflows/executions/request-changes` | external | `workflows:run` | Answer a human-approval step with changes requested |
+| [`resetTriggerCursor`](#op-resettriggercursor) ★ | `POST /api/v1/workflows/{action_id}/trigger-reset` | external | `workflows:run` | Reset the trigger cursor to now |
+| [`resolveSkillTemplates`](#op-resolveskilltemplates) | `POST /api/v1/skills/resolve-templates` | write | `workflows:write` | Resolve skill template names to ids |
+| [`restartExecution`](#op-restartexecution) | `POST /api/v1/workflows/executions/{execution_id}/restart` | external | `workflows:run` | Restart one workflow execution |
+| [`restoreSkillVersion`](#op-restoreskillversion) | `POST /api/v1/skills/{action_id}/versions/{version_id}/restore` | write | `workflows:write` | Restore an earlier version of a skill |
+| [`resumeExecution`](#op-resumeexecution) ★ | `POST /api/v1/workflows/executions/{execution_id}/resume` | external | `workflows:run` | Resume a paused execution (tenant-checked) |
+| [`runSkillTestSuite`](#op-runskilltestsuite) | `POST /api/v1/skills/{action_id}/test-runs` | external | `workflows:run` | Run every saved test case against a skill |
+| [`saveWorkflowIntegration`](#op-saveworkflowintegration) | `POST /api/v1/workflows/integrations/{provider_name}` | write | `workflows:write` | Connect or update a workflow integration |
+| [`stopExecution`](#op-stopexecution) ★ | `POST /api/v1/workflows/executions/{execution_id}/stop` | external | `workflows:run` | Permanently stop an execution (tenant-checked) |
+| [`testIntegrationCredential`](#op-testintegrationcredential) | `POST /api/v1/workflows/integrations/{provider_name}/test` | external | `workflows:run` | Try a Roam or Slack token |
+| [`testSkillOnce`](#op-testskillonce) | `POST /api/v1/skills/{action_id}/test` | write | `workflows:write` | Dry-run a skill once |
+| [`updateSkillTestCase`](#op-updateskilltestcase) | `PUT /api/v1/skills/{action_id}/test-cases/{test_case_id}` | write | `workflows:write` | Update a test case |
+| [`updateWorkflow`](#op-updateworkflow) ★ | `PUT /api/v1/workflows/{action_id}` | external | `workflows:run` | Update a workflow's graph |
+| [`validateWorkflow`](#op-validateworkflow) ★ | `POST /api/v1/workflows/validate` | external | `workflows:run` | Validate a workflow graph (structural + reference resolution) |
+
+---
+
+<a id="op-approveexecution"></a>
+
+### `g8.api.workflows.approveExecution(input)`
+
+**Approve a run waiting on a human**
+
+- HTTP: `POST /api/v1/workflows/executions/approve`
+- operationId: `approve_execution_workflows_executions_approve_post` (also callable as `g8.api.call("approve_execution_workflows_executions_approve_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `workflows:run`
+
+REACHES OUTSIDE GRAPH8 when the approved step does: the paused run
+RESUMES and performs the action it was holding (a send, an API call, a
+write). 403 when `approved_by` may not approve it; 404 for another
+organisation's run.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ExecutionApproval` | yes | Request body; fields below. |
+
+Body fields (`ExecutionApproval`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.approved_by` | `string` | yes | Who approved; voice checks they may. min length 1 |
+| `body.workflow_id` | `string` | yes | The paused run's workflow id. min length 1 |
+| `body.notes` | `string \| null` | no | max length 2000 |
+
+**Returns** `ApiResponse_VoicePayload_`: the envelope `{ data: VoicePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.workflows.approveExecution({ body: { approved_by: "example", workflow_id: "id" } });
+```
+
+---
+
+<a id="op-attachskillcollections"></a>
+
+### `g8.api.workflows.attachSkillCollections(input)`
+
+**Give a skill collections to retrieve from**
+
+- HTTP: `POST /api/v1/skills/{action_id}/collections`
+- operationId: `attach_skill_collections_skills__action_id__collections_post` (also callable as `g8.api.call("attach_skill_collections_skills__action_id__collections_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+ADDITIVE, not a replace: attaching does not detach what is already there.
+
+Takes effect on the next run. A collection with no vectors retrieves
+nothing - check `/voice/collections/{id}/vector-status` if a skill seems
+to be ignoring what you gave it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.action_id` | `string` | yes | Skill or workflow `action_id`. |
+| `body` | `Body_attach_skill_collections_skills__action_id__collections_post` | yes | Request body; fields below. |
+
+Body fields (`Body_attach_skill_collections_skills__action_id__collections_post`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.collection_ids` | `Array<integer>` | yes | Collections to attach. Additive - existing links survive. min items 1 |
+
+**Returns** `ApiResponse_VoicePayload_`: the envelope `{ data: VoicePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.attachSkillCollections({ path: { action_id: "id" }, body: { collection_ids: [123] } });
+```
+
+---
+
+<a id="op-bulkrestartexecutions"></a>
+
+### `g8.api.workflows.bulkRestartExecutions(input?)`
+
+**Restart many workflow executions**
+
+- HTTP: `POST /api/v1/workflows/executions/bulk-restart`
+- operationId: `bulk_restart_executions_workflows_executions_bulk_restart_post` (also callable as `g8.api.call("bulk_restart_executions_workflows_executions_bulk_restart_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `workflows:run`
+
+"Re-run all failed", in one call. EVERY NODE RUNS AGAIN.
+
+Not a resume: a restart begins at the start, so nodes that already
+succeeded run a second time - including anything that sent a message,
+called an API or spent credits the first time.
+
+Voice applies a 60-second idempotency window to this route, so an
+accidental double-submit inside that window does not double-run the batch.
+Send an `Idempotency-Key` header as well for the app-wide guard.
+
+Every execution in the batch is scoped to the caller's org before it is
+touched; ids belonging to another tenant are simply not found.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `Record<string, unknown>` | no | Request body; fields below. |
+
+**Returns** `ApiResponse_VoicePayload_`: the envelope `{ data: VoicePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.workflows.bulkRestartExecutions();
+```
+
+---
+
+<a id="op-createskilltestcase"></a>
+
+### `g8.api.workflows.createSkillTestCase(input)`
+
+**Save a test case for a skill**
+
+- HTTP: `POST /api/v1/skills/{action_id}/test-cases`
+- operationId: `create_skill_test_case_skills__action_id__test_cases_post` (also callable as `g8.api.call("create_skill_test_case_skills__action_id__test_cases_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+Saving a case RUNS NOTHING. Only `POST .../test-runs` runs the skill.
+
+That separation is the point: building a suite is free, and executing it
+is the operation that costs.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.action_id` | `string` | yes | Skill or workflow `action_id`. |
+| `body` | `Body_create_skill_test_case_skills__action_id__test_cases_post` | yes | Request body; fields below. |
+
+Body fields (`Body_create_skill_test_case_skills__action_id__test_cases_post`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.input_data` | `Record<string, unknown>` | yes | The fixture, same shape as an execution's input. |
+| `body.name` | `string` | yes | Human label. min length 1, max length 200 |
+| `body.assertion_config` | `Record<string, unknown> \| null` | no | Extra configuration for the assertion. |
+| `body.assertion_type` | `string` | no | "exact", "contains" or "llm_judge". `llm_judge` is skipped by dry runs. default `"contains"` |
+| `body.expected_output` | `unknown \| null` | no | What the assertion compares against. |
+
+**Returns** `ApiResponse_VoicePayload_`: the envelope `{ data: VoicePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.createSkillTestCase({
+  path: { action_id: "id" },
+  body: { input_data: {}, name: "Example" },
+});
+```
+
+---
+
+<a id="op-createworkbench"></a>
+
+### `g8.api.workflows.createWorkbench(input)`
+
+**Create a workbench (so a workflow has somewhere to write)**
+
+- HTTP: `POST /api/v1/workflows/workbenches`
+- operationId: `create_workbench_workflows_workbenches_post` (also callable as `g8.api.call("create_workbench_workflows_workbenches_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `workflows:run`
+
+Create an empty workbench and return its `workbench_id`.
+
+The missing half of the loop: an agent could be TOLD a workbench id but could
+never make one, so "build me a workflow that collects X into a new workbench"
+always needed a human to go and click New Workbench first.
+
+``entity_type`` is optional and must be ``contact`` or ``company`` when given;
+a blank workbench may defer it, which is what the underlying command already
+allows. ``created_by`` is the authenticated caller and is never read from the
+request, so a key cannot attribute a workbench to someone else.
+
+The webhook API key the browser route returns on create is deliberately NOT
+surfaced here. It is a write credential for a different ingestion path, it is
+returned exactly once, and nothing in the workflow surface needs it — an agent
+that never sees it cannot leak it into a workflow config or a chat transcript.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `Record<string, unknown>` | yes | Request body; fields below. |
+
+**Returns** `Record<string, unknown>`.
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.workflows.createWorkbench({ body: {} });
+```
+
+---
+
+<a id="op-createworkflow"></a>
+
+### `g8.api.workflows.createWorkflow(input)`
+
+**Create a workflow**
+
+- HTTP: `POST /api/v1/workflows`
+- operationId: `create_workflow_workflows_post` (also callable as `g8.api.call("create_workflow_workflows_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `workflows:run`
+- ★ Hand-written: [`g8.workflows.create()`](../sdk-clients.md#g8-workflows-create)
+
+Create a new workflow. Pins ``org_id`` and ``runtime_type='workflow'``
+server-side - the body cannot override either.
+
+Translates the public ``config`` field to voice's internal
+``skill_config`` before forwarding (see module docstring).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `Record<string, unknown>` | yes | Request body; fields below. |
+
+**Returns** `Record<string, unknown>`.
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.workflows.createWorkflow({ body: {} });
+```
+
+---
+
+<a id="op-deleteskilltestcase"></a>
+
+### `g8.api.workflows.deleteSkillTestCase(input)`
+
+**Delete a test case**
+
+- HTTP: `DELETE /api/v1/skills/{action_id}/test-cases/{test_case_id}`
+- operationId: `delete_skill_test_case_skills__action_id__test_cases__test_case_id__delete` (also callable as `g8.api.call("delete_skill_test_case_skills__action_id__test_cases__test_case_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `workflows:delete`
+
+The case goes; its HISTORICAL RUNS SURVIVE, still carrying its id.
+
+So a deleted case leaves readable history rather than orphaning it - past
+runs in `GET .../test-runs` keep working.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.action_id` | `string` | yes | Skill or workflow `action_id`. |
+| `path.test_case_id` | `string` | yes | Test case id. |
+
+**Returns** `ApiResponse_VoicePayload_`: the envelope `{ data: VoicePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.workflows.deleteSkillTestCase({ path: { action_id: "id", test_case_id: "id" } });
+```
+
+---
+
+<a id="op-deleteworkflow"></a>
+
+### `g8.api.workflows.deleteWorkflow(input)`
+
+**Delete a workflow**
+
+- HTTP: `DELETE /api/v1/workflows/{action_id}`
+- operationId: `delete_workflow_workflows__action_id__delete` (also callable as `g8.api.call("delete_workflow_workflows__action_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `workflows:delete`
+- ★ Hand-written: [`g8.workflows.delete()`](../sdk-clients.md#g8-workflows-delete)
+
+Delete a workflow. Voice's delete returns ``{"success": true, ...}``
+on success and 403 for system defaults - both pass through.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.action_id` | `string` | yes | Workflow action_id. |
+
+**Returns** `Record<string, unknown>`.
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.workflows.deleteWorkflow({ path: { action_id: "id" } });
+```
+
+---
+
+<a id="op-deleteworkflowintegration"></a>
+
+### `g8.api.workflows.deleteWorkflowIntegration(input)`
+
+**Disconnect a workflow integration**
+
+- HTTP: `DELETE /api/v1/workflows/integrations/{provider_name}`
+- operationId: `delete_workflow_integration_workflows_integrations__provider_name__delete` (also callable as `g8.api.call("delete_workflow_integration_workflows_integrations__provider_name__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `workflows:delete`
+
+Removes the stored credential and configuration. NOT REVERSIBLE.
+
+Any workflow node using this provider starts failing at its next run.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.provider_name` | `string` | yes | Provider name. |
+
+**Returns** `ApiResponse_VoicePayload_`: the envelope `{ data: VoicePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.workflows.deleteWorkflowIntegration({ path: { provider_name: "Example" } });
+```
+
+---
+
+<a id="op-describeformfields"></a>
+
+### `g8.api.workflows.describeFormFields(input)`
+
+**Discover form field names from recent submissions (resolver helper)**
+
+- HTTP: `GET /api/v1/workflows/forms/{form_id}/fields`
+- operationId: `describe_form_fields_workflows_forms__form_id__fields_get` (also callable as `g8.api.call("describe_form_fields_workflows_forms__form_id__fields_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+- ★ Hand-written: [`g8.workflows.listFormFields()`](../sdk-clients.md#g8-workflows-listformfields)
+
+Sample recent submissions for a form and return the unique field names.
+
+Use this to populate the ``form_fields[]`` array on a
+``new_form_submitted`` trigger node config at create time, mirroring
+what ``NodeConfigPanel.handleFormSelect`` does on the frontend when
+the user selects a form in the dropdown.
+
+Without these names pre-populated, downstream nodes cannot reference
+submitted values via ``${<trigger_node_id>.<field>}`` until the user
+re-selects the form in the UI.
+
+Calls ``forms`` handlers in-process (no voice round-trip). Forms data
+lives in ClickHouse via ``apps.forms()`` — sampled submissions are
+paginated server-side; we only ever read ``per_page=10`` here.
+
+Returns ``{form_id, fields: [str], sample_size: int}``. Empty
+``fields`` means no submissions exist yet — the caller should fall
+back to asking the user for the field list, or accept that
+``${trigger.<field>}`` references will only resolve once a real
+submission arrives.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.form_id` | `string` | yes | HTML form id (form_tag_id) |
+
+**Returns** `Record<string, unknown>`.
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.describeFormFields({ path: { form_id: "id" } });
+```
+
+---
+
+<a id="op-detachskillcollection"></a>
+
+### `g8.api.workflows.detachSkillCollection(input)`
+
+**Stop a skill retrieving from a collection**
+
+- HTTP: `DELETE /api/v1/skills/{action_id}/collections/{collection_id}`
+- operationId: `detach_skill_collection_skills__action_id__collections__collection_id__delete` (also callable as `g8.api.call("detach_skill_collection_skills__action_id__collections__collection_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `workflows:delete`
+
+Breaks the LINK only. The collection and its files are untouched.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.action_id` | `string` | yes | Skill or workflow `action_id`. |
+| `path.collection_id` | `integer` | yes | Collection to unlink. |
+
+**Returns** `ApiResponse_VoicePayload_`: the envelope `{ data: VoicePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.workflows.detachSkillCollection({ path: { action_id: "id", collection_id: 123 } });
+```
+
+---
+
+<a id="op-diffskillversions"></a>
+
+### `g8.api.workflows.diffSkillVersions(input)`
+
+**Diff two versions of a skill**
+
+- HTTP: `GET /api/v1/skills/{action_id}/versions/{version_id}/diff`
+- operationId: `diff_skill_versions_skills__action_id__versions__version_id__diff_get` (also callable as `g8.api.call("diff_skill_versions_skills__action_id__versions__version_id__diff_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Field-level diff - what actually changed, not just that something did.
+
+The question to ask when a skill's output changed and nobody remembers
+editing it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.action_id` | `string` | yes | Skill or workflow `action_id`. |
+| `path.version_id` | `string` | yes | The version to diff. |
+| `query.against` | `string \| null` | no | The version to compare with. Defaults to the one immediately before. |
+
+**Returns** `ApiResponse_VoicePayload_`: the envelope `{ data: VoicePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.diffSkillVersions({ path: { action_id: "id", version_id: "id" } });
+```
+
+---
+
+<a id="op-executeworkflow"></a>
+
+### `g8.api.workflows.executeWorkflow(input)`
+
+**Execute a workflow**
+
+- HTTP: `POST /api/v1/workflows/{action_id}/execute`
+- operationId: `execute_workflow_workflows__action_id__execute_post` (also callable as `g8.api.call("execute_workflow_workflows__action_id__execute_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `workflows:run`
+- ★ Hand-written: [`g8.workflows.execute()`](../sdk-clients.md#g8-workflows-execute)
+
+Trigger a workflow run. Returns ``execution_id`` for polling.
+
+Pins ``org_id`` server-side; the caller cannot override which org's
+execution row is created. ``triggered_by`` defaults to the caller's
+user id when not supplied.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.action_id` | `string` | yes | Workflow action_id. |
+| `body` | `Record<string, unknown>` | no | Request body; fields below. |
+
+**Returns** `Record<string, unknown>`.
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.workflows.executeWorkflow({ path: { action_id: "id" } });
+```
+
+---
+
+<a id="op-getexecution"></a>
+
+### `g8.api.workflows.getExecution(input)`
+
+**Get execution status / result**
+
+- HTTP: `GET /api/v1/workflows/executions/{execution_id}`
+- operationId: `get_execution_workflows_executions__execution_id__get` (also callable as `g8.api.call("get_execution_workflows_executions__execution_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+- ★ Hand-written: [`g8.workflows.getExecution()`](../sdk-clients.md#g8-workflows-getexecution)
+
+Return execution status + output_data + token / cost telemetry.
+
+The MCP polling pattern: call this until ``status`` reaches a TERMINAL
+value — ``completed``, ``failed`` or ``stopped``. A run can also sit in
+``paused`` or ``pending_approval`` (both non-terminal and resumable via
+the lifecycle routes below), so a poller must treat those as "keep
+waiting", not "done" — polling only for completed/failed hangs forever on
+a paused or approval-gated run. The full set voice writes is
+``pending|running|completed|failed|paused|pending_approval|stopped``.
+Voice's GET enforces tenant isolation natively so no pre-flight is needed
+for the read path.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.execution_id` | `string` | yes | Execution UUID. |
+
+**Returns** `Record<string, unknown>`.
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.getExecution({ path: { execution_id: "id" } });
+```
+
+---
+
+<a id="op-getexecutionstats"></a>
+
+### `g8.api.workflows.getExecutionStats(input?)`
+
+**Run health for the organisation or one skill**
+
+- HTTP: `GET /api/v1/workflows/stats/executions`
+- operationId: `get_execution_stats_workflows_stats_executions_get` (also callable as `g8.api.call("get_execution_stats_workflows_stats_executions_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+SPENDS NOTHING. Status buckets that sum to the total, success rate,
+duration, tokens, and `total_cost_usd` - a FLOOR on spend, since only
+LLM-runtime runs record a cost (`executions_with_cost` says how many).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.action_id` | `string \| null` | no | One skill's health; omit for the organisation. |
+| `query.days` | `integer \| null` | no | Window; omit for lifetime. |
+
+**Returns** `ApiResponse_VoicePayload_`: the envelope `{ data: VoicePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.getExecutionStats();
+```
+
+---
+
+<a id="op-getnodetypesschema"></a>
+
+### `g8.api.workflows.getNodeTypesSchema(input?)`
+
+**Catalog of all workflow node types and their config schemas**
+
+- HTTP: `GET /api/v1/workflows/node-types/schema`
+- operationId: `get_node_types_schema_workflows_node_types_schema_get` (also callable as `g8.api.call("get_node_types_schema_workflows_node_types_schema_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+- ★ Hand-written: [`g8.workflows.nodeTypes()`](../sdk-clients.md#g8-workflows-nodetypes)
+
+Catalog every node type with its config schema, trigger output schemas,
+resolver-tool hints, and worked examples. Cached (LRU + 1h Cache-Control)
+on voice's side - context-cheap to call repeatedly from MCP clients.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.detail` | `string` | no | "slim" returns name+type per field; "full" includes Pydantic JSON schema. default `"slim"` |
+| `query.node_type` | `string \| null` | no | If provided, return just one entry instead of the full catalog. |
+
+**Returns** `Record<string, unknown>`.
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.getNodeTypesSchema();
+```
+
+---
+
+<a id="op-gettriggeractivity"></a>
+
+### `g8.api.workflows.getTriggerActivity(input)`
+
+**Whether workflow triggers are being evaluated**
+
+- HTTP: `GET /api/v1/workflows/stats/trigger-activity`
+- operationId: `get_trigger_activity_workflows_stats_trigger_activity_get` (also callable as `g8.api.call("get_trigger_activity_workflows_stats_trigger_activity_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+SPENDS NOTHING. Per workflow: when its trigger was last evaluated and
+last matched. A workflow absent from the answer is UNKNOWN (never evaluated,
+or its 30-day record lapsed), not "never ran".
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.action_ids` | `string` | yes | Comma-separated workflow ids (first 200 used). |
+
+**Returns** `ApiResponse_VoicePayload_`: the envelope `{ data: VoicePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.getTriggerActivity({ query: { action_ids: "id" } });
+```
+
+---
+
+<a id="op-gettriggerstatus"></a>
+
+### `g8.api.workflows.getTriggerStatus(input)`
+
+**Trigger status (cursor + config) for a workflow**
+
+- HTTP: `GET /api/v1/workflows/{action_id}/trigger-status`
+- operationId: `get_trigger_status_workflows__action_id__trigger_status_get` (also callable as `g8.api.call("get_trigger_status_workflows__action_id__trigger_status_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+- ★ Hand-written: [`g8.workflows.getTriggerStatus()`](../sdk-clients.md#g8-workflows-gettriggerstatus)
+
+Return whether the workflow has a trigger, its type, and last cursor.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.action_id` | `string` | yes | Workflow action_id. |
+
+**Returns** `Record<string, unknown>`.
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.getTriggerStatus({ path: { action_id: "id" } });
+```
+
+---
+
+<a id="op-getworkflow"></a>
+
+### `g8.api.workflows.getWorkflow(input)`
+
+**Get a workflow's full graph**
+
+- HTTP: `GET /api/v1/workflows/{action_id}`
+- operationId: `get_workflow_workflows__action_id__get` (also callable as `g8.api.call("get_workflow_workflows__action_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+- ★ Hand-written: [`g8.workflows.get()`](../sdk-clients.md#g8-workflows-get)
+
+Return the full workflow graph (nodes + edges + trigger config).
+
+Translates voice's internal ``skill_config`` field to public
+``config`` on the way out (see module docstring).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.action_id` | `string` | yes | Workflow action_id. |
+
+**Returns** `Record<string, unknown>`.
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.getWorkflow({ path: { action_id: "id" } });
+```
+
+---
+
+<a id="op-getworkflowintegration"></a>
+
+### `g8.api.workflows.getWorkflowIntegration(input)`
+
+**Get one workflow integration**
+
+- HTTP: `GET /api/v1/workflows/integrations/{provider_name}`
+- operationId: `get_workflow_integration_workflows_integrations__provider_name__get` (also callable as `g8.api.call("get_workflow_integration_workflows_integrations__provider_name__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Its configuration and whether a key is stored - never the key itself.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.provider_name` | `string` | yes | Provider name. |
+
+**Returns** `ApiResponse_VoicePayload_`: the envelope `{ data: VoicePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.getWorkflowIntegration({ path: { provider_name: "Example" } });
+```
+
+---
+
+<a id="op-getworkflownodestats"></a>
+
+### `g8.api.workflows.getWorkflowNodeStats(input)`
+
+**Per-node success and failure rates for a workflow**
+
+- HTTP: `GET /api/v1/workflows/node-stats`
+- operationId: `get_workflow_node_stats_workflows_node_stats_get` (also callable as `g8.api.call("get_workflow_node_stats_workflows_node_stats_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Which STEP is failing, aggregated across runs.
+
+The view that turns "this workflow is flaky" into "this node times out",
+without reading every execution.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.action_id` | `string` | yes | The workflow to analyse. |
+| `query.days` | `integer` | no | Window, in days. default `30` |
+
+**Returns** `ApiResponse_VoicePayload_`: the envelope `{ data: VoicePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.getWorkflowNodeStats({ query: { action_id: "id" } });
+```
+
+---
+
+<a id="op-getworkflowrunsummary"></a>
+
+### `g8.api.workflows.getWorkflowRunSummary(input?)`
+
+**Has this workflow ever run?**
+
+- HTTP: `GET /api/v1/workflows/run-summary`
+- operationId: `get_workflow_run_summary_workflows_run_summary_get` (also callable as `g8.api.call("get_workflow_run_summary_workflows_run_summary_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+The authoritative answer for a BATCH of workflows, in one call.
+
+Worth using instead of listing executions per workflow: "never run" and
+"ran and returned nothing" look identical in an empty execution list, and
+this distinguishes them.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.action_ids` | `string \| null` | no | Comma-separated workflow ids. Omit for every workflow in the org. |
+
+**Returns** `ApiResponse_VoicePayload_`: the envelope `{ data: VoicePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.getWorkflowRunSummary();
+```
+
+---
+
+<a id="op-inferskillvariable"></a>
+
+### `g8.api.workflows.inferSkillVariable(input)`
+
+**Infer one skill variable from a record**
+
+- HTTP: `POST /api/v1/skills/infer-variable`
+- operationId: `infer_skill_variable_skills_infer_variable_post` (also callable as `g8.api.call("infer_skill_variable_skills_infer_variable_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+Work out what one skill variable should be for a given record.
+
+The single-variable version of what a skill does to its whole input before
+it runs - useful for showing a caller what a skill WILL see without running
+it. Results are cached per `(org, entity_id)`, so passing `entity_id` makes
+a repeated call cheap.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `Body_infer_skill_variable_skills_infer_variable_post` | yes | Request body; fields below. |
+
+Body fields (`Body_infer_skill_variable_skills_infer_variable_post`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.entity_data` | `Record<string, unknown>` | yes | The contact or company record, same shape as an execution input. |
+| `body.entity_data_type` | `string` | yes | "contact" or "company". |
+| `body.entity_id` | `string \| null` | no | Record id. Used for cache keying only. |
+
+**Returns** `ApiResponse_VoicePayload_`: the envelope `{ data: VoicePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.inferSkillVariable({ body: { entity_data: {}, entity_data_type: "example" } });
+```
+
+---
+
+<a id="op-listdispositions"></a>
+
+### `g8.api.workflows.listDispositions(input?)`
+
+**List valid call disposition values (system + this org's custom)**
+
+- HTTP: `GET /api/v1/workflows/dispositions`
+- operationId: `list_dispositions_workflows_dispositions_get` (also callable as `g8.api.call("list_dispositions_workflows_dispositions_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+- ★ Hand-written: [`g8.workflows.listDispositions()`](../sdk-clients.md#g8-workflows-listdispositions)
+
+Return every disposition value accepted by ``disposition_filters`` on the
+``new_call_disposition`` trigger - system values AND the caller org's own
+custom dispositions.
+
+Each entry carries ``origin``: ``system`` for the built-in vocabulary,
+``custom`` for an org-defined one (whose ``value`` is the stored
+``custom_{id}`` key, never the display name). ``category`` keeps its
+existing meaning: ``sdr_selectable`` a rep can pick it, ``system_set`` only
+the dialer backend writes it.
+
+Authority for the system half is voice's ``SDR_SELECTABLE_DISPOSITIONS``
+(``voice/graph8_livekit/schemas/dispositions.py``) plus the two system-set
+values the dialer also emits (``sdr_hangup``, ``failed``). That half is
+inlined here and a parity test
+(``developer_api/tests/test_workflow_dispositions.py``) fails the build if
+voice adds a value that is not mirrored - the previous "mirror the change
+here" comment was not enforced and silently went stale when ``busy`` was
+added.
+
+The custom half comes from voice's ``GET /api/dialer/dispositions/{org_id}``,
+with the org pinned server-side from the authenticated caller and echoed in
+the ``X-Org-Id`` header voice's tenant gate requires. Nothing about the
+request body or query can influence which org is read.
+
+Degraded mode: if voice is unreachable or errors, this returns the system
+vocabulary alone with ``source='static_fallback'`` and logs a warning,
+rather than failing the whole call. An agent that sees
+``source='static_fallback'`` should say it could not confirm custom
+dispositions instead of asserting none exist.
+
+Legacy aliases (``positive``/``neutral``/``negative``) are deliberately
+absent: ``normalize_disposition`` rewrites them before storage, so a filter
+on them could never match.
+
+**Input**: none.
+
+**Returns** `Record<string, unknown>`.
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.listDispositions();
+```
+
+---
+
+<a id="op-listinboxtags"></a>
+
+### `g8.api.workflows.listInboxTags(input?)`
+
+**List AI Inbox tags for the org (resolver helper)**
+
+- HTTP: `GET /api/v1/workflows/inbox-tags`
+- operationId: `list_inbox_tags_workflows_inbox_tags_get` (also callable as `g8.api.call("list_inbox_tags_workflows_inbox_tags_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Resolve human tag descriptions ("out of office", "interested", "referred
+me to a colleague") into the concrete tag IDs required by the
+``new_inbox_tag_set`` trigger's ``tag_filters``.
+
+This is the resolver that makes reply-intent workflows authorable. Without
+it an agent has no way to turn a tag NAME into a tag ID, so it falls back to
+a ``new_email_reply`` trigger plus a condition node grepping the body text -
+which is both fragile and duplicates work the inbox AI agent already did
+when it tagged the message on arrival.
+
+``ai_applicable_only=true`` narrows to tags whose ``ai_can_apply`` is set,
+i.e. the ones an agent applies automatically the moment an email lands.
+Those are the tags a ``new_inbox_tag_set`` trigger will actually fire on
+without a human touching anything.
+
+Calls the ``ai_inbox`` tag service in-process (no voice round-trip). Org is
+pinned from the authenticated caller and used as the Postgres tenant schema;
+nothing client-supplied selects the tenant.
+
+Returns ``{tags: [{id, name, description, color, ai_can_apply}], total}``.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.ai_applicable_only` | `boolean` | no | Return only tags an AI agent is allowed to apply automatically. default `false` |
+
+**Returns** `Record<string, unknown>`.
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.listInboxTags();
+```
+
+---
+
+<a id="op-listlinkedinsenders"></a>
+
+### `g8.api.workflows.listLinkedinSenders(input?)`
+
+**List LinkedIn sender accounts for the org (resolver helper)**
+
+- HTTP: `GET /api/v1/workflows/integrations/linkedin/senders`
+- operationId: `list_linkedin_senders_workflows_integrations_linkedin_senders_get` (also callable as `g8.api.call("list_linkedin_senders_workflows_integrations_linkedin_senders_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Return LinkedIn sender accounts for ``sender_account_id`` resolution.
+
+Resolves the ``sender_account_id`` on the Netrion workflow nodes
+(``send_netrion_connection_request`` / ``send_netrion_message``) and on the
+``linkedin_*`` triggers' ``linkedin_account_id``. Until this existed there was
+NO way to discover these ids programmatically: voice's ``_RESOLVER_HINTS``
+said "no MCP resolver yet — ask user", and the only listing endpoint
+(``GET /v1/linkedin/accounts``) is behind ``get_current_user`` browser auth,
+so an MCP/API caller could build the node and then not attach a sender.
+
+``sender_account_id`` is the INTEGER PK (``ArlinkLinkedInAccount.id``), which
+is the value the node config takes — deliberately NOT the arlink ``lia_...``
+string. ``account_resolution.resolve_active_account`` cannot parse the
+``lia_`` form, and the Netrion nodes opt into ``strict_account``, so naming
+one is a hard failure rather than a silent send from an arbitrary seat. The
+field is emitted as a STRING because that is the node config's own type.
+
+Mirrors ``GET /v1/linkedin/accounts`` on degradation: flag off, no accounts,
+or per-org tables not provisioned all answer an empty list, never a 500.
+A sender that is not ``status='OK'`` is still returned, with its status, so
+the caller can say "that seat is disconnected" instead of "no seats".
+
+**Input**: none.
+
+**Returns** `Record<string, unknown>`.
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.listLinkedinSenders();
+```
+
+---
+
+<a id="op-listmcpservers"></a>
+
+### `g8.api.workflows.listMcpServers(input?)`
+
+**List MCP servers connected to the org (resolver helper)**
+
+- HTTP: `GET /api/v1/workflows/mcp-servers`
+- operationId: `list_mcp_servers_workflows_mcp_servers_get` (also callable as `g8.api.call("list_mcp_servers_workflows_mcp_servers_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+- ★ Hand-written: [`g8.workflows.listMcpServers()`](../sdk-clients.md#g8-workflows-listmcpservers)
+
+Return MCP servers (with their tool lists) for ``tool.mcp_server_id`` resolution.
+
+``org_id`` is REQUIRED by voice (``voice/graph8_livekit/routers/mcp_servers.py``
+declares ``list_mcp_servers(org_id: str)`` with no default), so omitting it makes
+voice answer 422, not an empty list. This route previously sat below the
+``/{action_id}`` catch-all and was unreachable, which hid the missing parameter -
+un-shadowing it turned a 404 into a 422 until this was fixed.
+
+The org is pinned from the authenticated caller and is never read from the request,
+so a client cannot enumerate another tenant's MCP servers.
+
+**Input**: none.
+
+**Returns** `Record<string, unknown>`.
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.listMcpServers();
+```
+
+---
+
+<a id="op-listrecentworkflowruns"></a>
+
+### `g8.api.workflows.listRecentWorkflowRuns(input)`
+
+**Recent runs of one workflow**
+
+- HTTP: `GET /api/v1/workflows/{action_id}/runs/recent`
+- operationId: `list_recent_workflow_runs_workflows__action_id__runs_recent_get` (also callable as `g8.api.call("list_recent_workflow_runs_workflows__action_id__runs_recent_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Ordered and limited in SQL, so a busy workflow answers cheaply.
+
+`GET /workflows/executions` lists across the whole org; this is the
+per-workflow view.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.action_id` | `string` | yes | Skill or workflow `action_id`. |
+| `query.limit` | `integer` | no | Rows to return, newest first. default `10` |
+
+**Returns** `ApiResponse_VoiceListPayload_`: the envelope `{ data: VoiceListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`VoiceListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.listRecentWorkflowRuns({ path: { action_id: "id" } });
+```
+
+---
+
+<a id="op-listroamgroups"></a>
+
+### `g8.api.workflows.listRoamGroups(input?)`
+
+**List Roam groups connected to the org (resolver helper)**
+
+- HTTP: `GET /api/v1/workflows/integrations/roam/groups`
+- operationId: `list_roam_groups_workflows_integrations_roam_groups_get` (also callable as `g8.api.call("list_roam_groups_workflows_integrations_roam_groups_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+- ★ Hand-written: [`g8.workflows.listRoamGroups()`](../sdk-clients.md#g8-workflows-listroamgroups)
+
+Return Roam groups for ``send_roam_notification.recipient_id`` resolution.
+
+**Input**: none.
+
+**Returns** `Record<string, unknown>`.
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.listRoamGroups();
+```
+
+---
+
+<a id="op-listroamusers"></a>
+
+### `g8.api.workflows.listRoamUsers(input?)`
+
+**List Roam users connected to the org (resolver helper)**
+
+- HTTP: `GET /api/v1/workflows/integrations/roam/users`
+- operationId: `list_roam_users_workflows_integrations_roam_users_get` (also callable as `g8.api.call("list_roam_users_workflows_integrations_roam_users_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+- ★ Hand-written: [`g8.workflows.listRoamUsers()`](../sdk-clients.md#g8-workflows-listroamusers)
+
+Return Roam users for ``send_roam_notification.user_ids`` resolution.
+
+**Input**: none.
+
+**Returns** `Record<string, unknown>`.
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.listRoamUsers();
+```
+
+---
+
+<a id="op-listskillcollections"></a>
+
+### `g8.api.workflows.listSkillCollections(input)`
+
+**Collections a skill retrieves from**
+
+- HTTP: `GET /api/v1/skills/{action_id}/collections`
+- operationId: `list_skill_collections_skills__action_id__collections_get` (also callable as `g8.api.call("list_skill_collections_skills__action_id__collections_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+What this skill can look things up in while it runs.
+
+The collections themselves are managed at `/voice/collections`; this is
+the link between one skill and them.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.action_id` | `string` | yes | Skill or workflow `action_id`. |
+
+**Returns** `ApiResponse_VoiceListPayload_`: the envelope `{ data: VoiceListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`VoiceListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.listSkillCollections({ path: { action_id: "id" } });
+```
+
+---
+
+<a id="op-listskilltestcases"></a>
+
+### `g8.api.workflows.listSkillTestCases(input)`
+
+**List a skill's saved test cases**
+
+- HTTP: `GET /api/v1/skills/{action_id}/test-cases`
+- operationId: `list_skill_test_cases_skills__action_id__test_cases_get` (also callable as `g8.api.call("list_skill_test_cases_skills__action_id__test_cases_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Oldest first, so the suite has a stable order between runs.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.action_id` | `string` | yes | Skill or workflow `action_id`. |
+
+**Returns** `ApiResponse_VoiceListPayload_`: the envelope `{ data: VoiceListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`VoiceListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.listSkillTestCases({ path: { action_id: "id" } });
+```
+
+---
+
+<a id="op-listskilltestruns"></a>
+
+### `g8.api.workflows.listSkillTestRuns(input)`
+
+**A skill's test-run history**
+
+- HTTP: `GET /api/v1/skills/{action_id}/test-runs`
+- operationId: `list_skill_test_runs_skills__action_id__test_runs_get` (also callable as `g8.api.call("list_skill_test_runs_skills__action_id__test_runs_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Newest first. Reading history costs nothing and runs nothing.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.action_id` | `string` | yes | Skill or workflow `action_id`. |
+| `query.test_case_id` | `string \| null` | no | Only runs of this case. |
+| `query.limit` | `integer` | no | Rows to return, newest first. default `50` |
+| `query.include_output` | `boolean` | no | True adds the stored output previews. They can be large. default `false` |
+
+**Returns** `ApiResponse_VoiceListPayload_`: the envelope `{ data: VoiceListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`VoiceListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.listSkillTestRuns({ path: { action_id: "id" } });
+```
+
+---
+
+<a id="op-listskillversions"></a>
+
+### `g8.api.workflows.listSkillVersions(input)`
+
+**A skill's versions**
+
+- HTTP: `GET /api/v1/skills/{action_id}/versions`
+- operationId: `list_skill_versions_skills__action_id__versions_get` (also callable as `g8.api.call("list_skill_versions_skills__action_id__versions_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+SPENDS NOTHING. Version history, newest first, with the published one
+marked. Compare two with `GET /skills/{action_id}/versions/{version_id}/diff`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.action_id` | `string` | yes | Skill (action) id. |
+| `query.limit` | `integer` | no | Newest first. default `50` |
+
+**Returns** `ApiResponse_VoicePayload_`: the envelope `{ data: VoicePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.listSkillVersions({ path: { action_id: "id" } });
+```
+
+---
+
+<a id="op-listslackchannels"></a>
+
+### `g8.api.workflows.listSlackChannels(input?)`
+
+**List Slack channels for the org (resolver helper)**
+
+- HTTP: `GET /api/v1/workflows/integrations/slack/channels`
+- operationId: `list_slack_channels_workflows_integrations_slack_channels_get` (also callable as `g8.api.call("list_slack_channels_workflows_integrations_slack_channels_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+- ★ Hand-written: [`g8.workflows.listSlackChannels()`](../sdk-clients.md#g8-workflows-listslackchannels)
+
+Return Slack channels for ``send_slack_notification.channel_id`` resolution.
+
+**Input**: none.
+
+**Returns** `Record<string, unknown>`.
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.listSlackChannels();
+```
+
+---
+
+<a id="op-listslackusers"></a>
+
+### `g8.api.workflows.listSlackUsers(input?)`
+
+**List Slack users for the org (resolver helper)**
+
+- HTTP: `GET /api/v1/workflows/integrations/slack/users`
+- operationId: `list_slack_users_workflows_integrations_slack_users_get` (also callable as `g8.api.call("list_slack_users_workflows_integrations_slack_users_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+- ★ Hand-written: [`g8.workflows.listSlackUsers()`](../sdk-clients.md#g8-workflows-listslackusers)
+
+Return Slack workspace users for ``send_slack_notification.user_id`` resolution.
+
+**Input**: none.
+
+**Returns** `Record<string, unknown>`.
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.listSlackUsers();
+```
+
+---
+
+<a id="op-listworkbenches"></a>
+
+### `g8.api.workflows.listWorkbenches(input?)`
+
+**List workbenches for the org (resolver helper)**
+
+- HTTP: `GET /api/v1/workflows/workbenches`
+- operationId: `list_workbenches_workflows_workbenches_get` (also callable as `g8.api.call("list_workbenches_workflows_workbenches_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Resolve a workbench NAME into the `workbench_id` the workbench nodes need.
+
+Returns ``{workbenches: [{workbench_id, name, entity_type, description,
+row_count, created_at}], total, page, limit}``.
+
+``workbench_id`` is the value to paste straight into a node config. It is the
+same id the Workbench page URL shows, so an agent and a human are naming the
+same thing.
+
+Org is pinned from the authenticated caller and used as the tenant scope;
+nothing client-supplied selects the tenant.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.limit` | `integer` | no | Page size. default `50` |
+| `query.page` | `integer` | no | 1-based page number. default `1` |
+| `query.filter_name` | `string \| null` | no | Case-insensitive name filter. |
+
+**Returns** `Record<string, unknown>`.
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.listWorkbenches();
+```
+
+---
+
+<a id="op-listworkflowexecutions"></a>
+
+### `g8.api.workflows.listWorkflowExecutions(input?)`
+
+**List workflow executions for the caller's org (recover a lost execution_id)**
+
+- HTTP: `GET /api/v1/workflows/executions`
+- operationId: `list_workflow_executions_workflows_executions_get` (also callable as `g8.api.call("list_workflow_executions_workflows_executions_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+List this org's workflow executions, newest first, with SQL-side
+pagination - the recovery path for a lost ``execution_id`` (the single
+``GET /workflows/executions/{execution_id}`` read below needs an id you
+no longer have).
+
+Org is pinned server-side from the authenticated caller and passed to
+voice in the PATH; a client-supplied ``org_id`` query param is ignored,
+so one tenant can never list another tenant's executions (the voice
+backing route trusts its path ``org_id``, so pinning here is the tenant
+boundary - getting it wrong is a cross-org IDOR). ``runtime_type`` is
+pinned to ``workflow`` so only workflow runs surface here, matching the
+sibling ``GET /workflows`` which does not expose raw LLM/API/script
+action runs.
+
+Proxies voice's ``GET /api/v1/executions/list/{org_id}`` and returns its
+``ExecutionListResponse`` shape unchanged - ``{executions: [...],
+total_count: int}`` - consistent with this router's pass-through
+convention (voice owns the execution DTO; re-declaring its ~20 fields
+here would only drift). Voice also clamps ``limit`` to 1..200 SQL-side;
+the bounds here reject an out-of-range page with a clean 422 before the
+round-trip.
+
+Read-only and additive: nothing is created, and no existing route changes.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.action_id` | `string \| null` | no | Filter to a single workflow's executions. |
+| `query.status_filter` | `string \| null` | no | Filter by execution status (equality match — one status per call). The backend writes seven values: pending\|running\|completed\|failed\|paused\|pending_approval\|stopped. The four terminal-or-early states are pending, running, completed, failed; paused and pending_approval are resumable, stopped is terminal. |
+| `query.triggered_by` | `string \| null` | no | Filter by the identity that started the run (user email, agent id, 'api', ...). |
+| `query.limit` | `integer` | no | Page size (1..200). default `50` |
+| `query.offset` | `integer` | no | Rows to skip for pagination. default `0` |
+
+**Returns** `Record<string, unknown>`.
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.listWorkflowExecutions();
+```
+
+---
+
+<a id="op-listworkflowintegrations"></a>
+
+### `g8.api.workflows.listWorkflowIntegrations(input?)`
+
+**List connected workflow integrations**
+
+- HTTP: `GET /api/v1/workflows/integrations`
+- operationId: `list_workflow_integrations_workflows_integrations_get` (also callable as `g8.api.call("list_workflow_integrations_workflows_integrations_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Which third-party accounts workflow nodes can act as.
+
+Rows report `has_api_key` rather than the key: credentials on this surface
+are write-only and are never echoed back.
+
+**Input**: none.
+
+**Returns** `ApiResponse_VoiceListPayload_`: the envelope `{ data: VoiceListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`VoiceListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.listWorkflowIntegrations();
+```
+
+---
+
+<a id="op-listworkflows"></a>
+
+### `g8.api.workflows.listWorkflows(input?)`
+
+**List workflows for the caller's org**
+
+- HTTP: `GET /api/v1/workflows`
+- operationId: `list_workflows_workflows_get` (also callable as `g8.api.call("list_workflows_workflows_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+- ★ Hand-written: [`g8.workflows.list()`](../sdk-clients.md#g8-workflows-list)
+
+List workflow actions (``runtime_type='workflow'``) owned by the org.
+
+Voice's underlying ``GET /list/{org_id}`` lists all actions; we pin
+``runtime_type=workflow`` so the public surface returns workflows
+only. Raw action listing (LLM/API/script skills) is intentionally
+not exposed here.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.enabled` | `boolean \| null` | no | Filter by enabled flag. |
+| `query.category` | `string \| null` | no | Filter by category. |
+| `query.is_template` | `boolean \| null` | no | Templates only when true. |
+
+**Returns** `Record<string, unknown>`.
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.listWorkflows();
+```
+
+---
+
+<a id="op-parsescriptparameters"></a>
+
+### `g8.api.workflows.parseScriptParameters(input)`
+
+**Detect a script's parameters from its code**
+
+- HTTP: `POST /api/v1/skills/parse-script-parameters`
+- operationId: `parse_script_parameters_skills_parse_script_parameters_post` (also callable as `g8.api.call("parse_script_parameters_skills_parse_script_parameters_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+Static analysis, not execution. The code is PARSED and never run.
+
+Returns the detected parameter names with their types and defaults, which
+is how a builder offers the right inputs for a script it did not write.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `Body_parse_script_parameters_skills_parse_script_parameters_post` | yes | Request body; fields below. |
+
+Body fields (`Body_parse_script_parameters_skills_parse_script_parameters_post`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.code` | `string` | yes | The script source. |
+| `body.language` | `string` | no | "python", "javascript" or "typescript". default `"python"` |
+
+**Returns** `ApiResponse_VoicePayload_`: the envelope `{ data: VoicePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.parseScriptParameters({ body: { code: "example" } });
+```
+
+---
+
+<a id="op-pauseexecution"></a>
+
+### `g8.api.workflows.pauseExecution(input)`
+
+**Pause a running execution (tenant-checked)**
+
+- HTTP: `POST /api/v1/workflows/executions/{execution_id}/pause`
+- operationId: `pause_execution_workflows_executions__execution_id__pause_post` (also callable as `g8.api.call("pause_execution_workflows_executions__execution_id__pause_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `workflows:run`
+- ★ Hand-written: [`g8.workflows.pauseExecution()`](../sdk-clients.md#g8-workflows-pauseexecution)
+
+Pause a running workflow execution. Pre-flight enforces that the
+execution belongs to the caller's org before forwarding to voice.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.execution_id` | `string` | yes | Execution UUID. |
+| `body` | `Record<string, unknown>` | no | Request body; fields below. |
+
+**Returns** `Record<string, unknown>`.
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.workflows.pauseExecution({ path: { execution_id: "id" } });
+```
+
+---
+
+<a id="op-planinlineworkflow"></a>
+
+### `g8.api.workflows.planInlineWorkflow(input)`
+
+**Preview a normalized execution plan for an inline workflow graph**
+
+- HTTP: `POST /api/v1/workflows/plan`
+- operationId: `plan_inline_workflow_workflows_plan_post` (also callable as `g8.api.call("plan_inline_workflow_workflows_plan_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Compute a normalized plan for a graph that is NOT yet saved. Accepts
+either ``{config: {...}}`` or a raw graph ``{nodes, edges, start_node_id}``
+directly. Read-only: nothing is persisted or executed.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `Record<string, unknown>` | yes | Request body; fields below. |
+
+**Returns** `Record<string, unknown>`.
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.planInlineWorkflow({ body: {} });
+```
+
+---
+
+<a id="op-planworkflow"></a>
+
+### `g8.api.workflows.planWorkflow(input)`
+
+**Preview a normalized execution plan for a saved workflow**
+
+- HTTP: `POST /api/v1/workflows/{action_id}/plan`
+- operationId: `plan_workflow_workflows__action_id__plan_post` (also callable as `g8.api.call("plan_workflow_workflows__action_id__plan_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Fetch a saved workflow's graph and compute its normalized plan. Org is
+pinned server-side; the caller cannot preview another tenant's workflow.
+Read-only.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.action_id` | `string` | yes | Workflow action_id. |
+| `body` | `Record<string, unknown>` | no | Request body; fields below. |
+
+**Returns** `Record<string, unknown>`.
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.planWorkflow({ path: { action_id: "id" } });
+```
+
+---
+
+<a id="op-rejectexecution"></a>
+
+### `g8.api.workflows.rejectExecution(input)`
+
+**Reject a run waiting on a human**
+
+- HTTP: `POST /api/v1/workflows/executions/reject`
+- operationId: `reject_execution_workflows_executions_reject_post` (also callable as `g8.api.call("reject_execution_workflows_executions_reject_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+SPENDS NOTHING. The held action is NOT performed and the run ends. For
+"try again with changes" use `POST /workflows/executions/request-changes`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ExecutionRejection` | yes | Request body; fields below. |
+
+Body fields (`ExecutionRejection`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.rejected_by` | `string` | yes | Who rejected; voice checks they may. min length 1 |
+| `body.workflow_id` | `string` | yes | The paused run's workflow id. min length 1 |
+| `body.reason` | `string \| null` | no | max length 2000 |
+
+**Returns** `ApiResponse_VoicePayload_`: the envelope `{ data: VoicePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.rejectExecution({ body: { rejected_by: "example", workflow_id: "id" } });
+```
+
+---
+
+<a id="op-requestexecutionchanges"></a>
+
+### `g8.api.workflows.requestExecutionChanges(input)`
+
+**Answer a human-approval step with changes requested**
+
+- HTTP: `POST /api/v1/workflows/executions/request-changes`
+- operationId: `request_execution_changes_workflows_executions_request_changes_post` (also callable as `g8.api.call("request_execution_changes_workflows_executions_request_changes_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `workflows:run`
+
+The THIRD outcome of a human-approval step, beside approve and reject.
+
+Approve and reject are terminal for the paused node. This one is not: it
+sends the run down the revise branch carrying the reviewer's words, so the
+workflow gets another attempt instead of ending.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `Body_request_execution_changes_workflows_executions_request_changes_post` | yes | Request body; fields below. |
+
+Body fields (`Body_request_execution_changes_workflows_executions_request_changes_post`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.feedback` | `string` | yes | REQUIRED and non-blank. It is the value the revise branch reads as `${<human_node>.feedback}` - an empty one sends the workflow down the revise path with nothing to revise against. min length 1, max length 2000 |
+| `body.requested_by` | `string` | yes | Who is asking for changes. |
+| `body.workflow_id` | `string` | yes | The workflow the run belongs to. |
+
+**Returns** `ApiResponse_VoicePayload_`: the envelope `{ data: VoicePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.workflows.requestExecutionChanges({
+  body: { feedback: "example", requested_by: "example", workflow_id: "id" },
+});
+```
+
+---
+
+<a id="op-resettriggercursor"></a>
+
+### `g8.api.workflows.resetTriggerCursor(input)`
+
+**Reset the trigger cursor to now**
+
+- HTTP: `POST /api/v1/workflows/{action_id}/trigger-reset`
+- operationId: `reset_trigger_cursor_workflows__action_id__trigger_reset_post` (also callable as `g8.api.call("reset_trigger_cursor_workflows__action_id__trigger_reset_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `workflows:run`
+- ★ Hand-written: [`g8.workflows.resetTrigger()`](../sdk-clients.md#g8-workflows-resettrigger)
+
+Stop reprocessing old events - sets the trigger cursor to now().
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.action_id` | `string` | yes | Workflow action_id. |
+
+**Returns** `Record<string, unknown>`.
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.workflows.resetTriggerCursor({ path: { action_id: "id" } });
+```
+
+---
+
+<a id="op-resolveskilltemplates"></a>
+
+### `g8.api.workflows.resolveSkillTemplates(input)`
+
+**Resolve skill template names to ids**
+
+- HTTP: `POST /api/v1/skills/resolve-templates`
+- operationId: `resolve_skill_templates_skills_resolve_templates_post` (also callable as `g8.api.call("resolve_skill_templates_skills_resolve_templates_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+Turn human template names into the `action_id`s every other route wants.
+
+The lookup that lets a caller write "Cold Call Opener" where the API needs
+a UUID. `org_id` is pinned from the key, so a name resolves within the
+caller's own templates.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `Record<string, unknown>` | yes | Request body; fields below. |
+
+**Returns** `ApiResponse_VoicePayload_`: the envelope `{ data: VoicePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.resolveSkillTemplates({ body: {} });
+```
+
+---
+
+<a id="op-restartexecution"></a>
+
+### `g8.api.workflows.restartExecution(input)`
+
+**Restart one workflow execution**
+
+- HTTP: `POST /api/v1/workflows/executions/{execution_id}/restart`
+- operationId: `restart_execution_workflows_executions__execution_id__restart_post` (also callable as `g8.api.call("restart_execution_workflows_executions__execution_id__restart_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `workflows:run`
+
+Runs the workflow again FROM THE BEGINNING. Not a resume.
+
+Nodes that already succeeded run a second time. If any of them sent an
+email, posted to Slack or called a paid API, they do it again. To continue
+a paused run instead, use `POST /workflows/executions/{id}/resume`.
+
+The org is forwarded and voice scopes the lookup by it, so one tenant
+cannot restart another's run.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.execution_id` | `string` | yes | Execution id. |
+| `body` | `Record<string, unknown>` | no | Request body; fields below. |
+
+**Returns** `ApiResponse_VoicePayload_`: the envelope `{ data: VoicePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.workflows.restartExecution({ path: { execution_id: "id" } });
+```
+
+---
+
+<a id="op-restoreskillversion"></a>
+
+### `g8.api.workflows.restoreSkillVersion(input)`
+
+**Restore an earlier version of a skill**
+
+- HTTP: `POST /api/v1/skills/{action_id}/versions/{version_id}/restore`
+- operationId: `restore_skill_version_skills__action_id__versions__version_id__restore_post` (also callable as `g8.api.call("restore_skill_version_skills__action_id__versions__version_id__restore_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+SPENDS NOTHING. Publishes the old snapshot as a NEW version, live for the
+next run - agents and workflows using the skill pick it up. Append-only, so
+the restore can itself be rolled back. Routine-managed skills refuse (403).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.action_id` | `string` | yes | Skill (action) id. |
+| `path.version_id` | `string` | yes | The version to bring back. |
+
+**Returns** `ApiResponse_VoicePayload_`: the envelope `{ data: VoicePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.restoreSkillVersion({ path: { action_id: "id", version_id: "id" } });
+```
+
+---
+
+<a id="op-resumeexecution"></a>
+
+### `g8.api.workflows.resumeExecution(input)`
+
+**Resume a paused execution (tenant-checked)**
+
+- HTTP: `POST /api/v1/workflows/executions/{execution_id}/resume`
+- operationId: `resume_execution_workflows_executions__execution_id__resume_post` (also callable as `g8.api.call("resume_execution_workflows_executions__execution_id__resume_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `workflows:run`
+- ★ Hand-written: [`g8.workflows.resumeExecution()`](../sdk-clients.md#g8-workflows-resumeexecution)
+
+Resume a paused execution. Pre-flight enforces tenant ownership.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.execution_id` | `string` | yes | Execution UUID. |
+| `body` | `Record<string, unknown>` | no | Request body; fields below. |
+
+**Returns** `Record<string, unknown>`.
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.workflows.resumeExecution({ path: { execution_id: "id" } });
+```
+
+---
+
+<a id="op-runskilltestsuite"></a>
+
+### `g8.api.workflows.runSkillTestSuite(input)`
+
+**Run every saved test case against a skill**
+
+- HTTP: `POST /api/v1/skills/{action_id}/test-runs`
+- operationId: `run_skill_test_suite_skills__action_id__test_runs_post` (also callable as `g8.api.call("run_skill_test_suite_skills__action_id__test_runs_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `workflows:run`
+
+RUNS THE SKILL, ONCE PER SAVED CASE. This has real side effects.
+
+For an `llm` skill that is a model call per case. For an `api` skill it is
+an outbound HTTP request per case, to the endpoint the skill is configured
+with, made AS THE PLATFORM - so a skill that writes somewhere will write
+there again, with the fixture's data.
+
+Every case is pinned to ONE version of the skill, so the result is a
+regression answer rather than a mix of versions.
+
+Tiered `external` by an explicit rule, for the same reason
+`POST /skills/{action_id}/execute` is: it reaches outside graph8 on the
+customer's behalf, and nothing in the path name says so.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.action_id` | `string` | yes | Skill or workflow `action_id`. |
+
+**Returns** `ApiResponse_VoicePayload_`: the envelope `{ data: VoicePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.workflows.runSkillTestSuite({ path: { action_id: "id" } });
+```
+
+---
+
+<a id="op-saveworkflowintegration"></a>
+
+### `g8.api.workflows.saveWorkflowIntegration(input)`
+
+**Connect or update a workflow integration**
+
+- HTTP: `POST /api/v1/workflows/integrations/{provider_name}`
+- operationId: `save_workflow_integration_workflows_integrations__provider_name__post` (also callable as `g8.api.call("save_workflow_integration_workflows_integrations__provider_name__post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+UPSERT: creates the integration or replaces its configuration.
+
+POST rather than PUT because that is the verb voice exposes, and one
+spelling is better than two.
+
+Whatever is stored here is used BY WORKFLOW NODES ACTING AS THE PLATFORM,
+so a key placed here is a standing grant, not a one-off.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.provider_name` | `string` | yes | Provider name. |
+| `body` | `Body_save_workflow_integration_workflows_integrations__provider_name__post` | no | Request body; fields below. |
+
+Body fields (`Body_save_workflow_integration_workflows_integrations__provider_name__post`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.api_key` | `string \| null` | no | The provider credential. WRITE-ONLY: no route on this API returns it. Omitting it on an update leaves the stored key in place. |
+| `body.configuration` | `Record<string, unknown> \| null` | no | Provider-specific settings. |
+
+**Returns** `ApiResponse_VoicePayload_`: the envelope `{ data: VoicePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.saveWorkflowIntegration({ path: { provider_name: "Example" } });
+```
+
+---
+
+<a id="op-stopexecution"></a>
+
+### `g8.api.workflows.stopExecution(input)`
+
+**Permanently stop an execution (tenant-checked)**
+
+- HTTP: `POST /api/v1/workflows/executions/{execution_id}/stop`
+- operationId: `stop_execution_workflows_executions__execution_id__stop_post` (also callable as `g8.api.call("stop_execution_workflows_executions__execution_id__stop_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `workflows:run`
+- ★ Hand-written: [`g8.workflows.stopExecution()`](../sdk-clients.md#g8-workflows-stopexecution)
+
+Stop an execution permanently. Pre-flight enforces tenant ownership.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.execution_id` | `string` | yes | Execution UUID. |
+| `body` | `Record<string, unknown>` | no | Request body; fields below. |
+
+**Returns** `Record<string, unknown>`.
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.workflows.stopExecution({ path: { execution_id: "id" } });
+```
+
+---
+
+<a id="op-testintegrationcredential"></a>
+
+### `g8.api.workflows.testIntegrationCredential(input)`
+
+**Try a Roam or Slack token**
+
+- HTTP: `POST /api/v1/workflows/integrations/{provider_name}/test`
+- operationId: `test_integration_credential_workflows_integrations__provider_name__test_post` (also callable as `g8.api.call("test_integration_credential_workflows_integrations__provider_name__test_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `workflows:run`
+
+REACHES OUTSIDE GRAPH8. Calls the provider with the token and reports
+whether it works (`success`, `error`). The token is not stored; save it with
+`PUT /workflows/integrations/{provider_name}`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.provider_name` | `"roam" \| "slack"` | yes | roam or slack. |
+| `body` | `IntegrationCredentialTest` | yes | Request body; fields below. |
+
+Body fields (`IntegrationCredentialTest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.api_key` | `string` | yes | The token to try. Not stored. min length 1 |
+
+**Returns** `ApiResponse_VoicePayload_`: the envelope `{ data: VoicePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.workflows.testIntegrationCredential({ path: { provider_name: "roam" }, body: { api_key: "example" } });
+```
+
+---
+
+<a id="op-testskillonce"></a>
+
+### `g8.api.workflows.testSkillOnce(input)`
+
+**Dry-run a skill once**
+
+- HTTP: `POST /api/v1/skills/{action_id}/test`
+- operationId: `test_skill_once_skills__action_id__test_post` (also callable as `g8.api.call("test_skill_once_skills__action_id__test_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+SPENDS NOTHING. One DRY run from a saved case or ad-hoc inputs: returns
+the resolved prompt (llm skills) or the unsent request with secrets masked
+(api skills). Never calls a model, never sends, never writes an execution.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.action_id` | `string` | yes | Skill (action) id. |
+| `body` | `SkillTestRun` | yes | Request body; fields below. |
+
+Body fields (`SkillTestRun`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.assertion_config` | `Record<string, unknown> \| null` | no | Ad-hoc only. |
+| `body.assertion_type` | `"exact" \| "contains" \| "llm_judge" \| null` | no | Ad-hoc only. |
+| `body.expected_output` | `unknown \| null` | no | Ad-hoc only: value to assert against. |
+| `body.input_data` | `Record<string, unknown> \| null` | no | Ad-hoc inputs (no saved case). |
+| `body.test_case_id` | `string \| null` | no | Run this saved case. |
+| `body.triggered_by` | `string \| null` | no | Attribution for the run history. |
+
+**Returns** `ApiResponse_VoicePayload_`: the envelope `{ data: VoicePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.testSkillOnce({ path: { action_id: "id" }, body: {} });
+```
+
+---
+
+<a id="op-updateskilltestcase"></a>
+
+### `g8.api.workflows.updateSkillTestCase(input)`
+
+**Update a test case**
+
+- HTTP: `PUT /api/v1/skills/{action_id}/test-cases/{test_case_id}`
+- operationId: `update_skill_test_case_skills__action_id__test_cases__test_case_id__put` (also callable as `g8.api.call("update_skill_test_case_skills__action_id__test_cases__test_case_id__put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+PARTIAL update despite the verb - voice exposes it as a PUT.
+
+Omitted fields are untouched; an explicit `null` CLEARS the field. Those
+are different instructions and only the second one is destructive.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.action_id` | `string` | yes | Skill or workflow `action_id`. |
+| `path.test_case_id` | `string` | yes | Test case id. |
+| `body` | `Record<string, unknown>` | yes | Request body; fields below. |
+
+**Returns** `ApiResponse_VoicePayload_`: the envelope `{ data: VoicePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.workflows.updateSkillTestCase({ path: { action_id: "id", test_case_id: "id" }, body: {} });
+```
+
+---
+
+<a id="op-updateworkflow"></a>
+
+### `g8.api.workflows.updateWorkflow(input)`
+
+**Update a workflow's graph**
+
+- HTTP: `PUT /api/v1/workflows/{action_id}`
+- operationId: `update_workflow_workflows__action_id__put` (also callable as `g8.api.call("update_workflow_workflows__action_id__put", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `workflows:run`
+- ★ Hand-written: [`g8.workflows.update()`](../sdk-clients.md#g8-workflows-update)
+
+Update a workflow. The voice update endpoint takes ``org_id`` as a
+query param and the partial body in JSON, so we forward both.
+
+Translates the public ``config`` field to voice's internal
+``skill_config`` before forwarding (see module docstring).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.action_id` | `string` | yes | Workflow action_id. |
+| `body` | `Record<string, unknown>` | yes | Request body; fields below. |
+
+**Returns** `Record<string, unknown>`.
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.workflows.updateWorkflow({ path: { action_id: "id" }, body: {} });
+```
+
+---
+
+<a id="op-validateworkflow"></a>
+
+### `g8.api.workflows.validateWorkflow(input)`
+
+**Validate a workflow graph (structural + reference resolution)**
+
+- HTTP: `POST /api/v1/workflows/validate`
+- operationId: `validate_workflow_workflows_validate_post` (also callable as `g8.api.call("validate_workflow_workflows_validate_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `workflows:run`
+- ★ Hand-written: [`g8.workflows.validate()`](../sdk-clients.md#g8-workflows-validate)
+
+Validate a workflow without saving. Returns errors + warnings +
+missing_references so an MCP client can repair before retrying create.
+
+The inner ``config`` is normalized the same way create/update do so
+a caller can validate hybrid/ReactFlow shapes and get a clean answer
+instead of a structural error from a key the validator didn't expect.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `Record<string, unknown>` | yes | Request body; fields below. |
+
+**Returns** `Record<string, unknown>`.
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.workflows.validateWorkflow({ body: {} });
+```