---
title: "Filter with plain parameters · Agent Wranglers"
url: https://agentwranglers.se/playbook/api-design/lists/filtering
updated: 2026-10-20
licence: "All rights reserved"
---

# Filter with plain parameters

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

- Level: Recommended
- Chapter: [Lists](https://agentwranglers.se/playbook/api-design/lists)
- Rule: Let clients filter lists by named query parameters, and document each one with its type.
- How: Use one parameter per field, such as `?status=shipped&createdAfter=2026-11-01T00:00:00Z`. Reject unknown parameters with 400, so a typo never returns everything.
- Check: A request with `?stauts=shipped` returns 400 naming the unknown parameter.

**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/filtering`.

- Previous: [Cap the page size](https://agentwranglers.se/playbook/api-design/lists/page-size-limit)
- Next: [Sort in a stable order](https://agentwranglers.se/playbook/api-design/lists/sorting)
- [Lists](https://agentwranglers.se/playbook/api-design/lists)