POST /managed-services/instances/{instanceId}/actions
Request a lifecycle change using the latest instance revision, then follow its completion.
Syntax
POST https://grid-lab.zyxio.xyz/managed-services/instances/<instanceId>/actions
x-api-key: <key>
content-type: application/json
{"revision": 2, "action": "rotate", "note": "Rotate application credentials"}Request
| Name | Where | Required | Meaning |
|---|---|---|---|
x-api-key | header | yes, or Authorization | Your API key, or Authorization: Bearer <token> from Zyxio sign-in. |
instanceId | path | yes | The UUID returned as id when provisioning, or in the instance list. |
revision | body | yes | The latest instance revision, as a positive integer. This is not binding.accessBindingRevision. |
action | body | yes | rotate, resize, restore, suspend, resume or retire. |
note | body | yes | Trimmed text, 1 to 2,000 characters. Do not include secrets. |
Unknown fields are refused. Only instances with no pending action and state ready or suspended accept actions.
| Action | Allowed state | Result when fulfilled |
|---|---|---|
rotate | ready | Refresh credentials or access; returns to ready. Download credentials again. |
resize | ready | Request a configuration change; fulfillment depends on the service and profile. |
restore | ready | Request restoration; fulfillment depends on the service and profile. |
suspend | ready | Disable access; state becomes suspended. |
resume | suspended | Restore access; state becomes ready. Download credentials again. |
retire | ready or suspended | Permanently end access; state becomes retired. This is not a promise of data deletion. |
The Tier-1 automated lifecycle supports rotate, suspend, resume and retire. Acceptance of resize or restore does not promise automated fulfillment or a particular capacity or recovery outcome.
Response
200 OK with the full instance record described by GET /managed-services/instances/{instanceId}. Recording the request increments revision; successful reconciliation can increment it again before the response.
The route attempts the action after recording it. A response with requestedAction still set means the operation remains pending, including when the provisioner could not finish. Poll until requestedAction is none and state matches the intended outcome; inspect statusNote if blocked. Do not treat 200 alone as proof that access or billing changed.
There is no action idempotency key. If you lose the response, read the current instance before deciding whether another request is needed. Replaying a stale revision returns 409 service_changed.
Errors
| Status | Body | When | What to do |
|---|---|---|---|
400 | {"error": "invalid_managed_service_action"} | Missing, invalid or unknown body field. | Supply a positive integer revision, allowed action and non-empty note. |
400 | {"error": "invalid_managed_service_request"} | The lifecycle store rejected the input. | Inspect its message and correct the request. |
401 | {"error": "unauthorized"} | Missing, revoked, expired or invalid API key. | Send a valid key. |
403 | {"error": "forbidden"} | A sign-in token has no usable account. | Use an invited account or its API key. |
403 | {"error": "managed_service_account_required"} | The caller has no active, allocated account. | Check the account used by your credential. |
503 | {"error": "accounting_unavailable"} | Authentication could not check the account database. | Retry shortly. |
403 | {"error": "account_suspended"} | The account became suspended before the operation could complete. | Restore account access. |
404 | {"error": "managed_service_not_found"} | Invalid UUID, missing instance or an instance of another account. | Check the ID and account. |
409 | {"error": "service_changed"} | The revision is stale. | Read the instance and reassess the action. |
409 | {"error": "service_busy"} | An action is pending, setup is incomplete, or the instance is neither ready nor suspended. | Wait for completion or resolve its recorded status. |
409 | {"error": "service_action_invalid"} | The action is not allowed in the current state. | Resume only suspended instances; rotate, resize, restore and suspend only ready ones. |
503 | {"error": "managed_service_unavailable"} | A service dependency failed or did not answer. | Retry shortly; read current status before repeating a change. |
Account and lifecycle errors may also include a human-readable message.
Example
Use INSTANCE_ID from a ready instance. Read its current revision immediately before requesting a rotation:
SERVICE_ACTION=rotate # rotate, suspend, resume or retire
SERVICE_INSTANCE=$(curl -fsS "https://grid-lab.zyxio.xyz/managed-services/instances/$INSTANCE_ID" \
-H "x-api-key: $BROWSERGRID_API_KEY")
SERVICE_REVISION=$(printf '%s' "$SERVICE_INSTANCE" | jq -er '.revision')
jq -n --argjson revision "$SERVICE_REVISION" --arg action "$SERVICE_ACTION" \
'{revision: $revision, action: $action, note: ("Requested " + $action + " from the command line")}' |
curl -fsS "https://grid-lab.zyxio.xyz/managed-services/instances/$INSTANCE_ID/actions" \
-H "x-api-key: $BROWSERGRID_API_KEY" \
-H "content-type: application/json" --data-binary @-Selected fields when a rotation was recorded but is still pending:
{
"id": "7be7d0d2-4eb8-4f38-9490-3fd25b8eb5bd",
"state": "ready",
"revision": 3,
"requestedAction": "rotate"
}Billing
No separate API fee. Active time continues to accrue until suspension or retirement actually changes the access binding's state. Completed suspension and retirement stop future plan accrual; resumption restarts it. Rotation does not stop the plan. Pausing invoicing or exhausting credit does not automatically suspend a service. See Credit and billing.
See also
GET /managed-services/instances/{instanceId}, POST /managed-services/instances/{instanceId}/credentials, Managed services.