Saanora Platform documentation

Send a record, such as a support ticket, an agent conversation or an invoice, together with typed questions about it. Clara returns a probability for every option you defined, for every question, in one call. You call it over HTTPS with one API key and pay from prepaid credit.

What the API does

You describe a decision as questions with fixed options. Clara reads the record and answers each question with probabilities over those options. It never writes free text: every answer is one of your options, and the probabilities always sum to 1. That makes the result safe to branch on in code.

There are three question types:

A typical integration acts on its own when a probability is high, sends the middle band to a person and declines when it is low. One request can carry 1 to 32 questions on Tier 1 and 64 from Tier 2.

Your first request

You need an account, credit and an API key. The Quickstart covers all three. Then keep the key in an environment variable on your server:

export SAANORA_API_KEY="sk_sa_..."

This request asks two questions about one customer message: a yes/no question with a threshold, and a choice between three options.

curl https://api.saanora.com/v1/decisions \
  -H "Authorization: Bearer $SAANORA_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 120 \
  -d '{
    "model": "clara-1",
    "state": "Order A-1042, delivered Oct 5. Customer writes: the blender arrived with a cracked jar. I want my money back, not a new one.",
    "questions": {
      "damaged": {
        "type": "noul",
        "instructions": "Does the customer say the item arrived damaged?",
        "threshold": 0.9
      },
      "wants": {
        "type": "choice",
        "instructions": "What does the customer want?",
        "criteria": {
          "refund": "Their money back",
          "replacement": "A new item sent to them",
          "other": "Anything else"
        }
      }
    }
  }'

The response carries one answer per question, keyed by the ids you chose (damaged, wants):

{
  "id": "dec_3b9e71c04f2a8d65e1c07b94",
  "object": "decision",
  "created": 1792491003,
  "model": "clara-1",
  "mode": "fast",
  "answers": {
    "damaged": { "type": "noul", "noul": 0.98, "threshold": 0.9, "decision": true },
    "wants": {
      "type": "choice",
      "choice": "refund",
      "probabilities": { "refund": 0.94, "replacement": 0.04, "other": 0.02 },
      "confidence": 0.91
    }
  },
  "usage": { "input_tokens": 170, "decisions": 2, "cost_usd": 0.000085 },
  "latency_ms": 88.7
}

How a request flows

Every call to POST /v1/decisions (or POST /v1/systemone) goes through the same six steps. Credit moves at two of them: a hold before the model runs and the exact charge after it.

1. 01
   API key
   Identifies your project and organization
2. 02
   Request
   Validated and checked against your limits
3. 03
   Hold
   Worst-case cost reserved from credit
4. 04
   Model
   Clara answers every question
5. 05
   Exact charge
   Only the tokens read are billed
6. 06
   Response
   Answers, usage and headers

Core objects

Base URL and endpoints

All endpoints are served from https://api.saanora.com over HTTPS. Requests and responses are JSON.

Conventions

• Authentication: send Authorization: Bearer sk_sa_.... X-API-Key: sk_sa_... is also accepted. See Authentication.
• Size: request bodies up to 1 MB. The record (state) is a string or a JSON object (objects are rendered compactly) of up to 16K tokens; longer records are shortened in the middle.
• Mode: set "mode": "consistent" in the body or ?mode=consistent on the URL. The default is fast.
• Request ids: every response, including errors, has an x-request-id header. Include it when you contact support.
• Errors: one shape for every error. Branch on error.code; param names the offending field when there is one. See Errors.

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "invalid or revoked API key",
    "param": null
  },
  "request_id": "req_5c1e9a0b7d3f42e8a61b9c04"
}

Models

Clara (clara-1) is Saanora's frontier decision model. It scores 93.55% on AgentDecisionBench tool routing and 94.9% on a held-out customer-service yes/no set, answers five questions about one record in about 0.1 s, and returns 0% malformed answers. It works in English only.

Mark (mark-1), the language model behind Saanora Chat, is coming soon. Until it opens, requests to it return 404 model_not_found.

To see which models your key can call, list them:

curl https://api.saanora.com/v1/models \
  -H "Authorization: Bearer $SAANORA_API_KEY"

{
  "object": "list",
  "data": [
    { "id": "clara-1", "object": "model", "owned_by": "saanora", "kind": "decision", "status": "live" }
  ]
}

Benchmarks, specifications and known limitations are on Models. Before you automate on Clara's answers, check them against a few hundred of your own labelled records.

What a request costs

Clara costs $0.50 per 1M input tokens. Output is $0 and there is no per-decision fee, so a request costs usage.input_tokens × $0.50 / 1,000,000. The example above read 170 tokens and cost $0.000085. The smallest top-up, $5, buys 10M input tokens, about 58,000 requests like it.

The mode changes what is billed:

• fast (the default) reads the record once for all questions: you pay for the record plus each question once. Lowest latency and cost.
• consistent reads the record again with each question, so its answers hold steadier when options change or a question is reworded. It bills the tokens it reads, roughly the record times the number of questions, and they count toward your tokens-per-minute limit. On JevBench-mini it scores 83.6 against 81.8 for fast.

Where to go next