TOON Format

Convert JSON to token-efficient TOON format for LLMs. Save up to 40% on tokens.

On this page

Overview

TOON is a token-efficient notation format for structured data. When sending JSON to LLMs, TOON can reduce token counts by up to 40% — lowering costs and freeing up context window space.

The TOON format endpoints let you convert between JSON and TOON, analyze token savings, or automatically pick the most efficient format for your data.

Based on the open-source @toon-format/toon library (MIT license). All TOON endpoints process data locally on our servers — no data is sent to external AI services.

curl
curl -X POST https://api.toneai.dev/toon/llmready \
  -H "Authorization: Bearer tone_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"name":"Alice","age":30},{"name":"Bob","age":25}]'

Authentication

TOON endpoints use the same authentication as all Tone API endpoints. Include your API key as a Bearer token:

header
Authorization: Bearer tone_YOUR_KEY

Each TOON endpoint call costs 1 credit.

Endpoints

Base URL: https://api.toneai.dev

POST/toon/llmready

Convert JSON to the most token-efficient format. Compares JSON compact, TOON, and TOON with nested tables, then returns whichever uses the fewest tokens.

Request body

// Any valid JSON — object, array, nested structures
[
  {"name": "Alice", "age": 30, "role": "admin"},
  {"name": "Bob", "age": 25, "role": "user"}
]

Response

{
  "format": "toon",
  "tokens": 18,
  "saved": "35.7%",
  "output": "name\tage\trole\nAlice\t30\tadmin\nBob\t25\tuser"
}

Costs 1 credit. The format field will be 'json', 'toon', or 'toon_nested' depending on which is most efficient for your data.

POST/toon/analyze

Analyze token counts for all formats and get a recommendation. Useful for understanding potential savings before committing to a format.

Request body

// Any valid JSON
[
  {"name": "Alice", "age": 30, "role": "admin"},
  {"name": "Bob", "age": 25, "role": "user"}
]

Response

{
  "tokens": {
    "json": 28,
    "toon": 18,
    "toon_nested": 20
  },
  "savings": {
    "toon": "35.7%",
    "toon_nested": "28.6%"
  },
  "recommendation": "toon",
  "reason": "Tabular arrays detected - TOON provides good compression"
}

Costs 1 credit. Savings are calculated relative to compact JSON. Recommendation is one of: json, toon, toon_nested.

POST/toon/encode

Convert JSON data to TOON format. Optionally enable nested table encoding for data with uniform nested objects.

Request body

{
  "data": [
    {"name": "Alice", "age": 30},
    {"name": "Bob", "age": 25}
  ],
  "nestedTables": false
}

Response

{
  "output": "name\tage\nAlice\t30\nBob\t25"
}

Costs 1 credit. Set nestedTables to true when your data contains arrays of objects within objects — it can improve compression for deeply nested structures.

POST/toon/decode

Convert a TOON-encoded string back to JSON. Use this to parse TOON output from LLMs back into structured data.

Request body

{
  "input": "name\tage\nAlice\t30\nBob\t25"
}

Response

{
  "output": [
    {"name": "Alice", "age": 30},
    {"name": "Bob", "age": 25}
  ]
}

Costs 1 credit. The input must be a valid TOON-encoded string.

n8n Integration

The TOON Format node is included in the official n8n-nodes-toneapi community package alongside the Tone API node.

Installation

If you already have the Tone API node installed, you have the TOON Format node too — they ship in the same package. Otherwise, install it:

package name
n8n-nodes-toneapi

Usage

1. Add the TOON Format node to your workflow.

2. Select your Tone API credentials (same API key as the Tone API node).

3. Choose an operation: LLM Ready, Analyze Tokens, Encode, or Decode.

4. Pass JSON data from previous nodes using expressions, e.g. {{ $json }}.

Ready to get started?

Create an account and get your API key in under a minute.

Create accountTone API docs