Skip to main content
POST
Create a score

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request body for creating a score.

name
string
required

Score name (e.g. "correctness")

Required string length: 1 - 255
score_type
enum<string>
required

Score type. Determines which value field is required. Vector type is not accepted on create (used by evaluators only).

Available options:
numeric,
boolean,
categorical,
text
source
enum<string>
required

Score source. Evaluator is not accepted (evaluator scores are created by the enrichment worker, not via this API).

Available options:
human,
llm,
code
application_id
string<uuid>
required

Application UUID

id
string<uuid>

Optional client-provided score ID for upsert. If not provided, a deterministic UUID v5 is generated from (application_id, target_id, name, annotator_id).

span_id
string

Target span ID. Exactly one of span_id, trace_id, or session_id is required.

trace_id
string

Target trace ID. Exactly one of span_id, trace_id, or session_id is required.

session_id
string

Target session ID. Exactly one of span_id, trace_id, or session_id is required.

value
number<double>

Numeric value. Required for numeric type. For boolean type, must be exactly 1.0 or 0.0 (runtime-validated; out-of-range values return 422).

label
string

Categorical label. Required for categorical type.

text
string

Text content. Required for text type.

Maximum string length: 65536
annotator_id
string

Annotator identifier. Required for source=llm and source=code. Ignored for source=human (backend populates from auth token).

reasoning
string

Optional reasoning or explanation

metadata
object

Arbitrary key-value metadata (string to string map)

config_name
string

Configuration name. Defaults to name if not provided.

Response

Score created successfully

Response object for standard API responses.

api_version
enum<string>
default:3.0

API version.

Available options:
2.0,
3.0
kind
enum<string>
default:NORMAL

Type of response, indicating a normal response.

Available options:
NORMAL
data
object

Score resource returned by all read endpoints.