---
seo_title: JSON to YAML API for Converting JSON Files to YAML | EnConvert
meta_desc: Convert JSON to YAML with POST /v1/convert/json-to-yaml. Block-style, human-readable output with key order preserved. Raw YAML bytes or presigned download URL.
keywords: json to yaml api, convert json to yaml rest api, json to yaml converter api, json config to yaml api, json file to yaml online api, api to transform json into yaml, json to yml conversion endpoint
---

# JSON to YAML API

Convert a JSON file to YAML with a single request to `POST /v1/convert/json-to-yaml`. The conversion is a direct mapping with no restructuring: output is human-readable block-style YAML with the original key order and unicode characters preserved. By default the response is raw YAML bytes; set `direct_download=false` to receive metadata with a presigned download URL instead.

---

## Endpoint

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

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

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

**Output format:** `.yaml` (`application/x-yaml`)

---

## 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. |
| `output_filename` | `string` | No | Input filename | Custom output filename. The `.yaml` extension is added automatically. |
| `direct_download` | `boolean` | No | `true` | When `true`, returns raw YAML bytes. When `false`, returns metadata with a presigned download URL. |

---

## Conversion Rules

Direct mapping from JSON to YAML with no restructuring:

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

Becomes:

```yaml
database:
  host: localhost
  port: 5432
  credentials:
    user: admin
    password: secret
features:
- auth
- logging
```

- Output uses **block style** (multi-line, human-readable), not flow style
- **Key order is preserved** from the original JSON
- Unicode characters are preserved as-is

---

## Response

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

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

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

```json
{
    "presigned_url": "https://spaces.example.com/...",
    "object_key": "env/files/{project_id}/json-to-yaml/config_20260405_123456789.yaml",
    "filename": "config_20260405_123456789.yaml",
    "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-yaml",
        headers={"X-API-Key": "sk_your_private_key"},
        files={"file": ("config.json", f, "application/json")}
    )

with open("config.yaml", "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-yaml", {
    method: "POST",
    headers: { "X-API-Key": "sk_your_private_key" },
    body: form
});

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

### PHP

```php
$ch = curl_init("https://api.enconvert.com/v1/convert/json-to-yaml");
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")]
]);
$yaml = 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-yaml", 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 YAML 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 JSON to YAML with a REST API?

Send a `multipart/form-data` POST request to `/v1/convert/json-to-yaml` with your `.json` file in the `file` field, authenticated with an `X-API-Key` header or a JWT `Authorization: Bearer` token. The response is the converted YAML.

### Does the JSON to YAML conversion preserve key order?

Yes. Key order from the original JSON is preserved, unicode characters are kept as-is, and the structure is mapped directly with no restructuring.

### Is the YAML output block style or flow style?

Output uses block style (multi-line, human-readable YAML) rather than inline flow style, as shown in the conversion example on this page.

### Can I get a presigned download URL instead of raw YAML bytes?

Yes. Set `direct_download=false` to receive a metadata response with a `presigned_url`, `object_key`, `filename`, `file_size`, and `conversion_time_seconds`.

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

A `400` is returned when the file is not a `.json` file, the content is not valid JSON, or the conversion fails. Files over your plan's size limit return `413 Payload Too Large`.