Appearance

Promote an environment ​

"Promote" can mean two different things on an environment — they're independent and you'll use both at different times.

What you're trying to doAxis to flipWhat it controls
Make this environment visible by default in the grid for everyoneclassification (AD_HOC → STANDARD)Display
Make this environment writable so per-env flag rules / config overrides / logger levels can be saved against itmanaged (false → true)Quota + write access

The two axes are independent. A fresh free account is seeded with staging already STANDARD (visible) but managed = false (writes rejected) — promoting it to managed is the common first step. Read Environments for the full model.

Prerequisites: OWNER or ADMIN role on the account.

Promote to managed (enable writes) ​

Use this when writes to per-environment flag rules / config overrides / logger levels return 400 environment_unmanaged. Promotion to managed consumes one platform.managed_environments quota slot.

In the console ​

  1. Go to Environments in the platform sidebar (/platform/environments).
  2. Find the environment in the list. Unmanaged environments show with the Unmanaged badge.
  3. Click Promote in the row's action column.
  4. Confirm. The environment flips to Managed and now accepts per-env writes.

If your account is at its platform.managed_environments quota, the promote button explains the limit and links to subscription management; nothing changes until you free a slot or upgrade.

Via the API ​

PUT /api/v1/environments/{id} flipping managed to true:

bash
curl -X PUT https://app.smplkit.com/api/v1/environments/staging \
  -H "Authorization: Bearer $SMPLKIT_API_KEY" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "environment",
      "id": "staging",
      "attributes": {
        "name": "Staging",
        "color": "#eab308",
        "classification": "STANDARD",
        "managed": true
      }
    }
  }'

JSON:API is full-replace — send the existing name, color, and classification alongside the new managed. The platform's check_managed_environment_promotion_limit only fires on the false → true transition, so PUTs that don't change managed are never quota-gated.

At-limit promotion returns 402 Payment Required:

json
{
  "errors": [{
    "status": "402",
    "code": "entitlement_limit_reached",
    "title": "Subscription limit reached",
    "detail": "Your free plan for platform allows a maximum of 2 platform managed_environments. Upgrade your subscription to increase this limit.",
    "meta": {
      "limit_key": "platform.managed_environments",
      "current": 2,
      "maximum": 2,
      "product": "platform",
      "plan": "free"
    }
  }]
}

Demote from managed ​

Demoting (managed = true → false) frees the quota slot. Per-environment values across all products are retained but frozen — runtime evaluations still see them, but new writes are rejected with environment_unmanaged. Re-promoting later restores write access without data loss.

bash
curl -X PUT https://app.smplkit.com/api/v1/environments/staging \
  -H "Authorization: Bearer $SMPLKIT_API_KEY" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "environment",
      "id": "staging",
      "attributes": {
        "name": "Staging", "color": "#eab308",
        "classification": "STANDARD", "managed": false
      }
    }
  }'

production is locked managed and cannot be demoted — every account is guaranteed at least one writable environment.

Promote classification (AD_HOC → STANDARD) ​

Use this when an auto-discovered environment (like a developer's laptop mike-laptop, or a per-PR preview pr-1234) becomes something the whole team should see by default. This is purely a display change; it does not affect writes or quota.

In the console ​

  1. Environments in the platform sidebar.
  2. Find the row. Ad-hoc environments show with the Ad hoc badge.
  3. Toggle classification to Standard.
  4. Save.

The environment now appears as a column in the product grids for every user.

Via the API ​

bash
curl -X PUT https://app.smplkit.com/api/v1/environments/staging \
  -H "Authorization: Bearer $SMPLKIT_API_KEY" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "environment",
      "id": "staging",
      "attributes": {
        "name": "Staging", "color": "#eab308",
        "classification": "STANDARD", "managed": true
      }
    }
  }'

The platform handles the display cascade — the environment is added to account.settings.environment_order and to every existing user's account_user.settings.environment_order that doesn't already include it.

Demote classification (STANDARD → AD_HOC) ​

bash
curl -X PUT https://app.smplkit.com/api/v1/environments/feature-spike \
  -H "Authorization: Bearer $SMPLKIT_API_KEY" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "environment",
      "id": "feature-spike",
      "attributes": {
        "name": "Feature Spike", "color": null,
        "classification": "AD_HOC", "managed": false
      }
    }
  }'

Demotion removes the environment from the account-level order only. Users who had personalized to include it keep seeing it. New users (with no personal order) won't.

Verify ​

bash
curl https://app.smplkit.com/api/v1/environments/staging \
  -H "Authorization: Bearer $SMPLKIT_API_KEY"

Check data.attributes.managed and data.attributes.classification. Then check the account settings:

bash
curl https://app.smplkit.com/api/v1/accounts/current/settings \
  -H "Authorization: Bearer $SMPLKIT_API_KEY"

environment_order should include the promoted environment if you flipped classification.

Try a write that targets the environment — a per-env flag default, config override, or logger level. It should succeed if managed = true; otherwise it returns 400 with code: environment_unmanaged.