CouchDB – Create Document – REST API / Web Interface

CouchDB – Create Document

A CouchDB document is a JSON object stored inside a database. You can create one with a client-supplied document ID by sending an HTTP PUT request, let CouchDB generate an ID by sending POST to the database endpoint, or use the built-in Fauxton web interface.

The examples below use CouchDB at 127.0.0.1:5984 and an existing database named tutorialkart. Replace the server address, database name, credentials, and document data with values for your installation.

Create a CouchDB Document with a Specific ID Using PUT

Send a HTTP PUT request with the following URL.

http://hostname/database_name/new_document_id/

We have our CouchDB running in our localhost. Hence, we shall use 127.0.0.1:5984 as hostname.

We will use an existing database named tutorialkart.

Let us create a document with id 0005.

The resulting request URL that we have to use for PUT request will become,

http://127.0.0.1:5984/tutorialkart/0005/

The request body must contain valid JSON. Set the Content-Type header to application/json. The following command creates document 0005 with two fields. Replace admin:password with an account that has permission to write to the database.

curl -X PUT "http://127.0.0.1:5984/tutorialkart/0005" \
  -u "admin:password" \
  -H "Content-Type: application/json" \
  -d '{"name":"CouchDB Tutorial","type":"article"}'

A successful creation normally returns HTTP 201 Created and a JSON response containing ok, the document id, and its first revision token.

{"ok":true,"id":"0005","rev":"1-revision_hash"}

We will use Postman, to trigger a PUT request with the URL to create a document in CouchDB Database. You can use any other CLI or GUI tool of your choice.

Verify the New CouchDB Document with GET

Let us check if the document is created.

Send a HTTP GET Request with the same URL as above.

curl -X GET "http://127.0.0.1:5984/tutorialkart/0005" \
  -u "admin:password"

The document has been created and is present in the database. The GET response contains the stored fields together with CouchDB metadata such as _id and _rev.

{
  "_id": "0005",
  "_rev": "1-revision_hash",
  "name": "CouchDB Tutorial",
  "type": "article"
}

Create a CouchDB Document with an Automatically Generated ID

When the application does not need to choose the document ID, send a POST request to the database URL. CouchDB generates a unique ID if the JSON body does not contain an _id field.

curl -X POST "http://127.0.0.1:5984/tutorialkart" \
  -u "admin:password" \
  -H "Content-Type: application/json" \
  -d '{"name":"Generated ID Example","type":"article"}'

The response has the generated value in the id property. Store both the returned ID and revision when the application will update the document later.

Create a CouchDB Document in the Fauxton Web Interface

You can also create document in CouchDB database using Web Interface.

Open URL http://hostname/_utils/ in your browser. In this example, the URL will be http://127.0.0.1:5984/_utils/.

Sign in if authentication is enabled. Click on Databases in the left panel, open the database in which you want to store the document, and then choose Create Document. The exact placement of controls can vary slightly between Fauxton versions.

An editor appears with the "_id" field pre-populated. You can override the id value. Also, add the required fields to the JSON text and then click on Create Document button.

Field names and string values must be enclosed in double quotation marks, and the complete editor content must be valid JSON. Avoid adding a trailing comma after the final property.

Once you click on the Create Document button, if everything is good, a new document is created.

To view the document, open Table view and click on the document.

When you click on the document, an editor will be opened with the JSON document.

CouchDB Document Creation Errors and Their Causes

• 400 Bad Request: The request body is not valid JSON, the database name is invalid, or the request URL is malformed.
• 401 Unauthorized: Credentials are missing or incorrect.
• 403 Forbidden: The authenticated user does not have permission to create documents in the database.
• 404 Not Found: The target database does not exist.
• 409 Conflict: A document with the specified ID already exists. Creating it again with PUT is treated as an update and requires the current _rev value.
• 415 Unsupported Media Type: The request body was sent without an appropriate Content-Type: application/json header.

If a document ID contains spaces, slashes, question marks, or other reserved URL characters, encode it before placing it in the request path. Applications commonly use simple generated identifiers to avoid ambiguous URLs.

CouchDB Create Document Questions

What is the difference between PUT and POST when creating a CouchDB document?

Use PUT /database/document-id when the client chooses the document ID. Use POST /database when CouchDB should generate the ID, although POST can also accept an _id field in the JSON body.

Why does CouchDB return a 409 conflict while creating a document?

The requested document ID already exists, or an update was attempted without the current revision token. Read the existing document, obtain its _rev, and include that revision in a deliberate update request.

Can a CouchDB document contain nested JSON objects and arrays?

Yes. A CouchDB document can contain JSON strings, numbers, booleans, null values, arrays, and nested objects. The entire request body must remain valid JSON.

Does CouchDB require an _id field in the request body?

No. For PUT, the document ID comes from the URL. For POST, CouchDB generates an ID when _id is absent. If _id is provided in a POST body, CouchDB uses that value.

CouchDB Document Creation Review Checklist

• Confirm that the target database already exists and that its name is correct.
• Use PUT only when a specific document ID is required; otherwise consider POST with a generated ID.
• Send valid JSON with the Content-Type: application/json header.
• Verify that the authenticated user has write permission for the database.
• Check for HTTP 201 Created, retain the returned id and rev, and verify the document with GET.

Summary

In this CouchDB Tutorial, we learned to create a new document in CouchDB database via HTTP REST API and Web Interface provided by CouchDB. A PUT request creates a document with a chosen ID, while a POST request can let CouchDB generate the ID. Successful responses include a revision value that is required for later updates.