JSON to TSV API Documentation¶

Overview¶

The JSON to TSV API converts structured or nested JSON data into a tab-separated values (TSV) format.
It validates the input JSON, flattens nested structures, and returns a downloadable TSV file.
This API supports synchronous processing for direct JSON input and asynchronous processing for remote files or URLs.

Endpoint (POST)¶

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

Headers¶

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

Accepted File Extensions¶

This tool accepts the following file extensions for URL or file mode:

.txt, .json, .log

Input Example (Body Mode)¶

{
  "user": {
    "id": 123,
    "name": "Alice",
    "roles": ["admin", "editor"]
  },
  "active": true
}

Input Example (URL Mode)¶

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

Input Example (File Mode)¶

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

Example Request¶

Synchronous (Body Input)¶

curl -X POST "https://api.apidatatools.com/json-to-tsv-api" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"user":{"id":123,"name":"Alice","roles":["admin","editor"]},"active":true}'

Asynchronous (Remote File URL)¶

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

Asynchronous (Input File)¶

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

Example Response¶

Successful (Body Mode)¶

{
  "status": "success",
  "request_id": "c1a2b3d4e5",
  "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.tsv",
  "preview": "user_id\tuser_name\tuser_roles_0\tuser_roles_1\tactive\n123\tAlice\tadmin\teditor\ttrue\n"
}

Async Job Accepted¶

{
  "status": "accepted",
  "job_id": "job_123456789",
  "status_url": "https://api.apidatatools.com/jobs/job_123456789",
  "request_id": "c1a2b3d4e5"
}

Error Handling¶

Error Code	HTTP Status	Description	Example
`INVALID_JSON`	400	Input JSON is malformed or invalid	`{"status":"error","error":"INVALID_JSON","details":{"message":"Expecting value at line 1 column 1"}}`
`TSV_CONVERSION_FAILED`	400	Failed to convert JSON to TSV	`{"status":"error","error":"TSV_CONVERSION_FAILED","details":{"message":"TSV conversion failed"}}`
`EMPTY_BODY`	400	Request body is empty	`{"status":"error","error":"EMPTY_BODY","details":{"message":"Request body is empty."}}`
`INVALID_BODY_ENCODING`	400	Base64 decoding failed	`{"status":"error","error":"INVALID_BODY_ENCODING","details":{"message":"Failed to base64-decode request body."}}`
`FILE_TOO_LARGE`	413	File exceeds plan limit	`{"status":"error","error":"FILE_TOO_LARGE","details":{"message":"Remote file exceeds plan limit."}}`
`INVALID_URL`	400	URL is missing or invalid	`{"status":"error","error":"INVALID_URL","details":{"message":"URL must be valid http/https."}}`
`URL_UNREACHABLE`	400	Remote URL cannot be reached	`{"status":"error","error":"URL_UNREACHABLE","details":{"message":"Could not reach URL"}}`
`URL_NOT_OK`	400	Remote URL returned non-200 status	`{"status":"error","error":"URL_NOT_OK","details":{"message":"URL returned HTTP 404"}}`
`INVALID_FILE_EXTENSION`	400	File extension not supported	`{"status":"error","error":"INVALID_FILE_EXTENSION","details":{"message":"Extension '.xml' is not allowed"}}`
`FILE_UNAVAILABLE`	400	File not found or inaccessible	`{"status":"error","error":"FILE_UNAVAILABLE","details":{"message":"Could not access file"}}`
`PAYLOAD_TOO_LARGE`	413	Body exceeds allowed size	`{"status":"error","error":"PAYLOAD_TOO_LARGE","details":{"message":"Request body exceeds 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 following endpoint:

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

Example Status Response for Async¶

Queued¶

{
  "job_id": "job_123456789",
  "status": "queued",
  "created_at": 1712345678,
  "updated_at": 1712345678,
  "message": "Your job is being processed.",
  "retry_after": 2
}

Success¶

{
  "job_id": "job_123456789",
  "status": "success",
  "created_at": 1712345678,
  "updated_at": 1712345688,
  "result": {
    "status": "success",
    "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.tsv",
    "request_id": "abcd234565432rgfds",
    "preview": "test  test123"
  }
}

Failed¶

{
  "job_id": "job_123456789",
  "status": "failed",
  "created_at": 1712345678,
  "updated_at": 1712345680,
  "error": {
    "code": "INVALID_JSON",
    "message": "JSON validation failed.",
    "details": {"line": 1, "column": 2}
  }
}

Notes for Developers¶

The API automatically validates JSON before conversion.
Nested JSON structures are flattened using underscore (_) separators.
Lists are indexed numerically (e.g., roles_0, roles_1).
The TSV output is UTF-8 encoded and tab-separated.
The preview field in the response contains the first 100 KB of TSV data.
For asynchronous operations (url or file mode), a job ID is returned; use the status endpoint to track progress.
Each response includes a unique request_id for traceability.
Ensure that remote files or URLs conform to allowed extensions and size limits defined by your plan.