XML to TSV API Documentation¶

Overview¶

The XML to TSV API converts well-formed XML data into a tab-separated values (TSV) file.
It supports three input modes:

Body Mode (Synchronous): Direct XML content in the request body.
URL Mode (Asynchronous): Remote XML file accessible via HTTP/HTTPS.
File Mode (Asynchronous): XML file previously uploaded to the platform.

The API validates the XML structure, converts it into a structured table, and returns a downloadable TSV file link.

Endpoint (POST)¶

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

Headers¶

Header	Required	Description	Example
`Content-Type`	Yes	Must be `application/json` for body mode or `application/json` for async modes	`application/json`
`x-api-key`	Yes	Your API key for authentication	`abcd1234xyz`
`x-source-type`	Optional	Defines input mode: `body`, `url`, or `file`	`body`

Accepted File Extensions¶

Mode	Allowed Extensions
URL/File	`.txt`, `.xml`, `.log`

Input Example (Body Mode)¶

<root><item><name>John</name><age>30</age></item><item><name>Jane</name><age>25</age></item></root>

Input Example (URL Mode)¶

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

Input Example (File Mode)¶

{
  "file": "user123/uploads/sample.xml"
}

Example Request¶

Synchronous (Body Input)¶

curl -X POST "https://api.apidatatools.com/xml-to-tsv-api" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-source-type: body" \
  -H "Content-Type: application/json" \
  -d '<root><item><name>John</name><age>30</age></item></root>'

Asynchronous (Remote File URL)¶

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

Asynchronous (Input File)¶

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

Example Response¶

Successful (Body Mode)¶

{
  "status": "success",
  "request_id": "b7e2f8c1-4b3d-4a9b-9e2f-8c1b4b3d4a9b",
  "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123def456.tsv",
  "preview": "name\tage\nJohn\t30\nJane\t25\n"
}

Async Job Accepted¶

{
  "status": "accepted",
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status_url": "https://api.apidatatools.com/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "request_id": "b7e2f8c1-4b3d-4a9b-9e2f-8c1b4b3d4a9b"
}

Error Handling¶

Error Code	HTTP Status	Description	Example
`INVALID_XML`	400	XML is malformed or invalid	`{"status":"error","error":"INVALID_XML","details":{"message":"XML parsing failed.","line":2,"column":5}}`
`TSV_CONVERSION_FAILED`	400	Conversion to TSV failed	`{"status":"error","error":"TSV_CONVERSION_FAILED","details":{"message":"Failed to convert XML to TSV."}}`
`INVALID_URL`	400	URL missing or invalid	`{"status":"error","error":"INVALID_URL","details":{"message":"Missing or invalid 'url'."}}`
`URL_UNREACHABLE`	400	Remote file could not be reached	`{"status":"error","error":"URL_UNREACHABLE","details":{"message":"Could not reach URL"}}`
`URL_NOT_OK`	400	Remote file returned non-200 HTTP code	`{"status":"error","error":"URL_NOT_OK","details":{"message":"URL returned HTTP 404, expected 200."}}`
`INVALID_FILE`	400	File path missing or invalid	`{"status":"error","error":"INVALID_FILE","details":{"message":"Missing or invalid 'file'."}}`
`INVALID_FILE_EXTENSION`	400	File extension not allowed	`{"status":"error","error":"INVALID_FILE_EXTENSION","details":{"message":"Extension '.pdf' is not allowed for 'xml-to-tsv-api'."}}`
`FILE_UNAVAILABLE`	400	File not found in storage	`{"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":"Remote file exceeds plan limit."}}`
`PAYLOAD_TOO_LARGE`	413	Request body too large	`{"status":"error","error":"PAYLOAD_TOO_LARGE","details":{"message":"Request body exceeds limit."}}`
`UNKNOWN_FUNCTION`	404	Invalid endpoint	`{"status":"error","error":"UNKNOWN_FUNCTION","details":{"message":"Unsupported API endpoint."}}`
`INTERNAL_ERROR`	500	Unexpected internal 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 202 Accepted response.

Endpoint¶

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

Example Status Response for Async¶

Queued or Processing¶

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "queued",
  "message": "Your job is being processed.",
  "retry_after": 2,
  "created_at": 1712345678,
  "updated_at": 1712345678
}

Success¶

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "success",
  "created_at": 1712345678,
  "updated_at": 1712345690,
  "result": {
    "status": "success",
    "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123def456.tsv",
    "request_id": "b7e2f8c1-4b3d-4a9b-9e2f-8c1b4b3d4a9b",
    "preview": "name\tage\nJohn\t30\nJane\t25\n"
  }
}

Failed¶

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "failed",
  "created_at": 1712345678,
  "updated_at": 1712345680,
  "error": {
    "code": "INVALID_XML",
    "message": "XML parsing failed.",
    "details": {
      "message": "mismatched tag: line 3, column 10",
      "line": 3,
      "column": 10
    }
  }
}

Notes for Developers¶

The API automatically validates XML before conversion.
The output TSV file is uploaded to a secure storage and returned as a downloadable link.
For large files or remote sources, use asynchronous mode (x-source-type: url or file).
Each response includes a unique request_id for traceability.
Asynchronous jobs can be monitored using the /jobs/{job_id} endpoint.
Ensure that remote URLs are publicly accessible and use allowed file extensions.
Empty or invalid XML will result in an INVALID_XML error.
TSV preview is limited to the first 100 KB of data.