Have an agent build it. Copy the brief below into Claude Code, Cursor, or any coding agent with access to your project. It states the calls, the questions worth asking you first, and the mistakes to avoid.
Agent brief
Agent brief
img tag at it.
The pipeline
1. Render the mark directly
2. Use a publishable key in the browser
Browser traffic uses a publishable key restricted to your domains, not your secret API key. It is metered on its own allowance and never spends credits, which is what makes it safe to put in client-side markup.3. Decide what a missing logo looks like
By default a domain we hold no mark for returns a generated monogram, so the tag always renders something. Ask for a 404 instead when you would rather draw your own fallback.4. Fetch it server side when you need the metadata
When you need the file itself, or its dimensions and dominant colour,GET /v1/web/brand/logo returns the asset with its details for 1 credit.
The first request for a new domain
A domain nobody has asked for before is resolved on the spot, and that first request waits rather than answering with a placeholder. The wait is bounded. Past the budget the resolve finishes in the background, that one request gets the fallback, and the next request is served from storage. So a cold domain takes a few seconds once and every request after it is immediate. This shapes where you put the call. In a list view rendering fifty companies, most will be warm and a few may not be, so give the image a placeholder background and let it swap in rather than blocking a layout on it. If you know the domains ahead of time, such as after an import, request them once in the background and the customer never meets a cold one.Getting the rendering right
Ask for thesize you actually draw at. Requesting 512 to display at 32 wastes bandwidth on every row of every page, and on a directory that is most of the page weight.
Account for retina. A 32 pixel avatar on a 2x display wants a 64 pixel image, so size from the device pixel ratio rather than the CSS pixel.
Pick the variant for the background you are drawing on. A light mark on a light card is an empty box, and this is the single most common way this goes wrong. If your interface has both themes, the logo has to switch with them.
Reserve the space. Give the image a fixed box with an aspect ratio so the row does not jump when it loads, since a directory that reflows as logos arrive feels broken even when everything worked.
Choosing the fallback deliberately
By default a domain with no mark returns a generated monogram, so the tag always renders something. That is right for most directories, since a consistent shape in every row looks intentional. Setfallback=404 instead when you want to draw your own placeholder, and handle the error on the image element.
Do not let a missing logo look like a broken page. Whichever route you pick, the empty state should be a designed state.
Operating it
The image URL is public and immutable, so it can go anywhere: your markup, an email template, a PDF export. Nothing to sign, nothing to proxy, no bucket to keep. Restrict the publishable key to your domains. It is going into client-side markup where anyone can read it, and the domain restriction is what stops it being used elsewhere. Remember the edge cache when you rotate a key. Once a URL has been served it is cached at the edge for up to a day, so revoking a key does not immediately stop already-cached URLs from loading. Reach for the API call only when you need more than pixels.GET /v1/web/brand/logo returns the file with its dimensions and dominant colour for 1 credit, which is what you want when generating an email template or picking a background to sit the mark on.
What it costs
The image endpoint does not spend credits. It runs on a separate allowance tied to your publishable key, because a logo in a list view is not the same kind of request as a scrape. The server side logo call is 1 credit. A full brand record is 5, so reach for it only when you want more than the mark.What to watch for
Setsize to what you actually render. Asking for 512 to display at 32 wastes bandwidth on every row of every page.
Pick the variant for your background. A light mark on a light card is an empty box, and this is the single most common way this goes wrong.
Remember the edge cache. Once a URL has been served it is cached at the edge for up to a day, so revoking a key does not immediately stop already-cached URLs from loading.