> ## 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. # Request a brief > Prepare brand guidance and selected assets for a task. Retrieve the result by ID when ready. ## OpenAPI ````yaml https://www.trybloom.ai/api/v1/spec.json post /briefs 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: Uploads description: >- Stage private local files for Brand sources, Library images, 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: Images description: Generate, edit, and retrieve images. - 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: Generate images, video, audio, and SVG, then retrieve the results. - name: Reviews description: >- Check an asset against a brand's color, typography, logo, and copy guidance. paths: /briefs: post: tags: - Briefs summary: Request a brief description: >- Prepare brand guidance and selected assets for a task. Retrieve the result by ID when ready. operationId: briefs.create parameters: - name: idempotency-key in: header schema: type: string minLength: 1 maxLength: 255 description: >- Optional key for safely retrying this request. Reuse it only with the same body. requestBody: required: true content: application/json: schema: type: object properties: brandSessionId: type: string format: uuid description: Brand to prepare the brief from. task: type: string minLength: 1 maxLength: 4000 description: What you are about to make, in plain language. required: - brandSessionId - task additionalProperties: false examples: - brandSessionId: e6220a5e-4a68-4d39-8bb9-5105e9a3a164 task: An investor slide deck about the Q3 launch and EU expansion. responses: '202': description: OK content: application/json: schema: type: object properties: data: type: object properties: id: type: string format: uuid description: Brief ID. status: enum: - pending - processing - completed - failed type: string required: - id - status required: - data '401': description: '401' content: application/json: schema: $ref: '#/components/schemas/BriefsCreate401ErrorResponse' '403': description: '403' content: application/json: schema: $ref: '#/components/schemas/BriefsCreate403ErrorResponse' '404': description: '404' content: application/json: schema: $ref: '#/components/schemas/BriefsCreate404ErrorResponse' '409': description: '409' content: application/json: schema: $ref: '#/components/schemas/BriefsCreate409ErrorResponse' '429': description: '429' content: application/json: schema: $ref: '#/components/schemas/BriefsCreate429ErrorResponse' 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/BriefsCreate500ErrorResponse' components: schemas: BriefsCreate401ErrorResponse: 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 BriefsCreate403ErrorResponse: 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: const: BETA_ACCESS_REQUIRED status: const: 403 message: type: string default: >- Briefs are in private beta and aren't enabled for this account. To request access, contact support@trybloom.ai. data: {} required: - code - status - message - type: object properties: code: type: string status: type: integer message: type: string data: {} required: - code - status - message required: - error BriefsCreate404ErrorResponse: 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 BriefsCreate409ErrorResponse: 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: This brand is not ready for briefs yet data: {} required: - code - status - message - 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: type: string status: type: integer message: type: string data: {} required: - code - status - message required: - error BriefsCreate429ErrorResponse: 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: const: ACTIVE_BRIEF_LIMIT_REACHED status: const: 429 message: type: string default: Too many briefs are already running data: {} required: - code - status - message - type: object properties: code: type: string status: type: integer message: type: string data: {} required: - code - status - message required: - error BriefsCreate500ErrorResponse: 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 brief 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.