API Documentation

Convert data between formats (JSON, YAML, TOML, XML, INI, TOON) using our RESTful API. All conversions are tracked for analytics and future rate limiting.

Base URL

Production: https://toon-writer-api.vardon-bainbridge.workers.dev

Convert Format

Convert data from one format to another. Returns the converted data as plain text.

POST /api/convert

Request Body

Parameter Type Required Description
data string Required The input data in the source format (as a string)
from_format string Required Source format: json, yaml, toml, xml, ini, or toon
to_format string Required Target format: json, yaml, toml, xml, ini, or toon
client_id string Required Unique identifier for tracking requests (for analytics and future rate limiting)

Example Request

cURL

curl -X POST https://toon-writer-api.vardon-bainbridge.workers.dev/api/convert \
  -H "Content-Type: application/json" \
  -d '{
    "data": "{\"name\": \"Alice\", \"age\": 30}",
    "from_format": "json",
    "to_format": "ini",
    "client_id": "my-app-123"
  }'

JavaScript (Fetch)

const response = await fetch('https://toon-writer-api.vardon-bainbridge.workers.dev/api/convert', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    data: JSON.stringify({ name: 'Alice', age: 30 }),
    from_format: 'json',
    to_format: 'ini',
    client_id: 'my-app-123'
  })
});

const convertedData = await response.text();
console.log(convertedData);

Python

import requests
import json

url = 'https://toon-writer-api.vardon-bainbridge.workers.dev/api/convert'
payload = {
    'data': json.dumps({'name': 'Alice', 'age': 30}),
    'from_format': 'json',
    'to_format': 'ini',
    'client_id': 'my-app-123'
}

response = requests.post(url, json=payload)
converted_data = response.text
print(converted_data)

Response

200 OK Success

Returns the converted data as plain text with the following headers:

  • Content-Type: text/plain; charset=utf-8
  • X-Input-Format: {from_format}
  • X-Output-Format: {to_format}
name=Alice
age=30

400 Bad Request Error

Returns plain text error message:

Error: Missing required field "data"

Common errors:

  • Missing required field "client_id"
  • Missing required fields "data", "from_format", "to_format"
  • Invalid format names
  • Invalid data syntax
  • Conversion errors

500 Internal Server Error Server Error

Returns plain text error message for server-side issues.

Supported Formats

Format Code Status Notes
JSON json ✅ Fully Supported Standard JSON format
INI ini ✅ Fully Supported Configuration file format
TOML toml ⚠️ Partial Support Basic TOML support (output only for some cases)
YAML yaml 🚧 Coming Soon Requires additional library setup
XML xml 🚧 Coming Soon Requires additional library setup
TOON toon ✅ Fully Supported Universal TOON format

Access & Client ID

The client_id parameter is required for all requests. Please note that access to the TOON Writer API is now restricted to authorized partners and developers.

How to get access: Contact us via the Contact Us page. We typically review requests and revert with a unique client_id within 12 hours.

A valid Client ID helps us:

  • Ensure API security and prevent abuse
  • Track usage patterns to improve the conversion engine
  • Manage rate limits to ensure stable performance for all users

Rate Limiting

Currently, there are no rate limits on the API. However, we reserve the right to implement rate limiting in the future.

When rate limiting is implemented:

  • Free users will have limited requests per day (based on client_id)
  • Authenticated users with subscriptions will have higher limits
  • Rate limit information will be included in response headers

Error Handling

All errors are returned as plain text with appropriate HTTP status codes:

  • 400 Bad Request: Invalid request parameters or data format
  • 500 Internal Server Error: Server-side errors during conversion
  • 501 Not Implemented: Format not yet supported (requires additional setup)

Always check the response status code before processing the response body.

CORS Support

The API supports Cross-Origin Resource Sharing (CORS) and can be called from web browsers. All endpoints include appropriate CORS headers.

← Back to Converter