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.

Endpoint

POST /v1/csv-to-json

Price

$0.005 per call

Service

csv-to-json

Docs

/docs/csv-to-json

01Limits

02Example

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

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
}

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.

03Format 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.

04Errors

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

05Questions

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.

06Related

• Documents guide
• CSV to JSON
• XLSX to JSON