Talarion

https://docs.talarion.com/
Admin
Talarion maintains a knowledge base of verified, dated assertions designed to power world-state...
Tokens:7,912
Snippets:60
Trust Score:5.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Python: POST to Talarion search endpoint with requests

Source: https://docs.talarion.com/search

Python example using the requests library to call the Talarion search endpoint. Reads the API key from the TALARION_API_KEY environment variable, raises an exception on HTTP errors, and prints each fact with its sources.

```python
import os
import requests

resp = requests.post(
    "https://api.talarion.com/v1/search",
    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()["results"]:
    print(f"{fact['question']} → {fact['answer']} (true by {fact['true_by']})")
    for url in fact["sources"]:
        print(f"    source: {url}")
```

--------------------------------

### JSON: Example search response

Source: https://docs.talarion.com/search

Example JSON response from the Talarion search endpoint. Each result contains a question, answer, true_by date (ISO YYYY-MM-DD or null), and a list of source URLs. Entries are ordered by most recent true_by by default; set timeline: false to order by relevance.

```json
{
  "results": [
    {
      "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/"
      ]
    }
  ]
}
```

--------------------------------

### TypeScript: POST to Talarion search endpoint with fetch

Source: https://docs.talarion.com/search

TypeScript example using fetch to call the Talarion search endpoint. Reads the API key from the TALARION_API_KEY environment variable and logs the results array.

```typescript
const res = await fetch("https://api.talarion.com/v1/search", {
  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 { results } = await res.json();
console.log(results);
```

--------------------------------

### Fetch API response format

Source: https://docs.talarion.com/fetch

Example of the JSON response structure returned by the fetch endpoint.

```json
{
  "as_of": "2026-06-01T00:00:00Z",
  "results": [
    {
      "url": "https://www.anthropic.com/news/claude-opus-4-8",
      "content_date": "2026-05-28T00:00:00Z",
      "text": "Introducing Claude Opus 4.8\nWe’re upgrading Claude Opus to a new version: Claude Opus 4.8. It builds on Opus 4.7 with improvements across benchmarks, and is a more effective collaborator…"
    }
  ]
}
```

--------------------------------

### POST /v1/search

Source: https://docs.talarion.com/rest-api

This snippet documents the Talarion search endpoint, including the request body, response structure, and example usage.

```APIDOC
## [POST] /v1/search

### Description
Call the Talarion search endpoint directly over HTTPS to retrieve verified assertions with a single POST request.

### Method
POST

### Endpoint
https://api.talarion.com/v1/search

### Parameters
#### Request Body
- **query** (string) - Required - The search query string.

### Request Example
{
  "query": "What are the most significant AI model releases in 2026?"
}

### Response
#### Success Response (200)
- **results** (array) - A list of fact objects.
  - **question** (string) - The question the fact answers.
  - **answer** (string) - The answer to the question.
  - **true_by** (string or null) - The date the fact was known true (ISO YYYY-MM-DD) or null when the source carries no truth-time.
  - **sources** (array of strings) - Upstream URL(s) the fact is drawn from.

#### Response Example
{
  "results": [
    {
      "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/"
      ]
    }
  ]
}
```

--------------------------------

### Configure Cursor MCP

Source: https://docs.talarion.com/installation

Manually add the Talarion MCP server to the Cursor configuration file.

```json
{
  "mcpServers": {
    "talarion": {
      "url": "https://mcp.talarion.com/mcp"
    }
  }
}
```

--------------------------------

### Configure Hermes MCP Server

Source: https://docs.talarion.com/installation

Add the Talarion MCP server to Hermes using OAuth or a workspace API key for headless environments.

```bash
hermes mcp add talarion --url https://mcp.talarion.com/mcp --auth oauth
```

```yaml
mcp_servers:
  talarion:
    url: "https://mcp.talarion.com/mcp"
    headers:
      Authorization: "Bearer ${env:TALARION_API_KEY}"
```

--------------------------------

### Configure OpenClaw MCP Server

Source: https://docs.talarion.com/installation

Register the Talarion MCP server in OpenClaw using an API key generated from the Talarion dashboard.

```bash
openclaw mcp set talarion \
  '{"url":"https://mcp.talarion.com/mcp","transport":"streamable-http","headers":{"Authorization":"Bearer YOUR_KEY"}}'
```

--------------------------------

### Fetch request using Python

Source: https://docs.talarion.com/fetch

Use the requests library to fetch page content, ensuring the API key is retrieved from environment variables.

```python
import os
import requests

resp = requests.post(
    "https://api.talarion.com/v1/fetch",
    headers={"Authorization": f"Bearer {os.environ['TALARION_API_KEY']}"},
    json={
        "urls": ["https://www.anthropic.com/news/claude-opus-4-8"],
        "as_of": "2026-06-01",
    },
)
resp.raise_for_status()

for doc in resp.json()["results"]:
    print(doc["url"], doc["content_date"])
    if doc["text"]:
        print(doc["text"][:500])
```

--------------------------------

### Configure Gemini CLI MCP

Source: https://docs.talarion.com/installation

Add the Talarion MCP server to the Gemini CLI by updating the settings.json file.

```json
{
  "mcpServers": {
    "talarion": {
      "httpUrl": "https://mcp.talarion.com/mcp"
    }
  }
}
```

--------------------------------

### Python MPP Client to pay and retry /v1/search

Source: https://docs.talarion.com/search

Uses the Machine Payments Protocol Python client to renew the account and charge intent, then posts the same search request with the payment credential. This handles the 402 challenge automatically and returns the search results.

```python
from mpp.client import Client
from mpp.methods.tempo import ChargeIntent, TempoAccount, tempo

account = TempoAccount.from_key("0x...")
async with Client(methods=[tempo(account=account, intents={"charge": ChargeIntent()})]) as client:
    response = await client.post(
        "https://api.talarion.com/v1/search",
        json={"query": "What changed in EU AI Act enforcement?"},
    )
```

--------------------------------

### Configure Claude Code MCP

Source: https://docs.talarion.com/installation

Add the Talarion MCP server to Claude Code with either user-scoped or project-scoped configuration.

```bash
# User-scoped (available across all your projects)
claude mcp add --scope user --transport http talarion https://mcp.talarion.com/mcp

# Project-scoped (current project only)
claude mcp add --transport http talarion https://mcp.talarion.com/mcp
```

--------------------------------

### Fetch request using curl

Source: https://docs.talarion.com/fetch

Perform a POST request to the fetch endpoint using curl, providing the URLs and the as_of date.

```bash
curl -X POST https://api.talarion.com/v1/fetch \
  -H "Authorization: Bearer $TALARION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://www.anthropic.com/news/claude-opus-4-8"],
    "as_of": "2026-06-01"
  }'
```

--------------------------------

### Fetch request using TypeScript

Source: https://docs.talarion.com/fetch

Perform a POST request using the native fetch API in a TypeScript environment.

```typescript
const res = await fetch("https://api.talarion.com/v1/fetch", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TALARION_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    urls: ["https://www.anthropic.com/news/claude-opus-4-8"],
    as_of: "2026-06-01",
  }),
});

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

--------------------------------

### curl request to /v1/search without Authorization header

Source: https://docs.talarion.com/rest-api

Sends a POST request to the Talarion /v1/search endpoint without an Authorization header, which triggers a 402 payment challenge instead of a 401. The query asks about EU AI Act enforcement changes.

```bash
curl -i -X POST https://api.talarion.com/v1/search \
  -H 'Content-Type: application/json' \
  -d '{"query": "What changed in EU AI Act enforcement?"}'

```

--------------------------------

### curl POST /v1/search without Authorization header

Source: https://docs.talarion.com/search

Sends a search request without an Authorization header to trigger a 402 payment challenge instead of a 401. If the client does not pay, you will receive the 402 response shown.

```bash
curl -i -X POST https://api.talarion.com/v1/search \
  -H 'Content-Type: application/json' \
  -d '{"query": "What changed in EU AI Act enforcement?"}'
```

--------------------------------

### POST /v1/fetch

Source: https://docs.talarion.com/fetch

Retrieves the archived text snapshot for each provided URL at or before the specified date. Returns a JSON object with a results array containing the URL, content date, and extracted text.

```APIDOC
## POST /v1/fetch

### Description
Retrieves the archived text snapshot for each provided URL at or before the specified date. Returns a JSON object with a results array containing the URL, content date, and extracted text.

### Method
POST

### Endpoint
https://api.talarion.com/v1/fetch

### Parameters
#### Request Body
- **urls** (string[]) - Required - Up to 20 URLs, deduplicated server-side; extras beyond 20 are dropped, not rejected. URLs are normalized before lookup (scheme, www., trailing slashes, tracking parameters); other query parameters are significant.
- **as_of** (date or datetime) - Optional - Return each page's most recent snapshot at or before this instant, ISO 8601. Defaults to now (UTC).

### Request Example
{
  "urls": ["https://www.anthropic.com/news/claude-opus-4-8"],
  "as_of": "2026-06-01"
}

### Response
#### Success Response (200)
- **as_of** (string) - The date and time used for the fetch, in ISO 8601 format.
- **results** (array) - One entry per URL.
  - **url** (string) - The URL as initially provided.
  - **content_date** (string) - The date the content is from, in ISO 8601 format.
  - **text** (string or null) - The extracted text of the page, or null if no content is held for that URL as of the specified date.

#### Response Example
{
  "as_of": "2026-06-01T00:00:00Z",
  "results": [
    {
      "url": "https://www.anthropic.com/news/claude-opus-4-8",
      "content_date": "2026-05-28T00:00:00Z",
      "text": "Introducing Claude Opus 4.8\nWe’re upgrading Claude Opus to a new version: Claude Opus 4.8. It builds on Opus 4.7 with improvements across benchmarks, and is a more effective collaborator…"
    }
  ]
}

### Error Handling
- **401** - Invalid API key. A request with no Authorization header gets a 402 payment challenge instead.
- **402** - Fetch requires an active subscription. Add a payment method in Billing.
- **503** + Retry-After - Retry after the given interval.
```

--------------------------------

### POST /v1/search

Source: https://docs.talarion.com/search

Searches for verified assertions based on a query. Returns a list of facts with questions, answers, truth dates, and sources.

```APIDOC
## POST /v1/search

### Description
Searches for verified assertions based on a query. Returns a list of facts with questions, answers, truth dates, and sources.

### Method
POST

### Endpoint
https://api.talarion.com/v1/search

### Parameters
#### Request Body
- **query** (string) - Required - The search query.
- **timeline** (boolean) - Optional - If false, orders results by relevance instead of most recent true_by date.

### Request Example
{
  "query": "What are the most significant AI model releases in 2026?"
}

### Response
#### Success Response (200)
- **results** (array) - List of fact objects.
  - **question** (string) - The question the fact answers.
  - **answer** (string) - The verified answer.
  - **true_by** (string or null) - ISO date (YYYY-MM-DD) when the fact was known true, or null if no truth-time.
  - **sources** (array of strings) - Upstream URLs the fact is drawn from.

#### Response Example
{
  "results": [
    {
      "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"]
    }
  ]
}
```

--------------------------------

### Authenticate REST API requests with a workspace API key

Source: https://docs.talarion.com/authentication

Use this header on every REST API request to authenticate with a workspace API key. The key is workspace-scoped and prefixed with 'tlrn_'. It is shown only once when created, so copy it immediately.

```http
Authorization: Bearer tlrn_...
```

--------------------------------

### curl: POST to Talarion search endpoint

Source: https://docs.talarion.com/search

Send a POST request to the Talarion search endpoint using curl. Requires an API key stored in the TALARION_API_KEY environment variable. The response contains a results array with verified facts.

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

--------------------------------

### HTTP 402 Payment Required response with payment challenge

Source: https://docs.talarion.com/rest-api

The response to the curl request without an Authorization header. It includes a WWW-Authenticate header with a payment challenge, specifying the payment method 'tempo' and the header 'Payment-Authorization' to use for retry.

```http
HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment id="...", realm="api.talarion.com", method="tempo",
  intent="charge", request="...", header="Payment-Authorization"

```

--------------------------------

### HTTP 402 Payment Required response with WWW-Authenticate

Source: https://docs.talarion.com/search

The expected response when sending a request without an Authorization header. Includes the WWW-Authenticate header with a payment challenge requiring Payment-Authorization.

```http
HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment id="...", realm="api.talarion.com", method="tempo",
  intent="charge", request="...", header="Payment-Authorization"
```

--------------------------------

### POST /v1/search

Source: https://docs.talarion.com/search

Searches for facts based on a query. Supports optional parameters for model-based filtering, result count, ordering, and date ranges. Can be used without an account via the Machine Payments Protocol.

```APIDOC
## [POST] /v1/search

### Description
Searches for facts based on a query. Supports optional parameters for model-based filtering, result count, ordering, and date ranges. Can be used without an account via the Machine Payments Protocol.

### Method
POST

### Endpoint
https://api.talarion.com/v1/search

### Parameters
#### Request Body
- **query** (string) - Required - 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) - Optional - 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) - Optional - Number of facts to return. Defaults to `20`; clamped to the range `10`–`100`.
- **timeline** (boolean) - Optional - Result ordering. `true` (default): most recent `true_by` first. `false`: ordered by relevance.
- **true_by_min** (datetime) - Optional - Only return facts with `true_by` on or after this ISO 8601 datetime. Overrides the `model_id`-derived training-cutoff floor. Naive datetimes are treated as UTC.
- **true_by_max** (datetime) - Optional - Only return facts with `true_by` on or before this ISO 8601 datetime — e.g. for date-boxed backtesting. Must be after `true_by_min`.

### Request Example
```bash
curl -i -X POST https://api.talarion.com/v1/search \
  -H 'Content-Type: application/json' \
  -d '{"query": "What changed in EU AI Act enforcement?"}'
```

### Response
#### Success Response (200)
- **facts** (array) - List of facts matching the query.

#### Response Example
```json
{
  "facts": []
}
```

### Error Handling
#### 402 Payment Required
- **WWW-Authenticate** (string) - Payment challenge header. Sent when no `Authorization` header is provided, indicating a payment is required.

#### Error Response Example
```http
HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment id="...", realm="api.talarion.com", method="tempo",
  intent="charge", request="...", header="Payment-Authorization"
```
```
Tokens:
Raw