POST /managed-services/instances
Provision PostgreSQL + PgBouncer, MLflow, LiteLLM or Valkey / Redis for your account.
Syntax
POST https://grid-lab.zyxio.xyz/managed-services/instances
x-api-key: <key>
content-type: application/json
{"requestId": "<UUID>", "service": "postgres", "name": "example-postgres", "note": "Application workspace"}Request
| Name | Where | Required | Meaning |
|---|---|---|---|
x-api-key | header | yes, or Authorization | Your API key, or Authorization: Bearer <token> from Zyxio sign-in. |
requestId | body | yes | A UUID you generate and retain for retries. Reusing it with the same normalized details returns the same instance. |
service | body | yes | postgres, mlflow, litellm or redis. |
name | body | yes | Trimmed text, 1 to 100 characters. |
profile | body | no | Omit for the private platform. awow-azure selects the separate Azure profile, which requires its own deployment and qualification. |
note | body | no | Trimmed text, up to 2,000 characters. Defaults to an empty string. |
Unknown fields are refused. Account and actor come from authentication; do not send accountId or actor. Neither names nor notes should contain passwords or provider keys. An active account with available credit or monthly invoicing capacity is required.
Response
201 Created when the returned instance has state: "ready"; 202 Accepted for every other state. The body is the full instance record documented by GET /managed-services/instances/{instanceId}; there is no envelope or schemaVersion on an instance record.
Provisioning is attempted after the request is recorded. A provisioner failure can leave the request pending without changing the response into an error. Keep id, inspect state, requestedAction and statusNote, and poll the instance until ready. Passwords are delivered separately by POST /managed-services/instances/{instanceId}/credentials.
Reusing requestId with the same service, trimmed name, defaulted profile and trimmed note returns the existing instance. The status still follows its current state: 201 if ready, otherwise 202. A pending request is not a reason to create another UUID.
Errors
| Status | Body | When | What to do |
|---|---|---|---|
400 | {"error": "invalid_managed_service_request"} | A required field is missing, invalid or unknown. | Use the exact fields and bounds above. |
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. |
403 | {"error": "billing_setup_required"} | The account has no available credit or monthly invoicing capacity. | Add credit or restore invoicing capacity. |
409 | {"error": "request_conflict"} | The same requestId was used with different details. | Retry the original body, or use a new UUID for a different instance. |
503 | {"error": "managed_service_unavailable"} | A service dependency failed or did not answer. | Retry shortly; read current status before repeating a change. |
Errors from account and lifecycle checks may also include a human-readable message; use error as the stable code.
Example
Requires Bash, curl, jq, uuidgen and your API key. Change SERVICE to provision another service; keep the request body when retrying.
SERVICE=postgres # postgres, mlflow, litellm or redis
SERVICE_REQUEST_ID=$(uuidgen)
SERVICE_REQUEST=$(jq -n --arg requestId "$SERVICE_REQUEST_ID" --arg service "$SERVICE" \
'{requestId: $requestId, service: $service, name: ("example-" + $service)}')
SERVICE_INSTANCE=$(curl -fsS https://grid-lab.zyxio.xyz/managed-services/instances \
-H "x-api-key: $BROWSERGRID_API_KEY" \
-H "content-type: application/json" -d "$SERVICE_REQUEST")
INSTANCE_ID=$(printf '%s' "$SERVICE_INSTANCE" | jq -er '.id')
printf '%s\n' "$SERVICE_INSTANCE" | jq '{id, service, state, revision, requestedAction}'Selected fields from a response where provisioning is still pending:
{
"id": "7be7d0d2-4eb8-4f38-9490-3fd25b8eb5bd",
"service": "postgres",
"state": "requested",
"revision": 1,
"requestedAction": "provision"
}Billing
The API call has no separate fee. Active service time is charged under rate card 2026-10-14.commercial-1: postgres.plan €49.00, mlflow.plan €39.00, litellm.plan €29.00 or redis.plan €15.00 per Tier-1 base workspace-month, prorated per active millisecond of each UTC calendar month. No full-month reservation is held at provisioning. See Managed services and Credit and billing.
See also
Managed services, GET /managed-services/instances, GET /managed-services/instances/{instanceId}, POST /managed-services/instances/{instanceId}/credentials.