---
seo_title: JSON to CSV API for Converting JSON Arrays to CSV | EnConvert
meta_desc: Convert JSON to CSV with POST /v1/convert/json-to-csv. Requires a JSON array of objects; headers come from the first object's keys. Comma-delimited output.
keywords: json to csv api, convert json to csv rest api, json to csv converter api, json array to csv api, json objects to csv rows, api to export json as csv, json file to csv endpoint, flatten json to csv api
---

# JSON to CSV API

Convert a JSON file to CSV with a single request to `POST /v1/convert/json-to-csv`. The input must be a JSON array of objects; column headers are derived from the first object's keys, and rows are comma-delimited with `QUOTE_MINIMAL` quoting. By default the response is raw CSV bytes; set `direct_download=false` to receive metadata with a presigned download URL instead.

---

## Endpoint

```
POST /v1/convert/json-to-csv
```

**Content-Type:** `multipart/form-data`

**Accepted input:** `.json` files (UTF-8 encoded)

**Output format:** `.csv` (`text/csv`)

---

## Authentication

Requires either a private API key or a JWT token from a public key.

```
X-API-Key: sk_your_private_key
```

Or:

```
Authorization: Bearer <jwt_token>
```

---

## Request Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `file` | file | Yes | -- | The `.json` file to convert. Must contain a JSON array of objects. UTF-8 encoded. |
| `output_filename` | `string` | No | Input filename | Custom output filename. The `.csv` extension is added automatically. |
| `direct_download` | `boolean` | No | `true` | When `true`, returns raw CSV bytes. When `false`, returns metadata with a presigned download URL. |

---

## Conversion Rules

```json
[
  {"name": "Alice", "age": 30, "city": "London"},
  {"name": "Bob", "age": 25, "city": "Paris"}
]
```

Becomes:

```csv
name,age,city
Alice,30,London
Bob,25,Paris
```

- Input **must** be a JSON array of objects (list of dictionaries)
- Column headers are derived from the **first object's keys only**
- Delimiter is comma (not configurable)
- Quoting follows `QUOTE_MINIMAL` -- values containing commas, quotes, or newlines are quoted
- Nested objects or arrays in values are serialized as their string representation (not flattened)

<div class="alert alert-warning">
<strong>Important:</strong> If objects in the array have different keys, extra keys in later objects are silently dropped. Missing keys produce empty values. For best results, ensure all objects have the same set of keys.
</div>

---

## Response

### Direct Download (`direct_download=true`, default)

```
HTTP 200 OK
Content-Type: text/csv
Content-Disposition: inline; filename="data_20260405_123456789.csv"
```

### Metadata Response (`direct_download=false`)

```json
{
    "presigned_url": "https://spaces.example.com/...",
    "object_key": "env/files/{project_id}/json-to-csv/data_20260405_123456789.csv",
    "filename": "data_20260405_123456789.csv",
    "file_size": 1234,
    "conversion_time_seconds": 0.03
}
```

---

## Code Examples

### Python

```python
import requests

with open("data.json", "rb") as f:
    response = requests.post(
        "https://api.enconvert.com/v1/convert/json-to-csv",
        headers={"X-API-Key": "sk_your_private_key"},
        files={"file": ("data.json", f, "application/json")}
    )

with open("data.csv", "wb") as out:
    out.write(response.content)
```

### Node.js

```javascript
const form = new FormData();
form.append("file", fs.createReadStream("data.json"));

const response = await fetch("https://api.enconvert.com/v1/convert/json-to-csv", {
    method: "POST",
    headers: { "X-API-Key": "sk_your_private_key" },
    body: form
});

const csv = await response.text();
```

### PHP

```php
$ch = curl_init("https://api.enconvert.com/v1/convert/json-to-csv");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: sk_your_private_key"],
    CURLOPT_POSTFIELDS => ["file" => new CURLFile("data.json", "application/json")]
]);
$csv = curl_exec($ch);
curl_close($ch);
```

### Go

```go
body := &bytes.Buffer{}
writer := multipart.NewWriter(body)
part, _ := writer.CreateFormFile("file", "data.json")
file, _ := os.Open("data.json")
io.Copy(part, file)
writer.Close()

req, _ := http.NewRequest("POST", "https://api.enconvert.com/v1/convert/json-to-csv", body)
req.Header.Set("Content-Type", writer.FormDataContentType())
req.Header.Set("X-API-Key", "sk_your_private_key")
resp, _ := http.DefaultClient.Do(req)
```

---

## Error Responses

| Status | Condition |
|--------|-----------|
| `400 Bad Request` | File is not a `.json` file |
| `400 Bad Request` | Invalid JSON content |
| `400 Bad Request` | JSON must be an array of objects for CSV conversion |
| `400 Bad Request` | JSON array is empty |
| `400 Bad Request` | JSON array must contain objects (dictionaries) |
| `401 Unauthorized` | Missing or invalid API key / JWT token |
| `402 Payment Required` | Monthly ops allowance exhausted |
| `413 Payload Too Large` | File exceeds plan's maximum file size |

---

## Limits

| Limit | Value |
|-------|-------|
| Max file size | Plan-dependent (Founding: 5 MB) |
| Input encoding | UTF-8 only |
| Input structure | Array of objects only |
| Monthly conversions | Plan-dependent |

## Frequently asked questions

### How do I convert a JSON array to CSV with a REST API?

Send a `multipart/form-data` POST request to `/v1/convert/json-to-csv` with a `.json` file containing an array of objects in the `file` field, authenticated with an `X-API-Key` header or a JWT `Authorization: Bearer` token. The response is comma-delimited CSV.

### What happens if the JSON objects have different keys?

Column headers come from the first object's keys only. Extra keys in later objects are silently dropped and missing keys produce empty values, so ensure all objects share the same key set for best results.

### Are nested JSON objects flattened into CSV columns?

No. Nested objects or arrays in values are serialized as their string representation rather than flattened into separate columns.

### Can I change the CSV delimiter?

No. The delimiter is always a comma and is not configurable. Quoting follows `QUOTE_MINIMAL`, so values containing commas, quotes, or newlines are quoted automatically.

### Why does the JSON to CSV API return 400 Bad Request?

A `400` is returned when the file is not `.json`, the JSON is invalid, the JSON is not an array of objects, or the array is empty. Oversized files return `413 Payload Too Large`.