API reference

Scores

Scores measure how well a product is structured for AI shopping agents. Each score breaks down into category-level assessments across title, description, images, and metadata.

The score model

The score model contains an overall composite score and per-category scores for title, description, images, and metadata.

Field	Type	Description
id	string
overall_score	integer
grade	string
score_change	integer
scored_at	string
created_at	string
product_id	string
category_scores	object
recommendations	string[]
lowest_categories	object[]
potential_improvement	number
improved	boolean

GET /v1/products/{product_id}/scores

List scores

Returns the score history for a product

Optional parameters

Parameter	Type	Description
page	integer
per_page	integer
since	string
until	string
grade	string

Request GET /v1/products/{product_id}/scores

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

GET /v1/products/{product_id}/scores/latest

Get latest score

Returns the latest score for a product

Request GET /v1/products/{product_id}/scores/latest

curl https://beaconed.ai/api/v1/products/{product_id}/scores/latest \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "data": {
    "id": "score-uuid",
    "product_id": "a1b2c3d4-...",
    "overall_score": 72,
    "grade": "C",
    "category_scores": {
      "title": {"score": 85, "weight": 0.2},
      "description": {"score": 60, "weight": 0.25},
      "images": {"score": 70, "weight": 0.2},
      "metadata": {"score": 55, "weight": 0.15}
    },
    "recommendations": [
      "Add meta description with primary keywords",
      "Include alt text for all product images"
    ],
    "created_at": "2026-03-31T10:00:00Z"
  }
}

POST /v1/products/{product_id}/scores/calculation

Calculate score

Recalculates the readiness score for a product

Request POST /v1/products/{product_id}/scores/calculation

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