(Docs)
API reference
Base URL
https://api.hesperan.com. JSON in, JSON out. The machine-readable description is at /openapi.json (OpenAPI 3.1).Authentication
Send your key as a bearer token: Authorization: Bearer hsp_…. Keys belong to your account; create and revoke them in the console. Never ship a key in browser or mobile code — call the API from your server.
POST /v1/systemone
Answer one or more typed questions about a state.
| Field | Type | Description |
|---|---|---|
state | string | object | array | What the questions are about. Up to 256 KB per request body. |
questions | object | Map of question name → question. At least one. |
questions.*.type | "choice" | "noul" | "score" | The judgment type. |
questions.*.instructions | string | The question (choice, score) or statement (noul). |
questions.*.criteria | object | array | choice: key → description · noul: optional { true, false } · score: level descriptions, lowest first. |
Response
| Field | Type | Description |
|---|---|---|
model | string | Model that answered, e.g. hesperan-1. |
answers | object | One answer per question name, with the same type. |
answers.*.choice | string | choice: the most likely option key. |
answers.*.noul | number | noul: probability that the statement holds. |
answers.*.score | number | score: expected level, Σ level × probability. |
answers.*.probabilities | object | choice and score: probability per option / level; sums to 1. |
usage.input_tokens | integer | Tokens read for this request. |
timing_ms | number | Time the model spent deciding, in milliseconds. |
Response headers
| Header | Meaning |
|---|---|
x-request-id | Unique id; include it when you contact support. |
x-billed-to | What paid for this answer: plan or balance. |
x-plan-usage | Share of this period's plan allowance used, e.g. 42%. |
x-balance-remaining | Your prepaid balance in euros after this request. |
x-ratelimit-limit | Requests per minute for this key's plan. |
x-ratelimit-remaining | Requests left in the current window. |
GET /health
Unauthenticated. Returns 200 with the model id when the service can answer, 503 otherwise.
{ "status": "ok", "model": "hesperan-1", "upstream": "ok" }