API Usage

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/notes
Returns: 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

Example cURL
    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>

Example cURL
    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

Example cURL
    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