YAML Formatter API Documentation¶

Overview¶

The YAML Formatter API validates YAML content, ensuring it is syntactically correct and properly formatted.
It supports single and multi-document YAML inputs and returns a prettified YAML output.
If the YAML is invalid, detailed error information (including line and column numbers when available) is returned.
This API supports Body, URL, and File input modes.

Endpoint (POST)¶

POST https://api.apidatatools.com/yaml-formatter-api

Headers¶

Header	Type	Required	Description
`x-api-key`	string	Yes	Your API key for authentication
`x-source-type`	string	No	Input mode: `body` (default), `url`, or `file`
`x-tab-space`	integer	No	Number of spaces for indentation in the formatted YAML

Accepted File Extensions¶

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

Input Example (Body Mode)¶

Header:

x-source-type: body
Content-Type: text/plain
x-api-key: YOUR_API_KEY

Body:

name: John Doe
age: 30
skills:
  - Python
  - YAML

Input Example (URL Mode)¶

Header:

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

Body:

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

Input Example (File Mode)¶

Header:

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

Body:

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

Example Request¶

Synchronous (Body Input)¶

curl -X POST "https://api.apidatatools.com/yaml-formatter-api" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-source-type: body" \
  -H "x-tab-space: 2" \
  -d 'name: John\nage: 25\nskills:\n  - Python\n  - YAML'

Asynchronous (Remote File URL)¶

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

Asynchronous (Input File)¶

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

Example Response¶

Successful (Body Mode)¶

Status Code: 200 OK

{
  "status": "success",
  "request_id": "b1f2e3d4-5678-90ab-cdef-1234567890ab",
  "file": "https://downloads.apidatatools.com/apidatatools_convert_abcdef123456.yaml",
  "preview": "name: John Doe\nage: 30\nskills:\n  - Python\n  - YAML\n"
}

Async Job Accepted¶

Status Code: 202 Accepted

{
  "status": "accepted",
  "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "status_url": "https://api.apidatatools.com/jobs/a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "request_id": "b1f2e3d4-5678-90ab-cdef-1234567890ab"
}

Error Handling¶

Error Code	HTTP Status	Description	Example
`INVALID_YAML`	400	YAML syntax error with details	`{"status":"error","error":"INVALID_YAML","details":{"message":"mapping values are not allowed here","line":3,"column":5}}`
`YAML_SERIALIZATION_FAILED`	400	Failed to pretty-print YAML	`{"status":"error","error":"YAML_SERIALIZATION_FAILED","details":{"message":"Failed to pretty-print YAML."}}`
`INVALID_BODY`	400	Invalid JSON body for URL/File mode	`{"status":"error","error":"INVALID_BODY","details":{"message":"Body must be valid JSON."}}`
`INVALID_URL`	400	URL missing or invalid	`{"status":"error","error":"INVALID_URL","details":{"message":"Missing or invalid 'url'."}}`
`URL_UNREACHABLE`	400	URL cannot 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."}}`
`INVALID_FILE`	400	File path missing or invalid	`{"status":"error","error":"INVALID_FILE","details":{"message":"Missing or invalid 'file'."}}`
`INVALID_FILE_EXTENSION`	400	Unsupported file extension	`{"status":"error","error":"INVALID_FILE_EXTENSION","details":{"message":"Invalid or unsupported file extension"}}`
`FILE_UNAVAILABLE`	400	File not accessible 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":"File exceeds plan limit."}}`
`PAYLOAD_TOO_LARGE`	413	Request body exceeds allowed size	`{"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 / Processing¶

{
  "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "status": "queued",
  "message": "Your job is being processed.",
  "retry_after": 2
}

Success¶

{
  "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "status": "success",
  "created_at": 1712345678,
  "updated_at": 1712345690,
  "result": {
    "status": "success",
    "file": "https://downloads.apidatatools.com/apidatatools_convert_abcdef123456.yaml",
    "request_id": "b1f2e3d4-5678-90ab-cdef-1234567890ab",
    "preview": "name: John Doe\nage: 30\nskills:\n  - Python\n  - YAML\n"
  }
}

Failed¶

{
  "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "status": "failed",
  "error": {
    "code": "INVALID_YAML",
    "message": "mapping values are not allowed here",
    "details": {
      "line": 3,
      "column": 5
    }
  }
}

Notes for Developers¶

The API supports three input modes:
body: Direct YAML text in request body (synchronous).
url: Remote YAML file URL (asynchronous).
file: Uploaded YAML file reference (asynchronous).
For asynchronous jobs, a job_id and status_url are returned. Use the status endpoint to poll job progress.
The x-tab-space header controls indentation in the formatted YAML output. Default is 4.
The response always includes a request_id for traceability.
Output files are temporarily stored and automatically expire after plan-defined retention.
Ensure URLs are publicly accessible and use http or https.