Convert CSV to JSON

To convert CSV to JSON, send one POST to /v1/csv-to-json with the CSV 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 CSV 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.csv",
  "header": true
}

200 OK
payment-response: <base64 settlement receipt>

{
  "source_url": "https://grist.tools/samples/documents/garden-plots.csv",
  "delimiter": ",",
  "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.csv, 220 bytes. Five-line comma-separated table of garden plots with a header row, quoted fields holding commas and doubled quotes, an empty field and number-like values such as 08 and 10.50. The request sets header to true. The recorded run returned 396 bytes of JSON, 1.8 times the source size, with 4 rows and 5 columns.

03Format notes

CSV as a source

CSV has no magic signature, so the check is on the text itself: the body must be strict UTF-8 with no NUL bytes, a missing charset is read as UTF-8, a UTF-8 byte order mark is accepted, and any other declared charset is refused. csv-to-json then detects the delimiter from the first rows unless one is supplied. Every value stays a string, which preserves leading zeros in codes and trailing zeros in decimals. With headers on by default, each row becomes an object; blank headings receive generated column names and repeated ones gain numeric suffixes. Short rows are padded with empty strings, while records whose fields are all whitespace are skipped. Structural budgets bound records, columns, cells and diagnostics during parsing, and the response reports the delimiter that was used.

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 CSV to JSON?

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

How large can the CSV 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
• JSON to CSV
• TSV to JSON
• XLSX to JSON