Get early access

    Your own question

    A bounded question we don’t maintain, without our domain facts or reason codes.

    Built and tested, not yet deployed. Early access.

    On this page

    The question object

    • typestringrequired

      predicate (true or false), choice (one of your options) or score (one of your ordered levels).

    • instructionsstringrequired

      The question, 1 to 4,000 characters, not blank.

    • optionsarray or objectchoice

      2 to 50 names, as ["a", "b"] or as a map of name to what it means, { "a": "what a means" }.

    • levelsarrayscore

      2 to 11 levels, ordered low to high.

    Input

    An object, or text of up to 20,000 characters. Text reaches the model as { "text": … }.

    A choice

    curl "$UNDERSTANDING_API_URL/v1/understand" \
  -H "Authorization: Bearer $UNDERSTANDING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": {
      "type": "choice",
      "instructions": "Which team should handle this message?",
      "options": ["billing", "support"]
    },
    "input": "I was charged twice for the same order."
  }'
    const base = process.env.UNDERSTANDING_API_URL;
const key = process.env.UNDERSTANDING_API_KEY;

const body = {
  question: {
    type: "choice",
    instructions: "Which team should handle this message?",
    options: ["billing", "support"],
  },
  input: "I was charged twice for the same order.",
};

const res = await fetch(`${base}/v1/understand`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${key}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
});
const result = await res.json();
    import os
import requests

base = os.environ["UNDERSTANDING_API_URL"]
key = os.environ["UNDERSTANDING_API_KEY"]

body = {
    "question": {
        "type": "choice",
        "instructions": "Which team should handle this message?",
        "options": ["billing", "support"],
    },
    "input": "I was charged twice for the same order.",
}

res = requests.post(
    f"{base}/v1/understand",
    headers={"Authorization": f"Bearer {key}"},
    json=body,
    timeout=10,
)
result = res.json()
    Response

    200 OKStand-in probability1

    {
  "decision": null,
  "type": "choice",
  "answer": "billing",
  "probability": 0.93,
  "reasons": [],
  "abstain": false
}

    A predicate

    Request only: there’s no tested example response for it yet.

    curl "$UNDERSTANDING_API_URL/v1/understand" \
  -H "Authorization: Bearer $UNDERSTANDING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": {
      "type": "predicate",
      "instructions": "Does this message ask to close the account?"
    },
    "input": "Please close my card account and send me the balance."
  }'
    const base = process.env.UNDERSTANDING_API_URL;
const key = process.env.UNDERSTANDING_API_KEY;

const body = {
  question: {
    type: "predicate",
    instructions: "Does this message ask to close the account?",
  },
  input: "Please close my card account and send me the balance.",
};

const res = await fetch(`${base}/v1/understand`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${key}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
});
const result = await res.json();
    import os
import requests

base = os.environ["UNDERSTANDING_API_URL"]
key = os.environ["UNDERSTANDING_API_KEY"]

body = {
    "question": {
        "type": "predicate",
        "instructions": "Does this message ask to close the account?",
    },
    "input": "Please close my card account and send me the balance.",
}

res = requests.post(
    f"{base}/v1/understand",
    headers={"Authorization": f"Bearer {key}"},
    json=body,
    timeout=10,
)
result = res.json()

    A score

    Request only. The answer is an integer from 0 to 100: the model’s score on your levels, mapped linearly and rounded, so 0 is the first level and 100 the last. A score between two levels lands between their points.

    curl "$UNDERSTANDING_API_URL/v1/understand" \
  -H "Authorization: Bearer $UNDERSTANDING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": {
      "type": "score",
      "instructions": "How urgent is this support message?",
      "levels": [
        "not urgent",
        "low",
        "medium",
        "high",
        "critical"
      ]
    },
    "input": "My card was declined at checkout and I need to pay rent today."
  }'
    const base = process.env.UNDERSTANDING_API_URL;
const key = process.env.UNDERSTANDING_API_KEY;

const body = {
  question: {
    type: "score",
    instructions: "How urgent is this support message?",
    levels: ["not urgent", "low", "medium", "high", "critical"],
  },
  input: "My card was declined at checkout and I need to pay rent today.",
};

const res = await fetch(`${base}/v1/understand`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${key}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
});
const result = await res.json();
    import os
import requests

base = os.environ["UNDERSTANDING_API_URL"]
key = os.environ["UNDERSTANDING_API_KEY"]

body = {
    "question": {
        "type": "score",
        "instructions": "How urgent is this support message?",
        "levels": [
            "not urgent",
            "low",
            "medium",
            "high",
            "critical",
        ],
    },
    "input": "My card was declined at checkout and I need to pay rent today.",
}

res = requests.post(
    f"{base}/v1/understand",
    headers={"Authorization": f"Bearer {key}"},
    json=body,
    timeout=10,
)
result = res.json()
    Where each of five levels sits on the 0 to 100 scale
    LevelPoint on the scale
    not urgent0
    low25
    medium50
    high75
    critical100

    What comes back

    decision is null and reasons is [], unless the model declined; then reasons is ["model_declined"]. The other four fields work as for a named decision.

    Errors

    • input must be an object or text
    • question must be an object
    • question.instructions must be text of 1 to 4000 characters
    • question.options must list 2 to 50 options
    • question.options descriptions must be text
    • question.levels must list 2 to 11 ordered levels
    • question.type must be "predicate", "choice" or "score"

    Don’t send health data

    Don’t send. Raw health records, readings lists or protected health information, including in your own questions. The three health decisions take derived numbers and generic labels only, and none is open yet.