Generate or update a flow

POST /flows

Api key auth

Query parameters

format string

The desired format for the generated flow

Values are xstate or fragments. Default value is xstate.
output-mode string

Whether to produce an incremental flow (excluding the existing flow) or a full flow

Values are full or incremental. Default value is incremental.

application/json

Body

text string Required

The text description of the flow we should generate
context string
The broader context that should be used to interpret text.

For example, if a user writes:
```
After users log in, bring them to the home page
```
and then continues:
```
Then, if it's their first visit, show them a popup
```
Providing After users log in... as context when passing Then, ... as the text will result in the correct interpretation of the source state for showing the popup.

The context will not contribute to any new transitions. It will only be used to properly interpret text.
existingFlow object

A flow
One of:
XStateFlow object FlowFragments object
An XState-style representation of a flow
Hide attributes Show attributes

format string Required

Value is xstate.

flow object Required

An XState-style representation of a state

Hide flow attributes Show flow attributes object

description string

Description of the state. Will include a markdown-formatted list of expectations.

on object

Map from event names to transitions

Hide on attribute Show on attribute object

* array[object] Additional properties

An XState-style representation of a single transition

Hide * attributes Show * attributes object

description string

Description of the transition

cond string

Reference to a condition

target string

Reference to a state

actions array[string]

Actions to execute when taking the transition

after array[object]

Array of delayed transitions

Hide after attributes Show after attributes object

delay string | number Required

One of:
string-1 string number-2 number

description string

Description of the transition

cond string

Reference to a condition

target string

Reference to a state

actions array[string]

Actions to execute when taking the transition

always array[object]

Array of eventless transitions

An XState-style representation of a single transition

Hide always attributes Show always attributes object

description string

Description of the transition

cond string

Reference to a condition

target string

Reference to a state

actions array[string]

Actions to execute when taking the transition

entryActions array[string]

Actions to execute when entering the state

exitActions array[string]

Actions to execute when exiting the state

invoke array[object]

Services to invoke in this state

An XState-style representaton of a service invocation

Hide invoke attributes Show invoke attributes object

src string Required

Reference to a service

onDone array[object]

Transitions to take when the invocation succeeds

An XState-style representation of a single transition

Hide onDone attributes Show onDone attributes object

description string

Description of the transition

cond string

Reference to a condition

target string

Reference to a state

actions array[string]

Actions to execute when taking the transition

onError array[object]

Transitions to take when the invocation succeeds

An XState-style representation of a single transition

Hide onError attributes Show onError attributes object

description string

Description of the transition

cond string

Reference to a condition

target string

Reference to a state

actions array[string]

Actions to execute when taking the transition

states object

Hide states attribute Show states attribute object

* object

An XState-style representation of a state

Hide * attributes Show * attributes object

description string

Description of the state. Will include a markdown-formatted list of expectations.

on object

Map from event names to transitions

Hide on attribute Show on attribute object

* array[object] Additional properties

An XState-style representation of a single transition

Hide * attributes Show * attributes object

description string

Description of the transition

cond string

Reference to a condition

target string

Reference to a state

actions array[string]

Actions to execute when taking the transition

after array[object]

Array of delayed transitions

Hide after attributes Show after attributes object

delay string | number Required

One of:
string-1 string number-2 number

description string

Description of the transition

cond string

Reference to a condition

target string

Reference to a state

actions array[string]

Actions to execute when taking the transition

always array[object]

Array of eventless transitions

An XState-style representation of a single transition

Hide always attributes Show always attributes object

description string

Description of the transition

cond string

Reference to a condition

target string

Reference to a state

actions array[string]

Actions to execute when taking the transition

entryActions array[string]

Actions to execute when entering the state

exitActions array[string]

Actions to execute when exiting the state

invoke array[object]

Services to invoke in this state

An XState-style representaton of a service invocation

Hide invoke attributes Show invoke attributes object

src string Required

Reference to a service

onDone array[object]

Transitions to take when the invocation succeeds

An XState-style representation of a single transition

Hide onDone attributes Show onDone attributes object

description string

Description of the transition

cond string

Reference to a condition

target string

Reference to a state

actions array[string]

Actions to execute when taking the transition

onError array[object]

Transitions to take when the invocation succeeds

An XState-style representation of a single transition

Hide onError attributes Show onError attributes object

description string

Description of the transition

cond string

Reference to a condition

target string

Reference to a state

actions array[string]

Actions to execute when taking the transition
A set of fragments representing a flow
Hide attributes Show attributes

format string Required

Value is fragments.

fragments array[object] Required

A fragment of a flow

A fragment of a flow

One of:
TransitionFragment object ExpectationFragment object EffectTransitionFragment object StateEffectFragment object DelayedTransitionFragment object

A flow fragment representing a transition

Hide attributes Show attributes

type string Required

Value is transition.

source string Required

Reference to a state

target string

Reference to a state

event string

Reference to an event

condition string

Reference to a condition

effects array[string]

Actions to execute when taking the transition

expectations array[string]

Expectations that should hold for the transition

A flow fragment representing an expectation

Hide attributes Show attributes

type string Required

Value is expectation.

state string Required

Reference to a state

expectations array[string] Required

Expectations that should hold for state

A flow fragment representing a transition due to the completion of an effect

Hide attributes Show attributes

type string Required

Value is effect-transition.

source string Required

Reference to a state

target string

Reference to a state

trigger string Required

Reference to an action

status string Required

The status of the effect

Values are success or failure.

condition string

Reference to a condition

effects array[string]

Actions to execute when taking the transition

expectations array[string]

Expectations that should hold for the transition

A flow fragment representing a state effect

Hide attributes Show attributes

type string Required

Value is state-effect.

state string Required

Reference to a state

on string Required

Whether to run the effect on entry or exit

Values are entry or exit.

effects array[string]

Effects that be run when in state

A flow fragment representing a delayed transition

Hide attributes Show attributes

type string Required

Value is delayed-transition.

source string Required

Reference to a state

target string

Reference to a state

delay number | string Required

One of:
number-1 number string-2 string

condition string

Reference to a condition

effects array[string]

Actions to execute when taking the transition

expectations array[string]

Expectations that should hold for the transition

Responses

200 application/json

The requested flow
Hide response attributes Show response attributes object
- id string Required
  
  Response identifier to be used in error reporting, debugging, and feedback
- result object Required
  
  A flow
  
  One of:
  XStateFlow object FlowFragments object
  
  An XState-style representation of a flow
  
  Hide attributes Show attributes
  
  format string Required
  
  Value is xstate.
  
  flow object Required
  
  An XState-style representation of a state
  
  Hide flow attributes Show flow attributes object
  
  description string
  
  Description of the state. Will include a markdown-formatted list of expectations.
  
  on object
  
  Map from event names to transitions
  
  Hide on attribute Show on attribute object
  
  * array[object] Additional properties
  
  An XState-style representation of a single transition
  
  Hide * attributes Show * attributes object
  
  description string
  
  Description of the transition
  
  cond string
  
  Reference to a condition
  
  target string
  
  Reference to a state
  
  actions array[string]
  
  Actions to execute when taking the transition
  
  after array[object]
  
  Array of delayed transitions
  
  Hide after attributes Show after attributes object
  
  delay string | number Required
  
  One of:
  string-1 string number-2 number
  
  description string
  
  Description of the transition
  
  cond string
  
  Reference to a condition
  
  target string
  
  Reference to a state
  
  actions array[string]
  
  Actions to execute when taking the transition
  
  always array[object]
  
  Array of eventless transitions
  
  An XState-style representation of a single transition
  
  Hide always attributes Show always attributes object
  
  description string
  
  Description of the transition
  
  cond string
  
  Reference to a condition
  
  target string
  
  Reference to a state
  
  actions array[string]
  
  Actions to execute when taking the transition
  
  entryActions array[string]
  
  Actions to execute when entering the state
  
  exitActions array[string]
  
  Actions to execute when exiting the state
  
  invoke array[object]
  
  Services to invoke in this state
  
  An XState-style representaton of a service invocation
  
  Hide invoke attributes Show invoke attributes object
  
  src string Required
  
  Reference to a service
  
  onDone array[object]
  
  Transitions to take when the invocation succeeds
  
  An XState-style representation of a single transition
  
  Hide onDone attributes Show onDone attributes object
  
  description string
  
  Description of the transition
  
  cond string
  
  Reference to a condition
  
  target string
  
  Reference to a state
  
  actions array[string]
  
  Actions to execute when taking the transition
  
  onError array[object]
  
  Transitions to take when the invocation succeeds
  
  An XState-style representation of a single transition
  
  Hide onError attributes Show onError attributes object
  
  description string
  
  Description of the transition
  
  cond string
  
  Reference to a condition
  
  target string
  
  Reference to a state
  
  actions array[string]
  
  Actions to execute when taking the transition
  
  states object
  
  Hide states attribute Show states attribute object
  
  * object
  
  An XState-style representation of a state
  
  Hide * attributes Show * attributes object
  
  description string
  
  Description of the state. Will include a markdown-formatted list of expectations.
  
  on object
  
  Map from event names to transitions
  
  Hide on attribute Show on attribute object
  
  * array[object] Additional properties
  
  An XState-style representation of a single transition
  
  Hide * attributes Show * attributes object
  
  description string
  
  Description of the transition
  
  cond string
  
  Reference to a condition
  
  target string
  
  Reference to a state
  
  actions array[string]
  
  Actions to execute when taking the transition
  
  after array[object]
  
  Array of delayed transitions
  
  Hide after attributes Show after attributes object
  
  delay string | number Required
  
  One of:
  string-1 string number-2 number
  
  description string
  
  Description of the transition
  
  cond string
  
  Reference to a condition
  
  target string
  
  Reference to a state
  
  actions array[string]
  
  Actions to execute when taking the transition
  
  always array[object]
  
  Array of eventless transitions
  
  An XState-style representation of a single transition
  
  Hide always attributes Show always attributes object
  
  description string
  
  Description of the transition
  
  cond string
  
  Reference to a condition
  
  target string
  
  Reference to a state
  
  actions array[string]
  
  Actions to execute when taking the transition
  
  entryActions array[string]
  
  Actions to execute when entering the state
  
  exitActions array[string]
  
  Actions to execute when exiting the state
  
  invoke array[object]
  
  Services to invoke in this state
  
  An XState-style representaton of a service invocation
  
  Hide invoke attributes Show invoke attributes object
  
  src string Required
  
  Reference to a service
  
  onDone array[object]
  
  Transitions to take when the invocation succeeds
  
  An XState-style representation of a single transition
  
  Hide onDone attributes Show onDone attributes object
  
  description string
  
  Description of the transition
  
  cond string
  
  Reference to a condition
  
  target string
  
  Reference to a state
  
  actions array[string]
  
  Actions to execute when taking the transition
  
  onError array[object]
  
  Transitions to take when the invocation succeeds
  
  An XState-style representation of a single transition
  
  Hide onError attributes Show onError attributes object
  
  description string
  
  Description of the transition
  
  cond string
  
  Reference to a condition
  
  target string
  
  Reference to a state
  
  actions array[string]
  
  Actions to execute when taking the transition
  
  A set of fragments representing a flow
  
  Hide attributes Show attributes
  
  format string Required
  
  Value is fragments.
  
  fragments array[object] Required
  
  A fragment of a flow
  
  A fragment of a flow
  
  One of:
  TransitionFragment object ExpectationFragment object EffectTransitionFragment object StateEffectFragment object DelayedTransitionFragment object
  
  A flow fragment representing a transition
  
  Hide attributes Show attributes
  
  type string Required
  
  Value is transition.
  
  source string Required
  
  Reference to a state
  
  target string
  
  Reference to a state
  
  event string
  
  Reference to an event
  
  condition string
  
  Reference to a condition
  
  effects array[string]
  
  Actions to execute when taking the transition
  
  expectations array[string]
  
  Expectations that should hold for the transition
  
  A flow fragment representing an expectation
  
  Hide attributes Show attributes
  
  type string Required
  
  Value is expectation.
  
  state string Required
  
  Reference to a state
  
  expectations array[string] Required
  
  Expectations that should hold for state
  
  A flow fragment representing a transition due to the completion of an effect
  
  Hide attributes Show attributes
  
  type string Required
  
  Value is effect-transition.
  
  source string Required
  
  Reference to a state
  
  target string
  
  Reference to a state
  
  trigger string Required
  
  Reference to an action
  
  status string Required
  
  The status of the effect
  
  Values are success or failure.
  
  condition string
  
  Reference to a condition
  
  effects array[string]
  
  Actions to execute when taking the transition
  
  expectations array[string]
  
  Expectations that should hold for the transition
  
  A flow fragment representing a state effect
  
  Hide attributes Show attributes
  
  type string Required
  
  Value is state-effect.
  
  state string Required
  
  Reference to a state
  
  on string Required
  
  Whether to run the effect on entry or exit
  
  Values are entry or exit.
  
  effects array[string]
  
  Effects that be run when in state
  
  A flow fragment representing a delayed transition
  
  Hide attributes Show attributes
  
  type string Required
  
  Value is delayed-transition.
  
  source string Required
  
  Reference to a state
  
  target string
  
  Reference to a state
  
  delay number | string Required
  
  One of:
  number-1 number string-2 string
  
  condition string
  
  Reference to a condition
  
  effects array[string]
  
  Actions to execute when taking the transition
  
  expectations array[string]
  
  Expectations that should hold for the transition

POST /flows

curl \
 --request POST 'https://api.flow.simplystated.dev/flows' \
 --header "x-api-key: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"text":"Open the search autocomplete when the user hovers or focuses in the search box","context":"After users log in, bring them to the home page\n","existingFlow":{"format":"xstate","flow":{"description":"string","on":{"click":[{"cond":"Is valid","target":"Submit","actions":["Show notification"]}]},"after":[{"delay":500,"target":"Timed out","actions":["Show timeout notification"]}],"always":[{"description":"string","cond":"isValid","target":"idle","actions":["string"]}],"entryActions":["string"],"exitActions":["string"],"invoke":[{"src":"saveUser","onDone":[{"description":"string","cond":"isValid","target":"idle","actions":["string"]}],"onError":[{"description":"string","cond":"isValid","target":"idle","actions":["string"]}]}],"states":{"*":{"description":"string","on":{"click":[{"cond":"Is valid","target":"Submit","actions":["Show notification"]}]},"after":[{"delay":500,"target":"Timed out","actions":["Show timeout notification"]}],"always":[{"description":"string","cond":"isValid","target":"idle","actions":["string"]}],"entryActions":["string"],"exitActions":["string"],"invoke":[{"src":"saveUser","onDone":[{"description":"string","cond":"isValid","target":"idle","actions":["string"]}],"onError":[{"description":"string","cond":"isValid","target":"idle","actions":["string"]}]}]}}}}}'

Request examples

{
  "text": "Open the search autocomplete when the user hovers or focuses in the search box",
  "context": "After users log in, bring them to the home page\n",
  "existingFlow": {
    "format": "xstate",
    "flow": {
      "description": "string",
      "on": {
        "click": [
          {
            "cond": "Is valid",
            "target": "Submit",
            "actions": [
              "Show notification"
            ]
          }
        ]
      },
      "after": [
        {
          "delay": 500,
          "target": "Timed out",
          "actions": [
            "Show timeout notification"
          ]
        }
      ],
      "always": [
        {
          "description": "string",
          "cond": "isValid",
          "target": "idle",
          "actions": [
            "string"
          ]
        }
      ],
      "entryActions": [
        "string"
      ],
      "exitActions": [
        "string"
      ],
      "invoke": [
        {
          "src": "saveUser",
          "onDone": [
            {
              "description": "string",
              "cond": "isValid",
              "target": "idle",
              "actions": [
                "string"
              ]
            }
          ],
          "onError": [
            {
              "description": "string",
              "cond": "isValid",
              "target": "idle",
              "actions": [
                "string"
              ]
            }
          ]
        }
      ],
      "states": {
        "*": {
          "description": "string",
          "on": {
            "click": [
              {
                "cond": "Is valid",
                "target": "Submit",
                "actions": [
                  "Show notification"
                ]
              }
            ]
          },
          "after": [
            {
              "delay": 500,
              "target": "Timed out",
              "actions": [
                "Show timeout notification"
              ]
            }
          ],
          "always": [
            {
              "description": "string",
              "cond": "isValid",
              "target": "idle",
              "actions": [
                "string"
              ]
            }
          ],
          "entryActions": [
            "string"
          ],
          "exitActions": [
            "string"
          ],
          "invoke": [
            {
              "src": "saveUser",
              "onDone": [
                {
                  "description": "string",
                  "cond": "isValid",
                  "target": "idle",
                  "actions": [
                    "string"
                  ]
                }
              ],
              "onError": [
                {
                  "description": "string",
                  "cond": "isValid",
                  "target": "idle",
                  "actions": [
                    "string"
                  ]
                }
              ]
            }
          ]
        }
      }
    }
  }
}

Response examples (200)

{
  "id": "string",
  "result": {
    "format": "xstate",
    "flow": {
      "description": "string",
      "on": {
        "click": [
          {
            "cond": "Is valid",
            "target": "Submit",
            "actions": [
              "Show notification"
            ]
          }
        ]
      },
      "after": [
        {
          "delay": 500,
          "target": "Timed out",
          "actions": [
            "Show timeout notification"
          ]
        }
      ],
      "always": [
        {
          "description": "string",
          "cond": "isValid",
          "target": "idle",
          "actions": [
            "string"
          ]
        }
      ],
      "entryActions": [
        "string"
      ],
      "exitActions": [
        "string"
      ],
      "invoke": [
        {
          "src": "saveUser",
          "onDone": [
            {
              "description": "string",
              "cond": "isValid",
              "target": "idle",
              "actions": [
                "string"
              ]
            }
          ],
          "onError": [
            {
              "description": "string",
              "cond": "isValid",
              "target": "idle",
              "actions": [
                "string"
              ]
            }
          ]
        }
      ],
      "states": {
        "*": {
          "description": "string",
          "on": {
            "click": [
              {
                "cond": "Is valid",
                "target": "Submit",
                "actions": [
                  "Show notification"
                ]
              }
            ]
          },
          "after": [
            {
              "delay": 500,
              "target": "Timed out",
              "actions": [
                "Show timeout notification"
              ]
            }
          ],
          "always": [
            {
              "description": "string",
              "cond": "isValid",
              "target": "idle",
              "actions": [
                "string"
              ]
            }
          ],
          "entryActions": [
            "string"
          ],
          "exitActions": [
            "string"
          ],
          "invoke": [
            {
              "src": "saveUser",
              "onDone": [
                {
                  "description": "string",
                  "cond": "isValid",
                  "target": "idle",
                  "actions": [
                    "string"
                  ]
                }
              ],
              "onError": [
                {
                  "description": "string",
                  "cond": "isValid",
                  "target": "idle",
                  "actions": [
                    "string"
                  ]
                }
              ]
            }
          ]
        }
      }
    }
  }
}

Generate or update a flow

Query parameters

Body

existingFlow object

delay string | number Required

delay string | number Required

Responses

result object Required

delay string | number Required

delay string | number Required