Quickstart

Make your first call to Sonoe in a few minutes: create an account, create a key, ask a question.

1. Create an account

Go to sonoeai.com and sign up with your email. New accounts start on a trial of 5,000 tokens a month, enough for a few dozen requests while you try things out.

2. Create an API key

In the console, open API keys and choose New key. Give it a name (for example, the app that will use it) and, if you like, a monthly token limit for that key alone.

The full key (sk_sonoe_…) is shown only once. Copy it and keep it as a secret on your server:

export SONOE_API_KEY="sk_sonoe_..."

3. Ask a question

curl https://api.sonoeai.com/v1/systemone \
  -H "Authorization: Bearer $SONOE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sonoe-latest",
    "state": "My card was charged twice and I want my money back.",
    "questions": {
      "team": {
        "type": "choice",
        "instructions": "Which team should handle this?",
        "criteria": { "billing": "Payments, charges, refunds", "shipping": "Deliveries", "sales": null }
      }
    }
  }'

import os
import requests

r = requests.post(
    "https://api.sonoeai.com/v1/systemone",
    headers={"Authorization": f"Bearer {os.environ['SONOE_API_KEY']}"},
    json={
        "model": "sonoe-latest",
        "state": "My card was charged twice and I want my money back.",
        "questions": {
            "team": {
                "type": "choice",
                "instructions": "Which team should handle this?",
                "criteria": {"billing": "Payments, charges, refunds", "shipping": "Deliveries", "sales": None},
            }
        },
    },
    timeout=10,
)
r.raise_for_status()
team = r.json()["answers"]["team"]
print(team["choice"], team["confidence"])

const r = await fetch("https://api.sonoeai.com/v1/systemone", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SONOE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "sonoe-latest",
    state: "My card was charged twice and I want my money back.",
    questions: {
      team: {
        type: "choice",
        instructions: "Which team should handle this?",
        criteria: { billing: "Payments, charges, refunds", shipping: "Deliveries", sales: null },
      },
    },
  }),
});
if (!r.ok) throw new Error(`Sonoe: ${r.status}`);
const { answers } = await r.json();
console.log(answers.team.choice, answers.team.confidence);

The answer:

{
  "model": "sonoe-1.1.0",
  "answers": {
    "team": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.9958, "shipping": 0.0017, "sales": 0.0025 },
      "confidence": 0.9727
    }
  },
  "usage": { "input_tokens": 112, "output_tokens": 0 }
}

4. Or use an SDK

TypeSafe's official SDKs work with Sonoe as they are. Install one and set two environment variables:

pip install typesafe-sdk
export TYPESAFE_BASE_URL="https://api.sonoeai.com"
export TYPESAFE_API_KEY="$SONOE_API_KEY"

from typesafe_sdk import Choice, TypeSafeClient

client = TypeSafeClient()
result = client.system_one(
    "My card was charged twice and I want my money back.",
    {"team": Choice(instructions="Which team should handle this?",
                    criteria={"billing": "Payments, charges, refunds", "shipping": "Deliveries", "sales": None})},
)
print(result.choices["team"].choice)

npm install @typesafe-ai/sdk
export TYPESAFE_BASE_URL="https://api.sonoeai.com"
export TYPESAFE_API_KEY="$SONOE_API_KEY"

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

const client = new TypeSafeClient();
const { answers } = await client.systemOne({
  state: "My card was charged twice and I want my money back.",
  questions: {
    team: choice("Which team should handle this?", {
      billing: "Payments, charges, refunds",
      shipping: "Deliveries",
      sales: null,
    }),
  },
});
console.log(answers.team.choice);

Next steps

StateWhat to send, and how to shape it.QuestionsPick the right question type.Errors and limitsStatus codes, quotas and retries.