Get started

Developer quickstart

Create a key, install an SDK and make your first System One request.

1. Create an API key

Sign up with Google, GitHub or email, then open the dashboard and create a key. Every account starts with 100M free input tokens. The key is shown only once, so store it somewhere safe, then export it along with the base URL:

Shell

export TYPESAFE_API_KEY="sk-codiv-..."
export TYPESAFE_BASE_URL="https://api.codiv.ai"

Why TYPESAFE_*?

Codiv speaks the same wire format as TypeSafe's Jev, so TypeSafe's official SDKs work unchanged. They read these two variables.

2. Install an SDK

pip install typesafe-sdk

npm install @typesafe-ai/sdk

# nothing to install

3. Make a request

This asks three questions about one support message:

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"

4. Read the answers

Answers are keyed by the ids you chose. choice and score answers carry the full probability distribution and a confidence between 0 and 1. noul answers are the probability of yes.

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}
}

Only usage.input_tokens counts toward your quota. The dashboard shows it within seconds of each request.

Next steps

Write better questions with instructions and criteria.
Use probabilities and confidence to set thresholds.
Browse the API reference.