{"openapi":"3.1.0","info":{"title":"Brandbase","version":"0.1.0","description":"Brand context for any agent. Read a brand's guidelines, prompts, skills, logos, colors, fonts, images and video, and keep them up to date."},"servers":[{"url":"https://api.brandbase.run"}],"security":[{"bearer":[]}],"tags":[{"name":"brands","description":"A brand and its context."},{"name":"assets","description":"What a brand is made of."}],"paths":{"/brands":{"get":{"operationId":"listBrands","summary":"List Brands","description":"The brands this workspace holds, most recently changed first, each with its slug and how many assets of each kind it has. Start here when you do not know a brand's slug.","tags":["brands"],"parameters":[{"name":"query","in":"query","required":false,"description":"Filter by name, slug or client.","schema":{"type":"string","maxLength":120}},{"name":"page","in":"query","required":false,"description":"Page number, from 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Results per page, up to 100.","schema":{"default":25,"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"The result, in `data`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Data"}}}},"default":{"description":"An error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createBrand","summary":"Create Brand","description":"Add a brand to the workspace. Write a description: it is the first thing every agent reads.","tags":["brands"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80,"description":"The brand's name as people say it, e.g. \"Moraleja Design\"."},"slug":{"description":"URL-safe handle, lowercase with hyphens. Derived from the name when omitted.","type":"string","maxLength":60,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"client":{"description":"The client the brand belongs to, when a studio manages several. Free text.","anyOf":[{"type":"string","maxLength":80},{"type":"null"}]},"description":{"description":"What the brand is and who it speaks to, in a paragraph. Every agent reads this first.","anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"website":{"description":"The brand's public site.","anyOf":[{"type":"string","maxLength":300,"format":"uri"},{"type":"null"}]},"metadata":{"description":"Free-form facts about the brand as a JSON object, e.g. industry, markets, launch year.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["name"],"additionalProperties":false}}}},"responses":{"200":{"description":"The result, in `data`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Data"}}}},"default":{"description":"An error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/brands/{brand}":{"get":{"operationId":"getBrand","summary":"Get Brand","description":"One brand's profile and asset counts. For the guidance itself call get_brand_context.","tags":["brands"],"parameters":[{"name":"brand","in":"path","required":true,"description":"The brand, by id (brd_…) or slug, e.g. \"moraleja\".","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"The result, in `data`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Data"}}}},"default":{"description":"An error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateBrand","summary":"Update Brand","description":"Change a brand's profile. Only the fields you send change.","tags":["brands"],"parameters":[{"name":"brand","in":"path","required":true,"description":"The brand, by id (brd_…) or slug, e.g. \"moraleja\".","schema":{"type":"string","minLength":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80,"description":"The brand's name as people say it, e.g. \"Moraleja Design\"."},"slug":{"description":"URL-safe handle, lowercase with hyphens. Derived from the name when omitted.","type":"string","maxLength":60,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"client":{"description":"The client the brand belongs to, when a studio manages several. Free text.","anyOf":[{"type":"string","maxLength":80},{"type":"null"}]},"description":{"description":"What the brand is and who it speaks to, in a paragraph. Every agent reads this first.","anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"website":{"description":"The brand's public site.","anyOf":[{"type":"string","maxLength":300,"format":"uri"},{"type":"null"}]},"metadata":{"description":"Free-form facts about the brand as a JSON object, e.g. industry, markets, launch year.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"The result, in `data`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Data"}}}},"default":{"description":"An error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteBrand","summary":"Delete Brand","description":"Remove a brand and every asset in it. Confirm with the user first.","tags":["brands"],"parameters":[{"name":"brand","in":"path","required":true,"description":"The brand, by id (brd_…) or slug, e.g. \"moraleja\".","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"The result, in `data`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Data"}}}},"default":{"description":"An error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/brands/{brand}/context":{"get":{"operationId":"getBrandContext","summary":"Get Brand Context","description":"Everything to read before working on a brand: its profile, the full text of its guidelines and color palettes, and an index of its prompts, skills, logos, fonts, images, video and templates with their rules and URLs. Pass task to keep only what applies to the work at hand. Call this first, once per brand per conversation.","tags":["brands"],"parameters":[{"name":"brand","in":"path","required":true,"description":"The brand, by id (brd_…) or slug, e.g. \"moraleja\". list_brands returns both.","schema":{"type":"string","minLength":1}},{"name":"task","in":"query","required":false,"description":"What you are about to make, so only the guidance that applies is returned. Suggested: design, image, video, motion, copy, web, social, print, audio, code.","schema":{"type":"string","minLength":1,"maxLength":48}},{"name":"max_chars","in":"query","required":false,"description":"Cap on the total guideline text returned. Guidelines past the cap are listed without their body.","schema":{"type":"integer","minimum":1000,"maximum":400000}}],"responses":{"200":{"description":"The result, in `data`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Data"}}}},"default":{"description":"An error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/assets":{"get":{"operationId":"searchAssets","summary":"Search Assets","description":"Find assets in one brand or across all of them. query matches names, paths, tags, descriptions, rules, metadata and the body of text assets, ignoring case and accents; filters narrow by kind, tags, applies_to, format, metadata and status. Results carry metadata, rules and URLs but not text bodies: read those with get_asset. match says how the results were found: \"exact\" when every word matched, \"partial\" when only some did (best first), \"fuzzy\" when only close spellings did.","tags":["assets"],"parameters":[{"name":"brand","in":"query","required":false,"description":"The brand, by id (brd_…) or slug, e.g. \"moraleja\". list_brands returns both. Omit to search every brand.","schema":{"type":"string","minLength":1}},{"name":"query","in":"query","required":false,"description":"Free text matched against name, path, tags, description, rules, metadata and the body of text assets. Accent and case insensitive; every word must match, a word may be a prefix.","schema":{"type":"string","maxLength":240}},{"name":"kind","in":"query","required":false,"description":"Only these kinds.","schema":{"type":"array","items":{"type":"string","enum":["guideline","prompt","skill","logo","palette","font","image","video","audio","template","document","file"]}}},{"name":"tags","in":"query","required":false,"description":"Only assets carrying every one of these tags.","schema":{"maxItems":32,"type":"array","items":{"type":"string","minLength":1,"maxLength":48}}},{"name":"applies_to","in":"query","required":false,"description":"Only assets that apply to any of these kinds of work.","schema":{"maxItems":32,"type":"array","items":{"type":"string","minLength":1,"maxLength":48}}},{"name":"format","in":"query","required":false,"description":"Only these file formats, e.g. [\"svg\", \"png\"].","schema":{"type":"array","items":{"type":"string"}}},{"name":"metadata","in":"query","required":false,"description":"Match assets whose metadata contains this object, e.g. {\"background\": \"dark\"}.","schema":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},{"name":"status","in":"query","required":false,"description":"Defaults to \"active\".","schema":{"type":"string","enum":["active","draft","archived"]}},{"name":"sort","in":"query","required":false,"description":"\"relevance\" (default with a query), \"updated\", \"name\" or \"path\".","schema":{"type":"string","enum":["relevance","updated","name","path"]}},{"name":"page","in":"query","required":false,"description":"Page number, from 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Results per page, up to 100.","schema":{"default":25,"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"The result, in `data`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Data"}}}},"default":{"description":"An error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createAsset","summary":"Create Asset","description":"Add an asset to a brand. Send exactly one body: content for text you can write out (markdown, SVG, HTML, JSON), source_url for a file already online, content_base64 for a small file, or upload_id after request_upload for a local file. Fill description, tags, applies_to and metadata so the asset can be found, and rules when its use is restricted.","tags":["assets"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brand":{"type":"string","minLength":1,"description":"The brand, by id (brd_…) or slug, e.g. \"moraleja\". list_brands returns both."},"kind":{"type":"string","enum":["guideline","prompt","skill","logo","palette","font","image","video","audio","template","document","file"],"description":"What the asset is. One of:\nguideline: A written brand rulebook an agent must follow: design.md, image.md, video.md, voice.md, brand.md. Markdown.\nprompt: A reusable prompt that produces on-brand output with a generative model.\nskill: An agent skill (SKILL.md or a packaged folder) that teaches a workflow for this brand.\nlogo: A logo file: primary, mark, wordmark or lockup, per background. SVG preferred.\npalette: Color tokens. The colors live in metadata.colors; the body may carry them as JSON or CSS.\nfont: A typeface file with its family, weight and role.\nimage: Photography, illustration, texture, icon or any reference picture.\nvideo: A video or motion reference: brand film, intro, bumper, animation.\naudio: A sonic logo, music bed or voice reference.\ntemplate: A ready-to-fill layout: HTML, CSS, an email signature, a slide, a social card.\ndocument: A brand book, deck or any reference document: PDF, Word, Keynote, a zip.\nfile: Anything else worth keeping with the brand."},"name":{"type":"string","minLength":1,"maxLength":160,"description":"A human title, e.g. \"Primary logo, dark background\"."},"path":{"type":"string","minLength":1,"maxLength":240,"description":"Where it lives inside the brand, like a file path: \"guidelines/design.md\", \"logos/primary-dark.svg\". Unique per brand. Derived from kind and name when omitted."},"description":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"description":"What the asset is and what it shows. Written for search: say what someone would type to find it."},"rules":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}],"description":"How it must be used: when to pick it, clear space, minimum size, do and don't. Agents read this before using the asset."},"tags":{"maxItems":32,"type":"array","items":{"type":"string","minLength":1,"maxLength":48},"description":"Lowercase labels for search and grouping."},"applies_to":{"maxItems":32,"type":"array","items":{"type":"string","minLength":1,"maxLength":48},"description":"Which kinds of work it governs or serves. Suggested: design, image, video, motion, copy, web, social, print, audio, code. Empty means every kind."},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Structured facts as a JSON object. Each kind suggests fields (logo: variant, background, color; palette: colors; font: family, weight, role; prompt: target, model, variables). Any other key is kept and searchable."},"status":{"type":"string","enum":["active","draft","archived"],"description":"\"active\" (default) is live brand truth; \"draft\" is work in progress; \"archived\" is kept but no longer in use."},"content":{"type":"string","description":"The body as text: markdown, SVG, HTML, JSON, CSS. Use for anything you can write out."},"source_url":{"type":"string","format":"uri","description":"A public URL to copy the file from. Use for images, video, fonts and documents already online."},"content_base64":{"type":"string","description":"The file's bytes, base64. Only for small files; for anything larger call request_upload."},"content_type":{"type":"string","maxLength":120,"description":"The media type, when the path's extension does not say it."},"upload_id":{"type":"string","description":"The upload_id from request_upload, after the file was sent to its upload_url."}},"required":["brand","kind","name"],"additionalProperties":false}}}},"responses":{"200":{"description":"The result, in `data`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Data"}}}},"default":{"description":"An error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/assets/{asset}":{"get":{"operationId":"getAsset","summary":"Get Asset","description":"One asset in full: metadata, rules, and its body. Text assets (markdown, SVG, HTML, JSON) come back in content; files come back as url, with preview_url for a small rendition. Address it by asset id, or by brand and path. Pass version to read an earlier revision.","tags":["assets"],"parameters":[{"name":"asset","in":"path","required":true,"description":"The asset id (ast_…).","schema":{"type":"string","minLength":1}},{"name":"brand","in":"query","required":false,"description":"The brand, by id (brd_…) or slug, e.g. \"moraleja\". list_brands returns both. With path, instead of asset.","schema":{"type":"string","minLength":1}},{"name":"path","in":"query","required":false,"description":"The asset's path inside the brand, e.g. \"guidelines/design.md\".","schema":{"type":"string","minLength":1}},{"name":"version","in":"query","required":false,"description":"An earlier version to read instead of the current one.","schema":{"type":"integer","minimum":1,"maximum":9007199254740991}}],"responses":{"200":{"description":"The result, in `data`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Data"}}}},"default":{"description":"An error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateAsset","summary":"Update Asset","description":"Change an asset's details, its body, or both. Only the fields you send change; tags, applies_to and metadata are replaced whole. Every update is a new version. Pass expected_version from your last read so a concurrent change is not overwritten.","tags":["assets"],"parameters":[{"name":"asset","in":"path","required":true,"description":"The asset id (ast_…).","schema":{"type":"string","minLength":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":160,"description":"A human title, e.g. \"Primary logo, dark background\"."},"path":{"type":"string","minLength":1,"maxLength":240,"description":"Where it lives inside the brand, like a file path: \"guidelines/design.md\", \"logos/primary-dark.svg\". Unique per brand. Derived from kind and name when omitted."},"kind":{"description":"What the asset is. One of:\nguideline: A written brand rulebook an agent must follow: design.md, image.md, video.md, voice.md, brand.md. Markdown.\nprompt: A reusable prompt that produces on-brand output with a generative model.\nskill: An agent skill (SKILL.md or a packaged folder) that teaches a workflow for this brand.\nlogo: A logo file: primary, mark, wordmark or lockup, per background. SVG preferred.\npalette: Color tokens. The colors live in metadata.colors; the body may carry them as JSON or CSS.\nfont: A typeface file with its family, weight and role.\nimage: Photography, illustration, texture, icon or any reference picture.\nvideo: A video or motion reference: brand film, intro, bumper, animation.\naudio: A sonic logo, music bed or voice reference.\ntemplate: A ready-to-fill layout: HTML, CSS, an email signature, a slide, a social card.\ndocument: A brand book, deck or any reference document: PDF, Word, Keynote, a zip.\nfile: Anything else worth keeping with the brand.","type":"string","enum":["guideline","prompt","skill","logo","palette","font","image","video","audio","template","document","file"]},"description":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"description":"What the asset is and what it shows. Written for search: say what someone would type to find it."},"rules":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}],"description":"How it must be used: when to pick it, clear space, minimum size, do and don't. Agents read this before using the asset."},"tags":{"maxItems":32,"type":"array","items":{"type":"string","minLength":1,"maxLength":48},"description":"Lowercase labels for search and grouping."},"applies_to":{"maxItems":32,"type":"array","items":{"type":"string","minLength":1,"maxLength":48},"description":"Which kinds of work it governs or serves. Suggested: design, image, video, motion, copy, web, social, print, audio, code. Empty means every kind."},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Structured facts as a JSON object. Each kind suggests fields (logo: variant, background, color; palette: colors; font: family, weight, role; prompt: target, model, variables). Any other key is kept and searchable."},"status":{"type":"string","enum":["active","draft","archived"],"description":"\"active\" (default) is live brand truth; \"draft\" is work in progress; \"archived\" is kept but no longer in use."},"content":{"type":"string","description":"The body as text: markdown, SVG, HTML, JSON, CSS. Use for anything you can write out."},"source_url":{"type":"string","format":"uri","description":"A public URL to copy the file from. Use for images, video, fonts and documents already online."},"content_base64":{"type":"string","description":"The file's bytes, base64. Only for small files; for anything larger call request_upload."},"content_type":{"type":"string","maxLength":120,"description":"The media type, when the path's extension does not say it."},"upload_id":{"type":"string","description":"The upload_id from request_upload, after the file was sent to its upload_url."},"expected_version":{"description":"The version you read. The update is refused if the asset changed since, so two writers never overwrite each other.","type":"integer","minimum":1,"maximum":9007199254740991},"note":{"description":"One line on what changed and why, kept in the revision history.","type":"string","maxLength":240}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"The result, in `data`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Data"}}}},"default":{"description":"An error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteAsset","summary":"Delete Asset","description":"Remove an asset from its brand. Confirm with the user first.","tags":["assets"],"parameters":[{"name":"asset","in":"path","required":true,"description":"The asset id (ast_…).","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"The result, in `data`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Data"}}}},"default":{"description":"An error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/assets/{asset}/versions":{"get":{"operationId":"listAssetVersions","summary":"List Asset Versions","description":"The revision history of an asset, newest first: who changed it, when, and the note they left.","tags":["assets"],"parameters":[{"name":"asset","in":"path","required":true,"description":"The asset id (ast_…).","schema":{"type":"string","minLength":1}},{"name":"page","in":"query","required":false,"description":"Page number, from 1.","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"per_page","in":"query","required":false,"description":"Results per page, up to 100.","schema":{"default":25,"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"The result, in `data`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Data"}}}},"default":{"description":"An error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/assets/{asset}/restore":{"post":{"operationId":"restoreAsset","summary":"Restore Asset Version","description":"Bring an earlier version of an asset back as the newest one. Nothing is lost: the restore is itself a new version.","tags":["assets"],"parameters":[{"name":"asset","in":"path","required":true,"description":"The asset id (ast_…).","schema":{"type":"string","minLength":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"The version to bring back."}},"required":["version"],"additionalProperties":false}}}},"responses":{"200":{"description":"The result, in `data`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Data"}}}},"default":{"description":"An error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/uploads":{"post":{"operationId":"requestUpload","summary":"Request Upload","description":"Open an upload for a local file. Returns an upload_url, the form fields to send with it and a ready curl command; POST the file as multipart form data, then pass the upload_id to create_asset or update_asset.","tags":["assets"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brand":{"type":"string","minLength":1,"description":"The brand, by id (brd_…) or slug, e.g. \"moraleja\". list_brands returns both."},"filename":{"type":"string","minLength":1,"maxLength":200,"description":"The file's name with its extension, e.g. \"hero-shot.png\"."},"content_type":{"type":"string","maxLength":120,"description":"The media type, when the path's extension does not say it."}},"required":["brand","filename"],"additionalProperties":false}}}},"responses":{"200":{"description":"The result, in `data`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Data"}}}},"default":{"description":"An error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"A Brandbase API key."}},"schemas":{"Data":{"type":"object","properties":{"data":{}},"required":["data"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","code","message"]}},"required":["error"]}}}}