API Usage
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 POSTReturns: 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""} });