JSB Query
Every endpoint that returns a document can also shape that document for you. Add ?query= to the URL and JsonBank transforms the JSON before it reaches you — grab a single field, slice an array, find a record, count things — without pulling the whole document and filtering it yourself.
No SDK, no setup. Just a URL. (New to JsonBank? Start with Concepts.)
How a query looks
A query is a filter followed by its arguments, separated by dashes:
?query=filter-arg1-arg2That reads as filter(arg1, arg2). A few real ones:
?query=has-author— does the document have anauthorkey??query=pick-name— keep only thenamefield.?query=slice-0-2— the first two items of an array.
Try it
These run against a real public document, jsonbank/sdk-test/index.json, which looks like this:
{ "name": "JsonBank SDK Test File", "author": "jsonbank" }Hit Run — these call the live API right here in the page:
curl 'https://api.jsonbank.io/f/jsonbank/sdk-test/index.json?query=keys'curl 'https://api.jsonbank.io/f/jsonbank/sdk-test/index.json?query=pick-name'Go on — swap pick for omit and watch it flip.
A bigger document
Most of the fun is on arrays. The rest of this guide uses two real public docs, so every example is live — just hit Run.
jsonbank/tests/countries.json — an object with a countries array (51 of them):
{
"countries": [
{ "name": "Afghanistan", "code": "AF", "capital": "Kabul", "region": "Asia", "population": 38928346, "currency": "AFN" },
{ "name": "Albania", "code": "AL", "capital": "Tirana", "region": "Europe", "population": 2877797, "currency": "ALL" }
]
}jsonbank/tests/numbers.json — a plain list: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10].
Chaining filters
Separate filters with a comma (,) and they run left → right, each result feeding the next — a little pipeline. The countries live under a countries key, so we usually get-countries first:
curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=get-countries,map-name,slice-0-3'That's get-countries (the array) → map-name (just the names) → slice-0-3 (the first three).
Pick a single country and trim it down:
curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=get-countries[0],pick-name-capital'Reaching into nested data
Arguments that point at a location use dot and bracket paths, just like JavaScript. countries[4] is the fifth country:
curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=get-countries[4].name'curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=has-countries[0].capital'Scalar results and $value
When a query ends on a plain value — a string, number or boolean rather than an object or array — JsonBank wraps it in a $value envelope so the response stays valid JSON:
curl 'https://api.jsonbank.io/f/jsonbank/tests/numbers.json?query=sum'Objects and arrays come back as-is, no wrapper.
Trickier arguments: var(), raw(), json()
Dashes separate arguments and commas separate filters — so what if an argument contains a dash or comma, or is a whole object? Move it into its own URL parameter and point at it.
var(name) — use the value of &name=…. If it has commas, it becomes a list:
curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=get-countries,mapPick-var(fields)&fields=name,capital'raw(name) — same, but the value is taken literally (never split on commas). Handy for a single path with punctuation in it:
curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=at-raw(path)&path=countries[4].name'json(name) — the value is parsed as JSON, so you can pass objects and arrays. Perfect for the matching filters:
curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=get-countries,filter-json(match),map-name&match={"currency":"EUR"}'json() also accepts base64: &match=b64(eyJjdXJyZW5jeSI6IkVVUiJ9). Where you can use it
Any endpoint that returns a document accepts ?query=:
| Endpoint | Document |
|---|---|
GET /f/{username}/{project}/{file} | a public file, by path |
GET /f/{id} | a public file, by id |
GET /gh/{owner}/{repo}/{file} | a public file from GitHub |
GET /v1/file/{path-or-id} | your own file (send your public key header) |
/meta/…) don't return document content, so they can't be queried. Limits & errors
Documents larger than 2 MB can't be queried. Errors come back as { "error": { "code": …, "message": … } } — try an unknown filter:
curl 'https://api.jsonbank.io/f/jsonbank/sdk-test/index.json?query=notafilter'| Code | Means |
|---|---|
invalidQuery | unknown filter name |
invalidJson | the stored document isn't valid JSON |
badQuery | a filter ran but the arguments didn't fit |
resultUndefined | the query resolved to nothing |
query.tooLarge | document is over 2 MB |
Filter reference
Here's every filter, each with a button to run it. They each do one small transform — chain them with commas (see Chaining) to go further. Examples run against the countries and numbers docs above; the array/collection ones start with get-countries so what you get back is that filter's own output.
Array
chunk
Break an array into smaller arrays of n.
curl 'https://api.jsonbank.io/f/jsonbank/tests/numbers.json?query=chunk-3'first
The first item.
curl 'https://api.jsonbank.io/f/jsonbank/tests/numbers.json?query=first'last
The last item.
curl 'https://api.jsonbank.io/f/jsonbank/tests/numbers.json?query=last'nth
The item at a position (0-based).
curl 'https://api.jsonbank.io/f/jsonbank/tests/numbers.json?query=nth-3'reverse
Reverse the order.
curl 'https://api.jsonbank.io/f/jsonbank/tests/numbers.json?query=reverse'slice
A sub-range by position — from start up to (not including) end.
curl 'https://api.jsonbank.io/f/jsonbank/tests/numbers.json?query=slice-2-5'take
The first n items.
curl 'https://api.jsonbank.io/f/jsonbank/tests/numbers.json?query=take-3'takeRight
The last n items.
curl 'https://api.jsonbank.io/f/jsonbank/tests/numbers.json?query=takeRight-3'mapPick
From an array of objects, keep only these keys on each one.
curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=get-countries,take-2,mapPick-name-code'mapOmit
From an array of objects, drop these keys from each one.
curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=get-countries,take-2,mapOmit-name-code'Object
get
Pull out a value by path — dots for keys, [n] for array positions.
curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=get-countries[0].capital'at
Pull values at one or more paths — always returns an array. One path with raw(), or several with a json() array:
curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=at-raw(path)&path=countries[4].name'curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=at-json(paths)&paths=["countries[0].name","countries[4].name"]'has
Check whether a path exists (true/false).
curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=has-countries[0].name'keys
The keys of an object.
curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=keys'values
The values of an object.
curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=get-countries[0],values'omit
The object without these keys.
curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=get-countries[0],omit-code-population'pick
The object with only these keys.
curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=get-countries[0],pick-name-capital'Type
castArray
Wrap a value in an array (arrays are left as-is).
curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=get-countries[0],castArray'isArray
Is the value an array? get-countries is; the whole document isn't:
curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=get-countries,isArray'curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=isArray'Collection
Several of these take a matcher: a field name (matches where it's truthy), a json() object {field: value}, or a json() [field, value] pair.
find
The first item that matches — here by an object, then by a [field, value] pair:
curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=get-countries,find-json(match)&match={"region":"Europe"}'curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=get-countries,find-json(match)&match=["currency","EUR"]'findLast
The last item that matches (like find, from the end).
curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=get-countries,findLast-json(match)&match={"region":"Europe"}'filter
Every item that matches.
curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=get-countries,filter-json(match)&match={"region":"Oceania"}'reject
Every item that does not match (the opposite of filter). Each country is slimmed first so the result is easy to scan:
curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=get-countries,mapPick-name-region,reject-json(match)&match={"region":"Asia"}'size
How many — an array's length, or an object's number of keys.
curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=get-countries,size'every
Are all items a match? (true/false). A field name checks it's truthy on every item; a json() object checks fields:
curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=get-countries,every-name'curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=get-countries,every-json(c)&c={"region":"Europe"}'orderBy
Sort by a field, with a direction (asc or desc). Slimmed to name + population here:
curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=get-countries,mapPick-name-population,orderBy-population-desc'sortBy
Sort by a field, ascending.
curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=get-countries,mapPick-name-population,sortBy-population'shuffle
Randomly reorder a list (run it a couple of times).
curl 'https://api.jsonbank.io/f/jsonbank/tests/numbers.json?query=shuffle'map
Pull one field out of every item.
curl 'https://api.jsonbank.io/f/jsonbank/tests/countries.json?query=get-countries,take-3,map-name'Number
max
The largest value in a list of numbers.
curl 'https://api.jsonbank.io/f/jsonbank/tests/numbers.json?query=max'min
The smallest value.
curl 'https://api.jsonbank.io/f/jsonbank/tests/numbers.json?query=min'sum
Add up all the numbers.
curl 'https://api.jsonbank.io/f/jsonbank/tests/numbers.json?query=sum'