API Usage

API Usage

Examples

Base URL

All API access is over HTTPS, and accessed from the api.noteshred.com domain.
All data is sent and received as JSON.

Ruby Gem

If you are integrating NoteShred into your Ruby or Rails project, we highly recommend using our Ruby gem to communicate with the API. Instructions for using the gem are here.

Authentication

All API requests require an API key to be sent within the header of the request as an authorization token in order to access the service.
Keep your API key secret as this is what identifies your application. If we detect suspicious behaviour against your API key, it will be disabled.
The token is added to the header in the following format:
Authorization: Token token=<API Key>

Example

curl https://api.noteshred.com/v1/aaaaaa  -X POST
Returns: 401: HTTP Token: Access denied. 

curl https://api.noteshred.com/v1/aaaaaa -X POST -H "Authorization: Token token=de5264da5b6265ab72947bf625e82"
Returns: 200: { "status": "invalid", "message": "Password is required", "content": [] }


Get Your API key

Your API key is available from the settings page within your NoteShred dashboard.

Rate Limiting

By default, any individual client (based on IP) is allowed 400 requests per hour. If you require more than this, please contact us

The Response

All responses are in JSON and contain status, message and content fields.
Errors and exceptions will have an empty array as the content field, where as successful create and show responses will contain the note within the content field.
The MD5 "email_hash" field is included so you can get the users Gravatar. Instructions here

Example Reponse JSON

          {
            "token": "a36c13b",
            "title": "My Super Secret Note",
            "created_by": "Long John Silver",
            "shred_method": "1",
            "email": "youremail@gmail.com",
            "email_hash": "cf0414cc7a83fabb2b0e6cb79e11e5a5",
            "content": "This is the super secret content",
            "activities": {[/* Geocoded Activities, Viewed, Created, Downloads etc */]}
          }

Methods

Create, show, index, share, shred and delete methods are exposed for you to use.

Create

The create method will create a new note, and trigger the email notification.
Attachments are not available currently with the API

Verb: POST
Path: https://api.noteshred.com/v1/notes
Required Parameters:

  • title   (A short title for your note)
  • content   (The note content)
  • recipients   (An array of email addresses you want to recieve notification of the note)
  • password   (The note password)
  • hint   (A password hint to be included with emails. Optional)
  • shred_method   (1 = Shred after reading, 2 = Shred later)
  • time_period   (Only if shred_method = 2. Options are hours, days or weeks)
  • from_now   (Only if shred_method = 2. An integer value)

Example Request JSON

          {
            "title": "My Super Secret Note",
            "shred_method": "1",
            "hint": "what was the password for server1?",
            "password": "some_password_123",
            "content": "This is the super secret content",
            "recipients": ["user1@example.com","user2@example.com"]
          }

Index

The index method lists the previous notes created by the user attached to the api key.

Verb: GET
Path: https://api.noteshred.com/v1/notes

Show

The show method decrypts and retrieves a stored note

Verb: POST
Path: https://api.noteshred.com/v1/notes/<note_id>
Required Parameters:

  • password   (The note password)

Example Request JSON

          {
            "password": "some_password_123"
          }

Shred

The shred method will destroy all encrypted content but leave the record ID so users will see a "This has been shredded" message if they try to access the note again.

Verb: POST
Path: https://api.noteshred.com/v1/notes/<note_id>/shred
Required Parameters:

  • password   (The note password)

Example Request JSON

          {
            "password": "some_password_123"
          }

Delete

The delete method will delete a note completely. Any users trying to access the note after it has been deleted will get a 404 error, or a "does_not_exist" exception if using the API

Verb: DELETE
Path: https://api.noteshred.com/v1/notes/<note_id>
Required Parameters:

  • password   (The note password)

Example Request JSON

          {
            "password": "some_password_123"
          }

Share

The share method will send an email notification with the note URL and comments to a recipient. This is the same email that is used when clicking the "Email Note" button when viewing a note through the web application

Verb: POST
Path: https://api.noteshred.com/v1/notes/<note_id>/share
Required Parameters:

  • password   (The note password)
  • dest_email   (The destination email(s). Comma seperated for multiple addresses)
  • comments   (Optional comments to be included in the email to the recipient)

Example Request JSON

          {
            "password": "some_password_123",
            "dest_email": "someguy@gmail.com",
            "comments": "Here is the information you requested last week"
          }

Request

Requests let you receive information from someone without the need for them to have a NoteShred account. Think of it like creating a blank note and asking someone else to fill it in for you. This person will be able to open a password protected link and enter some information to be encrypted which is then sent back to you in the form of a regular note, after which you will see it appear in your note list and can access using the password you originally defined

Verb: POST
Path: https://api.noteshred.com/v1/note_requests
Required Parameters:

  • password   (The note password)
  • confirm_password   (The note password again for confirmation)
  • message   (A message describing the content you want)
  • recipient_email   (The persons email you want to send the request to)

Example Request JSON

          {
            "password": "some_password_123",
            "password_confirm": "some_password_123",
            "message": "Please send me the details for server-x",
            "recipient_email": "guy@company.com"
          }

Status Codes

API responses will follow RESTful HTTP standards.
Successful requests will always result in a 200 or 201 response where as request failures, validation failures, invalid responses, permission denied or bad request bodies will result in 401 and 422 HTTP codes

Examples

jQuery

Although you will not be able to use this code on your site due to cross domain restrictions, you can how ever open https://api.noteshred.com in your browser, then open your javascript console and test out this code to get familiar with how the API works.
You will need to change the API key in the header and note ID in the URL"s to your own.

Create a new note

            data = JSON.stringify({
              "password": "password123",
              "title": "Testing NoteShred",
              "created_by": "Jason Smith",
              "shred_method": "1",
              "email": "youremail@gmail.com",
              "content": "This is super secret content"
            });

            $.ajax({
              type: "POST",
              url: "https://api.noteshred.com/v1/notes",
              data: data,
              success: function(data){console.log(data)},
              dataType: "json",
              headers: {Authorization: "Token token="82748c7a765ac87c6a65a7c76a657a779""}
            });

Retrieve a note

            data = JSON.stringify({
              "password": "password123"
            });

            $.ajax({
              type: "POST",
              url: "https://api.noteshred.com/v1/notes/6b3fad24",
              data: data,
              success: function(data){console.log(data)},
              dataType: "json",
              headers: {Authorization: "Token token="82748c7a765ac87c6a65a7c76a657a779""}
            });

Send a notification email

              data = JSON.stringify({
                "password": "password123",
                "dest_email": "recipient@gmail.com",
                "comments": "Here is the information you requested last week"
              });

              $.ajax({
                type: "POST",
                url: "https://api.noteshred.com/v1/notes/notify/6b3fad24",
                data: data,
                success: function(data){console.log(data)},
                dataType: "json",
                headers: {Authorization: "Token token="82748c7a765ac87c6a65a7c76a657a779""}
              });