Score a prompt

POST

https://api.smallest.ai/atoms/v1/prompt-scoring/score

POST

/atoms/v1/prompt-scoring/score

import requests
url = "https://api.smallest.ai/atoms/v1/prompt-scoring/score"
payload = { "versionId": "6a1589b75e048394eb37bc47" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

{
  "status": true,
  "data": {
    "overall_score": 56,
    "overall_grade": "Needs Work",
    "band": "lean",
    "estimated_ttft_overhead_ms": 12.9,
    "dimensions": [
      {
        "tier": 1,
        "level": "Adequate",
        "evidence_span": "You are a friendly and helpful weather assistant. Your role is to provide accurate, real-time weather information to users.",
        "title": "Clear but basic role definition",
        "description": "The role is clearly defined but lacks specific success criteria or scope boundaries."
      },
      {
        "tier": 1,
        "level": "Weak",
        "evidence_span": "Use the get_weather function to fetch real-time data",
        "title": "Undeclared tool reference",
        "description": "The 'get_weather' tool is referenced but not defined, and failure paths are missing."
      },
      {
        "tier": 2,
        "level": "Missing",
        "evidence_span": "no relevant content found",
        "title": "No failure mode coverage",
        "description": "The prompt contains no instructions for handling errors, tool failures, or unclear user input."
      }
    ]
  }
}

Scores an agent’s prompt across 11 quality dimensions using Gemini-based analysis. Requires the prompt to have changed since the last scoring.

Input: Provide exactly one of versionId (published agent version) or draftId (agent draft). Providing both or neither returns a 400.

Credit usage: 1 credit is deducted per successful call.

Idempotency: Re-submitting the same prompt without changes returns a 400 — retrieve the cached score via the GET agent endpoint instead.

Supported agent types: Only single_prompt agents are supported. Workflow-graph agents return a 400.

Scoring model: Two sequential Gemini calls — a Platform Analyst pass followed by a Rubric Judge pass.

Scored Dimensions

Tier	Dimension	Notes
1	Role & Objective
1	Personality & Voice
1	Conversation Structure
1	Tool Integration
1	Constraints & Safety
2	Conversational Naturalness
2	Failure-Mode Coverage
3	Information Integrity	Gating — if Weak/Missing, score capped at 70
3	Variable & Tool Hygiene	Gating — if Weak/Missing, score capped at 50
3	Internal Consistency
3	Density	Computed from token analysis

Authentication

AuthorizationBearer

API key from the console ApiKey collection, sent as Bearer token. Also accepts session cookies for browser-based auth.

Request

This endpoint expects an object.

objectRequired

Response

Prompt scored successfully

statusbooleanOptional

dataobjectOptional

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

429

Too Many Requests Error

500

Internal Server Error