---
title: "Create a Brand Edit"
method: POST
path: "/brands/{id}/edits"
tags: ["Brands"]
---

# Create a Brand Edit

`POST /brands/{id}/edits`

## Request

- Base URL: `https://www.rainbrand.com/api/v1`
- URL: `https://www.rainbrand.com/api/v1/brands/{id}/edits`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer
  - OAuth 2
    - Authorization code: `https://www.rainbrand.com/api/auth/oauth2/authorize`
    - Token URL: `https://www.rainbrand.com/api/auth/oauth2/token`

Prepare proposed changes without changing the active brand. Inspect progress and the proposal with [Get a Brand Edit](/api-reference/brands/get-a-brand-edit).

## Path parameters

- `id` string, uuid, required: Brand ID

## Headers

- `idempotency-key` string, required: A unique key for this operation. Reuse it when retrying the same request.

## Request body

- object
  - `baseSkillId` string, uuid, required: The active Brand Skill version on which this edit is based.
  - `replacesEditId` string, uuid: A candidate awaiting approval to replace atomically once the new candidate is ready. The previous candidate remains available while preparation is incomplete or unsuccessful.
  - `change` union, required: The requested change: an instruction for a semantic edit, or exact profile values with an optional related instruction.
    - object
      - `kind` 'instruction', required
      - `instruction` string
    - object
      - `kind` 'profile', required
      - `changes` object, required: Exact structured Brand Profile values to include in the candidate; related Markdown may also change.
        - `name` string
        - `primaryLogo` object
          - `imageId` string, uuid, required
        - `colors` object[]: The complete desired palette in order. For a matching HEX value, omitted name, group, and usage fields keep their current values; null removes that metadata field. Colors absent from the list are removed.
          - `hex` string, required
          - `name` string, nullable: The color's name. Omit to keep the name for a matching HEX value, or send null to remove it.
          - `group` string, nullable: The palette group label. Omit to keep the group for a matching HEX value, or send null to remove it.
          - `usage` string, nullable: Guidance on when and how to use this color. Omit to keep the guidance for a matching HEX value, or send null to remove it.
        - `gradients` object[]: The complete desired list of linear gradients. Omit to keep the current gradients, or send an empty list to remove them all.
          - `name` string, required: The gradient's name, as established by the source.
          - `angle` number, required: The linear gradient's angle in degrees, from 0 up to but not including 360.
          - `stops` object[], required: At least two color stops in non-decreasing position order. Adjacent stops may share a position to create a hard transition.
            - `hex` string, required: Six-digit HEX color value for this stop, including the leading #.
            - `position` number, required: The stop's position as a percentage from 0 to 100.
          - `usage` string: Source-supported guidance on when and how to use this gradient.
        - `typography` union
          - object
            - `roles` object[]: Roles to add or change, by name. New roles are appended.
              - …
            - `removeRoles` string[]: Roles to remove, by name.
          - object: Deprecated. Heading and body fonts, applied to the roles named Heading and Body. A font changes or adds that role.
            - `heading` union: Font for the role named Heading; null removes that role.
              - …
            - `body` union: Font for the role named Body; null removes that role.
              - …
      - `instruction` string: Additional guidance for Brand content related to the profile changes.
  - `evidence` object: Optional sources and Brand Library images that support the requested change.
    - `sources` union[]: Evidence sources for this request. Across the original request and all follow-up answers, a Brand Edit accepts at most 30 submitted sources and 256 MiB of stored files, with up to 100 MiB per file. Resubmitting the same URL consumes another source slot. Each submission may include at most one website and one Instagram account.
      - union
        - object
          - `kind` 'website', required: Source type for a public website
          - `url` string, uri, required: Public website URL to turn into a Brand Skill
        - object
          - `kind` 'instagram', required: Source type for an Instagram account
          - `username` string, required: Instagram username to use as brand evidence
        - object
          - `kind` 'file', required: Source type for an uploaded file, including a PDF
          - `url` string, uri, required: Temporary public HTTPS URL for a file up to 100 MiB, including a PDF
          - `filename` string: Original filename used for source labels. It defaults from the URL when possible.
        - object
          - `kind` 'file', required: Source type for a completed temporary upload
          - `uploadId` string, uuid, required: Completed temporary upload from POST /uploads
    - `imageIds` string[]: Brand Library image IDs to use as evidence. At most 10 submitted IDs across the original request and all follow-up answers; submitting an image again consumes another slot.

## Response `202`

OK

- object
  - `data` object, required
    - `id` string, uuid, required
    - `brandId` string, uuid, required
    - `status` 'preparing' | 'input_required' | 'awaiting_approval' | 'applied' | 'discarded' | 'stale' | 'no_changes' | 'failed', required
    - `baseSkillId` string, uuid, required
    - `target` object, nullable, required
      - `skillId` string, uuid, required
    - `changeSet` object, nullable, required
      - `schemaVersion` unknown, required
      - `baseSkillId` string, uuid, required: Canonical identity of the complete base Brand revision.
      - `targetSkillId` string, uuid, required: Canonical identity reserved for the complete candidate Brand revision.
      - `profileChanges` object[], required
        - `kind` 'field', required
        - `path` string, required
        - `operation` 'add' | 'remove' | 'replace', required
        - `previous` string, nullable, required
        - `next` string, nullable, required
      - `markdownChanges` object[], required
        - `path` string, required
        - `operation` 'add' | 'remove' | 'modify', required
        - `additions` integer, nullable, required
        - `deletions` integer, nullable, required
        - `hunks` object[], required
          - `oldStart` integer, required
          - `oldLines` integer, required
          - `newStart` integer, required
          - `newLines` integer, required
          - `lines` object[], required
            - `kind` 'context' | 'add' | 'remove', required
            - `text` string, required
            - `noNewlineAtEndOfFile` unknown
        - `truncated` boolean, required
      - `assetChanges` union[], required
        - union
          - object
            - `kind` 'asset', required
            - `role` 'primary_logo', required
            - `operation` 'add' | 'remove' | 'replace', required
            - `previousAssetId` string, uuid, nullable, required
            - `nextAssetId` string, uuid, nullable, required
          - object
            - `kind` 'asset', required
            - `role` 'font', required
            - `operation` 'add' | 'remove', required
            - `path` string, required
            - `family` string, required
            - `weight` integer, required
            - `format` 'woff' | 'woff2' | 'ttf' | 'otf', required
    - `targetProfile` object, nullable, required
      - `name` string, nullable, required
      - `colors` object[], nullable
        - `hex` string, required: Six-digit HEX color value, including the leading #.
        - `name` string: The color's name, when established by the source.
        - `group` string: The source's palette group label. Omit when the source does not group this color.
        - `usage` string: Source-supported guidance on when and how to use this color.
      - `gradients` object[]: The Brand's evidenced linear gradients in source order, including exact angles, stops, and usage guidance.
        - `name` string, required: The gradient's name, as established by the source.
        - `angle` number, required: The linear gradient's angle in degrees, from 0 up to but not including 360.
        - `stops` object[], required: At least two color stops in non-decreasing position order. Adjacent stops may share a position to create a hard transition.
          - `hex` string, required: Six-digit HEX color value for this stop, including the leading #.
          - `position` number, required: The stop's position as a percentage from 0 to 100.
        - `usage` string: Source-supported guidance on when and how to use this gradient.
      - `primaryLogo` object, nullable, required
        - `imageId` string, uuid, required
      - `typography` object
        - `roles` object[], required
          - `name` string, required
          - `weight` integer, nullable, required
          - `font` union, required
            - object
              - …
            - object
              - …
        - `heading` union, required: Deprecated. Font of the role named Heading, if any.
          - object
            - `source` 'google' | 'custom', required
            - `family` string, required
          - object
            - `family` string, required
            - `status` 'unavailable', required
            - `reason` string, required
        - `body` union, required: Deprecated. Font of the role named Body, if any.
          - object
            - `source` 'google' | 'custom', required
            - `family` string, required
          - object
            - `family` string, required
            - `status` 'unavailable', required
            - `reason` string, required
    - `interaction` union, required
      - object
        - `id` string, uuid, required
        - `subject` string, required
        - `prompt` string, required
        - `kind` 'clarification', required
        - `accepts` object, required
          - `text` object
            - `required` boolean
            - `minLength` integer
            - `maxLength` integer
          - `images` object
            - `min` integer
            - `max` integer, required
          - `sources` object
            - `min` integer
            - `max` integer, required
      - object
        - `id` string, uuid, required
        - `subject` string, required
        - `prompt` string, required
        - `kind` 'choice', required
        - `options` object[], required
          - `id` string, required
          - `label` string, required
          - `description` string
          - `imageIds` string[]
        - `alternate` object
          - `label` string
          - `accepts` object, required
            - `text` object
              - …
            - `images` object
              - …
            - `sources` object
              - …
    - `replacement` object, nullable, required
      - `replacesEditId` string, uuid, nullable, required
      - `replacedByEditId` string, uuid, nullable, required
      - `discardReason` 'explicit' | 'replaced', nullable, required
    - `changeSummary` string, nullable, required
    - `statusMessage` string, required
    - `error` object, nullable, required
      - `code` string, required
      - `message` string, required
      - `retryable` boolean, required
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required

## Other responses

- `400`: 400
- `401`: 401
- `402`: 402
- `403`: 403
- `404`: 404
- `409`: 409
- `429`: 429
- `500`: 500

---

[API](https://skmtc.dev/rainbrand/apis/rainbrand-api.md) - [All operations](https://skmtc.dev/rainbrand/apis/rainbrand-api/llms.txt) - [OpenAPI document](https://skmtc.dev/rainbrand/apis/rainbrand-api/revisions/012b8e9da4df?raw)