---
title: "Create or replace project_score"
method: PUT
path: "/v1/project_score"
tags: ["ProjectScores"]
---

# Create or replace project_score

`PUT /v1/project_score`

Create or replace project_score. If there is an existing project_score in the project with the same name as the one specified in the request, will replace the existing project_score with the provided fields

## Request body

- CreateProjectScore — A project score is a user-configured score, which can be manually-labeled through the UI
  - `project_id` string, uuid, required — Unique identifier for the project that the project score belongs under
  - `name` string, required — Name of the project score
  - `description` string, nullable — Textual description of the project score
  - `score_type` 'slider' | 'categorical' | 'weighted' | 'minimum' | 'online', required — The type of the configured score
  - `categories` union
    - ProjectScoreCategory[] — For categorical-type project scores, the list of all categories
      - `name` string, required — Name of the category
      - `value` number, required — Numerical value of the category. Must be between 0 and 1, inclusive
    - object — For weighted-type project scores, the weights of each score
    - string[] — For minimum-type project scores, the list of included scores
    - object, nullable
  - `config` ProjectScoreConfig, nullable
    - `multi_select` boolean, nullable
    - `destination` 'expected' | 'null', nullable
    - `online` OnlineScoreConfig, nullable
      - `sampling_rate` number, required — The sampling rate for online scoring
      - `scorers` SavedFunctionId[], required — The list of scorers to use for online scoring
        - union
          - object
            - `type` 'function', required
            - `id` string, required
          - object
            - `type` 'global', required
            - `name` string, required
      - `apply_to_root_span` boolean, nullable — Whether to trigger online scoring on the root span of each trace
      - `apply_to_span_names` string[], nullable — Trigger online scoring on any spans with a name in this list

## Response `200`

Returns the new project_score object

- ProjectScore — A project score is a user-configured score, which can be manually-labeled through the UI
  - `id` string, uuid, required — Unique identifier for the project score
  - `project_id` string, uuid, required — Unique identifier for the project that the project score belongs under
  - `user_id` string, uuid, required
  - `created` string, date-time, nullable — Date of project score creation
  - `name` string, required — Name of the project score
  - `description` string, nullable — Textual description of the project score
  - `score_type` 'slider' | 'categorical' | 'weighted' | 'minimum' | 'online', required — The type of the configured score
  - `categories` union
    - ProjectScoreCategory[] — For categorical-type project scores, the list of all categories
      - `name` string, required — Name of the category
      - `value` number, required — Numerical value of the category. Must be between 0 and 1, inclusive
    - object — For weighted-type project scores, the weights of each score
    - string[] — For minimum-type project scores, the list of included scores
    - object, nullable
  - `config` ProjectScoreConfig, nullable
    - `multi_select` boolean, nullable
    - `destination` 'expected' | 'null', nullable
    - `online` OnlineScoreConfig, nullable
      - `sampling_rate` number, required — The sampling rate for online scoring
      - `scorers` SavedFunctionId[], required — The list of scorers to use for online scoring
        - union
          - object
            - `type` 'function', required
            - `id` string, required
          - object
            - `type` 'global', required
            - `name` string, required
      - `apply_to_root_span` boolean, nullable — Whether to trigger online scoring on the root span of each trace
      - `apply_to_span_names` string[], nullable — Trigger online scoring on any spans with a name in this list
  - `position` string, nullable — An optional LexoRank-based string that sets the sort position for the score in the UI

## Other responses

- `400` — The request was unacceptable, often due to missing a required parameter
- `401` — No valid API key provided
- `403` — The API key doesn’t have permissions to perform the request
- `429` — Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
- `500` — Something went wrong on Braintrust's end. (These are rare.)

## Changes

- **2024-09-30** `ac2727014d93` — 5 breaking, 1 info
  - the response's body became nullable
  - the response's body became nullable
  - the response's body became nullable
  - the response's body became nullable
  - …2 more
- **2024-09-25** `68955d9009ff` — 1 breaking, 1 info
  - removed the enum value `undefined` of the request property `score_type`
  - removed the `undefined` enum value from the `score_type` response property for the response status `200`
- **2024-09-21** `1e677afe2f7b` — 1 warning, 2 info
  - added the new `online` enum value to the `score_type` response property for the response status `200`
  - added the new `online` enum value to the request property `score_type`
  - added the optional property `config/online` to the response with the `200` status
- **2024-07-30** `573fc67af16c` — 1 breaking, 3 info
  - removed `subschema #1, subschema #2, subschema #3` from the `categories` request property `anyOf` list
  - added `subschema #1: categorical, subschema #2: weighted, subschema #3: minimum` to the `categories` request property `anyOf` list
  - added `subschema #1: categorical, subschema #2: weighted, subschema #3: minimum` to the `categories` response property `anyOf` list for the response status `200`
  - removed `subschema #1, subschema #2, subschema #3` from the `categories` response property `anyOf` list for the response status `200`
- …earlier changes not shown

[Full history](https://skmtc.dev/braintrustdata/apis/braintrust-api/changes/v1/project_score/put.md)

---

[API](https://skmtc.dev/braintrustdata/apis/braintrust-api.md) · [All operations](https://skmtc.dev/braintrustdata/apis/braintrust-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/braintrustdata/braintrust-api/revisions/9d216c8243fe/schema)