{"openapi":"3.1.0","info":{"title":"Swapvera API","description":"Connect an LLM app, capture real calls and get a statistical verdict on whether a feature can switch model.\n\nAuthenticate with `Authorization: Bearer sv_...`. The same key is `SWAPVERA_KEY` for the SDK and `SWAPVERA_LICENSE` for the CLI.\n\nBefore acting on behalf of a person, read `/agents.md`: sending production traces, storing a provider key and starting a comparison each need their approval.","version":"0.1.0"},"paths":{"/healthz":{"get":{"summary":"Health check","operationId":"healthz_healthz_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"description":"Returns `{\"ok\": true}` when the API is up."}},"/v1/trial":{"post":{"summary":"Request a free trial key","operationId":"trial_v1_trial_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrialIn"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Sends a license key to the given email. The key is never returned here, so a person with access to that inbox has to provide it. One trial per email."}},"/v1/license":{"get":{"summary":"Read the license","operationId":"license_info_v1_license_get","parameters":[],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Returns plan, remaining credits, status, period end and a masked email.","security":[{"licenseKey":[]}]}},"/v1/traces":{"post":{"summary":"Send captured calls","operationId":"traces_v1_traces_post","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TracesIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Up to 50 traces per request. Traces contain prompts and answers. The SDK calls this for you; call it directly only for a client the SDK does not wrap.","security":[{"licenseKey":[]}]}},"/v1/feedback":{"post":{"summary":"Send a signal on a trace","operationId":"feedback_v1_feedback_post","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Optional. Regenerated requests are detected without it.","security":[{"licenseKey":[]}]}},"/v1/project":{"get":{"summary":"Read the project","operationId":"project_v1_project_get","parameters":[],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Returns `features[]`, each with `group_key`, `traces_30d`, `distinct_requests`, `model`, `cost_per_1k` and `suggestions[]` (`to_model`, `n_cases`, `est_generation_usd`), plus `experiments[]`, `credits` and `providers_with_keys`. Use it to confirm that traces arrive.","security":[{"licenseKey":[]}]}},"/v1/project/keys":{"put":{"summary":"Store provider keys","operationId":"put_keys_v1_project_keys_put","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeysIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Keys are encrypted and never returned. Comparisons run on this account, so a person must approve it. Prefer that they use the dashboard. An empty string removes a key.","security":[{"licenseKey":[]}]}},"/v1/project/settings":{"put":{"summary":"Update project settings","operationId":"put_settings_v1_project_settings_put","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectSettingsIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Spending limit per comparison, trace retention in days (1 to 90) and opt-in sharing with the migration atlas.","security":[{"licenseKey":[]}]}},"/v1/experiments":{"post":{"summary":"Start a comparison","operationId":"create_experiment_v1_experiments_post","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExperimentIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Needs at least 10 captured calls for the feature and a stored key for both providers. Uses one credit and bills generations to the customer's provider account, so a person must approve it. `to_model` looks like `anthropic:model-id`.","security":[{"licenseKey":[]}]}},"/v1/experiments/{eid}":{"get":{"summary":"Read a comparison","operationId":"get_experiment_v1_experiments__eid__get","parameters":[{"name":"eid","in":"path","required":true,"schema":{"type":"string","title":"Eid"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"`status` is `queued`, `running`, `done` or `failed`. When done, `result.verdict` is `safe`, `review`, `do_not_migrate` or `inconclusive`, and `report_md` explains it.","security":[{"licenseKey":[]}]}},"/v1/experiments/{eid}/pairs":{"get":{"summary":"Download compared pairs","description":"NDJSON with the customer's own answers, for calibrating the judge against human labels.","operationId":"experiment_pairs_v1_experiments__eid__pairs_get","parameters":[{"name":"eid","in":"path","required":true,"schema":{"type":"string","title":"Eid"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"licenseKey":[]}]}},"/v1/atlas/export":{"get":{"summary":"Read the migration atlas","description":"Anonymous aggregates. Below the publication threshold, only the number of teams.","operationId":"atlas_export_v1_atlas_export_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/atlas/risk":{"post":{"summary":"Estimate migration risk","operationId":"atlas_risk_v1_atlas_risk_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskIn"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"What happened to other teams on this migration, for a profile of case kinds. Sends counts only, never cases."}},"/v1/atlas/mine":{"delete":{"summary":"Withdraw shared results","description":"Removes everything this license shared with the atlas.","operationId":"atlas_forget_v1_atlas_mine_delete","parameters":[],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"licenseKey":[]}]}}},"components":{"schemas":{"AtlasCase":{"properties":{"format":{"type":"string","enum":["json","tool","text"],"title":"Format"},"turns":{"type":"string","enum":["single","multi"],"title":"Turns"},"input_len":{"type":"string","enum":["xs","s","m","l"],"title":"Input Len"},"checks":{"items":{"type":"string","enum":["api_error","contains","contains_any","equals","json","json_schema","language","max_chars","min_chars","no_tool","not_contains","regex","tool","tool_args"]},"type":"array","maxItems":14,"title":"Checks"},"outcome":{"type":"string","enum":["worse","better","same"],"title":"Outcome"},"failed_new":{"items":{"type":"string","enum":["api_error","contains","contains_any","equals","json","json_schema","language","max_chars","min_chars","no_tool","not_contains","regex","tool","tool_args"]},"type":"array","maxItems":14,"title":"Failed New"},"reps":{"type":"integer","maximum":50.0,"minimum":1.0,"title":"Reps"}},"additionalProperties":false,"type":"object","required":["format","turns","input_len","checks","outcome","failed_new","reps"],"title":"AtlasCase"},"AtlasSubmitIn":{"properties":{"from_model":{"type":"string","maxLength":100,"title":"From Model"},"to_model":{"type":"string","maxLength":100,"title":"To Model"},"verdict":{"type":"string","enum":["safe","review","do_not_migrate","inconclusive"],"title":"Verdict"},"pref":{"type":"number","maximum":1.0,"minimum":-1.0,"title":"Pref"},"det_change":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Det Change"},"judge_consistency":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Judge Consistency"},"engine_version":{"type":"string","pattern":"^\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}$","title":"Engine Version"},"cases":{"items":{"$ref":"#/components/schemas/AtlasCase"},"type":"array","maxItems":2000,"minItems":5,"title":"Cases"}},"additionalProperties":false,"type":"object","required":["from_model","to_model","verdict","pref","engine_version","cases"],"title":"AtlasSubmitIn"},"CustomerIn":{"properties":{"status":{"anyOf":[{"type":"string","enum":["active","suspended"]},{"type":"null"}],"title":"Status"},"is_test":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Test"},"plan":{"anyOf":[{"type":"string","enum":["trial","pro","team","emergency"]},{"type":"null"}],"title":"Plan"},"period_end":{"anyOf":[{"type":"string","pattern":"^(\\d{4}-\\d{2}-\\d{2})?$"},{"type":"null"}],"title":"Period End"},"add_credits":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":-100.0},{"type":"null"}],"title":"Add Credits"},"note":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Note"},"follow_up_on":{"anyOf":[{"type":"string","pattern":"^(\\d{4}-\\d{2}-\\d{2})?$"},{"type":"null"}],"title":"Follow Up On"}},"additionalProperties":false,"type":"object","title":"CustomerIn"},"EventIn":{"properties":{"type":{"type":"string","enum":["pageview","click"],"title":"Type"},"path":{"type":"string","maxLength":200,"pattern":"^/[A-Za-z0-9._~/-]*$","title":"Path"},"label":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Label"},"referrer":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Referrer"},"utm_source":{"anyOf":[{"type":"string","maxLength":60,"pattern":"^[A-Za-z0-9._-]+$"},{"type":"null"}],"title":"Utm Source"}},"type":"object","required":["type","path"],"title":"EventIn"},"ExperimentIn":{"properties":{"group_key":{"type":"string","pattern":"^[0-9a-f]{10}$","title":"Group Key"},"to_model":{"type":"string","maxLength":100,"pattern":"^[a-z]+:[A-Za-z0-9._-]+$","title":"To Model"},"n_cases":{"type":"integer","maximum":300.0,"minimum":10.0,"title":"N Cases","default":150}},"type":"object","required":["group_key","to_model"],"title":"ExperimentIn"},"FeedbackIn":{"properties":{"trace_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$","title":"Trace Id"},"signal":{"type":"string","enum":["accepted","regenerated","edited","rejected","copied"],"title":"Signal"}},"type":"object","required":["trace_id","signal"],"title":"FeedbackIn"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"InviteIn":{"properties":{"email":{"type":"string","maxLength":200,"minLength":3,"title":"Email"},"plan":{"type":"string","enum":["trial","pro","team","emergency"],"title":"Plan","default":"trial"},"send_email":{"type":"boolean","title":"Send Email","default":false}},"type":"object","required":["email"],"title":"InviteIn"},"JudgeIn":{"properties":{"verdict_id":{"type":"string","title":"Verdict Id"},"items":{"items":{"$ref":"#/components/schemas/JudgeItemIn"},"type":"array","maxItems":20,"title":"Items"}},"type":"object","required":["verdict_id","items"],"title":"JudgeIn"},"JudgeItemIn":{"properties":{"context":{"additionalProperties":true,"type":"object","title":"Context"},"a":{"type":"string","maxLength":20000,"title":"A"},"b":{"type":"string","maxLength":20000,"title":"B"},"reference":{"anyOf":[{"type":"string","maxLength":20000},{"type":"null"}],"title":"Reference"},"rubric":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"title":"Rubric"}},"type":"object","required":["context","a","b"],"title":"JudgeItemIn"},"KeysIn":{"properties":{"anthropic":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"title":"Anthropic"},"openai":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"title":"Openai"},"google":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"title":"Google"}},"additionalProperties":false,"type":"object","title":"KeysIn"},"LeadIn":{"properties":{"company":{"anyOf":[{"type":"string","maxLength":120,"minLength":1},{"type":"null"}],"title":"Company"},"contact":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Contact"},"channel":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}],"title":"Channel"},"stage":{"anyOf":[{"type":"string","enum":["to_contact","contacted","replied","call","testing","would_pay","paid","lost"]},{"type":"null"}],"title":"Stage"},"next_step":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"title":"Next Step"},"follow_up_on":{"anyOf":[{"type":"string","pattern":"^(\\d{4}-\\d{2}-\\d{2})?$"},{"type":"null"}],"title":"Follow Up On"},"notes":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Notes"}},"additionalProperties":false,"type":"object","title":"LeadIn"},"ProfileIn":{"properties":{"n_cases":{"type":"integer","maximum":100000.0,"minimum":0.0,"title":"N Cases"},"format":{"additionalProperties":{"type":"integer"},"propertyNames":{"enum":["json","tool","text"]},"type":"object","title":"Format"},"checks":{"additionalProperties":{"type":"integer"},"propertyNames":{"enum":["api_error","contains","contains_any","equals","json","json_schema","language","max_chars","min_chars","no_tool","not_contains","regex","tool","tool_args"]},"type":"object","title":"Checks"}},"additionalProperties":false,"type":"object","required":["n_cases"],"title":"ProfileIn"},"ProjectSettingsIn":{"properties":{"budget_per_experiment_usd":{"anyOf":[{"type":"number","maximum":500.0,"minimum":0.5},{"type":"null"}],"title":"Budget Per Experiment Usd"},"retention_days":{"anyOf":[{"type":"integer","maximum":90.0,"minimum":1.0},{"type":"null"}],"title":"Retention Days"},"share_atlas":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Share Atlas"}},"additionalProperties":false,"type":"object","title":"ProjectSettingsIn"},"RiskIn":{"properties":{"from_model":{"type":"string","maxLength":100,"title":"From Model"},"to_model":{"type":"string","maxLength":100,"title":"To Model"},"profile":{"$ref":"#/components/schemas/ProfileIn"}},"additionalProperties":false,"type":"object","required":["from_model","to_model","profile"],"title":"RiskIn"},"StartIn":{"properties":{"from_model":{"type":"string","maxLength":200,"title":"From Model"},"to_model":{"type":"string","maxLength":200,"title":"To Model"},"n_cases":{"type":"integer","minimum":1.0,"title":"N Cases"},"max_reps":{"type":"integer","minimum":1.0,"title":"Max Reps","default":8}},"type":"object","required":["from_model","to_model","n_cases"],"title":"StartIn"},"TeamIn":{"properties":{"name":{"type":"string","maxLength":80,"minLength":1,"title":"Name"},"email":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Email"},"role":{"type":"string","enum":["viewer","support","owner"],"title":"Role"}},"type":"object","required":["name","role"],"title":"TeamIn"},"TraceIn":{"properties":{"id":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$","title":"Id"},"provider":{"type":"string","enum":["anthropic","openai","google"],"title":"Provider"},"model":{"type":"string","maxLength":100,"pattern":"^[A-Za-z0-9._:/-]+$","title":"Model"},"feature":{"anyOf":[{"type":"string","maxLength":64,"pattern":"^[\\w .:/-]+$"},{"type":"null"}],"title":"Feature"},"system":{"title":"System"},"messages":{"items":{"additionalProperties":true,"type":"object"},"type":"array","maxItems":200,"title":"Messages"},"tools":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Tools"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"output":{"type":"string","maxLength":400000,"title":"Output","default":""},"tool_calls":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Tool Calls"},"usage":{"additionalProperties":true,"type":"object","title":"Usage"},"latency_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Latency Ms"}},"type":"object","required":["id","provider","model","messages"],"title":"TraceIn"},"TracesIn":{"properties":{"traces":{"items":{"$ref":"#/components/schemas/TraceIn"},"type":"array","maxItems":50,"title":"Traces"}},"type":"object","required":["traces"],"title":"TracesIn"},"TrialIn":{"properties":{"email":{"type":"string","maxLength":200,"title":"Email"},"plan":{"type":"string","enum":["trial","pro","team","emergency"],"title":"Plan","default":"trial"}},"type":"object","required":["email"],"title":"TrialIn"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"licenseKey":{"type":"http","scheme":"bearer","bearerFormat":"sv_..."}}},"servers":[{"url":"https://swapvera.com"}]}