Hesperan

(Docs)

Quick start

Create a key, send one request, read the probabilities.

1 — Create an API key

Sign in, open Console → API keys and create a key. It starts with hsp_ and is shown once. Keep it on the server side and export it:

Shell
export HESPERAN_API_KEY="hsp_…"

2 — Ask a question

Two questions about one support ticket: which team, and is it urgent?

curl
curl https://api.hesperan.com/v1/systemone \
  -H "Authorization: Bearer $HESPERAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "state": "Hi, I was charged twice for order #48213. Can you refund the second charge?", "questions": { "team": { "type": "choice", "instructions": "Which team should handle this ticket?", "criteria": { "billing": "payments, refunds, double charges", "shipping": "delivery, tracking, damaged parcels", "technical": "app errors, login problems" } }, "urgent": { "type": "noul", "instructions": "The customer has lost money and needs a reply today." } } }'
Python
import os, requests

res = requests.post(
    "https://api.hesperan.com/v1/systemone",
    headers={"Authorization": f"Bearer {os.environ['HESPERAN_API_KEY']}"},
    json={
      "state": "Hi, I was charged twice for order #48213. Can you refund the second charge?",
      "questions": {
        "team": {
          "type": "choice",
          "instructions": "Which team should handle this ticket?",
          "criteria": {
            "billing": "payments, refunds, double charges",
            "shipping": "delivery, tracking, damaged parcels",
            "technical": "app errors, login problems"
          }
        },
        "urgent": {
          "type": "noul",
          "instructions": "The customer has lost money and needs a reply today."
        }
      }
    },
    timeout=30,
)
res.raise_for_status()
answers = res.json()["answers"]
print(answers["team"]["choice"], answers["urgent"]["noul"])
TypeScript
const res = await fetch("https://api.hesperan.com/v1/systemone", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HESPERAN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "state": "Hi, I was charged twice for order #48213. Can you refund the second charge?",
    "questions": {
      "team": {
        "type": "choice",
        "instructions": "Which team should handle this ticket?",
        "criteria": {
          "billing": "payments, refunds, double charges",
          "shipping": "delivery, tracking, damaged parcels",
          "technical": "app errors, login problems"
        }
      },
      "urgent": {
        "type": "noul",
        "instructions": "The customer has lost money and needs a reply today."
      }
    }
  }),
});
if (!res.ok) throw new Error((await res.json()).error);
const { answers } = await res.json();

Working with a coding agent? Give it the Hesperan skill and let it write this integration for you.

3 — Read the answer

Response
{
  "model": "hesperan-1",
  "answers": {
    "team":   { "type": "choice", "choice": "billing",
                "probabilities": { "billing": 0.94, "shipping": 0.03, "technical": 0.03 } },
    "urgent": { "type": "noul", "noul": 0.88 }
  },
  "usage": { "input_tokens": 231 },
  "timing_ms": 88.4
}

Act on the probability, not just the label: route automatically when probabilities.billing is high, and send the ticket to a person when no option is clearly ahead. This request used two decisions from your plan — one per question.