API reference

Base URL

All API access is over HTTPS, from the www.noteshred.com domain. All endpoints are versioned — the current version is v2 — and all data is sent and received as JSON.

https://www.noteshred.com/api/v2

Authentication

Every request needs your API key sent as an authorization token in the request header. Keep your API key secret — it identifies your application, and it will be disabled if we detect suspicious behaviour against it.

Authorization: Token token=<API key>

Example

curl https://www.noteshred.com/api/v2/notes
# 401: {"message":"Unauthorized"}

curl https://www.noteshred.com/api/v2/notes \
  -H "Authorization: Token token=[your api key]"
# 200: {"result":[{"token":"2529fa1262","title":"My super secret note..", ...}]}

Get your API key

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

The response

All responses are JSON. Errors and feedback arrive in the message field; any data returned by a query or write operation arrives in the result field.

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

Rate limiting

Each client (by IP) is allowed 400 requests per hour. If you need more, contact us.

Status codes

Responses follow RESTful HTTP standards. Successful requests return 200 or 201; request failures, validation failures, permission problems and bad request bodies return 500, 401 or 422.

Create

Creates a new note and triggers the email notification. Attachments are not available directly through the API.

POST /api/v2/notes

Parameters

• title — a short title for your note
• content — the note content
• password — the note password
• recipients — email address to notify about the note (optional)
• hint — a password hint included with emails (optional)
• shred_method — 1 = shred after reading, 2 = shred later
• time_period — only if shred_method is 2: hours, days or weeks
• from_now — only if shred_method is 2: number of hours, days or weeks

Example

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

Lists notes created by you and by other users on the same subscription.

GET /api/v2/notes

curl \
  --header "Authorization: Token token=[your api key]" \
  --request GET \
  https://www.noteshred.com/api/v2/notes

Show

Retrieves the properties of a note, without the encrypted content. The response is more extensive than the index entry and includes the note's activity timeline.

GET /api/v2/notes/<note_id>

curl \
  --header "Authorization: Token token=[your api key]" \
  --request GET \
  https://www.noteshred.com/api/v2/notes/fe13a241

Shred

Destroys all encrypted content but leaves the record, so anyone opening the link sees a "this has been shredded" message.

POST /api/v2/notes/<note_id>/shred

curl \
  --header "Authorization: Token token=[your api key]" \
  --request POST \
  https://www.noteshred.com/api/v2/notes/fe13a241/shred

Delete

Deletes a note completely. Anyone trying to access it afterwards gets a 404, or a "does_not_exist" exception through the API.

DELETE /api/v2/notes/<note_id>

Share

Sends an email notification with the note URL and a comment to a recipient — the same email as the "Send" button in the web application.

POST /api/v2/notes/<note_id>/share

Parameters

• recipients — the recipient's email address
• message — message included in the email to the recipient

Example

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 them needing a NoteShred account — like creating a blank note and asking someone else to fill it in. They open a password protected link and enter information which is encrypted and sent back to you as a regular note in your note list, readable with the password you defined.

POST /api/v2/note_requests

Parameters

• title — the note request title
• password — the note request password
• password_confirm — the password again, for confirmation
• message — a message describing the content you want
• recipients — the email address to send the request to

Example

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/note_requests