Set up a brand kit and teach it your look

A brand kit holds your brand's name, colours, fonts, voice and logo. Every design Nimply makes uses one. A kit can also learn your look from your own designs: the layouts, type, colour use and photo style you use. After that, every new design for that kit follows it.

Scopes: designs:read for reads, designs:write for changes. Plans and credits: creating and editing kits is free (your plan sets how many kits you can have). Learning a look and reading a brand from a website or several sources use AI credits, on paid plans and during a trial.

Endpoints

1. Create the kit

Every workspace already has a main kit (isMain: true in GET /v1/brand-kits). Change it with PATCH, or create another kit for a second brand:

curl -X POST https://api.nimply.io/v1/brand-kits \
  -H "Authorization: Bearer $NIMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Brewhaus",
    "colors": ["#F0530F", "#1B1815", "#FFF7EE"],
    "fonts": { "heading": { "family": "Anton" }, "body": { "family": "Inter", "weight": 400 } },
    "voice": "Warm, plain-spoken and a little playful."
  }'

• colors are hex codes, most important first: the first is your main colour.
• Fonts are Google Fonts families or fonts uploaded in Nimply.
• For a logo, import the image with POST /v1/media and pass its id as logoMediaId.
• On PATCH, only the fields you send change. colors and fonts replace the whole list; null clears a field.

Fill it from your website. POST /v1/brand-kits/import with { "website": "brewhaus.coffee" } reads the site and suggests a name, colours, fonts and logos. It saves nothing: send what you want to keep to POST or PATCH. It uses your connected Brandfetch account when you have one (no credits), otherwise AI (a few credits; creditsCharged says how many).

Create a kit from several sources

Read your brand from up to 6 sources at once and get one draft kit to review. Each value in the draft says which source it came from, and where two sources disagree you choose.

Upload files first. PDFs and images are passed as media ids. Upload a local file with POST /v1/media/uploads (contentType: "application/pdf" for a PDF), PUT the bytes, then complete it; or import a public link with POST /v1/media.

1. Check the cost (optional, free)

POST /v1/brand-kits/imports/estimate with the same body as below returns creditsMax per source and in total, plus creditsAvailable. An import usually uses about 20–80 credits.

2. Start reading

curl -X POST https://api.nimply.io/v1/brand-kits/imports \
  -H "Authorization: Bearer $NIMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": [
      { "kind": "website", "website": "brewhaus.coffee" },
      { "kind": "pdf", "mediaId": "…" },
      { "kind": "text", "text": "Brewhaus is a neighbourhood coffee roaster. Primary colour #5F8EFD. Never use script fonts." },
      { "kind": "channel", "channelId": "…" }
    ]
  }'

It returns 202 with the import id, status: "queued", one entry per source in sources, and the estimate. Nimply holds up to estimate.creditsMax credits and charges only what it really uses. A source that can't be used is a 400 with sourceIndex (0-based) saying which.

3. Poll until ready

Reading takes about a minute. Read GET /v1/brand-kits/imports/{id} every 10–20 seconds until status is ready (or failed: nothing could be read, no credits used). Each source shows waiting, reading, done or failed with an error; one failed source doesn't stop the others.

When ready, draft holds the kit: name, colors (with roles, primary first), fonts, logos, voice, voiceSamples, guidelines, doNots, examples (with examplesCount), fontUploads (fonts that are not Google Fonts: upload them in Nimply) and warnings. Every value has sources: the source's index, kind, label and, where known, a detail (for example p.3).

4. Review disagreements

draft.colorConflicts lists each colour role where two sources state different colours, for example the PDF says #5F8EFD and the website #515DEF. The first option is the default (a brand book or your text beats the website, which beats colours measured on posts). name, voice and each font also have options when sources differ.

5. Save

curl -X POST https://api.nimply.io/v1/brand-kits/imports/$IMPORT_ID/save \
  -H "Authorization: Bearer $NIMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "picks": { "colors": { "primary": "#515DEF" } }, "logo": 0, "learn": true }'

• picks: your choices for name, colors (per role), fonts (per role, a family) and voice. Leave them out to keep the defaults.
• logo: which of draft.logos to use, by position (default 0; -1 for none).
• learn: true also starts learning the look from the examples found (at least 3; uses AI credits).

It returns brandKitId, how many examples were added, learningStarted, creditsReserved for learning, and notes about anything that didn't apply. Your don'ts become rules of the new kit. A ready draft is kept for 7 days.

Add a brand book to a kit you already have

Pass brandKitId when you start, with the new sources (usually one pdf):

curl -X POST https://api.nimply.io/v1/brand-kits/imports \
  -H "Authorization: Bearer $NIMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "brandKitId": "…", "sources": [{ "kind": "pdf", "mediaId": "…" }] }'

The import has targetBrandKitId, and once ready a target that compares the draft with the kit. It lists only what differs: colors (with the added colours the kit doesn't have), fonts per role, voice and guidelines, each with the kit's value (kit) and the one found (found). target.brandBooks lists the kit's current brand book PDFs.

Save works as above but updates the kit. The kit's own values win by default; empty fields are filled (target.defaults shows what save will do). To choose, send apply:

curl -X POST https://api.nimply.io/v1/brand-kits/imports/$IMPORT_ID/save \
  -H "Authorization: Bearer $NIMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "apply": { "colors": "add", "fonts": { "heading": "found" } }, "replaceBrandBook": true, "learn": true }'

• apply.colors: kit (keep), found (use the colours found) or add (keep the kit's and add the new ones). apply.guidelines takes the same values; apply.voice and each apply.fonts role take kit or found.
• The kit keeps its logo unless you send logo. The don'ts found are added to its rules and the brand book's pages are added as examples.
• replaceBrandBook: true replaces the kit's current brand book: its pages leave the learned look and its files leave the kit's Brand assets folder (you can delete them then). Learn the look again (learn: true) so it reflects the new book.

The result also has updated: true, the kit fields that changed and replacedBrandBooks.

2. Add examples

The look is learned from your own designs: at least 3, up to 50. Between 8 and 20 varied examples work best. Two kinds of example:

• Images from your media library: mediaIds.
• Published posts with an image: postIds. List them with GET /v1/brand-kits/{id}/style/post-candidates (24 per page, cursor for more, optional channelId).

curl -X POST https://api.nimply.io/v1/brand-kits/$KIT_ID/style/examples \
  -H "Authorization: Bearer $NIMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "postIds": ["…", "…"], "mediaIds": ["…"] }'

Adding examples is free; duplicates are skipped. The response is the kit's style (below).

3. Learn the look

First check the cost: GET /v1/brand-kits/{id}/style returns learnEstimate.creditsMax (the most it can use) and creditsAvailable. Then start learning:

curl -X POST https://api.nimply.io/v1/brand-kits/$KIT_ID/style/learn \
  -H "Authorization: Bearer $NIMPLY_API_KEY"

It returns 202 with status: "learning" and creditsReserved. Nimply holds that many credits and charges only what it really uses. Learning takes a few minutes: read GET /v1/brand-kits/{id}/style about once a minute until status is ready or failed.

When it is ready, the style has a plain-words summary, a palette, fonts, doNots, recipes (the kinds of posts you make) and learned rules. New designs for this kit follow it automatically (see Learned brand look).

Learning again later learns only the new examples. Pass { "relearnAll": true } to learn everything again.

4. Add your own rules

Rules are short instructions every design for the kit follows, yours first. Send your whole list to PUT /v1/brand-kits/{id}/style/rules:

{
  "rules": [
    { "text": "Never use script fonts." },
    { "text": "Leave space for the logo in the top right." },
    { "id": "learned:2", "text": "Headlines in all caps.", "enabled": false }
  ]
}

• A rule without an id is new. Your rules left out of the list are deleted.
• Learned rules have ids learned:<n>. Switch one off with enabled: false, or change its text to save your own version. A learned rule you leave out keeps its state.
• Your rules stay when the look is learned again.

Errors

From ChatGPT, Claude and other assistants

The MCP server has a tool for each step: create_brand_kit, import_brand_from_website, import_brand_from_sources, get_brand_import, save_brand_import, get_brand_kit, update_brand_kit, list_style_post_candidates, add_style_examples, remove_style_example, learn_brand_style, get_brand_style and set_brand_style_rules. Ask things like:

• "Set up a brand kit for brewhaus.coffee."
• "Make a brand kit from our website, this brand book PDF and our Instagram."
• "Learn our look from our 10 best Instagram posts."
• "Add a rule: never use script fonts."

The assistant tells you the credit cost before it starts learning, and checks back until the look is ready. Connections made before these tools existed need to be reconnected to see them.