> ## Documentation Index > Fetch the complete documentation index at: https://docs.typesafe.ai/llms.txt > Use this file to discover all available pages before exploring further. # System One > Answer one or more questions about the content supplied in `state`. You can mix question types in one request. Answers use the same names as the questions, so you can match each result to its question. The response also includes the model used and token usage. ## OpenAPI ````yaml https://api.typesafe.ai/openapi.json post /v1/systemone openapi: 3.1.0 info: title: TypeSafe description: >- Ask yes/no questions, evaluate statements, select choices, or assign ratings to your content. Send your API key in the Authorization header as `Bearer `. Use GET /v1/models to discover available model names. version: 0.2.0 servers: - url: https://api.typesafe.ai security: [] paths: /v1/systemone: post: summary: System One description: >- Answer one or more questions about the content supplied in `state`. You can mix question types in one request. Answers use the same names as the questions, so you can match each result to its question. The response also includes the model used and token usage. 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' example: 'true' - name: TypeSafe-Danger-Zone-Long-Context in: header description: Set to true to use long context. schema: type: string enum: - 'true' example: 'true' requestBody: content: application/json: schema: $ref: '#/components/schemas/SystemOneRequest' examples: noul: summary: Noul value: model: jev-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: jev-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: jev-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/SystemOneRequest' 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/SystemOneResponse' examples: noul: summary: Noul value: model: jev-latest answers: billing: type: noul noul: 0.98 usage: input_tokens: 120 output_tokens: 12 choice: summary: Choice value: model: jev-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: jev-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 '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - HTTPBearer: [] components: schemas: SystemOneRequest: properties: model: type: string title: Model description: >- Name or alias of the model to use. Available names are returned by GET /v1/models. examples: - jev-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/Question' 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/Asset' 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. SystemOneResponse: 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: - jev-latest answers: additionalProperties: $ref: '#/components/schemas/Answer' 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/Usage' 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. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' 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. Question: oneOf: - $ref: '#/components/schemas/NoulQuestion' title: Noul - $ref: '#/components/schemas/ChoiceQuestion' title: Choice - $ref: '#/components/schemas/ScoreQuestion' title: Score - $ref: '#/components/schemas/BoxQuestion' 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. Asset: 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. Answer: oneOf: - $ref: '#/components/schemas/NoulAnswer' title: Noul - $ref: '#/components/schemas/ChoiceAnswer' title: Choice - $ref: '#/components/schemas/ScoreAnswer' title: Score - $ref: '#/components/schemas/BoxAnswer' 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. Usage: 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. ValidationError: 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. NoulQuestion: 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/NoulCriteria' - 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. ChoiceQuestion: 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. ScoreQuestion: 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. BoxQuestion: 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. NoulAnswer: 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. ChoiceAnswer: 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. ScoreAnswer: 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. BoxAnswer: properties: type: type: string const: box title: Type description: Identifies a box answer. examples: - box box: $ref: '#/components/schemas/BoxCoordinates' 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. NoulCriteria: 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. BoxCoordinates: 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. securitySchemes: HTTPBearer: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.