Create Score

Create a single annotation score on a source.

Create Score

Create a single annotation score on a specific source (trace, span, etc.). This also creates a legacy TraceAnnotation for backward compatibility. If the source belongs to an annotation queue, the corresponding queue item may auto-complete.

POST https://api.futureagi.com/model-hub/scores/
Bearer 
          Click "Try It" to send a request

Authentication

All requests require authentication via API keys:

HeaderDescription
X-Api-KeyYour API key
X-Secret-KeyYour secret key

Request Body

source_type string Required

The type of source to annotate. One of trace, span, generation, or session.

source_id string Required

UUID of the source object to annotate.

label_id string Required

UUID of the annotation label to use for this score.

value object Required

The score value as JSON. The structure depends on the label type (e.g., rating: 5 for star, selected: [“option1”] for categorical).

notes string

Optional freeform notes to attach to the score.

score_source string

Origin of the score. Defaults to "human". Other values include "automation" or "sdk".

Response

id string
UUID of the created score.
source_type string
The source type.
source_id string
UUID of the source.
label_id string
UUID of the label used.
label_name string
Display name of the label.
label_type string
Type of the label (text, categorical, numeric, star, thumbs_up_down).
value object
The score value.
score_source string
Origin of the score.
notes string
Attached notes, if any.
annotator string
UUID of the user who created the score.
annotator_name string
Display name of the annotator.
annotator_email string
Email of the annotator.
queue_item string
UUID of the associated queue item, if any.
created_at string
ISO 8601 timestamp of creation.
updated_at string
ISO 8601 timestamp of last update.

Note

Creating a score also writes a legacy TraceAnnotation for backward compatibility. If the annotated source belongs to an annotation queue and all required labels are now scored, the queue item may auto-complete.

Code Examples

import requests

url = "https://api.futureagi.com/model-hub/scores/"
headers = {
    "X-Api-Key": "YOUR_API_KEY",
    "X-Secret-Key": "YOUR_SECRET_KEY",
    "Content-Type": "application/json",
}

payload = {
    "source_type": "trace",
    "source_id": "your-source-uuid",
    "label_id": "your-label-uuid",
    "value": {"rating": 5},
    "notes": "Excellent response quality",
    "score_source": "human",
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
const response = await fetch("https://api.futureagi.com/model-hub/scores/", {
  method: "POST",
  headers: {
    "X-Api-Key": "YOUR_API_KEY",
    "X-Secret-Key": "YOUR_SECRET_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    sourceType: "trace",
    sourceId: "your-source-uuid",
    labelId: "your-label-uuid",
    value: { rating: 5 },
    notes: "Excellent response quality",
    scoreSource: "human",
  }),
});

const data = await response.json();
console.log(data);
curl -X POST https://api.futureagi.com/model-hub/scores/ \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Secret-Key: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "trace",
    "source_id": "your-source-uuid",
    "label_id": "your-label-uuid",
    "value": {"rating": 5},
    "notes": "Excellent response quality",
    "score_source": "human"
  }'
Was this page helpful?

Questions & Discussion