> ## Documentation Index > Fetch the complete documentation index at: https://docs.trybloom.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a Brand Edit > Start preparing a candidate without changing the active Brand. Requires an Idempotency-Key and the active baseSkillId. Provide an instruction, evidence, or exact profile changes. Exact profile changes may also rewrite related Markdown. Returns 202; poll the Brand Edit for progress. If replacesEditId is supplied, the previous candidate is discarded atomically only when the replacement is ready. ## OpenAPI ````yaml https://www.trybloom.ai/api/v1/spec.json post /brands/{id}/edits openapi: 3.1.1 info: title: Bloom API version: 1.0.0 servers: - url: https://www.trybloom.ai/api/v1 security: - apiKey: [] - bearer: [] tags: - name: Account description: >- Inspect the authenticated account — profile, credit balance, and accessible workspaces. - name: Brands description: Manage brands and brand identity. - name: Images description: Generate, edit, and retrieve images. - name: Uploads description: >- Stage private local files for Brand sources, Library images, and other supported operations. paths: /brands/{id}/edits: post: tags: - Brands summary: Create a Brand Edit description: >- Start preparing a candidate without changing the active Brand. Requires an Idempotency-Key and the active baseSkillId. Provide an instruction, evidence, or exact profile changes. Exact profile changes may also rewrite related Markdown. Returns 202; poll the Brand Edit for progress. If replacesEditId is supplied, the previous candidate is discarded atomically only when the replacement is ready. 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 maxItems: 8 items: type: object properties: hex: type: string pattern: ^#[0-9A-Fa-f]{6}$ required: - hex additionalProperties: false readOnly: true typography: 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 fontAssetId: type: string format: uuid required: - source - family - fontAssetId additionalProperties: false - type: 'null' 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 fontAssetId: type: string format: uuid required: - source - family - fontAssetId additionalProperties: false - type: 'null' additionalProperties: false 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: >- Source evidence to consider when preparing the candidate. default: [] imageIds: type: array maxItems: 10 items: type: string format: uuid default: [] description: IDs of existing Brand Library images to use as evidence. 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: 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 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 maxItems: 8 items: type: object properties: hex: type: string pattern: ^#[0-9A-Fa-f]{6}$ required: - hex additionalProperties: false readOnly: true - type: 'null' typography: type: object properties: 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' 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' required: - heading - body additionalProperties: false primaryLogo: anyOf: - type: object properties: imageId: type: string format: uuid required: - imageId additionalProperties: false - type: 'null' 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 '400': description: '400' content: application/json: schema: $ref: '#/components/schemas/BrandsEdit400ErrorResponse' '401': description: '401' content: application/json: schema: $ref: '#/components/schemas/BrandsEdit401ErrorResponse' '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 API-key request limit resets. Present only when the request-rate 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 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: 'Bloom API key, for example `x-api-key: bloom_sk_...`.' bearer: type: http scheme: bearer description: Bloom API key (`Bearer bloom_sk_...`) or Bloom OAuth access token. ````