CSV to YAML API Documentation¶

Overview¶

The CSV to YAML API converts CSV data into a YAML-formatted document.
It supports three input modes:

Body Mode – Direct CSV content in the request body (synchronous)
URL Mode – Remote CSV file accessible via HTTP/HTTPS (asynchronous)
File Mode – CSV file previously uploaded to the platform (asynchronous)

The output is a single YAML document representing a list of row objects.
Each row corresponds to a CSV record, with column names as keys.

Endpoint (POST)¶

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

Headers¶

Header	Type	Required	Description
`x-api-key`	string	Yes	Your API key for authentication
`x-source-type`	string	Optional	Input source: `body` (default), `url`, or `file`
`x-has-header`	string	Optional	`"0"`, `"false"`, or `"no"` if CSV has no header row
`x-delimiter`	string	Optional	Custom delimiter (e.g., `,`, `;`, `\t`) default `,`
`x-tab-space`	integer	Optional	Number of spaces for YAML indentation (default: 2)
`Content-Type`	string	Required	`text/plain` or `application/json` depending on mode

Accepted File Extensions¶

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

Input Example (Body Mode)¶

Headers

x-source-type: body
Content-Type: text/plain

Body

name,age,city
Alice,30,New York
Bob,25,London

Input Example (URL Mode)¶

Headers

x-source-type: url
Content-Type: application/json

Body

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

Input Example (File Mode)¶

Headers

x-source-type: file
Content-Type: application/json

Body

{
  "file": "user123/uploads/upl_abc123/sample.csv"
}

Example Request¶

Synchronous (Body Input)¶

curl -X POST "https://api.apidatatools.com/csv-to-yaml-api" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-source-type: body" \
  -H "Content-Type: text/plain" \
  -d 'name,age,department
Alice,30,Engineering
Bob,25,Marketing'

Asynchronous (Remote File URL)¶

curl -X POST "https://api.apidatatools.com/csv-to-yaml-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.csv"}'

Asynchronous (Input File)¶

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

Example Response¶

Successful (Body Mode)¶

Status Code: 200 OK

{
  "status": "success",
  "request_id": "b9f1d2e3-4a56-789b-cdef-1234567890ab",
  "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.yaml",
  "preview": "- name: Alice\n  age: '30'\n  city: New York\n- name: Bob\n  age: '25'\n  city: London\n"
}

Async Job Accepted¶

Status Code: 202 Accepted

{
  "status": "accepted",
  "job_id": "job_1234567890abcdef",
  "status_url": "https://api.apidatatools.com/jobs/job_1234567890abcdef",
  "request_id": "b9f1d2e3-4a56-789b-cdef-1234567890ab"
}

Error Handling¶

Error Code	HTTP Status	Description	Example
`INVALID_CSV`	400	CSV is empty or cannot be parsed	`{"status":"error","error":"INVALID_CSV","details":{"message":"Empty CSV input."}}`
`CSV_TO_YAML_CONVERSION_FAILED`	400	Failed to convert CSV to YAML	`{"status":"error","error":"CSV_TO_YAML_CONVERSION_FAILED","details":{"message":"Failed to convert CSV to row dictionaries."}}`
`YAML_SERIALIZATION_FAILED`	400	YAML serialization failed	`{"status":"error","error":"YAML_SERIALIZATION_FAILED","details":{"message":"Failed to serialize rows to YAML."}}`
`INVALID_URL`	400	Invalid or missing URL in async mode	`{"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."}}`
`INVALID_FILE`	400	Invalid or missing file path	`{"status":"error","error":"INVALID_FILE","details":{"message":"Missing or invalid 'file'."}}`
`INVALID_FILE_EXTENSION`	400	File extension not supported	`{"status":"error","error":"INVALID_FILE_EXTENSION","details":{"message":"Invalid or unsupported file extension"}}`
`FILE_UNAVAILABLE`	400	File not accessible in S3	`{"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	Body exceeds plan limit	`{"status":"error","error":"PAYLOAD_TOO_LARGE","details":{"message":"Request body exceeds limit."}}`
`INTERNAL_ERROR`	500	Unexpected internal error	`{"status":"error","error":"INTERNAL_ERROR","details":{"message":"Failed to process your request"}}`

Async Job Status¶

Endpoint

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

Response Examples

Queued or Processing¶

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

Successful¶

{
  "job_id": "job_1234567890abcdef",
  "status": "success",
  "created_at": 1712345678,
  "updated_at": 1712345690,
  "result": {
    "status": "success",
    "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.yaml",
    "request_id": "b9f1d2e3-4a56-789b-cdef-1234567890ab",
    "preview": "- name: Alice\n  age: '30'\n  city: New York\n"
  }
}

Failed¶

{
  "job_id": "job_1234567890abcdef",
  "status": "failed",
  "created_at": 1712345678,
  "updated_at": 1712345680,
  "error": {
    "code": "INVALID_CSV",
    "message": "Failed to parse CSV.",
    "details": {"message": "Error tokenizing data"}
  }
}

Notes for Developers¶

The API supports synchronous (body) and asynchronous (url/file) modes.
For asynchronous jobs, use the status_url to poll job status until completion.
YAML indentation can be customized using the x-tab-space header.
When CSV lacks headers, set x-has-header: 0 to auto-generate column names.
The output YAML file is temporarily hosted and will expire after the retention period defined by the user’s plan.