Properties
| Name | Type | Description |
|---|---|---|
| ChangeDescription | string | Recorded on each Unit write. |
| ChangeOrderID | string | The ChangeOrder to promote. Without one, everything each upstream has reached is promoted. With one, only its range is, into the Spaces it is headed for. |
| ChangeSetID | string | An existing open ChangeSet to record every write in. |
| Clearance | object | The guarded reasons the writes are cleared for. A path whose guards this does not cover is not written, and the withheld change is reported in the Unit's Conflicts. |
| DryRun | boolean | Plan the promotion, evaluate its gates, and return the same response without writing anything. |
| ExpectedPlan | string | The Plan a previous dry run returned. If the plan now differs, nothing is written and the request fails with 412. |
| Force | boolean | Promote even though the Stage's entry gates do not hold. Requires ForceReason, and Edit permission on the ChangeOrder, where the override is recorded. |
| ForceReason | string | Why the gates were overridden. Required with Force. |
| Guards | object | Reasons to record on the paths each Unit write changes. A later operation must be cleared for them before overwriting those paths. Clearance must cover them, since a write is withheld by guards it is |
| PriorRevisions | string | With a ChangeOrder, what to do for a Unit whose last merged upstream Revision is before the ChangeOrder's start there -- typically because a Link in the upstream Space, such as a TransformPaths Link, |
| Protect | boolean | Record the paths each Unit write changes as protected local overrides, so a later merge from upstream does not overwrite them. By default a write claims nothing and each path keeps the protection it a |
| SpaceFilterID | string | A Filter over Spaces selecting the Spaces to promote. Intersected with the other selectors. |
| Squash | boolean | Merge each Unit's range as one rebased Revision rather than replaying each upstream Revision. |
| Subgroup | string | A category recorded on the Mutations of each Unit write. Alphanumeric, at most 64 characters, and not starting with ConfigHub. |
| TagID | string | A Tag to put on the Revision each Unit the promotion writes is left at, clones included. Units the promotion leaves Unchanged are not tagged. Requires Use permission on the Tag, and cannot be used wit |
| TargetStage | string | A Stage of the ChangeOrder's ChangeWorkflow to promote into. Requires a ChangeOrder with a ChangeWorkflow. When empty, and neither WhereSpace nor SpaceFilterID is given, the next Stage the change has |
| WhereSpace | string | A where expression selecting the Spaces to promote. Intersected with the other selectors. |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://artifacts.apis.io/confighub/json-schema/confighub-promote-request-schema.json",
"title": "PromoteRequest",
"x-generated": "2026-11-10",
"x-method": "derived",
"x-generator": "derive-json-schema.py",
"x-source": "openapi/confighub-promote-api-openapi.yml#/components/schemas/PromoteRequest",
"type": "object",
"properties": {
"ChangeDescription": {
"type": "string",
"description": "Recorded on each Unit write.",
"x-go-type-skip-optional-pointer": true
},
"ChangeOrderID": {
"type": "string",
"description": "The ChangeOrder to promote. Without one, everything each upstream has reached is promoted. With one, only its range is, into the Spaces it is headed for.",
"format": "uuid"
},
"ChangeSetID": {
"type": "string",
"description": "An existing open ChangeSet to record every write in.",
"format": "uuid"
},
"Clearance": {
"allOf": [
{
"$ref": "#/$defs/Clearance"
}
],
"description": "The guarded reasons the writes are cleared for. A path whose guards this does not cover is not written, and the withheld change is reported in the Unit's Conflicts."
},
"DryRun": {
"type": "boolean",
"description": "Plan the promotion, evaluate its gates, and return the same response without writing anything.",
"x-go-type-skip-optional-pointer": true
},
"ExpectedPlan": {
"type": "string",
"description": "The Plan a previous dry run returned. If the plan now differs, nothing is written and the request fails with 412.",
"x-go-type-skip-optional-pointer": true
},
"Force": {
"type": "boolean",
"description": "Promote even though the Stage's entry gates do not hold. Requires ForceReason, and Edit permission on the ChangeOrder, where the override is recorded.",
"x-go-type-skip-optional-pointer": true
},
"ForceReason": {
"type": "string",
"description": "Why the gates were overridden. Required with Force.",
"x-go-type-skip-optional-pointer": true
},
"Guards": {
"allOf": [
{
"$ref": "#/$defs/GuardStamp"
}
],
"description": "Reasons to record on the paths each Unit write changes. A later operation must be cleared for them before overwriting those paths. Clearance must cover them, since a write is withheld by guards it is not cleared for, its own included."
},
"PriorRevisions": {
"enum": [
"Include",
"Skip",
"Error",
"All"
],
"type": "string",
"description": "With a ChangeOrder, what to do for a Unit whose last merged upstream Revision is before the ChangeOrder's start there -- typically because a Link in the upstream Space, such as a TransformPaths Link, wrote Revisions after the Unit last merged. Include merges those Revisions first, as Revisions of their own that do not carry the ChangeOrder, and then the ChangeOrder's range; Skip merges only the ChangeOrder's range, as though the Unit had already merged as far as its start, and those Revisions do not arrive later; Error refuses, naming the Revisions; All merges them as Include does, and also marks every Unit in the Space the change does not change at its head, so the next promotion brings it up to this Space. Defaults to the ChangeOrder's PriorRevisions, or Include. A Unit that has merged past the ChangeOrder's start is an error whatever this says. Refused with an Insert, Upsert, or TransformPaths ChangeOrder, whose Links read their sources as they are at its end rather than merging a range.",
"x-go-type-skip-optional-pointer": true
},
"Protect": {
"type": "boolean",
"description": "Record the paths each Unit write changes as protected local overrides, so a later merge from upstream does not overwrite them. By default a write claims nothing and each path keeps the protection it already had. Accepted only for an Invoke ChangeOrder and for one that follows Insert, Upsert, or TransformPaths Links: refused for a promotion that merges, which protection holds paths against.",
"x-go-type-skip-optional-pointer": true
},
"SpaceFilterID": {
"type": "string",
"description": "A Filter over Spaces selecting the Spaces to promote. Intersected with the other selectors.",
"format": "uuid"
},
"Squash": {
"type": "boolean",
"description": "Merge each Unit's range as one rebased Revision rather than replaying each upstream Revision.",
"x-go-type-skip-optional-pointer": true
},
"Subgroup": {
"type": "string",
"description": "A category recorded on the Mutations of each Unit write. Alphanumeric, at most 64 characters, and not starting with ConfigHub.",
"x-go-type-skip-optional-pointer": true
},
"TagID": {
"type": "string",
"description": "A Tag to put on the Revision each Unit the promotion writes is left at, clones included. Units the promotion leaves Unchanged are not tagged. Requires Use permission on the Tag, and cannot be used with ChangeOrderID, whose own Tags mark what it promotes. A selected Space with a Unit to write that the Tag already marks fails, and nothing in it is written.",
"format": "uuid"
},
"TargetStage": {
"type": "string",
"description": "A Stage of the ChangeOrder's ChangeWorkflow to promote into. Requires a ChangeOrder with a ChangeWorkflow. When empty, and neither WhereSpace nor SpaceFilterID is given, the next Stage the change has not reached.",
"x-go-type-skip-optional-pointer": true
},
"WhereSpace": {
"type": "string",
"description": "A where expression selecting the Spaces to promote. Intersected with the other selectors.",
"x-go-type-skip-optional-pointer": true
}
},
"$defs": {
"Clearance": {
"type": "array",
"items": {
"$ref": "#/$defs/ClearanceRequirement"
}
},
"ClearanceRequirement": {
"type": "object",
"properties": {
"Key": {
"type": "string",
"description": "The guard key this requirement is about",
"x-go-type-skip-optional-pointer": true
},
"Operator": {
"type": "string",
"description": "Exists, In, NotIn, or DoesNotExist",
"x-go-type-skip-optional-pointer": true
},
"Values": {
"type": "array",
"items": {
"type": "string"
},
"description": "The values In and NotIn compare against; unused by Exists and DoesNotExist",
"x-go-type-skip-optional-pointer": true
}
}
},
"GuardStamp": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
}
Work with this as data
Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for schemas
4 MCP tools reach this
find_json_schemasBrowse and filter every JSON Schema in the catalog.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/confighub-promote-request"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.