Concepts
A quick tour of how JsonBank is organised. If you skimmed an SDK page and wondered what a "path", a "project" or a "key" actually is — start here.
What is JsonBank?
JsonBank stores and serves JSON documents over a simple API, with SDKs for JavaScript, Go, Python and Rust. Think of it as a hosted home for the JSON your apps need — config, feature flags, content, fixtures — readable by API, public or private.
Projects, folders & documents
- Project — a namespace you own. Everything lives inside a project.
- Folder — optional grouping inside a project (folders can nest).
- Document — a single JSON file. This is the thing you read and write.
Documents have an id and a path
Every document has a stable id (returned as meta.id) and a human-readable path. Anywhere an SDK accepts id_or_path, either one works.
A path is just the document's location:
| You're reading… | Path shape | Example |
|---|---|---|
| Your own document | project/[folder/]name | sdk-test/index.json |
| A public document | username/project/[folder/]name | jsonbank/sdk-test/index.json |
The only difference is the leading username. For your own documents your API key already identifies you, so you drop the prefix. For public documents you name the owner up front (here, jsonbank). The .json extension is optional.
Public vs private
- Public documents can be read by anyone — no API key required.
- Private documents are readable only by you, using your public key (see the table below). Each SDK has an "own content" method for these (
getOwnContent/get_own_content/GetOwnContent).
Which key does what?
JsonBank gives you two keys. They're named by what they grant, not by how secret they are — keep both safe.
| Key | What it's for |
|---|---|
| Public key | Read-only. authenticate() and read your own (private) documents. |
| Private key | Write-only. Create, update and delete documents and folders. |
You only need the public key to read; add the private key when you want to write. Reading public documents needs no key at all.
GitHub passthrough
JsonBank can also fetch public JSON straight from a GitHub repo's default branch, no auth required:
get_github_content("owner/repo/path/to/file.json")Note this is a GitHub path (owner/repo/file), not a JsonBank path — a separate convenience for reading JSON you already keep in a repo.