API reference

System One

Ask typed questions about a state and get a calibrated answer to each.

Create a decision

Endpoint

POST https://api.codiv.ai/v1/systemone

Evaluates every question against the state and returns one answer per question. Authenticate with Authorization: Bearer <key>.

Request body

statestring, object or arrayRequired

What the questions are about. Objects and arrays are sent to the model as JSON.

modelstringRequired

The model to use: openjev-latest, or any id from List models. jev-latest is accepted as an alias.

questionsmap of question objectsRequired

Question id → question. At least one question is required. Ids key the answers in the response and are never shown to the model.

Question object properties

type"noul", "choice" or "score"Required

The question type. See Writing questions.

instructionsstring, object or arrayOptional

What to decide about the state.

criteriaobject or array

noul (optional): {"true": description, "false": description}.
choice (required): {option: description or null}, with 1 to 128 options.
score (required): [level, …], 2 to 10 levels ordered from lowest to highest.

Returns

A response object. The x-typesafe-request-id header identifies the request; include it when you report a problem.

curl https://api.codiv.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openjev-latest",
    "state": "Hi, my Stripe connection keeps failing with a 403 and we launch tomorrow.",
    "questions": {
      "department": {
        "type": "choice",
        "instructions": "Which team should handle this",
        "criteria": {
          "billing": "Payment or subscription issues",
          "technical": "Bugs or integration problems",
          "sales": "Pricing or account questions"
        }
      },
      "frustration": {
        "type": "score",
        "instructions": "How frustrated the customer appears",
        "criteria": ["Calm, just stating facts", "Frustrated but civil", "Very angry, strong language"]
      },
      "is_urgent": {"type": "noul", "instructions": "The message conveys urgency"}
    }
  }'

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

# Reads TYPESAFE_API_KEY and TYPESAFE_BASE_URL=https://api.codiv.ai
client = TypeSafeClient()

response = client.system_one(
    "Hi, my Stripe connection keeps failing with a 403 and we launch tomorrow.",
    {
        "department": Choice(
            instructions="Which team should handle this",
            criteria={
                "billing": "Payment or subscription issues",
                "technical": "Bugs or integration problems",
                "sales": "Pricing or account questions",
            },
        ),
        "frustration": Score(
            instructions="How frustrated the customer appears",
            criteria=["Calm, just stating facts", "Frustrated but civil", "Very angry, strong language"],
        ),
        "is_urgent": Noul(instructions="The message conveys urgency"),
    },
    model="openjev-latest",
)

print(response.choices["department"].choice)   # "technical"
print(response.scores["frustration"].score)     # 1.0
print(response.nouls["is_urgent"].noul)        # 1.0

import { TypeSafeClient, choice, noul, score } from "@typesafe-ai/sdk";

// Reads TYPESAFE_API_KEY; baseURL can also come from TYPESAFE_BASE_URL
const client = new TypeSafeClient({ baseURL: "https://api.codiv.ai" });

const response = await client.systemOne({
  model: "openjev-latest",
  state: "Hi, my Stripe connection keeps failing with a 403 and we launch tomorrow.",
  questions: {
    department: choice("Which team should handle this", {
      billing: "Payment or subscription issues",
      technical: "Bugs or integration problems",
      sales: "Pricing or account questions",
    }),
    frustration: score("How frustrated the customer appears", [
      "Calm, just stating facts",
      "Frustrated but civil",
      "Very angry, strong language",
    ]),
    is_urgent: noul("The message conveys urgency"),
  },
});

console.log(response.answers.department.choice); // "technical"

Response

{
  "model": "openjev-0.1",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "technical",
      "probabilities": {"billing": 0.0, "technical": 1.0, "sales": 0.0},
      "confidence": 1.0
    },
    "frustration": {
      "type": "score",
      "score": 1.0,
      "legend": {"0": "Calm, just stating facts", "1": "Frustrated but civil", "2": "Very angry, strong language"},
      "probabilities": {"0": 0.0, "1": 1.0, "2": 0.0},
      "confidence": 0.97
    },
    "is_urgent": {"type": "noul", "noul": 1.0}
  },
  "usage": {"input_tokens": 175, "output_tokens": 0}
}

The response object

modelstring

The exact model version that answered, for example openjev-0.1.

answersmap of answer objects

Answers keyed by your question ids. Every answer has a type matching its question.

noul answer

noulnumber

Probability of yes, between 0 and 1.

choice answer

choicestring

The most likely option.

probabilitiesmap of number

The probability of every option. The values sum to 1.

confidencenumber

1 − H(p)/ln K: 1 when certain and 0 when uniform. See Probabilities & confidence.

score answer

scorenumber

The expected level, Σ i·pᵢ, with levels numbered from 0.

legendmap of string

Your levels, keyed "0", "1", and so on.

probabilitiesmap of number

The probability of each level, keyed like legend.

confidencenumber

As for choice.

usageobject

input_tokens is what counts against your quota. output_tokens is always 0.

Answer objects

{"type": "noul", "noul": 0.93}

{"type": "choice", "choice": "bug",
 "probabilities": {"billing": 0.04, "bug": 0.95, "other": 0.01},
 "confidence": 0.81}

{"type": "score", "score": 1.62,
 "legend": {"0": "negative", "1": "neutral", "2": "positive"},
 "probabilities": {"0": 0.03, "1": 0.32, "2": 0.65},
 "confidence": 0.62}