API reference

Everything the Saanora API accepts and returns: each endpoint, every request and response field with its type, default and limit, the three answer shapes, the response headers and every error code. To make your first call, start with the Quickstart and come back here for the details.

Base URL and endpoints

All requests go to https://api.saanora.com over HTTPS. Bodies are JSON, sent with Content-Type: application/json and limited to 1 MB.

Every response, including errors, carries an x-request-id header. Error bodies repeat it as request_id. Quote it when you write to support@saanora.com.

Authentication

Every request needs a secret API key. Create one in the console under API keys and send it as a bearer token:

Authorization: Bearer sk_sa_...
Content-Type: application/json

Clients that cannot set Authorization can send the key as X-API-Key: sk_sa_... instead.

• Scope. Each key belongs to one project. Its requests count toward that project's usage and its optional monthly spend limit. Credit and rate limits are shared by the whole organization.
• Storage. Keys are stored only as SHA-256 hashes, so a key cannot be shown again after it is created.
• Revocation. A revoked key stops working within 60 seconds, because the gateway caches key lookups for 60 s.
• Errors. No key, or a value that is not an sk_sa_ key, returns 401 missing_api_key. An unknown or revoked key returns 401 invalid_api_key.

Create a decision

Send one record (state) and a set of typed questions about it. You get back, for every question, a probability over the options you defined. Answers are always one of your options, probabilities always sum to 1, and the model never writes free text.

Request body

A body over 1 MB returns 413 request_too_large; a body that is not JSON returns 400 invalid_json.

Question object

Each value in questions describes one question. Write instructions so it can be answered from the record alone.

Yes/no questions (noul)

Use noul for anything with a yes or no answer. criteria is optional: add it when yes and no need defining, as an object with "true" and "false" keys ("yes" and "no" are also accepted). Add threshold to have the API apply your cut-off for you.

"refund": {
  "type": "noul",
  "instructions": "Is the customer asking for their money back?",
  "criteria": {
    "true": "The customer asks for a refund or a chargeback",
    "false": "Any other request, including questions about the refund policy"
  },
  "threshold": 0.9
}

Choice questions

Use choice when exactly one of several options applies. criteria maps each option id to a short description; the ids are what you get back. 2 to 255 options.

"intent": {
  "type": "choice",
  "instructions": "What does the customer want to do with their subscription?",
  "criteria": {
    "cancel": "End the subscription",
    "upgrade": "Move to a bigger plan",
    "support": "Get help with a problem, without changing the plan"
  }
}

Score questions

Use score for an ordered scale. criteria is an array of level descriptions, lowest first, with 2 to 255 levels. Levels are referred to by their index: 0 for the first, 1 for the next, and so on. Score scales are the least reliable question type, so when a decision can be phrased as yes/no or as a choice, prefer that.

"severity": {
  "type": "score",
  "instructions": "How severe is the business impact?",
  "criteria": ["none", "low", "high", "critical"]
}

Modes: fast and consistent

Both modes return the same response shape. The difference is how the record is read and what is billed.

For example, a 2,000-token record with 8 questions bills a little over 2,000 tokens in fast mode (about $0.001 at $0.50 per 1M) and roughly 16,000 tokens in consistent mode (about $0.008). In both modes each question is answered on its own, so adding or removing a question never changes the others. Use consistent when steadier probabilities are worth the extra tokens: thresholds, audits, and choice questions whose options change over time, such as tool menus.

Example request

Three questions, one of each type, about a support message. The Python and TypeScript versions check for errors and print each answer.

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": "Customer writes: our nightly export has failed three nights in a row and the finance team needs it by 9am.",
  "questions": {
    "failing":  { "type": "noul",   "instructions": "Is a scheduled export currently failing?" },
    "team":     { "type": "choice", "instructions": "Which team should own this?",
                  "criteria": { "engineering": "Fixes broken product functionality",
                                "billing": "Handles invoices, charges and refunds" } },
    "severity": { "type": "score",  "instructions": "How severe is the business impact?",
                  "criteria": ["none", "low", "high", "critical"] }
  }
}'

Response

A successful request returns 200 OK with a decision object. This is the response to the example above:

{
  "id": "dec_1eab8757a66cc4fba1e7d9f7",
  "object": "decision",
  "created": 1792431238,
  "model": "clara-1",
  "mode": "fast",
  "answers": {
    "failing": { "type": "noul", "noul": 0.996 },
    "team": {
      "type": "choice", "choice": "billing", "confidence": 0.317,
      "probabilities": { "engineering": 0.341, "billing": 0.659 }
    },
    "severity": {
      "type": "score", "score": 2.48, "confidence": 0.511,
      "probabilities": { "0": 0.001, "1": 0.004, "2": 0.511, "3": 0.484 },
      "legend": { "0": "none", "1": "low", "2": "high", "3": "critical" }
    }
  },
  "usage": { "input_tokens": 191, "decisions": 3, "cost_usd": 0.000096 },
  "latency_ms": 279.6
}

Clara costs $0.50 per 1M input tokens and $0 for output, with no per-decision fee. The example above billed 191 tokens: 191 × $0.50 / 1,000,000 = $0.0000955, rounded up to $0.000096. Each request's cost is rounded up to the nearest $0.000001. Before the model runs, a hold covering the worst case is placed on your credit; the exact cost is deducted afterward. If the hold cannot be covered, the request fails with 402 insufficient_credit and nothing runs. Failed requests are free. See Billing and credit.

Yes/no answer

The refund question above, with threshold 0.9, could come back as:

"refund": { "type": "noul", "noul": 0.93, "threshold": 0.9, "decision": true }

Choice answer

For the intent question above, with 3 options and 0.94 on support: (0.94 - 1/3) / (1 - 1/3) = 0.91.

"intent": {
  "type": "choice",
  "choice": "support",
  "probabilities": { "cancel": 0.04, "upgrade": 0.02, "support": 0.94 },
  "confidence": 0.91
}

Score answer

For the severity question in the example: 0 × 0.001 + 1 × 0.004 + 2 × 0.511 + 3 × 0.484 = 2.48, so the impact sits between "high" and "critical", nearly halfway. The most likely single level is the key with the highest probability, here "2" ("high").

"severity": {
  "type": "score",
  "score": 2.48,
  "legend": { "0": "none", "1": "low", "2": "high", "3": "critical" },
  "probabilities": { "0": 0.001, "1": 0.004, "2": 0.511, "3": 0.484 },
  "confidence": 0.511
}

Response headers

The x-ratelimit-* and saanora-processing-ms headers come with every response that reached the model, successful or not. A 429 rate_limit_exceeded carries the x-ratelimit-* headers and Retry-After. Any other error carries only x-request-id.

List models

Returns the live models. Use it to check that a key works, or to confirm a model id before you send it. It needs the same API key as every other endpoint.

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

The response:

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

Mark (mark-1), the language model behind Saanora Chat, is coming soon. Until it opens, requests to it return 404 model_not_found. See Models for benchmarks and known limitations.

System One compatibility

For clients written for the open System One format, such as JevBench. Point the client at https://api.saanora.com/v1/systemone and send your key in the Authorization header.

• The body is the same as /v1/decisions, except that model is optional and defaults to clara-1.
• The response, headers, errors, rate limits and billing are the same as /v1/decisions.
• mode works the same way, in the body or as ?mode=.

curl https://api.saanora.com/v1/systemone \
  -H "Authorization: Bearer $SAANORA_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 120 \
  -d '{
  "state": "Customer writes: our nightly export has failed three nights in a row.",
  "questions": {
    "failing": { "type": "noul", "instructions": "Is a scheduled export currently failing?" }
  }
}'

Errors

Errors use standard HTTP status codes and a JSON body. Branch on error.code; message is written for people and can change.

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_criteria",
    "message": "choice needs criteria with 2 to 255 options",
    "param": "questions.team.criteria"
  },
  "request_id": "req_5b0c2e8f9a1d4c7b3e6f8a20"
}

Error codes

Limits

Rate limits apply to the whole organization, across all projects, keys and models. Both are sliding 60-second windows. Tokens per minute counts billed tokens, the same number as usage.input_tokens; failed or refused requests do not count. Your tier rises automatically the moment both conditions are met.

Beyond Tier 5, write to support@saanora.com. More in Rate limits.