Skip to content

docs(api): document the repeated-filter refusal on GET /data/:object#8142

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hotlong merged 1 commit into from
Aug 12, 2026
Merged

docs(api): document the repeated-filter refusal on GET /data/:object #8142

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 10 additions & 1 deletion content/docs/api/data-api.mdx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -19,7 +19,7 @@ Query records with filtering, sorting, selection, and pagination.
|:----------|:---------|:------------|
| `object` | path | Object name |
| `select` | query | Comma-separated field names. Every name must exist — an unknown one is `400 INVALID_FIELD`, never dropped. |
| `filter` | query | Filter expression (JSON). `filters` also accepted for backward compatibility. Malformed JSON is rejected with `400 INVALID_FILTER` — never ignored. |
| `filter` | query | Filter expression (JSON). `filters` also accepted for backward compatibility. Malformed JSON is rejected with `400 INVALID_FILTER` — never ignored; so is sending the parameter more than once (`?filter=…&filter=…`), which is refused as a repetition rather than diagnosed as malformed. |
| `sort` | query | Sort expression (e.g. `name asc` or `-created_at`). Must name a real field on the object itself — an unknown name or a dotted path (`account.company_name`) is `400 INVALID_SORT`. |
| `top` | query | Max records to return. No default — omitting it returns all matching records. |
| `skip` | query | Offset |
Expand DownExpand Up@@ -76,9 +76,18 @@ successful query:
| `?filter=5`, `?filter="done"`, `?filter=null` | `400` — parses, but is not a filter |
| `?filter=` (blank) | treated as absent — no filter, no error |
| `where` and `filter` sent with **different** values | `400` — aliases for one slot; send exactly one |
| `?filter={"a":1}&filter={"b":2}` — one spelling sent **twice** | `400` — `Repeated "filter" query parameter — send exactly one` |

The same rule applies to `orderby` on `GET /data/:object/export`.

Sending one spelling **twice** — on `GET /data/:object`, in any of the four
spellings — is refused as its own named cause rather than reported as a
malformed filter: a repeat is neither merged nor resolved by precedence,
because either would apply a filter you did not express. Repetition is counted,
not compared, so two identical occurrences are still two occurrences, while a
single occurrence that a server adapter delivers as a one-element array is
still one.

#### Nor is a sort, a projection, or an expansion

`filter` is not the only parameter that names a field. `sort`, `select` and
Expand Down
Loading