docs/brand-kits.md

Brand Kit

Status

The current working tree implements Brand Kit as a real workspace-owned domain under app/brand/ with /v1/brand REST routes, frontend brand-kit feature modules, TypeScript/Python SDK resources, MCP brand tools, and an n8n MediaBrandKit node. Authoritative PostgreSQL migrations, RLS runtime certification, Docker/Hugging Face runtime verification, and final production certification remain deferred until all planned product phases are complete.

Domain model

BrandKit and BrandKitVersion are the canonical records. A kit owns versions through brand_kit_versions, includes workspace/creator ownership fields, and tracks status, timestamps, and an active_version_id. Versions store bounded branding fields such as colors, fonts, voice/tone metadata, asset references, watermark settings, and a metadata JSON column mapped safely away from the SQLAlchemy reserved metadata attribute.

API

Method	Endpoint	Purpose
GET	/v1/brand	List workspace brand kits with active version metadata.
POST	/v1/brand	Create a workspace brand kit.
PATCH	/v1/brand/{brand_kit_id}	Update a workspace brand kit.
DELETE	/v1/brand/{brand_kit_id}	Delete a workspace brand kit.

POST /v1/brand accepts name, optional description, and initial_version payload data. The response surface returns the kit plus its current active_version_id; it does not expose invitation tokens or secret fields.

Version-specific brand-kit routes are not exposed in the current backend contract. Python and TypeScript SDKs therefore fail closed with NotImplementedError for get_version and create_version instead of inventing endpoints.

Frontend

The frontend uses /v1/brand through frontend/features/brand-kits/api/index.ts. Brand kits appear in workspace settings navigation with permission: "admin", and capability discovery treats the brand area as active when the backend advertises the expected routes.

SDK

Both official SDKs use /v1/brand for list/get/create/update/delete operations. The Python client is defined in sdk/python/media_platform/brand_kits.py, and the TypeScript client is defined in sdk/typescript/src/resources/brand-kits.ts. Static contract tests verify route paths, request bodies, and fail-closed versioned-operation behavior.

MCP and n8n

MCP registers narrow typed brand tools through app/mcp/tools/brand.py and app/mcp/server.py. The official n8n MediaBrandKit node consumes the shared MediaRouter SDK/credential boundary; no provider credentials or raw brand documents are exposed to n8n transports.

Security and runtime

Brand kit routes reuse the existing API-key authentication, scoped workspace context, and structured audit boundary. Sensitive fields remain backend-only. PostgreSQL FORCE RLS, migration ordering, and provider-facing certification are intentionally deferred to the final production certification phase.