YAML to JSON API Documentation¶

Overview¶

The YAML to JSON API converts YAML content into JSON format.
It supports:

Single or multi-document YAML.
Validation of YAML syntax.
Pretty-printed JSON output.
Operation in three modes: Body, URL, and File.

This API is available at:

https://api.apidatatools.com/yaml-to-json-api

Endpoint (POST)¶

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

Headers¶

Header	Description	Required	Example
`Content-Type`	Input content type	Yes	`text/plain`
`x-source-type`	Input source type (`body`, `url`, or `file`)	Optional (default: `body`)	`body`
`x-tab-space`	Controls JSON indentation (default: 4)	Optional	`2`
`x-api-key`	API key	Yes	`<api_key>`

Accepted File Extensions¶

This tool accepts the following file extensions:

yml, yaml, txt, log

Input Example (Body Mode)¶

---
name: John Doe
age: 30
skills:
  - Python
  - YAML
---
name: Jane Smith
age: 25
skills:
  - JavaScript
  - HTML

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-json-api" \
  -H "Content-Type: text/plain" \
  -H "x-source-type: body" \
  -H "x-api-key: YOUR_API_KEY" \
  -d "<YAML_INPUT>'

Asynchronous (Remote File URL)¶

curl -X POST "https://api.apidatatools.com/yaml-to-json-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-json-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)¶

{
  "request_id": "b7c9f8e2-1a3d-4c9a-9e3b-4b8e2f7a9c2d",
  "status": "success",
  "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.json",
  "preview": "{\n    \"name\": \"John Doe\",\n    \"age\": 30,\n    \"skills\": [\"Python\", \"YAML\"]\n}"
}

Async Job Accepted¶

{
  "status": "accepted",
  "job_id": "job-7d9f2e3b-1c4a-4b7e-9f2d-8a3b4c9e2f7a",
  "status_url": "https://api.apidatatools.com/jobs/job-7d9f2e3b-1c4a-4b7e-9f2d-8a3b4c9e2f7a",
  "request_id": "b7c9f8e2-1a3d-4c9a-9e3b-4b8e2f7a9c2d"
}

Error Handling¶

Error Code	HTTP Status	Description	Example
`INVALID_YAML`	400	YAML validation failed	`{"status":"error","error":"INVALID_YAML","details":{"message":"YAML validation failed."}}`
`JSON_SERIALIZATION_FAILED`	400	Failed to convert YAML to JSON	`{"status":"error","error":"JSON_SERIALIZATION_FAILED","details":{"message":"Failed to convert YAML to JSON."}}`
`INVALID_BODY_ENCODING`	400	Body could not be decoded	`{"status":"error","error":"INVALID_BODY_ENCODING","details":{"message":"Failed to base64-decode request body."}}`
`EMPTY_BODY`	400	Request body is empty	`{"status":"error","error":"EMPTY_BODY","details":{"message":"Request body is empty."}}`
`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."}}`
`FILE_TOO_LARGE`	413	File exceeds plan limit	`{"status":"error","error":"FILE_TOO_LARGE","details":{"message":"File exceeds plan limit."}}`
`INVALID_FILE_EXTENSION`	400	Unsupported file extension	`{"status":"error","error":"INVALID_FILE_EXTENSION","details":{"message":"Invalid or unsupported file extension."}}`
`JOB_NOT_FOUND`	404	Job ID not found	`{"status":"error","error":"JOB_NOT_FOUND","details":{"message":"Job not found"}}`
`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:

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

Example Status Response for Async¶

Queued¶

{
  "job_id": "job-7d9f2e3b-1c4a-4b7e-9f2d-8a3b4c9e2f7a",
  "status": "queued",
  "message": "Your job is being processed.",
  "retry_after": 2
}

Success¶

{
  "job_id": "job-7d9f2e3b-1c4a-4b7e-9f2d-8a3b4c9e2f7a",
  "status": "success",
  "created_at": 1712345678,
  "updated_at": 1712345689,
  "result": {
    "request_id": "b7c9f8e2-1a3d-4c9a-9e3b-4b8e2f7a9c2d",
    "status": "success",
    "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.json",
    "preview": "{\n    \"name\": \"John Doe\",\n    \"age\": 30\n}"
  }
}

Failed¶

{
  "job_id": "job-7d9f2e3b-1c4a-4b7e-9f2d-8a3b4c9e2f7a",
  "status": "failed",
  "error": {
    "code": "INVALID_YAML",
    "message": "YAML validation failed.",
    "details": {
      "line": 3,
      "column": 5
    }
  }
}

Notes for Developers¶

The API supports Body, URL, and File input modes.
For Body Mode, conversion is synchronous and returns the JSON file immediately.
For URL or File Mode, the operation is asynchronous:
A job ID is returned.
Use the Status API to check job progress.
The output is uploaded to a secure storage and accessible via a temporary download link.
Each response includes a unique request_id for traceability.
Ensure proper YAML syntax before submission to avoid validation errors.
The preview field contains the first 100 KB of the converted JSON for quick inspection.