Convert JSON to CSV

To convert JSON to CSV, send one POST to /v1/json-to-csv with the JSON 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/json-to-csv

Price

$0.005 per call

Service

json-to-csv

Docs

/docs/json-to-csv

01Limits

02Example

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

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

{
  "url": "https://grist.tools/samples/documents/garden-harvest.json"
}

200 OK
payment-response: <base64 settlement receipt>

{
  "source_url": "https://grist.tools/samples/documents/garden-harvest.json",
  "columns": [
    "week",
    "crop",
    "kg",
    "plots",
    "note"
  ],
  "csv": "week,crop,kg,plots,note\r\n1,radish,2.5,\"[\"\"A1\"\",\"\"B2\"\"]\",\r\n1,lettuce,4,,\"first cut, outer leaves only\"\r\n2,peas,3.25,\"[\"\"A2\"\"]\",",
  "row_count": 3,
  "truncated": false
}

Source file: documents/garden-harvest.json, 233 bytes. JSON array of three harvest records whose keys differ from row to row, with a nested array value, a null and a string holding a comma. The recorded run returned 126 bytes of CSV, 54% of the source size, with 3 rows and 5 columns.

03Format notes

JSON as a source

JSON reaches json-to-csv as a UTF-8 document, and a leading byte order mark is stripped before parsing. The top level must be an array of objects or a single object, which is treated as one row; an array holding scalars, or any other top-level value, is refused because it has no columns. Text that does not parse as JSON is refused as well. A nested value inside a cell is walked iteratively before serialisation, and nesting beyond the serialiser's depth cap is rejected instead of overflowing the stack. The max_rows setting keeps the leading rows, marks the result truncated when later rows are dropped, and infers columns from the kept rows only. Key order follows JavaScript enumeration, so canonical array-index keys within an object come first in ascending order and their textual order is not preserved.

CSV as a target

json-to-csv renders with papaparse's unparse, which quotes and escapes fields to RFC-4180 and separates records with CRLF. Without a columns list, the header is the union of row keys in the order they are first seen, and within each row JavaScript enumerates array-index keys numerically before other keys. A columns list both selects and orders the fields. Nested arrays and objects are written into a cell as JSON text, while null values and missing keys become empty fields. Nothing guards against spreadsheet formulas: values starting with an equals sign, plus, minus or at sign are kept exactly, so untrusted data needs spreadsheet-side import controls. The max_rows setting limits retained records; when rows are dropped, truncated is set and columns are inferred only from the rows that were kept.

04Errors

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

05Questions

What does it cost to convert JSON to CSV?

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

How large can the JSON 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