The tabnas API #

Endpoints #

Each operation carries a unique operationId, typed parameters and a response schema in /openapi.json, so a tool that turns an OpenAPI document into callable functions can do so without further description.

Any page, as markdown #

Every page on this site is content-negotiated. Ask for markdown and the same URL answers with markdown instead of HTML — no navigation, no styling, no scripts — and the response carries Vary: Accept so a cache keeps the two apart (acceptmarkdown.com).

curl -H "Accept: text/markdown" https://tabnas.dev/docs/quickstart

The same bytes are at the path plus .md, for callers that would rather not set a header — https://tabnas.dev/docs/quickstart.md, and https://tabnas.dev/index.md for the home page. Each twin opens with a small YAML frontmatter block carrying the page's title, description and canonical URL.

If you want the whole documentation set in one request instead, that is /llms-full.txt; the index of what is here is /llms.txt.

When something is wrong #

A path that does not exist returns a real 404 — never a 200 with an application shell. What is in the body depends on what you asked for: application/json, any path under /api/, and any path ending .json or .yaml get an error object; a browser gets the 404 page; anything else gets markdown carrying the same links.

{
  "error": {
    "status": 404,
    "code": "not_found",
    "message": "Not Found",
    "hint": "Nothing is published at /api/v1/parse. This site is documentation for the tabnas parsing engine; start from /llms.txt for the machine-readable index, or /openapi.json for the endpoints that return JSON.",
    "documentation": "https://tabnas.dev/api",
    "openapi": "https://tabnas.dev/openapi.json",
    "resources": {
      "llms.txt": "https://tabnas.dev/llms.txt"
    }
  }
}

code is stable and safe to branch on: it is one of not_found, method_not_allowed (the site is read-only, so anything other than GET, HEAD or OPTIONS gets one) and not_acceptable (you asked for a representation that does not exist for that URL). hint is written to tell you what to do next, and resources lists the site's entry points so one failed request is enough to recover.

Errors from the engine are a different thing entirely: a parse failure carries a diagnostic whose code is the contract across both runtimes. All 46 of them are at /errors.json, one at a time at /errors/<code>.json, and with prose at /errors.

The MCP endpoint #

7 tools that actually run the engine — parse, validate a grammar, explain a failure, run fixtures, read the plugin catalogue, compare two grammar versions — are served over the Model Context Protocol from a separate service at https://mcp.tabnas.dev, deployed from the tabnas/mcp repository. Start from /.well-known/mcp on this domain, which names both transports; /mcp has each tool's contract.

Local stdio stays the recommended path: npx --yes @tabnas/mcp mcp is the same code, unbounded and private. The hosted endpoint is bounded by a body cap and a per-IP rate limit, both reported by its own /.well-known/mcp.