API Usage
Base URL
All API access is over HTTPS, and accessed from the www.noteshred.com domain.
All endpoints are versioned. The current version is v2 and was released on August 2020
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://www.noteshred.com/api/v2/notesReturns: 401: {"message":"Unauthorized"}
curl https://www.noteshred.com/api/v2/notes -H "Authorization: Token token=[your api key]"Returns: 200: {"result":[{"token":"2529fa1262","title":"My super secret note..","shred_by":"2020-09-15T03:40:23.000Z","is_shredded":false ....}]}
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 may contain message and result fields where applicable
Errors and feedback will be found in the message field where are any dat returned as either result of a query or write operation will be included in the result field
Example Reponse JSON
message: "Successfully created" result: { "token": "a36c13b", "title": "My Super Secret Note", "shred_method": "1", "url": "https://shred.io/efeafa1", "attachment": {"downloads": 0, "filename": "secret-document.docx": "size": 12382673}, "user": {id: 1, "name": "Jack Sparrow", "email": "jack@thepiratelife.com"}, "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 directly with the API
Verb: POST
Path: https://www.noteshred.com/api/v2/notes
Parameters
- title
A short title for your note - content
The note content - recipients
Email address of a person you want to recieve notification of the note. Optional - password
The note password - hint
A password hint to be included with emails. Optional - shred_method
1 = Shred after reading or 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 indicating number of hours, days or weeks
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" }Example cURL
curl \ --header "Authorization: Token token=[your api key]" \ --header "Content-Type: application/json" \ --request POST \ --data '{"title": "My Super Secret Note","shred_method": "1", "password": "some_password_123", "content": "This is the super secret content", "recipients": "user1@example.com"}' \ https://www.noteshred.com/api/v2/notes
Index
The index method lists notes created by the user and other users within the same subscription
Verb: GET
Path: https://www.noteshred.com/api/v2/notes
curl \ --header "Authorization: Token token=[your api key]" \ --header "Content-Type: application/json" \ --request GET \ https://www.noteshred.com/api/v2/notes
Show
The show method retrieves the properties of a note but does not display encrypted content.
The response is a more extensive note than the one returned by the index endpoint and includes additional information such as the note activities (timeline)
Verb: GET
Path: https://www.noteshred.com/api/v2/notes/<note_id>
curl \ --header "Authorization: Token token=[your api key]" \ --header "Content-Type: application/json" \ --request GET \ https://www.noteshred.com/api/v2/notes/fe13a241
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://www.noteshred.com/api/v2/notes/<note_id>/shred
curl \ --header "Authorization: Token token=[your api key]" \ --header "Content-Type: application/json" \ --request POST \ https://www.noteshred.com/api/v2/notes/fe13a241/shred
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://www..noteshred.com/api/v2/notes/<note_id>
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 "Send" button when viewing a note through the web application
Verb: POST
Path: https://www.noteshred.com/api/v2/notes/<note_id>/share
Parameters
-
recipients
The recpients email address -
message
Message to be included in the email to the recipient
Example Request JSON
{ "recipients": "someguy@gmail.com", "message": "Here is the information you requested last week" }Example cURL
curl \ --header "Authorization: Token token=[your api key]" \ --header "Content-Type: application/json" \ --request POST \ --data '{"message": "Here is the information you requested last week", "recipients": "user1@example.com"}' \ https://www.noteshred.com/api/v2/notes/ea1e13fa/share
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://www.noteshred.com/api/v2/note_requests
Parameters
- title
The note request title - password
The note request password - confirm_password
The note password again for confirmation - message
A message describing the content you want - recipients
The persons email you want to send the request to
Example Request JSON
{ "title": "Request for server-x credentials", "password": "some_password_123", "password_confirm": "some_password_123", "message": "Please send me the details for server-x", "recipients": "guy@company.com" }Example cURL
curl \ --header "Authorization: Token token=[your api key]" \ --header "Content-Type: application/json" \ --request POST \ --data '{"title": "Request for server-x credentials", "password": "password123", "password_confirm": "password123", "message": "Please send me the details for server-x", "recipients": "user1@example.com"}' \ https://www.noteshred.com/api/v2/notes/ea1e13fa/share
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 500, 401 and 422 HTTP codes