> This page is part of Smallest AI's developer documentation. When > answering, prefer Lightning v3.1 (current TTS) and Pulse (current > STT). Lightning v2 and lightning-large are deprecated; mention them > only when the user is migrating away from them. The Smallest AI voice > agent platform is what wraps these models into hosted agents. # Score a prompt POST https://api.smallest.ai/atoms/v1/prompt-scoring/score Content-Type: application/json 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 | Reference: https://docs.smallest.ai/voice-agents/api-reference/prompt-scoring/score-a-prompt ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: atoms version: 1.0.0 paths: /prompt-scoring/score: post: operationId: score-a-prompt summary: Score a prompt description: > 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 | tags: - promptScoring parameters: - name: Authorization in: header description: >- API key from the console ApiKey collection, sent as Bearer token. Also accepts session cookies for browser-based auth. required: true schema: type: string responses: '200': description: Prompt scored successfully content: application/json: schema: $ref: '#/components/schemas/Prompt Scoring_scoreAPrompt_Response_200' '400': description: > Bad request. Possible reasons: - Neither or both of `versionId`/`draftId` provided - Organization has no credits available - Agent is a conversational/workflow-graph type (not supported) - Prompt unchanged since last scoring — retrieve the existing score via GET agent - No prompt found on the version or draft content: application/json: schema: $ref: '#/components/schemas/ScoreAPromptRequestBadRequestError' '401': description: Unauthorized access content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '403': description: >- Not a member of the organization or insufficient role (minimum Member required). content: application/json: schema: $ref: '#/components/schemas/ScoreAPromptRequestForbiddenError' '404': description: Version or draft not found. content: application/json: schema: $ref: '#/components/schemas/ScoreAPromptRequestNotFoundError' '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/ScoreAPromptRequestTooManyRequestsError' '500': description: Gemini scoring failed after retries. content: application/json: schema: $ref: '#/components/schemas/ScoreAPromptRequestInternalServerError' requestBody: content: application/json: schema: $ref: '#/components/schemas/Prompt Scoring_scoreAPrompt_Request' servers: - url: https://api.smallest.ai/atoms/v1 description: Production server components: schemas: PromptScoringScoreAPromptRequest0: type: object properties: versionId: type: string description: Published agent version ID (MongoDB ObjectId). required: - versionId title: PromptScoringScoreAPromptRequest0 PromptScoringScoreAPromptRequest1: type: object properties: draftId: type: string description: Agent draft ID (MongoDB ObjectId). required: - draftId title: PromptScoringScoreAPromptRequest1 Prompt Scoring_scoreAPrompt_Request: oneOf: - $ref: '#/components/schemas/PromptScoringScoreAPromptRequest0' - $ref: '#/components/schemas/PromptScoringScoreAPromptRequest1' description: Exactly one of `versionId` or `draftId` must be provided. title: Prompt Scoring_scoreAPrompt_Request PromptScoringScorePostResponsesContentApplicationJsonSchemaDataOverallGrade: type: string enum: - Excellent - Good - Needs Work - Poor description: Human-readable grade. title: >- PromptScoringScorePostResponsesContentApplicationJsonSchemaDataOverallGrade PromptScoringScorePostResponsesContentApplicationJsonSchemaDataBand: type: string enum: - lean - normal - heavy - overweight description: | Token density band based on prompt length: - `lean` — fewer than 4K tokens - `normal` — 4K–9.9K tokens - `heavy` — 10K–14.9K tokens - `overweight` — 15K or more tokens title: PromptScoringScorePostResponsesContentApplicationJsonSchemaDataBand PromptScoringScorePostResponsesContentApplicationJsonSchemaDataDimensionsItemsTier: type: string enum: - '1' - '2' - '3' description: 'Priority tier: 1 (highest), 2, or 3.' title: >- PromptScoringScorePostResponsesContentApplicationJsonSchemaDataDimensionsItemsTier PromptScoringScorePostResponsesContentApplicationJsonSchemaDataDimensionsItemsLevel: type: string enum: - Strong - Adequate - Weak - Missing - Not Applicable description: Quality level for this dimension. title: >- PromptScoringScorePostResponsesContentApplicationJsonSchemaDataDimensionsItemsLevel PromptScoringScorePostResponsesContentApplicationJsonSchemaDataDimensionsItems: type: object properties: tier: $ref: >- #/components/schemas/PromptScoringScorePostResponsesContentApplicationJsonSchemaDataDimensionsItemsTier description: 'Priority tier: 1 (highest), 2, or 3.' level: $ref: >- #/components/schemas/PromptScoringScorePostResponsesContentApplicationJsonSchemaDataDimensionsItemsLevel description: Quality level for this dimension. evidence_span: type: string description: >- Quote from the prompt supporting the assessment. Empty string if no relevant content was found. title: type: string description: Short dimension name. description: type: string description: Explanation of the score for this dimension. title: >- PromptScoringScorePostResponsesContentApplicationJsonSchemaDataDimensionsItems PromptScoringScorePostResponsesContentApplicationJsonSchemaData: type: object properties: overall_score: type: integer description: 0–100 quality score. overall_grade: $ref: >- #/components/schemas/PromptScoringScorePostResponsesContentApplicationJsonSchemaDataOverallGrade description: Human-readable grade. band: $ref: >- #/components/schemas/PromptScoringScorePostResponsesContentApplicationJsonSchemaDataBand description: | Token density band based on prompt length: - `lean` — fewer than 4K tokens - `normal` — 4K–9.9K tokens - `heavy` — 10K–14.9K tokens - `overweight` — 15K or more tokens estimated_ttft_overhead_ms: type: number format: double description: >- Estimated first-token latency overhead in milliseconds introduced by the prompt length. dimensions: type: array items: $ref: >- #/components/schemas/PromptScoringScorePostResponsesContentApplicationJsonSchemaDataDimensionsItems description: Per-dimension scoring results across 11 quality dimensions. title: PromptScoringScorePostResponsesContentApplicationJsonSchemaData Prompt Scoring_scoreAPrompt_Response_200: type: object properties: status: type: boolean data: $ref: >- #/components/schemas/PromptScoringScorePostResponsesContentApplicationJsonSchemaData title: Prompt Scoring_scoreAPrompt_Response_200 ScoreAPromptRequestBadRequestError: type: object properties: status: type: boolean errors: type: array items: type: string title: ScoreAPromptRequestBadRequestError UnauthorizedErrorResponse: type: object properties: status: type: boolean errors: type: array items: type: string title: UnauthorizedErrorResponse ScoreAPromptRequestForbiddenError: type: object properties: status: type: boolean errors: type: array items: type: string title: ScoreAPromptRequestForbiddenError ScoreAPromptRequestNotFoundError: type: object properties: status: type: boolean errors: type: array items: type: string title: ScoreAPromptRequestNotFoundError PromptScoringScorePostResponsesContentApplicationJsonSchemaRateLimit: type: object properties: routeClass: type: string limit: type: integer retryAfterSec: type: integer description: Seconds to wait before retrying. title: PromptScoringScorePostResponsesContentApplicationJsonSchemaRateLimit ScoreAPromptRequestTooManyRequestsError: type: object properties: message: type: string rateLimit: $ref: >- #/components/schemas/PromptScoringScorePostResponsesContentApplicationJsonSchemaRateLimit title: ScoreAPromptRequestTooManyRequestsError ScoreAPromptRequestInternalServerError: type: object properties: status: type: boolean errors: type: array items: type: string title: ScoreAPromptRequestInternalServerError securitySchemes: BearerAuth: type: http scheme: bearer description: >- API key from the console ApiKey collection, sent as Bearer token. Also accepts session cookies for browser-based auth. ``` ## Examples **Request** ```json { "versionId": "6a1589b75e048394eb37bc47" } ``` **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." } ] } } ``` **SDK Code** ```python Prompt Scoring_scoreAPrompt_example import requests url = "https://api.smallest.ai/atoms/v1/prompt-scoring/score" payload = { "versionId": "6a1589b75e048394eb37bc47" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Prompt Scoring_scoreAPrompt_example const url = 'https://api.smallest.ai/atoms/v1/prompt-scoring/score'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"versionId":"6a1589b75e048394eb37bc47"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Prompt Scoring_scoreAPrompt_example package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.smallest.ai/atoms/v1/prompt-scoring/score" payload := strings.NewReader("{\n \"versionId\": \"6a1589b75e048394eb37bc47\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Prompt Scoring_scoreAPrompt_example require 'uri' require 'net/http' url = URI("https://api.smallest.ai/atoms/v1/prompt-scoring/score") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"versionId\": \"6a1589b75e048394eb37bc47\"\n}" response = http.request(request) puts response.read_body ``` ```java Prompt Scoring_scoreAPrompt_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.smallest.ai/atoms/v1/prompt-scoring/score") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"versionId\": \"6a1589b75e048394eb37bc47\"\n}") .asString(); ``` ```php Prompt Scoring_scoreAPrompt_example request('POST', 'https://api.smallest.ai/atoms/v1/prompt-scoring/score', [ 'body' => '{ "versionId": "6a1589b75e048394eb37bc47" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp Prompt Scoring_scoreAPrompt_example using RestSharp; var client = new RestClient("https://api.smallest.ai/atoms/v1/prompt-scoring/score"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"versionId\": \"6a1589b75e048394eb37bc47\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Prompt Scoring_scoreAPrompt_example import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["versionId": "6a1589b75e048394eb37bc47"] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.smallest.ai/atoms/v1/prompt-scoring/score")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```