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
Status
Code
When
400
invalid_asset
The file can't be used. details.reason says why (below)
401
unauthorized
No session token, or an API key
403
admin_required
You're a member, not an admin
404
not_found
The project doesn't exist, or you're not in its organization
413
asset_too_large
The file is over 1 MB. details.maxBytes is 1048576
details.reason for invalid_asset:
Reason
Message
missing_file
Send 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.
empty
The file is empty.
unsupported_type
Upload 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.
doctype
SVG files with a DOCTYPE or entity declarations are not accepted.
malformed
The SVG is not well-formed XML.
not_svg
The 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.",