Result Control

Result Control query parameters determine which public fields and relations the intratool API returns and how it orders, limits, or paginates the result. These controls do not bypass resource authorization, visibility, or Restricted Scope rules.

Each endpoint defines the fields, relations, computed properties, and pagination behavior it supports. Resource-specific query extensions are not part of the shared Result Control contract unless the affected API reference documents them explicitly.

Query Parameters

Key	Type	Default	Description
select	string	Endpoint fields	Comma-separated fields to return.
with_count	string	No counts	Pipe-separated relations whose counts are returned.
include	string	Endpoint relations	Pipe-separated relations to return.
filter	object	{}	Standard Value Filters and Constraints.
filter_relation	object	{}	Grouped Relation Filters on query-backed endpoints.
filter_with_count	object	{}	Filtered Relation Counts and count comparisons on query-backed endpoints.
sort	string	Endpoint order	Comma-separated fields used for ordering.
limit	integer	No additional limit	Maximum number of records.
page	integer	1	Page number for pagination-enabled endpoints.
per_page	integer	25	Page size for pagination-enabled endpoints.
appends	string	Endpoint appends	Comma-separated computed fields to add.

Includes

Use include to return related resources without additional API requests. The relation must be listed as public in the affected resource's Model Definition.

Syntax

• {route} - Endpoint from which records are retrieved.

• ?include - Query parameter containing the relations.

• {relations} - Relation identifiers separated by |; use . for nested relations.

GET /api/{route}?include={relations}

Relation Fields

Append : and comma-separated field keys to select fields on an included relation.

?include={relation}:{field1},{field2}

Include every key needed to resolve the relation. For example, a selected child record may need its primary and foreign keys for the relation to be returned correctly.

Relation Options

Append relation options after the selected fields. Options use square brackets, are separated by commas, and are case-sensitive. A relation without field selection places the first option directly after :.

?include={relation}:{field1},[{option}={value}]

Option	Type	Description
withCounts	string	Add counts for one or more related relations. Separate multiple relation names with +.
order	string	Order related records by one or more fields. Separate fields with + and prefix a field with - for descending order.
limit	integer	Limit the number of related records.
appends	string	Add one or more computed fields to related records. Separate field names with +.
nestLevels	integer	Repeat a self-referential relation for the specified number of additional nesting levels.

Combined example

GET /api/{route}?include=manualEntries:id,title,manual_chapter_id,[withCounts=seenUsers+readUsers],[order=-id],[limit=2],[appends=hash]

Self-referential example

GET /api/{route}?include=children:id,title,parent_id,[nestLevels=2]

Relation options affect only supported, authorized relations. Invalid or unavailable relations are not made accessible by including them.

Selects

Use select to restrict the response to specified public fields.

Syntax

• {route} - Endpoint from which records are retrieved.

• ?select - Query parameter containing the fields.

• {fields} - Field keys separated by ,.

GET /api/{route}?select={fields}

When combining select with include, include the field required to resolve each requested relation.

Limiting

Use limit to control the maximum number of returned records.

Syntax

• {route} - Endpoint from which records are retrieved.

• ?limit - Query parameter containing the maximum result count.

• {value} - Maximum number of records to return.

GET /api/{route}?limit={value}

For paginated endpoints with an exact count, limit also caps the reported total and can therefore reduce the last available page. Count-less endpoints still stop returning records after the limit is reached.

Pagination

Pagination-enabled endpoints accept page and per_page. They default to page 1 with 25 records per page.

Syntax

• {route} - Pagination-enabled endpoint from which records are retrieved.

• ?page - Query parameter containing the page number.

• ?per_page - Query parameter containing the page size.

GET /api/{route}?page=2&per_page=25

Paginated responses contain current_page, last_page, per_page, total, from, to, and data. Endpoints that do not enable pagination ignore these shared pagination controls or document different behavior.

Count-less Pagination

Some entity-selection and preview endpoints avoid an exact count. Their response keeps the standard pagination fields but returns total as null. While another page may exist, last_page is the next page number; otherwise it equals current_page. Clients can therefore test whether last_page is greater than current_page without treating it as an exact total page count.

Sorting

Use sort to define the order of returned records.

Syntax

• {route} - Endpoint from which records are retrieved.

• ?sort - Query parameter containing the sort fields.

• {fields} - Field keys separated by ,; prefix a field with - for descending order.

GET /api/{route}?sort={fields}

For example, ?sort=-updated_at,title sorts by updated_at descending and then by title ascending.

Relation Counts

Use with_count to return the number of related records without returning those resource objects.

Syntax

• {route} - Endpoint from which records are retrieved.

• ?with_count - Query parameter containing the relations.

• {relations} - Relation identifiers separated by |.

GET /api/{route}?with_count={relations}

Each count uses the snake-case relation name followed by _count. For example, with_count=seenUsers|readUsers adds seen_users_count and read_users_count.

Filtered Relation Counts

On query-backed endpoints, filter_with_count computes a count with optional related-field filters. The relation must be public for the endpoint, and its access restrictions still apply. This filter adds the count to the response without requiring a separate with_count parameter.

Filtered count example

GET /api/infoboard/posts?filter_with_count[comments][user_id][is]=3

This request adds comments_count for comments authored by user 3. Other fields inside the relation's filter object use the standard Value Filters.

Place comparisons on the resulting count under count. A scalar count means exact equality; an object accepts the supported count comparisons.

Count comparison example

GET /api/infoboard/posts?filter_with_count[comments][user_id][is]=3&filter_with_count[comments][count][gte]=2

This request returns posts with at least two accessible comments authored by user 3. Use relation as alias as the relation key to name the count explicitly, for example filter_with_count[comments as authored_comments][count][gte]=2; the response field is then authored_comments. Encode spaces when sending the URL. Relation and alias identifiers must start with a letter or underscore and contain only letters, digits, and underscores.

Count comparisons

• is - Count equals the supplied value.

• not - Count differs from the supplied value.

• gt - Count exceeds the supplied value.

• gte - Count is at least the supplied value.

• lt - Count is below the supplied value.

• lte - Count is at most the supplied value.

• in - Count matches one of the supplied comma-separated values or array items.

• nin - Count matches none of the supplied comma-separated values or array items.

• is_null - Tests whether the aggregate is null with 1, or non-null with 0; relation counts normally return a number, including 0.

These filters require a database-backed query. Endpoints that calculate a collection of results in memory do not support this aggregate-filter syntax.

Appends

Use appends to add supported computed fields to API responses.

Syntax

• {route} - Endpoint from which records are retrieved.

• ?appends - Query parameter containing the computed fields.

• {fields} - Computed field keys separated by ,.

GET /api/{route}?appends={fields}

Top-level example

GET /api/manual/entries/1?appends=hash

Use the appends relation option for included relations. Top-level fields are separated by ,, while relation-option fields are separated by +.

GET /api/forms/1?include=formFields:[appends=field_validation_string]

If an appended field depends on an attribute excluded by select, the appended output can be incomplete.

Filters

The shared filter object accepts the field comparisons documented under Value Filters and the relation conditions documented under Constraints.

Grouped Relation Filters

On query-backed endpoints, filter_relation[{relation}] groups comparisons that must match the same related record. Multiple comparisons use AND semantics within that record. The relation must be public for the endpoint, and its access restrictions still apply.

Grouped relation example

GET /api/infoboard/posts?filter_relation[comments][user_id][is]=3&filter_relation[comments][text][value]=approved

This request returns posts with an accessible comment authored by user 3 whose text contains approved. Separate dot-notation filters can match different related records; grouping them requires one comment to satisfy both conditions. Filtering does not include comments in the response; add include=comments when needed.

Resource-specific shortcut filters added on top of those shared operators are intentionally not part of the public API documentation yet.