Free score
MCP server and CLI Agent setup Support

API reference

Products

Products represent your catalog items. Use these endpoints to list, create, update, sync from Shopify, and request AI optimizations.

The product model

The product model contains core catalog data, readiness scoring, and references to optimizations.

Field Type Description
id string
shopify_id integer
title string
handle string
status string
vendor string
product_type string
readiness_score integer
readiness_grade string
optimization_status string
pending_optimizations_count integer
primary_image_url string
last_synced_at string
created_at string
updated_at string
description string
meta_title string
meta_description string
og_title string AI-optimized Open Graph title for social media previews
og_description string AI-optimized Open Graph description for social media previews
tags string
options object[]
images image[]
price_min number
latest_optimization optimization_summary
score_history score_history_summary[]
GET /v1/products

List all products

Returns a paginated list of products for the authenticated account

Optional parameters

Parameter Type Description
page integer Default 1.
per_page integer Default 25. Max 100.
status string One of active, draft, archived.
min_score integer Max 100.
max_score integer Max 100.
grade string One of excellent, good, fair, poor, critical.
needs_optimization boolean
q string Search by title
Request GET /v1/products 
curl -G \
  https://beaconed.ai/api/v1/products \
  -H "Authorization: Bearer {token}"
Response 
{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "shopify_id": 7982561779890,
      "title": "Organic Cotton T-Shirt",
      "status": "active",
      "readiness_score": 85,
      "grade": "B",
      "optimized_at": "2026-03-15T14:30:00Z",
      "created_at": "2026-03-01T10:00:00Z"
    }
  ]
}
POST /v1/products

Create a product

Create a product from external data (non-Shopify). Use external_id for idempotency.

Optional attributes

Attribute Type Description
title string Product title
description string Full product description (HTML supported)
handle string URL-safe product handle
status string
vendor string Brand or manufacturer name
product_type string Product category
meta_title string SEO meta title (shown in search results)
meta_description string SEO meta description (shown in search results)
og_title string Open Graph title for social media previews
og_description string Open Graph description for social media previews
tags string Comma-separated product tags
external_id string Your system's product ID. Used for idempotency on create.
images object[]
Request POST /v1/products 
curl -X POST \
  https://beaconed.ai/api/v1/products \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"product": {"title": "New Product", "shopify_id": 123456}}'
GET /v1/products/{id}

Get a product

Returns detailed information about a specific product

Request GET /v1/products/{id} 
curl https://beaconed.ai/api/v1/products/{id} \
  -H "Authorization: Bearer {token}"
PATCH /v1/products/{id}

Update a product

Update a product's fields. Only include fields you want to change.

Optional attributes

Attribute Type Description
title string Product title
description string Full product description (HTML supported)
handle string URL-safe product handle
status string
vendor string Brand or manufacturer name
product_type string Product category
meta_title string SEO meta title (shown in search results)
meta_description string SEO meta description (shown in search results)
og_title string Open Graph title for social media previews
og_description string Open Graph description for social media previews
tags string Comma-separated product tags
external_id string Your system's product ID. Used for idempotency on create.
images object[]
Request PATCH /v1/products/{id} 
curl -X PATCH \
  https://beaconed.ai/api/v1/products/{id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"product": {"tags": "organic,cotton,sustainable"}}'
POST /v1/products/{product_id}/sync

Sync a product

Triggers a sync of the product from Shopify

Request POST /v1/products/{product_id}/sync 
curl -X POST \
  https://beaconed.ai/api/v1/products/{product_id}/sync \
  -H "Authorization: Bearer {token}"
POST /v1/products/{product_id}/optimization

Request optimization

Queue AI optimization for one or more fields on a product. Each field generates a separate Optimization record with suggested content. Poll GET /api/v1/optimizations?product_id={product_id}&status=pending to retrieve results.

Optional attributes

Attribute Type Description
fields string[] Fields to optimize. Defaults to all fields if omitted.
Request POST /v1/products/{product_id}/optimization 
curl -X POST \
  https://beaconed.ai/api/v1/products/{product_id}/optimization \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"fields": ["title", "description"]}'
Response 
{
  "success": true,
  "data": {
    "id": "opt-uuid-here",
    "product_id": "a1b2c3d4-...",
    "fields": ["title", "description"],
    "status": "queued",
    "created_at": "2026-03-31T10:00:00Z"
  }
}