Excel to YAML API Documentation¶

Overview¶

The Excel to YAML API converts Microsoft Excel files (.xls or .xlsx) into YAML format.
It supports: - Single-sheet and multi-sheet Excel files. - Optional header row handling. - Sheet selection by name or index. - Custom YAML indentation.

The API can be used in three modes:

Body Mode (Synchronous) — Upload Excel file content directly in the request body.
URL Mode (Asynchronous) — Provide a remote file URL for conversion.
File Mode (Asynchronous) — Provide a previously uploaded file reference for conversion.

Endpoint (POST)¶

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

Headers¶

Header	Type	Required	Description
`x-api-key`	string	Yes	Your API key for authentication.
`x-source-type`	string	Optional	Input source type: `body` (default), `url`, or `file`.
`x-has-header`	string	Optional	`"true"` (default) or `"false"` — whether the first row contains column headers.
`x-sheet-name`	string	Optional	Name of the sheet to convert.
`x-sheet-index`	integer	Optional	Index (0-based) of the sheet to convert.
`x-tab-space`	integer	Optional	Number of spaces for YAML indentation (default: 2).
`Content-Type`	string	Required	Must be `application/octet-stream` for binary body uploads.

Accepted File Extensions¶

Mode	Allowed Extensions
Body	`.xls`, `.xlsx`
URL	`.xls`, `.xlsx`
File	`.xls`, `.xlsx`

Input Example (Body Mode)¶

Headers:

x-source-type: body
x-has-header: true
x-api-key: YOUR_API_KEY
Content-Type: application/octet-stream

Body: Binary Excel file.

Input Example (URL Mode)¶

Headers:

x-source-type: url
x-api-key: YOUR_API_KEY
Content-Type: application/json

Body:

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

Input Example (File Mode)¶

Headers:

x-source-type: file
x-api-key: YOUR_API_KEY
Content-Type: application/json

Body:

{
  "file": "user123/upl_abc123/sample.xlsx"
}

Example Request¶

Synchronous (Body Input)¶

curl -X POST "https://api.apidatatools.com/excel-to-yaml-api" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-source-type: body" \
  -H "x-has-header: true" \
  -H "Content-Type: application/octet-stream" \
  --data-binary "@sample.xlsx"

Asynchronous (Remote File URL)¶

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

Asynchronous (Input File)¶

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

Example Response¶

Successful (Body Mode)¶

Status Code: 200 OK

{
  "status": "success",
  "request_id": "b2c8f3e2-9f1a-4a8b-9c6d-4e2f9f1a8b3c",
  "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.yaml",
  "preview": "Sheet1:\n  - Name: John\n    Age: 30\n  - Name: Jane\n    Age: 25\n"
}

Async Job Accepted (URL or File Mode)¶

Status Code: 202 Accepted

{
  "status": "accepted",
  "job_id": "job_123e4567-e89b-12d3-a456-426614174000",
  "status_url": "https://api.apidatatools.com/jobs/job_123e4567-e89b-12d3-a456-426614174000",
  "request_id": "b2c8f3e2-9f1a-4a8b-9c6d-4e2f9f1a8b3c"
}

Error Handling¶

Error Code	HTTP Status	Description	Example
`INVALID_EXCEL_CONTENT_TYPE`	400	Input is not valid Excel bytes.	`{"error":"INVALID_EXCEL_CONTENT_TYPE","details":{"message":"Excel content must be raw bytes."}}`
`EXCEL_READ_FAILED`	400	Failed to read Excel file.	`{"error":"EXCEL_READ_FAILED","details":{"message":"Failed to read Excel file."}}`
`EXCEL_TO_YAML_CONVERSION_FAILED`	400	Conversion from Excel to YAML failed.	`{"error":"EXCEL_TO_YAML_CONVERSION_FAILED","details":{"message":"Failed to convert Excel rows to YAML data."}}`
`YAML_SERIALIZATION_FAILED`	400	YAML serialization failed.	`{"error":"YAML_SERIALIZATION_FAILED","details":{"message":"Failed to serialize YAML."}}`
`INVALID_URL`	400	Invalid or missing URL in async mode.	`{"error":"INVALID_URL","details":{"message":"Missing or invalid 'url'."}}`
`URL_UNREACHABLE`	400	Could not reach provided URL.	`{"error":"URL_UNREACHABLE","details":{"message":"Could not reach URL."}}`
`URL_NOT_OK`	400	URL returned non-200 HTTP status.	`{"error":"URL_NOT_OK","details":{"message":"URL returned HTTP 404, expected 200."}}`
`FILE_TOO_LARGE`	413	File exceeds plan limit.	`{"error":"FILE_TOO_LARGE","details":{"message":"Remote file exceeds plan limit."}}`
`INVALID_FILE_EXTENSION`	400	File extension not supported.	`{"error":"INVALID_FILE_EXTENSION","details":{"message":"Extension '.txt' is not allowed for this tool."}}`
`FILE_UNAVAILABLE`	400	File not found in storage.	`{"error":"FILE_UNAVAILABLE","details":{"message":"Could not access file."}}`
`PAYLOAD_TOO_LARGE`	413	Request body exceeds plan limit.	`{"error":"PAYLOAD_TOO_LARGE","details":{"message":"Request body exceeds 5120KB limit for your plan."}}`
`INTERNAL_ERROR`	500	Unexpected internal 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 provided in the 202 Accepted response.

Endpoint¶

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

Example Status Response for Async¶

Pending Job¶

{
  "job_id": "job_123e4567-e89b-12d3-a456-426614174000",
  "status": "queued",
  "message": "Your job is being processed.",
  "retry_after": 2
}

Successful Job¶

{
  "job_id": "job_123e4567-e89b-12d3-a456-426614174000",
  "status": "success",
  "created_at": 1712345678,
  "updated_at": 1712345690,
  "result": {
    "status": "success",
    "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.yaml",
    "request_id": "b2c8f3e2-9f1a-4a8b-9c6d-4e2f9f1a8b3c",
    "preview": "Sheet1:\n  - Name: John\n    Age: 30\n"
  }
}

Failed Job¶

{
  "job_id": "job_123e4567-e89b-12d3-a456-426614174000",
  "status": "failed",
  "error": {
    "code": "EXCEL_READ_FAILED",
    "message": "Failed to read Excel file.",
    "details": {"message": "Invalid Excel format"}
  }
}

Notes for Developers¶

The API supports synchronous and asynchronous processing depending on x-source-type.
For large files or remote URLs, use asynchronous mode (url or file).
YAML output is stored temporarily and accessible via the returned file URL.
The request_id is unique per request and can be used for debugging or support.
Use the Status API to poll job progress for async operations.
Multi-sheet Excel files are represented as a YAML dictionary with sheet names as keys.