The Prefer Header — Overview

Helpdocs Admin Updated by Helpdocs Admin

Tokity's API uses the standard HTTP Prefer header to let you control the shape and format of API responses — without needing separate endpoints or query parameters for every variation. This overview covers how the header works in general. For the specific options available on each API, see the linked articles below.

How it works

The Prefer header is sent as part of your request, and its value is made up of one or more directives — each telling the API how you'd like the response formatted or filtered. Tokity currently supports Prefer on the following APIs:

Each API supports its own set of directives relevant to that resource — for example, whether to include related tickets in a workspace response, or which form fields to return. Those specifics are covered in each API's dedicated article.

content-type: shared across all APIs

One directive, content-type, behaves consistently everywhere it's supported:

Directive

Values

Default

content-type

markdown | html

markdown

It always controls whether text content is returned as raw Markdown or pre-rendered HTML. What that directive actually formats depends on which API you're calling:

  • On the Ticket API, it formats ticket notes/comments.
  • On the Workspace API, it formats workspace notes.
  • On the Form Result API, it formats each field's description.

See the relevant article above for details specific to that resource.

Why content-type exists

Tokity's Markdown isn't rendered using default, out-of-the-box Markdown rules — our servers apply a centralized set of conversion rules so that content looks and behaves consistently everywhere it's displayed, including in our own UI. These rules include:

  • Natural paragraph breaks — a normal line return is treated as a new paragraph. You don't need the usual Markdown convention of adding a trailing double-space or a blank line to force a paragraph break.
  • Automatic video embeds — links to popular video providers (e.g., YouTube, Vimeo, and others) are automatically converted into embedded video players, rather than staying as plain links. Standard image links still work as expected for presenting images.
  • No raw HTML — any raw HTML included in Markdown source is sanitized. This is a security measure, so raw HTML is never passed through as-is.
  • Safer links — links are automatically given rel="noreferrer noopener" (or equivalent) attributes.

If you want your integration's rendered output to match Tokity's own UI exactly, requesting content-type: html via Prefer gives you that same server-side conversion, rather than needing to implement these rules yourself or guess at formatting edge cases.

Why use Prefer at all?

The reasoning behind content-type isn't unique to it — it reflects Tokity's broader DTO (Data Transfer Object) design philosophy: API responses are shaped to return everything a consumer needs in a single call, rather than requiring multiple round-trips to assemble a complete picture (e.g., fetching a resource, then separately calling a conversion API, then separately fetching related data).

Prefer is the mechanism that lets you tune how much of that "everything" you actually want back, without needing separate endpoints for every variation:

  • content-type lets you get pre-rendered HTML in the same call, instead of a follow-up call to a separate Markdown-conversion API.
  • workspace.tickets-include lets you get a workspace's tickets in the same call, instead of a follow-up call to list tickets separately.
  • form-result lets you get an already-filtered view of a form submission, instead of fetching the raw result and re-implementing the display/answer logic yourself.

In each case, the underlying trade-off is the same: a smaller, sparser response is faster and requires less client-side logic to consume as-is, while a fuller response saves you extra round-trips when you need the additional data anyway. Prefer directives let you pick the point on that trade-off that fits your integration, on a per-call basis, rather than Tokity forcing one-size-fits-all behavior.

Combining directives

If an API supports more than one directive (for example, the Workspace and Form Result APIs each support content-type alongside a second, API-specific directive), you can include multiple directives in the same Prefer header. Refer to each API's article for the exact directive names and accepted values.

How did we do?

Uploading Attachments (Ticket API)

Controlling Returned Data (Ticket API)

Contact