Update the desired machine version for an existing instance.

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

Set the desired machine version for an existing instance.

The instance will not be upgraded immediately but will be upgraded the next time an event is sent to it from a settled state.

A 400 with code "no-migration-path" will be returned if there is no path through the set of existing migrations from the current instance version to the desired instance version.

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 machine version for an existing instance.

Responses

  • 201

    The desired version was recorded successfully and will be applied the next time an event is sent to the instance from a settled state.

  • 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.

PUT /machines/{machineSlug}/i/{instanceSlug}/v
curl \
 -X PUT https://api.statebacked.dev/machines/my-machine/i/user-1234/v \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"targetMachineVersionId":"string"}'
Request example
{
  "targetMachineVersionId": "string"
}
Response examples (400)
{
  "error": "string",
  "code": "specify-org",
  "parameter": "string"
}
Response examples (403)
{
  "error": "string",
  "code": "missing-scope"
}