Implementation:Langfuse Langfuse API Client Score Schema

Knowledge Sources	Langfuse Langfuse API Reference
Domains	API, Scoring
Last Updated	2026-02-14 00:00 GMT

Overview

Fern API definition for the client-side score creation endpoint, used by SDKs to submit numeric, categorical, boolean, and correction scores against traces, observations, sessions, and dataset runs.

Description

This file defines the public API contract for creating scores via the Langfuse client SDKs. It contains a single endpoint and three supporting types:

• POST /api/public/scores -- Upserts a score record, identified by its id. Supports attaching scores to traces, observations, sessions, or dataset runs.
• CreateScoreRequest -- The request body type with fields for score name, value, data type, and optional associations.
• ScoreDataType -- Enum defining the four supported score types: NUMERIC, CATEGORICAL, BOOLEAN, and CORRECTION.
• CreateScoreValue -- A discriminated union of double and string, allowing numeric or string values depending on the score data type.

Usage

Developers reference this definition when:

• Modifying the score creation API endpoint behavior
• Updating SDK client code generation via Fern
• Understanding the public API contract for score ingestion
• Adding new score data types or validation rules

Code Reference

Source Location

• Repository: Langfuse
• File: fern/apis/client/definition/score.yml
• Lines: 1-93

Signature

service:
  auth: true
  base-path: /api/public
  endpoints:
    create:
      docs: Add a score to the database, upserts on id
      method: POST
      path: /scores
      request: CreateScoreRequest

types:
  CreateScoreRequest:
    properties:
      id: optional<string>
      traceId: optional<string>
      sessionId: optional<string>
      observationId: optional<string>
      datasetRunId: optional<string>
      name:
        type: string
        docs: The name of the score. Always overrides "output" for correction scores.
      value:
        type: CreateScoreValue
      comment: optional<string>
      metadata: optional<unknown>
      dataType: optional<ScoreDataType>
      configId: optional<string>

  ScoreDataType:
    enum:
      - NUMERIC
      - CATEGORICAL
      - BOOLEAN
      - CORRECTION

  CreateScoreValue:
    discriminated: false
    union:
      - double
      - string

I/O Contract

Endpoints

Method	Path	Description
POST	/api/public/scores	Create or upsert a score by id

Key Types

Type Name	Description
CreateScoreRequest	Request body for score creation with name, value, optional trace/observation/session/dataset run associations
ScoreDataType	Enum of score data types: NUMERIC, CATEGORICAL, BOOLEAN, CORRECTION
CreateScoreValue	Union type accepting either a double (numeric/boolean) or string (categorical/correction)

Usage Examples

# Create a numeric score
curl -X POST "https://cloud.langfuse.com/api/public/scores" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "novelty",
    "value": 0.9,
    "traceId": "cdef-1234-5678-90ab"
  }'

# Create a categorical score
curl -X POST "https://cloud.langfuse.com/api/public/scores" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "toxicity",
    "value": "not toxic",
    "dataType": "CATEGORICAL",
    "traceId": "cdef-1234-5678-90ab"
  }'

# Create a boolean score
curl -X POST "https://cloud.langfuse.com/api/public/scores" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hallucination",
    "value": 0,
    "dataType": "BOOLEAN",
    "traceId": "cdef-1234-5678-90ab"
  }'

Related Pages

• Environment:Langfuse_Langfuse_Node_24_Runtime