---
seo_title: JSON to TOML API for Converting JSON Files to TOML | EnConvert
meta_desc: Convert JSON to TOML via POST /v1/convert/json-to-toml. Upload a .json file, get TOML back directly or as a presigned URL. Null values return a 400 error.
keywords: json to toml api, convert json to toml, json to toml converter api, json to toml rest api, json file to toml online api, json to toml python requests, json to toml curl, json config to toml api
---

# JSON to TOML API

The JSON to TOML API converts a JSON file to TOML format with a single request to `POST /v1/convert/json-to-toml`. Upload a `.json` file via multipart form data and receive the converted TOML directly, or set `direct_download=false` to get metadata with a presigned download URL. JSON arrays are wrapped under an `items` key and scalar values under a `value` key, since TOML requires a top-level table.

---

## Endpoint

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

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

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

**Output format:** `.toml` (`application/toml`)

---

## 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 be UTF-8 encoded. Must not contain `null` values. |
| `output_filename` | `string` | No | Input filename | Custom output filename. The `.toml` extension is added automatically. |
| `direct_download` | `boolean` | No | `true` | When `true`, returns raw TOML bytes. When `false`, returns metadata with a presigned download URL. |

---

## Conversion Rules

- **JSON object** passes through directly:
  ```json
  {"database": {"host": "localhost", "port": 5432}}
  ```
  Becomes:
  ```toml
  [database]
  host = "localhost"
  port = 5432
  ```

- **JSON array** is wrapped under an `items` key (TOML requires a top-level table):
  ```json
  [1, 2, 3]
  ```
  Becomes:
  ```toml
  items = [1, 2, 3]
  ```

- **Scalar value** is wrapped under a `value` key:
  ```json
  42
  ```
  Becomes:
  ```toml
  value = 42
  ```

<div class="alert alert-warning">
<strong>Important:</strong> TOML does not support <code>null</code> values. If your JSON contains any <code>null</code> values, the conversion will fail with a 400 error. Remove or replace <code>null</code> values before converting.
</div>

---

## Response

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

```
HTTP 200 OK
Content-Type: application/toml
Content-Disposition: inline; filename="config_20260405_123456789.toml"
```

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

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

---

## Code Examples

### Python

```python
import requests

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

with open("config.toml", "wb") as out:
    out.write(response.content)
```

### Node.js

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

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

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

### PHP

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

### Go

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

req, _ := http.NewRequest("POST", "https://api.enconvert.com/v1/convert/json-to-toml", 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 to TOML conversion failed (typically due to `null` values) |
| `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 |
| Null values | Not supported (TOML limitation) |
| Monthly conversions | Plan-dependent |

---

## Frequently asked questions

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

Send a `multipart/form-data` POST request to `POST /v1/convert/json-to-toml` with your `.json` file in the `file` field, authenticating with an `X-API-Key` header or a JWT `Authorization: Bearer` token. By default the response body is the raw TOML bytes.

### Why does my JSON to TOML conversion fail with a 400 error?

TOML does not support `null` values, so any JSON containing `null` fails with a `400 Bad Request`. A `400` is also returned when the upload is not a `.json` file or the JSON content is invalid.

### Can I convert a JSON array or a scalar value to TOML?

Yes. Because TOML requires a top-level table, a JSON array is wrapped under an `items` key and a scalar value is wrapped under a `value` key.

### How do I get a download URL instead of the raw TOML file?

Set `direct_download=false` in the request. The API then returns JSON metadata including a `presigned_url`, `object_key`, `filename`, `file_size`, and `conversion_time_seconds`.

### What file size limit applies to JSON to TOML conversions?

The maximum file size is plan-dependent (Founding plan: 5 MB). Files exceeding your plan's limit return `413 Payload Too Large`.