---
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: eJztWm1z27gR/is7nM4kcSnJSdNeq04/OI5zddvYHr8kd+NzQ4hYSTiDAIMXKTqN/ntnAVKiJEpy0i/tTPIhpkm8LBa7z+4+63ni2Mgm/fvkozaPQ6mnwHEolHBCK5s8pAlHmxtR0u9JPzk1yBxaYDCtxnfhdoxg8LNH62Cg+QyEBTfGxkLAde4LVA6EsyiHKSjtYGpYWSIHoYCpGaCaoNQldn9Rv6hOWLXeA6xjxllgDgxOhKUlX6YwFW4cdmLe6U7BhHJMKOSQSRLSZcCkYBZKLZQTakTzhevS6hfajemN8crCDF0fnBGjERoLWskZGBwJ69DAdIwKZtoDy52YMIfAVFw2rHONQzSoclrLYm7QWdAGJswINpBIimAOxmyCoDRMmPRI25GKhkJhH3JSKJ3H+jxH5BaY4uFQBm2plUWQwrqg0QK84mggmzKjhBrZDKwOwuVMgUUXB7GhQzNlhttukia6RBN2OOdJP6k12g/7YpIm1c290XyW9OdJrpVD5eiRlaUUeZjb+9XS9c8Tm4+xYPTkhJOY9Jd283Z520mauFlJ3/TgV8xdsmlEa1e7spJ+OLZlBa7shd5MhPVMAnLhtAHLJmi7cOOwtMAMAoOClaCHYB2WIDg4HR7/urrSMExO2cyCwYEX0oFFM0HTsYIjDI0uwhRLy5DskFVzs5RUzCCXApXrWE86IQur186qSxUWuLA5Mxx5t1KrMMjJtRQrSNNhB3Kp0tClOIGWFBm+kkKjzqwzQo22dPZ3XzDVMcg42dVKfTSb9sMvrCjDhZy8PwduxNCBzZlSaJJFmjzi7PAep/GQ+VhbVGClH8Hz7N/3rPPbcecvD9XPzsP8OP3Tq8XvshcpeCU+e4QSDWgzYkr8Fo2ZbFgUhXckbBfOVHSGH4W7LG3HuplE8KVFcuqJYJBd3d1Crz6U7TUwqDd/xNkiWz8jK0QnnLHTOOPaYbbPupp9kzNlgWMp9Qw52FyXaGGoDWjvOHPI4eT9ue3SoiVz48Oae6clOaZQwWCX5wBnELvwFofMS/JhDVlv4yg9AhatOsJhYXvLg9HeyrQeZNuZlJeylMwNtSkIN7Q3OQbTWJOHjDQclnxkXSwaljMp0Tyza1cZlBAtdyXKDr9+3+qHDQ+PbguC1y5ZjpnyBRqRw3OlYTwrx6jsC9IQ4zzMYfJqzV3WRVgsUoIshXkMWKsBzBg22xLxjI/QwgDdFMnE6Vy0WVB+++pLKD98/is0HeNVA/1DhNJlPAdkQQ1MfiDEyIJmC3SMM8da9k4TiwVTTuQf0NgdRr0uwGW90yTOAMkGKME6bZCDVlVciRF03Qxfdl91j8OB2xXvjMfFYhGkyr0Rbpb07+fJAJlBc+LJSe4fFg8EfDFsBX29On5JP/bA/5TZGAMjbH51+LnyAyns+Bqtl64l8qxjbb1tWwBrmdwEccGTtEbySuATGuNLXj1vIbvg+3FoOvwkhh/fDD4OSz86Vntw+gDy7QohB4LCXsDcg31PAq8miJy3KGIXvh1yipXuWyQjAGQu6Sd0Jx0nCqQpqyt64hQy89pNmqZyXb/bbyq1lZ3zpLFOU/QtU2lM+VqTWRM0ThTK4QjNFj7U8oPyxQBNGvPqKjN+uQYIfwj2sUzpWrCPgg6hXMSGtrA09FKuoX9GczIKk5TTLjNcC15JtJYAMpee4yqX/ButHaHyGy6+mvKmxaeC4iQyixfarYH7asBB/A2GEmuNEyoJAmxJeTkM2FhbTfz0FSZToUzDckLxgfvR5r8wocP4IWn7Q8a2ZjyVyKtxA60lMrVllB/H6MZoYiFHqnpmNzL3qvLi3W9y5uWUHWawF20qQW4cc0/JAKoMqJpVJUGCKtd4hlDo0Vp7M5zKbm4bex+MbLSqbzHjNEHlCzKxEhWPb2S0pSETEsnehKou66G+t6/VMMdvmiaZdWfGaNOm2fXzFWgtG7VYaUgAeduHgOJe0Wbvd97xFkTGCUCjqSYfA4tsRnWnzyxkUxyMtX68MzLk8htuuPzYJtKh9Gqx2KJcbg8SHF04ZQoGWOFrTCxbdbJVVepprBCMcBhyMVYVuM+j0zQwmniRkJnXBlWhK3EMEzS0hENyb4XTzhInyKRquqIlO18l3pXRn2o1FKOPccZBJuGsoE15ZGk2OCdTUTOBrcrDsoDKmVnMypd0DHOBfiJ5qbIuJctx+1rbbWyljNPLi3fnP346u7i9/vnT3cX12c3lvz6cvQ3nPwyvF1efTq7OP/3z7OeQBArVjuHVXpFoSkJtkjws6n9p8vqnn7bT7VjVA5KfRbIukHSW2JApsVNT+jw1Wo36RG6FgZDR5lkKDMbrzEPG0TEh6ZPiKRUVEyYFj9hGkOINWnqPlbYDOTAcRvSBoUC5L9MvjR5ILH6/J+OPI57EMlnHFGeGV4cKB39+/e4Ufvjz8Q9Q7QXxRDaNpBAnj892yZS92LaNKMchXwtAF9mlu+vzFLA76kI2dq60/d6S++jYmXVYdDlOekFou/qktOsMtVd8g0L4pjVCdIsq3WuZ2sFy/FaQaYn9r49fh4BAKj20dKMMJJcUHDaSE8AvRH7S3kLRZeYHxN3BIbXkPFExBwmDK4OW/KPdzvuH7XwHtbBpQ0+otQJb0aP6rRfhLGYvO+Jic2rhbUVC1zknVLvP4Bkh27OkgSJ/bEORO4VfSswJbCN1WgHKd0/+7snfPfl/0pNjbTPW1PcptQ2SBtl26JZaFMG1bShfPWWwS4tkpeg2aeZurouEktWaDrwh944aaJKCy8PQQrRDGEblYBiUpNXDu7pA+MfH25Ank4ter3pTZ7UK6oZJC6VV0WctHNmmLTy5A7BS2Q6mq2KxVndVc+WbxPT9nLTVZJPXa882vqFmZclnhrqNtKRLmyyHH3dfdo+3DvvGC8lTKCNTmlLPMyRvoAfhvhv9iooiXusnLD0b1Uio2J59pz1Vt8iWzQLqNAgLJ1fn/di/PTpasTj26ChU8mvNiLrHZ7twNkEzC509GGCui5CyR44KORwd1dXE0VFox6mqeSssIEUiqW3s6h4dBa4F6/3IUnhs/xKZ4KiTt2wgP5fiESGjYjh70YWTqkInMqzq8NIGIUN23igb6vhGl7ja8ewL5r4+pMFcU4wK5wl6Dh2QwSz8rDrWQpXeUYrsXXygu5B6ZKsVb6o+Mr1e2svRETwilsSVc1TURYgDLDqS2dJqgXpYK4JiC0tbVzDVcJ3YxW808TdtptEH/t7y/79r+VeI6/CL65WSiRAlfSQkIpytCEebNHne0J4eU6zo3yfz+YBZvDNysaDXnz0aavo0UCz0fNJkjIyjCUEjAvBpNJ7OLQlCw6UPcXmzo7NI6xkneY6l2zv2oRHOri5vbil0VH+0EMmOxDAyZPq/n4S/fFj2BMO7eSKZGvkQY5O4ZiBk1uPURlyKTG6VV6hZQ8L5PI641Y+oFotl9HH0e7Kguvw/1eNuzg==
sidebar_class_name: "post 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={"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>