Documentation

Everything you need to know about the OneJSONFile API.

Quick Start

Get running in under 60 seconds. No account needed for anonymous files.

1. Create an anonymous file

curl -X POST https://onejsonfile.com/api/v1/anonymous \
  -H "Content-Type: application/json" \
  -d '{}'

2. Write data to it

curl -X PUT https://onejsonfile.com/api/v1/files/YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"hello":"world"}'

3. Read it back any time

curl https://onejsonfile.com/api/v1/files/YOUR_TOKEN

Anonymous files expire after 24 hours. Sign in to create permanent files.

Authentication

OneJSONFile uses token-based access. Each JSON file has a unique token that acts as both an identifier and an access key.

Authenticated tokens — 32-char alphanumeric strings. Linked to your account. Anyone with the token can read and write — token possession is the credential. If you are signed in as a different account, writes are rejected. No expiry.

Anonymous tokens — prefixed with anon_. Anyone with the token can read and write. Expire after 24 hours.

Tokens are passed in the URL path — no Authorization header needed. Works equally well from curl, scripts, IoT devices, and the browser.

Anonymous Files

Create throwaway JSON files without signing in. Perfect for prototyping and testing.

Expiry	24 hours from creation
Max size	100 KB
Auth required	No
Rate limit	10 requests / hour per IP

API Reference

POST/api/v1/anonymous

Create an anonymous JSON file. No authentication required. Expires in 24 hours.

Request body

{ "content"?: object }

Response

{ "token": string, "expiresAt": string, "message": string }

Example

curl -X POST https://onejsonfile.com/api/v1/anonymous \
  -H "Content-Type: application/json" \
  -d '{"content":{"books":[]}}'

Example response

{
  "token": "anon_abc123",
  "expiresAt": "2026-04-03T00:00:00Z",
  "message": "Anonymous file created. Store your token - it cannot be recovered."
}

GET/api/v1/files/:token

Read the JSON content of a file. Returns the raw JSON object.

Response

The stored JSON object

Example

curl https://onejsonfile.com/api/v1/files/YOUR_TOKEN

Example response

{"books":[{"title":"The Pragmatic Programmer","author":"David Thomas","isbn":"978-0135957059","rating":4.8},{"title":"Clean Code","author":"Robert Martin","isbn":"978-0132350884","rating":4.7},{"title":"Designing Data-Intensive Applications","author":"Martin Kleppmann","isbn":"978-1449373320","rating":4.9}]}

PUT/api/v1/files/:token

Replace the entire content of a file. Anonymous files can be written by anyone with the token.

Request body

Any JSON object

Response

{ "success": true, "fileSize": number }

Example

curl -X PUT https://onejsonfile.com/api/v1/files/YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"books":[{"title":"The Pragmatic Programmer","author":"David Thomas","isbn":"978-0135957059","rating":4.8},{"title":"Clean Code","author":"Robert Martin","isbn":"978-0132350884","rating":4.7},{"title":"Designing Data-Intensive Applications","author":"Martin Kleppmann","isbn":"978-1449373320","rating":4.9}]}'

Example response

{"success":true,"fileSize":312}

PATCH/api/v1/files/:token

Deep merge a partial object into the existing file. Arrays are replaced, not merged.

Request body

Any JSON object (partial update)

Response

{ "success": true, "fileSize": number }

Example

curl -X PATCH https://onejsonfile.com/api/v1/files/YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"lastUpdated":"2026-04-02","totalBooks":4,"newArrival":{"title":"A Philosophy of Software Design","author":"John Ousterhout","rating":4.6}}'

Example response

{"success":true,"fileSize":421}

DELETE/api/v1/files/:token

Permanently delete a file and its data. This cannot be undone.

Response

{ "deleted": true }

Example

curl -X DELETE https://onejsonfile.com/api/v1/files/YOUR_TOKEN

Example response

{"deleted":true}

GET/api/v1/health

Health check. Returns API status and version.

Response

{ "status": "ok", "version": string, "timestamp": string }

Example

curl https://onejsonfile.com/api/v1/health

Example response

{"status":"ok","version":"1.0.0","timestamp":"2024-03-30T20:00:00Z"}

Error Codes

Code	HTTP	Description
NOT_FOUND	404	File or resource not found
GONE	410	File has expired
UNAUTHORIZED	401	Authentication required
FORBIDDEN	403	You don't have access to this resource
TOO_LARGE	413	Content exceeds size limit
INVALID_JSON	400	Request body is not valid JSON
INVALID_TOKEN	400	Token format is invalid
RATE_LIMITED	429	Too many requests, slow down
FILE_LIMIT_REACHED	403	Plan file limit reached
PRECONDITION_FAILED	412	If-Match header didn't match current ETag
INTERNAL_ERROR	500	Something went wrong on our end

Rate Limits

Tier	Files	Max size	Req / hour	In-browser editor
Anonymous	1	100 KB	10	No
Scout	2	250 KB	25	No
Indie	25	10 MB	1,000	Yes
Pro	100	25 MB	5,000	Yes

Rate limits use a sliding window per hour. Limits are applied per-file per-IP for anonymous files, and per-user for authenticated files.

Code Examples

curl

shellbash

# Create anonymous file
TOKEN=$(curl -s -X POST https://onejsonfile.com/api/v1/anonymous \
  -H "Content-Type: application/json" \
  -d '{}' | grep -o '"token":"[^"]*"' | cut -d'"' -f4)

# Store a book catalog
curl -X PUT "https://onejsonfile.com/api/v1/files/$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"books":[{"title":"The Pragmatic Programmer","author":"David Thomas","rating":4.8}]}'

# Read it back
curl "https://onejsonfile.com/api/v1/files/$TOKEN"

# Add more data via merge
curl -X PATCH "https://onejsonfile.com/api/v1/files/$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"lastUpdated":"2026-04-02","totalBooks":2}'

# Delete it
curl -X DELETE "https://onejsonfile.com/api/v1/files/$TOKEN"

JavaScript / TypeScript

onejsonfile.tstypescript

const BASE = "https://onejsonfile.com";

// Create anonymous file
const { token } = await fetch(`${BASE}/api/v1/anonymous`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({}),
}).then(r => r.json());

// Store a book catalog
await fetch(`${BASE}/api/v1/files/${token}`, {
  method: "PUT",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    books: [{ title: "The Pragmatic Programmer", author: "David Thomas", rating: 4.8 }],
  }),
});

// Read it back
const data = await fetch(`${BASE}/api/v1/files/${token}`).then(r => r.json());
console.log(data); // { books: [...] }

// Merge update
await fetch(`${BASE}/api/v1/files/${token}`, {
  method: "PATCH",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ lastUpdated: "2026-04-02", totalBooks: 2 }),
});

Python

onejsonfile.pypython

import requests

BASE = "https://onejsonfile.com"

# Create anonymous file
resp = requests.post(f"{BASE}/api/v1/anonymous", json={})
token = resp.json()["token"]

# Store a book catalog
requests.put(
    f"{BASE}/api/v1/files/{token}",
    json={"books": [{"title": "The Pragmatic Programmer", "author": "David Thomas", "rating": 4.8}]},
)

# Read it back
data = requests.get(f"{BASE}/api/v1/files/{token}").json()
print(data)  # {'books': [...]}

# Merge update
requests.patch(
    f"{BASE}/api/v1/files/{token}",
    json={"lastUpdated": "2026-04-02", "totalBooks": 2},
)

# Delete
requests.delete(f"{BASE}/api/v1/files/{token}")

Optimistic Concurrency

ETags let you detect when a file has changed since you last read it, preventing lost updates when multiple clients write to the same file. Using ETags is opt-in — clients that omit If-Match see no behavior change (last-write-wins). Available on all tiers.

How ETags work

Every GET response includes an ETag header — a SHA-256 hash of the file content wrapped in quotes, e.g. "a1b2c3d4...". Successful PUT and PATCH responses include etag in the JSON body.

Send If-Match: "hash" on PUT/PATCH to enforce optimistic locking. If the file has changed since your read, the server returns 412 Precondition Failed so you can re-read and retry.

Send If-None-Match: "hash" on GET to save bandwidth. If the content hasn't changed, the server returns 304 Not Modified with no body.

Safe read-modify-write cycle

# Step 1: Read the file and capture the ETag
curl -i https://onejsonfile.com/api/v1/files/YOUR_TOKEN
# Note the ETag header value, e.g.: ETag: "a1b2c3d4..."

# Step 2: Write with If-Match to prevent lost updates
curl -X PUT https://onejsonfile.com/api/v1/files/YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -H 'If-Match: "a1b2c3d4..."' \
  -d '{"key":"value"}'
# Returns 412 if another client modified the file since your read
# On 412: re-read the file, merge your changes, and retry

Conditional GET to save bandwidth

# First read — captures the ETag
curl -i https://onejsonfile.com/api/v1/files/YOUR_TOKEN
# ETag: "a1b2c3d4..."

# Subsequent poll — 304 if unchanged, full response if modified
curl -i https://onejsonfile.com/api/v1/files/YOUR_TOKEN \
  -H 'If-None-Match: "a1b2c3d4..."'

IoT & Multi-Device Patterns

When multiple devices or clients write to the same file simultaneously, use field namespacing to avoid conflicts. Each device writes only to its own key — PATCH deep merge handles this naturally with no coordination required between devices.

Recommended pattern: device namespacing

Instead of all devices writing to the same keys (where they overwrite each other), give each device its own namespace within the JSON object:

{
  "device_001": {"temperature": 72, "humidity": 45, "ts": 1234567890},
  "device_002": {"temperature": 68, "humidity": 50, "ts": 1234567891},
  "device_003": {"temperature": 75, "humidity": 42, "ts": 1234567892}
}

Each device PATCHes only its own key. Because PATCH uses deep merge, no device can accidentally overwrite another device's data:

curl -X PATCH https://onejsonfile.com/api/v1/files/YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"device_001": {"temperature": 73, "humidity": 44, "ts": 1234567900}}'

Token strategy for IoT

For IoT deployments, use authenticated tokens created from the dashboard:

Anonymous tokens expire after 24 hours — not suitable for long-running devices
Authenticated tokens never expire
Token possession is the write credential — no session or login required from the device
Store the token securely on each device (environment variable, secure storage, or hardware security module)

Reading the full fleet state

A single GET returns the state of all devices in one request — ideal for dashboards and monitoring systems:

curl https://onejsonfile.com/api/v1/files/YOUR_TOKEN

Single-writer devices: If only one device writes to a file at a time (e.g., a sensor that owns its own token), use ETags instead of namespacing — simpler structure, and you get lost-update protection for free.