JSON to CouchDB Converter
Convert JSON objects into ready-to-run CouchDB cURL commands for document insertion. Generates single-document PUT requests, bulk _bulk_docs POST commands, and handles _id and _rev fields correctly — paste the output directly into your terminal.
Convert JSON objects into ready-to-run CouchDB cURL commands for document insertion. Generates single-document PUT requests, bulk _bulk_docs POST commands, and handles _id and _rev fields correctly — paste the output directly into your terminal.
This tool is designed to provide a seamless experience for developers by handling complex operations directly in your browser with maximum speed and security.
CouchDB is an open-source NoSQL database developed by the Apache Software Foundation. Unlike relational databases that organize data into tables with fixed schemas, CouchDB stores data as JSON documents — each document is a self-contained JSON object with no required structure beyond two system fields: _id (the document identifier) and _rev (the revision token used for conflict resolution). Every other field in the document is defined by your application. This schema-free design makes CouchDB well-suited for storing heterogeneous data where different records have different shapes.
CouchDB's entire API is HTTP-based. There is no proprietary wire protocol, no client library required, and no special connection setup — you interact with CouchDB entirely through standard HTTP requests that any HTTP client can make. Creating a document is an HTTP PUT request to the document URL. Querying documents uses HTTP GET. Deleting uses HTTP DELETE. This REST API design is one of CouchDB's defining characteristics: you can interact with it using curl from the command line, fetch() from JavaScript, requests in Python, or any other HTTP client without installing a database-specific driver. The trade-off is that understanding the HTTP API is essential for using CouchDB effectively.
CouchDB also has a built-in replication protocol designed for eventually consistent multi-master replication across multiple nodes and across unreliable networks. PouchDB is a JavaScript implementation of the CouchDB protocol that runs in the browser and can sync with a CouchDB server, making the combination popular for offline-first web applications where data needs to work locally and sync when connectivity is restored. The _rev field on every document is central to this replication — it is a content hash that CouchDB uses to detect and resolve conflicts when the same document has been modified in two places simultaneously.
This tool takes a JSON object (or an array of JSON objects) and generates the CouchDB HTTP commands needed to insert the data as documents. For a single JSON object, it produces a curl PUT command targeting the CouchDB document endpoint — curl -X PUT http://127.0.0.1:5984/your_database/document_id -H "Content-Type: application/json" -d '{your json}'. The document ID in the URL is either taken from the _id field in your JSON (if present) or auto-generated as a UUID. The generated command is ready to paste into your terminal against a running CouchDB instance. For a JSON array of objects, the tool generates a _bulk_docs POST command which is CouchDB's batch insertion API. A bulk insert is significantly more efficient than inserting documents one at a time — CouchDB processes an entire batch in a single HTTP request and a single disk write transaction, making it the correct approach for loading seed data, migrating records from another system, or inserting datasets with more than a handful of documents. The generated _bulk_docs command wraps your JSON array in the required docs wrapper object that the CouchDB bulk API expects. The tool also handles the _id and _rev fields correctly. If your JSON already has an _id field, that value is used as the document ID in the PUT URL and preserved in the document body. If _id is absent, the tool generates a UUID for the document ID — you can also let CouchDB generate the ID by using POST to the database endpoint instead of PUT, which the tool offers as an option. The _rev field is intentionally excluded from new document inserts since CouchDB assigns the initial revision automatically — including _rev on a new document causes a conflict error.
1. Paste your JSON into the Input JSON field — this can be a single JSON object like {"name": "John", "age": 30} for inserting one document, or a JSON array like [{...}, {...}, {...}] for bulk inserting multiple documents using the _bulk_docs API. If your JSON already contains _id fields, those values will be used as the document IDs. Click Load Example to see a sample multi-field document before using your own data.
2. Click Convert to CouchDB cURL — the tool parses your JSON, checks for _id and _rev fields, formats the document or documents correctly for the CouchDB API, and generates the appropriate cURL command in the output panel. For single objects it generates a PUT command. For arrays it generates a _bulk_docs POST command. The database name in the generated command defaults to your_database — replace this with your actual CouchDB database name before running the command.
3. Review the generated cURL command — check that the document ID in the URL (for PUT) or in the docs array (for bulk) looks correct, that the database name is set to your actual database, and that the Content-Type header is included (application/json). The command assumes CouchDB is running locally at http://127.0.0.1:5984 — update the host and port if your CouchDB instance is running at a different address.
4. Add authentication if your CouchDB instance requires it — CouchDB by default requires authentication in production deployments. Add -u username:password to the curl command before the URL to include Basic Authentication credentials. For CouchDB instances using cookie authentication or API tokens, adjust the authentication flags according to your CouchDB configuration.
5. Copy the command and run it in your terminal against your CouchDB instance — paste the complete curl command into your terminal and press Enter. A successful insert returns a JSON response with ok: true, the document id, and the assigned rev value. If you get a 409 Conflict error, a document with that _id already exists in the database — use a different _id or delete the existing document first.
The scenario where I reach for a tool like this most is initial data loading — you have a dataset in JSON format (an API response, a CSV converted to JSON, a data export from another system) and you need to get it into a fresh CouchDB database quickly for development or testing. Writing the curl commands by hand is straightforward for one document but becomes error-prone for 50 documents and impractical for 500. This tool generates the correctly formatted commands immediately so you can focus on verifying the data structure rather than the HTTP command syntax. CouchDB's HTTP API is elegant but has specific requirements that catch developers new to CouchDB repeatedly. The Content-Type header must be application/json or CouchDB returns a 400 error even if the body is valid JSON. PUT requests must specify the document ID in the URL, not just in the body. POST requests to the database endpoint let CouchDB generate the ID but return a different response structure than PUT. The _bulk_docs endpoint requires the JSON body to be an object with a docs array, not a bare array — posting a bare JSON array returns a 400 error with a message that does not make the required structure obvious. This tool generates commands that get all of these details right by default. For migrating data from a relational database or another NoSQL system into CouchDB, the workflow is: export your data as JSON, paste it here, get the _bulk_docs command, run it against your CouchDB instance. A migration that would take an afternoon of writing and debugging curl commands takes 10 minutes with a reliable command generator. The generated commands also serve as documentation of exactly how your data was inserted, which matters when you need to reproduce the migration later.
Correct CouchDB API format — generates commands that include the required Content-Type header
the correct PUT vs POST method based on whether an _id is provided
and the proper _bulk_docs wrapper structure for batch inserts
Handles _id and _rev fields correctly — uses existing _id values as document IDs in the URL
auto-generates UUIDs when _id is absent
and excludes _rev from new document inserts to avoid conflict errors
Bulk insert support — converts JSON arrays into _bulk_docs POST commands which are far more efficient than one-at-a-time PUT requests for inserting multiple documents
Ready-to-run curl commands — the generated output pastes directly into any terminal with curl installed and runs without modification beyond replacing the database name and host
100% browser-based — your JSON data including any sensitive document content never leaves your machine and is never transmitted to any server
Handles nested objects and arrays — CouchDB stores arbitrary JSON including nested objects and arrays of values which the generated commands preserve exactly as-is
Works with custom database names and hosts — the generated commands use placeholder values that are clearly labeled for easy replacement with your actual CouchDB URL and database name
Instant conversion — all JSON parsing and command generation runs locally in your browser with no server processing delay
Loading seed data into a CouchDB database for development or testing environments
Migrating records from a relational database or another NoSQL system into CouchDB by converting exported JSON to cURL commands
Inserting API response data into CouchDB for offline-first applications using PouchDB sync
Bulk importing JSON datasets into CouchDB using the _bulk_docs API for efficient batch insertion
Generating CouchDB document insertion commands for use in setup scripts and CI/CD pipelines
Creating CouchDB documents from JSON configuration or fixture files during application bootstrapping
Testing CouchDB database setup by quickly inserting sample documents without writing API code
Converting data exports from MongoDB or Firebase into CouchDB-compatible insertion commands
Example Input
[
{
"_id": "user_001",
"name": "Priya Singh",
"email": "priya@learnhubly.com",
"role": "admin",
"isActive": true,
"tags": ["developer", "admin"]
},
{
"_id": "user_002",
"name": "Jane Smith",
"email": "jane@example.com",
"role": "editor",
"isActive": true,
"tags": ["editor"]
}
]Example Output
curl -X POST http://127.0.0.1:5984/your_database/_bulk_docs \
-H "Content-Type: application/json" \
-d '{
"docs": [
{
"_id": "user_001",
"name": "Priya Singh",
"email": "priya@learnhubly.com",
"role": "admin",
"isActive": true,
"tags": ["developer", "admin"]
},
{
"_id": "user_002",
"name": "Jane Smith",
"email": "jane@example.com",
"role": "editor",
"isActive": true,
"tags": ["editor"]
}
]
}'
# Expected response on success:
# [{"ok":true,"id":"user_001","rev":"1-abc123"},{"ok":true,"id":"user_002","rev":"1-def456"}]Invalid JSON: The tool requires valid JSON input before it can generate CouchDB commands. If your JSON has syntax errors — missing commas, unquoted keys, trailing commas, or single quotes — the conversion will fail. Use the JSON Formatter and Validator tool to fix any syntax errors first, then paste the corrected JSON here.
ID Conflicts — _id Already Exists in Database: If you run the generated curl command and CouchDB returns a 409 Conflict error, a document with that _id already exists in the target database. CouchDB does not overwrite existing documents on a PUT insert without the current _rev value. To update an existing document you must include its current _rev value in the request body. To insert as a new document, change the _id value in your JSON to a unique identifier before converting and running the command.
Large Payloads Taking Longer Than Expected: For very large JSON objects or arrays with thousands of documents, the conversion may take a moment and the generated curl command body will be very long. This is normal. For extremely large datasets (tens of thousands of documents), consider splitting the array into smaller batches of 500 to 1000 documents each and running multiple _bulk_docs commands — very large single bulk requests can timeout on slower network connections to remote CouchDB instances.
Missing Authentication Error (401 Unauthorized): CouchDB returns 401 Unauthorized if your instance requires authentication and the curl command does not include credentials. Add -u your_username:your_password to the curl command before the URL. For admin party mode (authentication disabled, common in local development) no credentials are needed. Check your CouchDB configuration (local.ini or docker environment variables) to verify whether authentication is required.
Database Does Not Exist Error (404 Not Found): If CouchDB returns 404 Not Found, the target database does not exist yet. Create it first with: curl -X PUT http://127.0.0.1:5984/your_database -u admin:password. Then run the insert command again. CouchDB does not automatically create databases on first insert unlike some other NoSQL databases.
Including _rev in new document inserts
Fix: The _rev field in CouchDB is a revision token assigned by CouchDB when a document is created or updated. On a new document insert (a document that does not yet exist in the database), the _rev field must be absent from the request body. If you include _rev: null or _rev: '' on a new document, CouchDB treats it as an update request and returns a 409 Conflict error because no existing revision matches. The tool automatically excludes _rev from generated insert commands. If you are writing your own insert code, never set _rev on a new document — only include _rev when updating an existing document, and use the exact _rev value returned by the most recent GET or the previous PUT/POST response.
Using sequential integer IDs instead of UUIDs for document _id values
Fix: CouchDB stores documents in a B-tree index sorted by _id. If you use sequential integer IDs (1, 2, 3, 4...), all new documents are always appended to the end of the B-tree, which causes hot-spot writes and replication conflicts in multi-node setups. CouchDB generates UUIDs for document IDs by default specifically to avoid this problem — UUIDs distribute writes evenly across the B-tree. For CouchDB specifically, use UUIDs or CouchDB-generated IDs rather than sequential integers, even if your application logic uses integers as identifiers. Store your application integer ID as a separate field (appId: 123) and let _id be a UUID.
Posting a bare JSON array to _bulk_docs instead of wrapping it in a docs object
Fix: The CouchDB _bulk_docs endpoint requires the request body to be a JSON object with a docs property containing the array of documents: {"docs": [{...}, {...}]}. Posting a bare JSON array directly — [{...}, {...}] — returns a 400 Bad Request with an error message that does not clearly indicate the required wrapper structure. This is one of the most common CouchDB API mistakes for developers new to CouchDB. This tool generates the correct {"docs": [...]} wrapper automatically. If you are writing curl commands manually, always remember the docs wrapper.
Forgetting that CouchDB document fields starting with _ are reserved
Fix: CouchDB reserves field names that begin with an underscore for system use. The fields _id, _rev, _deleted, _attachments, _conflicts, _deleted_conflicts, _local_seq, and _revs_info are all CouchDB system fields. If your application data has fields that start with underscore — for example _metadata or _type — CouchDB will either ignore them, reject the document, or interpret them as system instructions. Rename any application fields that start with underscore before inserting into CouchDB. A common workaround is to prefix your internal fields differently: use meta instead of _meta, or type instead of _type.
Assuming CouchDB will merge or update a document when you PUT with the same _id
Fix: In CouchDB, a PUT request to an existing document _id without providing the current _rev value returns a 409 Conflict — it does not merge or overwrite. To update an existing document you must first GET the document to retrieve its current _rev, then include that exact _rev value in your PUT request body. This is CouchDB's Multi-Version Concurrency Control mechanism — it prevents lost updates in concurrent write scenarios. If you just want to insert data without worrying about existing documents, use POST to the database endpoint (without specifying an _id in the URL) and let CouchDB generate a new unique _id, guaranteeing no conflicts.
JSON Cheatsheet
Interactive reference guide for valid JSON syntax, data types, parsing/stringifying methods, schema validation rules, and language integrations.
Regex Cheatsheet
Interactive guide to Regex anchors, character classes, quantifiers, lookarounds, capturing groups, and search flags.
HTTP Headers Cheatsheet
Complete guide to standard and security HTTP headers including Authorization, CORS control, caching policies, and CSP directives.
SQL Cheatsheet
Complete guide to SQL statements including SELECT queries, WHERE filters, aggregate functions, JOIN types, and DDL commands.
Does it support bulk uploads?
Yes. If you paste a JSON array rather than a single object, the tool generates a _bulk_docs POST command which is CouchDB's native batch insertion API. Bulk insertion is dramatically more efficient than inserting documents one at a time — a single _bulk_docs request can insert hundreds or thousands of documents in one HTTP request and one disk transaction. For any dataset larger than a handful of documents, bulk insertion is the correct approach. The tool wraps your JSON array in the required docs object structure that the _bulk_docs endpoint expects.
Can I customize the database name in the generated command?
Yes. The generated curl command uses your_database as a placeholder database name in the URL. Replace your_database with your actual CouchDB database name before running the command. The database must already exist in CouchDB before inserting documents — if it does not exist, create it first with curl -X PUT http://127.0.0.1:5984/your_actual_database and then run the insert command.
Is it safe for sensitive data?
Yes. All JSON parsing and curl command generation runs entirely in your browser. Your JSON data — including any personal information, credentials, or proprietary content in your documents — never leaves your machine and is never transmitted to any server. The generated curl command is just text that you paste into your own terminal and run against your own CouchDB instance.
What is the _rev field and why does it matter?
The _rev field is CouchDB's document revision token. Every time a document is created or updated, CouchDB assigns a new _rev value in the format generation-hash, for example 1-abc123 for the first revision and 2-def456 for the second. To update a document, you must include its current _rev value in the request — CouchDB uses this to detect concurrent modification conflicts. For new document inserts, _rev must be absent. This tool correctly excludes _rev from generated insert commands. When you run a successful insert, the response includes the assigned _rev value — save this if you plan to update the document later.
How is CouchDB different from MongoDB?
Both are document databases that store JSON, but they differ significantly in architecture and use case. CouchDB's API is pure HTTP REST — every operation is an HTTP request, no driver needed. MongoDB uses a binary protocol (BSON) and requires a driver. CouchDB has built-in multi-master replication designed for eventual consistency across unreliable networks, making it the preferred choice for offline-first applications using PouchDB. MongoDB has more powerful query capabilities with its aggregation pipeline and index options. CouchDB uses MapReduce views (or Mango queries) for querying. For offline-first mobile or web apps that need to sync, CouchDB plus PouchDB is the established pattern. For complex analytics or rich queries on large datasets, MongoDB is typically the stronger choice.
Can I use this to update existing CouchDB documents?
The tool generates insert commands for new documents. To update an existing CouchDB document, you need the document's current _rev value, which is only available after you have previously inserted the document (from the insert response) or retrieved it with a GET request. The update command structure is: curl -X PUT http://127.0.0.1:5984/database/document_id -H 'Content-Type: application/json' -d '{...your updated document including the current _rev...}'. The _rev must match the document's current revision exactly — if another process has updated the document between your GET and your PUT, your update will fail with a 409 Conflict and you must retry with the latest _rev.
What happens if my JSON has an _id that already exists in CouchDB?
CouchDB returns a 409 Conflict error when you try to PUT a document with an _id that already exists without providing the correct _rev. It does not overwrite or merge. You have three options: change the _id in your JSON to a unique value and re-generate and run the insert command, DELETE the existing document first and then re-run the insert, or GET the existing document to retrieve its _rev and then update it with a PUT that includes the _rev. For bulk inserts using _bulk_docs, individual document conflicts are reported per-document in the response array — successfully inserted documents have ok: true and conflicting documents have error: conflict, so a partial batch insert is possible.
Does CouchDB need to be running locally or can I use a remote instance?
The generated curl command defaults to http://127.0.0.1:5984 (localhost) but works with any CouchDB instance. Replace the host and port with your remote CouchDB URL — for example http://couchdb.example.com:5984 or a cloud-hosted CouchDB URL from IBM Cloudant or any other managed CouchDB service. For remote instances, add authentication credentials with -u username:password in the curl command. If your CouchDB is behind HTTPS, replace http:// with https:// in the URL. IBM Cloudant, which is a cloud-hosted CouchDB-compatible service, also accepts the same curl commands with its own authentication headers.
How to Convert JSON to Dart Classes for Flutter – Complete In-Depth Guide (2026)
How to convert JSON to Dart classes for Flutter in 2026. In-depth guide covering Dart model best practices, null safety, immutable classes, code generation with json_serializable & freezed, Flutter integration with Riverpod, and real-world architecture tips from a Principal Software Engineer with 15+ years experience.
What is JSON? How to Format, Validate & Use It (Complete Guide 2026)
What is JSON? How to Format, Validate & Use It (Complete Guide 2026). In-depth explanation of JSON syntax, real-world use cases, formatting best practices, common mistakes, advantages, disadvantages, and expert tips from a Principal Software Engineer with 15+ years experience.
How to validate JSON online (step-by-step guide)
Invalid JSON can break your application. Follow this guide to quickly validate and fix your JSON data.
Recent Activity
No recent activity