Preview a configuration change

POST

/api/v1/settings/plans

curl --request POST \
  --url 'https://api.inside.chat/api/v1/settings/plans?website_id=example' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "path": "example", "expected_version": 1, "changes": { "name": "example", "enabled": true } }'

• Hosted Gateway
• Local development

Required scopes: config_read, config_plan
Data access: –
MCP tool: config_plan
Note: Write
Note: Idempotency-Key required
Note: preview only

Preview an exact name/enabled diff for an owned AI feature at the expected latest active version. Requires an unrestricted installation policy. This dry run changes no native configuration, creates no approval or apply authority, and preserves all hidden settings. Native apply remains unavailable. Results are retained for 24 hours. A permanent content-free tombstone prevents the same key from creating a new effect after result expiry. Reuse the same key and identical input when retrying. Changed input or policy/revisions conflict. Current policy is checked before result reuse. An unknown outcome returns 409 outcome_unknown; never retry with a new key automatically.

Authorizations

• installation_token
• oauth_client_credentials
  config_read config_plan

Parameters

Query Parameters

website_id

required

string

/^web_[0-9]{1,20}_[1-9][0-9]{0,18}$/

An explicitly granted website.

Header Parameters

Idempotency-Key

required

string

>= 1 characters <= 128 characters /^[!-~]+$/

A stable key for this intended effect. Reuse the same key and input for retries; never automatically replace it after an unknown outcome.

Request Body^required

Media typeapplication/json

object

path

required

string

<= 200 characters /^/ai/features/aif_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$/

expected_version

required

integer

>= 1 <= 2147483647

changes

required

object

>= 1 properties

name

string

>= 1 characters <= 200 characters /^(?=.*\S)[^<>\x00-\x1f\x7f-\x9f]+$/

enabled

boolean

Example ^generated

{
  "path": "example",
  "expected_version": 1,
  "changes": {
    "name": "example",
    "enabled": true
  }
}

Responses

200

Authorized result. Projection depends on current scopes and data policy.

Media typeapplication/json

A dry-run diff. Nothing is saved, and the preview grants no approval or apply authority.

object

data

required

object

preview

required

object

website_id

required

string

/^web_[0-9]{1,20}_[1-9][0-9]{0,18}$/

path

required

string

feature_id

required

string

/^aif_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$/

expected_version

required

integer

>= 1

changes

required

Actual changes only, in name then enabled order. Empty for a no-op.

Array<object>

object

field

required

string

Allowed values: name enabled

before

required

Any of:

string

string

boolean

boolean

after

required

Any of:

string

string

boolean

boolean

has_changes

required

boolean

approval_required

required

apply_available

required

status

required

Allowed value: preview_only

Example

{
  "data": {
    "preview": {
      "changes": [
        {
          "field": "name"
        }
      ],
      "approval_required": true,
      "apply_available": false,
      "status": "preview_only"
    }
  }
}

Headers

X-Gateway-Operation-Id

string

/^op_[a-f0-9]{64}$/

Retained command receipt identifier when command reservation was acknowledged; use operation_get with the original credential and website. Not proof of native success or delivery.

400

Invalid, duplicate or unsupported request parameters.

401

Missing, expired or revoked installation credential.

404

Resource not found or not permitted by current authority.

409

Idempotency_conflict: the key has different input or authority revisions; operation_in_progress: the same command is pending; operation_conflict: native business state rejects the change; outcome_unknown: the native result is uncertain or no longer retained. Keep the same key and input for retries; never automatically create a new key or resubmit the effect.

Media typeapplication/problem+json

object

type

required

string

title

required

string

status

required

integer

Allowed value: 409

code

required

string

Allowed values: idempotency_conflict operation_in_progress operation_conflict outcome_unknown

request_id

required

string

Example

{
  "status": 409,
  "code": "idempotency_conflict"
}

Headers

X-Gateway-Operation-Id

string

/^op_[a-f0-9]{64}$/

Retained command receipt identifier when command reservation was acknowledged; use operation_get with the original credential and website. Not proof of native success or delivery.

422

The requested capability is not available for application installations.

429

Per-app quota exceeded.

Headers

Retry-After

integer

>= 1

503

Enrollment, native service or required authority is unavailable.