Scorecard Records API
The Records API from Scorecard — 5 operation(s) for records.
OpenAPI Specification
openapi: 3.1.0
info:
title: Scorecard Metrics Records API
description: REST API for Scorecard
version: 1.0.0
servers:
- url: https://api2.scorecard.io/api/v2
security:
- ApiKeyAuth: []
tags:
- name: Records
paths:
/records/{recordId}:
delete:
operationId: deleteRecord
summary: Delete Record
description: Delete a specific Record by ID.
parameters:
- in: path
name: recordId
description: The ID of the Record to delete.
schema:
type: string
example: '777'
required: true
responses:
'200':
description: Record deleted successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
description: Whether the deletion was successful.
required:
- success
examples:
Delete Record response:
value:
success: true
summary: Delete Record success
description: Response indicating successful deletion of the Record.
'401':
$ref: '#/components/responses/UnauthenticatedError'
'500':
$ref: '#/components/responses/ServiceError'
x-codeSamples:
- lang: JavaScript
source: "import Scorecard from 'scorecard-ai';\n\nconst client = new Scorecard({\n apiKey: process.env['SCORECARD_API_KEY'], // This is the default and can be omitted\n});\n\nconst record = await client.records.delete('777');\n\nconsole.log(record.success);"
- lang: Python
source: "import os\nfrom scorecard_ai import Scorecard\n\nclient = Scorecard(\n api_key=os.environ.get(\"SCORECARD_API_KEY\"), # This is the default and can be omitted\n)\nrecord = client.records.delete(\n \"777\",\n)\nprint(record.success)"
- lang: cURL
source: "curl https://api2.scorecard.io/api/v2/records/$RECORD_ID \\\n -X DELETE \\\n -H \"Authorization: Bearer $SCORECARD_API_KEY\""
tags:
- Records
/records/{recordId}/annotations:
get:
operationId: listAnnotations
summary: List Annotations
description: List all annotations (ratings and comments) for a specific Record.
parameters:
- in: path
name: recordId
description: The ID of the Record to list annotations for.
schema:
type: string
example: '777'
required: true
responses:
'200':
description: Successfully retrieved list of Annotations for the Record.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Annotation'
required:
- data
examples:
Annotations for a record:
value:
data:
- id: '1'
recordId: '777'
spanId: null
rating: true
comment: Great response!
userId: user_abc123
createdAt: 2026-03-01 12:00:00+00:00
- id: '2'
recordId: '777'
spanId: span_xyz
rating: false
comment: This answer was incorrect for the given context.
userId: user_def456
createdAt: 2026-03-02 15:30:00+00:00
summary: Annotations for a record
description: Example response showing annotations with ratings and comments on a Record.
'401':
$ref: '#/components/responses/UnauthenticatedError'
'500':
$ref: '#/components/responses/ServiceError'
x-codeSamples:
- lang: JavaScript
source: "import Scorecard from 'scorecard-ai';\n\nconst client = new Scorecard({\n apiKey: process.env['SCORECARD_API_KEY'], // This is the default and can be omitted\n});\n\nconst annotations = await client.records.annotations.list('777');\n\nconsole.log(annotations.data);"
- lang: Python
source: "import os\nfrom scorecard_ai import Scorecard\n\nclient = Scorecard(\n api_key=os.environ.get(\"SCORECARD_API_KEY\"), # This is the default and can be omitted\n)\nannotations = client.records.annotations.list(\n \"777\",\n)\nprint(annotations.data)"
- lang: cURL
source: "curl https://api2.scorecard.io/api/v2/records/$RECORD_ID/annotations \\\n -H \"Authorization: Bearer $SCORECARD_API_KEY\""
tags:
- Records
/records/{recordId}/tags:
get:
operationId: listRecordTags
summary: List Record Tags
description: List all tags applied to a specific Record.
parameters:
- in: path
name: recordId
description: The ID of the Record to list tags for.
schema:
type: string
example: '777'
required: true
responses:
'200':
description: Successfully retrieved the Record's tags.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/RecordTag'
required:
- data
examples:
Tags for a record:
value:
data:
- id: '1'
recordId: '777'
text: urgent
source: user
userId: user_abc123
createdAt: 2026-03-01 12:00:00+00:00
- id: '2'
recordId: '777'
text: env:prod
source: otel
userId: null
createdAt: 2026-03-01 12:00:00+00:00
summary: Tags for a record
description: Example response showing user- and OTel-sourced tags on a Record.
'401':
$ref: '#/components/responses/UnauthenticatedError'
'500':
$ref: '#/components/responses/ServiceError'
x-codeSamples:
- lang: JavaScript
source: "import Scorecard from 'scorecard-ai';\n\nconst client = new Scorecard({\n apiKey: process.env['SCORECARD_API_KEY'], // This is the default and can be omitted\n});\n\nconst tags = await client.records.tags.list('777');\n\nconsole.log(tags.data);"
- lang: Python
source: "import os\nfrom scorecard_ai import Scorecard\n\nclient = Scorecard(\n api_key=os.environ.get(\"SCORECARD_API_KEY\"), # This is the default and can be omitted\n)\ntags = client.records.tags.list(\n \"777\",\n)\nprint(tags.data)"
- lang: cURL
source: "curl https://api2.scorecard.io/api/v2/records/$RECORD_ID/tags \\\n -H \"Authorization: Bearer $SCORECARD_API_KEY\""
tags:
- Records
post:
operationId: createRecordTag
summary: Create Record Tag
description: 'Apply a tag to a Record. Idempotent: re-applying an existing tag returns the existing tag.'
parameters:
- in: path
name: recordId
description: The ID of the Record to tag.
schema:
type: string
example: '777'
required: true
requestBody:
content:
application/json:
schema:
type: object
properties:
text:
type: string
description: 'The tag text to apply. Idempotent: re-applying an existing tag is a no-op.'
required:
- text
examples:
Tag a record:
value:
text: urgent
summary: Tag a record
description: Apply the `urgent` tag to a Record.
responses:
'201':
description: The created (or existing) tag.
content:
application/json:
schema:
$ref: '#/components/schemas/RecordTag'
examples:
Created tag:
value:
id: '1'
recordId: '777'
text: urgent
source: user
userId: user_abc123
createdAt: 2026-03-01 12:00:00+00:00
summary: Created tag
description: Response after successfully tagging a Record.
'401':
$ref: '#/components/responses/UnauthenticatedError'
'500':
$ref: '#/components/responses/ServiceError'
x-codeSamples:
- lang: JavaScript
source: "import Scorecard from 'scorecard-ai';\n\nconst client = new Scorecard({\n apiKey: process.env['SCORECARD_API_KEY'], // This is the default and can be omitted\n});\n\nconst recordTag = await client.records.tags.create('777', { text: 'urgent' });\n\nconsole.log(recordTag.id);"
- lang: Python
source: "import os\nfrom scorecard_ai import Scorecard\n\nclient = Scorecard(\n api_key=os.environ.get(\"SCORECARD_API_KEY\"), # This is the default and can be omitted\n)\nrecord_tag = client.records.tags.create(\n record_id=\"777\",\n text=\"urgent\",\n)\nprint(record_tag.id)"
- lang: cURL
source: "curl https://api2.scorecard.io/api/v2/records/$RECORD_ID/tags \\\n -H 'Content-Type: application/json' \\\n -H \"Authorization: Bearer $SCORECARD_API_KEY\" \\\n -d '{\n \"text\": \"urgent\"\n }'"
tags:
- Records
/records/{recordId}/tags/{text}:
delete:
operationId: deleteRecordTag
summary: Delete Record Tag
description: Remove a tag from a Record by its text.
parameters:
- in: path
name: recordId
description: The ID of the Record to remove the tag from.
schema:
type: string
example: '777'
required: true
- in: path
name: text
description: The tag text to remove.
schema:
type: string
example: urgent
required: true
responses:
'200':
description: The tag was removed (or was not present).
content:
application/json:
schema:
type: object
properties:
deleted:
type: number
description: The number of tag rows removed (0 if the tag was not present).
required:
- deleted
examples:
Deleted tag:
value:
deleted: 1
summary: Deleted tag
description: Response indicating how many tag rows were removed.
'401':
$ref: '#/components/responses/UnauthenticatedError'
'500':
$ref: '#/components/responses/ServiceError'
x-codeSamples:
- lang: JavaScript
source: "import Scorecard from 'scorecard-ai';\n\nconst client = new Scorecard({\n apiKey: process.env['SCORECARD_API_KEY'], // This is the default and can be omitted\n});\n\nconst tag = await client.records.tags.delete('urgent', { recordId: '777' });\n\nconsole.log(tag.deleted);"
- lang: Python
source: "import os\nfrom scorecard_ai import Scorecard\n\nclient = Scorecard(\n api_key=os.environ.get(\"SCORECARD_API_KEY\"), # This is the default and can be omitted\n)\ntag = client.records.tags.delete(\n text=\"urgent\",\n record_id=\"777\",\n)\nprint(tag.deleted)"
- lang: cURL
source: "curl https://api2.scorecard.io/api/v2/records/$RECORD_ID/tags/$TEXT \\\n -X DELETE \\\n -H \"Authorization: Bearer $SCORECARD_API_KEY\""
tags:
- Records
/records/{recordId}/scores/{metricConfigId}:
put:
operationId: upsertScore
summary: Upsert Score
description: Create or update a Score for a given Record and MetricConfig. If a Score with the specified Record ID and MetricConfig ID already exists, it will be updated. Otherwise, a new Score will be created. The score provided should conform to the schema defined by the MetricConfig; otherwise, validation errors will be reported.
parameters:
- in: path
name: recordId
description: The ID of the Record to upsert the Score for.
schema:
type: string
example: '777'
required: true
- in: path
name: metricConfigId
description: The ID of the MetricConfig.
schema:
type: string
format: uuid
example: a1b2c3d4-e5f6-7890-1234-567890abcdef
required: true
requestBody:
content:
application/json:
schema:
type: object
properties:
score:
type: object
additionalProperties: true
description: The score of the Record, as arbitrary JSON. This data should ideally conform to the output schema defined by the associated MetricConfig. If it doesn't, validation errors will be captured in the `validationErrors` field.
required:
- score
examples:
Upsert simple score:
value:
score:
value: true
reasoning: The response is correct
summary: Upsert a simple score
description: Creates or updates a Score with a basic score object.
Upsert complex score:
value:
score:
f1_score: 0.75
precision: 0.8
recall: 0.7
reasoning: Model performed well on typical cases.
summary: Upsert a complex score
description: Creates or updates a Score with a more detailed, structured score, potentially including multiple metrics and qualitative feedback.
Upsert score needing validation:
value:
score:
rating: excellent
summary: Upsert score that may have validation issues
description: Example of a score that might not fully conform to the metric's output schema, which would result in validationErrors in the response.
responses:
'200':
description: Score upserted successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Score'
examples:
Upserted simple score:
value:
recordId: '777'
metricConfigId: a1b2c3d4-e5f6-7890-1234-567890abcdef
score:
value: true
reasoning: The response is correct
validationErrors: []
summary: Successful simple score upsert
description: Response showing the full Score after a successful upsert with a simple score.
Upserted score with validation errors:
value:
recordId: '778'
metricConfigId: b2c3d4e5-f6a7-8901-2345-67890abcdef0
score:
rating: excellent
validationErrors:
- path: /score/rating
message: Expected number, received string
summary: Upserted score with validation errors
description: Response for a Score that was stored but whose `score` field had discrepancies with the MetricConfig's output schema, detailed in `validationErrors`.
'401':
$ref: '#/components/responses/UnauthenticatedError'
'500':
$ref: '#/components/responses/ServiceError'
x-codeSamples:
- lang: JavaScript
source: "import Scorecard from 'scorecard-ai';\n\nconst client = new Scorecard({\n apiKey: process.env['SCORECARD_API_KEY'], // This is the default and can be omitted\n});\n\nconst score = await client.scores.upsert('a1b2c3d4-e5f6-7890-1234-567890abcdef', {\n recordId: '777',\n score: { value: true, reasoning: 'The response is correct' },\n});\n\nconsole.log(score.validationErrors);"
- lang: Python
source: "import os\nfrom scorecard_ai import Scorecard\n\nclient = Scorecard(\n api_key=os.environ.get(\"SCORECARD_API_KEY\"), # This is the default and can be omitted\n)\nscore = client.scores.upsert(\n metric_config_id=\"a1b2c3d4-e5f6-7890-1234-567890abcdef\",\n record_id=\"777\",\n score={\n \"value\": True,\n \"reasoning\": \"The response is correct\",\n },\n)\nprint(score.validation_errors)"
- lang: cURL
source: "curl https://api2.scorecard.io/api/v2/records/$RECORD_ID/scores/$METRIC_CONFIG_ID \\\n -X PUT \\\n -H 'Content-Type: application/json' \\\n -H \"Authorization: Bearer $SCORECARD_API_KEY\" \\\n -d '{\n \"score\": {\n \"value\": \"bar\",\n \"reasoning\": \"bar\"\n }\n }'"
tags:
- Records
components:
responses:
ServiceError:
description: An internal service error indicating an issue with the Scorecard service.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
Internal error:
value:
code: INTERNAL_ERROR
message: An unexpected error occurred while processing your request.
details: {}
summary: Internal error
description: Generic error when an unexpected internal issue occurs.
UnauthenticatedError:
description: Error indicating that the request is not authenticated.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
Authentication failure:
value:
code: UNAUTHORIZED
message: Invalid or missing authentication token
details: {}
summary: Authentication failure
description: Error returned when authentication credentials are invalid or missing.
schemas:
Annotation:
type: object
properties:
id:
type: string
description: The ID of the Annotation.
recordId:
type: string
description: The ID of the Record this Annotation belongs to.
spanId:
type:
- string
- 'null'
description: Optional span ID linking this annotation to a specific span.
rating:
type:
- boolean
- 'null'
description: 'The rating of the annotation: true (positive), false (negative), or null (no rating).'
comment:
type:
- string
- 'null'
description: An optional text comment for the annotation.
userId:
type: string
description: The ID of the user who created the annotation.
createdAt:
type: string
description: The ISO 8601 timestamp when the annotation was created.
required:
- id
- recordId
- spanId
- rating
- comment
- userId
- createdAt
description: An annotation on a Record, containing a rating (thumbs up/down) and/or a text comment.
RecordTag:
type: object
properties:
id:
type: string
description: The ID of the tag.
recordId:
type: string
description: The ID of the Record this tag belongs to.
text:
type: string
description: The tag text. May encode key:value semantics with a colon (e.g. `env:prod`).
source:
type: string
enum:
- user
- otel
description: 'How the tag was applied: `user` (UI, SDK, or REST) or `otel` (lifted from a span attribute at ingest).'
userId:
type:
- string
- 'null'
description: The ID of the user who applied the tag; null for OTel-sourced tags.
createdAt:
type: string
description: The ISO 8601 timestamp when the tag was created.
required:
- id
- recordId
- text
- source
- userId
- createdAt
description: An arbitrary tag applied to a Record (e.g. `urgent`, `regression`, `env:prod`), either by a user or lifted from OTel span attributes at ingest.
ApiError:
type: object
properties:
code:
type: string
message:
type: string
details:
type: object
additionalProperties: true
x-stainless-any: true
required:
- code
- message
- details
description: An API error.
Score:
type: object
properties:
recordId:
type: string
description: The ID of the Record this Score is for.
metricConfigId:
type: string
format: uuid
description: The ID of the MetricConfig this Score is for.
score:
type: object
additionalProperties: true
description: The score of the Record, as arbitrary JSON. This data should ideally conform to the output schema defined by the associated MetricConfig. If it doesn't, validation errors will be captured in the `validationErrors` field.
validationErrors:
type: array
items:
type: object
properties:
path:
type: string
description: JSON Pointer to the field with the validation error.
example: /data/question
message:
type: string
description: Human-readable error description.
example: Required field missing
required:
- path
- message
description: Validation errors found in the Score data. If present, the Score doesn't fully conform to its MetricConfig's schema.
required:
- recordId
- metricConfigId
- score
description: A Score represents the evaluation of a Record against a specific MetricConfig. The actual `score` is stored as flexible JSON. While any JSON is accepted, it is expected to conform to the output schema defined by the MetricConfig. Any discrepancies will be noted in the `validationErrors` field, but the Score will still be stored.
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
bearerFormat: starts with ak_