Convert TSV to JSON

To convert TSV to JSON, send one POST to /v1/csv-to-json with the TSV source. Each call costs $0.005 in USDC on Base via x402, with no account and no API key. The source file can be up to 25 MB.

Agents read this page asGET /v1/csv-to-json/schemafree: schema, examples, errors, price

Endpoint
POST /v1/csv-to-json
Price
$0.005 per call
API
csv-to-json
TSVgarden-plots.tsvthe source, by URL or inline
JSONin the responsereturned in the JSON answer

Limits

LimitValue
Largest source file25 MB (26,214,400 bytes)
Timeout30 s
Source formatsCSV, TSV
Output formatsJSON
Option headerdefault true
Option max_rowsdefault 10000

Example

A real TSV to JSON run of csv-to-json.

Request
POST /v1/csv-to-json
content-type: application/json
payment-signature: <base64 x402 payload>

{
  "url": "https://grist.tools/samples/documents/garden-plots.tsv",
  "header": true
}
Response200 OK
200 OK
payment-response: <base64 settlement receipt>

{
  "source_url": "https://grist.tools/samples/documents/garden-plots.tsv",
  "delimiter": "\t",
  "columns": [
    "plot",
    "holder",
    "crop",
    "area_m2",
    "notes"
  ],
  "rows": [
    {
      "plot": "A1",
      "holder": "Maple Group",
      "crop": "tomatoes",
      "area_m2": "12",
      "notes": "Stakes needed, north side"
    },
    {
      "plot": "A2",
      "holder": "Oak Group",
      "crop": "beans",
      "area_m2": "08",
      "notes": ""
    },
    {
      "plot": "B1",
      "holder": "Willow Group",
      "crop": "herbs, mixed",
      "area_m2": "6",
      "notes": "Shares water with \"B2\""
    },
    {
      "plot": "B2",
      "holder": "Birch Group",
      "crop": "squash",
      "area_m2": "10.50",
      "notes": "Compost added in April"
    }
  ],
  "row_count": 4,
  "truncated": false
}

Source file: documents/garden-plots.tsv, 212 bytes. Tab-separated table of four community garden plots with a header row (plot, holder, crop, area_m2, notes), the same data as garden-plots.csv including an empty field, a comma inside a value and embedded double quotes. The request sets header to true. The recorded run returned 396 bytes of JSON, 1.9 times the source size, with 4 rows and 5 columns.

Format notes

TSV as a source

TSV separates values with tab characters, so a comma inside a value is ordinary text and needs no quoting on its account. Grist reads TSV through csv-to-json, where tab is among the delimiters detected automatically from the opening rows, or it can be named explicitly. The input passes the same gate as CSV: strict UTF-8, no NUL bytes, and only UTF-8 charset declarations. Values stay strings, headings are normalised the same way, and the response reports a tab as the delimiter it used. Quoted fields still follow the parser's quoting rules, so a double quote inside a TSV value is read through the same quote handling as in CSV. TSV has an input role only: no service in the catalogue lists it as an output format, so it appears on these pages as a source.

JSON as a target

The JSON that Grist returns keeps different value types depending on the reader. csv-to-json leaves every cell a string and returns header-keyed objects, or positional arrays when header is false, together with the delimiter, the column list, a row count and a truncated flag. xlsx-to-json keeps numbers and booleans as typed values, turns dates into ISO-8601 strings, uses the cached result of a formula, and reduces rich text and hyperlinks to their text; error cells become null. It returns every worksheet, or a single sheet selected by exact name. A delimited source therefore produces JSON that needs type conversion by the caller, while a workbook source produces typed values straight away. Blank and duplicate headings are made unique by both readers before they become object keys.

Errors

When each is raised, and what it means for payment: /docs/csv-to-json.

invalid_input 400blocked_target 403unreachable_target 424upstream_timeout 424unsupported_content_type 415too_large 413unprocessable 422internal 500

Questions

What does it cost to convert TSV to JSON?

$0.005 per call, paid in USDC on Base via x402.

How large can the TSV file be?

Up to 25 MB (26,214,400 bytes). Past a limit the call answers too_large (413).

What happens if the conversion fails?

The tool answers with a typed JSON error from the errors table. Payment is settled only after the tool has produced its result; a call that fails inside the tool is never settled.