# API overview

Source: https://docs.temprl.org/api

> The Simo HTTP API - base URL, authentication with API keys, the single /v1/ask endpoint, and conventions for headers and errors.

The SDK is a thin client over one endpoint, so any language can call Simo directly.

```text
POST https://api.temprl.org/v1/ask
```

## Base URL

```text
https://api.temprl.org
```

Always use HTTPS.

## Authentication

Send your API key as a bearer token. Create keys in the [console](https://app.temprl.org) under **API keys**; they look like `simo_sk_...` and are shown once.

```http
Authorization: Bearer simo_sk_...
```

Keys are secret. Call the API from your server, never from a browser or mobile app where the key would be visible. Revoke a leaked key in the console; it stops working immediately.

## Endpoints

| Method | Path | Auth | Purpose |
|---|---|---|---|
| `POST` | [`/v1/ask`](https://docs.temprl.org/api/ask) | API key | Answer questions about a state |
| `GET` | [`/v1/models`](https://docs.temprl.org/api/other-endpoints#list-models) | none | List models and their availability |
| `GET` | [`/health`](https://docs.temprl.org/api/other-endpoints#health) | none | Service health check |

`POST /v1/systemone` is the endpoint's previous name. It still works for older integrations; new code should use `/v1/ask`.

## A complete request

**cURL**

```bash
curl https://api.temprl.org/v1/ask \
  -H "Authorization: Bearer $SIMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "simo-1-pro",
       "state": "The customer says the parcel arrived broken and wants their money back.",
       "questions": {"refund": {"type": "noul", "instructions": "The customer asks for a refund"}}}'
```

**JavaScript**

```javascript
const res = await fetch("https://api.temprl.org/v1/ask", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SIMO_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "simo-1-pro",
    state: "The customer says the parcel arrived broken and wants their money back.",
    questions: { refund: { type: "noul", instructions: "The customer asks for a refund" } },
  }),
});
if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${res.status} ${error.code}: ${error.message}`);
}
const data = await res.json();
console.log(data.answers.refund.noul, res.headers.get("x-simo-cost-usd"));
```

**Python (requests)**

```python
import os, requests

res = requests.post(
    "https://api.temprl.org/v1/ask",
    headers={"Authorization": f"Bearer {os.environ['SIMO_API_KEY']}"},
    json={"model": "simo-1-pro",
          "state": "The customer says the parcel arrived broken and wants their money back.",
          "questions": {"refund": {"type": "noul", "instructions": "The customer asks for a refund"}}},
    timeout=120,
)
res.raise_for_status()
print(res.json()["answers"]["refund"]["noul"])
```

**Response**

```json
{
  "id": "evt_...",
  "model": "simo-1-pro",
  "answers": {"refund": {"type": "noul", "noul": 0.991}},
  "usage": {"input_tokens": 41, "output_tokens": 0, "cost": 0.00000123}
}
```

## Conventions

- Bodies are JSON, sent with `Content-Type: application/json`.
- Successful answers carry `x-request-id` (the same `evt_...` id as `id` in the body), `x-simo-cost-usd`, `x-simo-balance-usd` and `x-simo-latency-ms`. Quote the request id to support.
- Errors return `{"error": {"code": "...", "message": "..."}}`. See [Errors](https://docs.temprl.org/api/errors).
- New fields may be added to responses. Ignore fields you don't use.