Notehub API Introduction

This API reference contains an overview of all requests relevant to interacting with Notehub.io. Each section details request parameters, response members, example curl requests, and JSON responses.

note

New to the Notehub API? Check out Using the Notehub API, our tutorial which walks you through running your first few requests.

note

For web apps, check out our Notehub JS library

If you want to access the Notehub API in a JavaScript-based application, consider our Notehub JS library available on npm. It's our official JavaScript-based library to connect to and interact with the Notehub API.

Authentication with OAuth Bearer Tokens

All requests to the Notehub API are authorized via OAuth bearer tokens. Each bearer token is unique based on the Notehub user and Notehub project, and can be obtained via a request to the /oauth2/token endpoint.

curl -X POST
 -L 'https://notehub.io/oauth2/token'
 -H 'content-type: application/x-www-form-urlencoded'
 -d grant_type=client_credentials
 -d client_id=your-client-id
 -d client_secret=your-client-secret

The client_id and client_secret values can be obtained from the Settings of a Notehub project, under Programmatic API access:

note

Tokens automatically expire after 30 minutes, as reflected by the expires_in property (in seconds), which is returned alongside the access_token.

Tokens can also be manually revoked at any time using the Remove Client Application button that appears after enabling programmatic API access.

Authentication with Session Tokens (Deprecated)

warning

This authentication method is officially deprecated in favor of the OAuth workflow documented above.

All requests to the Notehub API require an authentication token in the form of an X-SESSION-TOKEN header. This token can be obtained via a request to the /auth/login endpoint using a Notehub username and password in the body of the request.

curl -X POST
     -L 'https://api.notefile.net/auth/login'
     -d '{"username":"you@youremail.com", "password": "your_password"}'

note

Accounts using GitHub Authentication

If an account was created by using "Sign in with GitHub", by default there is no password available for API authentication purposes. Therefore, users will need to set a password in the Account settings panel in Notehub.io. This password will only be used when generating an authentication token.

API Calls and Consumption Credits

Notehub API calls utilize your account's Consumption Credits (CCs). For more information, please consult our pricing page.

Postman Collection for Notehub API

Want to use the Postman API platform to test your Notehub API calls? Download our Postman Collection and get started now.

After you've imported the data file into Postman, click on the top level folder of the Notehub API collection, and confirm if the baseUrl variable's initial value and current value are set. If not, set them to https://api.notefile.net.

Next, click the eyeball/page icon in the upper right hand corner of Postman to create a new environment (this will hold our secret X-Session-Token value to authenicate with the Notehub API). Select Add on the Environment section, rename the new environment to something like "Notehub API Env" and make a new variable named apiKey, set its type to secret, and hit the Save button in the upper right corner (no need to add any values here, we'll do it dynamically in the next step).

Finally, select the "Notehub API Env" option (or whatever you named your new environment) from the Environment dropdown in the top right corner, open the login request inside of the Notehub API folder, add your username and password for your Notehub account to the Body tab and in the Tests tab, add the following code snippet:

var jsonData = JSON.parse(responseBody);
pm.environment.set("apiKey", jsonData.session_token);

This code will set the environment variable apiKey to the generated X-Session-Token value that every other Notehub API request needs. As long as the environment with the apiKey value is selected, any subsequent Notehub API requests you make should work.