Apply a signed plan once.

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

Idempotent on planId: a second (or concurrent) apply of the same plan returns the first apply's result without writing again (queued while the first is still running). Apply re-checks the stored change against what exists now; when it moved, the answer is 409 change_plan_stale with a fix (plan again). An expired plan is 409 too. A partial result stays open: applying the same plan again finishes only what is left. Another location's or project's plan is 404.

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

planIdstringrequired

The planId POST …/changes/plan returned.

Possible values: <= 2048 characters, Value must match regular expression ^cp1\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$

Example (auto)

{
  "planId": "cp1.eyJwIjoicHJqXzVmMGMyYTNlIn0.c2lnbmF0dXJl"
}

application/json

What the apply did.

application/json

Schema

Schema

statusstringrequired
applied: done. queued: accepted and finishing in the background (or another apply of this plan is running). partial: some steps failed; apply the same plan again to finish.
Available optionsappliedqueuedpartial
jobIdstring

The background operation, when one was queued (app-config operation id).

resultrequired

Kind-specific outcome, e.g. records {ok, created, reused, updated, deleted, skipped, failed}; null while another apply runs.

linksobjectrequired

Where to see the result.

Example (auto)

{
  "status": "applied",
  "jobId": "op_8d41c4b9",
  "result": {
    "ok": true,
    "created": 2,
    "reused": 1
  },
  "links": {
    "preview": "https://preview.example.com/my-portal"
  }
}

Example

{
  "status": "applied",
  "result": {
    "enabled": [
      "courses"
    ],
    "already": []
  },
  "links": {}
}