Scores endpoints
GET /api/v1/projects/{project_id}/score-configs
Section titled “GET /api/v1/projects/{project_id}/score-configs”List score configs
By name. Unpaginated: a project holds at most 500 score configs.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: array of ScoreConfigOut |
| 422 | Validation Error | application/json: HTTPValidationError |
POST /api/v1/projects/{project_id}/score-configs
Section titled “POST /api/v1/projects/{project_id}/score-configs”Add a score config
Define a score name. 409 NAME_TAKEN when the name has a config, including one the
first score created: edit that one instead.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes |
Request body (application/json, required): ScoreConfigSpec
| Status | Description | Body |
|---|---|---|
| 201 | Successful Response | application/json: ScoreConfigOut |
| 422 | Validation Error | application/json: HTTPValidationError |
DELETE /api/v1/projects/{project_id}/score-configs/{config_id}
Section titled “DELETE /api/v1/projects/{project_id}/score-configs/{config_id}”Delete a score config
409 SCORE_CONFIG_IN_USE while scores carry the name or a review queue asks for it.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
config_id |
path | string (uuid) | yes |
| Status | Description | Body |
|---|---|---|
| 204 | Successful Response | none |
| 422 | Validation Error | application/json: HTTPValidationError |
PATCH /api/v1/projects/{project_id}/score-configs/{config_id}
Section titled “PATCH /api/v1/projects/{project_id}/score-configs/{config_id}”Edit a score config
Change the description, range or categories; the config becomes explicit. A new
data_type is 409 SCORE_CONFIG_IN_USE once scores use the name. New bounds apply to new
scores only.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
config_id |
path | string (uuid) | yes |
Request body (application/json, required): ScoreConfigPatch
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: ScoreConfigOut |
| 422 | Validation Error | application/json: HTTPValidationError |
POST /api/v1/projects/{project_id}/score-configs/failure-category
Section titled “POST /api/v1/projects/{project_id}/score-configs/failure-category”Add the failure-category config
Create the categorical failure_category config with the categories sent, in that
order (2 to 30, distinct, none included). 409 NAME_TAKEN when the project has one:
edit its list with PATCH /score-configs/{config_id}.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes |
Request body (application/json, required): FailureCategoriesIn
| Status | Description | Body |
|---|---|---|
| 201 | Successful Response | application/json: ScoreConfigOut |
| 422 | Validation Error | application/json: HTTPValidationError |
DELETE /api/v1/projects/{project_id}/scores/{score_id}
Section titled “DELETE /api/v1/projects/{project_id}/scores/{score_id}”Delete a score
Your own human score, or any score as an admin; 403 FORBIDDEN otherwise.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
score_id |
path | string (uuid) | yes |
| Status | Description | Body |
|---|---|---|
| 204 | Successful Response | none |
| 422 | Validation Error | application/json: HTTPValidationError |
GET /api/v1/projects/{project_id}/traces/{trace_id}/scores
Section titled “GET /api/v1/projects/{project_id}/traces/{trace_id}/scores”List a trace’s scores
Every score of the trace, latest first (at most 1000). A score may name a trace that has not arrived yet, so an unknown trace lists its scores too.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
trace_id |
path | string | yes |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: array of ScoreOut |
| 422 | Validation Error | application/json: HTTPValidationError |
POST /api/v1/projects/{project_id}/traces/{trace_id}/scores
Section titled “POST /api/v1/projects/{project_id}/traces/{trace_id}/scores”Score a trace
Add a human score by the caller. 404 when the trace is not in the project; 422 VALIDATION_ERROR when the score does not fit its name’s config. A first score with a new
name creates its config.
id makes a retry idempotent: when a score with that id already exists in the project,
nothing is written and the stored score is returned as it is, even if it belongs to another
trace or author.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
trace_id |
path | string | yes |
Request body (application/json, required): ScoreCreate
| Status | Description | Body |
|---|---|---|
| 201 | Successful Response | application/json: ScoreOut |
| 422 | Validation Error | application/json: HTTPValidationError |
POST /v1/scores
Section titled “POST /v1/scores”Ingest Scores
Store a batch of 1 to 1000 scores. The body is read after the key is checked, bounded like span ingestion and may be gzip or deflate encoded.
Request body (application/json, required): object
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: ScoreIngestResponse |