Overview

This API is accessed using normal HTTP requests with parameters passed as a query string, both POST and GET will work. All responses are in XML format encoded with UTF-8.

Authentication

Only notebooks protected with a password can be accessed through this API.

The authentication method is basic HTTP-Auth, where the username is the email address associated with the notebook being accessed.

The notebook to access is specified by adding it to the end of the URL, i.e. api.pen.ly/apidemo

Mandatory parameters

Name	Type	Description
function	string	Name of the function to call. See what functions are available below.
version	int	The version of the function to call.

Available functions

get-preview-of-all-notes

Fetch a list of all notes in your workspace. The response will be in a more compact format, leaving out some data, and the note contents is truncated to maximum 30 chars. Useful in for example mobile apps where bandwidth is an issue, and where all notes probably do not need to be downloaded all at once.

Parameters

Name	Type	Description
function	string	Set to "get-preview-of-all-notes".
version	int	Set to 1.
workspace	int	ID of the workspace the notes are at, between 1 and 9. Currently there can only be one workspace. This will change in the future. Optional. Defaults to 1.
oldest-first	bool	If set to false the most recent updated notes will be returned first. Useful for determining what depth to stack notes at. Optional. Defaults to true.

Response


		<notes_preview>

		<note_preview id="35"

		              x="289"

		              y="69"

		              width="172"

		              height="61"

		              rgb="caffff"

		              contents="Demo of the pen.ly API."/>

		...

		<note_preview id="... />

		</notes_preview>

id	int	Unique ID of the note.
x, y, width, height	int	Location and dimensions of the note as seen on the web front-end. Other applications may scale accordingly.
rgb	string	Background color of note.
contents	string	Contents of the note truncated to 30 characters.

get-all-notes

Fetch a complete list of all notes in the specified workspace. Full data for each note is returned. This may result in big chunks of data so use with care. Also be advised that this function is subject to throttling.

Parameters

Name	Type	Description
function	string	Set to "get-preview-of-all-notes".
version	int	Set to 1.
workspace	int	ID of the workspace the notes are at, between 1 and 9. Currently there can only be one workspace. This will change in the future. Optional. Defaults to 1.
oldest-first	bool	If set to false the most recent updated notes will be returned first. Useful for determining what depth to stack notes at. Optional. Defaults to true.

Response

See the example session below. The response will contain multiple note-elements.

get-note

Fetch the complete data of a single note including its dimensions and other properties.

Parameters

Name	Type	Description
function	string	Set to "get-note".
version	int	Set to 1.
note_id	int	ID of the note you want to retrieve.

Response

See the example session below. The note-element will contain the same data.

Example request and response

$ curl -i "http://apidemo%40dummy.domain:apidemo@api.pen.ly/ \ apidemo?function=get-note&version=1¬e_id=35" HTTP/1.1 200 OK Date: Wed, 17 Jun 2009 00:09:43 GMT Server: Apache Cache-Control: no-cache Vary: Accept-Encoding Content-Length: 494 Content-Type: text/xml;charset=utf-8 <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <notes> <note id="35" revision="45" workspace="1"> <position x="289" y="69"/> <size width="172" height="61"/> <decoration rgb="caffff"/> <permalink type="web">[http-link]</permalink> <created>2009-06-17T02:03:03+0200</created> <updated>2009-06-17T02:03:03+0200</updated> <edited>2009-06-17T02:03:03+0200</edited> <contents><![CDATA[Demo of the pen.ly API.]]></contents> </note> </notes>

Name	Type	Description
revision	int	The revision of this note. Every time a note is saved or modified it gets a new revision.
permalink	string	http://pen.ly/apidemo/ac2cd1e6c190e41c9145c6d8c153c32dfd48f820
created updated edited	date	ISO-8601. Wikipedia.
content	string	Full contents of the note.