Interact with the documents in your Mongo database’s collections.

The documents API is where much of the fun happens. It allows you to interact with the documents including adding and querying. You can query, create, read, update and delete documents.

GET /databases/:db/collections/:col/documents

List or query documents under the specified collection.

This will return a list of the documents in your collection. If given a query it will perform a search on the documents.

Required Parameters:

_apikey Your MongoHQ account’s secret key.

db The database name.

col The collection name.

Optional Parameters:

q A JSON document to use in querying your data.

fields A JSON array or hash describing the fields to return from the query.

skip An integer with the number of documents to skip. (allowing pagination)

limit The number of documents to return. (defaults to 20, max of 100)

sort A JSON document describing how to sort the results.

Returned Headers X-Mongohq-Count Total number of documents matching the query (or no query)

Example Request:

curl -X GET "https://api.mongohq.com/databases/vehicles/collections/rockets/documents?_apikey=12345&limit=5"

GET /databases/:db/collections/:col/documents/:doc_id

Retrieves a particular document by _id under the specified collection. This will return document specified by doc_id.

Required Parameters:

_apikey Your MongoHQ account’s secret key.

db The database name.

col The collection name.

doc_id The document to retrieve. This is the Mongo _id. The API will attempt to convert the doc_id string to the appropriate object where necessary (eg. to an ObjectID type).

Example Request:

curl -X GET https://api.mongohq.com/databases/vehicles/collections/rockets/documents/bottle?_apikey=12345

POST /databases/:db/collections/:col/documents

Create a new document under the specified collection

This will create a new document with the document specified. There is no need to pass an _id as this will be generated automatically.

Required Parameters:

_apikey Your MongoHQ account’s secret key.

db The database name.

col The collection name.

document The JSON document to be created.

Optional Parameters

safe If set to true, the operation waits until the document is saved before returning. Otherwise, the document gets saved asynchronously (defaults to false per MongoDB specs.)

Example Request:

curl -X POST https://api.mongohq.com/databases/vehicles/collections/rockets/documents?_apikey=12345 \
-H "Content-Type: application/json" \
-d '{"document" : {"_id" : "bottle", "pilot_name" : "Elton John"}, "safe" : true }'

PUT /databases/:db/collections/:col/documents/:doc_id

Update a single document by id under the specified collection. You can pass any JSON document that is accepted by the update command in MongoDB.

Required Parameters:

_apikey Your MongoHQ account’s secret key.

db The database name.

col The collection name.

document The JSON document update command (accepts standard MongoDB update directives, like $set or $inc).

doc_id The document to update. This is the Mongo _id. The API will attempt to convert the doc_id string to the appropriate object where necessary (eg. to an ObjectID type).

Optional Parameters:

safe If set to true, the operation waits until the document is saved before returning. Otherwise, the document gets saved asynchronously (defaults to false)

Example Request:

curl -X PUT https://api.mongohq.com/databases/vehicles/collections/rockets/documents/bottle?_apikey=12345 \
-H "Content-Type: application/json" \
-d '{"document" : { "$set" : {"pilot_name" : "Rocket Man"} } }'

PUT /databases/:db/collections/:col/documents

Update a documents by criteria. Also known as bulk update. You can pass any JSON criteria and new object that is accepted by the update command in MongoDB.

Required Parameters:

_apikey Your MongoHQ account’s secret key.

db The database name.

col The collection name.

criteria The JSON criteria used to match which documents to update

object The JSON document update command (called objNew in the MongoDB docs. Accepts standard MongoDB update directives, like $set or $inc).

Optional Parameters:

upsert If set to true, the operation will create records that do not exist. Upsert only inserts a single document. (defaults to false)

multi If set to true, all documents matching he criteria should be updated. false* will update just one. (defaults to false)

safe If set to true, the operation waits until the document is saved before returning. Otherwise, the document gets saved asynchronously (defaults to false)

Example Request:

curl -X PUT https://api.mongohq.com/databases/vehicles/collections/rockets/documents?_apikey=12345 \
-H "Content-Type: application/json" \
-d '{"criteria", { "pilot_name" : "Rocket Man" }, "object" : { "$set" : {"pilot_name" : "Elton John"} } }'

DELETE /databases/:db/collections/:col/documents/:doc_id

Destroy a single document by id under the specified collection. Be careful as this operation cannot be undone.

Required Parameters:

_apikey Your MongoHQ account’s secret key.

db The database name.

col The collection name.

doc_id The document to delete. This is the Mongo _id. The API will internally attempt to convert the doc_id string to the appropriate object where necessary (eg. to an ObjectID type).

Example Request:

curl -X DELETE https://api.mongohq.com/databases/vehicles/collections/rockets/documents/bottle?_apikey=12345