Skip to content

YAML to CSV API Documentation

Overview

The YAML to CSV API converts YAML content into a CSV file.
It supports multi-document YAML, nested structures, and automatically flattens complex YAML objects into tabular CSV rows.
Each YAML document becomes one row in the resulting CSV.

This API supports three input modes:

  • Body Mode (Synchronous) — Direct YAML text in the request body.
  • URL Mode (Asynchronous) — Provide a remote file URL for processing.
  • File Mode (Asynchronous) — Provide a previously uploaded file reference.

Endpoint (POST)

POST https://api.apidatatools.com/yaml-to-csv-api

Headers

Header Type Required Description
Content-Type application/json or text/plain Yes Defines the content type of the request body.
x-source-type body | url | file Optional Determines input mode. Defaults to body.
x-api-key <API_KEY> Yes API key for authentication.

Accepted File Extensions

Mode Allowed Extensions
URL / File .yml, .yaml, .txt, .log

Input Example (Body Mode)

---
name: Alice
age: 30
skills:
  - Python
  - Data Science
---
name: Bob
age: 25
skills:
  - JavaScript
  - Web Development

Input Example (URL Mode)

{
  "url": "https://example.com/data/sample.yaml"
}

Input Example (File Mode)

{
  "file": "user_uploads/abc123/sample.yaml"
}

Example Request

Synchronous (Body Input)

curl -X POST "https://api.apidatatools.com/yaml-to-csv-api" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: text/plain" \
  -H "x-source-type: body" \
  -d '<yaml input>'

Asynchronous (Remote File URL)

curl -X POST "https://api.apidatatools.com/yaml-to-csv-api" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-source-type: url" \
  -d '{"url": "https://example.com/data/sample.yaml"}'

Asynchronous (Input File)

curl -X POST "https://api.apidatatools.com/yaml-to-csv-api" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-source-type: file" \
  -d '{"file": "user_uploads/abc123/sample.yaml"}'

Example Response

Successful (Body Mode)

Status Code: 200 OK 

{
  "status": "success",
  "request_id": "e3b2f6b8-4b2a-4f7a-9a1a-123456789abc",
  "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.csv",
  "preview": "name,age,skills_0,skills_1\nAlice,30,Python,Data Science\nBob,25,JavaScript,Web Development\n"
}

Async Job Accepted

Status Code: 202 Accepted 

{
  "status": "accepted",
  "job_id": "b7f1a2c3-4d5e-678f-9012-abcdef123456",
  "status_url": "https://api.apidatatools.com/jobs/b7f1a2c3-4d5e-678f-9012-abcdef123456",
  "request_id": "a1b2c3d4-e5f6-7890-1234-56789abcdef0"
}

Error Handling

Error Code HTTP Status Description Example
INVALID_YAML 400 YAML validation failed. {"status":"error","error":"INVALID_YAML","details":{"message":"YAML validation failed."}}
YAML_FLATTEN_FAILED 400 Failed to flatten YAML structure. {"status":"error","error":"YAML_FLATTEN_FAILED","details":{"message":"Failed to flatten YAML structure for CSV conversion."}}
CSV_CONVERSION_FAILED 400 Failed to convert YAML to CSV. {"status":"error","error":"CSV_CONVERSION_FAILED","details":{"message":"Failed to convert YAML to CSV."}}
INVALID_URL 400 Invalid or missing URL in async mode. {"status":"error","error":"INVALID_URL","details":{"message":"Missing or invalid 'url'."}}
URL_UNREACHABLE 400 Could not reach the provided URL. {"status":"error","error":"URL_UNREACHABLE","details":{"message":"Could not reach URL."}}
URL_NOT_OK 400 URL returned non-200 HTTP response. {"status":"error","error":"URL_NOT_OK","details":{"message":"URL returned HTTP 404, expected 200."}}
FILE_TOO_LARGE 413 File exceeds plan limit. {"status":"error","error":"FILE_TOO_LARGE","details":{"message":"Remote file exceeds plan limit."}}
INVALID_FILE 400 Missing or invalid file path. {"status":"error","error":"INVALID_FILE","details":{"message":"Missing or invalid 'file'."}}
INVALID_FILE_EXTENSION 400 Unsupported file extension. {"status":"error","error":"INVALID_FILE_EXTENSION","details":{"message":"Invalid or unsupported file extension."}}
EMPTY_BODY 400 Request body is empty. {"status":"error","error":"EMPTY_BODY","details":{"message":"Request body is empty."}}
PAYLOAD_TOO_LARGE 413 Request body exceeds allowed size. {"status":"error","error":"PAYLOAD_TOO_LARGE","details":{"message":"Request body exceeds limit."}}
INTERNAL_ERROR 500 Unexpected internal failure. {"status":"error","error":"INTERNAL_ERROR","details":{"message":"Failed to process your request"}}

Async Job Status

Endpoint:
GET https://api.apidatatools.com/jobs/{job_id}

Response Examples:

Queued / Processing

{
  "job_id": "b7f1a2c3-4d5e-678f-9012-abcdef123456",
  "status": "queued",
  "created_at": 1712345678,
  "updated_at": 1712345678,
  "message": "Your job is being processed.",
  "retry_after": 2
}

Success

{
  "job_id": "b7f1a2c3-4d5e-678f-9012-abcdef123456",
  "status": "success",
  "created_at": 1712345678,
  "updated_at": 1712345690,
  "result": {
    "status": "success",
    "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.csv",
    "request_id": "e3b2f6b8-4b2a-4f7a-9a1a-123456789abc",
    "preview": "name,age,skills_0,skills_1\nAlice,30,Python,Data Science\nBob,25,JavaScript,Web Development\n"
  }
}

Failed

{
  "job_id": "b7f1a2c3-4d5e-678f-9012-abcdef123456",
  "status": "failed",
  "created_at": 1712345678,
  "updated_at": 1712345690,
  "error": {
    "code": "INVALID_YAML",
    "message": "YAML validation failed.",
    "details": {
      "message": "Invalid YAML syntax at line 3."
    }
  }
}

Notes for Developers

  • The API automatically flattens nested YAML structures for CSV output.
  • Multi-document YAML files are supported; each document becomes a separate CSV row.
  • The preview field in responses contains the first 100 KB of the generated CSV.
  • For large files or remote URLs, use asynchronous mode (x-source-type: url or file).
  • Use the status_url returned in async responses to poll job status.
  • All responses include a unique request_id for traceability.
  • Uploaded or generated files are stored securely and expire after the retention period defined by your plan.