---
id: workflow-update
title: "Update a workflow"
description: "Pushes a new version of the definition. The body can be the bare definition or `{ definition, mode }`, where `mode` controls versioning:"
sidebar_label: "Update a workflow"
hide_title: true
hide_table_of_contents: true
api: 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
sidebar_class_name: "put api-method"
info_path: docs/api/workflows
custom_edit_url: null
---

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a workflow"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/workflows/definitions/{id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>



Pushes a new version of the definition. The body can be the bare definition or `{ definition, mode }`, where `mode` controls versioning:

- `auto` (default): overwrites the latest revision, unless an active alias points at it, in which case a new revision is created. Safe by default: you never rewrite something that is live.
- `new-revision`: always create a new revision.
- `overwrite`: always rewrite the latest revision.

If the `{id}` in the URL is a key that doesn't exist yet, the workflow is created instead and the response is 201: `PUT` doubles as an upsert, so a git repository of definitions can push them without knowing which ones already exist.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Workflow reference: a server-minted id (`wf_...`) or the workflow's client-chosen key (lowercase slug, unique per organization).","example":"wf_ifWBbWfpug0n"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","properties":{"definition":{"title":"WorkflowDefinition","type":"object","description":"The workflow definition: the same document the visual editor saves. Steps are a map of step id to step; triggers are always rebuilt server-side from steps of type `trigger`, so a client-supplied `triggers` value is discarded.","required":["name","steps"],"properties":{"name":{"type":"string","description":"Human-readable workflow name.","example":"AMI drift scanner"},"key":{"type":"string","description":"Client-chosen slug (`^[a-z0-9][a-z0-9-]{0,62}$`), unique per organization and immutable. Enables GitOps-style upserts via `PUT /workflows/definitions/{key}`.","example":"ami-drift-scanner"},"description":{"type":"string","example":"Scans deployed scopes for outdated AMIs."},"path":{"type":"string","description":"Folder in the workflows tree. Defaults to `/`.","example":"/action-items/ami-drift"},"nrn":{"type":"string","description":"The nullplatform resource name the workflow is scoped to. Defaults to the caller's organization."},"steps":{"type":"object","description":"Map of step id to step definition. Step ids are alphanumeric (no hyphens).","additionalProperties":{"type":"object"}},"connections":{"type":"array","description":"Edges between steps.","items":{"type":"object"}},"variables":{"type":"object","description":"Per-run variables with optional `initialValue`."},"metadata":{"type":"object"},"semanticVersion":{"type":"string","description":"Optional version label stored on the revision.","example":"1.2.0"}},"additionalProperties":true},"mode":{"type":"string","enum":["auto","overwrite","new-revision"],"default":"auto"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The definition was updated. `mode` says whether the latest revision was overwritten or a new one created.","content":{"application/json":{"schema":{"title":"PublishResult","type":"object","properties":{"workflow":{"title":"Workflow","type":"object","required":["id","name","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"wf_ifWBbWfpug0n"},"key":{"type":"string","example":"ami-drift-scanner"},"name":{"type":"string","example":"AMI drift scanner"},"description":{"type":"string"},"path":{"type":"string","example":"/action-items/ami-drift"},"organizationId":{"type":"string"},"nrn":{"type":"string"},"metadata":{"type":"object"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"revision":{"title":"Revision","type":"object","required":["workflowId","revision","createdAt"],"properties":{"workflowId":{"type":"string","example":"wf_ifWBbWfpug0n"},"revision":{"type":"integer","description":"Revision number, starting at 1.","example":3},"definition":{"type":"object","nullable":true,"description":"The full definition. `null` in list responses unless `includeDefinition=true`."},"createdAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string"},"releaseNotes":{"type":"string"},"semanticVersion":{"type":"string"}}},"latestAlias":{"allOf":[{"title":"Alias","type":"object","required":["workflowId","name","revision","active","updatedAt"],"properties":{"workflowId":{"type":"string","example":"wf_ifWBbWfpug0n"},"name":{"type":"string","example":"live"},"revision":{"type":"integer","example":3},"active":{"type":"boolean","description":"Whether the alias's triggers are activated."},"updatedAt":{"type":"string","format":"date-time"},"updatedBy":{"type":"string"},"metadata":{"type":"object"},"triggerStates":{"type":"object","description":"Map of trigger id to its activation state.","additionalProperties":{"title":"TriggerState","type":"object","properties":{"status":{"type":"string","enum":["pending","live","failed","inactive"]},"activatedAt":{"type":"string","format":"date-time"},"deactivatedAt":{"type":"string","format":"date-time"},"lastError":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}}},"runtimeMetadata":{"type":"object","description":"Runtime data such as the trigger's `webhookUrl`.","properties":{"webhookUrl":{"type":"string"}},"additionalProperties":true}}}}}}],"description":"The auto-maintained `latest` alias. Can be `null`."},"mode":{"type":"string","description":"How the write was applied (update responses only).","enum":["created","overwritten","new-revision"]},"warnings":{"type":"array","items":{"title":"ConfigWarning","type":"object","description":"Emitted when the definition references a config entry with no value at any visible place.","properties":{"code":{"type":"string","enum":["CONFIG_ENTRY_UNRESOLVED"]},"name":{"type":"string","example":"NP_API_KEY"},"kind":{"type":"string","enum":["secret","var"]}}}}}}}}},"201":{"description":"No workflow matched the key, so one was created (upsert).","content":{"application/json":{"schema":{"title":"PublishResult","type":"object","properties":{"workflow":{"title":"Workflow","type":"object","required":["id","name","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"wf_ifWBbWfpug0n"},"key":{"type":"string","example":"ami-drift-scanner"},"name":{"type":"string","example":"AMI drift scanner"},"description":{"type":"string"},"path":{"type":"string","example":"/action-items/ami-drift"},"organizationId":{"type":"string"},"nrn":{"type":"string"},"metadata":{"type":"object"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"revision":{"title":"Revision","type":"object","required":["workflowId","revision","createdAt"],"properties":{"workflowId":{"type":"string","example":"wf_ifWBbWfpug0n"},"revision":{"type":"integer","description":"Revision number, starting at 1.","example":3},"definition":{"type":"object","nullable":true,"description":"The full definition. `null` in list responses unless `includeDefinition=true`."},"createdAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string"},"releaseNotes":{"type":"string"},"semanticVersion":{"type":"string"}}},"latestAlias":{"allOf":[{"title":"Alias","type":"object","required":["workflowId","name","revision","active","updatedAt"],"properties":{"workflowId":{"type":"string","example":"wf_ifWBbWfpug0n"},"name":{"type":"string","example":"live"},"revision":{"type":"integer","example":3},"active":{"type":"boolean","description":"Whether the alias's triggers are activated."},"updatedAt":{"type":"string","format":"date-time"},"updatedBy":{"type":"string"},"metadata":{"type":"object"},"triggerStates":{"type":"object","description":"Map of trigger id to its activation state.","additionalProperties":{"title":"TriggerState","type":"object","properties":{"status":{"type":"string","enum":["pending","live","failed","inactive"]},"activatedAt":{"type":"string","format":"date-time"},"deactivatedAt":{"type":"string","format":"date-time"},"lastError":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}}},"runtimeMetadata":{"type":"object","description":"Runtime data such as the trigger's `webhookUrl`.","properties":{"webhookUrl":{"type":"string"}},"additionalProperties":true}}}}}}],"description":"The auto-maintained `latest` alias. Can be `null`."},"mode":{"type":"string","description":"How the write was applied (update responses only).","enum":["created","overwritten","new-revision"]},"warnings":{"type":"array","items":{"title":"ConfigWarning","type":"object","description":"Emitted when the definition references a config entry with no value at any visible place.","properties":{"code":{"type":"string","enum":["CONFIG_ENTRY_UNRESOLVED"]},"name":{"type":"string","example":"NP_API_KEY"},"kind":{"type":"string","enum":["secret","var"]}}}}}}}}},"4XX":{"description":"Client error. The body says what went wrong: an error `type`, a human-readable `detail`, and, on validation failures, one entry per offending field.","content":{"application/problem+json":{"schema":{"title":"Problem","type":"object","description":"The standard error body (RFC 7807 problem details, served as `application/problem+json`).","properties":{"type":{"type":"string","description":"Error type URI, e.g. `https://workflow-system.dev/errors/workflow-not-found`.","example":"https://workflow-system.dev/errors/workflow-not-found"},"title":{"type":"string","example":"Not found"},"status":{"type":"integer","example":404},"detail":{"type":"string","example":"No workflow with id wf_ifWBbWfpug0n exists"},"instance":{"type":"string","example":"/workflows/definitions/wf_ifWBbWfpug0n"},"errors":{"type":"array","description":"Present on validation failures: one entry per offending field.","items":{"type":"object","properties":{"path":{"type":"string","example":"/steps/scan/config"},"message":{"type":"string","example":"must have required property 'code'"}}}}}}}}},"5XX":{"description":"Unexpected server error.","content":{"application/problem+json":{"schema":{"title":"Problem","type":"object","description":"The standard error body (RFC 7807 problem details, served as `application/problem+json`).","properties":{"type":{"type":"string","description":"Error type URI, e.g. `https://workflow-system.dev/errors/workflow-not-found`.","example":"https://workflow-system.dev/errors/workflow-not-found"},"title":{"type":"string","example":"Not found"},"status":{"type":"integer","example":404},"detail":{"type":"string","example":"No workflow with id wf_ifWBbWfpug0n exists"},"instance":{"type":"string","example":"/workflows/definitions/wf_ifWBbWfpug0n"},"errors":{"type":"array","description":"Present on validation failures: one entry per offending field.","items":{"type":"object","properties":{"path":{"type":"string","example":"/steps/scan/config"},"message":{"type":"string","example":"must have required property 'code'"}}}}}}}}}}}
>
  
</StatusCodes>