YAML to XML API Documentation¶

Overview¶

The YAML to XML API converts YAML content into a well-structured XML document.
It supports single and multi-document YAML inputs and ensures proper tag sanitization for valid XML output.
This API can operate in three modes:

Body Mode (synchronous conversion)
URL Mode (asynchronous remote file processing)
File Mode (asynchronous S3 file processing)

The output is stored securely and returned as a downloadable file link.

Endpoint (POST)¶

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

Headers¶

Header	Description	Default
`x-source-type`	Defines input source type: `body`, `url`, or `file`.	`body`
`x-root-name`	Custom root element name for the XML output.	`root`
`x-tab-space`	Number of spaces used for indentation in XML output.	`2`
`x-api-key`	Your API key for authentication	`abcd1234xyz`

Accepted File Extensions¶

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

Input Example (Body Mode)¶

name: Example
version: 1.0
items:
  - id: 1
    name: Item One
  - id: 2
    name: Item Two

Input Example (URL Mode)¶

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

Input Example (File Mode)¶

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

Example Request¶

Synchronous (Body Input)¶

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

Asynchronous (Remote File URL)¶

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

Asynchronous (Input File)¶

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

Example Response¶

Successful (Body Mode)¶

{
  "status": "success",
  "request_id": "b7f2e8c1-9d4a-4e8b-9c2a-8f2a1a6e9b3f",
  "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.xml",
  "preview": "<data><name>Example</name><version>1.0</version><items><id>1</id><name>Item One</name></items>..."
}

Async Job Accepted¶

{
  "status": "accepted",
  "job_id": "job-9f8a7e6b-4c3d-2a1b-0e9f-8d7c6b5a4f3e",
  "status_url": "https://api.apidatatools.com/jobs/job-9f8a7e6b-4c3d-2a1b-0e9f-8d7c6b5a4f3e",
  "request_id": "b7f2e8c1-9d4a-4e8b-9c2a-8f2a1a6e9b3f"
}

Error Handling¶

Error Code	Description	Example
`INVALID_YAML`	YAML validation failed due to syntax or structure issues.	`{"status":"error","error":"INVALID_YAML","details":{"message":"YAML validation failed."}}`
`YAML_TO_XML_STRUCTURE_FAILED`	Failed to convert YAML structure into XML-ready form.	`{"status":"error","error":"YAML_TO_XML_STRUCTURE_FAILED","details":{"message":"Failed to convert YAML structure into XML-ready form."}}`
`YAML_TO_XML_SERIALIZATION_FAILED`	XML serialization failed during conversion.	`{"status":"error","error":"YAML_TO_XML_SERIALIZATION_FAILED","details":{"message":"Failed to serialize YAML to XML."}}`
`INVALID_BODY`	Request body is not valid JSON or YAML.	`{"status":"error","error":"INVALID_BODY","details":{"message":"Body must be valid JSON."}}`
`INVALID_URL`	Provided URL is invalid or unreachable.	`{"status":"error","error":"INVALID_URL","details":{"message":"URL must be valid http/https."}}`
`URL_UNREACHABLE`	Remote URL could not be reached.	`{"status":"error","error":"URL_UNREACHABLE","details":{"message":"Could not reach URL."}}`
`URL_NOT_OK`	Remote URL returned non-200 HTTP status.	`{"status":"error","error":"URL_NOT_OK","details":{"message":"URL returned HTTP 404, expected 200."}}`
`FILE_TOO_LARGE`	File exceeds plan limit.	`{"status":"error","error":"FILE_TOO_LARGE","details":{"message":"File exceeds plan limit."}}`
`INVALID_FILE_EXTENSION`	File extension not allowed for this tool.	`{"status":"error","error":"INVALID_FILE_EXTENSION","details":{"message":"Invalid or unsupported file extension."}}`
`INVALID_SOURCE_TYPE`	Header `x-source-type` is not one of `body`, `url`, or `file`.	`{"status":"error","error":"INVALID_SOURCE_TYPE","details":{"message":"Must be 'url' or 'file'."}}`
`INTERNAL_ERROR`	Unexpected internal error occurred.	`{"status":"error","error":"INTERNAL_ERROR","details":{"message":"Failed to process your request"}}`

Async Job Status¶

To check the status of an asynchronous job (URL or File mode):

Endpoint¶

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

Example Status Response for Async¶

Queued¶

{
  "job_id": "job-9f8a7e6b-4c3d-2a1b-0e9f-8d7c6b5a4f3e",
  "status": "queued",
  "message": "Your job is being processed.",
  "retry_after": 2
}

Success¶

{
  "job_id": "job-9f8a7e6b-4c3d-2a1b-0e9f-8d7c6b5a4f3e",
  "status": "success",
  "created_at": 1712345678,
  "updated_at": 1712345689,
  "result": {
    "status": "success",
    "request_id": "b7f2e8c1-9d4a-4e8b-9c2a-8f2a1a6e9b3f",
    "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.xml",
    "preview": "<root><name>Example</name><version>1.0</version>...</root>"
  }
}

Failed¶

{
  "job_id": "job-9f8a7e6b-4c3d-2a1b-0e9f-8d7c6b5a4f3e",
  "status": "failed",
  "error": {
    "code": "INVALID_YAML",
    "message": "YAML validation failed.",
    "details": {"line": 3, "column": 5}
  }
}

Notes for Developers¶

The API supports multi-document YAML; multiple documents are wrapped under <document> elements inside the root tag.
The root tag and indentation can be customized via headers.
For asynchronous operations (url or file mode), a job ID is returned immediately with HTTP 202 status.
Use the Status API to poll job progress and retrieve results.
Each response includes a unique request_id for traceability.
The preview field contains the first 100 KB of the generated XML for quick inspection.
Ensure that uploaded or remote files conform to allowed extensions and size limits defined by your plan.