← Back to blog

CSV to JSON API — Convert CSV and JSON with curl or Python

CSV and JSON are the two most common data exchange formats on the web, and almost every automation hits the seam between them: an API returns JSON, but the downstream spreadsheet importer wants CSV. Or a legacy export hands you CSV, and your agent needs JSON objects to reason about. You can write a converter by hand every time, or you can call one endpoint and move on.

Agent Media Tools ships a CSV ↔ JSON conversion API that handles both directions with a single POST. It is one of the smallest tools in the toolbox, but it quietly removes a whole class of boilerplate from agent workflows. This guide shows the real endpoint, real curl and Python examples, and how the same conversion is exposed as an MCP tool for agents.

Why convert CSV and JSON with an API?

Writing a CSV parser is a classic "I'll just do it inline" task that goes wrong in predictable places:

• Quoted fields — a value containing a comma ("Smith, John") breaks naive split(',') parsers.
• Embedded quotes — CSV escapes quotes by doubling them (""), which is awkward to handle by hand.
• Headers drift — the same data from two sources rarely has the same column order, and hand-rolled mappers silently misalign rows.
• Escaping in the other direction — turning JSON back into CSV means knowing which values need quoting and how to escape them.

The conversion endpoint centralizes that logic: you send raw input and a direction, and you get back a ready-to-use result plus metadata (headers, row count, output format). No dependencies, no edge-case debugging in your pipeline.

The endpoint: POST /api/csv-convert

The API is a single public endpoint that takes JSON in the request body:

Field	Type	Required	Description
input	string	yes	The CSV text or JSON text to convert
direction	string	yes	json2csv or csv2json

It returns {"success": true, ...} with the converted output in a result field, or {"success": false, "error": "..."} on invalid input. No API key is required for this endpoint, so it works from any script, CI job, or one-off command.

Convert JSON to CSV with curl

Start with an array of objects. The API reads the union of all keys across the array as the CSV header row, so objects don't need to share identical key order.

curl -s https://agentmediatools.com/api/csv-convert \
  -H "Content-Type: application/json" \
  -d '{
    "direction": "json2csv",
    "input": "[{\"name\":\"Ada\",\"role\":\"Engineer\",\"city\":\"London\"},{\"name\":\"Grace\",\"role\":\"Admiral\",\"city\":\"Arlington\"}]"
  }'

Response:

{
  "success": true,
  "result": "name,role,city\nAda,Engineer,London\nGrace,Admiral,Arlington",
  "headers": ["name", "role", "city"],
  "rows": 2,
  "format": "csv"
}

Notice the shape: result is the CSV string, headers lists the generated column order, and rows counts the data rows. Values that contain commas, quotes, or newlines are automatically quoted and escaped — try a value like "Smith, John" and the output will come back correctly quoted.

Convert CSV to JSON with curl

The reverse direction takes CSV text with a header row and produces pretty-printed JSON:

curl -s https://agentmediatools.com/api/csv-convert \
  -H "Content-Type: application/json" \
  -d '{
    "direction": "csv2json",
    "input": "name,role,city\nAda,Engineer,London\nGrace,Admiral,Arlington"
  }'

Response:

{
  "success": true,
  "result": "[\n  {\n    \"name\": \"Ada\",\n    \"role\": \"Engineer\",\n    \"city\": \"London\"\n  },\n  {\n    \"name\": \"Grace\",\n    \"role\": \"Admiral\",\n    \"city\": \"Arlington\"\n  }\n]",
  "rows": 2,
  "format": "json"
}

The header row becomes the object keys, and every following row becomes one object. The parser understands comma-containing quoted fields, so "Smith, John" stays a single value instead of splitting into two columns.

Python example with requests

Here is the same conversion in Python using the standard requests library. The pattern works identically in any HTTP client — this is a plain REST endpoint, so there is no SDK to install.

import json
import requests

def convert(input_text, direction):
    r = requests.post(
        "https://agentmediatools.com/api/csv-convert",
        json={"input": input_text, "direction": direction},
        timeout=30,
    )
    r.raise_for_status()
    return r.json()

# JSON -> CSV
orders = [
    {"id": 1, "item": "laptop", "price": 1200},
    {"id": 2, "item": "monitor", "price": 300},
]
csv_out = convert(json.dumps(orders), "json2csv")
print(csv_out["result"])
# id,item,price
# 1,laptop,1200
# 2,monitor,300

# CSV -> JSON
json_out = convert("id,item,price\n1,laptop,1200\n2,monitor,300", "csv2json")
rows = json.loads(json_out["result"])
print(rows[0]["item"])  # laptop

One practical tip: when you convert CSV to JSON, parse result with json.loads() right away so the rest of your pipeline works with native objects instead of strings.

Agent use cases

The endpoint is especially useful as a glue step inside agent workflows, where data almost never arrives in the shape you want:

• Spreadsheet handoff — after an agent collects JSON records from an API, convert to CSV and hand the string to a spreadsheet tool or attach it to a report.
• Legacy import — parse a vendor CSV export into JSON objects, then feed those objects to a structured API that requires JSON.
• Normalizing tool output — two tools returning differently-shaped data become comparable once both are converted to a consistent row/object shape.
• Inline with other text tools — the same toolbox includes JSON formatting and validation, case conversion, and slug generation, so a data pipeline can stay entirely on one host.

MCP access: csv_convert

The same conversion is exposed to AI agents as the csv_convert MCP tool, with the same two inputs (input and direction). If you connect an MCP-capable client to the hosted endpoint at https://agentmediatools.com/api/mcp, the tool appears in the agent's tool list and the agent can call it directly — no prompt engineering, no copy-pasting curl commands. See our Claude MCP setup guide for the general connection pattern, and the Agent Hub for the full tool catalog.

For higher-volume or authenticated workflows, API keys start with mt_ and are passed as Authorization: Bearer mt_... — the same key format used across the agent API surface.

What the endpoint handles for you

Because the conversion logic runs server-side, you get consistent behavior without vendoring a parser:

• Automatic header generation from the union of keys when converting JSON → CSV.
• Quoting and escape handling for commas, double quotes, and newlines in values.
• Comma-containing quoted-field parsing when converting CSV → JSON.
• Row counts and header metadata in the response, so downstream code can validate before consuming.

Limits and boundaries

Keep the honest product boundaries in mind. The conversion is text-in, text-out — it does not fetch URLs, read files, stream large datasets, or support fields containing embedded line breaks. For big exports or full RFC-style CSV handling, use a dedicated local parser. If you need spreadsheet file generation (real .xlsx / .docx output), that's a separate endpoint — see our Excel & Word generation guide.

CSV ↔ JSON conversion is one of those boring utilities that pays for itself the first time a pipeline stops breaking on a quoted comma. One POST, both directions, and it works from curl, Python, or directly as an MCP tool for your agent.