Brand kits
Give this prompt to your AI agent. The agent does the task for you.
Read https://thirds.ai/docs/api-reference/brand-kits and help me choose the right thirds.ai endpoint and write a request. Check the fields and credentials in this reference.
Manage brand colours, logos, and fonts, then apply the same brand kit when you create a template or image.
See all API resources or read API keys and requests.
Endpoints
createBrandKit
POST /v1/brand-kits
Create a brand kit
Create one mutable account-owned brand kit. Logos and fonts are uploaded through the kit's asset route after creation. The account plan sets how many kits the account can keep: 1 on Free, a pack-only account, and Starter, 5 on Growth, and 20 on Scale. Every kit of the account counts, archived kits too. A kit over that limit answers 409 brand_kit_limit with error.plan_limit. An account above its limit after a downgrade keeps every kit and can still change and archive them.
Authentication: bearer API key. See authentication.
Request body: application/json, BrandKitWrite.
| Status | Meaning | Body |
|---|---|---|
| 201 | The brand kit was created. | application/json: BrandKitDetail |
| 400 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 401 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 403 | The authenticated account is suspended. The code is account_suspended. | application/json: ErrorEnvelope |
| 405 | The method is not allowed on this route. | application/json: ErrorEnvelope |
| 409 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 413 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 415 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 422 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 431 | The request has more than 64 headers or more than 32 KiB of header names and values. | application/json: ErrorEnvelope |
listBrandKits
GET /v1/brand-kits
List brand kits
List the account's active and archived brand kits newest first. Asset metadata is omitted from the page; read one kit for its current assets.
Authentication: bearer API key. See authentication.
| Parameter | Location | Required | Rule |
|---|---|---|---|
status | query | No | {"type":"string","enum":["active","archived","all"],"default":"all"} |
limit | query | No | {"type":"integer","default":20} |
cursor | query | No | {"type":"string","maxLength":128} |
| Status | Meaning | Body |
|---|---|---|
| 200 | One page of brand-kit summaries. | application/json: BrandKitPage |
| 400 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 401 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 403 | The authenticated account is suspended. The code is account_suspended. | application/json: ErrorEnvelope |
| 405 | The method is not allowed on this route. | application/json: ErrorEnvelope |
| 431 | The request has more than 64 headers or more than 32 KiB of header names and values. | application/json: ErrorEnvelope |
getBrandKit
GET /v1/brand-kits/{brand_kit_id}
Get a brand kit
Return one owned kit and its current logo and font metadata. Replaced assets remain private durable content but are omitted.
Authentication: bearer API key. See authentication.
| Parameter | Location | Required | Rule |
|---|---|---|---|
brand_kit_id | path | Yes | BrandKitId |
| Status | Meaning | Body |
|---|---|---|
| 200 | The brand kit and its current assets. | application/json: BrandKitDetail |
| 401 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 403 | The authenticated account is suspended. The code is account_suspended. | application/json: ErrorEnvelope |
| 404 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 405 | The method is not allowed on this route. | application/json: ErrorEnvelope |
| 431 | The request has more than 64 headers or more than 32 KiB of header names and values. | application/json: ErrorEnvelope |
updateBrandKit
PATCH /v1/brand-kits/{brand_kit_id}
Update a brand kit
Replace any supplied mutable brand values. Omitted fields stay unchanged; a null tone_guidance clears it. Archived kits cannot change.
Authentication: bearer API key. See authentication.
| Parameter | Location | Required | Rule |
|---|---|---|---|
brand_kit_id | path | Yes | BrandKitId |
Request body: application/json, BrandKitPatch.
| Status | Meaning | Body |
|---|---|---|
| 200 | The updated kit and its current assets. | application/json: BrandKitDetail |
| 400 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 401 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 403 | The authenticated account is suspended. The code is account_suspended. | application/json: ErrorEnvelope |
| 404 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 405 | The method is not allowed on this route. | application/json: ErrorEnvelope |
| 413 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 415 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 422 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 431 | The request has more than 64 headers or more than 32 KiB of header names and values. | application/json: ErrorEnvelope |
archiveBrandKit
DELETE /v1/brand-kits/{brand_kit_id}
Archive a brand kit
Archive one owned kit. The operation is idempotent. The kit and every current or replaced asset stay durable for already captured references.
Authentication: bearer API key. See authentication.
| Parameter | Location | Required | Rule |
|---|---|---|---|
brand_kit_id | path | Yes | BrandKitId |
| Status | Meaning | Body |
|---|---|---|
| 204 | The brand kit is archived. | No body |
| 401 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 403 | The authenticated account is suspended. The code is account_suspended. | application/json: ErrorEnvelope |
| 404 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 405 | The method is not allowed on this route. | application/json: ErrorEnvelope |
| 431 | The request has more than 64 headers or more than 32 KiB of header names and values. | application/json: ErrorEnvelope |
createBrandAsset
POST /v1/brand-kits/{brand_kit_id}/assets
Add a brand asset
Add one logo or WOFF2 font to an active owned kit. The declared Content-Type and the complete bytes must agree. No customer bytes or storage reference appears in the response.
Authentication: bearer API key. See authentication.
| Parameter | Location | Required | Rule |
|---|---|---|---|
brand_kit_id | path | Yes | BrandKitId |
Request body: image/png, {"type":"string","format":"binary"}.
Request body: image/jpeg, {"type":"string","format":"binary"}.
Request body: image/webp, {"type":"string","format":"binary"}.
Request body: font/woff2, {"type":"string","format":"binary"}.
| Status | Meaning | Body |
|---|---|---|
| 201 | The immutable asset was accepted and selected by the kit. | application/json: BrandAsset |
| 400 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 401 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 403 | The authenticated account is suspended. The code is account_suspended. | application/json: ErrorEnvelope |
| 404 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 405 | The method is not allowed on this route. | application/json: ErrorEnvelope |
| 413 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 415 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 422 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 429 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 431 | The request has more than 64 headers or more than 32 KiB of header names and values. | application/json: ErrorEnvelope |
| 503 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
readBrandAsset
GET /v1/brand-kits/{brand_kit_id}/assets/{asset_id}
Read a brand asset
Read the validated logo or font bytes from an owned kit. Captured assets remain readable after replacement or archive. Responses are private and must not be cached.
Authentication: bearer API key. See authentication.
| Parameter | Location | Required | Rule |
|---|---|---|---|
brand_kit_id | path | Yes | BrandKitId |
asset_id | path | Yes | BrandAssetId |
| Status | Meaning | Body |
|---|---|---|
| 200 | The validated image or WOFF2 font bytes. | image/png: {"type":"string","format":"binary"}; image/jpeg: {"type":"string","format":"binary"}; image/webp: {"type":"string","format":"binary"}; font/woff2: {"type":"string","format":"binary"} |
| 401 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 403 | The authenticated account is suspended. The code is account_suspended. | application/json: ErrorEnvelope |
| 404 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 405 | The method is not allowed on this route. | application/json: ErrorEnvelope |
| 431 | The request has more than 64 headers or more than 32 KiB of header names and values. | application/json: ErrorEnvelope |
replaceBrandAsset
PUT /v1/brand-kits/{brand_kit_id}/assets/{asset_id}
Replace a brand asset
Create a new immutable asset of the same kind and make it current. The old asset and bytes stay unchanged for any template or queued operation that already captured its ID.
Authentication: bearer API key. See authentication.
| Parameter | Location | Required | Rule |
|---|---|---|---|
brand_kit_id | path | Yes | BrandKitId |
asset_id | path | Yes | BrandAssetId |
Request body: image/png, {"type":"string","format":"binary"}.
Request body: image/jpeg, {"type":"string","format":"binary"}.
Request body: image/webp, {"type":"string","format":"binary"}.
Request body: font/woff2, {"type":"string","format":"binary"}.
| Status | Meaning | Body |
|---|---|---|
| 201 | The new immutable current asset. | application/json: BrandAsset |
| 400 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 401 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 403 | The authenticated account is suspended. The code is account_suspended. | application/json: ErrorEnvelope |
| 404 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 405 | The method is not allowed on this route. | application/json: ErrorEnvelope |
| 413 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 415 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 422 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 429 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 431 | The request has more than 64 headers or more than 32 KiB of header names and values. | application/json: ErrorEnvelope |
| 503 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
Schemas
BrandAssetId
Schema rules: {"type":"string","pattern":"^asset_[0-9a-f]{32}$"}.
BrandKitWrite
| Field | Required | Description and type |
|---|---|---|
name | Yes | {"type":"string","minLength":1,"maxLength":100} |
colours | No | {"type":"array","maxItems":16,"uniqueItems":true,"items":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"default":[]} |
tone_guidance | No | {"type":["string","null"],"minLength":1,"maxLength":500} |
Schema rules: {"type":"object","additionalProperties":false}.
BrandKitPatch
| Field | Required | Description and type |
|---|---|---|
archived_at | No | Restore the item. Omit this field to keep its archive state. {"type":"null"} |
name | No | {"type":"string","minLength":1,"maxLength":100} |
colours | No | {"type":"array","maxItems":16,"uniqueItems":true,"items":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"}} |
tone_guidance | No | {"type":["string","null"],"minLength":1,"maxLength":500} |
Schema rules: {"type":"object","minProperties":1,"additionalProperties":false}.
BrandKitSummary
| Field | Required | Description and type |
|---|---|---|
id | Yes | BrandKitId |
name | Yes | {"type":"string","minLength":1,"maxLength":100} |
colours | Yes | {"type":"array","maxItems":16,"uniqueItems":true,"items":{"type":"string","pattern":"^#[0-9a-f]{6}$"}} |
tone_guidance | Yes | {"type":["string","null"],"minLength":1,"maxLength":500} |
created_at | Yes | {"type":"string","format":"date-time"} |
updated_at | Yes | {"type":"string","format":"date-time"} |
archived_at | Yes | {"type":["string","null"],"format":"date-time"} |
assets | Yes | {"type":"array","maxItems":16,"items":{"$ref":"#/components/schemas/BrandAsset"}} — BrandAsset |
Schema rules: {"type":"object","additionalProperties":false}.
BrandAsset
| Field | Required | Description and type |
|---|---|---|
id | Yes | BrandAssetId |
kind | Yes | {"type":"string","enum":["logo","font"]} |
media_type | Yes | {"type":"string","enum":["image/png","image/jpeg","image/webp","font/woff2"]} |
byte_size | Yes | {"type":"integer","minimum":1,"maximum":10485760} |
created_at | Yes | {"type":"string","format":"date-time"} |
Schema rules: {"type":"object","additionalProperties":false}.
BrandKitDetail
| Field | Required | Description and type |
|---|---|---|
archive_history | Yes | {"type":"array","items":{"$ref":"#/components/schemas/ArchivePeriod"}} — ArchivePeriod |
id | Yes | BrandKitId |
name | Yes | {"type":"string","minLength":1,"maxLength":100} |
colours | Yes | {"type":"array","maxItems":16,"uniqueItems":true,"items":{"type":"string","pattern":"^#[0-9a-f]{6}$"}} |
tone_guidance | Yes | {"type":["string","null"],"minLength":1,"maxLength":500} |
created_at | Yes | {"type":"string","format":"date-time"} |
updated_at | Yes | {"type":"string","format":"date-time"} |
archived_at | Yes | {"type":["string","null"],"format":"date-time"} |
assets | Yes | {"type":"array","maxItems":16,"items":{"$ref":"#/components/schemas/BrandAsset"}} — BrandAsset |
Schema rules: {"type":"object","additionalProperties":false}.
BrandKitPage
| Field | Required | Description and type |
|---|---|---|
items | Yes | {"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/BrandKitSummary"}} — BrandKitSummary |
next_cursor | Yes | {"type":["string","null"],"maxLength":128} |
Schema rules: {"type":"object","additionalProperties":false}.
Shared errors, headers, and authentication schemes are in shared types and security.