# TOON Format

**TOON** (Terse Object-Oriented Notation) is a compact data serialization format supported by the Bookings API. It is designed to reduce token count when feeding API responses into Large Language Models — typically achieving a **30–60% reduction** compared to JSON by stripping syntactic noise (braces, quotes, colons, commas) while preserving the full data structure.

TOON responses are opt-in and fully backwards compatible. Standard JSON remains the default.

## When to use TOON

TOON is most useful when:

- Passing API responses directly into an LLM prompt or context window
- Reducing inference costs by keeping token counts low
- Building AI-powered booking assistants or search features on top of the Bookings API


For all other integrations, JSON is recommended.

## How to request TOON

Set the `Accept` header to `text/toon` on any supported GET request:


```http
GET /venues
Accept: text/toon
Authorization: Bearer <token>
X-Partner-Reference: your-partner-ref
```

Omitting the header, or using `Accept: application/json`, returns standard JSON — no other changes required.

## Supported endpoints

All Bookings API endpoints that return a response body support TOON encoding:

| Method | Endpoint | Schema |
|  --- | --- | --- |
| `GET` | `/venues` | Paginated `VenueResponse` |
| `GET` | `/venues/{venueId}` | `Venue` |
| `GET` | `/venues/{compositeId}/availability` | `AvailabilityResponse` |
| `POST` | `/venues/{compositeId}/booking` | `Booking` |
| `GET` | `/venues/bookings` | Paginated `ReservationResponse` |
| `GET` | `/venues/bookings/{bookingId}` | `Booking` |
| `PUT` | `/venues/bookings/{bookingId}` | `Booking` |
| `PATCH` | `/venues/bookings/{bookingId}` | `Booking` |
| `GET` | `/venues/category` | `ProductCategoryResponse` |


> Request bodies (POST/PUT/PATCH) remain `application/json` only.


## Example: Fetch venues as TOON

cURL

```bash
curl https://api.bookabletech.com/venues \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: text/toon"
```

JavaScript

```javascript
const response = await fetch(`${BASE_URL}/venues`, {
  headers: {
    Authorization: `Bearer ${accessToken}`,
    Accept: 'text/toon',
  },
});

const toon = await response.text();
```

Python

```python
response = requests.get(
    f'{BASE_URL}/venues',
    headers={
        'Authorization': f'Bearer {access_token}',
        'Accept': 'text/toon',
    },
)
response.raise_for_status()
toon = response.text
```

Java

```java
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create(BASE_URL + "/venues"))
    .header("Authorization", "Bearer " + accessToken)
    .header("Accept", "text/toon")
    .GET()
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
String toon = response.body();
```

C#

```csharp
var request = new HttpRequestMessage(HttpMethod.Get, $"{BASE_URL}/venues");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("text/toon"));

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
var toon = await response.Content.ReadAsStringAsync();
```

## Example: Feeding TOON into an LLM prompt


```csharp
var request = new HttpRequestMessage(HttpMethod.Get, $"{BASE_URL}/venues");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("text/toon"));

var response = await client.SendAsync(request);
var toon = await response.Content.ReadAsStringAsync();

var prompt = $"""
    You are a booking assistant. Here is the list of available venues:

    {toon}

    Answer the user's question: {userQuestion}
    """;
```

By requesting `text/toon` instead of JSON, the venue list consumes significantly fewer tokens in the prompt, reducing both latency and cost.

## MIME type note

`text/toon` is not an IANA-registered media type — it is a convention used by this API. Clients must explicitly request it via the `Accept` header.

## Combining with sparse fieldsets

TOON and [sparse fieldsets](/resources/sparse-fieldsets) are designed to be used together. Sparse fieldsets eliminate fields you don't need; TOON strips the syntactic overhead from what remains. Combined, they make the Bookings API highly efficient for agentic workflows where every token counts.


```http
GET /venues?fields=id,name,location(city),products(compositeId,productName)
Accept: text/toon
Authorization: Bearer <token>
```

A typical `GET /venues` response in JSON might consume **800–1,200 tokens** per page. With sparse fieldsets and TOON together, the same data can drop to **200–400 tokens** — a reduction of 60–75%, directly lowering your spend on OpenAI, Claude, and other inference APIs.

Agentic API design
The Bookings API is built for AI-native integrations. Use `fields` to shape the data, `Accept: text/toon` to compress it, and inject the result directly into your prompt context — with minimal token overhead and no pre-processing required.

## Related

- [Sparse Fieldsets](/resources/sparse-fieldsets)
- [Bookings API Reference](/apis/production/bookingapi)
- [MCP Connection Guide](/mcp/connection-guide)