YAML to Excel API Documentation¶

Overview¶

The YAML to Excel API converts YAML content into an Excel (.xlsx) file.
Each YAML document is validated, flattened, and converted into a row in an Excel sheet.
The resulting Excel file is returned as a downloadable link or as an asynchronous job if a remote file or uploaded file is used.

Base URL:
https://api.apidatatools.com/yaml-to-excel-api

Endpoint (POST)¶

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

Headers¶

Header	Type	Required	Description
`x-api-key`	string	Yes	Your API key for authentication
`Content-Type`	string	Yes	`application/json` or `text/plain`
`x-source-type`	string	Optional	One of `body`, `url`, or `file` (default: `body`)

Accepted File Extensions¶

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

Input Example (Body Mode)¶

---
name: John Doe
age: 30
skills:
  - Python
  - AWS
---
name: Jane Smith
age: 25
skills:
  - JavaScript
  - React

Input Example (URL Mode)¶

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

Input Example (File Mode)¶

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

Example Request¶

Synchronous (Body Input)¶

curl -X POST "https://api.apidatatools.com/yaml-to-excel-api" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: text/plain" \
  -H "x-source-type: body" \
  --data-binary @sample.yaml

Asynchronous (Remote File URL)¶

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

Asynchronous (Input File)¶

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

Example Response¶

Successful (Body Mode)¶

{
  "status": "success",
  "request_id": "b3c1e2f0-1234-4a56-9abc-7890def12345",
  "file": "https://downloads.apidatatools.com/apidatatools_convert_abcdef1234567890.xlsx",
  "preview": ""
}

Async Job Accepted¶

{
  "status": "accepted",
  "job_id": "8f7a2b3c-1234-4d56-9e78-abcdef123456",
  "status_url": "https://api.apidatatools.com/jobs/8f7a2b3c-1234-4d56-9e78-abcdef123456",
  "request_id": "b3c1e2f0-1234-4a56-9abc-7890def12345"
}

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 Excel conversion."}}`
`EXCEL_CONVERSION_FAILED`	400	Failed to convert YAML to Excel	`{"status":"error","error":"EXCEL_CONVERSION_FAILED","details":{"message":"Failed to convert YAML to Excel."}}`
`EXCEL_WRITE_FAILED`	400	Failed to write Excel file	`{"status":"error","error":"EXCEL_WRITE_FAILED","details":{"message":"Failed to write Excel file."}}`
`INVALID_URL`	400	Invalid or missing URL	`{"status":"error","error":"INVALID_URL","details":{"message":"Missing or invalid 'url'."}}`
`URL_UNREACHABLE`	400	URL could not be reached	`{"status":"error","error":"URL_UNREACHABLE","details":{"message":"Could not reach URL."}}`
`URL_NOT_OK`	400	URL returned non-200 status	`{"status":"error","error":"URL_NOT_OK","details":{"message":"URL returned HTTP 404, expected 200."}}`
`INVALID_FILE`	400	Invalid or missing 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."}}`
`FILE_UNAVAILABLE`	400	File not accessible	`{"status":"error","error":"FILE_UNAVAILABLE","details":{"message":"Could not access file."}}`
`FILE_TOO_LARGE`	413	File exceeds plan limit	`{"status":"error","error":"FILE_TOO_LARGE","details":{"message":"File exceeds plan limit."}}`
`PAYLOAD_TOO_LARGE`	413	Request body too large	`{"status":"error","error":"PAYLOAD_TOO_LARGE","details":{"message":"Request body exceeds allowed limit."}}`
`INTERNAL_ERROR`	500	Unexpected server error	`{"status":"error","error":"INTERNAL_ERROR","details":{"message":"Failed to process your request"}}`

Async Job Status¶

To check the status of an asynchronous job, use the status_url returned in the accepted response.

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

Example Status Response for Async¶

Pending / Queued¶

{
  "job_id": "8f7a2b3c-1234-4d56-9e78-abcdef123456",
  "status": "queued",
  "created_at": 1712345678,
  "updated_at": 1712345678,
  "message": "Your job is being processed.",
  "retry_after": 2
}

Successful¶

{
  "job_id": "8f7a2b3c-1234-4d56-9e78-abcdef123456",
  "status": "success",
  "created_at": 1712345678,
  "updated_at": 1712345690,
  "result": {
    "status": "success",
    "file": "https://downloads.apidatatools.com/apidatatools_convert_abcdef1234567890.xlsx",
    "request_id": "b3c1e2f0-1234-4a56-9abc-7890def12345",
    "preview": ""
  }
}

Failed¶

{
  "job_id": "8f7a2b3c-1234-4d56-9e78-abcdef123456",
  "status": "failed",
  "created_at": 1712345678,
  "updated_at": 1712345680,
  "error": {
    "code": "INVALID_YAML",
    "message": "YAML validation failed.",
    "details": {
      "message": "YAML validation failed."
    }
  }
}

Notes for Developers¶

The API supports three modes:
Body Mode (synchronous) – send YAML directly in the request body.
URL Mode (asynchronous) – provide a remote file URL.
File Mode (asynchronous) – provide a previously uploaded file path.
For asynchronous operations (url or file), a job_id is returned immediately with a 202 Accepted response.
Use the provided status_url to poll job status.
The resulting Excel file is stored temporarily and accessible via a secure download link.
Always include the x-source-type header to specify the input mode.