Convert File — ConvertaCoal — Files API

POST

/convert

Upload a file and convert it to the specified output format. The request must be sent as multipart/form-data. A successful response returns a download URL valid for 24 hours.

Required scope: convertacoal:convert

Request Parameters

Content-Type: multipart/form-data

Parameter	Type	Required	Description
file	file	required	The file to convert. Accepted formats: csv, xls, xlsx, html, json
output_format	string	required	Target format. One of: csv, xlsx, html, pdf, json

Response 200 OK

{
  "success": true,
  "data": {
    "id": 123,
    "original_filename": "document.csv",
    "input_format": "csv",
    "output_format": "xlsx",
    "download_url": "https://coals.ai/api/v1/convertacoal/download/123"
  }
}

id Unique identifier for this conversion. Use with GET /download/{id} to re-download.

download_url Pre-built download link valid for 24 hours. Requires your API key in the Authorization header.

Example Request

curl -X POST https://coals.ai/api/v1/convertacoal/convert \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/document.csv" \
  -F "output_format=xlsx"

// Using Guzzle
$response = $client->post('https://coals.ai/api/v1/convertacoal/convert', [
  'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'],
  'multipart' => [
    ['name' => 'file', 'contents' => fopen('/path/to/document.csv', 'r')],
    ['name' => 'output_format', 'contents' => 'xlsx'],
  ]
]);
$data = json_decode($response->getBody(), true);

# Using requests
import requests

response = requests.post(
  "https://coals.ai/api/v1/convertacoal/convert",
  headers={"Authorization": "Bearer YOUR_API_KEY"},
  files={"file": open("/path/to/document.csv", "rb"), "output_format": (None, "xlsx")}
)
data = response.json()

# Using net/http
require "net/http"
require "json"

uri = URI("https://coals.ai/api/v1/convertacoal/convert")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer YOUR_API_KEY"

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)

// Using fetch (Node 18+)
const response = await fetch("https://coals.ai/api/v1/convertacoal/convert", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY"
  }
});
const data = await response.json();

Error Responses

Status	Cause
400	Missing file or output_format, or unsupported format combination
401	Missing or invalid API key
403	API key missing convertacoal:convert scope
413	File exceeds the maximum size allowed by your plan
429	Monthly quota exhausted or rate limit hit