Create a new machine instance.

POST /machines/{machineSlug}

Create a new instance of the machine definition with the given slug.

The allowWrite function for the machine definition version will be called to authorize the initial transition and, if it fails, a 403 with code rejected-by-machine-authorizer will be returned.

Otherwise, the state of the machine instance after the initial transition will be returned.

All top-level events have a 10 second timeout for the machine to settle. Settling means that the machine has reached a stable state and has no child services running.

If the machine does not settle within 10 seconds but has completed at least one transition successfully, a 200 with the current state will be returned, the child services will be stopped, and error events will be delivered for each stopped service before the next event is sent.

If a machine instance for this (machineSlug, instance slug) already exists, a 409 will be returned.

Path parameters

machineSlug string Required

The slug/name for the machine definition to create an instance of.

Minimum length is 1. Format should match the following pattern: ^[a-zA-Z0-9_-]{1,128}$.

Body

Request to create an instance of a machine.

If machineVersionId is provided, creates an instance of the machine definition version with that ID. Otherwise, creates an instance of the current version of the machine definition.

slug string Required

An identifier for the machine instance. Must be unique within the instances for the associated machine definition.

Minimum length is 1. Format should match the following pattern: ^[a-zA-Z0-9_-]{1,128}$.
context object

The initial context for the machine instance. Defaults to {}.
Hide context attribute Show context attribute object
- Additional properties are allowed
machineVersionId string

The ID of the machine definition version to use for this instance. If not provided, creates an instance of the current version of the machine definition.

Responses

200

The machine instance was created successfully.
Hide response attributes Show response attributes object
- ts number Required
  
  Timestamp for when the state was created
- state string | object Required
  
  One of:
  SimpleStateValue string CompoundStateValue object
  
  A simple state
- publicContext object
  
  The public context of the machine instance.
  
  This includes all context under the public key.
  
  Hide publicContext attribute Show publicContext attribute object
  
  Additional properties are allowed
- tags array[string] Required
  
  Array of tags for the current states
- done boolean Required
  
  Is the state machine complete
403

The request was unauthorized.
Hide response attributes Show response attributes object
- error string
  
  A description of the error.
- code string
  
  A code specifying the type of error.
  
  Values are missing-scope, rejected-by-machine-authorizer, missing-user, or missing-org.
409

The resource already exists.
Hide response attributes Show response attributes object
- code string
  
  Machine-readable identifier for the type of error
  
  Value is invalid-state.
- error string
  
  Human-readable identifier for the error

POST /machines/{machineSlug}

curl \
 -X POST https://api.statebacked.dev/machines/my-machine \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"slug":"user-1234","context":{},"machineVersionId":"string"}'

Request example

{
  "slug": "user-1234",
  "context": {},
  "machineVersionId": "string"
}

Request examples

{
  "slug": "user-1234",
  "context": {},
  "machineVersionId": "string"
}

Response examples (200)

{
  "state": "idle",
  "done": false,
  "tags": [
    "some-tag"
  ]
}

{
  "state": {
    "parent": {
      "nested1": "idle"
    }
  },
  "publicContext": {
    "user": "u_1234"
  },
  "done": false,
  "tags": [
    "some-tag"
  ]
}

{
  "values": {
    "state": {
      "parent": {
        "nested1": "idle",
        "nested2": "idle"
      }
    },
    "publicContext": {
      "connectedDocuments": [
        "doc_1234",
        "doc_5678"
      ]
    },
    "done": false,
    "tags": [
      "some-tag"
    ]
  }
}

Response examples (200)

{
  "done": false,
  "tags": [
    "some-tag"
  ],
  "state": "idle"
}

Response examples (403)

{
  "error": "string",
  "code": "missing-scope"
}

Response examples (403)

{
  "error": "string",
  "code": "missing-scope"
}

Response examples (409)

{
  "code": "invalid-state",
  "error": "string"
}

Response examples (409)

{
  "code": "invalid-state",
  "error": "string"
}