---
seo_title: TOML to JSON API for Converting TOML Files to JSON | EnConvert
meta_desc: Convert TOML to JSON via POST /v1/convert/toml-to-json. Upload a .toml file and get pretty-printed JSON back directly or via a presigned download URL.
keywords: toml to json api, convert toml to json, toml to json converter api, toml to json rest api, parse toml to json api, toml to json python requests, toml to json curl, toml config file to json api
---

# TOML to JSON API

The TOML to JSON API converts a TOML file to JSON format with a single request to `POST /v1/convert/toml-to-json`. Upload a `.toml` file via multipart form data and receive pretty-printed, 2-space-indented JSON directly, or set `direct_download=false` to get metadata with a presigned download URL. TOML datetime values are preserved as ISO-8601 strings.

---

## Endpoint

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

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

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

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

---

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

---

## Conversion Rules

Direct mapping from TOML to JSON:

```toml
[database]
host = "localhost"
port = 5432

[database.credentials]
user = "admin"
password = "secret"

features = ["auth", "logging"]
```

Becomes:

```json
{
  "database": {
    "host": "localhost",
    "port": 5432,
    "credentials": {
      "user": "admin",
      "password": "secret"
    }
  },
  "features": ["auth", "logging"]
}
```

- TOML tables become JSON objects
- TOML arrays become JSON arrays
- TOML datetime values are serialized as ISO-8601 strings
- Output is 2-space indented with unicode preserved

---

## Response

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

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

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

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

---

## Code Examples

### Python

```python
import requests

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

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

### Node.js

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

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

const json = await response.json();
```

### PHP

```php
$ch = curl_init("https://api.enconvert.com/v1/convert/toml-to-json");
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.toml")]
]);
$json = curl_exec($ch);
curl_close($ch);
```

### Go

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

req, _ := http.NewRequest("POST", "https://api.enconvert.com/v1/convert/toml-to-json", 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 `.toml` file |
| `400 Bad Request` | Invalid TOML content |
| `400 Bad Request` | TOML to JSON conversion failed |
| `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 |
| Monthly conversions | Plan-dependent |

---

## Frequently asked questions

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

Send a `multipart/form-data` POST request to `POST /v1/convert/toml-to-json` with your `.toml` 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 JSON bytes.

### How are TOML datetime values represented in the JSON output?

TOML datetime values are serialized as ISO-8601 strings. TOML tables become JSON objects and TOML arrays become JSON arrays, with 2-space indentation and unicode preserved.

### Can I get a presigned download URL instead of the raw JSON?

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

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

A `400 Bad Request` is returned when the upload is not a `.toml` file, the TOML content is invalid, or the conversion itself fails. The file must also be UTF-8 encoded.