API reference

Optimizations

Optimizations are AI-generated improvements to product content. Each optimization follows a lifecycle: pending, approved or rejected, then applied or reverted.

The optimization model

The optimization model contains the AI-generated content suggestions, their status in the approval workflow, and the rationale behind each change.

Field	Type	Description
id	string
product_id	string
product_title	string
field	string
status	string
score_before	integer
score_after	integer
approved_at	string
applied_at	string
reverted_at	string
created_at	string
updated_at	string
original_content	string
optimized_content	string
rejection_reason	string
shopify_error	string
image_shopify_id	integer
approved_by_name	string

Optimizations follow a strict status machine: pending → approved → applied or pending → rejected. Applied optimizations can be reverted.

GET /v1/optimizations

List optimizations

Returns a paginated list of optimizations

Optional parameters

Parameter	Type	Description
page	integer
per_page	integer
status	string	One of `pending`, `approved`, `rejected`, `applied`, `reverted`.
field	string	One of `title`, `description`, `alt_text`, `meta_title`, `meta_description`, `tags`, `product_type`, `og_title`, `og_description`.
product_id	string
since	string

Request GET /v1/optimizations

curl -G \
  https://beaconed.ai/api/v1/optimizations \
  -H "Authorization: Bearer {token}"

GET /v1/optimizations/{id}

Get an optimization

Returns detailed information about an optimization

Request GET /v1/optimizations/{id}

curl https://beaconed.ai/api/v1/optimizations/{id} \
  -H "Authorization: Bearer {token}"

POST /v1/optimizations/{id}/approval

Approve an optimization

Approves a pending optimization

Request POST /v1/optimizations/{id}/approval

curl -X POST \
  https://beaconed.ai/api/v1/optimizations/{id}/approval \
  -H "Authorization: Bearer {token}"

POST /v1/optimizations/{id}/rejection

Reject an optimization

Rejects a pending optimization

Optional attributes

Attribute	Type	Description
reason	string	Reason for rejection

Request POST /v1/optimizations/{id}/rejection

curl -X POST \
  https://beaconed.ai/api/v1/optimizations/{id}/rejection \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Content does not match brand voice"}'

POST /v1/optimizations/{id}/application

Apply an optimization

Pushes an approved optimization to Shopify

Request POST /v1/optimizations/{id}/application

curl -X POST \
  https://beaconed.ai/api/v1/optimizations/{id}/application \
  -H "Authorization: Bearer {token}"

POST /v1/optimizations/{id}/reversion

Revert an optimization

Reverts an applied optimization back to original content

Request POST /v1/optimizations/{id}/reversion

curl -X POST \
  https://beaconed.ai/api/v1/optimizations/{id}/reversion \
  -H "Authorization: Bearer {token}"