Documents

Create, read, update, and delete JSON documents in a collection.

Create a Document

POST/v1/db/{ns}/{collection}

Creates a new document with an auto-generated ID.

Path Parameters

Name	Type	Description
`ns`required	string	Namespace name (e.g. 'default')
`collection`required	string	Collection name (e.g. 'users')

curl -X POST https://api.jsondb.cloud/v1/db/default/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "[email protected]"}'

Response (201 Created)

{
  "_id": "use_a1b2c3d4e5f6",
  "_createdAt": "2026-02-24T12:00:00.000Z",
  "_updatedAt": "2026-02-24T12:00:00.000Z",
  "_version": 1,
  "_collection": "users",
  "name": "Alice",
  "email": "[email protected]"
}

POST/v1/db/default/users

API Key

Request Body

Enter your API key above

Get a Document

GET/v1/db/{ns}/{collection}/{id}

Retrieves a single document by its ID.

Path Parameters

Name	Type	Description
`ns`required	string	Namespace name
`collection`required	string	Collection name
`id`required	string	Document ID

curl https://api.jsondb.cloud/v1/db/default/users/use_a1b2c3d4e5f6 \
  -H "Authorization: Bearer YOUR_API_KEY"

Replace a Document

PUT/v1/db/{ns}/{collection}/{id}

Replaces the entire document. Creates it if it doesn't exist.

warning

PUT replaces the entire document body. Use PATCH for partial updates.

curl -X PUT https://api.jsondb.cloud/v1/db/default/users/use_a1b2c3d4e5f6 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice Updated", "email": "[email protected]", "role": "admin"}'

Partial Update (Merge Patch)

PATCH/v1/db/{ns}/{collection}/{id}

Merge-patches a document (RFC 7396). Only fields you send are updated.

curl -X PATCH https://api.jsondb.cloud/v1/db/default/users/use_a1b2c3d4e5f6 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{"role": "admin"}'

JSON Patch (RFC 6902)

PATCH/v1/db/{ns}/{collection}/{id}

Applies JSON Patch operations. Set Content-Type to application/json-patch+json.

curl -X PATCH https://api.jsondb.cloud/v1/db/default/users/use_a1b2c3d4e5f6 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json-patch+json" \
  -d '[{"op": "replace", "path": "/name", "value": "Alice Smith"}, {"op": "add", "path": "/verified", "value": true}]'

Delete a Document

DELETE/v1/db/{ns}/{collection}/{id}

Permanently deletes a document.

curl -X DELETE https://api.jsondb.cloud/v1/db/default/users/use_a1b2c3d4e5f6 \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns 204 No Content on success.

Document Metadata

Every document includes auto-managed metadata fields:

Metadata Fields

Name	Type	Description
`_id`	string	Auto-generated unique identifier (e.g. 'use_a1b2c3d4')
`_createdAt`	string	ISO 8601 timestamp of creation
`_updatedAt`	string	ISO 8601 timestamp of last update
`_version`	number	Increments on every write (starts at 1)
`_collection`	string	The collection this document belongs to