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 255 options (24 on verdict-1.4).
score (required): [level, …], 2 to 10 levels ordered from lowest to highest.

OpenJev extensions (optional)

Leave these out and a request behaves exactly like Jev.

imagesarrayOptional

Up to 8 images the questions are about, as data:image/…;base64, URLs or {"content_type", "base64"} objects. JPEG, PNG, WebP or GIF, 5 MB each. About 280 input tokens per image. See Images.

stepsintegerOptional

Denoise steps per read, 1 to 8. Default 1.

samplesintegerOptional

Read 1 to 32 times with different noise and average. You pay for each read. Leave it out and the server reads again only when an answer is uncertain. Set samples: 1 for the fastest answer. See Read options.

thinkintegerOptional

Thought budget in tokens, 0 to 4096. A hard cap. Not with images.

sequentialbooleanOptional

Read question chunks in order, each seeing earlier answers. Not with images.

See Read options.

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 counts against your quota. output_tokens is 0 unless you set think, when it is the thought's length and counts too.

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}