{"openapi":"3.1.0","info":{"title":"Treecode API","version":"1.0.0","summary":"Grader Check, Rollout Budget, Cost per Solved Task and Checkpoints from one table of scored samples.","description":"Upload one table of scored samples (prompt, candidate, the grader's score, whether the candidate was right), run a calibration, and read the Report: how well the grader separates right from wrong within a prompt, how best-of-N succeeds with it, and what group size and sample count that implies.  Every number comes with a band and a sentence.  Authentication: an API key (Authorization: Bearer tc_live_...) on the public host, or the application's session cookie through /api/v1/product.  Errors are {\"error\": sentence}; an exceeded plan allowance is 402 with the allowance.  The full reference with examples is API.md.","contact":{"name":"Treecode","url":"https://app.treecode.ai","email":"hello@treecode.ai"}},"servers":[{"url":"https://api.treecode.ai/v1","description":"the public API"},{"url":"https://app.treecode.ai/api/v1/product","description":"the same routes through the application (the SDK's fallback)"}],"security":[{"apiKey":[]},{"session":[]}],"tags":[{"name":"accounts"},{"name":"keys"},{"name":"graders"},{"name":"samples"},{"name":"calibrations"},{"name":"decisions"},{"name":"budgets"},{"name":"runs"},{"name":"billing"},{"name":"sharing"},{"name":"meta"}],"paths":{"/auth/signup":{"post":{"summary":"Create an account and its organization","tags":["accounts"],"responses":{"201":{"description":"created; the session cookie is set","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"$ref":"#/components/schemas/User"},"org":{"$ref":"#/components/schemas/Org"},"token":{"type":"string","description":"the session token"}}}}}},"202":{"description":"waitlist mode: the request is noted","content":{"application/json":{"schema":{"type":"object","properties":{"waitlist":{"type":"boolean"},"message":{"type":"string"}}}}}},"403":{"description":"sign-up is closed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"the email is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"more than 10 sign-ups per hour from one address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"the body or the sample table is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"company":{"type":"string"},"password":{"type":"string","minLength":10}},"required":["name","email","company","password"]}}}},"security":[]}},"/me":{"get":{"summary":"The caller: user, organization, plan and this month's usage","tags":["accounts"],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"oneOf":[{"$ref":"#/components/schemas/User"},{"type":"null"}]},"org":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"plan":{"type":"string"}}},"plan":{"$ref":"#/components/schemas/Plan"},"usage":{"$ref":"#/components/schemas/Usage"},"auth":{"type":"string","enum":["session","api_key"]}}}}}},"401":{"description":"no valid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/keys":{"post":{"summary":"Create an API key (shown once)","tags":["keys"],"responses":{"201":{"description":"created","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/ApiKey"},"token":{"type":"string","description":"tc_live_..."},"note":{"type":"string"}}}}}},"401":{"description":"no valid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"an allowance of the plan is exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowanceError"}}}},"422":{"description":"the body or the sample table is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","default":"default"}}}}}}},"get":{"summary":"List the organization's keys (revoked ones included)","tags":["keys"],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}}}}}}},"401":{"description":"no valid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/keys/{key_id}":{"delete":{"summary":"Revoke a key","tags":["keys"],"responses":{"200":{"description":"revoked","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/ApiKey"},"revoked":{"type":"boolean"}}}}}},"401":{"description":"no valid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"the key"}]}},"/graders":{"post":{"summary":"Create a grader","tags":["graders"],"responses":{"201":{"description":"created","content":{"application/json":{"schema":{"type":"object","properties":{"grader":{"$ref":"#/components/schemas/Grader"}}}}}},"401":{"description":"no valid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"an allowance of the plan is exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowanceError"}}}},"422":{"description":"the body or the sample table is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GraderCreate"}}}}},"get":{"summary":"List graders: the organization's own, then the demo graders (demo: true)","tags":["graders"],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"graders":{"type":"array","items":{"$ref":"#/components/schemas/Grader"}},"counts":{"type":"object","properties":{"own":{"type":"integer"},"demo":{"type":"integer"},"allowance":{"type":["integer","null"]}}}}}}}},"401":{"description":"no valid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/graders/{grader_id}":{"get":{"summary":"A grader with its sample sets, calibrations, latest report and training runs","tags":["graders"],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"grader":{"$ref":"#/components/schemas/Grader"},"sample_sets":{"type":"array","items":{"$ref":"#/components/schemas/SampleSet"}},"calibrations":{"type":"array","items":{"$ref":"#/components/schemas/Calibration"}},"latest_report":{"oneOf":[{"$ref":"#/components/schemas/Report"},{"type":"null"}]},"runs":{"type":"array","items":{"$ref":"#/components/schemas/TrainingRun"}}}}}}},"401":{"description":"no valid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"grader_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"the grader (own or demo)"}]},"patch":{"summary":"Change a grader's settings","tags":["graders"],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"grader":{"$ref":"#/components/schemas/Grader"}}}}}},"401":{"description":"no valid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not allowed (demo graders are read-only)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"the body or the sample table is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GraderPatch"}}}},"parameters":[{"name":"grader_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"the grader (own or demo)"}]},"delete":{"summary":"Delete a grader (soft; its sample files are removed from storage)","tags":["graders"],"responses":{"200":{"description":"deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"grader_id":{"type":"string"},"sample_files_removed":{"type":"integer"}}}}}},"401":{"description":"no valid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not allowed (demo graders are read-only)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"grader_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"the grader (own or demo)"}]}},"/graders/{grader_id}/share":{"post":{"summary":"Create (or return) the grader's public share link","tags":["graders"],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"share_token":{"type":"string"},"url":{"type":"string"}}}}}},"401":{"description":"no valid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not allowed (demo graders are read-only)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"grader_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"the grader (own or demo)"}]},"delete":{"summary":"Stop sharing","tags":["graders"],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"share_token":{"type":"null"},"url":{"type":"null"}}}}}},"401":{"description":"no valid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not allowed (demo graders are read-only)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"grader_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"the grader (own or demo)"}]}},"/graders/{grader_id}/samples":{"post":{"summary":"Upload a sample table","tags":["samples"],"responses":{"201":{"description":"stored","content":{"application/json":{"schema":{"type":"object","properties":{"sample_set":{"$ref":"#/components/schemas/SampleSet"},"warnings":{"type":"array","items":{"type":"string"}}}}}}},"413":{"description":"over 50 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"multipart bodies are not accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"no valid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"an allowance of the plan is exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowanceError"}}}},"403":{"description":"not allowed (demo graders are read-only)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"the body or the sample table is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"description":"Validated by the engine (422 with problems); meters prompts_ingested; the normalized JSON lines are stored.","requestBody":{"required":true,"description":"The sample table: one row per candidate with prompt_id, candidate_id, score (higher is better) and label (1/0, true/false, correct/wrong); optional tokens; for step graders step, node_id and parent_correct; for runs checkpoint; and a free class tag. The format is detected from the content (?format=csv|jsonl|json overrides).  At most 50 MB per upload.","content":{"text/csv":{"schema":{"type":"string"},"example":"prompt_id,candidate_id,score,label,tokens\np1,c1,6.0,1,840\np1,c2,4.4,0,910\n"},"application/x-ndjson":{"schema":{"type":"string"},"example":"{\"prompt_id\":\"p1\",\"candidate_id\":\"c1\",\"score\":6.0,\"label\":true}\n"},"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SampleRow"}},"example":[{"prompt_id":"p1","candidate_id":"c1","score":6.0,"label":true}]}}},"parameters":[{"name":"grader_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"the grader (own or demo)"},{"name":"checkpoint","in":"query","required":false,"schema":{"type":"string"},"description":"label the table with this checkpoint"},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["csv","jsonl","json"]},"description":"csv, jsonl or json (default: detected)"}]}},"/graders/{grader_id}/calibrate":{"post":{"summary":"Queue a Grader Check","tags":["calibrations"],"responses":{"202":{"description":"queued","content":{"application/json":{"schema":{"type":"object","properties":{"calibration":{"$ref":"#/components/schemas/Calibration"}}}}}},"401":{"description":"no valid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"an allowance of the plan is exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowanceError"}}}},"403":{"description":"not allowed (demo graders are read-only)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"the body or the sample table is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"description":"Executed by a worker as a run of the hidden experiment product_calibrate; poll GET /calibrations/{id}.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalibrateBody"}}}},"parameters":[{"name":"grader_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"the grader (own or demo)"}]}},"/calibrations/{calibration_id}":{"get":{"summary":"A calibration and its Report","tags":["calibrations"],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"calibration":{"$ref":"#/components/schemas/Calibration"},"report":{"oneOf":[{"$ref":"#/components/schemas/Report"},{"type":"null"}]}}}}}},"401":{"description":"no valid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"calibration_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"the calibration"}]}},"/calibrations/{calibration_id}/events":{"get":{"summary":"The worker's progress and log lines","tags":["calibrations"],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"calibration_id":{"type":"string"},"status":{"type":"string"},"events":{"type":"array","items":{"$ref":"#/components/schemas/Event"}}}}}}},"401":{"description":"no valid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"calibration_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"the calibration"},{"name":"after","in":"query","required":false,"schema":{"type":"integer"},"description":"events with an id above this"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"},"description":"at most 2000"}]}},"/calibrations/{calibration_id}/decision":{"post":{"summary":"Record what was decided after reading the report","tags":["decisions"],"responses":{"201":{"description":"recorded","content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"$ref":"#/components/schemas/Decision"}}}}}},"401":{"description":"no valid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"the body or the sample table is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecisionBody"}}}},"parameters":[{"name":"calibration_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"the calibration"}]}},"/decisions":{"get":{"summary":"The organization's decision log","tags":["decisions"],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"decisions":{"type":"array","items":{"$ref":"#/components/schemas/Decision"}},"answers":{"type":"array","items":{"type":"string"}}}}}}},"401":{"description":"no valid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/budgets/rollouts":{"post":{"summary":"The Rollout Budget from a finished calibration","tags":["budgets"],"responses":{"200":{"description":"the Budget","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Budget"}}}},"401":{"description":"no valid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"the request conflicts with the state of the resource (an unfinished calibration, a report without the needed curve)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"the body or the sample table is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RolloutBudgetBody"}}}}}},"/budgets/serving":{"post":{"summary":"The Cost per Solved Task from a finished calibration","tags":["budgets"],"responses":{"200":{"description":"the Serving result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Serving"}}}},"401":{"description":"no valid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"the request conflicts with the state of the resource (an unfinished calibration, a report without the needed curve)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"the body or the sample table is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServingBody"}}}}}},"/vendors/prices":{"get":{"summary":"Listed, dated per-token prices of serving vendors","tags":["budgets"],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"vendors":{"type":"array","items":{"$ref":"#/components/schemas/VendorPrice"}},"price_date":{"type":"string"},"unit":{"type":"string"}}}}}},"401":{"description":"no valid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/runs":{"post":{"summary":"Create a training run (Team plan and above)","tags":["runs"],"responses":{"201":{"description":"created","content":{"application/json":{"schema":{"type":"object","properties":{"run":{"$ref":"#/components/schemas/TrainingRun"}}}}}},"401":{"description":"no valid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"an allowance of the plan is exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowanceError"}}}},"403":{"description":"not allowed (demo graders are read-only)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"the body or the sample table is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrainingRunCreate"}}}}},"get":{"summary":"List training runs (own, then demo)","tags":["runs"],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"runs":{"type":"array","items":{"$ref":"#/components/schemas/TrainingRun"}}}}}}},"401":{"description":"no valid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/runs/{run_id}":{"get":{"summary":"A training run, its checkpoints and the checkpoint series","tags":["runs"],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"run":{"$ref":"#/components/schemas/TrainingRun"},"checkpoints":{"type":"array","items":{"$ref":"#/components/schemas/SampleSet"}},"series":{"oneOf":[{"$ref":"#/components/schemas/CheckpointSeries"},{"type":"null"}]}}}}}},"401":{"description":"no valid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"the training run"}]}},"/runs/{run_id}/checkpoints":{"post":{"summary":"Upload one checkpoint's samples (the series is recomputed)","tags":["runs"],"responses":{"201":{"description":"stored","content":{"application/json":{"schema":{"type":"object","properties":{"sample_set":{"$ref":"#/components/schemas/SampleSet"},"warnings":{"type":"array","items":{"type":"string"}},"run":{"$ref":"#/components/schemas/TrainingRun"},"series":{"oneOf":[{"$ref":"#/components/schemas/CheckpointSeries"},{"type":"null"}]}}}}}},"401":{"description":"no valid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"an allowance of the plan is exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowanceError"}}}},"403":{"description":"not allowed (demo graders are read-only)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"the body or the sample table is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"requestBody":{"required":true,"description":"The sample table: one row per candidate with prompt_id, candidate_id, score (higher is better) and label (1/0, true/false, correct/wrong); optional tokens; for step graders step, node_id and parent_correct; for runs checkpoint; and a free class tag. The format is detected from the content (?format=csv|jsonl|json overrides).  At most 50 MB per upload.","content":{"text/csv":{"schema":{"type":"string"},"example":"prompt_id,candidate_id,score,label,tokens\np1,c1,6.0,1,840\np1,c2,4.4,0,910\n"},"application/x-ndjson":{"schema":{"type":"string"},"example":"{\"prompt_id\":\"p1\",\"candidate_id\":\"c1\",\"score\":6.0,\"label\":true}\n"},"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SampleRow"}},"example":[{"prompt_id":"p1","candidate_id":"c1","score":6.0,"label":true}]}}},"parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"the training run"},{"name":"checkpoint","in":"query","required":false,"schema":{"type":"string"},"description":"the checkpoint's label, e.g. 'step 100' (required unless the table carries one checkpoint value)"},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["csv","jsonl","json"]},"description":"csv, jsonl or json"}]}},"/usage":{"get":{"summary":"This month's usage, the allowances and the statement","tags":["billing"],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"string"},"period":{"type":"object"},"prompts_ingested":{"type":"integer"},"calibrations":{"type":"integer"},"checkpoints":{"type":"integer"},"graders":{"type":"integer"},"keys":{"type":"integer"},"runs":{"type":"integer"},"allowances":{"$ref":"#/components/schemas/Plan"},"statement":{"$ref":"#/components/schemas/Statement"}}}}}},"401":{"description":"no valid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/billing/plan":{"post":{"summary":"Change the plan (free, pro, team, scale; no payment is collected)","tags":["billing"],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"org":{"$ref":"#/components/schemas/Org"},"plan":{"$ref":"#/components/schemas/Plan"},"note":{"type":"string"}}}}}},"401":{"description":"no valid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"the body or the sample table is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"string","enum":["free","pro","team","scale"]}},"required":["plan"]}}}}}},"/share/{token}":{"get":{"summary":"A shared grader's latest report (no credential needed)","tags":["sharing"],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"grader":{"type":"object"},"report":{"oneOf":[{"$ref":"#/components/schemas/Report"},{"type":"null"}]},"org_name":{"type":["string","null"]},"calibration":{"oneOf":[{"$ref":"#/components/schemas/Calibration"},{"type":"null"}],"description":"the calibration the report comes from"}}}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"security":[]}},"/openapi.json":{"get":{"summary":"This document","tags":["meta"],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object"}}}}},"security":[]}},"/health":{"get":{"summary":"Service health","tags":["meta"],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"database":{"type":"string"},"dispatcher":{"type":"string"},"code_version":{"type":"string"},"time":{"type":"string"}}}}}},"503":{"description":"degraded","content":{"application/json":{"schema":{"type":"object"}}}}},"security":[]}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"tc_live_<40 url-safe characters>","description":"An API key from POST /keys.  Keys are shown once; the service stores their SHA-256."},"session":{"type":"apiKey","in":"cookie","name":"tc_session","description":"The web application's session cookie (through app.treecode.ai/api/v1/product)."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"a plain-language sentence"}},"required":["error"]},"ValidationError":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"array","items":{"type":"object"},"description":"pydantic field errors (invalid JSON bodies)"},"problems":{"type":"array","items":{"type":"string"},"description":"problems of the sample table (uploads)"}},"required":["error"]},"Allowance":{"type":"object","properties":{"plan":{"type":"string"},"kind":{"type":"string","enum":["graders","prompts_per_month","calibrations_per_month","keys","runs"]},"limit":{"type":"integer"},"used":{"type":"integer"},"requested":{"type":"integer"},"remaining":{"type":"integer"},"message":{"type":"string"}}},"AllowanceError":{"type":"object","properties":{"error":{"type":"string"},"allowance":{"$ref":"#/components/schemas/Allowance"},"upgrade":{"type":"string","example":"/billing"}},"required":["error","allowance","upgrade"]},"Plan":{"type":"object","properties":{"plan":{"type":"string"},"label":{"type":"string"},"graders":{"type":["integer","null"]},"prompts_per_month":{"type":["integer","null"]},"calibrations_per_month":{"type":["integer","null"]},"runs":{"type":"boolean"},"keys":{"type":["integer","null"]},"price":{"type":["number","null"],"description":"dollars per month; null for custom pricing"},"overage_per_1000_prompts":{"type":["number","null"]}},"description":"null means unlimited","example":{"plan":"free","label":"Free","graders":1,"prompts_per_month":1000,"calibrations_per_month":4,"runs":false,"keys":2,"price":0,"overage_per_1000_prompts":null}},"Usage":{"type":"object","properties":{"period":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}},"prompts_ingested":{"type":"integer"},"calibrations":{"type":"integer"},"checkpoints":{"type":"integer"},"graders":{"type":"integer"},"keys":{"type":"integer"},"runs":{"type":"integer"}},"description":"the current calendar month (UTC)"},"User":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"name":{"type":"string"},"role":{"type":"string"}}},"Org":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"plan":{"type":"string","enum":["free","pro","team","scale","enterprise","internal"]},"billing_email":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"signup_source":{"type":["string","null"]},"settings":{"type":"object"}}},"ApiKey":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"prefix":{"type":"string","description":"the first 12 characters"},"created_by":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"last_used_at":{"type":["string","null"]},"revoked_at":{"type":["string","null"]}}},"LatestCalibration":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","running","succeeded","failed"]},"verdict_level":{"type":["string","null"]},"headline":{"type":["string","null"]},"kind":{"type":["string","null"]},"finished_at":{"type":["string","null"]}}},"Grader":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"kind":{"type":"string","enum":["auto","outcome","step","binary"]},"group_size":{"type":"integer"},"depth":{"type":["integer","null"]},"label_source":{"type":"string"},"policy":{"type":["string","null"]},"checkpoint_label":{"type":["string","null"]},"notes":{"type":"string"},"settings":{"type":"object"},"demo":{"type":"boolean"},"own":{"type":"boolean","description":"belongs to the calling organization"},"share_token":{"type":["string","null"]},"share_url":{"type":["string","null"]},"created_by":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"deleted_at":{"type":["string","null"]},"sample_sets_count":{"type":"integer"},"latest_calibration":{"oneOf":[{"$ref":"#/components/schemas/LatestCalibration"},{"type":"null"}]}}},"GraderCreate":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["auto","outcome","step","binary"],"default":"auto"},"group_size":{"type":"integer","description":"the group size (training) or samples per query (serving)","default":8},"depth":{"type":["integer","null"],"description":"step graders: the number of steps"},"label_source":{"type":"string","default":"unknown"},"policy":{"type":["string","null"]},"checkpoint_label":{"type":["string","null"]},"notes":{"type":"string","default":""},"settings":{"type":"object"}},"required":["name"]},"GraderPatch":{"type":"object","properties":{"name":{"type":"string"},"group_size":{"type":"integer"},"depth":{"type":"integer"},"label_source":{"type":"string"},"policy":{"type":"string"},"checkpoint_label":{"type":"string"},"notes":{"type":"string"},"settings":{"type":"object"}},"description":"only the fields given are changed"},"SampleRow":{"type":"object","properties":{"prompt_id":{"type":"string"},"candidate_id":{"type":"string"},"score":{"type":"number"},"label":{"type":["boolean","integer","string"]},"tokens":{"type":["integer","null"]},"step":{"type":["integer","null"]},"node_id":{"type":["string","null"]},"parent_correct":{"type":["boolean","null"]},"checkpoint":{"type":["string","null"]},"class":{"type":["string","null"]}},"required":["prompt_id","candidate_id","score","label"]},"SampleSummary":{"type":"object","properties":{"prompts":{"type":"integer"},"candidates":{"type":"integer"},"correct":{"type":"integer"},"wrong":{"type":"integer"},"kind":{"type":"string"},"has_tokens":{"type":"boolean"},"checkpoints":{"type":"array","items":{"type":"string"}},"group_sizes":{"type":"object","properties":{"min":{"type":"integer"},"median":{"type":"integer"},"max":{"type":"integer"}}}}},"SampleSet":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"grader_id":{"type":"string","format":"uuid"},"training_run_id":{"type":["string","null"]},"checkpoint":{"type":["string","null"]},"prompts":{"type":"integer"},"candidates":{"type":"integer"},"correct":{"type":"integer"},"wrong":{"type":"integer"},"kind":{"type":"string","enum":["outcome","step","binary"]},"sha256":{"type":"string"},"summary":{"$ref":"#/components/schemas/SampleSummary"},"created_by":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"CalibrateBody":{"type":"object","properties":{"sample_set_id":{"type":["string","null"],"description":"default: the grader's latest sample set"},"group_size":{"type":["integer","null"],"description":"default: the grader's"},"depth":{"type":["integer","null"]},"target_success":{"type":"number","default":0.9},"n_boot":{"type":["integer","null"],"description":"bootstrap resamples (default 200; 500 below 5,000 candidates)"},"seed":{"type":"integer","default":0}}},"Calibration":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"grader_id":{"type":"string","format":"uuid"},"sample_set_id":{"type":"string","format":"uuid"},"params":{"type":"object"},"status":{"type":"string","enum":["queued","running","succeeded","failed"]},"run_id":{"type":["string","null"],"description":"the worker run; its events are at /calibrations/{id}/events"},"error":{"type":["string","null"]},"created_by":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":["string","null"]},"finished_at":{"type":["string","null"]},"verdict_level":{"type":["string","null"]},"headline":{"type":["string","null"]},"kind":{"type":["string","null"]},"seconds":{"type":["number","null"]}}},"Report":{"type":"object","properties":{"version":{"type":"integer","const":1},"kind":{"type":"string","enum":["outcome","step","binary"]},"input":{"type":"object"},"verdict":{"type":"object","properties":{"level":{"type":"string"},"headline":{"type":"string"},"sentences":{"type":"array","items":{"type":"string"}},"what_to_do":{"type":"array","items":{"type":"string"}},"conventions":{"type":"string"}}},"margins":{"type":["object","null"]},"ranking":{"type":["object","null"]},"distributions":{"type":["object","null"]},"coverage":{"type":["object","null"]},"best_of_n":{"type":["object","null"]},"label_noise":{"type":["object","null"]},"step":{"type":["object","null"]},"method":{"type":"object"}},"description":"The Report (version 1) of treecode_calibrate.calibrate; the key-by-key schema is in API.md"},"Event":{"type":"object","properties":{"id":{"type":"integer"},"run_id":{"type":"string"},"ts":{"type":"string","format":"date-time"},"level":{"type":"string"},"message":{"type":"string"},"progress":{"type":["number","null"]},"data":{"type":["object","null"]}}},"DecisionBody":{"type":"object","properties":{"answer":{"type":"string","enum":["changed_group_size","changed_mix","changed_n","stopped_run","changed_grader","no_change","not_yet"]},"note":{"type":"string","default":""}},"required":["answer"]},"Decision":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string"},"calibration_id":{"type":["string","null"]},"user_id":{"type":["string","null"]},"answer":{"type":"string"},"note":{"type":"string"},"ts":{"type":"string","format":"date-time"},"user_name":{"type":["string","null"]},"grader_id":{"type":["string","null"]},"grader_name":{"type":["string","null"]}}},"RolloutBudgetBody":{"type":"object","properties":{"calibration_id":{"type":"string","format":"uuid"},"group_size_now":{"type":["integer","null"],"description":"default: the report's group size"},"floors":{"oneOf":[{"type":"integer"},{"type":"object","additionalProperties":{"type":"integer"}},{"type":"null"}],"description":"an even group size of at least 4 for all classes, or per class name"},"cap":{"type":["integer","null"],"default":64},"cost_per_rollout":{"type":["number","null"],"description":"dollars; adds the dollar lines"}},"required":["calibration_id"]},"Budget":{"type":"object","properties":{"version":{"type":"integer"},"source":{"type":"string"},"group_size_now":{"type":"integer"},"floors":{"type":"object"},"cap":{"type":"integer"},"cost_per_rollout":{"type":["number","null"]},"proxies":{"type":"object"},"classes":{"type":"array","items":{"type":"object"}},"now":{"type":"object"},"allocations":{"type":"object"},"frontier":{"type":"array","items":{"type":"object"}},"saving_range":{"type":"object"},"weights":{"type":"object"},"sentences":{"type":"array","items":{"type":"string"}},"calibration_id":{"type":"string"}},"description":"treecode_calibrate.rollout_budget; keys in API.md"},"ServingBody":{"type":"object","properties":{"calibration_id":{"type":"string","format":"uuid"},"tokens_per_candidate":{"type":"number"},"price_per_mtok":{"type":"number","description":"output price, dollars per million tokens"},"grader_cost_per_candidate":{"type":"number","default":0},"target_success":{"type":"number","default":0.9},"failure_cost":{"type":["number","null"]},"prompt_tokens":{"type":["number","null"]},"price_in_per_mtok":{"type":["number","null"]}},"required":["calibration_id","tokens_per_candidate","price_per_mtok"]},"Serving":{"type":"object","properties":{"version":{"type":"integer"},"inputs":{"type":"object"},"cost_per_candidate":{"type":"number"},"n":{"type":"array","items":{"type":"integer"}},"success":{"type":"array","items":{"type":"number"}},"cost_per_task":{"type":"array","items":{"type":"number"}},"cost_per_solved":{"type":"array","items":{"type":["number","null"]}},"n_for_target":{"type":["integer","null"]},"cost_at_target":{"type":["number","null"]},"cost_per_solved_at_target":{"type":["number","null"]},"n_min_total_cost":{"type":["integer","null"]},"total_cost_at_min":{"type":["number","null"]},"vendors":{"type":"array","items":{"type":"object"}},"sentences":{"type":"array","items":{"type":"string"}},"calibration_id":{"type":"string"}},"description":"treecode_calibrate.serving_budget; keys in API.md"},"VendorPrice":{"type":"object","properties":{"name":{"type":"string"},"model":{"type":"string"},"price_in_per_mtok":{"type":"number"},"price_out_per_mtok":{"type":"number"},"date":{"type":"string"},"source":{"type":"string"}}},"TrainingRunCreate":{"type":"object","properties":{"grader_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"group_size":{"type":"integer"}},"required":["grader_id","name","group_size"]},"TrainingRun":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string"},"grader_id":{"type":"string"},"name":{"type":"string"},"group_size":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"created_by":{"type":["string","null"]},"has_series":{"type":"boolean"},"checkpoints_count":{"type":"integer"},"grader_name":{"type":"string"},"demo":{"type":"boolean"}}},"CheckpointSeries":{"type":"object","properties":{"version":{"type":"integer"},"group_size":{"type":"integer"},"n_boot":{"type":"integer"},"seed":{"type":"integer"},"experimental":{"type":"boolean"},"checkpoints":{"type":"array","items":{"type":"string"}},"series":{"type":"array","items":{"type":"object"}},"classes":{"type":"array","items":{"type":"object"}},"alarm":{"type":"object"},"trend":{"type":["object","null"]},"condition":{"type":"string"},"sentences":{"type":"array","items":{"type":"string"}}},"description":"treecode_calibrate.checkpoint_series; keys in API.md"},"Statement":{"type":"object","properties":{"plan_price":{"type":["number","null"]},"overage_prompts":{"type":"integer"},"overage_price":{"type":"number"},"total":{"type":["number","null"]},"currency":{"type":"string"},"note":{"type":["string","null"]}}}}},"x-plans":{"free":{"plan":"free","label":"Free","graders":1,"prompts_per_month":1000,"calibrations_per_month":4,"runs":false,"keys":2,"price":0,"overage_per_1000_prompts":null},"pro":{"plan":"pro","label":"Pro","graders":3,"prompts_per_month":10000,"calibrations_per_month":null,"runs":false,"keys":5,"price":99,"overage_per_1000_prompts":null},"team":{"plan":"team","label":"Team","graders":10,"prompts_per_month":100000,"calibrations_per_month":null,"runs":true,"keys":20,"price":990,"overage_per_1000_prompts":null},"scale":{"plan":"scale","label":"Scale","graders":null,"prompts_per_month":500000,"calibrations_per_month":null,"runs":true,"keys":null,"price":2900,"overage_per_1000_prompts":4},"enterprise":{"plan":"enterprise","label":"Enterprise","graders":null,"prompts_per_month":null,"calibrations_per_month":null,"runs":true,"keys":null,"price":null,"overage_per_1000_prompts":null},"internal":{"plan":"internal","label":"Internal","graders":null,"prompts_per_month":null,"calibrations_per_month":null,"runs":true,"keys":null,"price":0,"overage_per_1000_prompts":null}}}