/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API Reference Upload Brand Asset

Upload Brand Asset

Upload a logo or favicon and get back the public URL to use in name, logo and favicon settings

POST/v1/projects/{projectId}/brand-assetsTry it
Session token

Stores a logo (for light or dark mode) or a favicon for the project and returns its public URL. Uploading changes nothing on the site by itself: put the URL in logo.light, logo.dark or favicon and publish it with Publish Appearance Changes. This is what the appearance editor's Brand section calls.

Needs a session token (API keys get 401) and the project admin role (an org admin or the owner). A caller outside the project's organization gets 404. Each upload is recorded in the audit log as brand_asset.uploaded.

Path Parameters

NameDescription
projectId:stringpathRequired
The project ID.

Request Body

Send multipart/form-data with two fields:

NameDescription
kind:stringbodyRequired
logo-light, logo-dark or favicon.
file:filebodyRequired
The image, up to 1 MB. SVG or PNG; ICO is accepted for favicon only. The type is read from the file's bytes, not its name or Content-Type.

SVG cleaning

An SVG is parsed and written out again from an allowlist of drawing elements and attributes; the cleaned file is what's stored. Removed:

•
elements that aren't SVG drawing elements, with their content — <script>, <foreignObject>, <iframe>, <embed>, <object>, editor metadata in other namespaces
•
every on… attribute
•
href and xlink:href unless they point inside the file (#id) — so javascript:, data: and external links go, along with any <use> or <image> that loads another file
•
<set> and <animate…> that target a link or an event attribute
•
url(…) that isn't url(#id), @import and expression( in styles
•
comments, processing instructions and the XML declaration

An SVG with a DOCTYPE or entity declarations, XML that isn't well formed, or a file whose single root element isn't <svg> is refused.

Response

201 Created.

NameDescription
url:string
The public URL of the stored file, served by Get Brand Asset. The file name is a hash of the contents, so the same file always gets the same URL and a URL never changes meaning.
contentType:string
image/svg+xml, image/png or image/x-icon.
bytes:number
The stored size — for an SVG, the size after cleaning.
width:number
The image's width in pixels, when it can be read: a PNG's header, an ICO's first image, or an SVG's width / viewBox.
height:number
The image's height in pixels, when it can be read.

Response

Then publish it:

Error Responses

StatusCodeWhen
400invalid_assetThe file can't be used. details.reason says why (below)
401unauthorizedNo session token, or an API key
403admin_requiredYou're a member, not an admin
404not_foundThe project doesn't exist, or you're not in its organization
413asset_too_largeThe file is over 1 MB. details.maxBytes is 1048576

details.reason for invalid_asset:

ReasonMessage
missing_fileSend the file as multipart/form-data with the fields "file" and "kind". or Send the image in a multipart field named "file".
invalid_kind"kind" must be one of: logo-light, logo-dark, favicon.
emptyThe file is empty.
unsupported_typeUpload an SVG or PNG file. (Upload an SVG, PNG or ICO file. for favicon), or ICO files can only be used as the favicon. Upload the logo as SVG or PNG.
doctypeSVG files with a DOCTYPE or entity declarations are not accepted.
malformedThe SVG is not well-formed XML.
not_svgThe file is not an SVG image: it needs a single <svg> root element.
json
{
"error": {
"code": "invalid_asset",
"message": "ICO files can only be used as the favicon. Upload the logo as SVG or PNG.",
"details": { "reason": "unsupported_type" }
}
}
Was this page helpful? Yes No
Request
cURLJavaScriptPythonGoRubyPHPJavaC#cURL
curl -X POST https://api.syntext.dev/v1/projects/b4c5d6e7-f8a9-4b0c-9d1e-2f3a4b5c6d7e/brand-assets \
-H "Authorization: Bearer <session token>" \
-F "kind=logo-light" \
-F "file=@logo.svg"
Responseapplication/json
jsoncURL
{
"data": {
"url": "https://api.syntext.dev/v1/brand-assets/b4c5d6e7-f8a9-4b0c-9d1e-2f3a4b5c6d7e/3f9a1c2b7d4e.svg",
"contentType": "image/svg+xml",
"bytes": 2184,
"width": 120,
"height": 32
}
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext