API Developer's Guide

We have a REST-based API available for developers who want to write their own programs based on the npad platform. We know you guys will come up with more interesting stuff than we will, so we've opened up the system as much as possible. If you make something cool, or want to see some additional functionality, please write to us and let us know!

Table of Contents

1. Overview
2. Errors
3. Authentication
4. Adding notes
5. Getting one note
6. Getting multiple notes
7. Modifying (and deleting) notes
8. Adding tags
9. Modifying (and deleting) tags
10. Applying tags
11. Removing tags
12. Getting tags

Overview

The npad API is based on a very simple REST model. You send us variables in the form of a POST request and we send back a JSON string.

Each method has its own URL. For example, the URL for adding notes is http://www.npad.com/services/addnote/

All request parameters are lowerCamelCased and all response parameters are UpperCamelCased. Why? Because.

Errors

Every response contains a "Result" parameter, either 1 or 0, which allows you to easily test whether the call was successful or not. In addition, if the "Result" is 0, there also be two other elements, "ErrorCode" and "ErrorMessage". Your application can rely on error codes not to change, but the error message is mostly just a friendly piece of text to help you during development.

Authentication

Authentication works using secure tokens that are tied to an account. In order to make most API calls, you'll need a valid token, which you can get from this service. After you get a token, it is valid for 90 days. A user can have multiple tokens simultaneously to allow multiple, separate applications to operate independently.

Remember that npad auth tokens should always be stored securely and treated like passwords.

http://www.npad.com/services/auth/

Request
email	string	Required. The email address of the account.
passhash	string	Required. An MD5 hash of the user's password.

Response
Token	string	The unique authentication token .
Result	int	1 or 0 for success or failure, respectively.

Back to Table of Contents

Adding Notes

Use this service to add a new note to the account represented by 'token'.

http://www.npad.com/services/addnote/

Request
token	string	Required. The auth token.
noteText	string	Required. The text of the note to add.

Response
NoteID	int	The ID of the new note.
Result	int	1 or 0 for success or failure, respectively.

Back to Table of Contents

Getting One Note

Use this service to retrieve a single note based on its ID (you get gets IDs from the getnotes service).

http://www.npad.com/services/getnote/

Request
token	string	Required. The auth token.
noteID	int	Required. The ID of the note to retrieve.

Response
Note	obj
	NoteID	int	The ID of the note returned
	CreatedOn	int	The date the note was created, in unix timestamp format
	EditedOn	int	The date the note was last edited, in unix timestamp format
	NoteText	string	The text of the note
	Status	string	Whether the note is "Active", "Filed", or "Trash"
	IsStruck	int	0 or 1, depending on whether or not the note is crossed out. 1 means crossed out.
Result	int		1 or 0 for success or failure, respectively.

Back to Table of Contents

Getting Multiple Notes

Use this service to get all or a subset of the user's notes. There is a maximum of 1,000 notes returned per call, so if the difference between offsetStart and offsetEnd is greater than 1,000, you will only get the first 1,000 back.

http://www.npad.com/services/getnotes/

Request
token	string	Required. The auth token.
status	string	Required. The status of the notes you want to get back ("Active", "Filed", "Trash").
offsetStart	int	Optional. Along with offsetEnd, lets you specify a subset of the user's notes to retrieve. If omitted, this will be interpreted as 0.
offsetEnd	int	Optional. Along with offsetStart, lets you specify a subset of the user's notes to retrieve. If omitted, this will be interpreted as every note from offsetStart to the end.

Response
Notes	list	An array of Note objects. Each object has the following properties:
	NoteID	int	The ID of the note
	CreatedOn	int	The date the note was created, in unix timestamp format
	EditedOn	int	The date the note was last edited, in unix timestamp format
	NoteText	string	The text of the note
	Status	string	Whether the note is "Active", "Filed", or "Trash"
	IsStruck	int	0 or 1, depending on whether or not the note is crossed out. 1 means crossed out.
Total	int	The total notes with the given status, regardless of offsets
Result	int	1 or 0 for success or failure, respectively.

Back to Table of Contents

Modifying Notes

This service allows you to modify a note's status (i.e. move it to the trash or file it), modify its text, and cross it out. You can also delete notes by setting their status to "Deleted".

http://www.npad.com/services/updatenote/

Request
token	string	Required. The auth token.
noteID	int	Required. The ID of the note to modify.
noteText	string	Optional. The new text for the note.
status	string	Optional. Whether the note is "Active", "Filed", or "Trash". You can also set the status to "Deleted" in order to delete the note forever. Deleting a note cannot be undone.
isStruck	int	Optional. 1 if the note is crossed out, 0 if it isn't.

Response
Result	int	1 or 0 for success or failure, respectively.

Back to Table of Contents

Adding Tags

This service allows you to add new tags to the account associated with the token.

http://www.npad.com/services/addtag/

Request
token	string	Required. The auth token.
tagText	string	Required. The text of the new tag.

Response
TagID	int	The ID of the new tag.
Result	int	1 or 0 for success or failure, respectively.

Back to Table of Contents

Modifying Tags

This service allows you to modify and delete tags.

http://www.npad.com/services/updatetag/

Request
token	string	Required. The auth token.
tagText	string	Optional. The new text of the tag.
status	string	Optional. Set to "Deleted" to delete this tag. Deleting a tag cannot be undone.
tagID	int	Required. The ID of the tag to be updated.

Response
Result	int	1 or 0 for success or failure, respectively.

Back to Table of Contents

Applying Tags

This service allows you to apply an existing tag to an existing note.

http://www.npad.com/services/applytag/

Request
token	string	Required. The auth token.
tagID	int	Required. The ID of the tag to apply.
noteID	int	Required. The ID of the note to be tagged.

Response
Result	int	1 or 0 for success or failure, respectively.

Back to Table of Contents

Removing Tags

This service allows you to remove a tag from a note.

http://www.npad.com/services/removetag/

Request
token	string	Required. The auth token.
tagID	int	Required. The ID of the tag to remove.
noteID	int	Required. The ID of the note to be detagged.

Response
Result	int	1 or 0 for success or failure, respectively.

Back to Table of Contents

Getting Tags

This service allows you to get all tags belonging to a user or all tags applid to a certain note.

http://www.npad.com/services/gettags/

Request
token	string	Required. The auth token.
noteID	int	Optional. The ID of the note for which the tags should be returned. If this parameter is not present, all of the user's tags will be returned.

Response
Tags	list	An array of tag objects.
	TagID	int	The ID of the tag.
	TagText	string	The text of the tag.
Result	int	1 or 0 for success or failure, respectively.

Back to Table of Contents