{"openapi":"3.1.0","info":{"title":"Sieve public API","version":"0.2.0","description":"The public Decisions and TypeSafe-compatible System One APIs."},"servers":[{"url":"https://sandbox.api.sthanika.ai","description":"Sandbox"},{"url":"http://{host}:{port}","description":"Local gateway (your machine)","variables":{"host":{"default":"127.0.0.1","description":"Loopback host: 127.0.0.1, localhost or [::1]."},"port":{"default":"8080","description":"Port the gateway listens on."}}}],"paths":{"/v1/models":{"get":{"summary":"List models","description":"List the models and aliases available to the authenticated account.\n\nPass a returned model name as `model` in a POST /v1/systemone request.\n\n**Authentication.** Send your API key as `Authorization: Bearer <key>`. A missing or invalid key is 401; a key without the right access, model or IP address is 403. See [Authentication and keys](https://docs.sieve.one/get-started/authentication).\n\n**Rate limits.** Limits apply per organisation and model (requests and input tokens per second, an optional daily input-token limit). When a limit applies, responses carry `x-ratelimit-limit-*`, `x-ratelimit-remaining-*` and `x-ratelimit-reset-*` headers. A 429 with `retry-after` can be retried after that many seconds. See [Rate limits and quotas](https://docs.sieve.one/guides/rate-limits-and-quotas).\n\n**Errors.** Every response carries `x-typesafe-request-id`; quote it to support. Errors use the TypeSafe shape `{\"detail\": {\"error_type\", \"message\"}}`; 422 lists each validation problem. See [Errors](https://docs.sieve.one/decisions/errors) and [Errors and retries](https://docs.sieve.one/guides/errors-and-retries).","operationId":"models_v1_v1_models_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemOneModelMetadataList"}}},"headers":{"x-typesafe-request-id":{"description":"Request ID (req_ + 32 hex). Quote it when you contact support.","schema":{"type":"string"}}}},"401":{"description":"Missing, malformed, unknown, expired or revoked API key (`authentication_error`). Do not retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemOneSieveError"},"example":{"detail":{"error_type":"authentication_error","message":"Must supply an API key! Check your request and try again."}}}}},"403":{"description":"The key is valid but not allowed: organisation suspended, IP outside the allowlist, access level does not cover the route, or model not on the key's list. Do not retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemOneSieveError"},"example":{"detail":{"error_type":"permission_error","message":"This API key cannot use model sieve-31b."}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemOneHTTPValidationError"}}}},"429":{"description":"Rate or daily limit (`rate_limit_error`), or no credit left (`insufficient_quota`, no `retry-after`). Retry after `retry-after` when it is present; without it a retry will not help soon.","headers":{"retry-after":{"description":"Seconds to wait before retrying, when a retry can help.","schema":{"type":"integer"}},"retry-after-ms":{"description":"The same wait in milliseconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemOneSieveError"},"example":{"detail":{"error_type":"rate_limit_error","message":"Rate limit exceeded for requests. Retry after the time in the retry-after header."}}}}},"500":{"description":"Internal error. Retry with backoff; if it persists, send the request ID to support@sthanika.ai.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemOneSieveError"},"example":{"detail":{"error_type":"internal_error","message":"Internal server error."}}}}},"503":{"description":"Model temporarily unavailable or switched off. Retry after `retry-after` when present.","headers":{"retry-after":{"description":"Seconds to wait before retrying, when a retry can help.","schema":{"type":"integer"}},"retry-after-ms":{"description":"The same wait in milliseconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemOneSieveError"},"example":{"detail":{"error_type":"service_unavailable","message":"The model is temporarily unavailable. Please retry shortly."}}}}}},"security":[{"HTTPBearer":[]}]}},"/v1/systemone":{"post":{"summary":"System One","description":"Answer one or more questions about the content supplied in `state`.\n\nYou can mix question types in one request. Answers use the same names as the\nquestions, so you can match each result to its question. The response also includes\nthe model used and token usage.\n\n**Authentication.** Send your API key as `Authorization: Bearer <key>`. A missing or invalid key is 401; a key without the right access, model or IP address is 403. See [Authentication and keys](https://docs.sieve.one/get-started/authentication).\n\n**Rate limits.** Limits apply per organisation and model (requests and input tokens per second, an optional daily input-token limit). When a limit applies, responses carry `x-ratelimit-limit-*`, `x-ratelimit-remaining-*` and `x-ratelimit-reset-*` headers. A 429 with `retry-after` can be retried after that many seconds. See [Rate limits and quotas](https://docs.sieve.one/guides/rate-limits-and-quotas).\n\n**Errors.** Every response carries `x-typesafe-request-id`; quote it to support. Errors use the TypeSafe shape `{\"detail\": {\"error_type\", \"message\"}}`; 422 lists each validation problem. See [Errors](https://docs.sieve.one/decisions/errors) and [Errors and retries](https://docs.sieve.one/guides/errors-and-retries).","operationId":"systemone_v1_systemone_post","parameters":[{"name":"TypeSafe-Danger-Zone-Images","in":"header","description":"Set to true to use assets or box questions.","schema":{"type":"string","enum":["true"]}},{"name":"TypeSafe-Danger-Zone-Long-Context","in":"header","description":"Set to true to use long context.","schema":{"type":"string","enum":["true"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemOneSystemOneRequest"},"examples":{"noul":{"summary":"Noul","value":{"model":"sieve-latest","state":"I was charged twice for my subscription this month. Please refund the extra charge.","questions":{"billing":{"type":"noul","instructions":"Is this message about billing?"}}}},"choice":{"summary":"Choice","value":{"model":"sieve-latest","state":"I was charged twice for my subscription this month. Please refund the extra charge.","questions":{"tone":{"type":"choice","instructions":"What is the tone of this message?","criteria":{"angry":"An upset or hostile message","calm":"A neutral or polite message","excited":"An enthusiastic or eager message"}}}}},"score":{"summary":"Score","value":{"model":"sieve-latest","state":"I was charged twice for my subscription this month. Please refund the extra charge.","questions":{"urgency":{"type":"score","instructions":"How urgent is this message?","criteria":["Can wait","Needs attention this week","Needs attention today"]}}}},"box":{"summary":"Box (requires TypeSafe-Danger-Zone-Images: true)","value":{"model":"jev-preview","state":"photo","questions":{"red_rectangle":{"type":"box","instructions":"Locate the red rectangle."}},"assets":{"photo":{"type":"image","format":"png","data_base64":"iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAAAHElEQVR4nGP4TyJgoKcGBgbsaFQDfTUQB4aDBgDAen2fpitsVAAAAABJRU5ErkJggg=="}}}}}},"multipart/form-data":{"schema":{"type":"object","description":"The JSON request as the first part, named request, then each image as its own part. Every image part needs a unique, non-empty name and must be used by exactly one asset's part.","properties":{"request":{"description":"The JSON request, as the first part.","contentMediaType":"application/json","contentSchema":{"$ref":"#/components/schemas/SystemOneSystemOneRequest"}}},"required":["request"],"additionalProperties":{"type":"string","description":"An image, named by the asset part that uses it.","contentMediaType":"image/*"}},"encoding":{"request":{"contentType":"application/json"}}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemOneSystemOneResponse"},"examples":{"noul":{"summary":"Noul","value":{"model":"sieve-latest","answers":{"billing":{"type":"noul","noul":0.98}},"usage":{"input_tokens":120,"output_tokens":12}}},"choice":{"summary":"Choice","value":{"model":"sieve-latest","answers":{"tone":{"type":"choice","choice":"calm","confidence":0.7,"probabilities":{"angry":0.15,"calm":0.8,"excited":0.05}}},"usage":{"input_tokens":120,"output_tokens":12}}},"score":{"summary":"Score","value":{"model":"sieve-latest","answers":{"urgency":{"type":"score","score":1.7,"confidence":0.55,"legend":{"0":"Can wait","1":"Needs attention this week","2":"Needs attention today"},"probabilities":{"0":0.1,"1":0.1,"2":0.8}}},"usage":{"input_tokens":120,"output_tokens":12}}},"box":{"summary":"Box","value":{"model":"jev-preview","answers":{"red_rectangle":{"type":"box","box":{"top":0.2,"bottom":0.66,"left":0.19,"right":0.68},"confidence":null}},"usage":{"input_tokens":285,"output_tokens":20}}}}}},"headers":{"x-typesafe-request-id":{"description":"Request ID (req_ + 32 hex). Quote it when you contact support.","schema":{"type":"string"}},"x-ratelimit-limit-requests":{"description":"Sent when a requests limit applies: the limit.","schema":{"type":"string"}},"x-ratelimit-remaining-requests":{"description":"Sent when a requests limit applies: what is left in the window.","schema":{"type":"string"}},"x-ratelimit-reset-requests":{"description":"Sent when a requests limit applies: time until the window resets.","schema":{"type":"string"}},"x-ratelimit-limit-input-tokens":{"description":"Sent when a input-tokens limit applies: the limit.","schema":{"type":"string"}},"x-ratelimit-remaining-input-tokens":{"description":"Sent when a input-tokens limit applies: what is left in the window.","schema":{"type":"string"}},"x-ratelimit-reset-input-tokens":{"description":"Sent when a input-tokens limit applies: time until the window resets.","schema":{"type":"string"}}}},"400":{"description":"Bad request: unknown model (`api_usage_error`), a request over the token limits (`max_tokens_exceeded`) or a broken request rule (`invalid_request`). Do not retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemOneSieveError"},"example":{"detail":{"error_type":"api_usage_error","message":"Unknown model: nope"}}}}},"401":{"description":"Missing, malformed, unknown, expired or revoked API key (`authentication_error`). Do not retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemOneSieveError"},"example":{"detail":{"error_type":"authentication_error","message":"Must supply an API key! Check your request and try again."}}}}},"403":{"description":"The key is valid but not allowed: organisation suspended, IP outside the allowlist, access level does not cover the route, or model not on the key's list. Do not retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemOneSieveError"},"example":{"detail":{"error_type":"permission_error","message":"This API key cannot use model sieve-31b."}}}}},"404":{"description":"Unknown custom model (an `adp_…` or `ft:…` name your organisation does not have).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemOneSieveError"},"example":{"detail":{"error_type":"not_found_error","message":"Model not found: ft:my-model"}}}}},"413":{"description":"Body over 32 MiB before or after decompression, or an image over a size limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemOneSieveError"},"example":{"detail":{"error_type":"request_too_large","message":"Request body is larger than 32 MiB (before or after decompression)."}}}}},"415":{"description":"Unsupported `Content-Encoding` (only one layer of gzip, x-gzip or zstd) or a Content-Type other than JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemOneSieveError"},"example":{"detail":{"error_type":"unsupported_media_type","message":"Use application/json for this endpoint."}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemOneHTTPValidationError"}}}},"429":{"description":"Rate or daily limit (`rate_limit_error`), or no credit left (`insufficient_quota`, no `retry-after`). Retry after `retry-after` when it is present; without it a retry will not help soon.","headers":{"retry-after":{"description":"Seconds to wait before retrying, when a retry can help.","schema":{"type":"integer"}},"retry-after-ms":{"description":"The same wait in milliseconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemOneSieveError"},"example":{"detail":{"error_type":"rate_limit_error","message":"Rate limit exceeded for requests. Retry after the time in the retry-after header."}}}}},"500":{"description":"Internal error. Retry with backoff; if it persists, send the request ID to support@sthanika.ai.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemOneSieveError"},"example":{"detail":{"error_type":"internal_error","message":"Internal server error."}}}}},"503":{"description":"Model temporarily unavailable or switched off. Retry after `retry-after` when present.","headers":{"retry-after":{"description":"Seconds to wait before retrying, when a retry can help.","schema":{"type":"integer"}},"retry-after-ms":{"description":"The same wait in milliseconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemOneSieveError"},"example":{"detail":{"error_type":"service_unavailable","message":"The model is temporarily unavailable. Please retry shortly."}}}}},"504":{"description":"The model did not answer in time. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemOneSieveError"},"example":{"detail":{"error_type":"timeout_error","message":"The model did not answer in time. Please retry."}}}}},"529":{"description":"Overloaded. Retry after `retry-after`.","headers":{"retry-after":{"description":"Seconds to wait before retrying, when a retry can help.","schema":{"type":"integer"}},"retry-after-ms":{"description":"The same wait in milliseconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemOneSieveError"},"example":{"detail":{"error_type":"overloaded","message":"The service is temporarily overloaded. Please retry shortly."}}}}}},"security":[{"HTTPBearer":[]}]}},"/v1/decisions":{"post":{"operationId":"createDecision","summary":"Answer typed questions about an input","parameters":[{"name":"Content-Encoding","in":"header","description":"Optional; gzip, x-gzip or zstd, one layer (zstd window at most 8 MiB). Anything else is 415.","schema":{"type":"string","enum":["gzip","x-gzip","zstd","identity"]}},{"name":"Idempotency-Key","in":"header","description":"Optional. Requests with the same key (per API key) within 60 s return the first response. Without it, identical bodies from the same key within 60 s are deduplicated.\n","schema":{"type":"string","maxLength":255}},{"name":"Sieve-Extras","in":"header","description":"Set to true to add the top-level `sieve` object (served version per question, temperatures, latency).","schema":{"type":"string","enum":["true"]}}],"requestBody":{"required":true,"description":"JSON, at most 32 MiB before and after decompression; UTF-8 without BOM, nesting at most 64 levels in each of input and each question's instructions, choices and levels (whole document at most 512), finite numbers only.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecisionRequest"},"examples":{"mixed":{"value":{"model":"sieve-latest","input":"I was charged twice for my subscription this month. Please refund the extra charge.","questions":[{"name":"billing","type":"predicate","instructions":"This message is about billing."},{"name":"tone","type":"choice","instructions":"What is the tone of this message?","choices":[{"value":"angry","description":"An upset or hostile message"},{"value":"calm","description":"A neutral or polite message"}]},{"name":"urgency","type":"score","instructions":"How urgent is this message?","levels":[{"label":"low","description":"Can wait"},{"label":"medium","description":"Needs attention this week"},{"label":"high","description":"Needs attention today"}]}]}}}}}},"responses":{"200":{"description":"Answers in question order.","headers":{"x-request-id":{"schema":{"type":"string"},"description":"req_ + UUIDv7 hex"},"x-ratelimit-limit-requests":{"schema":{"type":"string"}},"x-ratelimit-remaining-requests":{"schema":{"type":"string"}},"x-ratelimit-reset-requests":{"schema":{"type":"string"}},"x-ratelimit-limit-input-tokens":{"schema":{"type":"string"}},"x-ratelimit-remaining-input-tokens":{"schema":{"type":"string"}},"x-ratelimit-reset-input-tokens":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Decision"},"examples":{"mixed":{"value":{"answers":[{"name":"billing","type":"predicate","probability":0.98},{"name":"tone","type":"choice","choice":"calm","confidence":0.6,"probabilities":[{"value":"angry","probability":0.2},{"value":"calm","probability":0.8}]},{"name":"urgency","type":"score","score":1.7,"confidence":0.55,"probabilities":[{"value":0,"label":"low","probability":0.1},{"value":1,"label":"medium","probability":0.1},{"value":2,"label":"high","probability":0.8}]}],"model":"sieve-4b-2026-10-01","usage":{"input_tokens":130,"input_tokens_details":{"cache_write_tokens":0,"cached_tokens":0},"output_tokens":15,"output_tokens_details":{"reasoning_tokens":0},"total_tokens":145}}}}}}},"400":{"description":"Invalid request (code invalid_request / invalid_json), unknown model (model_not_found), stream true (unsupported_parameter), generative parameters such as max_tokens or temperature (wrong_model_type), a question type other than predicate/choice/score such as box or noul (invalid_request, param questions[i].type), a role other than user (param input[i].role), an external image URL or file_id (param input[i].content[j].image_url / .file_id; the gateway makes no outbound fetches), images on a text model (unsupported_input), request over 64k tokens (context_length_exceeded), non-UTF-8 / BOM / nesting over 64 / NaN or Infinity (invalid_request).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key (invalid_api_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key not allowed (permission_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body over 32 MiB before or after decompression (request_too_large).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Unsupported Content-Encoding, more than one layer, zstd window over 8 MiB, or Content-Type other than JSON (unsupported_media_type).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (rate_limit_error / rate_limit_exceeded). Retry after retry-after.","headers":{"retry-after":{"schema":{"type":"integer"}},"retry-after-ms":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Overloaded (service_unavailable_error / server_is_overloaded, the OpenAI convention; an engine 529 is mapped here) or model temporarily unavailable (service_unavailable_error / service_unavailable). Retry after retry-after.\n","headers":{"retry-after":{"schema":{"type":"integer"}},"retry-after-ms":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The model did not answer within 30 s (timeout_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"**Authentication.** Send your API key as `Authorization: Bearer <key>`. A missing or invalid key is 401; a key without the right access, model or IP address is 403. See [Authentication and keys](https://docs.sieve.one/get-started/authentication).\n\n**Rate limits.** Limits apply per organisation and model (requests and input tokens per second, an optional daily input-token limit). When a limit applies, responses carry `x-ratelimit-limit-*`, `x-ratelimit-remaining-*` and `x-ratelimit-reset-*` headers. A 429 with `retry-after` can be retried after that many seconds. See [Rate limits and quotas](https://docs.sieve.one/guides/rate-limits-and-quotas).\n\n**Errors.** Every response carries `x-request-id`; quote it to support. Errors use the OpenAI shape `{\"error\": {\"message\", \"type\", \"param\", \"code\"}}`. See [Errors](https://docs.sieve.one/decisions/errors) and [Errors and retries](https://docs.sieve.one/guides/errors-and-retries)."}}},"components":{"schemas":{"SystemOneAnswer":{"oneOf":[{"$ref":"#/components/schemas/SystemOneNoulAnswer","title":"Noul"},{"$ref":"#/components/schemas/SystemOneChoiceAnswer","title":"Choice"},{"$ref":"#/components/schemas/SystemOneScoreAnswer","title":"Score"},{"$ref":"#/components/schemas/SystemOneBoxAnswer","title":"Box"}],"discriminator":{"propertyName":"type","mapping":{"noul":"#/components/schemas/NoulAnswer","choice":"#/components/schemas/ChoiceAnswer","score":"#/components/schemas/ScoreAnswer","box":"#/components/schemas/BoxAnswer"}},"description":"An answer whose type matches the corresponding question."},"SystemOneAsset":{"properties":{"type":{"type":"string","const":"image","title":"Type","description":"Identifies an image asset."},"format":{"type":"string","enum":["png","jpg","jpeg"],"title":"Format","description":"The image format, required with data_base64. The actual format is detected from the bytes."},"data_base64":{"type":"string","title":"Data Base64","description":"Base64-encoded image data."},"part":{"type":"string","title":"Part","description":"In a multipart request, the name of the image part this asset uses. With part, data_base64 is ignored."}},"type":"object","title":"Asset","description":"An image that replaces its placeholder: its bytes in data_base64 with their format, or, in a multipart request, the name of the image part that holds them. Requests with images must send the header TypeSafe-Danger-Zone-Images: true."},"SystemOneBoxAnswer":{"properties":{"type":{"type":"string","const":"box","title":"Type","description":"Identifies a box answer.","examples":["box"]},"box":{"$ref":"#/components/schemas/SystemOneBoxCoordinates","description":"The box's edges as fractions of image height and width, from 0 to 1. Each coordinate is the expected value of its edge's predicted position.","examples":[{"bottom":0.66,"left":0.19,"right":0.68,"top":0.2}]},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence","description":"Confidence for the given box, from 0 to 1, with 1 being more confident. Null when the model does not provide confidence.","examples":[null,0.9]}},"type":"object","required":["type","box","confidence"],"title":"BoxAnswer","description":"A located box with normalized edge coordinates and confidence."},"SystemOneBoxCoordinates":{"properties":{"top":{"type":"number","title":"Top","description":"Top edge of the box, as a fraction of image height from the top (0-1).","examples":[0.2]},"bottom":{"type":"number","title":"Bottom","description":"Bottom edge of the box, as a fraction of image height from the top (0-1).","examples":[0.66]},"left":{"type":"number","title":"Left","description":"Left edge of the box, as a fraction of image width from the left (0-1).","examples":[0.19]},"right":{"type":"number","title":"Right","description":"Right edge of the box, as a fraction of image width from the left (0-1).","examples":[0.68]}},"type":"object","required":["top","bottom","left","right"],"title":"BoxCoordinates","description":"Normalized box edges. Vertical coordinates are measured from the top of the image; horizontal coordinates are measured from the left."},"SystemOneBoxQuestion":{"properties":{"type":{"type":"string","const":"box","title":"Type","description":"Identifies a box question."},"instructions":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"},{"type":"null"}],"x-accepts":"string | object | array","title":"Instructions","description":"What to locate in the image."}},"type":"object","required":["type"],"title":"BoxQuestion","description":"A question that locates what its instructions describe in the request's image. Requests with box questions must send the header TypeSafe-Danger-Zone-Images: true."},"SystemOneChoiceAnswer":{"properties":{"type":{"type":"string","const":"choice","title":"Type","description":"Identifies a selection from the requested choices.","examples":["choice"]},"choice":{"type":"string","title":"Choice","description":"The name of the choice with the highest probability among the question's criteria.","examples":["angry"]},"confidence":{"type":"number","title":"Confidence","description":"Confidence in the selected choice, from 0 to 1. Higher values indicate greater certainty; use lower values to flag uncertain selections for review.","examples":[0.9]},"probabilities":{"additionalProperties":{"type":"number"},"type":"object","title":"Probabilities","description":"Probability of each choice in criteria, keyed by choice name, from 0 to 1. Shows how likely the alternatives are; values sum to approximately 1.","examples":[{"angry":0.8,"calm":0.1,"excited":0.1}]}},"type":"object","required":["type","choice","confidence","probabilities"],"title":"ChoiceAnswer","description":"The selected choice, confidence, and probabilities for a choice question."},"SystemOneChoiceQuestion":{"properties":{"type":{"type":"string","const":"choice","title":"Type","description":"Identifies a question that selects one of the choices in criteria.","examples":["choice"]},"instructions":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"},{"type":"null"}],"x-accepts":"string | object | array","title":"Instructions","description":"What the model should decide when choosing an option.","examples":["What is the tone of this message?"]},"criteria":{"additionalProperties":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"},{"type":"null"}],"x-accepts":"string | object | array"},"type":"object","minProperties":1,"maxProperties":255,"title":"Criteria","description":"Choice names and descriptions of when each applies. A choice without a description is interpreted by its name alone.","examples":[{"angry":"An upset or hostile message","calm":"A neutral or polite message","excited":"An enthusiastic or eager message"}]}},"type":"object","required":["type","criteria"],"title":"ChoiceQuestion","description":"A question that selects one option from the choices you define."},"SystemOneHTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/SystemOneValidationError"},"type":"array","title":"Detail","description":"Validation errors describing which request values are missing or invalid.","examples":[[{"loc":["body","state"],"msg":"Field required","type":"missing"}]]}},"type":"object","title":"HTTPValidationError","description":"Request validation failures returned with HTTP status 422."},"SystemOneModelMetadata":{"properties":{"name":{"type":"string","title":"Name","description":"Model name or alias accepted by the request's model field.","examples":["sieve-latest"]},"description":{"type":"string","title":"Description","description":"Human-readable description of the model and its capabilities.","examples":["General-purpose system one model."]},"release_date":{"type":"string","title":"Release Date","description":"Model release date, formatted as YYYY-MM-DD.","examples":["2026-09-15"]}},"type":"object","required":["name","description","release_date"],"title":"ModelMetadata","description":"A model or model alias available to the authenticated account."},"SystemOneModelMetadataList":{"properties":{"models":{"items":{"$ref":"#/components/schemas/SystemOneModelMetadata"},"type":"array","title":"Models","description":"Available models and aliases. Use a model's name in POST /v1/systemone requests.","examples":[[{"description":"General-purpose system one model.","name":"sieve-latest","release_date":"2026-09-15"}]]}},"type":"object","required":["models"],"title":"ModelMetadataList","description":"Models and aliases available to the authenticated account."},"SystemOneNoulAnswer":{"properties":{"type":{"type":"string","const":"noul","title":"Type","description":"Identifies a yes/no answer.","examples":["noul"]},"noul":{"type":"number","title":"Noul","description":"Probability of a yes answer or a true statement, from 0 to 1. Values near 1 favor yes or true, values near 0 favor no or false, and values near 0.5 indicate uncertainty.","examples":[0.98]}},"type":"object","required":["type","noul"],"title":"NoulAnswer","description":"The probability of a yes answer or a true statement."},"SystemOneNoulCriteria":{"properties":{"true":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"},{"type":"null"}],"x-accepts":"string | object | array","title":"True","description":"What counts as a yes answer.","examples":["The message is unsolicited advertising."]},"false":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"},{"type":"null"}],"x-accepts":"string | object | array","title":"False","description":"What counts as a no answer.","examples":["The message is a legitimate conversation."]}},"type":"object","title":"NoulCriteria","description":"Criteria defining what counts as a yes or no answer."},"SystemOneNoulQuestion":{"properties":{"type":{"type":"string","const":"noul","title":"Type","description":"Identifies a yes/no question or statement.","examples":["noul"]},"instructions":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"},{"type":"null"}],"x-accepts":"string | object | array","title":"Instructions","description":"The yes/no question or statement to evaluate.","examples":["Is this message spam?","This message contains unsolicited advertising.",{"task":"Identify unsolicited advertising."}]},"criteria":{"anyOf":[{"$ref":"#/components/schemas/SystemOneNoulCriteria"},{"type":"null"}],"description":"Criteria clarifying what counts as a yes or no answer.","examples":[{"false":"A legitimate conversation","true":"Unsolicited advertising"}]}},"type":"object","required":["type"],"title":"NoulQuestion","description":"A yes/no question or statement, answered with the probability of yes or true."},"SystemOneQuestion":{"oneOf":[{"$ref":"#/components/schemas/SystemOneNoulQuestion","title":"Noul"},{"$ref":"#/components/schemas/SystemOneChoiceQuestion","title":"Choice"},{"$ref":"#/components/schemas/SystemOneScoreQuestion","title":"Score"},{"$ref":"#/components/schemas/SystemOneBoxQuestion","title":"Box"}],"discriminator":{"propertyName":"type","mapping":{"noul":"#/components/schemas/NoulQuestion","choice":"#/components/schemas/ChoiceQuestion","score":"#/components/schemas/ScoreQuestion","box":"#/components/schemas/BoxQuestion"}},"description":"A question about the supplied content."},"SystemOneScoreAnswer":{"properties":{"type":{"type":"string","const":"score","title":"Type","description":"Identifies a rating against the requested score levels.","examples":["score"]},"score":{"type":"number","title":"Score","description":"Expected score: the probability-weighted average of the rubric levels. May fall between integer levels.","examples":[1.7]},"confidence":{"type":"number","title":"Confidence","description":"Confidence in the score, from 0 to 1. Higher values indicate greater certainty; use lower values to flag uncertain ratings for review.","examples":[0.9]},"legend":{"additionalProperties":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"}],"x-accepts":"string | object | array"},"type":"object","title":"Legend","description":"The requested criteria mapped to their score levels, so you can interpret the score.","examples":[{"0":"Can wait","1":"Needs attention this week","2":"Needs attention today"}]},"probabilities":{"additionalProperties":{"type":"number"},"type":"object","title":"Probabilities","description":"Probability of each score level, from 0 to 1, using the same keys as legend. Shows how likely the alternatives are; values sum to approximately 1.","examples":[{"0":0.1,"1":0.1,"2":0.8}]}},"type":"object","required":["type","score","confidence","legend","probabilities"],"title":"ScoreAnswer","description":"An expected score with its rubric, confidence, and score-level probabilities."},"SystemOneScoreQuestion":{"properties":{"type":{"type":"string","const":"score","title":"Type","description":"Identifies a question that rates the content using the levels in criteria.","examples":["score"]},"instructions":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"},{"type":"null"}],"x-accepts":"string | object | array","title":"Instructions","description":"What the model should rate.","examples":["How urgent is this message?"]},"criteria":{"items":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"}],"x-accepts":"string | object | array"},"type":"array","minItems":1,"maxItems":10,"title":"Criteria","description":"Ordered descriptions of the score levels. Each description's position determines its score, starting at zero.","examples":[["Can wait","Needs attention this week","Needs attention today"]]}},"type":"object","required":["type","criteria"],"title":"ScoreQuestion","description":"A question that assigns a score using an ordered rubric."},"SystemOneSystemOneRequest":{"properties":{"model":{"type":"string","title":"Model","description":"Name or alias of the model to use. Available names are returned by GET /v1/models.","examples":["sieve-latest"]},"state":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"}],"x-accepts":"string | object | array","title":"State","description":"The content all questions in this request refer to.","examples":["I was charged twice. Please help.",{"message":"Please help.","subject":"Duplicate charge"}]},"questions":{"additionalProperties":{"$ref":"#/components/schemas/SystemOneQuestion"},"type":"object","minProperties":1,"title":"Questions","description":"Questions to ask about the content, each with a name you choose. The response uses those names to identify the answers.","examples":[{"billing":{"instructions":"Is this message about billing?","type":"noul"}}]},"assets":{"additionalProperties":{"$ref":"#/components/schemas/SystemOneAsset"},"type":"object","minProperties":1,"title":"Assets","description":"Media assets keyed by an opaque placeholder (recommend a per-image UUID). Each placeholder, wherever it appears as or inside a string in state, question instructions, or criteria, is replaced with the asset. Image assets require a vision-language model."}},"type":"object","required":["model","state","questions"],"title":"SystemOneRequest","description":"Content and named questions to evaluate together using a TypeSafe model."},"SystemOneSystemOneResponse":{"properties":{"model":{"type":"string","title":"Model","description":"Name of the model that answered the questions. May differ from the alias supplied in the request.","examples":["sieve-latest"]},"answers":{"additionalProperties":{"$ref":"#/components/schemas/SystemOneAnswer"},"type":"object","minProperties":1,"title":"Answers","description":"Answers keyed by the question names supplied in the request. Each answer's type matches its question's type.","examples":[{"billing":{"noul":0.98,"type":"noul"}}]},"usage":{"$ref":"#/components/schemas/SystemOneUsage","description":"Input and output token counts for this evaluation.","examples":[{"input_tokens":120,"output_tokens":12}]}},"type":"object","required":["model","answers","usage"],"title":"SystemOneResponse","description":"Answers grouped by question name, with the model used and token usage."},"SystemOneUsage":{"properties":{"input_tokens":{"type":"integer","title":"Input Tokens","description":"Number of billable input tokens used to evaluate the request.","examples":[120]},"output_tokens":{"type":"integer","title":"Output Tokens","description":"Number of output tokens used to answer the questions. Output tokens are currently free of charge.","examples":[12]}},"type":"object","required":["input_tokens","output_tokens"],"title":"Usage","description":"Token usage for the request."},"SystemOneValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location","description":"Path to the invalid value: the request location followed by field names and array indices.","examples":[["body","questions","urgency","score","criteria"]]},"msg":{"type":"string","title":"Message","description":"Human-readable explanation of the validation failure.","examples":["Field required"]},"type":{"type":"string","title":"Error Type","description":"Machine-readable validation error code.","examples":["missing"]},"input":{"title":"Input","description":"The input value that failed validation.","examples":[{"type":"score"}]},"ctx":{"type":"object","title":"Context","description":"Additional context used to explain the validation failure.","examples":[{"min_length":1}]}},"type":"object","required":["loc","msg","type"],"title":"ValidationError","description":"A request validation error at a specific field or array element."},"SystemOneSieveError":{"type":"object","description":"TypeSafe error envelope used by /v1/systemone and /v1/models for every error except 422.","required":["detail"],"properties":{"detail":{"type":"object","required":["error_type","message"],"properties":{"error_type":{"type":"string","description":"Stable machine-readable category. Match on this and the status code, not on the message.","examples":["authentication_error","api_usage_error","max_tokens_exceeded","rate_limit_error"]},"message":{"type":"string","description":"Human-readable explanation. The wording may change."}}}}},"Content":{"description":"Text, or structured JSON (object or array) rendered into the prompt.","anyOf":[{"type":"string"},{"type":"object","additionalProperties":true},{"type":"array","items":{}}]},"DecisionRequest":{"type":"object","required":["model","input","questions"],"properties":{"model":{"type":"string","description":"Decision model name, alias or versioned ID (GET /v1/models)."},"input":{"description":"A string, or messages. One user message with only text becomes the state as a string; several messages become an array of {role, content}. Images (input_image, at most 128) need a vision model and are refused with 400 until one ships.\n","oneOf":[{"type":"string"},{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/InputMessage"}}]},"questions":{"type":"array","minItems":1,"maxItems":400,"items":{"$ref":"#/components/schemas/Question"}},"stream":{"type":"boolean","const":false,"description":"Decisions are not streamed; true is a 400."},"prompt_cache_key":{"type":["string","null"],"description":"Accepted and ignored (the engine computes each state once per request; cross-request caching is salted per org)."},"prompt_cache_options":{"type":["object","null"],"description":"Accepted and ignored."},"safety_identifier":{"type":["string","null"],"description":"Accepted and ignored."}}},"InputMessage":{"description":"OpenAI SDK DecisionInputMessageParam.","type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["user"],"description":"Required; only user messages. Any other role is a 400 with param input[i].role."},"type":{"const":"message"},"content":{"oneOf":[{"type":"string"},{"type":"array","items":{"oneOf":[{"type":"object","required":["type","text"],"properties":{"type":{"const":"input_text"},"text":{"type":"string"}}},{"type":"object","required":["type","image_url"],"properties":{"type":{"const":"input_image"},"image_url":{"type":"string","pattern":"^data:","description":"A base64 data URL. External http(s) URLs are refused (no outbound fetches)."},"detail":{"type":["string","null"],"enum":["low","high","auto","original",null]}}}]}}]}}},"Question":{"description":"Matches the OpenAI SDK's decision_create_params (openai-python 3.36.1).","type":"object","required":["type","instructions"],"properties":{"name":{"type":"string","minLength":1,"maxLength":256,"description":"Optional; unique among named questions; echoed in the answer (null when omitted)."},"type":{"type":"string","enum":["predicate","choice","score"]},"instructions":{"description":"The statement (predicate) or question. A string per OpenAI; JSON objects and arrays are also accepted (Sieve extension, same as System One).","$ref":"#/components/schemas/Content"},"choices":{"description":"choice only; 2 to 255 unique values. Values are typed (string or boolean): a string and a boolean with the same text, such as \"true\" and true, are distinct choices.","type":"array","minItems":2,"maxItems":255,"items":{"type":"object","required":["value"],"properties":{"value":{"oneOf":[{"type":"string","minLength":1},{"type":"boolean"}]},"description":{"$ref":"#/components/schemas/Content"}}}},"levels":{"description":"score only; 2 to 10 ordered levels (lowest first), labels unique. A level without a description is judged by its label.","type":"array","minItems":2,"maxItems":10,"items":{"type":"object","required":["label"],"properties":{"label":{"type":"string","minLength":1},"description":{"$ref":"#/components/schemas/Content"}}}}}},"Decision":{"description":"Matches the OpenAI SDK's Decision model, keys in this order (answers, model, usage); `sieve` only on request.","type":"object","required":["answers","model","usage"],"properties":{"answers":{"type":"array","description":"One answer per question, in question order.","items":{"$ref":"#/components/schemas/Answer"}},"model":{"type":"string","description":"Versioned model ID that answered (may differ from the alias sent)."},"usage":{"$ref":"#/components/schemas/Usage"},"sieve":{"type":"object","description":"Only with Sieve-Extras true — model_version, answered_by, temperature, escalated, state_tokens, latency_ms."}}},"Answer":{"oneOf":[{"$ref":"#/components/schemas/PredicateAnswer"},{"$ref":"#/components/schemas/ChoiceAnswer"},{"$ref":"#/components/schemas/ScoreAnswer"},{"$ref":"#/components/schemas/RefusalAnswer"}],"discriminator":{"propertyName":"type"}},"PredicateAnswer":{"type":"object","required":["type","probability"],"properties":{"name":{"type":["string","null"]},"type":{"const":"predicate"},"probability":{"type":"number","minimum":0,"maximum":1,"description":"P(true), 2 decimals."}}},"ChoiceAnswer":{"type":"object","required":["type","choice","confidence","probabilities"],"properties":{"name":{"type":["string","null"]},"type":{"const":"choice"},"choice":{"oneOf":[{"type":"string"},{"type":"boolean"}],"description":"Most likely value, typed as sent (first in order on ties)."},"confidence":{"type":"number","description":"(p_max - 1/n) / (1 - 1/n), 2 decimals."},"probabilities":{"type":"array","description":"In choices order; 2 decimals, rounding residue on the largest so they sum to 1.","items":{"type":"object","required":["value","probability"],"properties":{"value":{"oneOf":[{"type":"string"},{"type":"boolean"}]},"probability":{"type":"number"}}}}}},"ScoreAnswer":{"type":"object","required":["type","score","confidence","probabilities"],"properties":{"name":{"type":["string","null"]},"type":{"const":"score"},"score":{"type":"number","description":"Expected level index (0 = first level), 2 decimals."},"confidence":{"type":"number","description":"max(0, 1 - sum(p_i |i - m|) / MAD_uniform), m = most likely level; 2 decimals."},"probabilities":{"type":"array","description":"In levels order.","items":{"type":"object","required":["value","label","probability"],"properties":{"value":{"type":"integer","description":"Level index."},"label":{"type":"string"},"probability":{"type":"number"}}}}}},"RefusalAnswer":{"type":"object","description":"OpenAI AnswerAnswerResourceRefusal — {name, type} only. The other questions are still answered.","required":["type"],"properties":{"name":{"type":["string","null"]},"type":{"const":"refusal"}}},"Usage":{"type":"object","required":["input_tokens","input_tokens_details","output_tokens","output_tokens_details","total_tokens"],"properties":{"input_tokens":{"type":"integer","description":"Billed — state once plus each answered question."},"input_tokens_details":{"type":"object","properties":{"cache_write_tokens":{"type":"integer"},"cached_tokens":{"type":"integer"}}},"output_tokens":{"type":"integer","description":"Reported; priced at 0."},"output_tokens_details":{"type":"object","properties":{"reasoning_tokens":{"type":"integer"}}},"total_tokens":{"type":"integer"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type","code"],"properties":{"message":{"type":"string"},"type":{"type":"string","enum":["invalid_request_error","permission_error","rate_limit_error","service_unavailable_error","server_error"]},"param":{"type":["string","null"]},"code":{"type":["string","null"]}}}}}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"},"bearer":{"type":"http","scheme":"bearer"}}}}