State Backed

Send an event to a machine instance.

POST /machines/{machineSlug}/i/{instanceSlug}/events
Bearer auth

Send an event to the machine instance that was previously created by calling POST /machines/{machineSlug}.

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

Otherwise, the state of the machine instance after any transitions resulting from the event will be returned.

The request will wait for the machine to settle before returning a response. Settling means that the machine has reached a stable state and has no child services running.

All top-level events have a 10 second timeout for the machine to settle.

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.

Path parameters

  • machineSlug string Required

    The slug/name for the machine definition.

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

  • instanceSlug string Required

    The slug/name for the machine instance.

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

Body

Request to send an event to an instance of a machine.

  • event object | string Required

    One of:
    EventWithPayload object EventWithoutPayload string

    An event to send to a machine.

    Event types are user-defined for a given machine definition.

Responses

  • 200

    The event was delivered 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.
POST /machines/{machineSlug}/i/{instanceSlug}/events 
curl \
 -X POST https://api.statebacked.dev/machines/my-machine/i/user-1234/events \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"event":{"type":"string"}}'
Request example 
{
  "event": {
    "type": "string"
  }
}
Request examples 
{
  "event": {
    "type": "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"
}