The primary way to interact with HarperDB is through our REST API. All features and functionality can be called via the API. All API calls require authentication, which you can read more about under the Security tab.



Postman API Collection

HarperDB maintains a Postman collection with all API calls and basic examples.


HarperDB Postman Collection



Code Samples

API code samples, generated from the Postman collection, can be found directly in the the HarperDB Studio.


Studio Code Samples



HarperDB API Basics

The HarperDB API is accessed through a single endpoint. This section describes the basics required for every HarperDB API request.



Request Type: HarperDB always expects the request type to be a POST. 


URL: The URL of the endpoint you are interacting with. For HarperDB, this will always be your instance URL. If you are using the HarperDB Studio, your URL will be provided on your instance card or under the config tab inside your instance. Click the clipboard icon next to your URL and paste it into the Postman request URL bar.


Headers: All HarperDB requests require two headers in order to make successful API requests.

  1. Key: “Authorization”
    Value: Your basic authentication token
  2. Key: “Content-Type”
    Value: “application/json”

You will need to change the Authorization header to your personal HarperDB instance authentication token to properly authenticate. We recommend importing our API Reference into Postman, instructions can be found below.


Body: The body will consist of a JSON which will carry the operation and any other data appropriate to that operation. For all requirements and options of our operations, please visit our API Reference docs.



Response Body: The HarperDB API response will be displayed here.



Using the Postman App with the HarperDB API Reference

The HarperDB API Reference is powered by Postman, which means you can open the full HarperDB API reference in your Postman application and begin interacting with your HarperDB instance. To learn more about Postman visit the Postman Learning Center.




Opening the HarperDB API Reference as a Postman Collection:

  1. Open the  HarperDB API Reference.
  2. Click the “Run in Postman” button, located at the top right of the screen.
  3. Select the Postman application you want to open (Web based or Application).
  4. The HarperDB API Postman Collection should now be imported into Postman.
  5. Click on the HarperDB Collection. in your collections to open the collection settings.
  6. Click on the Variables tab. 
  7. Replace all values in the CURRENT VALUE column to match your HarperDB instance.
    • HDB_ENDPOINT: The URL of your HarperDB instance.
    • HDB_USER: Username of your HarperDB instance user.
    • HDB_PASSWORD: Password of your HarperDB instance user.
  8. Save the Collection.
  9. Your HarperDB Postman Collection is now configured to interact with your instance.