--- title: "Score" method: POST path: "/v1/score/{model}" tags: ["score"] --- # Score `POST /v1/score/{model}` Score items against a query using a reranker model. Supports both msgpack and JSON request bodies (Content-Type header). Returns msgpack by default, JSON if Accept header requests it. Args: model: Model name to use for scoring. http_request: FastAPI request object (for body and app state). accept: Accept header for response content negotiation. x_machine_profile: Machine profile header for routing validation. Returns: ScoreResponse with scores sorted by relevance (descending). Format depends on Accept header: msgpack (default) or JSON. Raises: HTTPException: 400 for invalid input or profile mismatch, 404 if model not found, 503 if not loaded. ## Path parameters - `model` string, required ## Headers - `accept` string, nullable - `X-SIE-MACHINE-PROFILE` string, nullable ## Request body - ScoreRequestModel — Request body for score endpoint. - `query` ItemModel, required — A single item to encode. - `id` string, nullable — Optional identifier for this item. Returned in response. - `text` string, nullable — Text content to encode - `images` ImageInputModel[], nullable — Images for multimodal models - `data` string, byte, required — Image data. Base64-encoded on the JSON path; native binary on the msgpack path. - `format` string, nullable — Image format hint: 'jpeg', 'png', etc. - `audio` AudioInputModel — Audio input for audio models. - `data` string, byte, required — Audio data. Base64-encoded on the JSON path; native binary on the msgpack path. - `format` string, nullable — Audio format: 'wav', 'mp3', etc. - `sample_rate` integer, nullable — Sample rate in Hz. Must be positive. - `video` VideoInputModel — Video input for video models. - `data` string, byte, required — Video data. Base64-encoded on the JSON path; native binary on the msgpack path. - `format` string, nullable — Video format: 'mp4', 'webm', etc. - `document` DocumentInputModel — Document input for composite-document extractors (PDF, DOCX, HTML, ...). - `data` string, byte, required — Document bytes (raw file content). Base64-encoded on the JSON path; native binary on the msgpack path. - `format` string, nullable — Document format hint: 'pdf', 'docx', 'html', etc. - `metadata` object, nullable — Arbitrary metadata. Returned in response. - `items` ItemModel[], required — Items to score - `id` string, nullable — Optional identifier for this item. Returned in response. - `text` string, nullable — Text content to encode - `images` ImageInputModel[], nullable — Images for multimodal models - `data` string, byte, required — Image data. Base64-encoded on the JSON path; native binary on the msgpack path. - `format` string, nullable — Image format hint: 'jpeg', 'png', etc. - `audio` AudioInputModel — Audio input for audio models. - `data` string, byte, required — Audio data. Base64-encoded on the JSON path; native binary on the msgpack path. - `format` string, nullable — Audio format: 'wav', 'mp3', etc. - `sample_rate` integer, nullable — Sample rate in Hz. Must be positive. - `video` VideoInputModel — Video input for video models. - `data` string, byte, required — Video data. Base64-encoded on the JSON path; native binary on the msgpack path. - `format` string, nullable — Video format: 'mp4', 'webm', etc. - `document` DocumentInputModel — Document input for composite-document extractors (PDF, DOCX, HTML, ...). - `data` string, byte, required — Document bytes (raw file content). Base64-encoded on the JSON path; native binary on the msgpack path. - `format` string, nullable — Document format hint: 'pdf', 'docx', 'html', etc. - `metadata` object, nullable — Arbitrary metadata. Returned in response. - `instruction` string, nullable — Optional scoring instruction ## Response `200` Scores computed successfully - ScoreResponseModel — Response from score endpoint. - `model` string, required — Model used for scoring - `query_id` string, nullable — Query ID (if provided) - `scores` ScoreEntryModel[], required — Scores sorted by relevance (descending) - `item_id` string, required — Item ID - `score` number, required — Relevance score - `rank` integer, required — Rank (0 = most relevant) - `usage` ScoreUsageModel — Authoritative worker-emitted score usage. - `input_tokens` integer, required — Post-truncation input tokens processed - `images` integer, nullable — Images processed across query-document pairs ## Other responses - `400` — Invalid request - `404` — Model not found - `422` — Validation Error - `502` — Terminal model-load failure (MODEL_LOAD_FAILED). Carried in the ``detail`` envelope: ``{code, message, error_class, permanent, attempts}``. No ``Retry-After`` header — clients MUST NOT auto-retry. - `503` — Model not loaded or service unavailable ## Changes > 43 revisions in range; 2 could not be searched. - **2026-07-22** `872f29afcb07` — 4 breaking, 21 info - the `items/items/` request property type/format changed from ``/`` to `object`/`` (media type: application/json) - the `items/items/` request property type/format changed from ``/`` to `object`/`` (media type: application/msgpack) - the `query` request property type/format changed from ``/`` to `object`/`` (media type: application/json) - the `query` request property type/format changed from ``/`` to `object`/`` (media type: application/msgpack) - …21 more - **2026-04-29** `7a3933f67211` — 1 info - added the non-success response with the status `502` - **2026-04-29** `62c36304882b` — 1 info - removed the non-success response with the status `502` [Change history](https://skmtc.dev/superlinked/apis/sie-server/changes/v1/score/:model/post.md) --- [API](https://skmtc.dev/superlinked/apis/sie-server.md) · [All operations](https://skmtc.dev/superlinked/apis/sie-server/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/superlinked/sie-server/revisions/26ac644915a4/schema)