OpenAPI Specification
openapi: 3.1.1
info:
title: Bloom Account Images API
version: 1.0.0
description: Inspect the authenticated account — profile, credit balance, and accessible workspaces.
servers:
- url: https://www.trybloom.ai/api/v1
security:
- apiKey: []
- bearer: []
tags:
- name: Images
description: Generate, edit, and retrieve images.
paths:
/images:
get:
operationId: images.list
summary: List images
description: List images scoped to a brand or across all brands, with cursor-based pagination. Supports filtering by status and action type. Returns short redirect URLs (/img/{id}) for completed images by default. When `ids` is provided, pass `wait=true` to hold the connection until every referenced image reaches a terminal status (use this to collect results from a fire-and-forget batch of generations).
tags:
- Images
parameters:
- name: ids
in: query
schema:
type: string
description: Comma-separated image IDs to filter by (max 50). Returns only the specified images.
allowEmptyValue: true
allowReserved: true
- name: workspaceId
in: query
schema:
type: string
minLength: 1
description: Team workspace ID. Scopes results to that workspace. Omit to list across every workspace the caller can see.
allowEmptyValue: true
allowReserved: true
- name: brandSessionId
in: query
schema:
type: string
format: uuid
description: Brand session ID (from GET /brands). Omit to list images across all brands.
allowEmptyValue: true
allowReserved: true
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 50
description: Results per page (1–100, default 50)
allowEmptyValue: true
allowReserved: true
- name: cursor
in: query
schema:
type: string
description: Pagination cursor from a previous response's nextCursor
allowEmptyValue: true
allowReserved: true
- name: source
in: query
schema:
enum:
- generated
- uploaded
- scraped
description: Filter by image source. "generated" = AI-created, "uploaded" = user uploads, "scraped" = website images from brand onboarding
style: deepObject
explode: true
allowEmptyValue: true
allowReserved: true
- name: status
in: query
schema:
enum:
- pending
- generating
- completed
- failed
description: Filter by generation status (only applies to generated images — uploaded/scraped images are excluded when this filter is active)
style: deepObject
explode: true
allowEmptyValue: true
allowReserved: true
- name: actionType
in: query
schema:
enum:
- generation
- edit
- resize
- variant
- recreate
- remove-background
- vectorize
description: Filter by action type (only applies to generated images — uploaded/scraped images are excluded when this filter is active)
style: deepObject
explode: true
allowEmptyValue: true
allowReserved: true
- name: includeUrls
in: query
schema:
anyOf:
- type: boolean
- enum:
- '0'
- '1'
- 'true'
- 'false'
description: Include signed download URLs for completed images
style: deepObject
explode: true
allowEmptyValue: true
allowReserved: true
- name: wait
in: query
schema:
anyOf:
- type: boolean
- enum:
- '0'
- '1'
- 'true'
- 'false'
default: false
description: Hold the connection until every image referenced by `ids` reaches a terminal status. No-op when `ids` is omitted.
style: deepObject
explode: true
allowEmptyValue: true
allowReserved: true
- name: timeout
in: query
schema:
type: integer
minimum: 1
maximum: 295
default: 120
description: Max seconds to wait (default 120, max 295)
allowEmptyValue: true
allowReserved: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
images:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
source:
enum:
- generated
- uploaded
- scraped
brandSessionId:
type: string
format: uuid
prompt:
anyOf:
- type: string
- type: 'null'
description:
anyOf:
- type: string
- type: 'null'
aspectRatio:
anyOf:
- enum:
- '1:1'
- '2:3'
- '3:2'
- '3:4'
- '4:3'
- '4:5'
- '5:4'
- '9:16'
- '16:9'
- '21:9'
- type: 'null'
width:
anyOf:
- type: number
- type: 'null'
height:
anyOf:
- type: number
- type: 'null'
actionType:
anyOf:
- enum:
- generation
- edit
- resize
- variant
- recreate
- remove-background
- vectorize
- type: 'null'
variantGroupId:
anyOf:
- type: string
format: uuid
- type: 'null'
status:
anyOf:
- enum:
- pending
- generating
- completed
- failed
- type: 'null'
failureReason:
anyOf:
- enum:
- content_safety
- rate_limited
- type: 'null'
imageUrl:
anyOf:
- type: string
- type: 'null'
workspaceId:
anyOf:
- type: string
- type: 'null'
workspaceName:
type: string
createdAt:
type: string
format: date-time
x-native-type: date
required:
- id
- source
- prompt
- description
- aspectRatio
- width
- height
- actionType
- variantGroupId
- status
- failureReason
- workspaceId
- workspaceName
- createdAt
nextCursor:
anyOf:
- type: string
- type: 'null'
hasMore:
type: boolean
required:
- images
- nextCursor
- hasMore
required:
- data
'401':
description: '401'
content:
application/json:
schema:
oneOf:
- type: object
properties:
defined:
const: true
code:
const: UNAUTHORIZED
status:
const: 401
message:
type: string
default: Invalid or missing API credentials
data: {}
required:
- defined
- code
- status
- message
- type: object
properties:
defined:
const: false
code:
type: string
status:
type: number
message:
type: string
data: {}
required:
- defined
- code
- status
- message
'403':
description: '403'
content:
application/json:
schema:
oneOf:
- type: object
properties:
defined:
const: true
code:
const: FORBIDDEN
status:
const: 403
message:
type: string
default: Plan upgrade required
data: {}
required:
- defined
- code
- status
- message
- type: object
properties:
defined:
const: false
code:
type: string
status:
type: number
message:
type: string
data: {}
required:
- defined
- code
- status
- message
'422':
description: '422'
content:
application/json:
schema:
oneOf:
- type: object
properties:
defined:
const: true
code:
const: BRAND_NOT_FOUND
status:
const: 422
message:
type: string
default: Brand session not found
data: {}
required:
- defined
- code
- status
- message
- type: object
properties:
defined:
const: false
code:
type: string
status:
type: number
message:
type: string
data: {}
required:
- defined
- code
- status
- message
'429':
description: '429'
content:
application/json:
schema:
oneOf:
- type: object
properties:
defined:
const: true
code:
const: TOO_MANY_REQUESTS
status:
const: 429
message:
type: string
default: Rate limit exceeded
data: {}
required:
- defined
- code
- status
- message
- type: object
properties:
defined:
const: false
code:
type: string
status:
type: number
message:
type: string
data: {}
required:
- defined
- code
- status
- message
delete:
operationId: images.deleteMany
summary: Delete images
description: Delete up to 50 images by id in one call.
tags:
- Images
parameters:
- name: ids
in: query
required: true
schema:
type: string
description: Comma-separated image IDs to delete (1-50).
allowEmptyValue: true
allowReserved: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
deletedCount:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: How many images were deleted. May be lower than the number of ids passed — ids that aren't yours or were already deleted are skipped, not errored.
required:
- deletedCount
required:
- data
'401':
description: '401'
content:
application/json:
schema:
oneOf:
- type: object
properties:
defined:
const: true
code:
const: UNAUTHORIZED
status:
const: 401
message:
type: string
default: Invalid or missing API credentials
data: {}
required:
- defined
- code
- status
- message
- type: object
properties:
defined:
const: false
code:
type: string
status:
type: number
message:
type: string
data: {}
required:
- defined
- code
- status
- message
'403':
description: '403'
content:
application/json:
schema:
oneOf:
- type: object
properties:
defined:
const: true
code:
const: FORBIDDEN
status:
const: 403
message:
type: string
default: Plan upgrade required
data: {}
required:
- defined
- code
- status
- message
- type: object
properties:
defined:
const: false
code:
type: string
status:
type: number
message:
type: string
data: {}
required:
- defined
- code
- status
- message
'429':
description: '429'
content:
application/json:
schema:
oneOf:
- type: object
properties:
defined:
const: true
code:
const: TOO_MANY_REQUESTS
status:
const: 429
message:
type: string
default: Rate limit exceeded
data: {}
required:
- defined
- code
- status
- message
- type: object
properties:
defined:
const: false
code:
type: string
status:
type: number
message:
type: string
data: {}
required:
- defined
- code
- status
- message
/images/{id}:
get:
operationId: images.get
summary: Get an image
description: Get an image by ID. Use this to poll for generation results. When status is "completed", imageUrl contains a short redirect URL (/img/{id}). Use wait=true to hold the connection until a terminal status is reached. When status is "failed" and failureReason is "content_safety", the prompt was blocked by the provider's content filter — retry with model "standard" (more permissive) or revise the prompt.
tags:
- Images
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: Image ID — works for generated, uploaded, and scraped images
- name: wait
in: query
required: false
schema:
anyOf:
- type: boolean
- enum:
- '0'
- '1'
- 'true'
- 'false'
default: false
description: Hold the connection until the resource reaches a terminal status
style: deepObject
explode: true
allowEmptyValue: true
allowReserved: true
- name: timeout
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 295
default: 120
description: Max seconds to wait (default 120, max 295)
allowEmptyValue: true
allowReserved: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
format: uuid
source:
enum:
- generated
- uploaded
- scraped
status:
anyOf:
- enum:
- pending
- generating
- completed
- failed
- type: 'null'
failureReason:
anyOf:
- enum:
- content_safety
- rate_limited
- type: 'null'
prompt:
anyOf:
- type: string
- type: 'null'
description:
anyOf:
- type: string
- type: 'null'
imageUrl:
anyOf:
- type: string
- type: 'null'
aspectRatio:
anyOf:
- enum:
- '1:1'
- '2:3'
- '3:2'
- '3:4'
- '4:3'
- '4:5'
- '5:4'
- '9:16'
- '16:9'
- '21:9'
- type: 'null'
width:
anyOf:
- type: number
- type: 'null'
height:
anyOf:
- type: number
- type: 'null'
actionType:
anyOf:
- enum:
- generation
- edit
- resize
- variant
- recreate
- remove-background
- vectorize
- type: 'null'
variantGroupId:
anyOf:
- type: string
format: uuid
- type: 'null'
workspaceId:
anyOf:
- type: string
- type: 'null'
workspaceName:
type: string
createdAt:
type: string
format: date-time
x-native-type: date
required:
- id
- source
- status
- failureReason
- prompt
- description
- imageUrl
- aspectRatio
- width
- height
- actionType
- variantGroupId
- workspaceId
- workspaceName
- createdAt
required:
- data
'401':
description: '401'
content:
application/json:
schema:
oneOf:
- type: object
properties:
defined:
const: true
code:
const: UNAUTHORIZED
status:
const: 401
message:
type: string
default: Invalid or missing API credentials
data: {}
required:
- defined
- code
- status
- message
- type: object
properties:
defined:
const: false
code:
type: string
status:
type: number
message:
type: string
data: {}
required:
- defined
- code
- status
- message
'403':
description: '403'
content:
application/json:
schema:
oneOf:
- type: object
properties:
defined:
const: true
code:
const: FORBIDDEN
status:
const: 403
message:
type: string
default: Plan upgrade required
data: {}
required:
- defined
- code
- status
- message
- type: object
properties:
defined:
const: false
code:
type: string
status:
type: number
message:
type: string
data: {}
required:
- defined
- code
- status
- message
'404':
description: '404'
content:
application/json:
schema:
oneOf:
- type: object
properties:
defined:
const: true
code:
const: IMAGE_NOT_FOUND
status:
const: 404
message:
type: string
default: Image not found
data: {}
required:
- defined
- code
- status
- message
- type: object
properties:
defined:
const: false
code:
type: string
status:
type: number
message:
type: string
data: {}
required:
- defined
- code
- status
- message
'429':
description: '429'
content:
application/json:
schema:
oneOf:
- type: object
properties:
defined:
const: true
code:
const: TOO_MANY_REQUESTS
status:
const: 429
message:
type: string
default: Rate limit exceeded
data: {}
required:
- defined
- code
- status
- message
- type: object
properties:
defined:
const: false
code:
type: string
status:
type: number
message:
type: string
data: {}
required:
- defined
- code
- status
- message
delete:
operationId: images.delete
summary: Delete an image
description: Delete a single image by ID (generated, uploaded, or scraped). Returns the deleted image's id, source, and owning workspace. Deleting the same image twice returns 404.
tags:
- Images
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: Image ID — works for generated, uploaded, and scraped images
requestBody:
required: false
content:
application/json:
schema:
type: object
properties: {}
required: []
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
format: uuid
source:
enum:
- generated
- uploaded
- scraped
workspaceId:
anyOf:
- type: string
- type: 'null'
workspaceName:
type: string
required:
- id
- source
- workspaceId
- workspaceName
required:
- data
'401':
description: '401'
content:
application/json:
schema:
oneOf:
- type: object
properties:
defined:
const: true
code:
const: UNAUTHORIZED
status:
const: 401
message:
type: string
default: Invalid or missing API credentials
data: {}
required:
- defined
- code
- status
- message
- type: object
properties:
defined:
const: false
code:
type: string
status:
type: number
message:
type: string
data: {}
required:
- defined
- code
- status
- message
'403':
description: '403'
content:
application/json:
schema:
oneOf:
- type: object
properties:
defined:
const: true
code:
const: FORBIDDEN
status:
const: 403
message:
type: string
default: Plan upgrade required
data: {}
required:
- defined
- code
- status
- message
- type: object
properties:
defined:
const: false
code:
type: string
status:
type: number
message:
type: string
data: {}
required:
- defined
- code
- status
- message
'404':
description: '404'
content:
application/json:
schema:
oneOf:
- type: object
properties:
defi
# --- truncated at 32 KB (130 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/trybloom/refs/heads/main/openapi/trybloom-images-api-openapi.yml