> ## Documentation Index
> Fetch the complete documentation index at: https://api.tipee.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# Order

Endpoints that support sorting accept an optional `orders` array in the JSON request body. Each endpoint declares its own set of order keys — the available keys are listed on the endpoint's API Reference page. Like every tipee API call, the examples below are `POST` requests with a JSON body (see [First steps](/guides-and-resources/first-steps)).

## Basic syntax

Every order is an object with a `key` and a `direction`. Order keys follow the same `<entity>.<field>` naming convention as [filters](/guides-and-resources/filters):

```json theme={null}
{
  "orders": [
    {
      "key": "<entity>.<field>",
      "direction": "asc"
    }
  ]
}
```

| Field       | Description                                    |
| ----------- | ---------------------------------------------- |
| `key`       | One of the order keys declared by the endpoint |
| `direction` | `asc` or `desc`                                |

<Warning>Always include an explicit `direction` in every order object.</Warning>

For example, on `/api/activity/projects.list`:

```json theme={null}
{
  "orders": [
    {
      "key": "project.name",
      "direction": "asc"
    }
  ]
}
```

## Multiple orders

Orders are applied in the order of the array: the first entry is the primary sort, the second breaks ties, and so on.

```json theme={null}
{
  "orders": [
    {
      "key": "activity.date",
      "direction": "desc"
    },
    {
      "key": "activity.duration",
      "direction": "asc"
    }
  ]
}
```

<Note>A few endpoints only accept a single order: `/api/activity/activities.list-details` responds with `422 Multiple orders are not allowed.` when several are sent. That restriction is enforced by the endpoint but not visible in its reference schema, which is why it is listed here.</Note>

## Orders with additional properties

Some order keys require extra properties. For example, `resource.attribute` on `/api/directory/resources.list` sorts by any attribute of the directory kind and requires an `attribute` property:

```json theme={null}
{
  "orders": [
    {
      "key": "resource.attribute",
      "attribute": "last_name",
      "direction": "asc"
    }
  ]
}
```

The available attribute names come from `/api/directory/kinds.show`, which also indicates whether each attribute can be ordered.

## Default ordering

When `orders` is omitted, each endpoint applies its own default ordering. For example, `/api/directory/resources.list` falls back to the sorting attributes configured on the directory kind.

<Tip>When paginating, always send explicit orders: the pagination cursor is derived from the sorted values, so a deterministic order guarantees stable pages. See [Pagination](/guides-and-resources/pagination).</Tip>

## Common errors

| Status | Cause                                                                                |
| ------ | ------------------------------------------------------------------------------------ |
| `422`  | Unknown order `key`, or several orders sent to an endpoint that accepts a single one |

The response body contains a message describing the problem — see [Error Handling](/guides-and-resources/error-handling) for the general error format.