Brand - ContentHero

Base URL https://app.contenthero.ai/api/v1. All endpoints take a bearer API key.

Brand kit

Method	Path	Scope	Purpose
`GET`	`/brand-kits`	`brand:read`	List your brand kits.
`POST`	`/brand-kits`	`brand:write`	Create a brand kit: empty, imported (`websiteUrls` and/or its own accounts in `brandAccounts`, with `extract: true`), from a social profile, or as a copy. Every new kit starts with the eight starter sections. An import returns at once; poll `analysisStatus` and `extractionStatus`.
`GET`	`/brand-kits/{brandKitId}`	`brand:read`	Read one brand kit, three ways (below).
`PATCH`	`/brand-kits/{brandKitId}`	`brand:write`	Update the kit: section content (`sections`), media, colors, typography and linked accounts. Send `{ "archive": true }` to archive (reversible).

Sections

A brand kit’s content is a set of sections, each one Markdown document. Every kit starts with eight:

Tab	Key (and role)	Default name
`overview`	`about`, `audience`, `offer`, `content_strategy`	About, Audience, Offer, Content Strategy
`voice`	`voice_and_tone`, `writing_style`, `speaking_style`	Voice & Tone, Writing Style, Speaking Style
`visual`	`design_guidelines`	Design Guidelines

The user can rename a section and add their own. Every section has:

a key: stable and unique within the kit. Address sections by key; the user renames sectionName, never the key.
a role: what a starter section means, the same in every kit whatever it is named. A section the user added has none.
a body: Markdown, in the user’s own structure.
a width: full or half, how wide its card is on the brand page.
a version: it increments on every body change. Send it back as expectedVersion to write safely.

Reading a kit

GET /brand-kits/{brandKitId} answers one of three ways:

Query	Returns
`detail=summary`	Every section with its key, role, version, length (`charCount`) and outline (its own headings), and no bodies. The cheap first read.
any of `keys`, `roles`, `tabs` (comma-separated, combined with AND)	Just those sections, with bodies. Add `history=true` for each section’s earlier versions, newest first.
nothing	The whole kit: every section, visual identity, linked accounts and a knowledge preview.

detail=summary with a filter, history without one, and any unknown role or tab are refused with a 400 naming the valid values.

Writing sections

Send sections in the PATCH body, naming only the sections you change. An entry with a key edits that section:

body replaces its whole content;
revertTo restores an earlier version (it lands as a new version, so a revert can itself be reverted);
sectionName renames it; width sets full or half.

An entry without a key adds a section of your own, and needs sectionName and tab. To remove a section, archive it through POST /archive with assetType: "brand_kit_section". The write is all or nothing, and it lands before anything else in the patch. If any section has changed since the expectedVersion you sent, nothing is written and the response is a 409:

{
  "error": "1 section(s) changed since the version you read; nothing was written",
  "conflicts": [{ "key": "voice_and_tone", "version": 4, "body": "## Personality\n\nThe current text." }]
}

Re-read, reapply your change to the current body, and send the new version.

Removed inputs. businessName, primaryOffer, nicheDefinition, positioning, audience, voiceProfile, contentStrategy, visualStyle, designPrinciples and fields are no longer accepted or returned, and GET /brand-kit-templates is gone. Sending a removed input is a 400 that names the replacement: write the matching section with sections, using the keys from a detail=summary read. Visual style and design principles belong in the design_guidelines section.

Knowledge base

Method	Path	Scope	Purpose
`GET`	`/brand-kits/{brandKitId}/knowledge`	`brand:read`	List the knowledge index (titles and metadata).
`POST`	`/brand-kits/{brandKitId}/knowledge`	`brand:write`	Add an item. Source is `text`, `url`, `youtube`, or a file via `fileData` (base64) or `fileUrl` (hosted).
`GET`	`/brand-kits/{brandKitId}/knowledge/{knowledgeId}`	`brand:read`	Get one item’s stored body.
`DELETE`	`/brand-kits/{brandKitId}/knowledge/{knowledgeId}`	`brand:write`	Remove an item and its embeddings.
`GET`	`/brand-kits/{brandKitId}/knowledge/search?q=`	`brand:read`	Semantic search, ranked by similarity.

Large files and video or audio must be added by a hosted URL (fileUrl), which the server fetches and chunks. Base64 (fileData) is for small documents and images. Adding is plan-limited; a limitReached response means the brand kit is at its cap.

See the Brand guide for the structure and the knowledge workflow.

​Brand kit

​Sections

​Reading a kit

​Writing sections

​Knowledge base

Brand kit

Sections

Reading a kit

Writing sections

Knowledge base