> For the complete documentation index, see [llms.txt](https://hub.equipme.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hub.equipme.io/development/api-reference-app/reading-resources.md).

# Reading resources

#### `fields` — the shape of the response

Without `fields`, a resource is represented by its **scalar values**: its own data plus, for every reference it holds, the value that identifies it — `assigneeId` for a contact, `statusName` for a status. Related objects are never embedded by default.

`fields` selects explicitly, and it drives the database read as well as the response, so asking for less is genuinely cheaper:

| Selection                                     | Response                                |
| --------------------------------------------- | --------------------------------------- |
| `fields=subject,createdAt`                    | `id`, `subject`, `createdAt`            |
| `fields=assignee`                             | `id` plus the assignee's scalar values  |
| `fields=assignee.firstName,assignee.lastName` | `id` plus exactly those two             |
| `fields=labels(limit=5;sort=name)`            | `id` plus the first five labels by name |

Anything listed as a property of the resource's schema can be selected. Rules worth knowing:

* `id` is returned first at every level, whether or not it was asked for.
* A relation selected without sub-fields yields its own scalar values — the same rule that shapes the resource itself.
* Fields are returned in the order they were requested.
* A collection accepts `(limit=…;offset=…;sort=…)`; without a limit it returns at most 50 entries, and never more than 100.
* An unknown field name is answered with `400`.

#### `filter` — a JSON expression

A predicate is `{"field": …, "op": …, "value": …}`; `and`, `or` and `not` nest them. A field may be a dotted path into a filterable relation. Which fields a resource accepts is documented per endpoint; an unknown one is answered with `400`.

```json
{"and":[{"field":"status.name","op":"eq","value":"in_progress"},
        {"field":"createdAt","op":"gte","value":"2026-03-01T00:00:00Z"}]}
```

Operators: `eq`, `neq`, `contains`, `startsWith`, `endsWith`, `doesNotContain`, `in`, `notIn`, `gt`, `gte`, `lt`, `lte`, `isNull`, `isNotNull`.

#### `search` — free text

The term is used as a whole — leading and trailing spaces are trimmed, nothing else is split off — and matched case-insensitively as a substring. Which fields it reaches is decided per resource and documented at the endpoint; it commonly includes related people, so searching for a name finds the tickets of that person. A resource that does not offer a search ignores the parameter.

#### `sort` — ordered terms

Comma-separated `field:direction`, direction defaults to `asc`: `sort=priority.level:desc,createdAt`. A field may be `relation.field` for a to-one relation. Results always receive `id` as a final tie-breaker, so paging stays stable.

#### `offset` and `limit`

`limit` has to be between 1 and 100 and defaults to 100. `count` in the response is the total number of matching rows, not the size of the page — use it to drive paging.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://hub.equipme.io/development/api-reference-app/reading-resources.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.