# API Reference

Call Talarion's research endpoint directly over HTTPS — verified, dated, sourced facts
about your topic from a single `POST`.

  [API Playground →](https://dashboard.talarion.com/playground)
  [Create an API key →](https://dashboard.talarion.com/api-keys)

## Your first request

#### curl

```bash
curl -X POST https://mcp.talarion.com/api/research \
  -H "Authorization: Bearer $TALARION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What are the most significant AI model releases in 2026?"}'
```

#### Python

```python
import os
import requests

resp = requests.post(
    "https://mcp.talarion.com/api/research",
    headers={"Authorization": f"Bearer {os.environ['TALARION_API_KEY']}"},
    json={"query": "What are the most significant AI model releases in 2026?"},
)
resp.raise_for_status()

for fact in resp.json()["research_guidance"]:
    print(f"{fact['question']} → {fact['answer']} (true by {fact['true_by']})")
    for url in fact["sources"]:
        print(f"    source: {url}")
```

#### TypeScript

```typescript
const res = await fetch("https://mcp.talarion.com/api/research", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TALARION_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "What are the most significant AI model releases in 2026?",
  }),
});

const { research_guidance } = await res.json();
console.log(research_guidance);
```

## Response

A JSON object with a `research_guidance` array. Each entry is a self-contained, current fact —
the misconceptions an LLM would otherwise operate under — with a `question`, an `answer`,
`true_by` (the date the fact was known true — ISO `YYYY-MM-DD`, or `null` when the source carries
no truth-time), and `sources`, a list of the upstream URL(s) the fact is drawn from. By default
entries are ordered with the most recent `true_by` first; set `timeline: false` to order by
relevance instead. See [Overview](/overview) for how to use them.

```json
{
  "research_guidance": [
    {
      "question": "What flagship AI model did Anthropic release in May 2026?",
      "answer": "Claude Opus 4.8.",
      "true_by": "2026-05-15",
      "sources": ["https://www.anthropic.com/news/claude-opus-4-8"]
    },
    {
      "question": "What is the estimated total amount major tech companies will spend on AI data centers in 2026?",
      "answer": "$650 billion.",
      "true_by": "2026-03-01",
      "sources": [
        "https://www.cnbc.com/2026/03/01/big-tech-ai-data-center-spending-2026.html",
        "https://www.reuters.com/technology/ai-capex-2026-forecast/"
      ]
    }
  ]
}
```

## Parameters

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | The search question you want caught up on — e.g. "How is insurance coverage of GLP-1 obesity drugs changing?". One focused question about one topic retrieves best. |
| `model_id` | string | No | Your model as an OpenRouter id (e.g. `anthropic/claude-opus-4.8`). Filters results to facts that postdate your model's training cutoff. |
| `k` | integer | No | Number of facts to return. Defaults to `20`; clamped to the range `10`–`100`. |
| `timeline` | boolean | No | Result ordering. `true` (default): most recent `true_by` first. `false`: ordered by relevance. |

## Errors & limits

| Status | Meaning |
|--------|---------|
| `401` | Missing or invalid API key. |
| `402` | Free-tier monthly call limit reached (1,000 calls/month). Upgrade in [Billing](https://dashboard.talarion.com/billing). |