picked 0.0.101-next.2 → 0.0.101

package/docs/reference/management-api/schema/workflow.md

@@ -0,0 +1,1110 @@
+---
+type: reference
+layout: docs
+generated: true
+---
+
+# Workflow schema
+
+The operations and types that `workflow.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+
+## Queries
+
+### `workflow`
+
+Get a workflow by ID.
+
+```graphql
+workflow(id: ID!): Workflow @auth
+```
+
+### `workflowTools`
+
+Every tool a workflow node may run, with the arguments each accepts. Read by
+the editor to build its node palette.
+
+```graphql
+workflowTools: [WorkflowToolDefinition!]! @auth
+```
+
+### `workflows`
+
+List workflows in a workspace. Filter by name with `search` (case-insensitive
+substring) and order with `sortKey` (default `NAME`) plus `reverse`.
+
+```graphql
+workflows(first: Int, after: String, last: Int, before: String, workspaceId: ID!, search: String, sortKey: WorkflowSortKeys = NAME, reverse: Boolean = false): WorkflowConnection! @auth
+```
+
+## Mutations
+
+### `workflowCreate`
+
+Create a new workflow. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+
+```graphql
+workflowCreate(input: WorkflowCreateInput!): WorkflowCreatePayload! @auth
+```
+
+### `workflowUpdate`
+
+Update a workflow. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+
+```graphql
+workflowUpdate(input: WorkflowUpdateInput!): WorkflowUpdatePayload! @auth
+```
+
+### `workflowGraphUpdate`
+
+Apply a batch of changes to a workflow's graph, all or nothing. Requires
+scope: `ORGANIZATION_PROJECTS_UPDATE`.
+
+```graphql
+workflowGraphUpdate(input: WorkflowGraphUpdateInput!): WorkflowGraphUpdatePayload! @auth
+```
+
+### `workflowDelete`
+
+Delete a workflow. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+
+```graphql
+workflowDelete(input: WorkflowDeleteInput!): WorkflowDeletePayload! @auth
+```
+
+### `workflowTestRun`
+
+Walk a workflow's draft graph once against a supplied trigger input, holding
+every write back, and return what each node did. Nothing is stored. Requires
+scope `ORGANIZATION_WORKSPACE_UPDATE` and every scope in `Workflow.scopes`;
+a refusal names each one missing.
+
+```graphql
+workflowTestRun(input: WorkflowTestRunInput!): WorkflowTestRunPayload! @auth
+```
+
+## Types
+
+### `Workflow`
+
+```graphql
+"""
+An automation rule: when its trigger fires, its definition runs.
+
+The definition is a graph of `nodes` and `edges`, authored directly through
+`workflowCreate` and `workflowGraphUpdate`.
+"""
+type Workflow {
+  """Unique workflow identifier."""
+  id: ID!
+  """Display name of the workflow."""
+  name: String!
+  """
+  What causes this workflow to run. Chosen at create and fixed for the workflow's life.
+  """
+  trigger: WorkflowTrigger!
+  """
+  Scopes a run of this workflow acts with, derived from the tools its graph
+  names and rewritten whenever the graph is written. An author may only save a
+  graph naming tools they hold these for.
+  """
+  scopes: [Scope!]!
+  """Nodes in the workflow graph, typed by their `__typename`."""
+  nodes: [WorkflowNode!]!
+  """Edges connecting nodes in the workflow graph."""
+  edges: [WorkflowEdge!]!
+  """
+  How many times a run may visit any one node, from 1 to 100; 10 unless set. A run that
+  arrives at a node it has already visited this many times fails with `loop_limit_reached`.
+  """
+  maxNodeVisits: Int!
+  """When this workflow was created."""
+  createdAt: DateTime!
+  """When this workflow was last updated."""
+  updatedAt: DateTime!
+  """The workspace this workflow belongs to."""
+  workspace: Workspace!
+  """
+  The workspace ID this workflow belongs to (denormalised for query convenience).
+  """
+  workspaceId: ID
+  """
+  Every path this workflow's templates and rules may address: `trigger`, `nodes.<id>` by
+  the tool the node runs, and the run's variables beneath `run`, `workflow` and `current`.
+  Read by the editor's reference picker and its condition builder.
+  """
+  references: WorkflowReferences!
+}
+```
+
+### `WorkflowTriggerType`
+
+```graphql
+"""
+Which kind of trigger this is: what tells `WorkflowEventTrigger` and `WorkflowActionTrigger` apart.
+"""
+enum WorkflowTriggerType {
+  """A domain event starts the run."""
+  EVENT
+  """One action starts the run."""
+  ACTION
+}
+```
+
+### `WorkflowEventName`
+
+```graphql
+"""
+Domain events a workflow can be bound to.
+
+An action is reached through an `ACTION` trigger rather than an event, so that a
+workflow names the one action it answers to.
+"""
+enum WorkflowEventName {
+  """A workspace was created."""
+  WORKSPACE_CREATED
+  """A workspace was updated."""
+  WORKSPACE_UPDATED
+  """A workspace was deleted."""
+  WORKSPACE_DELETED
+  """A workspace version was published."""
+  WORKSPACE_PUBLISHED
+  """A feature was created."""
+  FEATURE_CREATED
+  """A feature was updated."""
+  FEATURE_UPDATED
+  """A feature was deleted."""
+  FEATURE_DELETED
+  """A step was deleted."""
+  STEP_DELETED
+  """A condition was deleted."""
+  CONDITION_DELETED
+  """An action was deleted."""
+  ACTION_DELETED
+}
+```
+
+### `WorkflowTrigger`
+
+```graphql
+"""
+What starts a workflow's run. Use `__typename` to discriminate the implementation.
+"""
+interface WorkflowTrigger {
+  """Which kind this is. `__typename` says the same thing."""
+  type: WorkflowTriggerType!
+}
+```
+
+### `WorkflowEventTrigger`
+
+```graphql
+"""A workflow started by a domain event."""
+type WorkflowEventTrigger implements WorkflowTrigger {
+  type: WorkflowTriggerType!
+  """The event that starts the run."""
+  eventName: WorkflowEventName!
+}
+```
+
+### `WorkflowActionTrigger`
+
+```graphql
+"""
+A workflow started by one action. An action starts at most one workflow.
+"""
+type WorkflowActionTrigger implements WorkflowTrigger {
+  type: WorkflowTriggerType!
+  """ID of the action whose run starts the workflow."""
+  actionId: ID!
+  """
+  The action whose run starts the workflow. Null once that action is deleted.
+  """
+  action: Action
+}
+```
+
+### `WorkflowTriggerInput`
+
+```graphql
+"""
+Input form of a workflow's trigger. Only the field matching `type` is read.
+"""
+input WorkflowTriggerInput {
+  """Which kind of trigger this is."""
+  type: WorkflowTriggerType!
+  """For EVENT triggers: the domain event that starts the run."""
+  eventName: WorkflowEventName
+  """
+  For ACTION triggers: the action to bind, which must start no workflow yet.
+  """
+  actionId: ID
+}
+```
+
+### `WorkflowNodeType`
+
+```graphql
+"""Which kind of node this is: what tells the four node types apart."""
+enum WorkflowNodeType {
+  """Where a run starts. Exactly one per workflow."""
+  ORIGIN
+  """A node that runs a registered tool."""
+  TOOL
+  """A node that branches the run on a rule."""
+  CONDITION
+  """A node that suspends the run for a duration."""
+  SLEEP
+}
+```
+
+### `WorkflowEdgeHandle`
+
+```graphql
+"""
+Edge handle for `WorkflowConditionNode` outgoing edges. Picks which branch the
+run follows when the condition resolves true / false.
+"""
+enum WorkflowEdgeHandle {
+  """The TRUE branch of a condition."""
+  TRUE
+  """The FALSE branch of a condition."""
+  FALSE
+  """A tool's error exit, which a run follows when the tool fails."""
+  ERROR
+}
+```
+
+### `WorkflowNode`
+
+```graphql
+"""
+A node in the workflow graph. Use `__typename` to discriminate the implementation.
+"""
+interface WorkflowNode {
+  """
+  Stable node identifier within the graph, and the run's durable step id.
+  """
+  id: ID!
+  """Which kind of node this is. `__typename` says the same thing."""
+  type: WorkflowNodeType!
+  """Canvas position for the dashboard editor."""
+  position: Position!
+}
+```
+
+### `WorkflowOriginNode`
+
+```graphql
+"""
+Where a run starts. Exactly one per workflow.
+
+It carries no trigger: what starts a workflow is the workflow's own `trigger`.
+"""
+type WorkflowOriginNode implements WorkflowNode {
+  id: ID!
+  type: WorkflowNodeType!
+  position: Position!
+}
+```
+
+### `WorkflowToolNode`
+
+```graphql
+"""A node that runs a registered tool with the given configuration."""
+type WorkflowToolNode implements WorkflowNode {
+  id: ID!
+  type: WorkflowNodeType!
+  position: Position!
+  """Name of the tool this node runs."""
+  tool: String!
+  """Values for the arguments that tool declares."""
+  configuration: JSON!
+}
+```
+
+### `WorkflowConditionNode`
+
+```graphql
+"""
+A node that branches the run. Outgoing edges carry `sourceHandle: TRUE | FALSE`.
+"""
+type WorkflowConditionNode implements WorkflowNode {
+  id: ID!
+  type: WorkflowNodeType!
+  position: Position!
+  """The rule evaluated when the run reaches this node."""
+  logic: JSON!
+}
+```
+
+### `WorkflowSleepNode`
+
+```graphql
+"""A node that suspends the run."""
+type WorkflowSleepNode implements WorkflowNode {
+  id: ID!
+  type: WorkflowNodeType!
+  position: Position!
+  """
+  How long the run suspends for, as a count and a unit: `500ms`, `30s`, `5m`, `2h`, `1d`. At most one day.
+  """
+  duration: String!
+}
+```
+
+### `WorkflowEdge`
+
+```graphql
+"""An edge connecting two nodes in the workflow graph."""
+type WorkflowEdge {
+  """Stable edge identifier within the graph."""
+  id: ID!
+  """Node the edge leaves."""
+  sourceNodeId: ID!
+  """Node the edge arrives at."""
+  destinationNodeId: ID!
+  """
+  The exit the edge leaves by: a `WorkflowConditionNode` branch (TRUE / FALSE), or a `WorkflowToolNode`'s error exit (ERROR).
+  """
+  sourceHandle: WorkflowEdgeHandle
+}
+```
+
+### `WorkflowToolNodeInput`
+
+```graphql
+"""
+The data a `TOOL` node carries: which registered tool runs, and with what.
+
+A tool's arguments belong to one node in one workflow, so they sit on the node
+rather than on an entity of their own.
+"""
+input WorkflowToolNodeInput {
+  """Name of a registered tool, as `workflowTools` lists it."""
+  name: String!
+  """
+  Values for the arguments that tool declares. Omit for a tool that takes none.
+  """
+  configuration: JSON
+}
+```
+
+### `WorkflowConditionNodeInput`
+
+```graphql
+"""The data a `CONDITION` node carries: the rule that picks the branch."""
+input WorkflowConditionNodeInput {
+  """
+  The rule evaluated when the run reaches the node. Outgoing edges carry `sourceHandle`.
+  """
+  logic: JSON!
+}
+```
+
+### `WorkflowSleepNodeInput`
+
+```graphql
+"""The data a `SLEEP` node carries: how long the run suspends."""
+input WorkflowSleepNodeInput {
+  """A count and a unit: `500ms`, `30s`, `5m`, `2h`, `1d`. At most one day."""
+  duration: String!
+}
+```
+
+### `WorkflowNodeInput`
+
+```graphql
+"""
+Input form of a node in the workflow graph. Every node carries an id, a kind and
+a position; the block matching its kind carries the rest. `ORIGIN` has no block.
+"""
+input WorkflowNodeInput {
+  """Graph-unique identifier, and the run's durable step id."""
+  id: ID!
+  """Which kind of node to create."""
+  type: WorkflowNodeType!
+  """Canvas position."""
+  position: PositionInput!
+  """For TOOL nodes: the tool to run and its arguments."""
+  tool: WorkflowToolNodeInput
+  """For CONDITION nodes: the rule that picks the branch."""
+  condition: WorkflowConditionNodeInput
+  """For SLEEP nodes: how long the run suspends."""
+  sleep: WorkflowSleepNodeInput
+}
+```
+
+### `WorkflowEdgeInput`
+
+```graphql
+"""Input form of an edge in the workflow graph."""
+input WorkflowEdgeInput {
+  """Graph-unique identifier."""
+  id: ID!
+  """Node the edge leaves."""
+  sourceNodeId: ID!
+  """Node the edge arrives at."""
+  destinationNodeId: ID!
+  """
+  The exit the edge leaves by: a `WorkflowConditionNode` branch (TRUE / FALSE), or a `WorkflowToolNode`'s error exit (ERROR).
+  """
+  sourceHandle: WorkflowEdgeHandle
+}
+```
+
+### `WorkflowArgumentType`
+
+```graphql
+"""
+The type an argument takes.
+
+Every argument also accepts a Liquid template — `{{ nodes.n1.leads[0].id }}` — in place of a
+literal. A template that is the whole value keeps the type of what it names; one mixed with
+text renders to text and is read as the declared type when the node runs.
+"""
+enum WorkflowArgumentType {
+  """A text value."""
+  STRING
+  """A numeric value."""
+  NUMBER
+  """A true / false value."""
+  BOOLEAN
+  """Any JSON value."""
+  JSON
+  """
+  A query over one resource, written as a string in that resource's own query language.
+  A template may stand in a clause's value and nowhere else.
+  """
+  QUERY
+  """
+  One record of the resource type `resourceType` names, written as a reference to it.
+  The value resolves to that record's identifier before the tool runs.
+  """
+  REFERENCE
+}
+```
+
+### `WorkflowToolArgument`
+
+```graphql
+"""One argument a tool accepts."""
+type WorkflowToolArgument {
+  """Argument name, as it appears in a tool node's `configuration`."""
+  name: String!
+  """
+  The argument's name for authors, such as `Lead`, which an editor's form field takes.
+  """
+  label: String!
+  """The type the argument takes."""
+  type: WorkflowArgumentType!
+  """
+  For a `JSON` argument, the structured shape its value takes, such as `labels` — the
+  editor renders the control that shape calls for and validates against it. Null for
+  free-form JSON. Unlike `type` this vocabulary is open: an editor that does not know the
+  shape edits the value as raw JSON.
+  """
+  shape: String
+  """
+  For a `REFERENCE` argument, the resource type the value must name, such as `Lead` — the
+  editor offers only the paths that produce one. Null otherwise. Like `shape` this
+  vocabulary is open, and it is matched against `WorkflowReferenceEntry.resourceType` by
+  equality.
+  """
+  resourceType: String
+  """
+  For a `STRING` argument, the literals it admits, so the editor offers a choice rather
+  than free text. Null when the argument takes any string.
+  """
+  options: [String!]
+  """Whether the argument must be given."""
+  required: Boolean!
+  """What the argument is for."""
+  description: String!
+}
+```
+
+### `WorkflowToolDefinition`
+
+```graphql
+"""A tool a workflow node may run."""
+type WorkflowToolDefinition {
+  """Name a node references."""
+  name: String!
+  """The tool's name for authors, such as `External endpoint`."""
+  label: String!
+  """What the tool does."""
+  description: String!
+  """The arguments it accepts."""
+  arguments: [WorkflowToolArgument!]!
+  """
+  The scopes a run must hold for this tool to run. Empty for a tool that touches
+  no data. Read by the editor to show which tools the viewer can place.
+  """
+  scopes: [Scope!]!
+}
+```
+
+### `WorkflowReferenceType`
+
+```graphql
+"""How a reference entry's value reads."""
+enum WorkflowReferenceType {
+  """A text value."""
+  STRING
+  """A numeric value."""
+  NUMBER
+  """A true / false value."""
+  BOOLEAN
+  """Any JSON value; paths beneath it are not listed."""
+  JSON
+  """A record whose fields are listed beneath it."""
+  OBJECT
+  """
+  A list of records, addressed by index; `.0.` entries describe each item and `.truncated` says whether the list was cut at its bound.
+  """
+  COLLECTION
+}
+```
+
+### `WorkflowReferenceEntry`
+
+```graphql
+"""
+One path a workflow's templates and rules may address, with what the picker shows for it.
+
+The path is relative to its owner and written in the dotted form a rule reads —
+`action.responses.email` beneath `trigger`, `leads.0.id` beneath `nodes.<id>`, and
+`current.startedAt` from the root for a variable. A template writes an index as
+`leads[0].id`.
+"""
+type WorkflowReferenceEntry {
+  """The path, relative to its owner."""
+  path: String!
+  """How the value reads."""
+  type: WorkflowReferenceType!
+  """A human-readable label."""
+  label: String!
+  """A few words on what the path holds, shown beneath the label."""
+  description: String!
+  """A representative value, declared with the tool."""
+  example: JSON!
+  """
+  The resource type this path materialises to, such as `Lead`, for a path that names a
+  whole record or that record's identifier. Null for everything else. Matched against
+  `WorkflowToolArgument.resourceType` by equality.
+  """
+  resourceType: String
+}
+```
+
+### `WorkflowToolReferences`
+
+```graphql
+"""
+The paths one tool's output makes addressable beneath `nodes.<id>` for every node running it.
+"""
+type WorkflowToolReferences {
+  """The tool name, as a node's `tool` names it."""
+  tool: String!
+  """The addressable paths, relative to the node."""
+  entries: [WorkflowReferenceEntry!]!
+}
+```
+
+### `WorkflowReferences`
+
+```graphql
+"""
+Everything one workflow's templates and rules may address: the trigger, resolved from the
+workflow's trigger, each tool's output with its shapes resolved against the workspace's
+fields, and the run's variables. The editor filters the tool outputs to the nodes upstream of
+the one being edited.
+"""
+type WorkflowReferences {
+  """
+  Paths beneath `trigger`: `action` and its responses on an action-triggered workflow, `event` on an event-triggered one.
+  """
+  trigger: [WorkflowReferenceEntry!]!
+  """Paths beneath `nodes.<id>`, by the tool the node runs."""
+  tools: [WorkflowToolReferences!]!
+  """
+  The run's variables, the same on every workflow, each path written from its root:
+  `run.id`, `run.startedAt` and `run.preview` for the run; `workflow.id` and
+  `workflow.name` for the workflow; `current.id`, `current.startedAt` and `current.visit`
+  for the node that reads them. Times are ISO 8601 in UTC. A save refuses any other path
+  beneath these three roots.
+  """
+  variables: [WorkflowReferenceEntry!]!
+}
+```
+
+### `WorkflowChangesInput`
+
+```graphql
+"""Container for all change operations on a workflow graph."""
+input WorkflowChangesInput {
+  """Node changes in the workflow graph."""
+  nodes: WorkflowNodeChangesInput
+  """Edge changes connecting nodes."""
+  edges: WorkflowEdgeChangesInput
+}
+```
+
+### `WorkflowNodeChangesInput`
+
+```graphql
+"""Node-level changes within a `workflowGraphUpdate` batch."""
+input WorkflowNodeChangesInput {
+  """
+  Nodes to create, each named by its `clientId` until the server mints its id.
+  """
+  create: [WorkflowNodeCreateData!]
+  """
+  Fields to merge into the nodes they name. An id the graph lacks is ignored.
+  """
+  update: [WorkflowNodeUpdateData!]
+  """Node ids to delete. Edges touching a deleted node are dropped with it."""
+  delete: [ID!]
+}
+```
+
+### `WorkflowNodeCreateData`
+
+```graphql
+"""
+A node to add to the graph. The block matching `type` carries its data.
+"""
+input WorkflowNodeCreateData {
+  """
+  Client-generated id, for cross-referencing from edges in the same change set.
+  The server mints the persisted id and returns the pair in `idMappings`.
+  """
+  clientId: ID!
+  """Which kind of node to create."""
+  type: WorkflowNodeType!
+  """Canvas position."""
+  position: PositionInput!
+  """For TOOL nodes: the tool to run and its arguments."""
+  tool: WorkflowToolNodeInput
+  """For CONDITION nodes: the rule that picks the branch."""
+  condition: WorkflowConditionNodeInput
+  """For SLEEP nodes: how long the run suspends."""
+  sleep: WorkflowSleepNodeInput
+}
+```
+
+### `WorkflowNodeUpdateData`
+
+```graphql
+"""
+Fields to merge into an existing node. Omit a field to leave it unchanged; a
+kind block that is given replaces that kind's data whole.
+"""
+input WorkflowNodeUpdateData {
+  """Id of the node to change."""
+  id: ID!
+  """New canvas position."""
+  position: PositionInput
+  """For TOOL nodes: the tool to run and its arguments."""
+  tool: WorkflowToolNodeInput
+  """For CONDITION nodes: the rule that picks the branch."""
+  condition: WorkflowConditionNodeInput
+  """For SLEEP nodes: how long the run suspends."""
+  sleep: WorkflowSleepNodeInput
+}
+```
+
+### `WorkflowEdgeChangesInput`
+
+```graphql
+"""Edge-level changes within a `workflowGraphUpdate` batch."""
+input WorkflowEdgeChangesInput {
+  """
+  Edges to create, each named by its `clientId` until the server mints its id.
+  """
+  create: [WorkflowEdgeCreateInput!]
+  """
+  Fields to merge into the edges they name. An id the graph lacks is ignored.
+  """
+  update: [WorkflowEdgeUpdateInput!]
+  """Edge ids to delete."""
+  delete: [ID!]
+}
+```
+
+### `WorkflowEdgeCreateInput`
+
+```graphql
+"""
+An edge to add to the graph. Each endpoint is named one way: by its persisted id, or by the client id of a node created in the same change set.
+"""
+input WorkflowEdgeCreateInput {
+  """
+  Client-generated id. The server mints the persisted id and returns the pair in `idMappings`.
+  """
+  clientId: ID!
+  """
+  Node the edge leaves, by persisted id. Mutually exclusive with `sourceNodeClientId`.
+  """
+  sourceNodeId: ID
+  """
+  Node the edge leaves, created in this same change set. Mutually exclusive with `sourceNodeId`.
+  """
+  sourceNodeClientId: ID
+  """
+  Node the edge arrives at, by persisted id. Mutually exclusive with `destinationNodeClientId`.
+  """
+  destinationNodeId: ID
+  """
+  Node the edge arrives at, created in this same change set. Mutually exclusive with `destinationNodeId`.
+  """
+  destinationNodeClientId: ID
+  """
+  The exit the edge leaves by: a `WorkflowConditionNode` branch (TRUE / FALSE), or a `WorkflowToolNode`'s error exit (ERROR).
+  """
+  sourceHandle: WorkflowEdgeHandle
+}
+```
+
+### `WorkflowEdgeUpdateInput`
+
+```graphql
+"""
+Fields to merge into an existing edge. Omit a field to leave it unchanged.
+"""
+input WorkflowEdgeUpdateInput {
+  """Id of the edge to change."""
+  id: ID!
+  """New source node id."""
+  sourceNodeId: ID
+  """New destination node id."""
+  destinationNodeId: ID
+  """New exit: TRUE or FALSE off a condition, ERROR off a tool."""
+  sourceHandle: WorkflowEdgeHandle
+}
+```
+
+### `WorkflowConnection`
+
+```graphql
+"""
+Relay-style connection of workflows, with both an `edges` list and a flat `nodes` accessor.
+"""
+type WorkflowConnection {
+  """List of workflow edges."""
+  edges: [WorkflowConnectionEdge!]!
+  """
+  Flat list of workflows, equivalent to `edges[].node`. Convenience accessor.
+  """
+  nodes: [Workflow!]!
+  """Pagination metadata."""
+  pageInfo: PageInfo!
+  """Total number of workflows."""
+  totalCount: Int!
+}
+```
+
+### `WorkflowConnectionEdge`
+
+```graphql
+"""Edge type for `WorkflowConnection`."""
+type WorkflowConnectionEdge {
+  """Pagination cursor for this edge."""
+  cursor: String!
+  """The workflow."""
+  node: Workflow!
+}
+```
+
+### `WorkflowCreateInput`
+
+```graphql
+"""Input for `workflowCreate`."""
+input WorkflowCreateInput {
+  """Workspace ID to create the workflow in."""
+  workspaceId: ID!
+  """
+  Display name. Omit it to derive one from the trigger, suffixed until unused.
+  """
+  name: String
+  """What causes this workflow to run."""
+  trigger: WorkflowTriggerInput!
+  """Nodes of the graph to build. The `ORIGIN` node is added automatically."""
+  nodes: [WorkflowNodeInput!]
+  """Edges of the graph to build. Read only when `nodes` is given."""
+  edges: [WorkflowEdgeInput!]
+}
+```
+
+### `WorkflowCreatePayload`
+
+```graphql
+"""Payload returned by `workflowCreate`."""
+type WorkflowCreatePayload {
+  """The created workflow."""
+  workflow: Workflow
+}
+```
+
+### `WorkflowUpdateInput`
+
+```graphql
+"""
+Input for `workflowUpdate`. Omit a field to leave it unchanged. The trigger is fixed at create.
+"""
+input WorkflowUpdateInput {
+  """Workflow ID."""
+  id: ID!
+  """New display name."""
+  name: String
+  """
+  How many times a run may visit any one node, from 1 to 100. A value outside that range is refused.
+  """
+  maxNodeVisits: Int
+}
+```
+
+### `WorkflowGraphUpdateInput`
+
+```graphql
+"""
+Input for `workflowGraphUpdate`.
+
+The whole change set is applied or none of it is: the graph is validated once,
+after every change lands, so a set that would leave it unrunnable is refused
+entire and nothing is written.
+"""
+input WorkflowGraphUpdateInput {
+  """The workflow to update."""
+  workflowId: ID!
+  """New display name."""
+  name: String
+  """
+  How many times a run may visit any one node, from 1 to 100, set with the change set.
+  A value outside that range comes back in `errors` and nothing is written.
+  """
+  maxNodeVisits: Int
+  """All changes to apply to the workflow graph."""
+  changes: WorkflowChangesInput!
+}
+```
+
+### `WorkflowGraphUpdatePayload`
+
+```graphql
+"""Payload returned by `workflowGraphUpdate`."""
+type WorkflowGraphUpdatePayload {
+  """
+  The updated workflow with all changes applied, or null when `errors` is non-empty.
+  """
+  workflow: Workflow
+  """Validation errors. An empty array indicates success."""
+  errors: [UserError!]!
+  """
+  What the author should look at on a graph that saved. The change was written;
+  each entry names a node that will not do what its author meant when the
+  workflow runs: one no path from the origin reaches, a sleep of no length, or
+  one calling an origin the project has not registered as an external API.
+  Empty when `errors` is non-empty.
+  """
+  warnings: [UserError!]!
+  """
+  The persisted id minted for each created node and edge. Empty when `errors` is non-empty.
+  """
+  idMappings: WorkflowIdMappings!
+}
+```
+
+### `WorkflowIdMappings`
+
+```graphql
+"""
+The persisted ids a change set's creates were given, keyed by the client ids that named them.
+"""
+type WorkflowIdMappings {
+  """Node id mappings, in the order the nodes were created."""
+  nodes: [IdMapping!]!
+  """Edge id mappings, in the order the edges were created."""
+  edges: [IdMapping!]!
+}
+```
+
+### `WorkflowUpdatePayload`
+
+```graphql
+"""Payload returned by `workflowUpdate`."""
+type WorkflowUpdatePayload {
+  """The updated workflow."""
+  workflow: Workflow
+}
+```
+
+### `WorkflowDeleteInput`
+
+```graphql
+"""Input for `workflowDelete`."""
+input WorkflowDeleteInput {
+  """Workflow ID."""
+  id: ID!
+}
+```
+
+### `WorkflowDeletePayload`
+
+```graphql
+"""Payload returned by `workflowDelete`."""
+type WorkflowDeletePayload {
+  """ID of the deleted workflow."""
+  deletedWorkflowId: ID
+}
+```
+
+### `WorkflowTestRunInput`
+
+```graphql
+"""
+Input for `workflowTestRun`. Supply the field the workflow's trigger takes and
+omit the other.
+"""
+input WorkflowTestRunInput {
+  """The workflow to test-run."""
+  workflowId: ID!
+  """
+  For an `ACTION` trigger: the answers the action carries, keyed by field key.
+  Templates and rules reach them as `trigger.action.responses.<key>`. Defaults to
+  no answers. Refused on an `EVENT` trigger.
+  """
+  responses: JSON
+  """
+  For an `EVENT` trigger: the entity the event is about, reached as
+  `trigger.entityId`. Defaults to the workflow's workspace ID.
+  """
+  entityId: ID
+}
+```
+
+### `WorkflowTestRunStatus`
+
+```graphql
+"""How a test run ended."""
+enum WorkflowTestRunStatus {
+  """Every node the walk reached did its work, or held its write back."""
+  COMPLETED
+  """A node failed and the walk stopped there."""
+  FAILED
+}
+```
+
+### `WorkflowTestRunTaskStatus`
+
+```graphql
+"""How one task of a test run ended."""
+enum WorkflowTestRunTaskStatus {
+  """The node did its work. A tool that reads ran for real."""
+  SUCCEEDED
+  """The node failed, and the walk stopped there."""
+  FAILED
+  """
+  The tool writes, so the test run did not run it. `input` holds what it would
+  have sent; it recorded nothing, so a later node addressing it finds nothing.
+  """
+  SKIPPED
+}
+```
+
+### `WorkflowTestRunTask`
+
+```graphql
+"""
+One visit a test run made to a node. Never stored: it exists only in the payload that
+returned it.
+"""
+type WorkflowTestRunTask {
+  """The node's ID."""
+  nodeId: ID!
+  """
+  The node's place in the walk. The `ORIGIN` node is 0 and is not listed.
+  """
+  index: Int!
+  """
+  Which visit of its node the task is, from 1. A walk that re-enters a node lists each visit.
+  """
+  visit: Int!
+  """The node's kind. Never `ORIGIN`."""
+  type: WorkflowTaskType!
+  """The tool a `TOOL` node runs."""
+  tool: String
+  """How the task ended."""
+  status: WorkflowTestRunTaskStatus!
+  """
+  A `TOOL` node's arguments with every template resolved, as the tool received
+  them or, when `SKIPPED`, would have. A `SLEEP` node's `{ duration }`.
+  """
+  input: JSON
+  """
+  What a `TOOL` node recorded, in the form later nodes read it: a reference is a
+  `$ref` envelope naming the tool and what it resolves. Null when skipped.
+  """
+  output: JSON
+  """The branch a `CONDITION` node took."""
+  branch: WorkflowEdgeHandle
+  """
+  Why the task failed, naming the node, its tool and at most an argument.
+  """
+  failureMessage: String
+}
+```
+
+### `WorkflowTestRun`
+
+```graphql
+"""
+A workflow's draft graph walked once against a supplied trigger, with every
+write held back.
+
+Tools that read (`search_leads`, `http` with `GET` or `HEAD`) run for real;
+tools that write are `SKIPPED`. `SLEEP` nodes do not wait. Nothing is stored:
+no run appears in `Workflow.runs`, no operation is recorded and no event is
+published.
+"""
+type WorkflowTestRun {
+  """How the run ended."""
+  status: WorkflowTestRunStatus!
+  """Why the run stopped, when `status` is `FAILED`."""
+  failureMessage: String
+  """Every node the walk reached after the `ORIGIN`, in order."""
+  tasks: [WorkflowTestRunTask!]!
+}
+```
+
+### `WorkflowTestRunPayload`
+
+```graphql
+"""Payload returned by `workflowTestRun`."""
+type WorkflowTestRunPayload {
+  """The test run, or null when `userErrors` is non-empty."""
+  testRun: WorkflowTestRun
+  """
+  Why the input cannot start this workflow. Codes: `RESPONSES_NOT_ACCEPTED`,
+  `INVALID_RESPONSES`, `ACTION_DELETED`, `TRIGGER_UNUSABLE`.
+  """
+  userErrors: [UserError!]!
+}
+```
+
+### `WorkflowSortKeys`
+
+```graphql
+"""
+Sort keys for `workflows(...)`. Pair with `reverse: true` to flip the order
+(`NAME` + `reverse: false` sorts A→Z; `CREATED_AT` + `reverse: true` is newest-first).
+"""
+enum WorkflowSortKeys {
+  """Sort by `name` (alphabetical)."""
+  NAME
+  """Sort by `createdAt`."""
+  CREATED_AT
+  """Sort by `updatedAt`."""
+  UPDATED_AT
+}
+```