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.

Properties

  • Name
    id
    Type
    string
    Description
  • Name
    overall_score
    Type
    integer
    Description
  • Name
    grade
    Type
    string
    Description
  • Name
    score_change
    Type
    integer
    Description
  • Name
    scored_at
    Type
    string
    Description
  • Name
    created_at
    Type
    string
    Description
  • Name
    product_id
    Type
    string
    Description
  • Name
    category_scores
    Type
    object
    Description
  • Name
    recommendations
    Type
    string[]
    Description
  • Name
    lowest_categories
    Type
    object[]
    Description
  • Name
    potential_improvement
    Type
    number
    Description
  • Name
    improved
    Type
    boolean
    Description
GET /v1/products/{product_id}/scores

List scores

Returns the score history for a product

Optional parameters

  • Name
    page
    Type
    integer
    Description
  • Name
    per_page
    Type
    integer
    Description
  • Name
    since
    Type
    string
    Description
  • Name
    until
    Type
    string
    Description
  • Name
    grade
    Type
    string
    Description

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}"