Outcome
Create a draft Brand version from a complete typed snapshot.
Before you start
- Verify whoami and the pinned credential context, then inspect the exact discovered action before preparing input.
- Discover a granted Brand workspace. Pass its resourceType/workspace identifier separately from input; a copied fixture identifier grants no access.
- The declared permission is brand:write. The active credential, application scope, resource binding and runtime authority must all authorize the request.
- Review the exact mutation and recovery, including destructive scope, and execute only after the intended effect is authorized.
Discover the target
topolo whoami --json
topolo actions get app_topolo_brand.brand_kit_versions.create --detail --json
topolo resources topolo-brand --json
topolo workspaces list topolo-brand --json
Request
POST /api/brand-kits/{brandKitId}/versions
Resource context is the selected Brand workspace. CLI/SDK action input includes path identifiers; direct HTTP JSON bodies exclude path parameters. Read the reviewed plan for the exact request.
Input fields
| Field | Required | Meaning |
|---|---|---|
brandKitId | Yes | Brand kit identifier in the verified Brand workspace. Read brand_kits.list before selecting it. |
snapshot | Yes | Complete typed Brand snapshot. When updating a draft this replaces the entire snapshot; it is not a partial patch. |
changeNote | Conditional/optional | Version change note, at most 500 characters. Omitted on creation means an empty note. |
Exact published input schema:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"brandKitId": {
"type": "string",
"minLength": 1,
"description": "Brand kit identifier in the verified Brand workspace. Read brand_kits.list before selecting it."
},
"snapshot": {
"type": "object",
"properties": {
"identity": {
"type": "object",
"properties": {
"displayName": {
"type": "string",
"minLength": 1
},
"legalName": {
"type": "string",
"minLength": 1
},
"shortDescription": {
"type": "string",
"minLength": 1
},
"domains": {
"default": [],
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"locales": {
"default": [
"en"
],
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"displayName",
"shortDescription",
"domains",
"locales"
],
"additionalProperties": false
},
"visual": {
"type": "object",
"properties": {
"logos": {
"type": "object",
"properties": {
"primaryAssetId": {
"type": "string",
"minLength": 1
},
"reversedAssetId": {
"type": "string",
"minLength": 1
},
"markAssetId": {
"type": "string",
"minLength": 1
},
"markReversedAssetId": {
"type": "string",
"minLength": 1
},
"lockupAssetId": {
"type": "string",
"minLength": 1
},
"minimumClearSpace": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
},
"palette": {
"type": "object",
"properties": {
"primary": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$"
},
"secondary": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$"
},
"accent": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$"
},
"background": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$"
},
"foreground": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$"
},
"semantic": {
"default": {},
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$"
}
},
"dark": {
"type": "object",
"properties": {
"primary": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$"
},
"secondary": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$"
},
"accent": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$"
},
"background": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$"
},
"foreground": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$"
}
},
"required": [
"primary",
"secondary",
"accent",
"background",
"foreground"
],
"additionalProperties": false
}
},
"required": [
"primary",
"secondary",
"accent",
"background",
"foreground",
"semantic"
],
"additionalProperties": false
},
"typography": {
"type": "object",
"properties": {
"heading": {
"type": "object",
"properties": {
"family": {
"type": "string",
"minLength": 1
},
"weights": {
"minItems": 1,
"type": "array",
"items": {
"type": "integer",
"minimum": 100,
"maximum": 900
}
},
"fallback": {
"default": [],
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"assetId": {
"type": "string",
"minLength": 1
},
"license": {
"type": "string",
"minLength": 1
}
},
"required": [
"family",
"weights",
"fallback"
],
"additionalProperties": false
},
"body": {
"type": "object",
"properties": {
"family": {
"type": "string",
"minLength": 1
},
"weights": {
"minItems": 1,
"type": "array",
"items": {
"type": "integer",
"minimum": 100,
"maximum": 900
}
},
"fallback": {
"default": [],
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"assetId": {
"type": "string",
"minLength": 1
},
"license": {
"type": "string",
"minLength": 1
}
},
"required": [
"family",
"weights",
"fallback"
],
"additionalProperties": false
}
},
"required": [
"heading",
"body"
],
"additionalProperties": false
},
"layout": {
"type": "object",
"properties": {
"radius": {
"default": 16,
"type": "number",
"minimum": 0,
"maximum": 64
},
"spacingScale": {
"minItems": 3,
"type": "array",
"items": {
"type": "number",
"exclusiveMinimum": 0
}
},
"logoPlacement": {
"default": "top-left",
"type": "string",
"enum": [
"top-left",
"top-right",
"bottom-left",
"bottom-right"
]
}
},
"required": [
"radius",
"spacingScale",
"logoPlacement"
],
"additionalProperties": false
},
"imagery": {
"type": "object",
"properties": {
"direction": {
"type": "string",
"minLength": 1
},
"avoid": {
"default": [],
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"direction",
"avoid"
],
"additionalProperties": false
},
"iconography": {
"type": "string",
"minLength": 1
},
"motion": {
"type": "string",
"minLength": 1
}
},
"required": [
"logos",
"palette",
"typography",
"layout",
"imagery"
],
"additionalProperties": false
},
"verbal": {
"type": "object",
"properties": {
"positioning": {
"type": "string",
"minLength": 1
},
"audiences": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"valuePropositions": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"tone": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"do": {
"default": [],
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"dont": {
"default": [],
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"bannedTerms": {
"default": [],
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"positioning",
"audiences",
"valuePropositions",
"tone",
"do",
"dont",
"bannedTerms"
],
"additionalProperties": false
},
"claims": {
"default": [],
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"text": {
"type": "string",
"minLength": 1
},
"status": {
"type": "string",
"enum": [
"draft",
"approved",
"restricted",
"retired"
]
},
"source": {
"type": "string",
"minLength": 1
},
"qualifier": {
"type": "string",
"minLength": 1
},
"regions": {
"default": [],
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"channels": {
"default": [],
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"validFrom": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"validUntil": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
}
},
"required": [
"id",
"text",
"status",
"regions",
"channels"
],
"additionalProperties": false
}
},
"ctas": {
"default": [],
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"url": {
"type": "string",
"format": "uri"
},
"status": {
"type": "string",
"enum": [
"draft",
"approved",
"retired"
]
},
"channels": {
"default": [],
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"tracking": {
"default": {},
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
"required": [
"id",
"label",
"url",
"status",
"channels",
"tracking"
],
"additionalProperties": false
}
},
"assets": {
"default": [],
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"kind": {
"type": "string",
"enum": [
"logo",
"font",
"image",
"icon",
"motion",
"audio",
"template"
]
},
"name": {
"type": "string",
"minLength": 1
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "string",
"pattern": "^\\/[^\\s]*$"
}
]
},
"mimeType": {
"type": "string",
"minLength": 1
},
"license": {
"type": "string",
"minLength": 1
},
"altText": {
"type": "string",
"minLength": 1
}
},
"required": [
"id",
"kind",
"name",
"url"
],
"additionalProperties": false
}
},
"accessibility": {
"type": "object",
"properties": {
"minimumContrast": {
"default": 4.5,
"type": "number",
"minimum": 1,
"maximum": 21
},
"requireAltText": {
"default": true,
"type": "boolean"
},
"reducedMotion": {
"default": true,
"type": "boolean"
}
},
"required": [
"minimumContrast",
"requireAltText",
"reducedMotion"
],
"additionalProperties": false
},
"legal": {
"type": "object",
"properties": {
"requiredDisclosures": {
"default": [],
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"prohibitedTopics": {
"default": [],
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"requiredDisclosures",
"prohibitedTopics"
],
"additionalProperties": false
},
"communications": {
"type": "object",
"properties": {
"emailLogoAssetId": {
"type": "string",
"minLength": 1
},
"senderDisplayName": {
"type": "string",
"minLength": 1,
"maxLength": 120,
"pattern": "^[^\\u0000-\\u001f\\u007f<>\"]+$"
},
"replyToAddress": {
"type": "string",
"maxLength": 254,
"format": "email",
"pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
},
"supportAddress": {
"type": "string",
"maxLength": 254,
"format": "email",
"pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
},
"legalFooter": {
"type": "object",
"properties": {
"entityName": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"registeredAddress": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"companyNumber": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
},
"additionalProperties": false
},
"unsubscribeText": {
"type": "string",
"minLength": 1,
"maxLength": 300
},
"footerText": {
"type": "string",
"minLength": 1,
"maxLength": 1000
}
},
"additionalProperties": false
}
},
"required": [
"identity",
"visual",
"verbal",
"claims",
"ctas",
"assets",
"accessibility",
"legal"
],
"additionalProperties": false,
"description": "Complete typed Brand snapshot. When updating a draft this replaces the entire snapshot; it is not a partial patch."
},
"changeNote": {
"type": "string",
"maxLength": 500,
"description": "Version change note, at most 500 characters. Omitted on creation means an empty note."
}
},
"required": [
"brandKitId",
"snapshot"
],
"additionalProperties": false
}
Effects
Creates a draft under an active kit and records its creation; the draft is not published or resolved to consumers.
Interpret the response
version contains the exact draft identifier, numeric version and snapshot. Supply the complete authoring model, including identity, visual, voice, governance, claims, CTAs and assets as required by the input schema; omitted optional/defaulted fields are normalized by the handler.
Response identifier contract:
{
"kind": "brand_kit_version",
"identifierSource": "response",
"idPath": "$.version.id"
}
Worked examples
These complete synthetic responses were captured from the local worker over canonical SQL migrations. Auth and R2 dependencies are simulated; notification delivery is not exercised. Set BRAND_WORKSPACE_ID from granted workspace discovery. Save reviewed input as payload.json, validate and inspect the unchanged plan. The final mutation command and MCP confirm flag assume the intended effect has already been authorized.
Minimal example
Input · payload.json:
{
"brandKitId": "brand_c794be50-0306-4933-8de8-5609340bed9e",
"snapshot": {
"identity": {
"displayName": "Fixture identity",
"shortDescription": "The next generation of software.",
"domains": [
"topolo.io"
],
"locales": [
"en"
]
},
"visual": {
"logos": {
"primaryAssetId": "brand_asset_dd192c95-76da-4c2e-a61c-8b164686806b"
},
"palette": {
"primary": "#111827",
"secondary": "#E5E7EB",
"accent": "#F97316",
"background": "#FFFFFF",
"foreground": "#111827",
"semantic": {}
},
"typography": {
"heading": {
"family": "Inter",
"weights": [
700
],
"fallback": [
"sans-serif"
]
},
"body": {
"family": "Inter",
"weights": [
400,
600
],
"fallback": [
"sans-serif"
]
}
},
"layout": {
"radius": 16,
"spacingScale": [
4,
8,
16
],
"logoPlacement": "top-left"
},
"imagery": {
"direction": "Bold, graphic, product-led.",
"avoid": [
"generic stock photography"
]
}
},
"verbal": {
"positioning": "Enterprise-grade software without enterprise-era waste.",
"audiences": [
"small businesses"
],
"valuePropositions": [
"One connected software ecosystem"
],
"tone": [
"bold",
"direct"
],
"do": [
"Use specific proof"
],
"dont": [
"Use unsupported superlatives"
],
"bannedTerms": [
"guaranteed riches"
]
},
"claims": [],
"ctas": [],
"assets": [
{
"id": "brand_asset_dd192c95-76da-4c2e-a61c-8b164686806b",
"kind": "logo",
"name": "Fixture logo",
"url": "/api/brand-assets/brand_asset_dd192c95-76da-4c2e-a61c-8b164686806b/content",
"mimeType": "image/svg+xml"
}
],
"accessibility": {
"minimumContrast": 4.5,
"requireAltText": true,
"reducedMotion": true
},
"legal": {
"requiredDisclosures": [],
"prohibitedTopics": []
}
}
}
CLI:
topolo actions validate app_topolo_brand.brand_kit_versions.create --data @payload.json --json
topolo actions plan app_topolo_brand.brand_kit_versions.create --resource-type workspace --resource-id "$BRAND_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_brand.brand_kit_versions.create --resource-type workspace --resource-id "$BRAND_WORKSPACE_ID" --data @payload.json --confirm --json
MCP tool and arguments:
{
"tool": "topolo_call_action",
"arguments": {
"actionId": "app_topolo_brand.brand_kit_versions.create",
"input": {
"brandKitId": "brand_c794be50-0306-4933-8de8-5609340bed9e",
"snapshot": {
"identity": {
"displayName": "Fixture identity",
"shortDescription": "The next generation of software.",
"domains": [
"topolo.io"
],
"locales": [
"en"
]
},
"visual": {
"logos": {
"primaryAssetId": "brand_asset_dd192c95-76da-4c2e-a61c-8b164686806b"
},
"palette": {
"primary": "#111827",
"secondary": "#E5E7EB",
"accent": "#F97316",
"background": "#FFFFFF",
"foreground": "#111827",
"semantic": {}
},
"typography": {
"heading": {
"family": "Inter",
"weights": [
700
],
"fallback": [
"sans-serif"
]
},
"body": {
"family": "Inter",
"weights": [
400,
600
],
"fallback": [
"sans-serif"
]
}
},
"layout": {
"radius": 16,
"spacingScale": [
4,
8,
16
],
"logoPlacement": "top-left"
},
"imagery": {
"direction": "Bold, graphic, product-led.",
"avoid": [
"generic stock photography"
]
}
},
"verbal": {
"positioning": "Enterprise-grade software without enterprise-era waste.",
"audiences": [
"small businesses"
],
"valuePropositions": [
"One connected software ecosystem"
],
"tone": [
"bold",
"direct"
],
"do": [
"Use specific proof"
],
"dont": [
"Use unsupported superlatives"
],
"bannedTerms": [
"guaranteed riches"
]
},
"claims": [],
"ctas": [],
"assets": [
{
"id": "brand_asset_dd192c95-76da-4c2e-a61c-8b164686806b",
"kind": "logo",
"name": "Fixture logo",
"url": "/api/brand-assets/brand_asset_dd192c95-76da-4c2e-a61c-8b164686806b/content",
"mimeType": "image/svg+xml"
}
],
"accessibility": {
"minimumContrast": 4.5,
"requireAltText": true,
"reducedMotion": true
},
"legal": {
"requiredDisclosures": [],
"prohibitedTopics": []
}
}
},
"resourceType": "workspace",
"resourceId": "<identifier returned by resource discovery>",
"confirm": true
}
}
Captured local response · HTTP 201:
{
"version": {
"id": "brand_version_5d0eb310-87f0-4a81-9f27-11240da457e6",
"brandKitId": "brand_c794be50-0306-4933-8de8-5609340bed9e",
"version": 1,
"status": "draft",
"snapshot": {
"identity": {
"displayName": "Fixture identity",
"shortDescription": "The next generation of software.",
"domains": [
"topolo.io"
],
"locales": [
"en"
]
},
"visual": {
"logos": {
"primaryAssetId": "brand_asset_dd192c95-76da-4c2e-a61c-8b164686806b"
},
"palette": {
"primary": "#111827",
"secondary": "#E5E7EB",
"accent": "#F97316",
"background": "#FFFFFF",
"foreground": "#111827",
"semantic": {}
},
"typography": {
"heading": {
"family": "Inter",
"weights": [
700
],
"fallback": [
"sans-serif"
]
},
"body": {
"family": "Inter",
"weights": [
400,
600
],
"fallback": [
"sans-serif"
]
}
},
"layout": {
"radius": 16,
"spacingScale": [
4,
8,
16
],
"logoPlacement": "top-left"
},
"imagery": {
"direction": "Bold, graphic, product-led.",
"avoid": [
"generic stock photography"
]
}
},
"verbal": {
"positioning": "Enterprise-grade software without enterprise-era waste.",
"audiences": [
"small businesses"
],
"valuePropositions": [
"One connected software ecosystem"
],
"tone": [
"bold",
"direct"
],
"do": [
"Use specific proof"
],
"dont": [
"Use unsupported superlatives"
],
"bannedTerms": [
"guaranteed riches"
]
},
"claims": [],
"ctas": [],
"assets": [
{
"id": "brand_asset_dd192c95-76da-4c2e-a61c-8b164686806b",
"kind": "logo",
"name": "Fixture logo",
"url": "/api/brand-assets/brand_asset_dd192c95-76da-4c2e-a61c-8b164686806b/content",
"mimeType": "image/svg+xml"
}
],
"accessibility": {
"minimumContrast": 4.5,
"requireAltText": true,
"reducedMotion": true
},
"legal": {
"requiredDisclosures": [],
"prohibitedTopics": []
}
},
"changeNote": "",
"createdAt": "2026-10-03T11:23:59.072Z",
"updatedAt": "2026-10-03T11:23:59.072Z",
"publishedAt": null
}
}
version contains the exact draft identifier, numeric version and snapshot. Supply the complete authoring model, including identity, visual, voice, governance, claims, CTAs and assets as required by the input schema; omitted optional/defaulted fields are normalized by the handler.
Workflow example
Input · payload.json:
{
"brandKitId": "brand_55886012-13a4-4e95-ad31-3fe2b52cdf20",
"snapshot": {
"identity": {
"displayName": "Fixture identity",
"shortDescription": "The next generation of software.",
"domains": [
"topolo.io"
],
"locales": [
"en"
]
},
"visual": {
"logos": {
"primaryAssetId": "brand_asset_87bffee4-7249-419b-b4c1-8edeeb732d55"
},
"palette": {
"primary": "#111827",
"secondary": "#E5E7EB",
"accent": "#F97316",
"background": "#FFFFFF",
"foreground": "#111827",
"semantic": {}
},
"typography": {
"heading": {
"family": "Inter",
"weights": [
700
],
"fallback": [
"sans-serif"
]
},
"body": {
"family": "Inter",
"weights": [
400,
600
],
"fallback": [
"sans-serif"
]
}
},
"layout": {
"radius": 16,
"spacingScale": [
4,
8,
16
],
"logoPlacement": "top-left"
},
"imagery": {
"direction": "Bold, graphic, product-led.",
"avoid": [
"generic stock photography"
]
}
},
"verbal": {
"positioning": "Enterprise-grade software without enterprise-era waste.",
"audiences": [
"small businesses"
],
"valuePropositions": [
"One connected software ecosystem"
],
"tone": [
"bold",
"direct"
],
"do": [
"Use specific proof"
],
"dont": [
"Use unsupported superlatives"
],
"bannedTerms": [
"guaranteed riches"
]
},
"claims": [],
"ctas": [],
"assets": [
{
"id": "brand_asset_87bffee4-7249-419b-b4c1-8edeeb732d55",
"kind": "logo",
"name": "Fixture logo",
"url": "/api/brand-assets/brand_asset_87bffee4-7249-419b-b4c1-8edeeb732d55/content",
"mimeType": "image/svg+xml"
},
{
"id": "brand_asset_dce3c24f-65dd-4579-913f-9ffbf74619c9",
"kind": "logo",
"name": "Fixture email logo",
"url": "/api/brand-assets/brand_asset_dce3c24f-65dd-4579-913f-9ffbf74619c9/content",
"mimeType": "image/png",
"altText": "Fixture email identity"
}
],
"accessibility": {
"minimumContrast": 4.5,
"requireAltText": true,
"reducedMotion": true
},
"legal": {
"requiredDisclosures": [],
"prohibitedTopics": []
},
"communications": {
"emailLogoAssetId": "brand_asset_dce3c24f-65dd-4579-913f-9ffbf74619c9",
"senderDisplayName": "Fixture identity",
"replyToAddress": "reply@example.invalid",
"supportAddress": "support@example.invalid",
"legalFooter": {
"entityName": "Fixture identity Ltd",
"registeredAddress": "1 Fixture Street, Example City",
"companyNumber": "FIXTURE-001"
},
"unsubscribeText": "Manage your message preferences.",
"footerText": "Synthetic documentation example."
}
},
"changeNote": "A reviewed example draft"
}
CLI:
topolo actions validate app_topolo_brand.brand_kit_versions.create --data @payload.json --json
topolo actions plan app_topolo_brand.brand_kit_versions.create --resource-type workspace --resource-id "$BRAND_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_brand.brand_kit_versions.create --resource-type workspace --resource-id "$BRAND_WORKSPACE_ID" --data @payload.json --confirm --json
MCP tool and arguments:
{
"tool": "topolo_call_action",
"arguments": {
"actionId": "app_topolo_brand.brand_kit_versions.create",
"input": {
"brandKitId": "brand_55886012-13a4-4e95-ad31-3fe2b52cdf20",
"snapshot": {
"identity": {
"displayName": "Fixture identity",
"shortDescription": "The next generation of software.",
"domains": [
"topolo.io"
],
"locales": [
"en"
]
},
"visual": {
"logos": {
"primaryAssetId": "brand_asset_87bffee4-7249-419b-b4c1-8edeeb732d55"
},
"palette": {
"primary": "#111827",
"secondary": "#E5E7EB",
"accent": "#F97316",
"background": "#FFFFFF",
"foreground": "#111827",
"semantic": {}
},
"typography": {
"heading": {
"family": "Inter",
"weights": [
700
],
"fallback": [
"sans-serif"
]
},
"body": {
"family": "Inter",
"weights": [
400,
600
],
"fallback": [
"sans-serif"
]
}
},
"layout": {
"radius": 16,
"spacingScale": [
4,
8,
16
],
"logoPlacement": "top-left"
},
"imagery": {
"direction": "Bold, graphic, product-led.",
"avoid": [
"generic stock photography"
]
}
},
"verbal": {
"positioning": "Enterprise-grade software without enterprise-era waste.",
"audiences": [
"small businesses"
],
"valuePropositions": [
"One connected software ecosystem"
],
"tone": [
"bold",
"direct"
],
"do": [
"Use specific proof"
],
"dont": [
"Use unsupported superlatives"
],
"bannedTerms": [
"guaranteed riches"
]
},
"claims": [],
"ctas": [],
"assets": [
{
"id": "brand_asset_87bffee4-7249-419b-b4c1-8edeeb732d55",
"kind": "logo",
"name": "Fixture logo",
"url": "/api/brand-assets/brand_asset_87bffee4-7249-419b-b4c1-8edeeb732d55/content",
"mimeType": "image/svg+xml"
},
{
"id": "brand_asset_dce3c24f-65dd-4579-913f-9ffbf74619c9",
"kind": "logo",
"name": "Fixture email logo",
"url": "/api/brand-assets/brand_asset_dce3c24f-65dd-4579-913f-9ffbf74619c9/content",
"mimeType": "image/png",
"altText": "Fixture email identity"
}
],
"accessibility": {
"minimumContrast": 4.5,
"requireAltText": true,
"reducedMotion": true
},
"legal": {
"requiredDisclosures": [],
"prohibitedTopics": []
},
"communications": {
"emailLogoAssetId": "brand_asset_dce3c24f-65dd-4579-913f-9ffbf74619c9",
"senderDisplayName": "Fixture identity",
"replyToAddress": "reply@example.invalid",
"supportAddress": "support@example.invalid",
"legalFooter": {
"entityName": "Fixture identity Ltd",
"registeredAddress": "1 Fixture Street, Example City",
"companyNumber": "FIXTURE-001"
},
"unsubscribeText": "Manage your message preferences.",
"footerText": "Synthetic documentation example."
}
},
"changeNote": "A reviewed example draft"
},
"resourceType": "workspace",
"resourceId": "<identifier returned by resource discovery>",
"confirm": true
}
}
Captured local response · HTTP 201:
{
"version": {
"id": "brand_version_d00e1d23-0626-418b-ba5c-e9c02b746293",
"brandKitId": "brand_55886012-13a4-4e95-ad31-3fe2b52cdf20",
"version": 1,
"status": "draft",
"snapshot": {
"identity": {
"displayName": "Fixture identity",
"shortDescription": "The next generation of software.",
"domains": [
"topolo.io"
],
"locales": [
"en"
]
},
"visual": {
"logos": {
"primaryAssetId": "brand_asset_87bffee4-7249-419b-b4c1-8edeeb732d55"
},
"palette": {
"primary": "#111827",
"secondary": "#E5E7EB",
"accent": "#F97316",
"background": "#FFFFFF",
"foreground": "#111827",
"semantic": {}
},
"typography": {
"heading": {
"family": "Inter",
"weights": [
700
],
"fallback": [
"sans-serif"
]
},
"body": {
"family": "Inter",
"weights": [
400,
600
],
"fallback": [
"sans-serif"
]
}
},
"layout": {
"radius": 16,
"spacingScale": [
4,
8,
16
],
"logoPlacement": "top-left"
},
"imagery": {
"direction": "Bold, graphic, product-led.",
"avoid": [
"generic stock photography"
]
}
},
"verbal": {
"positioning": "Enterprise-grade software without enterprise-era waste.",
"audiences": [
"small businesses"
],
"valuePropositions": [
"One connected software ecosystem"
],
"tone": [
"bold",
"direct"
],
"do": [
"Use specific proof"
],
"dont": [
"Use unsupported superlatives"
],
"bannedTerms": [
"guaranteed riches"
]
},
"claims": [],
"ctas": [],
"assets": [
{
"id": "brand_asset_87bffee4-7249-419b-b4c1-8edeeb732d55",
"kind": "logo",
"name": "Fixture logo",
"url": "/api/brand-assets/brand_asset_87bffee4-7249-419b-b4c1-8edeeb732d55/content",
"mimeType": "image/svg+xml"
},
{
"id": "brand_asset_dce3c24f-65dd-4579-913f-9ffbf74619c9",
"kind": "logo",
"name": "Fixture email logo",
"url": "/api/brand-assets/brand_asset_dce3c24f-65dd-4579-913f-9ffbf74619c9/content",
"mimeType": "image/png",
"altText": "Fixture email identity"
}
],
"accessibility": {
"minimumContrast": 4.5,
"requireAltText": true,
"reducedMotion": true
},
"legal": {
"requiredDisclosures": [],
"prohibitedTopics": []
},
"communications": {
"emailLogoAssetId": "brand_asset_dce3c24f-65dd-4579-913f-9ffbf74619c9",
"senderDisplayName": "Fixture identity",
"replyToAddress": "reply@example.invalid",
"supportAddress": "support@example.invalid",
"legalFooter": {
"entityName": "Fixture identity Ltd",
"registeredAddress": "1 Fixture Street, Example City",
"companyNumber": "FIXTURE-001"
},
"unsubscribeText": "Manage your message preferences.",
"footerText": "Synthetic documentation example."
}
},
"changeNote": "A reviewed example draft",
"createdAt": "2026-10-03T11:23:59.115Z",
"updatedAt": "2026-10-03T11:23:59.115Z",
"publishedAt": null
}
}
version contains the exact draft identifier, numeric version and snapshot. Supply the complete authoring model, including identity, visual, voice, governance, claims, CTAs and assets as required by the input schema; omitted optional/defaulted fields are normalized by the handler.
Verify the result
Read the returned draft and compare its complete normalized snapshot. Validate governance before requesting review or publication.
Errors and recovery
-
auth_error(HTTP 401): CLI/SDK authentication classification when Auth returns a non-code message: restore the authorized credential, then verify whoami and context. Preserve the exact service message. -
permission_denied(HTTP 403): Use the exact permission and granted resource required by the reviewed action; organization membership alone is insufficient. -
workspace_required(HTTP 400): Discover and select a granted Brand workspace before preparing the request. -
brand_storage_unavailable(HTTP 503): The Brand storage bindings are unavailable. Preserve the request identifier and report the service fault; do not retry an unverified mutation.
Recovery boundary
An authorized brand_kit_versions.discard can remove this draft while it remains unpublished.
Related actions
app_topolo_brand.brand_kits.validate: Validate content and snapshot governance against a supplied Brand snapshot.app_topolo_brand.brand_kit_versions.request_review: Record a review request for a draft version.
Evidence
Four real local SQLite stores use all canonical migrations; Auth identity/grants and archival plus R2 object storage are explicitly simulated. Notifications are disabled in fixtures. No notification delivery, live mutation, gateway credential parity or deployed environment proof is claimed. Fixture identifiers and timestamps are synthetic and must be replaced by exact authorized resource discovery.