Generate or update a flow

POST /flows

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.

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
One of:
XStateFlow object FlowFragments object
An XState-style representation of a flow
Hide attributes Show attributes

format string Required

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

Additional properties: array[object]

An XState-style representation of a single transition

Hide Additional properties: attributes Show Additional properties: attributes array[object]

description string

Description of the transition

cond string

Reference to a condition

target string

Reference to a state

actions array[string]

Reference to an action

after array[object]

An XState-style representation of a single transition

Hide after attributes Show after attributes array[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]

Reference to an action

always array[object]

An XState-style representation of a single transition

Hide always attributes Show always attributes array[object]

description string

Description of the transition

cond string

Reference to a condition

target string

Reference to a state

actions array[string]

Reference to an action

entryActions array[string]

Reference to an action

exitActions array[string]

Reference to an action

invoke array[object]

An XState-style representaton of a service invocation

Hide invoke attributes Show invoke attributes array[object]

src string Required

Reference to a service

onDone array[object]

An XState-style representation of a single transition

Hide onDone attributes Show onDone attributes array[object]

description string

Description of the transition

cond string

Reference to a condition

target string

Reference to a state

actions array[string]

Reference to an action

onError array[object]

An XState-style representation of a single transition

Hide onError attributes Show onError attributes array[object]

description string

Description of the transition

cond string

Reference to a condition

target string

Reference to a state

actions array[string]

Reference to an action

states object

Hide states attribute Show states attribute object

Additional properties: object

An XState-style representation of a state

Hide Additional properties: attributes Show Additional properties: 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

Additional properties: array[object]

An XState-style representation of a single transition

Hide Additional properties: attributes Show Additional properties: attributes array[object]

description string

Description of the transition

cond string

Reference to a condition

target string

Reference to a state

actions array[string]

Reference to an action

after array[object]

An XState-style representation of a single transition

Hide after attributes Show after attributes array[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]

Reference to an action

always array[object]

An XState-style representation of a single transition

Hide always attributes Show always attributes array[object]

description string

Description of the transition

cond string

Reference to a condition

target string

Reference to a state

actions array[string]

Reference to an action

entryActions array[string]

Reference to an action

exitActions array[string]

Reference to an action

invoke array[object]

An XState-style representaton of a service invocation

Hide invoke attributes Show invoke attributes array[object]

src string Required

Reference to a service

onDone array[object]

An XState-style representation of a single transition

Hide onDone attributes Show onDone attributes array[object]

description string

Description of the transition

cond string

Reference to a condition

target string

Reference to a state

actions array[string]

Reference to an action

onError array[object]

An XState-style representation of a single transition

Hide onError attributes Show onError attributes array[object]

description string

Description of the transition

cond string

Reference to a condition

target string

Reference to a state

actions array[string]

Reference to an action
A set of fragments representing a flow
Hide attributes Show attributes

format string Required

fragments array[object] Required

One of:
TransitionFragment array[object] ExpectationFragment array[object] EffectTransitionFragment array[object] StateEffectFragment array[object] DelayedTransitionFragment array[object]

A flow fragment representing a transition

Hide attributes Show attributes

type string Required

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]

Reference to an action

expectations array[string]

Reference to an expectation

A flow fragment representing an expectation

Hide attributes Show attributes

type string Required

state string Required

Reference to a state

expectations array[string] Required

Reference to an expectation

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

Hide attributes Show attributes

type string Required

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]

Reference to an action

expectations array[string]

Reference to an expectation

A flow fragment representing a state effect

Hide attributes Show attributes

type string Required

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]

Reference to an action

A flow fragment representing a delayed transition

Hide attributes Show attributes

type string Required

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]

Reference to an action

expectations array[string]

Reference to an expectation

Responses

200

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
  
  One of:
  XStateFlow object FlowFragments object
  
  An XState-style representation of a flow
  
  Hide attributes Show attributes
  
  format string Required
  
  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
  
  Additional properties: array[object]
  
  An XState-style representation of a single transition
  
  Hide Additional properties: attributes Show Additional properties: attributes array[object]
  
  description string
  
  Description of the transition
  
  cond string
  
  Reference to a condition
  
  target string
  
  Reference to a state
  
  actions array[string]
  
  Reference to an action
  
  after array[object]
  
  An XState-style representation of a single transition
  
  Hide after attributes Show after attributes array[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]
  
  Reference to an action
  
  always array[object]
  
  An XState-style representation of a single transition
  
  Hide always attributes Show always attributes array[object]
  
  description string
  
  Description of the transition
  
  cond string
  
  Reference to a condition
  
  target string
  
  Reference to a state
  
  actions array[string]
  
  Reference to an action
  
  entryActions array[string]
  
  Reference to an action
  
  exitActions array[string]
  
  Reference to an action
  
  invoke array[object]
  
  An XState-style representaton of a service invocation
  
  Hide invoke attributes Show invoke attributes array[object]
  
  src string Required
  
  Reference to a service
  
  onDone array[object]
  
  An XState-style representation of a single transition
  
  Hide onDone attributes Show onDone attributes array[object]
  
  description string
  
  Description of the transition
  
  cond string
  
  Reference to a condition
  
  target string
  
  Reference to a state
  
  actions array[string]
  
  Reference to an action
  
  onError array[object]
  
  An XState-style representation of a single transition
  
  Hide onError attributes Show onError attributes array[object]
  
  description string
  
  Description of the transition
  
  cond string
  
  Reference to a condition
  
  target string
  
  Reference to a state
  
  actions array[string]
  
  Reference to an action
  
  states object
  
  Hide states attribute Show states attribute object
  
  Additional properties: object
  
  An XState-style representation of a state
  
  Hide Additional properties: attributes Show Additional properties: 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
  
  Additional properties: array[object]
  
  An XState-style representation of a single transition
  
  Hide Additional properties: attributes Show Additional properties: attributes array[object]
  
  description string
  
  Description of the transition
  
  cond string
  
  Reference to a condition
  
  target string
  
  Reference to a state
  
  actions array[string]
  
  Reference to an action
  
  after array[object]
  
  An XState-style representation of a single transition
  
  Hide after attributes Show after attributes array[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]
  
  Reference to an action
  
  always array[object]
  
  An XState-style representation of a single transition
  
  Hide always attributes Show always attributes array[object]
  
  description string
  
  Description of the transition
  
  cond string
  
  Reference to a condition
  
  target string
  
  Reference to a state
  
  actions array[string]
  
  Reference to an action
  
  entryActions array[string]
  
  Reference to an action
  
  exitActions array[string]
  
  Reference to an action
  
  invoke array[object]
  
  An XState-style representaton of a service invocation
  
  Hide invoke attributes Show invoke attributes array[object]
  
  src string Required
  
  Reference to a service
  
  onDone array[object]
  
  An XState-style representation of a single transition
  
  Hide onDone attributes Show onDone attributes array[object]
  
  description string
  
  Description of the transition
  
  cond string
  
  Reference to a condition
  
  target string
  
  Reference to a state
  
  actions array[string]
  
  Reference to an action
  
  onError array[object]
  
  An XState-style representation of a single transition
  
  Hide onError attributes Show onError attributes array[object]
  
  description string
  
  Description of the transition
  
  cond string
  
  Reference to a condition
  
  target string
  
  Reference to a state
  
  actions array[string]
  
  Reference to an action
  
  A set of fragments representing a flow
  
  Hide attributes Show attributes
  
  format string Required
  
  fragments array[object] Required
  
  One of:
  TransitionFragment array[object] ExpectationFragment array[object] EffectTransitionFragment array[object] StateEffectFragment array[object] DelayedTransitionFragment array[object]
  
  A flow fragment representing a transition
  
  Hide attributes Show attributes
  
  type string Required
  
  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]
  
  Reference to an action
  
  expectations array[string]
  
  Reference to an expectation
  
  A flow fragment representing an expectation
  
  Hide attributes Show attributes
  
  type string Required
  
  state string Required
  
  Reference to a state
  
  expectations array[string] Required
  
  Reference to an expectation
  
  A flow fragment representing a transition due to the completion of an effect
  
  Hide attributes Show attributes
  
  type string Required
  
  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]
  
  Reference to an action
  
  expectations array[string]
  
  Reference to an expectation
  
  A flow fragment representing a state effect
  
  Hide attributes Show attributes
  
  type string Required
  
  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]
  
  Reference to an action
  
  A flow fragment representing a delayed transition
  
  Hide attributes Show attributes
  
  type string Required
  
  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]
  
  Reference to an action
  
  expectations array[string]
  
  Reference to an expectation

POST /flows

curl \
 -X POST https://api.flow.simplystated.dev/flows \
 -H "x-api-key: $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"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":["sendTelemetry"]}],"entryActions":["sendTelemetry"],"exitActions":["sendTelemetry"],"invoke":[{"src":"saveUser","onDone":[{"description":"string","cond":"isValid","target":"idle","actions":["sendTelemetry"]}],"onError":[{"description":"string","cond":"isValid","target":"idle","actions":["sendTelemetry"]}]}],"states":{}}}}'

Request example

{
  "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": [
            "sendTelemetry"
          ]
        }
      ],
      "entryActions": [
        "sendTelemetry"
      ],
      "exitActions": [
        "sendTelemetry"
      ],
      "invoke": [
        {
          "src": "saveUser",
          "onDone": [
            {
              "description": "string",
              "cond": "isValid",
              "target": "idle",
              "actions": [
                "sendTelemetry"
              ]
            }
          ],
          "onError": [
            {
              "description": "string",
              "cond": "isValid",
              "target": "idle",
              "actions": [
                "sendTelemetry"
              ]
            }
          ]
        }
      ],
      "states": {}
    }
  }
}

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": [
            "sendTelemetry"
          ]
        }
      ],
      "entryActions": [
        "sendTelemetry"
      ],
      "exitActions": [
        "sendTelemetry"
      ],
      "invoke": [
        {
          "src": "saveUser",
          "onDone": [
            {
              "description": "string",
              "cond": "isValid",
              "target": "idle",
              "actions": [
                "sendTelemetry"
              ]
            }
          ],
          "onError": [
            {
              "description": "string",
              "cond": "isValid",
              "target": "idle",
              "actions": [
                "sendTelemetry"
              ]
            }
          ]
        }
      ],
      "states": {
        "Additional properties:": {
          "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": [
                "sendTelemetry"
              ]
            }
          ],
          "entryActions": [
            "sendTelemetry"
          ],
          "exitActions": [
            "sendTelemetry"
          ],
          "invoke": [
            {
              "src": "saveUser",
              "onDone": [
                {
                  "description": "string",
                  "cond": "isValid",
                  "target": "idle",
                  "actions": [
                    "sendTelemetry"
                  ]
                }
              ],
              "onError": [
                {
                  "description": "string",
                  "cond": "isValid",
                  "target": "idle",
                  "actions": [
                    "sendTelemetry"
                  ]
                }
              ]
            }
          ]
        }
      }
    }
  }
}

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": [
            "sendTelemetry"
          ]
        }
      ],
      "entryActions": [
        "sendTelemetry"
      ],
      "exitActions": [
        "sendTelemetry"
      ],
      "invoke": [
        {
          "src": "saveUser",
          "onDone": [
            {
              "description": "string",
              "cond": "isValid",
              "target": "idle",
              "actions": [
                "sendTelemetry"
              ]
            }
          ],
          "onError": [
            {
              "description": "string",
              "cond": "isValid",
              "target": "idle",
              "actions": [
                "sendTelemetry"
              ]
            }
          ]
        }
      ],
      "states": {}
    }
  }
}

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": [
            "sendTelemetry"
          ]
        }
      ],
      "entryActions": [
        "sendTelemetry"
      ],
      "exitActions": [
        "sendTelemetry"
      ],
      "invoke": [
        {
          "src": "saveUser",
          "onDone": [
            {
              "description": "string",
              "cond": "isValid",
              "target": "idle",
              "actions": [
                "sendTelemetry"
              ]
            }
          ],
          "onError": [
            {
              "description": "string",
              "cond": "isValid",
              "target": "idle",
              "actions": [
                "sendTelemetry"
              ]
            }
          ]
        }
      ],
      "states": {
        "Additional properties:": {
          "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": [
                "sendTelemetry"
              ]
            }
          ],
          "entryActions": [
            "sendTelemetry"
          ],
          "exitActions": [
            "sendTelemetry"
          ],
          "invoke": [
            {
              "src": "saveUser",
              "onDone": [
                {
                  "description": "string",
                  "cond": "isValid",
                  "target": "idle",
                  "actions": [
                    "sendTelemetry"
                  ]
                }
              ],
              "onError": [
                {
                  "description": "string",
                  "cond": "isValid",
                  "target": "idle",
                  "actions": [
                    "sendTelemetry"
                  ]
                }
              ]
            }
          ]
        }
      }
    }
  }
}

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