Controlling Returned Data (Ticket API)

Helpdocs Admin Updated by Helpdocs Admin

Ticket responses can include related data — comments, time entries, activities, and workspaces — but not all of it is needed for every use case. Rather than always returning everything, the Ticket API lets you control what's included using the standard HTTP Prefer header.

Why this matters

  • Comments — ticket comments/notes.
  • Time entries — an agent's logged time records, which also contain their own content.
  • Activities — system events like a ticket being closed, reopened, escalated, or fast-tracked. Most automations don't need these.
  • Workspaces — a list of workspaces, queried based on the current user's access. This is more expensive to compute than comments or time entries, since it depends on the requesting user's permissions.

Most automations only care about core fields like status, priority, queue, and category — they rarely need the full timeline, and almost never need activities.

Upcoming change: As of writing, the Ticket API still returns all comments, time entries, and activities by default (workspaces are excluded by default). Later in 2026, the default will change to exclude all of these for performance reasons. If your integration relies on any of this data, start specifying your preferences explicitly now via the Prefer header, so you won't be affected when the default changes.

The Prefer header

All preferences are set using a single Prefer header, with multiple values separated by commas. Order doesn't matter, but each preference name should only be specified once per request — specifying the same one twice produces an undefined result.

This applies across all API versions.

Prefer: content-type="html", ticket.comment-include="public", ticket.time-entry-include="empty", ticket.activity-include="empty", ticket.workspace-include="include-public"

Available preferences

Content type

Controls whether text fields (like descriptions, comments, and time entry content) are returned as Markdown (default) or server-rendered HTML.

export type PreferredContentType =
  | 'default' // markdown (as originally saved)
  | 'html';

Prefer: content-type="html"

Comment inclusion

export type PreferredCommentIncludeRule =
  | 'default' // current default behavior — returns all comments
  | 'empty'   // exclude comments
  | 'public'; // only include public comments

Prefer: ticket.comment-include="public"

Time entry inclusion

export type PreferredTimeEntryIncludeRule =
  | 'default' // current default behavior — returns all time entries
  | 'empty'   // exclude time entries
  | 'public'; // only include public time entries

Prefer: ticket.time-entry-include="empty"

Activity inclusion

export type TicketActivityIncludeRule =
  | 'default' // current default behavior — returns all activities
  | 'empty';  // exclude activities

Prefer: ticket.activity-include="empty"

Workspace inclusion

export type TicketWorkspaceIncludeRule =
  | 'empty'          // exclude workspaces (current default)
  | 'include-mine'   // only workspaces owned by the current user
  | 'include-public' // only public workspaces
  | 'include-any';   // any workspace the current user has access to

Prefer: ticket.workspace-include="include-public"

Combining preferences

You can combine as many preferences as you need in a single header:

Prefer: content-type="html", ticket.comment-include="empty", ticket.time-entry-include="empty", ticket.activity-include="empty", ticket.workspace-include="include-public"

This example requests HTML-formatted content, no comments, no time entries, no activities, and only public workspaces — a lean response focused on the ticket's core data plus workspace context.

How did we do?

The Prefer Header — Overview

Controlling Returned Data (Form Result API)

Contact