Check a change of one kind and sign a plan for it, without writing anything.

POST 
/ai-builder-api/projects/:projectId/changes/plan

The caller's AI writes a change of one kind; the server validates it against that kind's schema and against what exists now (CRM, modules, saved customization) and answers what applying it would do. Nothing is written and no model is called. planId is a signed token over {projectId, locationId, kind, changeHash} that expires at expiresAt; it is null when ok is false. The location is the session's, never the body's. Kinds: records, modules, appearance, mobile, assets, domain; any other kind is 400 unsupported_change_kind naming the supported ones. assets plans also return upload: PUT the image bytes to upload.url with upload.headers, then apply (apply is 409 customizer_image_not_uploaded until they land, and the plan stays open). domain apply returns the DNS records to add in result.dnsRecords; GET /custom-domains reports when it is active.

Request

Version stringrequired

The API version.

Available optionsv3

projectId stringrequired

The project's id.

Possible values: Value must match regular expression ^prj_[A-Za-z0-9_-]+$

application/json

application/json

Body

Bodyrequired

kindstringrequired

records, modules, appearance, mobile, assets or domain.

Possible values: Value must match regular expression ^[a-z][a-z_]{0,39}$

changeobjectrequired

The change, in the shape GET /changes/schema gives for kind.

Example

{
  "kind": "modules",
  "change": {
    "enable": [
      "courses"
    ],
    "disable": []
  }
}

application/json

The checked plan, or the problems to fix first.

application/json

Schema

Schema

planIdstring | nullnullablerequired

Signed, expiring plan id; null when ok is false.

okbooleanrequired

True when the change is valid and can be applied.

summarystringrequired

The change, in one line.

diffstring[]required

What apply would do, one line per step, in order.

errorsobject[]required

Why the change cannot be applied, when ok is false.

warningsstring[]required

Things to know before applying; they do not block it.

expiresAt(string | null)<date-time>nullablerequired

When planId stops working; null when ok is false.

uploadobject

Where to upload the file the change needs, for a change that needs one.

Example (auto)

{
  "planId": "cp1.eyJwIjoicHJqXzVmMGMyYTNlIn0.c2lnbmF0dXJl",
  "ok": true,
  "summary": "Turns off Communities",
  "diff": [
    "Turn off the Communities module"
  ],
  "errors": [
    {
      "path": "change.disable.0",
      "message": "Unknown module \"forum\"",
      "fix": "Send one of: courses, communities"
    }
  ],
  "warnings": [
    "Members lose access to their community posts"
  ],
  "expiresAt": "2026-10-15T10:30:00.000Z",
  "upload": {
    "method": "PUT",
    "url": "https://storage.example.com/uploads/asset-1.png?signature=abc123",
    "headers": {
      "Content-Type": "image/png"
    },
    "assetId": "ast_7b2e91",
    "publicUrl": "https://assets.example.com/asset-1.png",
    "expiresAt": "2026-10-15T10:15:00.000Z"
  }
}

Example

1 modules step(s) ready to apply.

{
  "planId": "cp1.WyJwcmpfMSIsImxvY18xIiwibW9kdWxlcyIsImFiYyIsMTc2MDAwMDAwMDAwMF0.c2ln",
  "ok": true,
  "summary": "1 modules step(s) ready to apply.",
  "diff": [
    "Turn on Courses"
  ],
  "errors": [],
  "warnings": [],
  "expiresAt": "2026-10-07T12:30:00.000Z"
}