# jstash bins API reference

> Hosted JSON storage with a small REST API. Save a JSON document with one request, get a URL, and read it from anywhere. Writes come from servers, scripts and CI; reads of public bins work from any website.

This is the plain-text reference for coding agents. The same facts, for people: https://jstash.app/docs/. For private data per signed-in user of a web app, see jstash Apps: https://jstash.app/docs/apps.md.

## When to use it

- A script, server, CI job or cron needs to save a small JSON document somewhere and read it back, or publish it at a stable URL.
- A static site or front end needs to *read* JSON (config, content, a feed, a status file) that something server-side writes.
- Prototypes and hobby projects: no signup needed for a first bin.

## When not to use it

- **Writing from browser JavaScript on your website.** The API refuses other websites (CORS), and an API key or edit token in front-end code would be public. For per-user data saved from the browser, use jstash Apps. Otherwise write from a server.
- **Secrets or personal data in a public bin.** Anyone with a public bin's URL can read it.
- **Many records, queries or relations.** A bin is one JSON document read and replaced whole. No queries, search, indexes or partial updates. Use a database.
- **Big documents.** 100 KB per bin on Trial and Free, 1 MB on Pro.
- **Anything that needs undo, version history or an uptime guarantee.** jstash keeps no old versions, doesn't restore bins on request, and has no SLA.
- **Files.** Bodies must be JSON.

## Hosts

- `https://api.jstash.app/v1`: the API (writes, details, private reads).
- `https://j.jstash.app/{id}`: public reads. Use a bin's `url` exactly as returned; don't build it yourself.

## Authorization

One header: `Authorization: Bearer <token>`.

- **Edit token** (`js_edit_…`): returned once when a trial bin is created. Works only on that bin: `GET`, `PUT`, `PATCH` and `DELETE` on `/v1/bins/{id}`, and `GET /v1/bins/{id}/content`. jstash stores only a hash of it, so a lost token can't be recovered. It stops working once the bin is claimed.
- **API key** (`js_live_…`): created in the dashboard at https://app.jstash.app (sign in with GitHub or Google), shown once. Works on every bin in the account. Revoked keys get `401 AUTH_REVOKED`.
- Creating a trial bin and reading a public bin need neither.

**Security rules**

- Call `api.jstash.app` only from server-side code: a backend, serverless function, script or CI. Browser JavaScript on other websites can't call it (CORS), and keys and edit tokens must never ship in front-end code.
- Read the key from an environment variable (for example `JSTASH_API_KEY`). Never commit it.
- If the key is missing, stop with a clear error. A `POST /v1/bins` with no `Authorization` header doesn't fail: it makes a public trial bin that's deleted after 7 days.

## Endpoints

| Method and path | Auth | What it does |
|---|---|---|
| `POST /v1/bins` | None or API key | Saves the body as a new bin. `201`. With no auth it's a public trial bin with an `edit_token`; with an API key it belongs to the account straight away (no token, no expiry). |
| `GET {url}` | None | A public bin's document, raw. Also `HEAD`. |
| `GET /v1/bins/{id}` | Edit token or API key | The bin's details. |
| `GET /v1/bins/{id}/content` | Edit token or API key | The document, fresh from storage, with an `ETag`. The only way to read a private bin. |
| `PUT /v1/bins/{id}` | Edit token or API key | Replaces the whole document. Same URL. |
| `PATCH /v1/bins/{id}` | Edit token or API key | Renames: `{"name": "…"}` (1–100 characters) or `{"name": null}`. Names are private labels; they never change the URL. |
| `DELETE /v1/bins/{id}` | Edit token or API key | Deletes the bin. `204`, safe to repeat. The URL returns 404 within 5 minutes, usually at once. |
| `POST /v1/bins/{id}/claim` | API key | Makes a trial bin permanent: body `{"edit_token": "js_edit_…"}`. Same URL. Must happen before `expires_at`. |
| `GET /v1/bins` | API key | Your bins, most recently updated first. `?limit=` 1–100 (default 50), then pass `next_cursor` as `?cursor=` until it's `null`. |
| `GET /v1/account/usage` | API key | Usage against the plan's limits. |

**Bodies:** any JSON value (object, array, string, number, `true`, `false`, `null`) as UTF-8. Any Content-Type is accepted; `curl -d` is fine. Stored byte for byte, so formatting and key order come back as sent. To send a file with curl, use `--data-binary @file.json` (plain `-d @file` strips newlines).

**Private bins (Pro):** create with the header `X-Bin-Visibility: private`. They have no public `url` (it's `null`); read them with `GET /v1/bins/{id}/content` and the API key. A bin's visibility is set when it's created and can't be changed: create a new bin to change it.

## Responses

Create (`201`, trial bin; an account bin has the same fields without `edit_token` and `keep_it`, and `expires_at` is `null`):

```json
{
  "url": "https://j.jstash.app/LmP6w8kC2fY7Qv4rZx1aNg",
  "edit_token": "js_edit_…",
  "expires_at": "2026-10-09T10:30:00.000Z",
  "keep_it": "To keep it, sign in at https://app.jstash.app and claim it with its edit_token before expires_at.",
  "id": "LmP6w8kC2fY7Qv4rZx1aNg",
  "name": null,
  "visibility": "public",
  "api_url": "https://api.jstash.app/v1/bins/LmP6w8kC2fY7Qv4rZx1aNg/content",
  "bytes": 17,
  "sha256": "93a239…",
  "version": 1,
  "etag": "\"fbc24bcc7a1794758fc1327fcfebdaf6\"",
  "created_at": "2026-10-02T10:30:00.000Z",
  "updated_at": "2026-10-02T10:30:00.000Z"
}
```

- `GET /v1/bins/{id}` and claim return the same details, without `edit_token` and `keep_it`.
- `PUT` returns `200` with `{"id", "version", "bytes", "etag", "updated_at"}`.
- `GET /v1/bins` returns `{"items": [{"id", "name", "visibility", "status", "url", "bytes", "version", "updated_at"}], "next_cursor"}`.
- `GET /v1/account/usage` returns `{"plan", "bins", "storage_bytes", "creates_today", "updates_today", "api_keys"}`, each counter as `{"used", "limit"}`.
- Create, `PUT` and `/content` also send the `ETag` header.

## Reading public bins

- A plain `GET` of the bin's `url` from a browser, server or shell. Returns `Content-Type: application/json`, an `ETag`, and `Access-Control-Allow-Origin: *`, so any website can `fetch()` it.
- Don't send custom headers or credentials to `j.jstash.app`: they trigger a CORS preflight, which isn't supported.
- Don't add query strings to bust the cache; they're ignored.
- Updates and deletes clear the edge cache for servers and scripts at once. A browser reading from a website can get the old copy for up to 5 minutes.
- Public reads aren't metered. One IP sending more than about 60 requests a second is briefly blocked.

```js
// Browser or server: no key needed for a public bin
const data = await fetch('https://j.jstash.app/<your-bin-id>').then((r) => r.json());
```

## Safe updates with ETags

- `PUT` replaces the whole document; there are no partial updates.
- If anything else might write the same bin, send the last `etag` you read as `If-Match`. The `etag` field and the `ETag` header are the same value.
- `412 ETAG_MISMATCH` means it changed: read it again, reapply your change and retry.
- Saving content identical to the current document is a no-op: no new version, and it doesn't count toward daily updates.

```js
// Server-side (Node 18+, Deno, Bun, Workers): replace a bin you own
const res = await fetch(`https://api.jstash.app/v1/bins/${id}`, {
  method: 'PUT',
  headers: { Authorization: `Bearer ${process.env.JSTASH_API_KEY}`, 'If-Match': etag },
  body: JSON.stringify(doc),
});
if (!res.ok) {
  const { error } = await res.json();
  throw Object.assign(new Error(error.message), { code: error.code });
}
const { etag: newEtag, version } = await res.json();
```

## Limits

| | Trial (no account) | Free | Pro |
|---|---|---|---|
| Size per bin | 100 KB | 100 KB | 1 MB |
| Bins / storage | No total cap | 100 bins, 10 MB | 1,000 bins, 1 GB |
| Lifetime | 7 days unless claimed | Until deleted | Until deleted |
| New bins a day | 20 per IP (and 5 a minute) | 100 | 1,000 |
| Updates a day | 1,000 per IP | 1,000 | 10,000 |
| Private bins | No | No | Yes, 50,000 private reads a day |
| API keys | Edit token per bin | 2 | 10 |
| Public reads | Not metered | Not metered | Not metered |

- Per API key, each minute: 10 creates, 60 updates and renames, 30 deletes, 300 reads and lists. Requests with an edit token get the same per-minute limits, counted per IP. Creates are also capped at 60 a minute per IP across all keys.
- Storage is shared with the account's jstash Apps documents.
- Daily limits reset at 00:00 UTC. Per-minute limits are rolling and approximate. "Per IP" counts IPv6 by /64.
- 1 KB = 1,000 bytes; 1 MB = 1,000,000 bytes.
- Free needs no card. Pro is available to everyone for US$5 a month, billed monthly, with no application. Subscribe from the dashboard Plan page (https://app.jstash.app/plan) and cancel any time. See plans at https://jstash.app/pricing/.
- Keep data that changes together in one bin; don't create a bin per request.

## Errors

Every error is JSON: `{"error": {"code": "…", "message": "…"}, "request_id": "req_…"}`. Branch on `code`, never on `message`. Log the message: it names the problem and, for common errors, the fix.

| Status | Code | Meaning and what to do |
|---|---|---|
| 400 | `INVALID_JSON` | The body is empty, not UTF-8 or not JSON; the message says where. |
| 400 | `INVALID_REQUEST` | A bad query parameter or header (`limit`, `cursor`, `X-Bin-Visibility`). |
| 401 | `AUTH_REQUIRED` | No credentials. |
| 401 | `AUTH_INVALID` | The key or token isn't recognised (a claimed bin's edit token stops working). |
| 401 | `AUTH_REVOKED` | The API key was revoked. |
| 403 | `FORBIDDEN` | The credentials can't do this, such as an edit token on another bin or on claim, or a suspended account. |
| 403 | `VISIBILITY_NOT_ALLOWED` | Private bins need Pro, and a bin's visibility can't be changed after it's created. |
| 403 | `BIN_LIMIT_REACHED`, `STORAGE_LIMIT_REACHED`, `API_KEY_LIMIT_REACHED` | The account is at a plan limit. Delete something first. |
| 403 | `BIN_SUSPENDED` | A moderator took the bin offline. Don't retry. |
| 404 | `BIN_NOT_FOUND` | No such bin, or it isn't yours. |
| 404 | `BIN_EXPIRED` | The trial bin passed `expires_at`. It can't be claimed any more. |
| 404 | `NOT_FOUND` | No such endpoint. Check the method and path. |
| 412 | `ETAG_MISMATCH` | See Safe updates. |
| 413 | `PAYLOAD_TOO_LARGE` | The body is over the size limit; the message gives both sizes. |
| 422 | `INVALID_METADATA` | A JSON request field is wrong, such as a name over 100 characters. |
| 429 | `RATE_LIMITED` | Too many requests this minute. Wait `Retry-After` seconds. |
| 429 | `WRITE_LIMIT_REACHED` | A daily limit is used up. Don't retry before 00:00 UTC. |
| 429 | `MONTHLY_QUOTA_EXCEEDED` | A monthly write or read allowance is used up (Free 5,000 / 50,000, Pro 40,000 / 400,000). The error has `reset_at` (the 1st, 00:00 UTC). Nothing is deleted. |
| 500 | `INTERNAL_ERROR` | Retry once; if it persists, send the `request_id` to support@jstash.app. |
| 503 | `R2_UNAVAILABLE`, `DATABASE_UNAVAILABLE` | Storage is briefly unavailable. Retry with a short backoff. |

**Retrying:** `PUT` and `DELETE` are safe to retry. `POST /v1/bins` isn't: a JSON error response means no bin was made, but a create with no response or a non-JSON error might have made one, and retrying can make a second bin. A `PUT` with `If-Match` that failed with a 5xx or got no response may already have saved: read the bin, and if it has your change, stop.

## Quick examples

```sh
# Create a public trial bin (no account). Keep the edit_token: it's shown once.
curl -d '{"hello":"world"}' https://api.jstash.app/v1/bins

# Create a bin in your account
curl -H "Authorization: Bearer $JSTASH_API_KEY" -d '{"hello":"world"}' https://api.jstash.app/v1/bins

# Replace it
curl -X PUT -H "Authorization: Bearer $JSTASH_API_KEY" -d '{"hello":"again"}' https://api.jstash.app/v1/bins/<your-bin-id>

# Claim a trial bin into your account
curl -X POST -H "Authorization: Bearer $JSTASH_API_KEY" -d '{"edit_token":"js_edit_…"}' https://api.jstash.app/v1/bins/<your-bin-id>/claim
```

```js
// Server-side: create a bin in your account
const res = await fetch('https://api.jstash.app/v1/bins', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.JSTASH_API_KEY}` },
  body: JSON.stringify({ hello: 'world' }),
});
const bin = await res.json(); // { id, url, etag, version, ... }
```

## Good to know

- No old versions and no restores on request: a replaced or deleted document can't be recovered. Keep your own copy of anything that matters.
- No SLA or uptime guarantee.
- Anyone with a public bin's URL can read it. Bin IDs are random, but don't store passwords, secrets or personal data in public bins. Don't store sensitive personal data such as health information anywhere in jstash.
- Trial bins are deleted soon after `expires_at`, usually within 15 minutes.

## More

- Docs: https://jstash.app/docs/
- jstash Apps (per-user data from the browser): https://jstash.app/docs/apps.md
- Pricing: https://jstash.app/pricing/
- Terms: https://jstash.app/terms/ · Privacy: https://jstash.app/privacy/
- Support: support@jstash.app
