---
id: workflow-create
title: Create a workflow
description: >-
  Creates a workflow. The request body is the definition document itself, not
  wrapped in any envelope.
sidebar_label: Create a workflow
hide_title: true
hide_table_of_contents: true
api: >-
  eJztWW1z27gR/is7mM4kmVKSk6a9Vp1+cBzn6raxPX6J78bnhhCxlHABAQYApeg8+u+dBUiJkijJSb+0M8mHRCHxsrt49sHuw0fm+dix4T27M/ZTrswMBOZSSy+NduwhYQJdZmVJ/2dDdmKRe3TAYVaP78PNBMHi5wqdh5ERc5AO/ARbC4EwWVWg9iC9Q5UnoI2HmeVliQKkBq7ngHqKypTY/0X/onth1WYPcJ5b74B7sDiVjpZ8mcBM+knYiVfe9AoutedSo4BUkZE+Ba4kd1Aaqb3UY5ovfZ9WPzd+Qk9spR3M0Q/BWzkeo3VgtJqDxbF0Hi3MJqhhbirgmZdT7hG4jsuGda4wR4s6o7UcZha9A2Nhyq3kI4UUCO5hwqcI2sCUqwppOwpRLjUOIaOAkj+uyjJE4YBrEZyy6EqjHYKSzoeIFlBpgRbSGbda6rFLwZlgXMY1OPRxEM892hm3wvVZwkyJNuxwJtiQNREdhn2RJaw+uTdGzNnwkWVGe9SefvKyVDILcwe/Ojr+R+ayCRacfnnpFbLhEjdvl6fNEubnJb0zo18x82wTRGtHu0LJMLjteIErvNCTqXQVV4BCemPB8Sm6Plx7LB1wi8Ch4CWYHJzHEqQAb8LPv66ONAxTMz53YHFUSeXBoZ2i7TkpEHJrijDF0TJkO6T13DShEHPIlETte66imBDCmrXT+lClAyFdxq1A0a/DKi0KSi3NC4p02IFSqrR0KF6io0CGtxTQGDPnrdTjrZj9vSq47lnkgnC1Ch/Npv3wCy/KcCDH789AWJl7cBnXGi1bJOwTzg/vcRKdzCbGoQanqjE8T/99z3u/HfX+8lD/23t4PEr+9Grxu/RFApWWnyuEEi0YO+Za/hbBTBiWRVF5MrYPpzomw4/SX5Su5/xcIVSlQ0rqqeSQXt7ewKBxyg1aHDR4/ITzRbruIy9kL/jYa/m45sy2r6vZ1xnXDgSWysxRgMtMiQ5yY8FUXnCPAo7fn7k+LVpyPzkcuXdGUWJKHQC79AO8RezDW8x5pSiHDaSDDVcGRCxG96THwg2WjtHe2nY6sp1MulKqVNznxhbEG6ayGQZorNlDIA3OUo6sm0XDMq4U2mdu7ShDECJyV6bsyOv3nXnYyvCYtiBFk5LlhOuqQCszeK4NTOblBLV7QRHiQoQ5XF2upcu6CYtFQpSlMYsX1moAt5bPt0w8FWN0MEI/Q4I4+UWbheB3r76k8sP+X6Lt2Uq32D/cUKaMfkAawsDVB2KMNES2QM8F97xj74Q5LLj2MvuA1u0A9boBF81O0zgDFB+hAueNRQFG1/dKvEHXYfiy/6p/FBzuDry3FS4Wi2BVVlnp52x4/8hGyC3a44qS5P5h8UDEF6+tEK9XRy/pnz30P+Mu3oGRNr/6+rmsRkq6yRW6SvmOm2eda5ttuy6wjsltEpeCJQ2T1wYf05iqFPXvLWaXYj8PzfKPMr97M7rLy2p8pPfw9AHm23WFHLgU9hLmHu57Enm1SeSsIxC7+O1QUqxi32EZESD3bMjoTHpeFkhTVkf0xCkE8yZN2lC5ap7th0qDsjPBWuu0Td+CSmvK10JmzdA4UWqPY7Rb/NDYD7oqRmiTWFfXlfHLNUL4Q8DHsqTr4D66dIjlIjd0XUt5pdQa+6c0J6VrkmraZYXroNIKnSOCzFQlcFVL/o3WjlT5DQdfT3nTkVMhcAq5w3Pj18h9NeAg/wagxF7jmFqCQFtKXeSBGxvUxFdfAZmaZVrICc0H7meb/wJCh/lD0faHwLYGntrk1biRMQq53gLl3QT9BG1s5ChUz9xG5V53XqL/Tcm8nLIDBnvZpjbk2nP/lAqgroDqWXURJKlzjT6ERo/W2lvh1Li5ae198GajVasOGCcMdVUQxErUIj5REUs5lwoJb1LXh/XQnNvXRljgN01T3PlTa43tiuy6fwU6x8cdKA0FoOh6EVi80rTZ+51nvEWRcQLQaOrJJ8CjmlGf6TMH6QxHE2M+3VoVavmNNFy+7DLpUHm1WGxJLjcHBY4+nHANI6z5NRaWnTHZ6irNLHYIVnoMtRivG9znMWlaHE26SKjMG0DV7EoawxQtLeGR0lvjrLfkCYJUI1d0VOerwrsG/YnRuRzfxRkHlYTTgjYVUaXZ0JxsLc0EtSoLywJqb+exKl/KMdwH+Ynspc66VDzD7WPtxtgqGCcX5+/Ofvx4en5z9fPH2/Or0+uLf304fRv8P0yv55cfjy/PPv7z9OdQBErdzeH1XlFoYqE3YQ+L5k/CXv/003a5Hbt6QMqzKNYFkc6RGjIjdWpGr2fW6PGQxK0wEFLaPE2Aw2RdeUgFei4VvdIioaZiypUUkduIUiqLjp5jHe0gDuR5ZB/IJap9lX5pzUhh8fs9FX8c8SSVyXmuBbeidio4/vzq3Qn88OejH6DeC6JHLomikKCMT3fZlL7Yxka041CuBaKL6tLt1VkC2B/3IZ14X7rhYKl99NzceSz6AqeDYLRbvdLG93JTabEhIXzTGuF2iyHdi0zjYTl+65LpuPtfH70OFwKF9NDSrTaQUlIK2ChOAL+Q+El7S02HmR0wd4eG1FHzxMAcFAwuLTrKj26cDw/jfIe0sImhJ/RaQa0YUP82iHQWq5cd92J7alG5WoRuak6od5/DM2K2Z6zFIn/sYpFbjV9KzIhso3RaE8r3TP6eyd8z+X8yk2NvMzH03ac0LlgabNsRW/pEEVLbhfa1ogp2iUheyn5bZu5npmBUrDZy4DWld4xAWxRcOkML0Q5hGLWDYRBL6h/vmgbhH3c3oU6mFL1afZs6bULQfDDpkLRq+axDI9vEwpO/AKxCtkPpqlWs1Vk1WvmmMH3/SNFqq8nrvWeX3tCospQzuSHfp61XR/0jtsx8dt7+BnB8eRYEPON8wXUraPH7bevz7WZoWl8Av3/s/b/72FvnmscvflAqLgM/VrEVjUBeSU2OtRW+8GFyQiwxvGePjyPu8NaqxYIef67Qktzfwm9Q+xM2QS7QBrqIqXcSwdO7IUNouKoCI29q+YukmXGcZVj6vWMfWkR2eXF9Q6RRf66ObS6znIBMfw9Z+Oa9/BoUnj0yxfW4CuzK4pqhFV9nqA1GihpefaPoecvCx8c44sZ8Qr1YLHnH0//Zgjqy/wBkj7X7
sidebar_class_name: post api-method
info_path: docs/api/nullplatform-api
custom_edit_url: null
canonical: 'https://docs.nullplatform.com/docs/api/workflow-create'
---
<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a workflow"}
>
</Heading>

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

</MethodEndpoint>

Creates a workflow. The request body is the definition document itself, not wrapped in any envelope.

- The workflow starts at revision 1, with the auto-maintained `latest` alias pointing at it.
- Nothing runs yet: triggers only register when you activate an alias.
- Referencing secrets or variables that have no value yet is fine: creation succeeds and the response lists them under `warnings` so you can set them afterwards.

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

<ParamsDetails
  parameters={undefined}
>

</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"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}}}}}
>

</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"The workflow was 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"]}}}}}}}}},"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>