---
title: "Add Brand Kit Image"
method: POST
path: "/brand-kits/{brand_kit_id}/images"
tags: ["brand-kits"]
---

# Add Brand Kit Image

`POST /brand-kits/{brand_kit_id}/images`

## Request

- Base URL: `https://api.moda.app/v1`
- URL: `https://api.moda.app/v1/brand-kits/{brand_kit_id}/images`
- Auth: HTTP bearer

Attach an uploaded image to a brand kit (ENG-2466).

Multipart-upload flow: the caller first ``POST /v1/uploads`` their file
and receives a ``file_*`` id (the response's ``id`` field), then calls this
endpoint with that id as ``file_id`` to associate the image with the brand
kit (logo / reference / asset). A bare UUID is also accepted for back-compat
with older integrations.

Returns ``404 not_found`` if the brand kit does not exist, has been
deleted, or the caller lacks team access — collapsed like the sibling
endpoints so the write path does not leak existence of brand kits in
other teams. An unusable ``file_id`` (missing, deleted, or outside the
kit's team) is a ``400``.

The attach is idempotent (ENG-3043): re-posting a ``file_id`` already on
the kit returns ``201`` with the brand kit unchanged rather than adding a
second image, so retries and full re-syncs are safe. Dedupe is per storage
bucket, and ``reference`` and ``asset`` share one bucket — re-attaching a
``reference`` image as an ``asset`` succeeds without recording the new
role. Re-posting the same ``role`` with a *different* ``label`` **relabels
the existing image in place** (ENG-5988) and returns ``201``: the ref keeps
its id, notes and position, and no second image is added. The role has to
match because the scan is bucket-scoped: re-posting under the other bucket's
role finds nothing to relabel and appends instead. ``role`` is required
here, so a caller always states one — the transports that default it carry a
louder warning. It was a ``400`` until then, on the
reasoning that the no-op path could not carry a new label without writing
and that returning success over a dropped one would be undetectable — both
true, and both answered by writing the label instead of dropping it.

## Path parameters

- `brand_kit_id` string, required: Prefixed ``bk_`` wire ID (Crockford base32 body) — the canonical, recommended form. For back-compat, **a bare UUID string is also accepted** in both path parameters and JSON request bodies (older integrations that stored raw UUIDs keep working), as is **the prefix over a UUID body** (``bk_00000000-0000-4000-8000-000000000000``). All three are permanent, supported inputs; only the canonical form is ever emitted.

## Headers

- `Moda-Version` '2026-04-12' | '2026-05-01'

## Request body

- AddBrandKitImageRequest: Request body for ``POST /v1/brand-kits/{id}/images`` (ENG-2466).
  - `file_id` string, required: The ``file_`` ID returned as ``id`` by a prior ``POST /v1/uploads`` response. A bare UUID (the form older integrations stored) is also accepted for back-compat.
  - `role` 'logo' | 'reference' | 'asset', required: How the image is used. 'logo' gets special downstream treatment; 'reference' is a style hint visible to the design agent; 'asset' is includable in designs.
  - `label` string, nullable: Optional human-readable label.

## Response `201`

Successful Response

- object

## Other responses

- `401`: Authentication required.
- `402`: Insufficient credits for a metered operation.
- `403`: Permission denied for this scope.
- `404`: Resource not found.
- `409`: Conflict (idempotency / resource state).
- `422`: Request validation failed.
- `429`: Rate limit exceeded.
- `500`: Internal error.

## Changes

- **2026-11-03** `9ac6a3abc0f8`: 8 info
  - added the non-success response with the status `402`
  - added the optional property `retryable` to the response with the `401` status
  - added the optional property `retryable` to the response with the `403` status
  - added the optional property `retryable` to the response with the `404` status
  - …4 more

[Operation history](https://skmtc.dev/moda/apis/moda-public-api/changes/brand-kits/:brand_kit_id/images/post.md)

---

[API](https://skmtc.dev/moda/apis/moda-public-api.md) - [All operations](https://skmtc.dev/moda/apis/moda-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/moda/apis/moda-public-api/revisions/9ac6a3abc0f8?raw)