Skip to content
Last updated

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:

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:

MethodEndpointSchema
GET/venuesPaginated VenueResponse
GET/venues/{venueId}Venue
GET/venues/{compositeId}/availabilityAvailabilityResponse
POST/venues/{compositeId}/bookingBooking
GET/venues/bookingsPaginated ReservationResponse
GET/venues/bookings/{bookingId}Booking
PUT/venues/bookings/{bookingId}Booking
PATCH/venues/bookings/{bookingId}Booking
GET/venues/categoryProductCategoryResponse

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

Example: Fetch venues as TOON

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

Example: Feeding TOON into an LLM prompt

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 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.

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.

Previous page
Next page