API reference

Convert JSON to TOML

Convert a JSON object to a TOML 1.0 document.

GET POST /api/convert/json-to-toml MCP tool json_to_toml

Parses input strictly as JSON and writes it as TOML 1.0.0. The top level must be an object. Strings, booleans and numbers become key = value pairs (numbers are copied as written, so 1.0 stays a float); non-empty objects become [table] sections and arrays of objects become [[array]] tables; objects inside other arrays become inline tables; an empty object is {}. Within each table, plain keys come first, then sub-tables. Keys that are not bare (A–Z, a–z, 0–9, _ and -) are quoted. TOML has no null, so a null anywhere is an error that names its JSON Pointer; so is an integer beyond 64 bits. The result is formatted like /api/toml/format output.

Browser version (runs locally): TOML Format & Validate.

Try it
Credentials
Remember these credentials

Not saved: you will paste them again next time.

No credentials yet? Get a client ID and secret. They are sent only to this site, in an Authorization: Basic header.

POST /api/convert/json-to-toml with a JSON body

Parameters

Parameter Type Default Description
input required string (≤ 200000 chars) — The JSON text (an object), as a string field or a raw text/plain POST body.
indent integer (1–8) 2 Spaces per level for arrays that are broken over several lines.
max_line_length integer (0–1000) 120 Arrays longer than this are broken one element per line, and longer lines are reported (line-length). 0 turns both off.
sort_keys boolean false Sort keys in every table and inline table, by UTF-16 code units. Array order never changes.

Also accepted on every endpoint: format (json | text). Parameters may come from the query string, a JSON object body, an urlencoded or multipart form, or (for input) a text/plain body.

Global parameters
Parameter Type Default Description
format json | text json json returns the documented object. text returns only the primary value as text/plain (see "Text output").

Response 200 application/json

Field Type Description
toml string The TOML document, ending with a line break (empty for {}).

Text output (format=text, text/plain): The TOML document.

Errors

Errors are JSON: {"error": "<message>", "code": "<code>", "param": "<name>"?}.

Status Code When
422 unprocessable_input input is not valid JSON (the message gives line and column), the top level is not an object, or a value cannot be written as TOML: a null, an integer beyond 64 bits, or a string with an unpaired surrogate. The message names the JSON Pointer.
400 invalid_parameter input is longer than 200,000 characters, or an option is out of range.
400 missing_parameter A required parameter is absent.
400 unknown_parameter A parameter name is not in the table above (typos are rejected, not ignored).
413 payload_too_large The request body exceeds 1 MiB.
405 method_not_allowed A method other than GET, POST or OPTIONS.

Behaviour

  • Idempotent: the same arguments always return the same result.
  • Requires a client ID and secret (authentication). Each call is recorded as one metadata row against your client ID; inputs and outputs are never stored or logged. Responses carry cache-control: no-store.
  • CORS: any origin may call this endpoint from a browser, using your credentials.

Examples

Responses below were produced by running each request through this code at build time. Long strings are shortened.

Nested objects and an array of objects

curl -X POST 'https://util.caruana.me/api/convert/json-to-toml' \
  -H 'content-type: application/json' \
  -d '{"input":"{\"name\":\"demo\",\"version\":\"1.0.0\",\"server\":{\"host\":\"0.0.0.0\",\"port\":8080,\"tls\":{\"enabled\":true}},\"users\":[{\"name\":\"ada\",\"roles\":[\"admin\"]},{\"name\":\"lin\",\"roles\":[]}],\"ratio\":1.0}"}'

Response 200

{
  "toml": "name = \"demo\"\nversion = \"1.0.0\"\nratio = 1.0\n\n[server]\nhost = \"0.0.0.0\"\nport = 8080\n\n[server.tls]\nenabled = true\n\n[[users… (69 more characters)"
}
Same call as an MCP tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "json_to_toml",
    "arguments": {
      "input": "{\"name\":\"demo\",\"version\":\"1.0.0\",\"server\":{\"host\":\"0.0.0.0\",\"port\":8080,\"tls\":{\"enabled\":true}},\"users\":[{\"name\":\"ada\",\"roles\":[\"admin\"]},{\"name\":\"lin\",\"roles\":[]}],\"ratio\":1.0}"
    }
  }
}

Sorted keys, quoted keys and a long array

curl -X POST 'https://util.caruana.me/api/convert/json-to-toml' \
  -H 'content-type: application/json' \
  -d '{"input":"{\"zone\":\"eu\",\"a.b\":1,\"tags\":[\"alpha\",\"beta\",\"gamma\",\"delta\",\"epsilon\",\"zeta\",\"eta\",\"theta\"],\"empty\":{}}","sort_keys":true,"max_line_length":40}'

Response 200

{
  "toml": "\"a.b\" = 1\nempty = {}\ntags = [\n  \"alpha\",\n  \"beta\",\n  \"gamma\",\n  \"delta\",\n  \"epsilon\",\n  \"zeta\",\n  \"eta\",\n  \"theta\",\n]\nzone = \"eu\"\n"
}
Same call as an MCP tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "json_to_toml",
    "arguments": {
      "input": "{\"zone\":\"eu\",\"a.b\":1,\"tags\":[\"alpha\",\"beta\",\"gamma\",\"delta\",\"epsilon\",\"zeta\",\"eta\",\"theta\"],\"empty\":{}}",
      "sort_keys": true,
      "max_line_length": 40
    }
  }
}