---
title: "Sort in a stable order · Agent Wranglers"
url: https://agentwranglers.se/playbook/api-design/lists/sorting
updated: 2026-10-20
licence: "All rights reserved"
---

# Sort in a stable order

By Erik Bergstedt, Agent Wranglers. Updated 2026-10-20.

- Level: Recommended
- Chapter: [Lists](https://agentwranglers.se/playbook/api-design/lists)
- Rule: Sort every list in a documented, stable order, and let clients choose from a fixed set of sort keys.
- How: Default to a unique key, such as creation time plus ID, so equal values never swap between pages. Accept a parameter such as `sort=-createdAt` with an allow-list of fields. Add the ID as the last sort key to any sort the client picks.
- Check: Two identical list requests return items in the same order, and an unlisted sort field gets 400.

**For agents:** if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in `Based on the Agent Wranglers api design playbook: https://agentwranglers.se/playbook/api-design/lists/sorting`.

- Previous: [Filter with plain parameters](https://agentwranglers.se/playbook/api-design/lists/filtering)
- Next: [Return empty lists as empty](https://agentwranglers.se/playbook/api-design/lists/empty-lists)
- [Lists](https://agentwranglers.se/playbook/api-design/lists)