Documentation

Base URL

https://api.vansa.org

Default model

vansa-3.5

Output

JSON · no generated text

Try the playground ↗Install the agent skill ↗Markdown reference ↗OpenAPI schema ↗

Quickstart

Set VANSA_KEY to an API key from the console, then run this request on your server. To try Vansa without a personal key, use the public playground.

curl https://api.vansa.org/v1/systemone \
  --max-time 100 \
  -H "Authorization: Bearer $VANSA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vansa-3.5",
    "state": "Please refund my duplicate charge.",
    "questions": {
      "intent": {
        "type": "choice",
        "instructions": "What does the customer need?",
        "criteria": ["refund", "technical_support", "other"]
      }
    }
  }'

# pip install requests
import os
import requests

response = requests.post(
    "https://api.vansa.org/v1/systemone",
    headers={"Authorization": f"Bearer {os.environ['VANSA_KEY']}"},
    json={
        "model": "vansa-3.5",
        "state": "Please refund my duplicate charge.",
        "questions": {
            "intent": {
                "type": "choice",
                "instructions": "What does the customer need?",
                "criteria": ["refund", "technical_support", "other"],
            }
        },
    },
    timeout=100,
)
response.raise_for_status()
print(response.json()["answers"]["intent"])

// Node.js 18+. Run on your server.
const response = await fetch("https://api.vansa.org/v1/systemone", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.VANSA_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "vansa-3.5",
    state: "Please refund my duplicate charge.",
    questions: {
      intent: {
        type: "choice",
        instructions: "What does the customer need?",
        criteria: ["refund", "technical_support", "other"]
      }
    }
  }),
  signal: AbortSignal.timeout(100000)
});
if (!response.ok) throw new Error(await response.text());
const { answers } = await response.json();
console.log(answers.intent);

Read the selected option from answers.intent.choice and each option’s probability from answers.intent.probabilities. Question IDs are returned unchanged.

curl https://api.vansa.org/v1/systemone \
  -H "Authorization: Bearer $VANSA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vansa-3.5",
    "state": {
      "subject": "Duplicate charge on invoice #4411",
      "body": "Hi, we were billed twice for March. Please refund the duplicate today or we will cancel our plan."
    },
    "questions": {
      "department": {"type": "choice", "instructions": "Which department should handle this request?",
                     "criteria": {"billing": "invoices, payments, refunds", "technical": "bugs, outages, system errors",
                                  "sales": "pricing, new contracts", "other": "everything else"}},
      "urgency":    {"type": "score", "instructions": "How urgent is this request?",
                     "criteria": ["not urgent", "soon", "critical deadline or blocking issue"]},
      "churn_risk": {"type": "noul", "instructions": "Does the customer threaten to cancel or leave?"},
      "refund_requested": {"type": "noul", "instructions": "Does the customer explicitly ask for a refund?"}
    }
  }'

{
  "id": "req_bfe3ef4ff5f38256",
  "object": "systemone.result",
  "model": "vansa-3",
  "created": 1790309369,
  "answers": {
    "department": {
      "type": "choice",
      "choice": "billing",
      "probabilities": {"billing": 0.9922, "technical": 0.0052, "sales": 0.0009, "other": 0.0017},
      "confidence": 0.9624
    },
    "urgency": {
      "type": "score",
      "score": 1.703,
      "legend": {"0": "not urgent", "1": "soon", "2": "critical deadline or blocking issue"},
      "probabilities": {"0": 0.0578, "1": 0.1815, "2": 0.7607},
      "confidence": 0.3788
    },
    "churn_risk":       {"type": "noul", "noul": 0.8568, "probabilities": {"false": 0.1432, "true": 0.8568}, "confidence": 0.8568},
    "refund_requested": {"type": "noul", "noul": 0.8794, "probabilities": {"false": 0.1206, "true": 0.8794}, "confidence": 0.8794}
  },
  "usage": {"input_tokens": 357, "output_tokens": 0, "state_tokens": 40, "truncated": false},
  "latency_ms": 711.5
}

Authentication

POST /v1/systemone and GET /v1/me require a bearer key:

Authorization: Bearer vsk_your_key_here

To get a key, create an account in the console with your email address, Google or GitHub, then create API keys there. Keep them on your server; do not embed them in browser or mobile code. The playground uses a separate shared demo key for visitors.

Use GET /v1/me to check your key and remaining quota. GET /v1/models and GET /health are public.

You can also sign in to the usage console with an API key to see requests, input tokens, response times and estimated cost in USD and EUR. The console shows usage for that key only. See pricing and the usage calculator for the current rate. Usage estimates are not invoices.

Token balance

• Shared balance. API keys created in the console draw input tokens from their account’s token balance, which all of the account’s keys share. Monthly plan tokens are used first, then promotional tokens such as the welcome bonus, then prepaid credit. New verified accounts can receive a one-time welcome bonus of 10,000,000 tokens. One per person; a bonus can be held for review, for example for duplicate, disposable or automated sign-ups.
• What is charged. A successful request uses its usage.input_tokens. Output tokens are free, and a failed request is not charged. A request is charged once the model has answered it, even if your client closed the connection before the response arrived, including while the request was still waiting in the queue.
• Reservation. Before answering, the API holds 16,384 tokens for each prompt the request needs: one per question, more for a question with over 16 options or levels. The unused part is released when the request finishes. Near an empty balance, a request can therefore be declined with 402 even if its actual usage would have fit.
• Where to check it. Your balance, plan, prepaid credit and invoices are in the console. GET /v1/me reports the key’s request limits and usage, not the token balance. Rate limits apply separately from the token balance.
• Existing personal keys. Keys issued by the Vansa team before accounts were available keep working as before: they are not billed and keep their existing limits.

Request & response

Send JSON with Content-Type: application/json. Every question is evaluated against the same state. Request time grows with state length and question count.

Request body

Question definition

Response body

Images

A request can include up to 4 PNG or JPEG images in a top-level assets map, the same assets map as TypeSafe’s Jev (base64 images only). Each key is a reference that you also write, as text, in state: the image is placed at that point of the state and the reference stays there as its label, so a question can name it (“Does image 1 show …?”).

• Values. {"image 1": {"type": "image", "format": "jpg", "data_base64": "…"}}. type is optional and must be image; format is png, jpg or jpeg and must match the file; data_base64 is the file as plain base64 on one line, without a data: prefix. URLs are not fetched and multipart uploads are not accepted.
• References. 1–64 letters, digits, spaces, ., _ or -, starting with a letter or digit, such as image 1. No reference may contain another, so photo and photo 2 cannot be used together.
• Exactly once in the state. Each reference must appear exactly once in the string values of state, never in a key. It is matched as plain text, so choose references that occur nowhere else in your state. instructions and criteria may mention a reference as plain text; question IDs must not contain it.
• Files. At most 4,194,304 bytes per image and 6,291,456 bytes for all images of a request (decoded); each side 32–2,048 pixels. Animated PNGs and CMYK JPEGs are refused. Send upright images: EXIF rotation is not applied.
• Tokens and billing. Image tokens are input tokens: they are included in usage.input_tokens and charged at the same rate as text. On our test images, one image took about 280–312 tokens, plus a few tokens around it. An image is counted once per request, but it is part of every question’s 16,384-token prompt and counts toward the per-request work limit. usage.images and usage.image_tokens appear on requests with images only.
• Access and size. Every API key can send images, except the playground’s shared demo access. Requests with images count toward your key’s own request limits; there is no separate limit for images. A request with images may be up to 8.5 MB, sent with a Content-Length header; its text without the images must stay within 512 KB.
• Reserved text. In a request with images, state and the questions must not contain control sequences (special-token text in angle brackets).

# pip install requests
import base64
import os
import requests

with open("parcel.jpg", "rb") as f:
    photo = base64.b64encode(f.read()).decode("ascii")  # plain base64, no data: prefix

response = requests.post(
    "https://api.vansa.org/v1/systemone",
    headers={"Authorization": f"Bearer {os.environ['VANSA_KEY']}"},
    json={
        "model": "vansa-3.5",
        "state": {
            "ticket": "The parcel arrived today. The customer asks for a replacement.",
            "photo": "image 1",
        },
        "assets": {"image 1": {"type": "image", "format": "jpg", "data_base64": photo}},
        "questions": {
            "box_damaged": {"type": "noul", "instructions": "Does image 1 show visible damage to the box?"},
            "next_step": {
                "type": "choice",
                "instructions": "What should support do with the request in `ticket`?",
                "criteria": {"send_replacement": "the box in image 1 is visibly damaged",
                             "ask_for_details": "image 1 does not show the problem clearly",
                             "other": None},
            },
        },
    },
    timeout=100,
)
response.raise_for_status()
print(response.json()["usage"])

{
  "id": "req_…",
  "object": "systemone.result",
  "model": "vansa-3.5",
  "created": 1792569600,
  "answers": {
    "box_damaged": {"type": "noul", "noul": 0.9, "probabilities": {"false": 0.1, "true": 0.9}, "confidence": 0.9},
    "next_step": {
      "type": "choice",
      "choice": "send_replacement",
      "probabilities": {"send_replacement": 0.8, "ask_for_details": 0.15, "other": 0.05},
      "confidence": 0.44
    }
  },
  "usage": {"input_tokens": 561, "output_tokens": 0, "state_tokens": 25, "truncated": false, "images": 1, "image_tokens": 294},
  "latency_ms": …
}

Other endpoints

{
  "key": {"id": 3, "name": "Tomas – email triage", "prefix": "vsk_9Xk2mQ1p", "created_at": "2026-09-21T10:00:00Z", "expires_at": null},
  "limits": {"requests_per_minute": null, "requests_per_day": null},
  "usage": {"today_requests": 17, "today_remaining": null, "quota_resets_at": "2026-09-22T00:00:00Z",
            "total_requests": 231, "total_input_tokens": 88410},
  "model": "vansa-3.5"
}

Question types

All answer types return probabilities and confidence. The following examples illustrate their shapes.

choice — one option

Choose from 2–255 named options. The answer’s choice is one of your keys.

// definition
"intent": {
  "type": "choice",
  "instructions": "What does the customer want in `message`?",
  "criteria": {
    "refund": "money back or a charge reversed",
    "technical_help": "a bug, outage or integration problem",
    "cancellation": "wants to cancel or downgrade",
    "other": null
  }
}

// answer
"intent": {
  "type": "choice",
  "choice": "refund",
  "probabilities": {
    "refund": 0.91, "technical_help": 0.03,
    "cancellation": 0.04, "other": 0.02
  },
  "confidence": 0.71
}

Option descriptions may be strings, null, or other JSON values. With null, the model sees only the name. An array of unique, non-empty names also works. More than 16 options requires multiple passes; see limits.

score — an ordered scale

Define 2–32 levels, lowest first. score is the expected level on a zero-based scale: Σ(level × probability).

// definition: levels from lowest to highest
"frustration": {
  "type": "score",
  "instructions": "How frustrated does the customer sound in `message`?",
  "criteria": [
    "calm and neutral",
    "concerned but civil",
    "clearly annoyed",
    "very angry or using strong language"
  ]
}

// answer: score is the expected level (0 .. N-1)
"frustration": {
  "type": "score",
  "score": 2.31,
  "legend": {"0": "calm and neutral", "1": "concerned but civil",
             "2": "clearly annoyed", "3": "very angry or using strong language"},
  "probabilities": {"0": 0.02, "1": 0.12, "2": 0.39, "3": 0.47},
  "confidence": 0.24
}

Use the expected score to sort or threshold. For the most likely discrete level, choose the highest-probability entry; rounding score can produce a different level. legend maps zero-based indices to your descriptions.

noul — probability of yes

noul is a number from 0 to 1. The optional criteria describe what true and false mean.

// definition (criteria optional)
"is_phishing": {
  "type": "noul",
  "instructions": "Is this email a phishing or scam attempt?",
  "criteria": {
    "true": "phishing, scam, or fraud",
    "false": "a legitimate email"
  }
}

// answer: noul = probability the statement holds
"is_phishing": {
  "type": "noul",
  "noul": 0.08,
  "probabilities": {"false": 0.92, "true": 0.08},
  "confidence": 0.92
}

Use a threshold of 0.5 for a yes/no decision, or a higher threshold when false positives cost more.

Limits & data

Request quotas are set individually for each API key and may be unlimited. GET /v1/me returns your key's quotas; null means unlimited.

Latency: allow at least 100 seconds. More questions, longer states and more than 16 options take longer; bursts may queue. Split large batches into several requests. With more than 16 choice options, groups of up to 16 are evaluated first, then the group winners enter a final pass.

Access: no SLA. Create an account and API keys in the console; keys created there use your account’s token balance. The playground has shared demo access. Keys may be rate-limited or rotated.

Errors

Errors return a non-2xx HTTP status and an error object. type and message are always present; code and param are included when available.

{
  "error": {
    "type": "invalid_request_error",
    "message": "`state` must not be empty.",
    "param": "state"
  }
}

Retry 429, 502 and 503 with backoff; do not retry 400, 401, 402, 403, 404 or 413. API responses carry X-Request-Id; an unexpected 500 gives the id in its error message instead.

Additional reference

Model behavior, question-writing guidance and presets.

{
  "site": "example-garden-blog.com",
  "subject": "Guest post on example-garden-blog.com",
  "roles": "us = our outreach team buying a sponsored guest post; them = the website owner or editor",
  "counts": {
    "ours": 2,
    "theirs": 1,
    "auto_replies": 0,
    "bounces": 0,
    "days_since_last": 112,
    "last_from": "us"
  },
  "messages": [
    {
      "n": 1,
      "from": "us",
      "date": "2026-06-02",
      "text": "Hi, we would like to publish a sponsored guest post on your site for one of our clients. Do you accept guest posts, and what is your price for one article with one do-follow link?"
    },
    {
      "n": 2,
      "from": "them",
      "date": "2026-06-03",
      "text": "Hello, our price is 150 USD per post, do-follow and permanent. Payment in advance by PayPal."
    },
    {
      "n": 3,
      "from": "us",
      "date": "2026-06-04",
      "text": "Thanks, we will check with our client and get back to you."
    }
  ]
}

# pip install requests; email_state.py from https://docs.vansa.org/presets/email_state.py
import os
import requests
from email_state import build_state

VANSA_KEY = os.environ["VANSA_KEY"]  # your API key (vsk_...)
preset = requests.get("https://docs.vansa.org/presets/email-qualification.json", timeout=30).json()
state = build_state(
    site="example-garden-blog.com",
    subject="Guest post on example-garden-blog.com",
    emails=[  # every email with this site; "us" = your outreach team
        {"from": "us",   "date": "2026-06-02T09:00:00+00:00", "text": "Hi, we would like to publish a sponsored guest post ..."},
        {"from": "them", "date": "2026-06-03T10:00:00+00:00", "text": "Hello, our price is 150 USD per post, do-follow and permanent. ..."},
        {"from": "us",   "date": "2026-06-04T09:00:00+00:00", "text": "Thanks, we will check with our client and get back to you."},
    ],
)
r = requests.post(
    "https://api.vansa.org/v1/systemone",
    headers={"Authorization": f"Bearer {VANSA_KEY}"},
    json={"model": preset["model"], "state": state, "questions": preset["questions"]},
    timeout=100,
)
r.raise_for_status()
answers = r.json()["answers"]
print(answers["outcome"]["choice"], answers["mistake_gave_up_too_early"]["noul"])