Query models with the TypeSafe System One API

TypeSafe's System One API evaluates application state against typed questions and returns structured answers. On Databricks, send requests to a System One-enabled model service through Unity Gateway. The Databricks route uses the System One request and response format.

Use the System One API when an application needs a compact, structured decision instead of generated prose. It can be a good fit when response time matters, for example to decide whether a request needs escalation, choose a routing label, or score it against a rubric. Response time depends on the model service and request load.

For decisions over table rows in SQL, see the ai_decide function.

Requirements

A workspace enabled for Unity Catalog and Unity Gateway.
A Unity Catalog model service backed by a System One-compatible model. The example uses the openjev-qwen35-4b model service, whose fully qualified name is system.ai.openjev-qwen35-4b.
Permission to execute the model service.

The System One route requires a Unity Catalog model service. It does not support a model provider service or a non-Unity Catalog serving endpoint.

Query a model service

The request body contains the fully qualified model service name, the state to evaluate, and one or more named questions. Each question uses one of the noul, choice, or score types.

The following request includes one question of each type:

Bash
curl \
-u token:$DATABRICKS_TOKEN \
-X POST \
-H "Content-Type: application/json" \
-d '{
  "model": "system.ai.openjev-qwen35-4b",
  "state": {
    "message": "My card was charged twice for the same order and I need a refund.",
    "channel": "support"
  },
  "questions": {
    "is_billing": {
      "type": "noul",
      "instructions": "Is this a billing-related request?",
      "criteria": {
        "true": "The message concerns a charge, payment, invoice, or refund.",
        "false": "The message does not concern billing."
      }
    },
    "intent": {
      "type": "choice",
      "instructions": "Which intent best matches the message?",
      "criteria": {
        "refund": "The customer requests a refund.",
        "duplicate_charge": "The customer reports being charged more than once.",
        "other": "Another request."
      }
    },
    "urgency": {
      "type": "score",
      "instructions": "How urgent is the request?",
      "criteria": [
        "Can wait",
        "Needs attention soon",
        "Urgent"
      ]
    }
  }
}' \
https://<workspace_host>/ai-gateway/typesafe/v1/systemone

Use the fully qualified Unity Catalog model service name, system.ai.openjev-qwen35-4b, in the request's model field.

Request fields

Field	Type	Description
`model`	String	The fully qualified Unity Catalog model service name, such as `system.ai.openjev-qwen35-4b`.
`state`	String, object, or array	The content to evaluate. Use a string for text or structured data for records, conversations, or application state.
`questions`	Object	A non-empty map of question IDs to question definitions. The response uses the same IDs in the `answers` object.

Field	Type	Description
`model`	String	The fully qualified Unity Catalog model service name, such as `system.ai.openjev-qwen35-4b`.
`state`	String, object, or array	The content to evaluate. Use a string for text or structured data for records, conversations, or application state.
`questions`	Object	A non-empty map of question IDs to question definitions. The response uses the same IDs in the `answers` object.

Each question has a type, optional instructions, and type-specific criteria:

Noul questions

A noul question returns the probability that the answer is yes. The optional criteria object describes what true and false mean. Provide either instructions or a description for true or false. The response contains a noul number from 0 (no) to 1 (yes).

Choice questions

A choice question selects one option from the criteria object. Each option maps to a description or to null when no additional description is needed. Define 1 to 255 options. The response contains the selected choice, a probability for every option, and a confidence value.

Score questions

A score question rates the state against an ordered criteria array. The response contains a probability-weighted score, a legend that maps level indexes to the criteria, probabilities for each level, and a confidence value. Define 1 to 10 levels.

Response format

The response contains the model identifier and one answer for each question in answers. Token usage appears in usage, with input_tokens and output_tokens:

JSON
{
  "model": "<returned-model-id>",
  "answers": {
    "is_billing": {
      "type": "noul",
      "noul": 0.98
    },
    "intent": {
      "type": "choice",
      "choice": "duplicate_charge",
      "confidence": 0.965,
      "probabilities": {
        "refund": 0.023,
        "duplicate_charge": 0.977,
        "other": 0.0002
      }
    },
    "urgency": {
      "type": "score",
      "score": 1.902,
      "confidence": 0.852,
      "legend": {
        "0": "Can wait",
        "1": "Needs attention soon",
        "2": "Urgent"
      },
      "probabilities": {
        "0": 0.0069,
        "1": 0.0845,
        "2": 0.9086
      }
    }
  },
  "usage": {
    "input_tokens": 238,
    "output_tokens": 0
  }
}

This response is based on the request above, with numeric values rounded. Answers, probabilities, confidence values, token counts, and the returned model identifier vary by request and backend. The response model value identifies the model reported by the backend and can differ from the request's fully qualified model service name.

Request errors

For request validation errors, the route returns HTTP 422 with a detail array that describes the invalid request.

Requirements​

Query a model service​

Request fields​

Noul questions​

Choice questions​

Score questions​

Response format​

Request errors​

Additional resources​