Images
1. Overview
The Firework Image API manages a business-owned image library. It supports image ingestion, metadata and lifecycle management, folder trees, shoppable product listings, and downloadable CDN renditions.
Base URL: https://api.firework.com
Feature requirement: Every endpoint in this document requires the business subscription's
imagesfeature. A request with valid authentication and scope returns402 Payment Requiredwhen the feature is unavailable.
Images can be created from exactly one source:
An
s3_keyproduced by the image upload-signature flowA public HTTP(S)
urlfetched by FireworkInline
file_base64bytes for images up to 5 MB decoded
Supported formats are JPEG (jpg / jpeg), PNG, and WebP. Original files must be between 1 KB and 50 MB, and neither dimension may exceed 16,384 pixels.
2. Authentication
All endpoints require an OAuth 2.0 bearer token.
images:read
List/read images and folders, list images for a product, and obtain image download URLs
images:write
Create/update/delete images and folders, manage lifecycle/product listings, and create upload signatures. Includes read access
Use this header unless an endpoint says otherwise:
Authorization
✅
Bearer {ACCESS_TOKEN}
Content-Type
✅
application/json for request bodies
3. Endpoint Summary
/api/v1/images
POST
images:write
Create a library image
/api/v1/images
GET
images:read
List library images
/api/v1/images/upload_signatures
POST
images:write
Create a direct-to-S3 upload signature
/api/v1/images/{id}
GET
images:read
Get an image
/api/v1/images/{id}
PATCH
images:write
Update image metadata and product listings
/api/v1/images/{id}
DELETE
images:write
Soft-delete an image
/api/v1/images/{id}/archive
POST
images:write
Archive an image
/api/v1/images/{id}/unarchive
POST
images:write
Unarchive an image
/api/v1/images/{id}/publish
POST
images:write
Publish or schedule an image
/api/v1/images/{id}/unpublish
POST
images:write
Return an image to draft state
/api/v1/images/{id}/download
GET
images:read
Get an original or transformed download URL
/api/v1/images/{id}/products
POST
images:write
Append product listings
/api/v1/images/{id}/products/{product_id}
PATCH
images:write
Update one image-product listing
/api/v1/images/{id}/products/{product_id}
DELETE
images:write
Remove one image-product listing
/api/v1/products/{product_id}/images
GET
images:read
List published images featuring a product
/api/v1/image_folders
POST
images:write
Create an image folder
/api/v1/image_folders
GET
images:read
List one level of the folder tree
/api/v1/image_folders/{id}
GET
images:read
Get an image folder
/api/v1/image_folders/{id}
PATCH
images:write
Rename or move an image folder
/api/v1/image_folders/{id}
DELETE
images:write
Cascade soft-delete a folder subtree
/api/v1/image_folders/{id}/archive
POST
images:write
Archive a folder without changing its content
/api/v1/image_folders/{id}/unarchive
POST
images:write
Unarchive a folder
4. Object Reference
4.1. Image Object
id
string
❌
Encoded image ID
title
string
❌
Image title, maximum 255 characters
description
string
✅
Description, maximum 5,000 characters
access
string
❌
public, private, or unlisted
badge
string
✅
Optional badge; currently ad
hashtags
string[]
❌
Normalized lowercase hashtags, without automatic extraction from the title
locale
string
✅
Normalized locale
source
string
❌
social_media, aigc, or api
folder_id
string
✅
Encoded folder ID; null for an unfiled image
published_at
string
✅
ISO 8601 publish time; future values indicate a scheduled image
is_published
boolean
❌
Evaluated at request time; true when published_at is present and not in the future
archived_at
string
✅
ISO 8601 archive time
metadata
object
❌
Metadata object; currently contains nullable alt_text
url
string
✅
Full-resolution CDN URL for the original file
format
string
❌
jpg, jpeg, png, or webp
width
integer
✅
Original width in pixels
height
integer
✅
Original height in pixels
file_size
integer
✅
Original file size in bytes
blur_hash
string
✅
BlurHash placeholder when available
products
object[]
❌
Ordered image-product listings
created_at
string
❌
ISO 8601 creation time
updated_at
string
❌
ISO 8601 last-update time
Example:
4.2. Image-Product Listing
product_id
string
❌
Encoded product ID
product_unit_id
string
✅
Encoded product-unit ID for a variant-specific listing
product_sort_position
integer
❌
Product order on the image; input array order starts at 1
image_sort_position
integer
✅
Image order for reverse product lookup; null entries sort after ranked entries
image_hidden
boolean
❌
Excludes this image from the product-to-images reverse lookup when true
product_hidden
boolean
❌
Marks the product as hidden on this image
bounding_box
object
✅
Fractional product box with exactly x, y, w, and h
Each bounding-box value is relative to the image dimensions. x and y must be at least 0, w and h must be greater than 0, and both x + w and y + h must be at most 1.
4.3. Image Folder Object
id
string
❌
Encoded folder ID
name
string
❌
Folder name, maximum 255 characters
parent_folder_id
string
✅
Encoded parent-folder ID; null at the root
archived_at
string
✅
ISO 8601 archive time
has_subfolders
boolean
❌
Whether the folder has a direct undeleted child; derived for list responses
has_images
boolean
❌
Whether the folder directly contains an undeleted image; derived for list responses
created_at
string
❌
ISO 8601 creation time
updated_at
string
❌
ISO 8601 last-update time
For a folder fetched directly, has_subfolders and has_images are false; use the folder-list endpoint when those expansion hints are needed.
4.4. Pagination Envelope
Image and folder collections use cursor pagination. after and before are mutually exclusive. Treat cursor values and links.next as opaque.
links.next
string
✅
Relative URL for the next page
pagination.cursor
string
✅
Opaque cursor for the next request
pagination.has_more
boolean
❌
Whether another page is currently available
The default page_size is 10 and the maximum is 100.
5. Create Image
Creates and synchronously ingests an image.
Endpoint: POST /api/v1/images Scope: images:write
5.1. Request Body
Provide exactly one of s3_key, url, or file_base64.
title
string
✅
None
Image title, maximum 255 characters
s3_key
string
Conditional
None
Key returned by POST /api/v1/images/upload_signatures
url
string
Conditional
None
Public HTTP(S) URL ending in a supported image extension
file_base64
string
Conditional
None
Base64 bytes or an image data URI, maximum 5 MB decoded
filename
string
Conditional
None
Required for base64 without a usable data-URI media type; extension determines format
description
string
❌
null
Description, maximum 5,000 characters
access
string
❌
public
public, private, or unlisted
badge
string
❌
null
Currently ad
hashtags
string[]
❌
[]
Up to 150 normalized hashtags
locale
string
❌
Business default
Locale
source
string
❌
api
social_media, aigc, or api
published_at
string
❌
Now
ISO 8601 time up to 28 days ahead; explicit null creates a draft
folder_id
string
❌
null
Encoded folder ID; omit or set null for unfiled
metadata
object
❌
{}
Supports alt_text
products
object[]
❌
[]
Ordered product listings, maximum 100
Each products entry requires product_id and may include product_unit_id, bounding_box, image_hidden, and product_hidden. Products and units must belong to the image's business.
5.2. Response
201 Created returns the full Image Object.
5.3. Errors
400
Missing/multiple ingestion sources; malformed source or base64 input
401
Missing or invalid token
402
The business does not have the images feature
403
Missing scope, inaccessible business, or an s3_key owned by another business
404
Business, folder, or related resource not found
422
Invalid metadata/listing, unsupported format, unreadable image, invalid size/dimensions, or invalid scheduling
5.4. Examples
Create from a URL:
Create an unpublished image from base64:
6. List Images
Lists the business's images newest first.
Endpoint: GET /api/v1/images Scope: images:read
6.1. Query Parameters
business_id
string
❌
Token business
Encoded business ID; optional for app tokens
folder_id
string
❌
None
Encoded folder ID, or unfiled for images without a folder
source
string
❌
None
social_media, aigc, or api
access
string
❌
None
public, private, or unlisted
badge
string
❌
None
Badge filter, such as ad
hashtag
string
❌
None
Require this hashtag
archived
boolean
❌
false
Omitted or false returns only non-archived images; true returns only archived images
published
boolean
❌
None
Filter by current published state
after
string
❌
None
Opaque forward cursor
before
string
❌
None
Opaque backward cursor
page_size
integer
❌
10
Page size, maximum 100
6.2. Response
200 OK returns images, links, and pagination.
6.3. Errors
400 for invalid IDs/pagination, 401 for authentication, 402 for the feature gate, 403 for scope/business access, and 404 when the business is not found.
6.4. Example
7. Get, Update, and Delete an Image
7.1. Get Image
Endpoint: GET /api/v1/images/{id} Scope: images:read
id
Path
string
✅
Encoded image ID
200 OK returns the full Image object. Errors are 401, 402, 403, and 404.
7.2. Update Image
Endpoint: PATCH /api/v1/images/{id} Scope: images:write
The path parameter is the encoded image ID. The body accepts the editable fields from Create Image, excluding ingestion-only s3_key, url, file_base64, and filename. Only provided fields change.
Passing products replaces all current product listings in the supplied order; an empty array clears them. Omit products to preserve existing listings. Passing published_at: null makes the image a draft.
200 OK returns the updated Image object. Errors are 400, 401, 402, 403, 404, and 422.
7.3. Delete Image
Endpoint: DELETE /api/v1/images/{id} Scope: images:write
The path parameter is the encoded image ID. A successful request soft-deletes the image and returns 204 No Content. Errors are 401, 402, 403, and 404.
8. Direct-to-S3 Upload
Use this flow for images that should be uploaded by the client rather than fetched by Firework or embedded as base64.
8.1. Create Upload Signature
Endpoint: POST /api/v1/images/upload_signatures Scope: images:write
filename
string
✅
File name with a supported extension
content_type
string
✅
image/jpeg, image/png, or image/webp
business_id
string
❌
Encoded business ID; defaults to the app business
201 Created returns:
key
S3 object key; reuse as s3_key when creating image
post_url
S3 multipart form destination
policy
Send as Policy
signature
Send as X-Amz-Signature
date
Send as X-Amz-Date
credential
Send as X-Amz-Credential
algorithm
Send as X-Amz-Algorithm
acl
Send as acl
Errors are 400, 401, 402, 403, and 404.
8.2. Upload to S3 and Create the Image
POST the returned fields to post_url as multipart/form-data. Include a Content-Type field matching the requested content type and put the binary file part last.
Then call POST /api/v1/images with the returned key:
9. Archive and Publish Lifecycle
9.1. Archive or Unarchive
Endpoints:
POST /api/v1/images/{id}/archivePOST /api/v1/images/{id}/unarchive
Scope: images:write
The path parameter is the encoded image ID. Both endpoints take no body and return 200 OK with the full Image object. Archive populates archived_at; unarchive clears it. Errors are 401, 402, 403, and 404.
9.2. Publish or Schedule
Endpoint: POST /api/v1/images/{id}/publish Scope: images:write
Omit the body to publish immediately. To schedule, send a future ISO 8601 published_at no more than 28 days ahead. Past times and times beyond the scheduling window return 422.
200 OK returns the full Image object. Errors are 400, 401, 402, 403, 404, and 422.
9.3. Unpublish
Endpoint: POST /api/v1/images/{id}/unpublish Scope: images:write
Takes no body, clears published_at, and returns 200 OK with the full Image object. Errors are 401, 402, 403, and 404.
10. Get Image Download URL
Returns the original CDN URL or an on-demand resized/converted rendition.
Endpoint: GET /api/v1/images/{id}/download Scope: images:read
10.1. Parameters
id
Path
string
✅
Encoded image ID
max_dimension
Query
integer
❌
Fit longest side to 16–16,384 pixels; downscale only
format
Query
string
❌
Convert to jpg, jpeg, png, or webp
The two transformation parameters compose. CDN renditions are generated on demand, so the first access may require a browser-like client.
10.2. Response
download_url
string
✅
Original or transformed CDN URL
format
string
✅
Format at download_url
width
integer
✅
Width at download_url
height
integer
✅
Height at download_url
file_size
integer
✅
Original byte size; null for resized or converted renditions
Errors are 401, 402, 403, 404, and 422.
11. Manage Image-Product Listings
11.1. Append Products
Endpoint: POST /api/v1/images/{id}/products Scope: images:write
products
object[]
✅
One or more listing inputs in the order to append
Existing positions are preserved, and new positions follow them. The combined total cannot exceed 100. A (product_id, product_unit_id) pair cannot be duplicated.
200 OK returns { "products": [...] } containing the image's complete ordered listing set. Errors are 400, 401, 402, 403, 404, and 422.
11.2. Update One Listing
Endpoint: PATCH /api/v1/images/{id}/products/{product_id} Scope: images:write
id
Path
string
✅
Encoded image ID
product_id
Path
string
✅
Encoded product ID
product_unit_id
Query
string
❌
Encoded unit ID required to select a variant-specific listing
The JSON body may contain image_hidden, product_hidden, image_sort_position, or bounding_box. Set image_sort_position or bounding_box to null to clear it.
200 OK returns the updated listing. Errors are 400, 401, 402, 403, 404, and 422.
11.3. Remove One Listing
Endpoint: DELETE /api/v1/images/{id}/products/{product_id} Scope: images:write
Use the same path/query identifiers as Update One Listing. A successful request returns 204 No Content; remaining positions are not renumbered. Errors are 401, 402, 403, and 404.
11.4. List Images for a Product
Endpoint: GET /api/v1/products/{product_id}/images Scope: images:read
product_id
Path
string
✅
None
Encoded product ID
include_unpublished
Query
boolean
❌
false
Include drafts and scheduled images
after
Query
string
❌
None
Opaque forward cursor
before
Query
string
❌
None
Opaque backward cursor
page_size
Query
integer
❌
10
Page size, maximum 100
Results are ordered by image_sort_position, with unranked listings last. Deleted and archived images and listings with image_hidden: true are always excluded. By default, unpublished and scheduled images are excluded.
200 OK uses the standard image collection envelope. Errors are 400, 401, 402, 403, and 404.
12. Image Folders
Folders form a business-scoped tree with a maximum depth of 10. Names must be unique among siblings.
12.1. Create Folder
Endpoint: POST /api/v1/image_folders Scope: images:write
name
string
✅
Folder name, maximum 255 characters
parent_folder_id
string
❌
Encoded parent ID; omit for a root folder
business_id
string
❌
Encoded business ID; defaults to app business
201 Created returns the Folder object. Errors are 400, 401, 402, 403, 404, and 422.
12.2. List a Folder Level
Endpoint: GET /api/v1/image_folders Scope: images:read
business_id
string
❌
Token business
Encoded business ID
parent_folder_id
string
❌
None
Parent whose direct children to list; omit for root
include_archived
boolean
❌
false
Include archived folders
after
string
❌
None
Opaque forward cursor
before
string
❌
None
Opaque backward cursor
page_size
integer
❌
10
Page size, maximum 100
200 OK returns image_folders, links, and pagination. Errors are 400, 401, 402, 403, and 404.
12.3. Get Folder
Endpoint: GET /api/v1/image_folders/{id} Scope: images:read
The path parameter is the encoded folder ID. 200 OK returns the Folder object. Errors are 401, 402, 403, and 404.
12.4. Update Folder
Endpoint: PATCH /api/v1/image_folders/{id} Scope: images:write
name
string
❌
New folder name
parent_folder_id
string
❌
New parent; null moves the folder to the root
Only supplied fields change. Cycles, sibling-name conflicts, foreign-business parents, and moves that exceed the depth limit return 422. 200 OK returns the updated Folder object. Other errors are 400, 401, 402, 403, and 404.
12.5. Delete Folder Subtree
Endpoint: DELETE /api/v1/image_folders/{id} Scope: images:write
This is a cascade soft delete: the folder, all nested folders, and all images in the subtree are deleted in one transaction.
Unlike other delete endpoints, success returns 200 OK with counts:
Errors are 401, 402, 403, and 404.
12.6. Archive or Unarchive Folder
Endpoints:
POST /api/v1/image_folders/{id}/archivePOST /api/v1/image_folders/{id}/unarchive
Scope: images:write
Both endpoints take no body and return 200 OK with the Folder object. Folder archiving is cosmetic: it does not archive, unpublish, move, or delete images or subfolders. Errors are 401, 402, 403, and 404.
13. Error Format
Errors use the shared public API JSON shape:
Validation errors may include a structured errors object when produced by a resource changeset.
Last updated
Was this helpful?