API Usage

NoteShred API

The NoteShred API is currently in beta. API keys are attached to user accounts. If you wish to use the NoteShred API, please feel free to get in contact to discuss your application requirements. Email us at admin[at]noteshred.com

Base URL

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

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": [] }

Request an API key

You may request an API key to use with your product from the contact page. Please include your applications name and how you intend to use NoteShred in your request.

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

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

Methods

Create, show, previous, 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
Required Parameters:

title (A short title for your note)
email (The email address of the notes owner)
created_by (The note owners name)
content (The note content)
password (The note password)
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',
            'created_by': 'Long John Silver',
            'shred_method': '1',
            'email': 'youremail@gmail.com',
            'password': 'some_password_123',
            'content': 'This is the super secret content'
          }

The previous method lists the previous notes created by the user attached to the api key. This method only applies to registered users

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

Show

The show method decrypts and retrieves a stored note

Verb: POST
Path: https://api.noteshred.com/v1/<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/<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/<note_id>
Required Parameters:

password (The note password)

Example Request JSON

          {
            'password': 'some_password_123'
          }

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/<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'
          }

Status Codes

Every API response will be in the same format. The root level of the JSON object will have a status property.
The status code will always be one of the following:

success

Means everything succeeded. No errors or validation issues occurred

invalid

Means your request was invalid. Usually caused by missing a required parameter or posting an invalid JSON object

error

Means there was an error processing your request. Typically an incorrect password or a problem creating your note. See the message property for more details

validation_error

Validation failed when saving a note. This is enforced by internal rules. Typically things like "password must be a minimum of 8 characters", "email address is required" etc

exception

Something went wrong internally. You wont receive any additional information about this, but we will be notified with the details of the exception to investigate further.

shredded

You will receive a "shredded" status when you attempt to view a note with an expired "shred by" date. The note will be shredded immediately.

locked

You will receive this status when the note has been locked due to too many failed login attempts

Rate Limiting

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

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",
              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/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/notify/6b3fad24",
                data: data,
                success: function(data){console.log(data)},
                dataType: 'json',
                headers: {Authorization: 'Token token="82748c7a765ac87c6a65a7c76a657a779"'}
              });

API Usage

API Usage

Examples

NoteShred API

Base URL

Authentication

Example

Request an API key

The Response

Methods

Create

Previous

Show

Shred

Delete

Share

Status Codes

success

invalid

error

validation_error

exception

shredded

locked

Rate Limiting

Examples

jQuery