API reference
Tablient API
Send an Excel workbook (.xlsx or .xlsm) and get text a model can read: the whole workbook, or only the parts an agent asks for. Base address https://tablient.com.
Get a key
Create a key on your account page. It is shown once. Send it as X-API-Key: llm_... or Authorization: Bearer llm_... on every request.
First request
curl -H "X-API-Key: $KEY" -F [email protected] https://tablient.com/v1/convert
# Python import requests r = requests.post("https://tablient.com/v1/convert", headers={"X-API-Key": KEY}, files={"file": open("model.xlsx", "rb")}) r.raise_for_status() text = r.json()["cellprose"] # put this in your prompt
// JavaScript (Node 18+) import { readFile } from "node:fs/promises"; const form = new FormData(); form.append("file", new Blob([await readFile("model.xlsx")]), "model.xlsx"); const r = await fetch("https://tablient.com/v1/convert", { method: "POST", headers: { "X-API-Key": KEY }, body: form }); const { cellprose } = await r.json();
Files are never kept: each upload is deleted when its request ends. Every request body is multipart/form-data except MCP, which is JSON.
Whole workbook
Convert
POST /v1/convert
| Field | Meaning |
|---|---|
file | The workbook. Required. |
sheets | Comma-separated sheet names. Default: every sheet. |
cell_range | One range such as A1:F40. |
max_rows | Keep the first and last rows of long tables and mark the gap. |
recalc | auto (default) recalculates with LibreOffice only when the file has formulas with no saved value. always or never force it. |
max_tokens | Answer 422 instead of returning more tokens than this. |
The reply holds cellprose (the text), sheets, tokens with its token_method, input_bytes, whether formulas were recalculated, the number of formula cells left as ?, and warnings. The token count uses the cl100k_base encoding, so it is an estimate for Claude models and not a billing figure.
POST /v1/convert/batch
Several workbooks in the repeated field files, with the same options except cell_range. The reply is {"results": [...]}. A bad file gets its own status and error and does not fail the others. Each converted file counts as one workbook.
GET /v1/usage
Files, input bytes and estimated tokens converted by the calling key.
Parts of a workbook
Agent tools
For an agent working through a large workbook: map it with index, then read only what the question needs. Every call takes the workbook again in file, counts as one workbook, and returns {tool, text, tokens, token_method, warnings}.
| Endpoint | Fields | Returns |
|---|---|---|
POST /v1/tools/index | none | Each sheet’s used range and counts, then every region with its size, formula count and first row. No other values. |
POST /v1/tools/read | ranges (repeat, up to 20, like Sheet1!A1:F40), formats | Those ranges as Cellprose text. |
POST /v1/tools/find | text, optional sheet, limit (1 to 200, default 30) | Cells whose text contains text, ignoring case, each with the values to its right. |
POST /v1/tools/trace | cell, optional dependents, transitive | The cells a formula reads. With dependents, the cells that read it; with transitive, everything downstream. |
POST /v1/tools/whatif | cell, and value or factor | Every other cell whose value changes after a LibreOffice recalculation. |
curl -H "X-API-Key: $KEY" -F [email protected] \ -F ranges="Model!A1:F5" -F ranges="Inputs!A1:B9" \ https://tablient.com/v1/tools/read
What-if limits. 30 seconds per run and two runs at a time. It answers 503 with Retry-After when busy and 504 on timeout. Its cost has been measured only on workbooks of 6 to 14 KB, so expect large or volatile models to be slow or to time out.
Model Context Protocol
Hosted MCP server
POST https://tablient.com/v1/mcp is a Streamable HTTP server with JSON replies and no sessions. It offers the five workbook tools, index, read, find, trace and whatif, with the same keys, limits and counting as the REST tools, plus files and open_url for getting a workbook in.
# Claude Code claude mcp add --transport http tablient https://tablient.com/v1/mcp --header "X-API-Key: $KEY" # any client that takes a JSON config { "mcpServers": { "tablient": { "type": "http", "url": "https://tablient.com/v1/mcp", "headers": { "X-API-Key": "llm_..." } } } }
Upload once, then name the file. A hosted server cannot see your disk, and a model writes every tool argument itself, so the workbook is never sent inside a call. Put it on the server once and the tools take its file_id:
- Account page. Upload under LLM API, Workbooks for your AI assistant. The
filestool lists what you uploaded, so you can just tell the assistant which file to use. - A public link. The
open_urltool fetches an https:// address (a GitHub file page works) and returns the id. - From code or a shell.
POST /v1/files, below.
curl -H "X-API-Key: $KEY" -F [email protected] https://tablient.com/v1/files # {"file_id": "wb_...", "filename": "model.xlsx", "expires_at": "..."} curl -H "X-API-Key: $KEY" -F file_id=wb_... -F text="net income" https://tablient.com/v1/tools/find
Files are kept for 24 hours and then deleted. Only keys on the account that uploaded a file can use it, each account holds up to 20 at once (the oldest goes first), and DELETE /v1/files/{file_id} removes one now. Uploading does not count toward the quota; each tool call still counts as one workbook. The old workbook argument (base64) still works for tiny files. To keep files on your own machine, use the open Cellprose MCP server, which reads paths.
Plans
Limits and errors
| Free | API Build, $19 a month | API Scale, $99 a month | |
|---|---|---|---|
| Workbooks a month | 1,000 | 20,000 | 150,000 |
| Requests a minute | 10 | 60 | 300 |
| File size | 5 MB | 25 MB | 25 MB |
A workbook is one successful convert, one file of a batch, one tool call or one MCP tool call. Counts reset on the 1st of the month (UTC). There is no overage: past the included volume, requests answer 429 until the reset or an upgrade.
| Status | Meaning |
|---|---|
| 401 | Missing or invalid key. |
| 413 | The file is larger than your plan allows, or the batch has too many files. |
| 422 | Not a readable .xlsx or .xlsm (encrypted and legacy .xls files are not supported), a bad option, or more than max_tokens. |
| 429 | Rate limit (retry after 60 seconds) or the monthly volume is used up. |
| 503, 504 | What-if is busy or unavailable, or it ran out of time. |
Errors are JSON: {"detail": "..."}. Over MCP, a tool failure comes back as a tool result marked isError.
What the text does not carry. Array formulas are written as their saved values, and charts, pivot tables, macros and images are not included. The reply’s warnings say when this applies.