# Developers

JSON API, Markdown and an MCP server to use the Tidbit dictionary from code or from AI agents.

## What there is

All of Tidbit is readable from code with no account: a static JSON API, a Markdown version of every page and an MCP server for AI agents. Everything is read-only, free and CORS-open. The content is MIT licensed: if you show it, link back to the entry.

## JSON API

https://tidbit.legios.com.ar/v1/terms.json lists every term with its one-line definition, aliases, level, topics and URLs in both languages. https://tidbit.legios.com.ar/v1/terms/<slug>.json has the full entry. The schema is at https://tidbit.legios.com.ar/openapi.json.

```
curl -s https://tidbit.legios.com.ar/v1/terms.json | jq '.terms[] | {slug, title: .en.title}'
curl -s https://tidbit.legios.com.ar/v1/terms/data-lake.json | jq '.es.tagline'
```

## Markdown

Any page returns Markdown when you ask with Accept: text/markdown, or when you add index.md to its URL. 404s answer in Markdown too when you ask for it.

```
curl -s -H 'Accept: text/markdown' https://tidbit.legios.com.ar/data-lake/
```

## MCP server

https://tidbit.legios.com.ar/mcp is an MCP server (Streamable HTTP, no auth) with four read-only tools: search_terms, get_term, list_topic and term_of_the_day. Add it to any MCP client with this configuration. The server card is at https://tidbit.legios.com.ar/.well-known/mcp/server-card.json.

```
{
  "mcpServers": {
    "tidbit": {
      "type": "http",
      "url": "https://tidbit.legios.com.ar/mcp"
    }
  }
}
```

## Errors

API and MCP errors are JSON. The API uses RFC 9457 (application/problem+json) with a machine-readable code (not_found, rate_limited, method_not_allowed), a message and what to do next. MCP uses JSON-RPC errors.

```
{
  "type": "https://tidbit.legios.com.ar/developers/#errors",
  "title": "Term not found",
  "status": 404,
  "code": "not_found",
  "detail": "No term has the slug 'foo'.",
  "resolution": "List every term at https://tidbit.legios.com.ar/v1/terms.json."
}
```

## Rate limits

Fair use: 300 requests per 60 seconds per client on /v1/ and /mcp, enforced approximately. Every response carries RateLimit-Policy and RateLimit headers; going over returns 429 with Retry-After. To get everything at once, use https://tidbit.legios.com.ar/v1/terms.json or https://tidbit.legios.com.ar/llms-full.txt instead of fetching term by term.

## Versioning

The version is in the path (/v1/). Within a version fields are only added, never removed or changed in meaning. A breaking change ships as /v2/, and /v1/ keeps working for at least 12 months after that, announced with Deprecation and Sunset headers and on this page.

## Help

Questions, bugs or term requests: https://github.com/legiosai/tidbit/issues. The guide for agents is at https://tidbit.legios.com.ar/llms.txt.