Get the current state of a machine instance.

GET /machines/{machineSlug}/i/{instanceSlug}

Retrieve the state of the machine instance that was previously created by calling POST /machines/{machineSlug} and may have had events sent to it by calling POST /machines/{machineSlug}/i/{instanceSlug}/events.

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

Otherwise, the current state of the machine instance will be returned.

Obviously, the state returned may be out of date by the time it is returned because reads are non-blocking but a the returned state will always be self-consistent.

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}$.

Responses

  • 200

    The state was retrieved successfully.

    Hide response attributes Show response attributes object
  • 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.

GET /machines/{machineSlug}/i/{instanceSlug}
curl \
 -X GET https://api.statebacked.dev/machines/my-machine/i/user-1234 \
 -H "Authorization: Bearer $ACCESS_TOKEN"
{
  "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 (403)
{
  "error": "string",
  "code": "missing-scope"
}