Skip to main content
Submit a screen image to ScreenScore AI for analysis. You can provide the image as a publicly accessible URL or as base64-encoded data. The API creates the analysis immediately and begins processing asynchronously — use the returned id to poll for results or configure a webhook to be notified when scoring completes.

​
Endpoint

POST https://api.screenscoreai.com/v1/analyses

​
Request parameters

​
project_id
string
required
The ID of the project to associate this analysis with. Project IDs are prefixed proj_.
​
image_url
string
A publicly accessible URL of the image to analyze. Required if image is not provided. The URL must be reachable by ScreenScore AI servers at the time of the request.
​
image
string
Base64-encoded image data. Required if image_url is not provided. Supported formats: JPEG, PNG, WebP. Maximum decoded size: 10 MB.
​
label
string
A human-readable label for this analysis, used to identify it in the dashboard and API responses. For example: "Homepage - Variant A". Maximum 200 characters.
​
criteria
object
Override the default scoring weights for this analysis. If omitted, the project’s default_criteria are used.All provided values must sum to exactly 100.
You must provide either image_url or image, but not both. If you provide both, the request will fail with a validation error.

​
Example request

curl --request POST \
  --url https://api.screenscoreai.com/v1/analyses \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "project_id": "proj_01hx4k2m9fvbzq3rcw7ndj6e5t",
    "image_url": "https://example.com/screens/homepage-v2.png",
    "label": "Homepage - Variant B",
    "criteria": {
      "visual_clarity": 25,
      "visual_hierarchy": 25,
      "color_contrast": 20,
      "cta_effectiveness": 20,
      "brand_consistency": 10
    }
  }'

​
Response

The endpoint returns an analysis object with status: "pending". Scoring runs asynchronously — the score, breakdown, and feedback fields are null until the analysis reaches status: "completed".
​
id
string
required
Unique identifier for this analysis, prefixed ana_.
​
project_id
string
required
The ID of the project this analysis belongs to.
​
status
string
required
Current processing status. One of pending, processing, completed, or failed.
​
image_url
string
The URL of the image that was analyzed. null if the image was submitted as base64 data.
​
label
string
The label provided at creation time. null if no label was supplied.
​
score
number
Overall score from 0 to 100. null until status is completed.
​
breakdown
object
Per-criterion scores. null until status is completed.
​
feedback
string[]
List of actionable suggestions generated by the AI. null until status is completed.
​
error_message
string
Human-readable description of what went wrong. Populated only when status is failed, otherwise null.
​
created_at
string
required
ISO 8601 timestamp of when the analysis was created.
​
completed_at
string
ISO 8601 timestamp of when scoring finished. null until status is completed or failed.

​
Example response

{
  "id": "ana_09jz7p3nqwec1x5vbr4mt8ks2d",
  "project_id": "proj_01hx4k2m9fvbzq3rcw7ndj6e5t",
  "status": "pending",
  "image_url": "https://example.com/screens/homepage-v2.png",
  "label": "Homepage - Variant B",
  "score": null,
  "breakdown": null,
  "feedback": null,
  "error_message": null,
  "created_at": "2026-04-16T10:23:45Z",
  "completed_at": null
}