API and MCP

Oesnada for developers

Oesnada’s published stories, storylines, topic summaries, analysis and AI model data can be read over a REST API and an MCP server. Both are free, read-only and need no key. Every response says where it came from and asks you to credit Oesnada and link the item.

Quick start

No key and no sign-up. Add lang=tr for Turkish. A Turkish item exists only where real Turkish text exists.

The five latest stories

curl 'https://oesnada.com/api/v1/stories?limit=5'

Search, in Turkish

curl 'https://oesnada.com/api/v1/search?q=yapay+zek%C3%A2&lang=tr'

AI model price changes this week

curl 'https://oesnada.com/api/v1/ai-models/price-changes?days=7'

The next page of a list

curl 'https://oesnada.com/api/v1/stories?limit=5&cursor=<next_cursor from the previous response>'

REST API

JSON over GET. The base address is https://oesnada.com/api/v1. The full description is in the OpenAPI document. OpenAPI document.

Endpoint	Returns
`GET /api/v1`	Index: version, endpoints and the MCP address.
`GET /api/v1/openapi.json`	The OpenAPI 3.1 description.
`GET /api/v1/stories`	Published stories, newest first. Filter by topic, category, storyline and date.
`GET /api/v1/stories/{id}`	One story.
`GET /api/v1/search`	Ranked search over our published text. It returns matches, not a written answer.
`GET /api/v1/storylines`	Ongoing stories with their updates.
`GET /api/v1/storylines/{slug}`	One storyline with its events and, when every citation checked out, the story so far.
`GET /api/v1/topics`	Topics with at least three stories.
`GET /api/v1/topics/{slug}`	One topic with its checked summary and recent stories.
`GET /api/v1/analysis`	Analysis posts and Notes.
`GET /api/v1/analysis/{series}/{key}`	One analysis post, for example 2026-42.
`GET /api/v1/ai-models`	AI models and prices from the latest daily snapshot. CC BY 4.0.
`GET /api/v1/ai-models/price-changes`	Price changes recorded in the last days. An empty list means none was recorded.
`GET /api/v1/ai-models/{slug}`	One model from the latest snapshot.
`GET /api/v1/ai-models/{slug}/history`	One model, one entry per daily snapshot.
`GET /api/v1/data/importance-index`	Aggregates of the automated importance score. A model judgement, not a measurement. CC BY 4.0.
`GET /api/v1/data/most-covered`	The most covered topics of a month. CC BY 4.0.

Parameters

lang is en or tr and defaults to en.
limit is an integer; each list has its own default and maximum.
An unknown or repeated parameter is rejected with 400, so a typo never returns the wrong list quietly.
since is inclusive and until is exclusive; both take an ISO 8601 date or time.

Pagination

Lists are newest first and page with a cursor: pass next_cursor from the response as cursor. A cursor is opaque, belongs to the query that produced it and expires after a day. There are no page numbers. Search returns the best 25 at most; narrow the query instead of paging.

Limits

Reads: 60 requests a minute per client. Search: 20 a minute.
The RateLimit and RateLimit-Policy headers show what is left and when it resets.
Over a limit the answer is 429 with Retry-After. When the service is under heavy load it answers 503 with Retry-After; cached responses keep being served.
Repeating exactly the same request many times in a minute is treated as a loop and limited.

MCP server

A read-only Model Context Protocol server over Streamable HTTP, for assistants and coding tools. It calls the same service as the REST API, with ten tools and no write access.

Address: https://oesnada.com/mcp

Tools

Each tool is read-only. Results carry the item address and the attribution line. An empty result means we have not covered it.

`oesnada_search`	Search published stories, storylines, topics and analysis.
`oesnada_latest`	The latest stories, optionally for one topic or category.
`oesnada_get_story`	One story by its number.
`oesnada_list_storylines`	Ongoing and recent storylines.
`oesnada_get_storyline`	One storyline with its events and the story so far.
`oesnada_get_topic`	One topic by name or slug, with its summary and recent stories.
`oesnada_ai_models`	AI models and prices from the latest snapshot.
`oesnada_ai_price_changes`	Recorded price changes of AI models.
`oesnada_data`	The importance index or the most-covered list.
`oesnada_latest_analysis`	The latest analysis posts.

Connect a client

Use this address in any client that supports remote MCP servers over HTTP. No sign-in is needed.

Claude Code

Run once in a terminal.

claude mcp add --transport http oesnada https://oesnada.com/mcp

Claude (web and desktop)

Settings, Connectors, Add custom connector. Paste this address, leave authentication empty.

https://oesnada.com/mcp

Cursor

Add to ~/.cursor/mcp.json, or to .cursor/mcp.json in a project.

{
  "mcpServers": {
    "oesnada": {
      "url": "https://oesnada.com/mcp"
    }
  }
}

VS Code

Add to .vscode/mcp.json in a project.

{
  "servers": {
    "oesnada": {
      "type": "http",
      "url": "https://oesnada.com/mcp"
    }
  }
}

Claude Desktop, configuration file

For clients that only start local programs. The mcp-remote package connects them to the address. Needs Node.js.

{
  "mcpServers": {
    "oesnada": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://oesnada.com/mcp"]
    }
  }
}

Attribution

Show “Source: Oesnada” (Turkish: “Kaynak: Oesnada”) next to anything you take from a response, and link the item. Use cite_url for the link: it is the same page with a referral mark, and the page itself keeps its canonical address.
AI model data, price changes, the importance index and the most-covered lists are licensed CC BY 4.0.
Summaries are produced automatically from public reporting. Do not present them as quotations, and say that Oesnada has not covered something rather than guessing.

Errors

Errors use the problem+json format (RFC 9457) with a code, a detail and, for a bad parameter, the parameter name.

Status	Code	When
400	`invalid_request`	An unknown, repeated or malformed parameter, or an expired cursor.
404	`not_found`	An unknown path, id or slug, or an item without text in the language you asked for.
405	`method_not_allowed`	Only GET is accepted.
413	`payload_too_large`	The request body is too large.
429	`rate_limited`	Too many requests. Wait for the number of seconds in Retry-After.
503	`overloaded`	The service is shedding load. Retry after the time in Retry-After.
500	`internal`	A fault on our side.

Versions

The version is in the path. Version 1 changes only by adding endpoints, parameters and fields. A breaking change ships as /api/v2, and version 1 stays available for at least six months after it is announced, with Deprecation and Sunset headers.

No question-answering tool

The API and the MCP server return our published text and data. They do not write answers. Bring your own model and cite what it reads.

Questions

Write to us on the contact page.