Data Formats¶

Convert structured data between JSON, CSV, XML, YAML, and TOML — in any direction. Two endpoints cover both workflows: a JSON response for inline data, and a direct streaming file download.

Base URL¶

https://convert.toolkitapi.io

Endpoints¶

Authentication is via the X-API-Key header (or Authorization: Bearer).

Supported conversions¶

Any pair among json, csv, xml, yaml, toml is supported. A few direction-specific rules apply:

• JSON → CSV requires an array of objects. Nested objects are flattened with dot notation (e.g. address.city).
• JSON → TOML requires a top-level object (dict), not an array.
• CSV → JSON emits an array of objects (with header) or arrays (without header).

GET /v1/convert/data¶

Stream a converted file download. Provide url or content as the source.

Query parameters¶

Response¶

200 OK with a Content-Type matching the target format and a Content-Disposition: attachment header.

Example — curl (JSON → YAML)¶

curl -L -G "https://convert.toolkitapi.io/v1/convert/data" \
  -H "X-API-Key: $CONVERT_API_KEY" \
  --data-urlencode 'content={"name":"test","value":42}' \
  --data-urlencode 'from_format=json' \
  --data-urlencode 'to_format=yaml' \
  -o output.yaml

Example — Python (remote CSV → JSON file)¶

import httpx

resp = httpx.get(
    "https://convert.toolkitapi.io/v1/convert/data",
    headers={"X-API-Key": CONVERT_API_KEY},
    params={
        "url": "https://example.com/products.csv",
        "from_format": "csv",
        "to_format": "json",
        "has_header": True,
        "filename": "products.json",
    },
)
resp.raise_for_status()
open("products.json", "wb").write(resp.content)

Example — JavaScript (inline JSON → CSV)¶

const params = new URLSearchParams({
  content: JSON.stringify([{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }]),
  from_format: "json",
  to_format: "csv",
});

const resp = await fetch(
  `https://convert.toolkitapi.io/v1/convert/data?${params}`,
  { headers: { "X-API-Key": process.env.CONVERT_API_KEY } },
);
const csv = await resp.text();
console.log(csv);
// id,name
// 1,Alice
// 2,Bob

POST /v1/convert/data¶

Convert a JSON request body and return the result as JSON. All conversion logic is shared with the GET endpoint; only the transport differs.

Request body¶

Provide either data or url — supplying both, or neither, returns 422.

Response fields¶

Example — curl (JSON → YAML)¶

curl -X POST https://convert.toolkitapi.io/v1/convert/data \
  -H "X-API-Key: $CONVERT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_format": "json",
    "to_format": "yaml",
    "data": {"name": "test", "value": 42}
  }'

{
  "success": true,
  "from_format": "json",
  "to_format": "yaml",
  "result": "name: test\nvalue: 42\n",
  "metadata": {}
}

Example — Python (JSON array → CSV, nested fields flattened)¶

import httpx

resp = httpx.post(
    "https://convert.toolkitapi.io/v1/convert/data",
    headers={"X-API-Key": CONVERT_API_KEY},
    json={
        "from_format": "json",
        "to_format": "csv",
        "data": [
            {"id": 1, "name": "Alice", "address": {"city": "London"}},
            {"id": 2, "name": "Bob", "address": {"city": "Paris"}},
        ],
    },
)
print(resp.json()["result"])
# id,name,address.city
# 1,Alice,London
# 2,Bob,Paris

Example — JavaScript (XML → JSON)¶

const resp = await fetch("https://convert.toolkitapi.io/v1/convert/data", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.CONVERT_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    from_format: "xml",
    to_format: "json",
    data: "<users><user><name>Alice</name><age>30</age></user></users>",
    strip_namespaces: true,
  }),
});
const { result } = await resp.json();
console.log(JSON.parse(result));

Python SDK Examples¶

from toolkitapi import Convert

cv = Convert(api_key="tk_...")

# JSON → YAML
result = cv.data(
    from_format="json",
    to_format="yaml",
    data={"name": "Alice", "scores": [95, 87, 92]},
)
print(result["result"])
# name: Alice
# scores:
# - 95
# - 87
# - 92

# JSON array → CSV (nested fields flattened with dot notation)
result = cv.data(
    from_format="json",
    to_format="csv",
    data=[
        {"id": 1, "name": "Alice", "address": {"city": "London"}},
        {"id": 2, "name": "Bob", "address": {"city": "Paris"}},
    ],
)
print(result["result"])
# id,name,address.city
# 1,Alice,London
# 2,Bob,Paris

# CSV → JSON
result = cv.data(
    from_format="csv",
    to_format="json",
    data="name,age\nAlice,30\nBob,25",
    has_header=True,
)
print(result["result"])
# [{"name": "Alice", "age": "30"}, {"name": "Bob", "age": "25"}]

# Download a remote CSV and get it back as YAML bytes
path = cv.data_file(
    url="https://toolkitapi.io/data/products.csv",
    from_format="csv",
    to_format="yaml",
    has_header=True,
    output_path="products.yaml",
)
print(f"Saved to {path}")

Errors¶

See Error Handling for the shared error envelope.