Versions and edits
An app’s version history, comparing two versions as permission facts, rolling back, and changing an app by a sentence. 6 routes, from the API’s own OpenAPI document.
6 routes. Every path starts at https://cloud-api.qaldy.com. Sign-in, tokens, errors and limits are on the overview.
Routes#
| Method | Path | What it does |
|---|---|---|
| POST | /v1/apps/{id}/changes | Plan a change to an app from a sentence: the permission diff, nothing built yet |
| GET | /v1/apps/{id}/versions | An app’s versions, newest first, and its rollbacks |
| POST | /v1/apps/{id}/versions/{versionId}/rollback | Go back to an older version: one pointer move, no rebuild |
| GET | /v1/apps/{id}/versions/compare | What one version may do that another could not, in permission sentences |
| GET | /v1/changes/{changeId} | Where a change is: planned, building, live or failed |
| POST | /v1/changes/{changeId}/approve | Approve a planned change: the new version is written and the app moves to it |
Reference#
POST /v1/apps/{id}/changes#
Plan a change to an app from a sentence: the permission diff, nothing built yet.
- Authentication: the console’s session cookie.
- Token: a personal access token or an MCP sign-in with the
writescope. - Who:
can_edit
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string | yes | 1 to 128 characters |
Request body (application/json)
| Field | Type | Required | Notes |
|---|---|---|---|
instruction | string | yes | 4 to 2000 characters |
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
changeId | string | yes | at least 1 characters |
appId | string | yes | at least 1 characters |
appName | string | yes | at least 1 characters |
baseVersionId | string | yes | at least 1 characters |
instruction | string | yes | |
summary | string | yes | 1 to 300 characters |
manifest | object | yes | |
manifest.name | string | yes | 2 to 60 characters |
manifest.description | string | yes | 4 to 280 characters |
manifest.archetype | "kiosk" · "tower" · "warehouse" · "workshop" · "bank" · "townhall" · "clocktower" · "printhouse" · … | yes | |
manifest.category | "interface" · "data" · "messaging" · "money" · "ai" · "time" · "people" · "growth" | yes | |
manifest.permissions | object | yes | |
manifest.triggers | object[] | yes | |
manifest.sharing | object | yes | |
manifest.roi | object | yes | |
diff | object | yes | |
diff.gains | object[] | yes | |
diff.losses | object[] | yes | |
diff.triggersAdded | object[] | yes | |
diff.triggersRemoved | object[] | yes | |
diff.details | object[] | yes | |
steps | string[] | yes | |
rebuildsCode | boolean | yes | |
builder | "claude" · "offline" | yes | |
model | string or null | yes | |
templateId | string or null | yes | |
notes | string[] | yes | up to 8 items |
adminApproval | object | yes | |
adminApproval.required | boolean | yes | |
adminApproval.connectors | string[] | yes |
…and 2 more fields. The full schema is in openapi.json.
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).
GET /v1/apps/{id}/versions#
An app’s versions, newest first, and its rollbacks.
- Authentication: the console’s session cookie.
- Token: a personal access token or an MCP sign-in with the
readscope. - Who:
can_view
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string | yes | 1 to 128 characters |
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
appId | string | yes | at least 1 characters |
currentVersionId | string or null | yes | |
versions | object[] | yes | |
versions[].id | string | yes | at least 1 characters |
versions[].appId | string | yes | at least 1 characters |
versions[].number | integer | yes | at least 1 |
versions[].createdAt | string (date-time) | yes | |
versions[].createdBy | string | yes | at least 1 characters |
versions[].createdByName | string or null | yes | |
versions[].bundleHash | string | yes | at least 1 characters |
versions[].trustScore | integer | yes | 0 to 100 |
versions[].trustBand | "pass" · "review" · "fail" | yes | |
versions[].kind | "build" · "edit" · "seed" | yes | |
versions[].summary | string | yes | 1 to 300 characters |
versions[].instruction | string or null | yes | |
versions[].baseVersionId | string or null | yes | |
versions[].isCurrent | boolean | yes | |
versions[].runnable | boolean | yes | |
versions[].builder | "claude" · "offline" · null or null | yes | |
rollbacks | object[] | yes | |
rollbacks[].at | string (date-time) | yes | |
rollbacks[].byName | string or null | yes | |
rollbacks[].fromVersionId | string | yes | at least 1 characters |
rollbacks[].toVersionId | string | yes | at least 1 characters |
canEdit | boolean | yes |
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).
POST /v1/apps/{id}/versions/{versionId}/rollback#
Go back to an older version: one pointer move, no rebuild.
- Authentication: the console’s session cookie.
- Token: a personal access token or an MCP sign-in with the
writescope. - Who:
can_edit
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string | yes | 1 to 128 characters |
versionId | path | string | yes | 1 to 128 characters |
Request body (application/json)
| Field | Type | Required | Notes |
|---|---|---|---|
expectCurrentVersionId | string | yes | at least 1 characters |
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
appId | string | yes | at least 1 characters |
fromVersionId | string | yes | at least 1 characters |
toVersionId | string | yes | at least 1 characters |
trustScore | integer | yes | 0 to 100 |
diff | object | yes | |
diff.gains | object[] | yes | |
diff.losses | object[] | yes | |
diff.triggersAdded | object[] | yes | |
diff.triggersRemoved | object[] | yes | |
diff.details | object[] | yes |
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).
GET /v1/apps/{id}/versions/compare#
What one version may do that another could not, in permission sentences.
- Authentication: the console’s session cookie.
- Token: a personal access token or an MCP sign-in with the
readscope. - Who:
can_view
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string | yes | 1 to 128 characters |
to | query | string | yes | 1 to 128 characters |
from | query | string | 1 to 128 characters |
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
from | object | yes | |
from.id | string | yes | at least 1 characters |
from.appId | string | yes | at least 1 characters |
from.number | integer | yes | at least 1 |
from.createdAt | string (date-time) | yes | |
from.createdBy | string | yes | at least 1 characters |
from.createdByName | string or null | yes | |
from.bundleHash | string | yes | at least 1 characters |
from.trustScore | integer | yes | 0 to 100 |
from.trustBand | "pass" · "review" · "fail" | yes | |
from.kind | "build" · "edit" · "seed" | yes | |
from.summary | string | yes | 1 to 300 characters |
from.instruction | string or null | yes | |
from.baseVersionId | string or null | yes | |
from.isCurrent | boolean | yes | |
from.runnable | boolean | yes | |
from.builder | "claude" · "offline" · null or null | yes | |
to | object | yes | |
to.id | string | yes | at least 1 characters |
to.appId | string | yes | at least 1 characters |
to.number | integer | yes | at least 1 |
to.createdAt | string (date-time) | yes | |
to.createdBy | string | yes | at least 1 characters |
to.createdByName | string or null | yes | |
to.bundleHash | string | yes | at least 1 characters |
to.trustScore | integer | yes | 0 to 100 |
to.trustBand | "pass" · "review" · "fail" | yes | |
to.kind | "build" · "edit" · "seed" | yes | |
to.summary | string | yes | 1 to 300 characters |
to.instruction | string or null | yes |
…and 8 more fields. The full schema is in openapi.json.
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).
GET /v1/changes/{changeId}#
Where a change is: planned, building, live or failed.
- Authentication: the console’s session cookie.
- Token: a personal access token or an MCP sign-in with the
readscope. - Who: plan's owner
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
changeId | path | string | yes | 1 to 128 characters |
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
changeId | string | yes | at least 1 characters |
appId | string | yes | at least 1 characters |
state | "planned" · "building" · "live" · "failed" · "expired" | yes | |
message | string or null | yes | |
versionId | string or null | yes | |
trustScore | integer or null | yes | 0 to 100 |
stage | string or null | yes | |
plan | object or null | ||
plan.changeId | string | yes | at least 1 characters |
plan.appId | string | yes | at least 1 characters |
plan.appName | string | yes | at least 1 characters |
plan.baseVersionId | string | yes | at least 1 characters |
plan.instruction | string | yes | |
plan.summary | string | yes | 1 to 300 characters |
plan.manifest | object | yes | |
plan.diff | object | yes | |
plan.steps | string[] | yes | |
plan.rebuildsCode | boolean | yes | |
plan.builder | "claude" · "offline" | yes | |
plan.model | string or null | yes | |
plan.templateId | string or null | yes | |
plan.notes | string[] | yes | up to 8 items |
plan.adminApproval | object | yes | |
plan.needsConsole | string[] | yes | |
plan.expiresAt | string (date-time) | yes |
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).
POST /v1/changes/{changeId}/approve#
Approve a planned change: the new version is written and the app moves to it.
- Authentication: the console’s session cookie.
- Token: a personal access token or an MCP sign-in with the
writescope. - Who: plan's owner with
can_edit; over a token only inside the safe band
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
changeId | path | string | yes | 1 to 128 characters |
Request body (application/json)
| Field | Type | Required | Notes |
|---|---|---|---|
manifest | object | yes | |
manifest.name | string | yes | 2 to 60 characters |
manifest.description | string | yes | 4 to 280 characters |
manifest.archetype | "kiosk" · "tower" · "warehouse" · "workshop" · "bank" · "townhall" · "clocktower" · "printhouse" · … | yes | |
manifest.category | "interface" · "data" · "messaging" · "money" · "ai" · "time" · "people" · "growth" | yes | |
manifest.permissions | object | yes | |
manifest.permissions.data | object[] | yes | |
manifest.permissions.connectors | object[] | yes | |
manifest.permissions.egress | object[] | yes | |
manifest.permissions.ai | object or null | yes | |
manifest.triggers | object[] | yes | |
manifest.sharing | object | yes | |
manifest.sharing.default | "private" · "team" · "workspace" | yes | |
manifest.roi | object | yes | |
manifest.roi.manualMinutesPerRun | number | yes | 0 to 1440 |
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
changeId | string | yes | at least 1 characters |
appId | string | yes | at least 1 characters |
state | "planned" · "building" · "live" · "failed" · "expired" | yes | |
message | string or null | yes | |
versionId | string or null | yes | |
trustScore | integer or null | yes | 0 to 100 |
stage | string or null | yes | |
plan | object or null | ||
plan.changeId | string | yes | at least 1 characters |
plan.appId | string | yes | at least 1 characters |
plan.appName | string | yes | at least 1 characters |
plan.baseVersionId | string | yes | at least 1 characters |
plan.instruction | string | yes | |
plan.summary | string | yes | 1 to 300 characters |
plan.manifest | object | yes | |
plan.diff | object | yes | |
plan.steps | string[] | yes | |
plan.rebuildsCode | boolean | yes | |
plan.builder | "claude" · "offline" | yes | |
plan.model | string or null | yes | |
plan.templateId | string or null | yes | |
plan.notes | string[] | yes | up to 8 items |
plan.adminApproval | object | yes | |
plan.needsConsole | string[] | yes | |
plan.expiresAt | string (date-time) | yes |
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).