Update the status of a machine instance

PUT /machines/{machineSlug}/i/{instanceSlug}/status

Set the status of the machine.

Machines in the 'paused' status will reject any events sent to them with a 409 error with a code of "invalid-state".

'running' instances will accept events normally.

It is dangerous to set an instance's status to 'paused'! You will drop events and, because delayed events are only retried 5 times (with ~30 seconds between each try), some delayed events may be dropped and never sent to your machine.

This exists purely to stop a runaway machine instance that is stuck in a loop of creating too many events.

This endpoint requires admin access.

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

application/json

Body

Request to update the status of an existing instance.

  • status string Required

    The status of a machine instance.

    Values are running or paused.

Responses

  • 204

    The instance status was set.

  • 400

    The request was malformed.

    Hide response attributes Show response attributes object
    • error string

      A description of the error.

    • code string

      A code specifying the type of error.

      • specify-org indicates that the user has access to multiple orgs and the operation requires specifying an organization. Pass the x-statebacked-org-id header to specify an org ID.
      • invalid-parameter indicates that one of the provided parameters was incorrect

      Values are specify-org or invalid-parameter.

    • The name of the invalid parameter

  • 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

PUT /machines/{machineSlug}/i/{instanceSlug}/status
curl \
 -X PUT https://api.statebacked.dev/machines/my-machine/i/user-1234/status \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"status":"running"}'
Request example
{
  "status": "running"
}
Request examples
{
  "status": "running"
}
Response examples (400)
{
  "error": "string",
  "code": "specify-org",
  "parameter": "string"
}
Response examples (400)
{
  "error": "string",
  "code": "specify-org",
  "parameter": "string"
}
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"
}