{"openapi":"3.1.0","info":{"title":"Newmen API","version":"0.1.0","description":"Newmen is a frontier model lab + reliability platform. The /v1 API is OpenAI-compatible and accepts `metadata.operation_id` for production tagging. Every customer-facing endpoint is described here; the SDKs and route handlers share these schemas as a single source of truth.","contact":{"name":"Newmen","url":"https://newmen.ai","email":"support@newmen.ai"}},"servers":[{"url":"https://api.newmen.ai/v1","description":"Production"},{"url":"http://localhost:3000/api/v1","description":"Local dev"}],"tags":[{"name":"Chat"},{"name":"Models"},{"name":"Feedback"},{"name":"Calls"},{"name":"Operations"},{"name":"Datasets"},{"name":"Evaluators"},{"name":"Evaluations"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key (nm_live_...)"}},"schemas":{"ErrorObject":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string"},"code":{"type":"string"},"param":{"type":["string","null"]}},"required":["message","type"]},"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorObject"}},"required":["error"]},"ShipGatesUnmetError":{"type":"object","properties":{"error":{"allOf":[{"$ref":"#/components/schemas/ErrorObject"},{"type":"object","properties":{"type":{"type":"string","enum":["ship_gates_unmet"]}}}]},"failed_gates":{"type":"array","items":{"type":"object","properties":{"evaluator_id":{"type":"string"},"min_score":{"type":"number"},"actual_score":{"type":["number","null"]}},"required":["evaluator_id","min_score","actual_score"]}}},"required":["error","failed_gates"]},"Model":{"type":"object","properties":{"id":{"type":"string","example":"atlas-1"},"object":{"type":"string","enum":["model"]},"created":{"type":"integer"},"owned_by":{"type":"string","example":"newmen"},"description":{"type":"string"}},"required":["id","object","created","owned_by"]},"ModelList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Model"}}},"required":["object","data"]},"Tier":{"type":"string","enum":["realtime","standard","batch"]},"ServedBy":{"type":"string","enum":["provider","atlas_network"]},"Quantization":{"type":"string","enum":["full","q8","q4"]},"DeliveryEvals":{"type":"object","properties":{"gates":{"type":"integer","minimum":0,"description":"Number of ship-gate evaluators bound to this call's operation."},"scheduled":{"type":"boolean","description":"True when the async eval pass will run on this call. Requires an operation with at least one bound ship gate. When false the call is recorded but not eligible for the eval-gated quality refund."}},"required":["gates","scheduled"]},"DeliveryFingerprints":{"type":"object","properties":{"prompt":{"type":"string","description":"Content-only fingerprint of the normalized prompt messages. No model, no parameters, no result. Two calls with the same prompt content yield the same `prompt` fingerprint regardless of which provider served them. Prefixed `fp_p_`."},"exchange":{"type":["string","null"],"description":"Model-agnostic fingerprint of the (prompt + assistant result) pair. Atlas uses these to detect exchanges that have been produced before — possibly by a different model — and re-route similar future prompts to the same provider/quantization that already passed your eval gates. `null` when the assistant produced no content. Prefixed `fp_e_`."},"schema":{"type":["string","null"],"description":"Fingerprint of any JSON schemas attached to the request: `response_format.json_schema` and `tools[*].function.parameters`. Two calls with the same structural contract yield the same `schema` fingerprint regardless of prompt content. `null` when the request has no schema attached. Prefixed `fp_s_`."},"cache":{"type":"string","description":"Strict response cache key. Includes the prompt, model, and every Atlas-relevant parameter (temperature, top_p, max_tokens, stop, seed, response_format, tools, tier, tier_strict). Two requests producing the same `cache` fingerprint are semantically equivalent and can share a cached response. Prefixed `fp_c_`."}},"required":["prompt","exchange","schema","cache"]},"Delivery":{"type":"object","properties":{"tier":{"$ref":"#/components/schemas/Tier"},"served_by":{"$ref":"#/components/schemas/ServedBy"},"provider":{"type":"string","description":"The upstream that actually served the call. Examples: `openai`, `anthropic`, `hyperbolic`, `deepinfra`, or `atlas-net:partner_<id>`."},"quantization":{"allOf":[{"$ref":"#/components/schemas/Quantization"},{"type":["string","null"]}]},"upgraded":{"type":"boolean","description":"True when the request specified `standard` or `batch` but Atlas could not find a cheaper path that passed the operation's eval gates, so the call was upgraded to `realtime` (and billed at realtime rates). Suppressible with `tier_strict: true`."},"eta_ms":{"type":"integer","minimum":0,"description":"For `batch` responses, the estimated time until the result is available. Omitted on `realtime` and `standard`."},"cost_usd":{"type":["number","null"],"description":"USD cost as priced at response time. Subject to refund-to-zero if the async eval pass scores below the operation's min_score. Null when token counts or upstream rates are unavailable."},"latency_ms":{"type":"integer","minimum":0,"description":"Server-measured end-to-end latency from request receipt to the final byte enqueued back to the caller, in milliseconds."},"evals":{"$ref":"#/components/schemas/DeliveryEvals"},"fingerprints":{"$ref":"#/components/schemas/DeliveryFingerprints"}},"required":["tier","served_by","provider","quantization","upgraded","cost_usd","latency_ms","evals","fingerprints"]},"ContentPart":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string"}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","enum":["image_url"]},"image_url":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"detail":{"type":"string","enum":["auto","low","high"]}},"required":["url"]}},"required":["type","image_url"]}]},"ChatMessage":{"type":"object","properties":{"role":{"type":"string","enum":["system","developer","user","assistant","tool"]},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"$ref":"#/components/schemas/ContentPart"}},{"type":"null"}]},"name":{"type":"string"},"tool_call_id":{"type":"string"},"tool_calls":{"type":"array","items":{}}},"required":["role"]},"RequestMetadata":{"type":"object","properties":{"operation_id":{"type":"string","minLength":1,"maxLength":128,"description":"Operation key OR id. Tags the call so it can be filtered in the console and rolled into per-operation datasets."}}},"ChatCompletionRequest":{"type":"object","properties":{"model":{"type":"string","example":"atlas-1"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ChatMessage"},"minItems":1},"temperature":{"type":"number","minimum":0,"maximum":2},"top_p":{"type":"number","minimum":0,"maximum":1},"max_tokens":{"type":"integer","minimum":1},"stream":{"type":"boolean"},"stop":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"presence_penalty":{"type":"number","minimum":-2,"maximum":2},"frequency_penalty":{"type":"number","minimum":-2,"maximum":2},"user":{"type":"string"},"metadata":{"$ref":"#/components/schemas/RequestMetadata"},"tier":{"allOf":[{"$ref":"#/components/schemas/Tier"},{"description":"Preferred delivery tier. Defaults to `standard` server-side. `standard` and `batch` are best-effort: Atlas may upgrade to `realtime` if no cheaper path passes the operation's eval gates, unless `tier_strict` is `true`."}]},"tier_strict":{"type":"boolean","description":"When `true`, Atlas will not silently upgrade the tier. If no path at the requested tier is available, the request fails with `tier_unavailable` instead of being served at a more expensive tier. Defaults to `false`."},"forbid_atlas_network":{"type":"boolean","description":"When `true`, Atlas will not route this call to the Atlas Network (consumer-GPU partners) regardless of `tier`. Use for prompts your compliance posture forbids leaving managed providers. Defaults to `false`; ignore for closed-weight models, which never touch the partner network."}},"required":["model","messages"]},"ChatCompletionChoice":{"type":"object","properties":{"index":{"type":"integer"},"message":{"type":"object","properties":{"role":{"type":"string","enum":["assistant"]},"content":{"type":["string","null"]}},"required":["role","content"]},"finish_reason":{"type":["string","null"],"enum":["stop","length","tool_calls","content_filter","function_call"]}},"required":["index","message","finish_reason"]},"Usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"}},"required":["prompt_tokens","completion_tokens","total_tokens"]},"ChatCompletion":{"type":"object","properties":{"id":{"type":"string","example":"chatcmpl-abc123"},"object":{"type":"string","enum":["chat.completion"]},"created":{"type":"integer"},"model":{"type":"string","example":"atlas-1"},"choices":{"type":"array","items":{"$ref":"#/components/schemas/ChatCompletionChoice"}},"usage":{"$ref":"#/components/schemas/Usage"},"delivery":{"allOf":[{"$ref":"#/components/schemas/Delivery"},{"description":"How this call was actually served. Optional for backwards compatibility — older deployments that pre-date the tier system omit it."}]}},"required":["id","object","created","model","choices","usage"]},"ChatCompletionDelta":{"type":"object","properties":{"role":{"type":"string","enum":["system","developer","user","assistant","tool"]},"content":{"type":"string"}}},"ChatCompletionChunkChoice":{"type":"object","properties":{"index":{"type":"integer"},"delta":{"$ref":"#/components/schemas/ChatCompletionDelta"},"finish_reason":{"type":["string","null"],"enum":["stop","length","tool_calls","content_filter","function_call"]}},"required":["index","delta","finish_reason"]},"ChatCompletionChunk":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["chat.completion.chunk"]},"created":{"type":"integer"},"model":{"type":"string"},"choices":{"type":"array","items":{"$ref":"#/components/schemas/ChatCompletionChunkChoice"}},"usage":{"$ref":"#/components/schemas/Usage"}},"required":["id","object","created","model","choices"]},"AnthropicContentBlock":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string"}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","enum":["image"]},"source":{"type":"object","properties":{"type":{"type":"string","enum":["base64","url"]},"media_type":{"type":"string"},"data":{"type":"string"},"url":{"type":"string","format":"uri"}},"required":["type"]}},"required":["type","source"]},{"type":"object","properties":{"type":{"type":"string","enum":["tool_use"]},"id":{"type":"string"},"name":{"type":"string"},"input":{}},"required":["type","id","name"]},{"type":"object","properties":{"type":{"type":"string","enum":["tool_result"]},"tool_use_id":{"type":"string"},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{}}]},"is_error":{"type":"boolean"}},"required":["type","tool_use_id"]}]},"AnthropicMessage":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant","system"]},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"$ref":"#/components/schemas/AnthropicContentBlock"}}]}},"required":["role","content"]},"AnthropicTool":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"input_schema":{}},"required":["name"]},"AnthropicMessagesRequest":{"type":"object","properties":{"model":{"type":"string","example":"anthropic/claude-sonnet-4"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/AnthropicMessage"},"minItems":1},"system":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string"}},"required":["type","text"]}}]},"max_tokens":{"type":"integer","minimum":1},"temperature":{"type":"number","minimum":0,"maximum":2},"top_p":{"type":"number","minimum":0,"maximum":1},"top_k":{"type":"integer","minimum":0},"stop_sequences":{"type":"array","items":{"type":"string"}},"stream":{"type":"boolean"},"tools":{"type":"array","items":{"$ref":"#/components/schemas/AnthropicTool"}},"tool_choice":{"type":"object","properties":{"type":{"type":"string","enum":["auto","any","tool"]},"name":{"type":"string"}}},"metadata":{"type":"object","properties":{"user_id":{"type":"string"},"operation_id":{"type":"string","minLength":1,"maxLength":128,"description":"Newmen extension — same semantics as on `/v1/chat/completions`."}}},"tier":{"type":"string","enum":["realtime","standard","batch"]},"tier_strict":{"type":"boolean"},"forbid_atlas_network":{"type":"boolean"}},"required":["model","messages","max_tokens"]},"AnthropicResponseContentBlock":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string"}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","enum":["tool_use"]},"id":{"type":"string"},"name":{"type":"string"},"input":{}},"required":["type","id","name"]}]},"AnthropicMessagesResponse":{"type":"object","properties":{"id":{"type":"string","example":"msg_01abc"},"type":{"type":"string","enum":["message"]},"role":{"type":"string","enum":["assistant"]},"model":{"type":"string"},"content":{"type":"array","items":{"$ref":"#/components/schemas/AnthropicResponseContentBlock"}},"stop_reason":{"type":["string","null"],"enum":["end_turn","max_tokens","stop_sequence","tool_use"]},"stop_sequence":{"type":["string","null"]},"usage":{"type":"object","properties":{"input_tokens":{"type":"integer"},"output_tokens":{"type":"integer"}},"required":["input_tokens","output_tokens"]},"delivery":{"$ref":"#/components/schemas/Delivery"}},"required":["id","type","role","model","content","stop_reason","usage"]},"ResponsesTool":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"parameters":{},"strict":{"type":"boolean"}},"required":["type"]},"ResponsesRequest":{"type":"object","properties":{"model":{"type":"string","example":"gpt-5.1"},"input":{"anyOf":[{"type":"string"},{"type":"array","items":{}}]},"instructions":{"type":"string","description":"High-level system instructions prepended as a leading system message."},"tools":{"type":"array","items":{"$ref":"#/components/schemas/ResponsesTool"}},"tool_choice":{},"temperature":{"type":"number","minimum":0,"maximum":2},"top_p":{"type":"number","minimum":0,"maximum":1},"max_output_tokens":{"type":"integer","minimum":1},"parallel_tool_calls":{"type":"boolean"},"stream":{"type":"boolean"},"metadata":{"type":"object","properties":{"operation_id":{"type":"string","minLength":1,"maxLength":128,"description":"Newmen extension — same semantics as on `/v1/chat/completions`."}}},"tier":{"type":"string","enum":["realtime","standard","batch"]},"tier_strict":{"type":"boolean"},"forbid_atlas_network":{"type":"boolean"}},"required":["model","input"]},"ResponsesOutputItem":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["message"]},"id":{"type":"string"},"role":{"type":"string","enum":["assistant"]},"status":{"type":"string"},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["output_text"]},"text":{"type":"string"},"annotations":{"type":"array","items":{}}},"required":["type","text"]}}},"required":["type","role","content"]},{"type":"object","properties":{"type":{"type":"string","enum":["function_call"]},"id":{"type":"string"},"call_id":{"type":"string"},"name":{"type":"string"},"arguments":{"type":"string"},"status":{"type":"string"}},"required":["type","call_id","name","arguments"]}]},"ResponsesUsage":{"type":"object","properties":{"input_tokens":{"type":"integer"},"output_tokens":{"type":"integer"},"total_tokens":{"type":"integer"}},"required":["input_tokens","output_tokens","total_tokens"]},"ResponsesResponse":{"type":"object","properties":{"id":{"type":"string","example":"resp_abc123"},"object":{"type":"string","enum":["response"]},"created_at":{"type":"integer"},"status":{"type":"string","enum":["completed","incomplete","failed","in_progress"]},"error":{},"incomplete_details":{},"model":{"type":"string"},"output":{"type":"array","items":{"$ref":"#/components/schemas/ResponsesOutputItem"}},"output_text":{"type":"string"},"usage":{"$ref":"#/components/schemas/ResponsesUsage"},"delivery":{"$ref":"#/components/schemas/Delivery"}},"required":["id","object","created_at","status","model","output","usage"]},"EmbeddingContentPart":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string"}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","enum":["image_url"]},"image_url":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"detail":{"type":"string","enum":["auto","low","high"]}},"required":["url"]}},"required":["type","image_url"]}]},"EmbeddingStructuredInput":{"type":"object","properties":{"content":{"type":"array","items":{"$ref":"#/components/schemas/EmbeddingContentPart"},"minItems":1}},"required":["content"]},"EmbeddingsInput":{"anyOf":[{"type":"string","minLength":1},{"type":"array","items":{"type":"string","minLength":1},"minItems":1},{"type":"array","items":{"$ref":"#/components/schemas/EmbeddingStructuredInput"},"minItems":1}]},"EmbeddingsRequest":{"type":"object","properties":{"model":{"type":"string","example":"atlas-embed-1"},"input":{"$ref":"#/components/schemas/EmbeddingsInput"},"encoding_format":{"type":"string","enum":["float","base64"]},"dimensions":{"type":"integer","minimum":1},"quantization":{"type":"string","enum":["full","q8","q4"]},"forbid_atlas_network":{"type":"boolean"},"user":{"type":"string"},"metadata":{"type":"object","properties":{"operation_id":{"type":"string","minLength":1,"maxLength":128,"description":"Operation key OR id. Tags the embedding call so it can be filtered in the console and rolled into per-operation datasets — same surface as `/chat/completions`."}}}},"required":["model","input"]},"EmbeddingData":{"type":"object","properties":{"object":{"type":"string","enum":["embedding"]},"index":{"type":"integer"},"embedding":{"anyOf":[{"type":"array","items":{"type":"number"}},{"type":"string"}]}},"required":["object","index","embedding"]},"EmbeddingsUsage":{"type":"object","properties":{"prompt_tokens":{"type":"integer"},"total_tokens":{"type":"integer"}},"required":["prompt_tokens","total_tokens"]},"EmbeddingsResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/EmbeddingData"}},"model":{"type":"string","example":"atlas-embed-1"},"usage":{"$ref":"#/components/schemas/EmbeddingsUsage"},"delivery":{"$ref":"#/components/schemas/Delivery"}},"required":["object","data","model","usage"]},"Feedback":{"type":"object","properties":{"id":{"type":"string"},"call_id":{"type":"string"},"user_id":{"type":["string","null"]},"rating":{"type":["string","null"],"enum":["thumbs_up","thumbs_down"]},"correction":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time","example":"2026-05-01T12:00:00Z"}},"required":["id","call_id","tags","created_at"]},"FeedbackCreateRequest":{"type":"object","properties":{"call_id":{"type":"string","example":"chatcmpl-abc123"},"rating":{"type":"string","enum":["thumbs_up","thumbs_down"]},"correction":{"type":"string","maxLength":64000},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":64}},"required":["call_id"]},"Call":{"type":"object","properties":{"id":{"type":"string","example":"chatcmpl-abc123"},"object":{"type":"string","enum":["call"]},"org_id":{"type":"string"},"operation_id":{"type":["string","null"]},"model":{"type":"string"},"model_version":{"type":"string"},"request_payload":{"type":"object","additionalProperties":{}},"response_payload":{"type":"object","additionalProperties":{}},"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"latency_ms":{"type":"integer"},"created_at":{"type":"string","format":"date-time","example":"2026-05-01T12:00:00Z"}},"required":["id","object","org_id","operation_id","model","model_version","request_payload","response_payload","prompt_tokens","completion_tokens","latency_ms","created_at"]},"CallList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Call"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more"]},"ShipGate":{"type":"object","properties":{"evaluator_id":{"type":"string"},"min_score":{"type":"number","minimum":0,"maximum":1}},"required":["evaluator_id","min_score"]},"Operation":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["operation"]},"org_id":{"type":"string"},"key":{"type":"string","example":"summarize_email"},"name":{"type":"string"},"description":{"type":["string","null"]},"ship_gates":{"type":"array","items":{"$ref":"#/components/schemas/ShipGate"}},"created_at":{"type":"string","format":"date-time","example":"2026-05-01T12:00:00Z"}},"required":["id","object","org_id","key","name","description","ship_gates","created_at"]},"OperationCreateRequest":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-z0-9_]+$"},"name":{"type":"string","minLength":1,"maxLength":256},"description":{"type":"string","maxLength":2000},"ship_gates":{"type":"array","items":{"$ref":"#/components/schemas/ShipGate"}}},"required":["key","name"]},"OperationUpdateRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":256},"description":{"type":["string","null"],"maxLength":2000},"ship_gates":{"type":"array","items":{"$ref":"#/components/schemas/ShipGate"}}}},"OperationList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Operation"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more"]},"Dataset":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["dataset"]},"org_id":{"type":"string"},"operation_id":{"type":"string"},"name":{"type":"string"},"version":{"type":"integer"},"status":{"type":"string","enum":["draft","golden"]},"promoted_at":{"type":["string","null"],"format":"date-time","example":"2026-05-01T12:00:00Z"},"created_at":{"type":"string","format":"date-time","example":"2026-05-01T12:00:00Z"}},"required":["id","object","org_id","operation_id","name","version","status","promoted_at","created_at"]},"DatasetCreateRequest":{"type":"object","properties":{"operation_id":{"type":"string"},"name":{"type":"string","minLength":1,"maxLength":256}},"required":["operation_id","name"]},"DatasetList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Dataset"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more"]},"DatasetItem":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["dataset_item"]},"dataset_id":{"type":"string"},"source_call_id":{"type":["string","null"]},"input":{},"expected_output":{},"weight":{"type":"number"},"created_at":{"type":"string","format":"date-time","example":"2026-05-01T12:00:00Z"}},"required":["id","object","dataset_id","source_call_id","weight","created_at"]},"DatasetItemCreate":{"type":"object","properties":{"source_call_id":{"type":"string"},"input":{},"expected_output":{},"weight":{"type":"number","minimum":0,"maximum":100}}},"DatasetItemsCreateRequest":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/DatasetItemCreate"},"minItems":1,"maxItems":1000}},"required":["items"]},"DatasetItemList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/DatasetItem"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more"]},"PromoteResponse":{"type":"object","properties":{"dataset":{"$ref":"#/components/schemas/Dataset"},"evaluation_id":{"type":"string"}},"required":["dataset"]},"TrainingRequest":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["training_request"]},"org_id":{"type":"string"},"dataset_id":{"type":"string"},"dataset_version":{"type":"integer"},"requested_by_user_id":{"type":"string"},"status":{"type":"string","enum":["requested","reviewing","approved","declined","completed"]},"notes":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time","example":"2026-05-01T12:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-05-01T12:00:00Z"}},"required":["id","object","org_id","dataset_id","dataset_version","requested_by_user_id","status","notes","created_at","updated_at"]},"TrainingRequestCreate":{"type":"object","properties":{"notes":{"type":"string","maxLength":8000}}},"Evaluator":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["evaluator"]},"org_id":{"type":"string"},"operation_id":{"type":["string","null"]},"name":{"type":"string"},"kind":{"type":"string","enum":["regex","json_schema","llm_judge","embedding_match"]},"config":{"type":"object","additionalProperties":{}},"created_at":{"type":"string","format":"date-time","example":"2026-05-01T12:00:00Z"}},"required":["id","object","org_id","operation_id","name","kind","config","created_at"]},"EvaluatorCreateRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":256},"operation_id":{"type":"string"},"kind":{"type":"string","enum":["regex","json_schema","llm_judge","embedding_match"]},"config":{"type":"object","additionalProperties":{}}},"required":["name","kind","config"]},"EvaluatorUpdateRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":256},"operation_id":{"type":["string","null"]},"config":{"type":"object","additionalProperties":{}}}},"EvaluatorList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Evaluator"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more"]},"EvaluationResult":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["evaluation_result"]},"evaluation_id":{"type":"string"},"dataset_item_id":{"type":"string"},"evaluator_id":{"type":"string"},"score":{"type":"number"},"details":{}},"required":["id","object","evaluation_id","dataset_item_id","evaluator_id","score"]},"Evaluation":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["evaluation"]},"org_id":{"type":"string"},"dataset_id":{"type":"string"},"evaluator_ids":{"type":"array","items":{"type":"string"}},"model_version":{"type":"string"},"status":{"type":"string","enum":["pending","running","done","failed"]},"summary_scores":{"type":["object","null"],"additionalProperties":{"type":"number"}},"started_at":{"type":["string","null"],"format":"date-time","example":"2026-05-01T12:00:00Z"},"completed_at":{"type":["string","null"],"format":"date-time","example":"2026-05-01T12:00:00Z"},"results":{"type":"array","items":{"$ref":"#/components/schemas/EvaluationResult"}}},"required":["id","object","org_id","dataset_id","evaluator_ids","model_version","status","summary_scores","started_at","completed_at"]},"EvaluationCreateRequest":{"type":"object","properties":{"dataset_id":{"type":"string"},"evaluator_ids":{"type":"array","items":{"type":"string"},"minItems":1},"model_version":{"type":"string"}},"required":["dataset_id","evaluator_ids"]},"EvaluationList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Evaluation"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more"]},"LimitQuery":{"type":"integer","minimum":1,"maximum":200,"default":50,"example":50},"CursorQuery":{"type":"string"}},"parameters":{"LimitQuery":{"schema":{"$ref":"#/components/schemas/LimitQuery"},"required":false,"name":"limit","in":"query"},"CursorQuery":{"schema":{"$ref":"#/components/schemas/CursorQuery"},"required":false,"name":"cursor","in":"query"}}},"paths":{"/models":{"get":{"tags":["Models"],"summary":"List models","description":"List the models available to your organization.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Models","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelList"}}}},"400":{"description":"Bad request — validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — token does not have access to this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/chat/completions":{"post":{"tags":["Chat"],"summary":"Create a chat completion","description":"OpenAI-compatible chat completions endpoint. Pass `model: \"atlas-1\"` to opt into smart routing across providers + per-operation eval-gated cost optimisation; pass an explicit model id (e.g. `openai/chatgpt-5.5`) to pin Atlas to a specific upstream. The `tier` field selects the delivery tier (`realtime` / `standard` / `batch`); the response's `delivery` block reports what Atlas actually picked. Pass `metadata.operation_id` to tag the call for production observability and unlock the eval-gated quality refund (calls that score below the operation's `min_score` are not metered). Supports streaming via Server-Sent Events when `stream: true` (not available on the `batch` tier).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionRequest"}}}},"responses":{"200":{"description":"Chat completion (or SSE stream of `ChatCompletionChunk` events if `stream: true`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletion"}},"text/event-stream":{"schema":{"$ref":"#/components/schemas/ChatCompletionChunk"}}}},"400":{"description":"Bad request — validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — token does not have access to this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/messages":{"post":{"tags":["Messages"],"summary":"Create a message (Anthropic-compatible)","description":"Anthropic Messages API drop-in. Set `ANTHROPIC_BASE_URL=https://api.newmen.ai` and `ANTHROPIC_API_KEY=nm_live_...` and any Anthropic SDK / Claude Code / compatible tool routes through Newmen. All routing, pricing, eval gates, and the tag-for-refund mechanic apply identically to `/v1/chat/completions`. Pin an OpenRouter model id (e.g. `anthropic/claude-sonnet-4`) or use `atlas-1` for smart routing.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnthropicMessagesRequest"}}}},"responses":{"200":{"description":"AnthropicMessagesResponse (or SSE stream of Anthropic Messages events when `stream: true`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnthropicMessagesResponse"}}}},"400":{"description":"Bad request — validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — token does not have access to this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/responses":{"post":{"tags":["Responses"],"summary":"Create a model response (OpenAI Responses-compatible)","description":"OpenAI Responses API drop-in. The current Codex CLI (0.121+) only speaks the Responses API; point it at Newmen by setting the base URL and an `nm_live_...` key. All routing, pricing, eval gates, and the tag-for-refund mechanic apply identically to `/v1/chat/completions`. Pin an OpenRouter model id (e.g. `openai/gpt-5.1`) or use `atlas-1` for smart routing. Supports streaming via Server-Sent Events when `stream: true`.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesRequest"}}}},"responses":{"200":{"description":"ResponsesResponse (or SSE stream of Responses events when `stream: true`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesResponse"}}}},"400":{"description":"Bad request — validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — token does not have access to this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/embeddings":{"post":{"tags":["Embeddings"],"summary":"Create one or more embeddings","description":"OpenAI- and OpenRouter-compatible embeddings endpoint. Pass `model: \"atlas-embed-1\"` to opt into smart routing across embedding providers, or pin a specific model id (e.g. `openai/text-embedding-3-large`, `qwen/qwen3-embedding-0.6b`). Accepts a single string, an array of strings, or an array of structured multimodal `{ content: [...] }` blocks. `metadata.operation_id` is recorded the same way as on `/chat/completions` so embedding workloads can be tagged, evaluated, and ship-gated alongside text generation.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbeddingsRequest"}}}},"responses":{"200":{"description":"An `EmbeddingsResponse` with one `EmbeddingData` per input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbeddingsResponse"}}}},"400":{"description":"Bad request — validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — token does not have access to this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/feedback":{"post":{"tags":["Feedback"],"summary":"Attach feedback to a call","description":"Attach a rating, correction, or tags to a previously recorded call. At least one of rating / correction / tags is required.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackCreateRequest"}}}},"responses":{"200":{"description":"Feedback recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Feedback"}}}},"400":{"description":"Bad request — validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — token does not have access to this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/calls":{"get":{"tags":["Calls"],"summary":"List calls","description":"List recorded calls, optionally filtered by operation_id.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"operation_id","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Calls","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallList"}}}},"400":{"description":"Bad request — validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — token does not have access to this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/calls/{id}":{"get":{"tags":["Calls"],"summary":"Retrieve a call","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Call","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Call"}}}},"400":{"description":"Bad request — validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — token does not have access to this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/operations":{"get":{"tags":["Operations"],"summary":"List operations","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Operations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationList"}}}},"400":{"description":"Bad request — validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — token does not have access to this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Operations"],"summary":"Create an operation","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationCreateRequest"}}}},"responses":{"201":{"description":"Operation created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Operation"}}}},"400":{"description":"Bad request — validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — token does not have access to this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/operations/{id}":{"get":{"tags":["Operations"],"summary":"Retrieve an operation","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Operation"}}}},"400":{"description":"Bad request — validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — token does not have access to this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Operations"],"summary":"Update an operation","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationUpdateRequest"}}}},"responses":{"200":{"description":"Operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Operation"}}}},"400":{"description":"Bad request — validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — token does not have access to this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/datasets":{"get":{"tags":["Datasets"],"summary":"List datasets","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Datasets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetList"}}}},"400":{"description":"Bad request — validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — token does not have access to this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Datasets"],"summary":"Create a dataset","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetCreateRequest"}}}},"responses":{"201":{"description":"Dataset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dataset"}}}},"400":{"description":"Bad request — validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — token does not have access to this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/datasets/{id}":{"get":{"tags":["Datasets"],"summary":"Retrieve a dataset","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Dataset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dataset"}}}},"400":{"description":"Bad request — validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — token does not have access to this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/datasets/{id}/items":{"post":{"tags":["Datasets"],"summary":"Add items to a dataset","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetItemsCreateRequest"}}}},"responses":{"201":{"description":"Items","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetItemList"}}}},"400":{"description":"Bad request — validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — token does not have access to this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"tags":["Datasets"],"summary":"List items in a dataset","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Items","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetItemList"}}}},"400":{"description":"Bad request — validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — token does not have access to this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/datasets/{id}/promote":{"post":{"tags":["Datasets"],"summary":"Promote a dataset to golden (ship-gate-enforced)","description":"Marks the dataset as 'golden'. All ship gates defined on the parent operation must pass on the latest evaluation; otherwise returns 400 ship_gates_unmet.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Dataset promoted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromoteResponse"}}}},"400":{"description":"Ship gates unmet (or other validation error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipGatesUnmetError"}}}},"401":{"description":"Unauthorized — missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — token does not have access to this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/datasets/{id}/training":{"post":{"tags":["Datasets"],"summary":"Request training on a golden dataset (sales-gated)","description":"Submits a training request to Newmen sales. A row is created in `training_requests` and the sales team is emailed.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrainingRequestCreate"}}}},"responses":{"201":{"description":"Training request created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrainingRequest"}}}},"400":{"description":"Bad request — validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — token does not have access to this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/evaluators":{"get":{"tags":["Evaluators"],"summary":"List evaluators","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Evaluators","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvaluatorList"}}}},"400":{"description":"Bad request — validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — token does not have access to this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Evaluators"],"summary":"Create an evaluator","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvaluatorCreateRequest"}}}},"responses":{"201":{"description":"Evaluator","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Evaluator"}}}},"400":{"description":"Bad request — validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — token does not have access to this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/evaluators/{id}":{"get":{"tags":["Evaluators"],"summary":"Retrieve an evaluator","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Evaluator","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Evaluator"}}}},"400":{"description":"Bad request — validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — token does not have access to this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Evaluators"],"summary":"Update an evaluator","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvaluatorUpdateRequest"}}}},"responses":{"200":{"description":"Evaluator","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Evaluator"}}}},"400":{"description":"Bad request — validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — token does not have access to this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/evaluations":{"get":{"tags":["Evaluations"],"summary":"List evaluations","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Evaluations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvaluationList"}}}},"400":{"description":"Bad request — validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — token does not have access to this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Evaluations"],"summary":"Run an evaluation","description":"Runs the specified evaluators against every item in the dataset. Returns the evaluation row; results are filled in as the run progresses. Small evaluations complete inline; larger ones run via `after()`.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvaluationCreateRequest"}}}},"responses":{"201":{"description":"Evaluation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Evaluation"}}}},"400":{"description":"Bad request — validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — token does not have access to this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/evaluations/{id}":{"get":{"tags":["Evaluations"],"summary":"Retrieve an evaluation","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Evaluation (with per-item results)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Evaluation"}}}},"400":{"description":"Bad request — validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — token does not have access to this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"webhooks":{}}