Controlling Returned Data (Workspace API)

Helpdocs Admin Updated by Helpdocs Admin

What is a workspace?

A workspace is a way to organize tickets — think of it as a collaborative workspace rather than a permissions boundary. Agents can be added to a workspace, and within it, tickets are organized into groups (similar to how GitHub Projects organizes items into columns or groups). A workspace doesn't control who can access a ticket — it's a structure for organizing and collaborating on tickets that already exist.

Controlling the response with the Prefer header

The Workspace API supports two Prefer header options, letting you control both the format and the amount of data returned:

Directive

Values

Default

Purpose

content-type

markdown | html

markdown

Controls the format of a workspace's notes.

workspace.tickets-include

empty | include

empty

Controls whether tickets are returned within each workspace group.

content-type

Determines whether a workspace's notes are returned as Markdown or pre-rendered HTML.

workspace.tickets-include

Determines whether the response includes the tickets that live inside each workspace group.

  • empty (default) — only the workspace's structure is returned (workspaces and their groups), without any ticket data. Use this when you only need to know how a workspace is organized.
  • include — each group returns the tickets that belong to it, including where each ticket sits within the workspace's structure (which group, and its position).

Why this matters

A single workspace can hold up to 500 tickets. Even though ticket timelines (comments and time entries) are never included in workspace responses, returning 500 tickets' worth of data is still a substantial payload — comparable to listing tickets and paging through all 500 at once.

Because of this, choose the option that matches what you actually need:

  • Use empty if you only need the workspace's structure — its groups and general layout — without caring which tickets are in it.
  • Use include if you need to know which tickets exist and where they're located within the workspace (which group, and their position in it).

How did we do?

Controlling Returned Data (Form Result API)

Contact