API Reference

All endpoints live under /<username>/<filename>.

GET

Fetch JSON content. Supports nested paths and query params.

GET

/johndoe/products

const res = await fetch("https://json.shahriyar.dev/johndoe/products")
const data = await res.json()
console.log(data)

Returns raw JSON. Supports conditional requests via If-None-Match (ETag) and If-Modified-Since — returns 304 Not Modified when unchanged.

Path Traversal

GET

/johndoe/store/inventory/items

const res = await fetch("https://json.shahriyar.dev/johndoe/store/inventory/items")
const data = await res.json()
console.log(data)

See Nested Paths.

Query Params

GET

/johndoe/products?search=widget&sort=price&order=desc

const res = await fetch("https://json.shahriyar.dev/johndoe/products?search=widget&sort=price&order=desc")
const data = await res.json()
console.log(data)

See Query Parameters.

POST

Add item to array, or replace item by ID.

Append

POST

/johndoe/products

const res = await fetch("https://json.shahriyar.dev/johndoe/products", {
  method: "POST",
  headers: { Authorization: "Bearer js_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" },
  body: JSON.stringify({...}),
})
const data = await res.json()
console.log(data)

Response 201:

{ "success": true, "data": { "id": 4, "name": "New Item", "price": 9.99 } }

Auto-ID: If existing elements have id/_id, auto-generates (numeric → max+1, string → UUID). Body id/_id used as-is. Duplicate returns 409.

Replace

POST

/johndoe/products/1

const res = await fetch("https://json.shahriyar.dev/johndoe/products/1", {
  method: "POST",
  headers: { Authorization: "Bearer js_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" },
  body: JSON.stringify({...}),
})
const data = await res.json()
console.log(data)

Finds by id/_id. Replaces entire element. Path ID wins. 404 if not found.

PATCH

Merge fields into object or filtered array items.

PATCH

/johndoe/products/1

const res = await fetch("https://json.shahriyar.dev/johndoe/products/1", {
  method: "PATCH",
  headers: { Authorization: "Bearer js_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" },
  body: JSON.stringify({...}),
})
const data = await res.json()
console.log(data)

Batch Update

PATCH

/johndoe/products?inStock=false

const res = await fetch("https://json.shahriyar.dev/johndoe/products?inStock=false", {
  method: "PATCH",
  headers: { Authorization: "Bearer js_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" },
  body: JSON.stringify({...}),
})
const data = await res.json()
console.log(data)

Query params filter array items, body merges into each match.

{ "success": true, "data": [...] }

DELETE

Remove item by ID or bulk by filter.

Single

DELETE

/johndoe/products/1

const res = await fetch("https://json.shahriyar.dev/johndoe/products/1", {
  method: "DELETE",
  headers: { Authorization: "Bearer js_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" },
})
const data = await res.json()
console.log(data)

{ "success": true, "data": { "id": 1, "name": "Widget", "price": 9.99 } }

Bulk

DELETE

/johndoe/products?inStock=false

const res = await fetch("https://json.shahriyar.dev/johndoe/products?inStock=false", {
  method: "DELETE",
  headers: { Authorization: "Bearer js_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" },
})
const data = await res.json()
console.log(data)

Returns array of removed items.

Error Codes

Code	When
400	Invalid body, target not array (POST), no ID/filter (DELETE)
401	Missing/invalid API key (mutations)
403	Private file, no valid key (GET)
404	User, file, path, or ID not found
409	Duplicate `id`/`_id` (POST)
429	Rate or monthly limit exceeded
500	Invalid JSON content in file