Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.selftune.dev/llms.txt

Use this file to discover all available pages before exploring further.

---
title: "Push API"
description: "Sync session data, grading results, and improvement signals to the selftune cloud"
---

## Overview

The push endpoint receives batched canonical records from the selftune CLI. It is called automatically by `selftune sync` — you do not need to call it directly unless you are building a custom integration.

## Endpoint
POST /v2/push 

Requires a valid API key passed as a Bearer token.

## Request body

```json
{
  "workspace_id": "string",
  "cli_version": "string",
  "pushed_at": "ISO 8601 timestamp",
  "data": {
    "sessions": [...],
    "prompts": [...],
    "normalization_runs": [...],
    "evolution_evidence": [...],
    "orchestrate_runs": [...],
    "grading_results": [...],
    "improvement_signals": [...]
  }
}
All arrays inside data are optional. Only include the record types you have to push.

​
grading_results

An array of grading result records produced by selftune grade. Each record captures the outcome of a single grading session for a skill.
FieldTypeDescription
grading_idstringUnique identifier for this grading run
session_idstringThe session that was graded
skill_namestringName of the skill that was evaluated
graded_atstringISO 8601 timestamp of when grading ran
pass_ratenumber | nullFraction of expectations that passed (0–1)
mean_scorenumber | nullMean score across all evaluated items
score_std_devnumber | nullStandard deviation of scores
passed_countnumber | nullNumber of passing expectations
failed_countnumber | nullNumber of failing expectations
total_countnumber | nullTotal expectations evaluated
expectations_jsonstring | nullSerialized expectation details
claims_jsonstring | nullSerialized claim details
eval_feedback_jsonstring | nullStructured feedback from the eval pass
failure_feedback_jsonstring | nullStructured feedback on failures
execution_metrics_jsonstring | nullTiming and resource metrics

​
improvement_signals

An array of improvement signal records. These are generated when a session contains queries that suggest a skill can be improved — for example, unmatched queries or explicit user feedback.
FieldTypeDescription
signal_idstringUnique identifier for this signal
timestampstringISO 8601 timestamp of when the signal was captured
session_idstringThe session the signal came from
querystringThe query that triggered the signal
signal_typestringCategory of signal (e.g. unmatched, low_grade)
mentioned_skillstring | nullSkill name referenced, if identifiable
consumedbooleanWhether this signal has been acted on by an evolution run
consumed_atstring | nullWhen the signal was consumed
consumed_by_runstring | nullThe evolution run ID that consumed it

​
Response

{
  "ok": true,
  "accepted": {
    "sessions": 4,
    "grading_results": 2,
    "improvement_signals": 7
  }
}

​
Usage with the CLI

selftune sync pushes all pending local records — including grading results and improvement signals — to the cloud automatically: 
selftune sync
After syncing, grading results appear in the cloud dashboard under each skill’s history, and improvement signals are visible under Cloud → Signals.
  • Signals — view and manage improvement signals in the dashboard
  • Grading — how selftune grades skill sessions locally
  • selftune sync — CLI command that calls this endpoint