# Developers

> The texuli.com developer portal: a read-only JSON API described by OpenAPI 3.1, the MCP server (remote and npx), the CLI, agent files, limits and versioning.

Language: en
Canonical: https://texuli.com/developers/
Markdown: https://texuli.com/developers.md (this page). Every texuli.com page has a Markdown twin at its URL plus `.md` (the home page is https://texuli.com/index.md), and any page URL answers `Accept: text/markdown` with its twin instead of HTML.
Last Updated: 2026-11-13

---

Everything on texuli.com an agent or a program can call: read-only JSON files with an OpenAPI description, an MCP server, and a CLI. No account and no key.

Base URL

`https://texuli.com/api/v1/`

Version

`0.18.0`, sent as `X-API-Version`

Description

[OpenAPI 3.1 (`/openapi.json`)](https://texuli.com/openapi.json)

Access

Anonymous and read-only ([auth.md](https://texuli.com/auth.md))

License

[MIT](https://github.com/DailybotHQ/texuli/blob/main/LICENSE)

## Quick start

```
curl -s https://texuli.com/api/v1/index.json
curl -s https://texuli.com/api/v1/themes.json
curl -sI https://texuli.com/api/health.json
```

The index lists every endpoint with its operationId. Every answer under `/api/` is JSON, with CORS open to any origin.

## Endpoints

Each endpoint reads a file the build writes: the edge serves a `/api/v1/` path from the file the site itself fetches, byte for byte. Pin the versioned path, because the site file follows the site.

GET endpoints under /api/v1/

| Endpoint | operationId | What it holds | Site file |
| --- | --- | --- | --- |
| `/api/v1/index.json` | `getApiIndexV1` | The version, the limits, the deprecation policy and every endpoint with its operationId. | `/api/index.json` |
| `/api/v1/health.json` | `getHealthV1` | A static file written by the build: status, release line and build time. It proves the build is served, not that a Function runs. | `/api/health.json` |
| `/api/v1/catalog.json` | `getCatalogV1` | The agent catalog snapshot: every component manifest with props, examples, accessibility notes and the emit tiers that may place it. | `/catalog/catalog.json` |
| `/api/v1/themes.json` | `listThemesV1` | Every library theme: id, name, description, category, collection, tags and its light swatches. | `/theme-catalog.json` |
| `/api/v1/themes-dark.json` | `listThemeDarkSwatchesV1` | The dark-mode swatches of every theme that has a dark palette. | `/theme-catalog-dark.json` |
| `/api/v1/theme-gallery.json` | `listThemeGalleryCardsV1` | Every theme with its WCAG AA contrast summary per mode and the key colors of each mode. | `/theme-gallery.json` |
| `/api/v1/themes/{id}.json` | `getThemeV1` | One theme's color explorer payload: its metadata and every color of each mode. | `/theme-data/{id}.json` |
| `/api/v1/twins.json` | `getTwinsManifestV1` | Every page route mapped to its Markdown twin (the page URL plus .md). | `/md-manifest.json` |

`{id}` is a theme id from `/api/v1/themes.json`. The OpenAPI document also describes `POST /mcp` as JSON-RPC.

## MCP server

- **Remote:** `https://texuli.com/mcp`, stateless Streamable HTTP (protocol `2025-11-25`). POST JSON-RPC; no session, no sign-in. It serves 29 read-only tools.
- **Local:** `npx -y @texuli/mcp`, over stdio, in any MCP host. It serves every tool, including the ones that need Node (ds.save, document.export, emoji.search, emoji.get, emoji.categories, emoji.variants). The `@texuli/mcp` package is on npm since 0.9.0.
- **Server card:** [`/.well-known/mcp/server-card.json`](https://texuli.com/.well-known/mcp/server-card.json). The tools, resources and prompts are documented in [mcp.md](https://github.com/DailybotHQ/texuli/blob/main/packages/tools/docs/mcp.md).
- **Setup for every host**, every tool with its limits, and the site tools: [Texuli MCP](https://texuli.com/mcp-server/).

## Command line

The `texuli` command of `@texuli/tools` runs the same operations as the MCP server: `texuli <group> <verb>`, with JSON input from stdin, `--json` or `--file`. In a project that has `@texuli/tools` installed, run `npx texuli <group> <verb>`; without installing it:

```
npx -p @texuli/tools texuli help
echo '{"query":"date"}' | npx -p @texuli/tools texuli catalog search
```

The `<group> <verb>` commands date from 0.9.0; the `deck` and `document` commands date from the 0.8 line. Every command: [ops.md](https://github.com/DailybotHQ/texuli/blob/main/packages/tools/docs/ops.md).

- `texuli catalog search`
- `texuli catalog validate`
- `texuli component get`
- `texuli example search`
- `texuli blueprint validate`
- `texuli blueprint theme`
- `texuli block list`
- `texuli block schema`
- `texuli theme search`
- `texuli theme get`
- `texuli theme preview`
- `texuli ds validate`
- `texuli ds compile`
- `texuli ds contrast`
- `texuli ds suggest`
- `texuli ds import`
- `texuli ds generate`
- `texuli ds allow`
- `texuli ds bundle`
- `texuli ds diff`
- `texuli ds preview`
- `texuli ds save`
- `texuli deck run`
- `texuli document run`
- `texuli document export`
- `texuli md convert`
- `texuli md render`
- `texuli emoji search`
- `texuli emoji get`
- `texuli emoji convert`
- `texuli emoji categories`
- `texuli emoji variants`
- `texuli site pages`
- `texuli site read`
- `texuli site search`

## Files for agents

- [OpenAPI 3.1 description](https://texuli.com/openapi.json): every endpoint above and POST /mcp.
- [API index](https://texuli.com/api/index.json): the /api/v1/ endpoints with their operationIds, as JSON.
- [llms.txt](https://texuli.com/llms.txt): the site guide for language models.
- [llms-full.txt](https://texuli.com/llms-full.txt): every component doc in one file.
- [Markdown twins manifest](https://texuli.com/md-manifest.json): every page and its .md twin, versioned at /api/v1/twins.json (or send Accept: text/markdown to a page URL).
- [The Texuli skill](https://texuli.com/skill/): install it in a coding agent.
- [API catalog](https://texuli.com/.well-known/api-catalog): RFC 9727 linkset.
- [AI catalog](https://texuli.com/.well-known/ai-catalog.json): the ARD resource catalog, npm packages included.
- [auth.md](https://texuli.com/auth.md): how agents access the site: anonymously.

## Limits

Rate limits per client

| Surface | RateLimit-Policy | Limit |
| --- | --- | --- |
| `/api/` | `"api";q=300;w=60` | 300 requests per client per 60 seconds. GET, HEAD and OPTIONS only. |
| `/mcp` | `"mcp";q=60;w=60` | 60 messages per client per 60 seconds (each message of a batch counts), batches of at most 10, bodies of at most 256 KB. |

Answers carry `RateLimit-Policy` and `RateLimit`. Past a limit the answer is `429` with `Retry-After`: wait that many seconds. The limits are best-effort: each edge isolate counts on its own. They come from the Pages middleware; if a file is ever served without it, it still carries `X-API-Version` and CORS, but no rate-limit fields.

## Errors

Every failed request under `/api/` is RFC 9457 `application/problem+json`, never an HTML page. The `error` object adds a stable code (`resource_not_found`, `method_not_allowed`, `rate_limited`, `internal_error`), a message, a recovery hint and this page's URL.

```
{
  "type": "https://texuli.com/developers/#errors",
  "title": "Not Found",
  "status": 404,
  "detail": "No API resource exists at /api/v1/no-such-file.json.",
  "instance": "/api/v1/no-such-file.json",
  "error": {
    "code": "resource_not_found",
    "message": "No API resource exists at /api/v1/no-such-file.json.",
    "hint": "Fetch https://texuli.com/api/v1/index.json for every endpoint, or https://texuli.com/openapi.json for the OpenAPI description. Endpoint paths end in \".json\".",
    "documentation_url": "https://texuli.com/developers/"
  }
}
```

## Versioning and deprecation

`X-API-Version` is the release line that built the files (`0.18.0`). Paths under /api/v1/ only change additively: new endpoints and new optional fields. A breaking change ships under /api/v2/, and /api/v1/ keeps serving for at least one release line (0.x minor) after that, with Deprecation (RFC 9745) and Sunset (RFC 8594) headers on every affected response. The unversioned paths are the files the site itself fetches: they follow the site and may change in any release, so pin /api/v1/.

## Access and license

Every endpoint is anonymous and read-only: there is no account, key or token, and the OAuth documents under `/.well-known/` are discovery stubs that say so (see [auth.md](https://texuli.com/auth.md)). Texuli is open source under the [MIT license](https://github.com/DailybotHQ/texuli/blob/main/LICENSE); the source is on [GitHub](https://github.com/DailybotHQ/texuli).