> ## Documentation Index > Fetch the complete documentation index at: https://docs.rainbrand.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a Brand Edit > Prepare proposed changes to a brand without changing its active guidance or profile. See [Edit a brand](/guides/edit-brand) to prepare, review, and apply changes. ## OpenAPI ````yaml https://www.rainbrand.com/api/v1/spec.json post /brands/{id}/edits openapi: 3.1.1 info: title: Rainbrand API version: 1.0.0 servers: - url: https://www.rainbrand.com/api/v1 security: - apiKey: [] - bearer: [] tags: - name: Uploads description: >- Stage private local files for brand sources, the Library, and other supported operations. - name: Account description: >- Inspect the authenticated account — profile, credit balance, and accessible workspaces. - name: Brands description: Manage brands and brand identity. - name: Library description: Add, list, and remove a brand's images, video, and audio. - name: Images description: Retrieve and manage images. - name: Videos description: Retrieve and manage video files. - name: Audio description: Retrieve and manage audio files. - name: Briefs description: Get brand guidance and selected assets for a specific task. - name: Models description: Find available models and check their inputs. - name: Generations description: Create and retrieve model generations. - name: Reviews description: >- Check an asset against a brand's color, typography, logo, and copy guidance. paths: /brands/{id}/edits: post: tags: - Brands summary: Create a Brand Edit description: >- Prepare proposed changes to a brand without changing its active guidance or profile. See [Edit a brand](/guides/edit-brand) to prepare, review, and apply changes. operationId: brands.edit parameters: - name: id in: path required: true schema: type: string format: uuid description: Brand ID - name: idempotency-key in: header required: true schema: type: string minLength: 1 maxLength: 255 description: >- A unique key for this operation. Reuse it when retrying the same request. requestBody: required: true content: application/json: schema: type: object properties: baseSkillId: type: string format: uuid description: The active Brand Skill version on which this edit is based. replacesEditId: type: string format: uuid description: >- 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: anyOf: - type: object properties: kind: const: instruction instruction: type: string minLength: 1 maxLength: 4000 required: - kind additionalProperties: false - type: object properties: kind: const: profile changes: type: object properties: name: type: string minLength: 1 maxLength: 120 primaryLogo: type: object properties: imageId: type: string format: uuid required: - imageId additionalProperties: false colors: type: array minItems: 1 items: type: object properties: hex: type: string pattern: ^#[0-9A-Fa-f]{6}$ name: anyOf: - type: string minLength: 1 maxLength: 80 - type: 'null' description: >- The color's name. Omit to keep the name for a matching HEX value, or send null to remove it. group: anyOf: - type: string minLength: 1 maxLength: 80 - type: 'null' description: >- The palette group label. Omit to keep the group for a matching HEX value, or send null to remove it. usage: anyOf: - type: string minLength: 1 maxLength: 500 - type: 'null' description: >- 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. required: - hex additionalProperties: false description: >- 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. gradients: type: array items: type: object properties: name: type: string minLength: 1 maxLength: 80 description: >- The gradient's name, as established by the source. angle: type: number minimum: 0 exclusiveMaximum: 360 description: >- The linear gradient's angle in degrees, from 0 up to but not including 360. stops: type: array minItems: 2 items: type: object properties: hex: type: string pattern: ^#[0-9A-Fa-f]{6}$ description: >- Six-digit HEX color value for this stop, including the leading #. position: type: number minimum: 0 maximum: 100 description: >- The stop's position as a percentage from 0 to 100. required: - hex - position additionalProperties: false description: >- At least two color stops in non-decreasing position order. Adjacent stops may share a position to create a hard transition. usage: type: string minLength: 1 maxLength: 500 description: >- Source-supported guidance on when and how to use this gradient. required: - name - angle - stops additionalProperties: false description: >- The complete desired list of linear gradients. Omit to keep the current gradients, or send an empty list to remove them all. typography: anyOf: - type: object properties: roles: type: array items: type: object properties: name: type: string minLength: 1 maxLength: 80 description: >- Existing role to change, or a new role to add. Names are unique regardless of case. newName: type: string minLength: 1 maxLength: 80 description: Rename the role. font: anyOf: - type: object properties: source: {} family: {} additionalProperties: false - type: object properties: source: {} family: {} fontAssetId: {} additionalProperties: false description: >- Required for a new role. Omit to keep the role's font. weight: anyOf: - type: integer minimum: 1 maximum: 1000 - type: 'null' description: >- Font weight for this role. Omit to keep it; null clears it. required: - name additionalProperties: false description: >- Roles to add or change, by name. New roles are appended. removeRoles: type: array items: type: string minLength: 1 maxLength: 80 description: Roles to remove, by name. additionalProperties: false - type: object properties: heading: anyOf: - anyOf: - type: object properties: source: const: google family: type: string minLength: 1 maxLength: 120 required: - source - family additionalProperties: false - type: object properties: source: const: custom family: type: string minLength: 1 maxLength: 120 description: >- Font family, 1–120 characters, with no line breaks or NUL characters. For a custom font, use the exact family returned by font upload; matching is case-sensitive after trimming. fontAssetId: type: string format: uuid required: - source - family - fontAssetId additionalProperties: false - type: 'null' description: >- Font for the role named Heading; null removes that role. body: anyOf: - anyOf: - type: object properties: source: const: google family: type: string minLength: 1 maxLength: 120 required: - source - family additionalProperties: false - type: object properties: source: const: custom family: type: string minLength: 1 maxLength: 120 description: >- Font family, 1–120 characters, with no line breaks or NUL characters. For a custom font, use the exact family returned by font upload; matching is case-sensitive after trimming. fontAssetId: type: string format: uuid required: - source - family - fontAssetId additionalProperties: false - type: 'null' description: >- Font for the role named Body; null removes that role. additionalProperties: false description: >- Deprecated. Heading and body fonts, applied to the roles named Heading and Body. A font changes or adds that role. additionalProperties: false description: >- Exact structured Brand Profile values to include in the candidate; related Markdown may also change. instruction: type: string minLength: 1 maxLength: 4000 description: >- Additional guidance for Brand content related to the profile changes. required: - kind - changes additionalProperties: false description: >- The requested change: an instruction for a semantic edit, or exact profile values with an optional related instruction. evidence: type: object properties: sources: type: array maxItems: 30 items: anyOf: - anyOf: - type: object properties: kind: enum: - website type: string description: Source type for a public website url: type: string format: uri description: >- Public website URL to turn into a Brand Skill required: - kind - url title: Website - type: object properties: kind: enum: - instagram type: string description: Source type for an Instagram account username: type: string minLength: 1 maxLength: 31 description: >- Instagram username to use as brand evidence required: - kind - username title: Instagram - type: object properties: kind: enum: - file type: string description: >- Source type for an uploaded file, including a PDF url: type: string format: uri description: >- Temporary public HTTPS URL for a file up to 100 MiB, including a PDF filename: type: string minLength: 1 maxLength: 240 description: >- Original filename used for source labels. It defaults from the URL when possible. required: - kind - url additionalProperties: false title: File - type: object properties: kind: const: file description: Source type for a completed temporary upload uploadId: type: string format: uuid description: Completed temporary upload from POST /uploads required: - kind - uploadId additionalProperties: false title: Temporary upload description: >- 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. default: [] imageIds: type: array maxItems: 10 items: type: string format: uuid default: [] description: >- 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. additionalProperties: false default: sources: [] imageIds: [] description: >- Optional sources and Brand Library images that support the requested change. required: - baseSkillId - change additionalProperties: false responses: '202': description: OK content: application/json: schema: type: object properties: data: type: object properties: id: type: string format: uuid brandId: type: string format: uuid status: enum: - preparing - input_required - awaiting_approval - applied - discarded - stale - no_changes - failed type: string baseSkillId: type: string format: uuid target: anyOf: - type: object properties: skillId: type: string format: uuid required: - skillId additionalProperties: false - type: 'null' changeSet: anyOf: - type: object properties: schemaVersion: const: 2 baseSkillId: type: string format: uuid description: >- Canonical identity of the complete base Brand revision. targetSkillId: type: string format: uuid description: >- Canonical identity reserved for the complete candidate Brand revision. profileChanges: type: array items: type: object properties: kind: const: field path: type: string minLength: 1 operation: enum: - add - remove - replace type: string previous: anyOf: - type: string - type: 'null' next: anyOf: - type: string - type: 'null' required: - kind - path - operation - previous - next additionalProperties: false markdownChanges: type: array items: type: object properties: path: type: string minLength: 1 operation: enum: - add - remove - modify type: string additions: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' deletions: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' hunks: type: array items: type: object properties: oldStart: type: integer minimum: 0 maximum: 9007199254740991 oldLines: type: integer minimum: 0 maximum: 9007199254740991 newStart: type: integer minimum: 0 maximum: 9007199254740991 newLines: type: integer minimum: 0 maximum: 9007199254740991 lines: type: array items: type: object properties: kind: enum: - context - add - remove type: string text: type: string noNewlineAtEndOfFile: const: true description: >- This line has no terminating newline: in the original file for remove, the candidate for add, or both for context. This annotation does not count as a content line. Older receipts may omit this information. required: - kind - text additionalProperties: false required: - oldStart - oldLines - newStart - newLines - lines additionalProperties: false truncated: type: boolean required: - path - operation - additions - deletions - hunks - truncated additionalProperties: false assetChanges: type: array items: anyOf: - type: object properties: kind: const: asset role: const: primary_logo operation: enum: - add - remove - replace type: string previousAssetId: anyOf: - type: string format: uuid - type: 'null' nextAssetId: anyOf: - type: string format: uuid - type: 'null' required: - kind - role - operation - previousAssetId - nextAssetId additionalProperties: false - type: object properties: kind: const: asset role: const: font operation: enum: - add - remove type: string path: type: string minLength: 1 family: type: string minLength: 1 weight: type: integer minimum: 1 maximum: 1000 format: enum: - woff - woff2 - ttf - otf type: string required: - kind - role - operation - path - family - weight - format additionalProperties: false required: - schemaVersion - baseSkillId - targetSkillId - profileChanges - markdownChanges - assetChanges additionalProperties: false - type: 'null' targetProfile: anyOf: - type: object properties: name: anyOf: - type: string - type: 'null' colors: anyOf: - type: array minItems: 1 items: type: object properties: hex: type: string pattern: ^#[0-9A-Fa-f]{6}$ description: >- Six-digit HEX color value, including the leading #. name: type: string minLength: 1 maxLength: 80 description: >- The color's name, when established by the source. group: type: string minLength: 1 maxLength: 80 description: >- The source's palette group label. Omit when the source does not group this color. usage: type: string minLength: 1 maxLength: 500 description: >- Source-supported guidance on when and how to use this color. required: - hex additionalProperties: false - type: 'null' gradients: type: array items: type: object properties: name: type: string minLength: 1 maxLength: 80 description: >- The gradient's name, as established by the source. angle: type: number minimum: 0 exclusiveMaximum: 360 description: >- The linear gradient's angle in degrees, from 0 up to but not including 360. stops: type: array minItems: 2 items: type: object properties: hex: type: string pattern: ^#[0-9A-Fa-f]{6}$ description: >- Six-digit HEX color value for this stop, including the leading #. position: type: number minimum: 0 maximum: 100 description: >- The stop's position as a percentage from 0 to 100. required: - hex - position additionalProperties: false description: >- At least two color stops in non-decreasing position order. Adjacent stops may share a position to create a hard transition. usage: type: string minLength: 1 maxLength: 500 description: >- Source-supported guidance on when and how to use this gradient. required: - name - angle - stops additionalProperties: false description: >- The Brand's evidenced linear gradients in source order, including exact angles, stops, and usage guidance. primaryLogo: anyOf: - type: object properties: imageId: type: string format: uuid required: - imageId additionalProperties: false - type: 'null' typography: type: object properties: roles: type: array items: type: object properties: name: type: string minLength: 1 weight: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' font: anyOf: - type: object properties: source: enum: - google - custom type: string family: type: string minLength: 1 maxLength: 120 required: - source - family additionalProperties: false - type: object properties: family: type: string minLength: 1 status: const: unavailable reason: type: string minLength: 1 required: - family - status - reason additionalProperties: false required: - name - weight - font additionalProperties: false heading: anyOf: - anyOf: - type: object properties: source: enum: - google - custom type: string family: type: string minLength: 1 maxLength: 120 required: - source - family additionalProperties: false - type: object properties: family: type: string minLength: 1 status: const: unavailable reason: type: string minLength: 1 required: - family - status - reason additionalProperties: false - type: 'null' description: >- Deprecated. Font of the role named Heading, if any. body: anyOf: - anyOf: - type: object properties: source: enum: - google - custom type: string family: type: string minLength: 1 maxLength: 120 required: - source - family additionalProperties: false - type: object properties: family: type: string minLength: 1 status: const: unavailable reason: type: string minLength: 1 required: - family - status - reason additionalProperties: false - type: 'null' description: >- Deprecated. Font of the role named Body, if any. required: - roles - heading - body additionalProperties: false required: - name - primaryLogo additionalProperties: false - type: 'null' interaction: anyOf: - anyOf: - type: object properties: id: type: string format: uuid subject: type: string minLength: 1 maxLength: 200 prompt: type: string minLength: 1 maxLength: 1000 kind: const: clarification accepts: type: object properties: text: type: object properties: required: type: boolean default: false minLength: type: integer minimum: 0 maximum: 10000 default: 1 maxLength: type: integer minimum: -9007199254740991 maximum: 10000 exclusiveMinimum: 0 default: 10000 additionalProperties: false images: type: object properties: min: type: integer minimum: 0 maximum: 9007199254740991 default: 0 max: type: integer minimum: -9007199254740991 maximum: 9007199254740991 exclusiveMinimum: 0 required: - max additionalProperties: false sources: type: object properties: min: type: integer minimum: 0 maximum: 9007199254740991 default: 0 max: type: integer minimum: -9007199254740991 maximum: 9007199254740991 exclusiveMinimum: 0 required: - max additionalProperties: false additionalProperties: false required: - id - subject - prompt - kind - accepts additionalProperties: false - type: object properties: id: type: string format: uuid subject: type: string minLength: 1 maxLength: 200 prompt: type: string minLength: 1 maxLength: 1000 kind: const: choice options: type: array minItems: 2 maxItems: 6 items: type: object properties: id: type: string minLength: 1 maxLength: 80 label: type: string minLength: 1 maxLength: 200 description: type: string minLength: 1 maxLength: 500 imageIds: type: array maxItems: 10 items: type: string format: uuid required: - id - label additionalProperties: false alternate: type: object properties: label: type: string minLength: 1 maxLength: 200 accepts: type: object properties: text: type: object properties: required: type: boolean default: false minLength: type: integer minimum: 0 maximum: 10000 default: 1 maxLength: type: integer minimum: -9007199254740991 maximum: 10000 exclusiveMinimum: 0 default: 10000 additionalProperties: false images: type: object properties: min: type: integer minimum: 0 maximum: 9007199254740991 default: 0 max: type: integer minimum: -9007199254740991 maximum: 9007199254740991 exclusiveMinimum: 0 required: - max additionalProperties: false sources: type: object properties: min: type: integer minimum: 0 maximum: 9007199254740991 default: 0 max: type: integer minimum: -9007199254740991 maximum: 9007199254740991 exclusiveMinimum: 0 required: - max additionalProperties: false additionalProperties: false required: - accepts additionalProperties: false required: - id - subject - prompt - kind - options additionalProperties: false - type: 'null' replacement: anyOf: - type: object properties: replacesEditId: anyOf: - type: string format: uuid - type: 'null' replacedByEditId: anyOf: - type: string format: uuid - type: 'null' discardReason: anyOf: - enum: - explicit - replaced type: string - type: 'null' required: - replacesEditId - replacedByEditId - discardReason additionalProperties: false - type: 'null' changeSummary: anyOf: - type: string - type: 'null' statusMessage: type: string error: anyOf: - type: object properties: code: type: string minLength: 1 message: type: string minLength: 1 retryable: type: boolean required: - code - message - retryable additionalProperties: false - type: 'null' createdAt: type: string format: date-time x-native-type: date updatedAt: type: string format: date-time x-native-type: date required: - id - brandId - status - baseSkillId - target - changeSet - targetProfile - interaction - replacement - changeSummary - statusMessage - error - createdAt - updatedAt additionalProperties: false required: - data headers: Location: description: >- Relative API path for reading this Brand Edit: `/api/v1/brands/{brandId}/edits/{editId}`. schema: type: string Retry-After: description: >- Seconds to wait before reading the edit again. Present only when the returned status is `preparing`; currently 2. schema: type: integer minimum: 0 '400': description: '400' content: application/json: schema: $ref: '#/components/schemas/BrandsEdit400ErrorResponse' '401': description: '401' content: application/json: schema: $ref: '#/components/schemas/BrandsEdit401ErrorResponse' '402': description: '402' content: application/json: schema: $ref: '#/components/schemas/BrandsEdit402ErrorResponse' '403': description: '403' content: application/json: schema: $ref: '#/components/schemas/BrandsEdit403ErrorResponse' '404': description: '404' content: application/json: schema: $ref: '#/components/schemas/BrandsEdit404ErrorResponse' '409': description: '409' content: application/json: schema: $ref: '#/components/schemas/BrandsEdit409ErrorResponse' '429': description: '429' content: application/json: schema: $ref: '#/components/schemas/BrandsEdit429ErrorResponse' headers: Retry-After: description: >- Seconds until the applicable request or operation limit resets. Present when the limiter can calculate the delay. schema: type: integer minimum: 0 '500': description: '500' content: application/json: schema: $ref: '#/components/schemas/BrandsEdit500ErrorResponse' components: schemas: BrandsEdit400ErrorResponse: type: object properties: error: allOf: - $ref: '#/components/schemas/ApiError' - anyOf: - type: object properties: code: const: INVALID_INPUT status: const: 400 message: type: string default: Invalid Brand Edit input data: {} required: - code - status - message - type: object properties: code: type: string status: type: integer message: type: string data: {} required: - code - status - message required: - error BrandsEdit401ErrorResponse: type: object properties: error: allOf: - $ref: '#/components/schemas/ApiError' - anyOf: - type: object properties: code: const: UNAUTHORIZED status: const: 401 message: type: string default: Invalid or missing API credentials data: {} required: - code - status - message - type: object properties: code: type: string status: type: integer message: type: string data: {} required: - code - status - message required: - error BrandsEdit402ErrorResponse: type: object properties: error: allOf: - $ref: '#/components/schemas/ApiError' - anyOf: - type: object properties: code: const: INSUFFICIENT_CREDITS status: const: 402 message: type: string default: Not enough credits to edit this brand data: type: object properties: action_url: type: string format: uri description: >- Deep link to /pricing for the caller to top up credits credits_required: type: number description: Credits the refused request needed balance: type: number description: >- The workspace's credit balance when the request was refused pricing_version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- The workspace's pricing version. Credit amounts are comparable only within one version. required: - action_url required: - code - status - message - data - type: object properties: code: const: PAYMENT_REQUIRED status: const: 402 message: type: string default: Subscription paused — complete payment to resume data: type: object properties: action_url: type: string format: uri description: >- Deep link to /pricing to complete the pending payment required: - action_url required: - code - status - message - data - type: object properties: code: type: string status: type: integer message: type: string data: {} required: - code - status - message required: - error BrandsEdit403ErrorResponse: type: object properties: error: allOf: - $ref: '#/components/schemas/ApiError' - anyOf: - type: object properties: code: const: ACCOUNT_BANNED status: const: 403 message: type: string default: This account has been suspended. data: {} required: - code - status - message - type: object properties: code: const: FORBIDDEN status: const: 403 message: type: string default: Plan upgrade required data: {} required: - code - status - message - type: object properties: code: type: string status: type: integer message: type: string data: {} required: - code - status - message required: - error BrandsEdit404ErrorResponse: type: object properties: error: allOf: - $ref: '#/components/schemas/ApiError' - anyOf: - type: object properties: code: const: BRAND_NOT_FOUND status: const: 404 message: type: string default: Brand not found data: {} required: - code - status - message - type: object properties: code: type: string status: type: integer message: type: string data: {} required: - code - status - message required: - error BrandsEdit409ErrorResponse: type: object properties: error: allOf: - $ref: '#/components/schemas/ApiError' - anyOf: - type: object properties: code: const: BRAND_SKILL_UNAVAILABLE status: const: 409 message: type: string default: Brand has no editable Skill data: {} required: - code - status - message - type: object properties: code: const: BRAND_CHANGED status: const: 409 message: type: string default: >- The active Brand Skill no longer matches the Skill this edit is based on. Inspect the Brand again and retry. data: type: object properties: activeSkillId: anyOf: - type: string format: uuid - type: 'null' required: - activeSkillId required: - code - status - message - data - type: object properties: code: const: IDEMPOTENCY_CONFLICT status: const: 409 message: type: string default: >- Idempotency-Key was already used with a different request data: {} required: - code - status - message - type: object properties: code: const: REPLACEMENT_CONFLICT status: const: 409 message: type: string default: >- The Brand Edit being replaced is no longer awaiting approval data: {} required: - code - status - message - type: object properties: code: type: string status: type: integer message: type: string data: {} required: - code - status - message required: - error BrandsEdit429ErrorResponse: type: object properties: error: allOf: - $ref: '#/components/schemas/ApiError' - anyOf: - type: object properties: code: const: TOO_MANY_REQUESTS status: const: 429 message: type: string default: Rate limit exceeded data: {} required: - code - status - message - type: object properties: code: type: string status: type: integer message: type: string data: {} required: - code - status - message required: - error BrandsEdit500ErrorResponse: type: object properties: error: allOf: - $ref: '#/components/schemas/ApiError' - anyOf: - type: object properties: code: const: INTERNAL_ERROR status: const: 500 message: type: string default: Failed to create Brand Edit data: {} required: - code - status - message - type: object properties: code: type: string status: type: integer message: type: string data: {} required: - code - status - message required: - error ApiError: type: object properties: code: type: string status: type: integer message: type: string data: {} required: - code - status - message securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: 'Rainbrand API key, for example `x-api-key: bloom_sk_...`.' bearer: type: http scheme: bearer description: >- Rainbrand API key (`Bearer bloom_sk_...`) or Rainbrand OAuth access token. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.