> ## Documentation Index > Fetch the complete documentation index at: https://docs.scorecard.io/llms.txt > Use this file to discover all available pages before exploring further. # Upsert Score > 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. ## OpenAPI ````yaml put /records/{recordId}/scores/{metricConfigId} openapi: 3.1.0 info: title: Scorecard API description: REST API for Scorecard version: 1.0.0 servers: - url: https://api2.scorecard.io/api/v2 security: - ApiKeyAuth: [] paths: /records/{recordId}/scores/{metricConfigId}: put: 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. operationId: upsertScore 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'; const client = new Scorecard({ apiKey: 'My API Key', }); const score = await client.scores.upsert('a1b2c3d4-e5f6-7890-1234-567890abcdef', { recordId: '777', score: { value: true, reasoning: 'The response is correct' }, }); console.log(score.validationErrors); - lang: Python source: |- from scorecard_ai import Scorecard client = Scorecard( api_key="My API Key", ) score = client.scores.upsert( metric_config_id="a1b2c3d4-e5f6-7890-1234-567890abcdef", record_id="777", score={ "value": True, "reasoning": "The response is correct", }, ) print(score.validation_errors) - lang: cURL source: >- curl https://api2.scorecard.io/api/v2/records/$RECORD_ID/scores/$METRIC_CONFIG_ID \ -X PUT \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $SCORECARD_API_KEY" \ -d '{ "score": { "value": "bar", "reasoning": "bar" } }' components: schemas: 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. 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. responses: 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. 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. securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: starts with ak_ ````