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. Only you can write or delete them. No expiry.

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

For authenticated endpoints, your session cookie is used automatically when accessing via the browser. For API access, tokens are passed in the URL path — no Authorization header needed.

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":{"hello":"world"}}'

Example response

{
  "token": "anon_Jzwn1fVnlY0z8hYTaiDmS5SHSRufOLM4",
  "expiresAt": "2024-03-31T20:42:22.778Z",
  "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

{"hello":"world"}

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 '{"user":"alice","theme":"dark"}'

Example response

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

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 '{"theme":"light"}'

Example response

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

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/files Auth required

List all files for the authenticated user.

Response

{ "files": FileRecord[], "usage": UsageInfo }

Example

curl https://onejsonfile.com/api/v1/files \
  -H "Cookie: next-auth.session-token=YOUR_SESSION"

Example response

{
  "files": [
    {
      "token": "abc123...",
      "name": "My Config",
      "fileSize": 256,
      "createdAt": "2024-03-01T00:00:00Z",
      "lastAccessedAt": "2024-03-30T12:00:00Z"
    }
  ],
  "usage": {
    "filesUsed": 1,
    "filesMax": 3,
    "tier": "free"
  }
}

POST/api/v1/files Auth required

Create a new named file for the authenticated user.

Request body

{ "name"?: string, "content"?: object }

Response

{ "token": string, "name": string | null, "createdAt": string, "fileSize": number }

Example

curl -X POST https://onejsonfile.com/api/v1/files \
  -H "Content-Type: application/json" \
  -H "Cookie: next-auth.session-token=YOUR_SESSION" \
  -d '{"name":"App Config","content":{"debug":false}}'

Example response

{
  "token": "abc123XYZ...",
  "name": "App Config",
  "createdAt": "2024-03-30T20:00:00Z",
  "fileSize": 16
}

GET/api/v1/account Auth required

Get account information and usage statistics for the authenticated user.

Response

{ "id", "username", "email", "tier", "createdAt", "usage" }

Example

curl https://onejsonfile.com/api/v1/account \
  -H "Cookie: next-auth.session-token=YOUR_SESSION"

Example response

{
  "id": "uuid...",
  "username": "your-username",
  "email": "you@example.com",
  "tier": "free",
  "createdAt": "2024-03-01T00:00:00Z",
  "usage": {
    "filesUsed": 2,
    "filesMax": 3,
    "maxFileSizeBytes": 1048576,
    "requestsPerHour": 100
  }
}

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
INTERNAL_ERROR	500	Something went wrong on our end

Rate Limits

Tier	Files	Max size	Req / hour
Anonymous	1 (temp)	100 KB	10
Free	3	1 MB	100
Indie	50	10 MB	1,000
Pro	Unlimited	100 MB	10,000

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)

# Write data
curl -X PUT "https://onejsonfile.com/api/v1/files/$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user":"alice","settings":{"theme":"dark"}}'

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

# Merge an update
curl -X PATCH "https://onejsonfile.com/api/v1/files/$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"settings":{"theme":"light"}}'

# 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());

// Write data
await fetch(`${BASE}/api/v1/files/${token}`, {
  method: "PUT",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ user: "alice", theme: "dark" }),
});

// Read it back
const data = await fetch(`${BASE}/api/v1/files/${token}`).then(r => r.json());
console.log(data); // { user: "alice", theme: "dark" }

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

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"]

# Write data
requests.put(
    f"{BASE}/api/v1/files/{token}",
    json={"user": "alice", "theme": "dark"},
)

# Read it back
data = requests.get(f"{BASE}/api/v1/files/{token}").json()
print(data)  # {'user': 'alice', 'theme': 'dark'}

# Merge update
requests.patch(
    f"{BASE}/api/v1/files/{token}",
    json={"theme": "light"},
)

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