The Stikkit API

Welcome, fellow stikkiteer and developer, to the Stikkit API documentation. We've set this page up in a way that we hope will get you building your own applications, scripts, and utilities on top of our API as easy as possible.

Table of contents:

• Stikkit feeds
• Overview
• Community
• The Rules
• Authentication
• Request Structure
• Sample Responses
• Available Methods

Stikkit feeds

It's worth mentioning, before getting too deep into the API documentation, that Stikkit feeds are entirely driven by the API methods covered further on.

Getting feeds of your stikkits is as easy as calling any one of the following URLs

• http://www.stikkit.com/stikkits.atom
• http://www.stikkit.com/calendar.atom
• http://www.stikkit.com/todos.atom
• http://www.stikkit.com/peeps.atom
• http://www.stikkit.com/bookmarks.atom

There are a number of ways to modify what is returned in a feed, all of which are described as you read on.

Stikkit feeds and API calls support Basic HTTP Authentication as well as the traditional route of supplying an api key. You can read more about authentication here.

Overview

As much as we believe in how Stikkit "thinks" about your data, only you know how to best organize your notes so they work for you. The Stikkit API lets you "get at" your Stikkit data so you can shape it, direct it, and mash it up with other applications.

Our goal is to make the Stikkit API as simple and intuitive to use as Stikkit itself. To that end, the API mirrors Stikkit's structure and functionality. We've also decided to base the API solely on REST, as it's the easiest architecture to get up and running: you simply send HTTP requests to the Stikkit API methods you want to call, and the Stikkit API sends data back in the format of your choice.

While you can use any number of languages and tools to talk to the Stikkit API, our examples will focus on three popular choices: HTTP, curl and Ruby.

curl 'http://api.stikkit.com/stikkits.atom?api_key=xxx'

The Stikkit API knows how to return the following data formats. You can see samples of these responses by studying the sample responses section:

Note: You can request a particular data format by supplying an extension (for example, .atom, or .vcf) or by supplying an Accept: header. If you supply both, the Accept: header overrides the extension.

Response format restrictions

Each Stikkit API method returns data in a particular set of formats; they are:

Format	/stikkits	/calendar	/todos	/peeps	/bookmarks
Atom
vCard
iCal
json
Text

A few API methods won't return any data if the HTTP request response format isn't supported. For example, if you ask /calendar to respond with vCard data, you won't get anything back as a result, as calendar events aren't formatted as vCards.

This restriction applies to /stikkits as well. If you ask for your stikkits in vCard format, for example, and only four of your ten stikkits are peeps (contacts), only the peep stikkits will be returned as vCards.

back to the top

The rules

The Stikkit API is meant for non-commercial use by third-party developers and by and for Stikkit users. By using the Stikkit API, we are assuming you've read and agree to our terms of use and privacy policy. (We also provide a summary of your rights and obligations.)

Be good. Write good code. Help Stikkit help your fellow stikkiteers get more done and be happier for it.

back to the top

Community

You'll find fellow stikkiteers and developers on our Stikkit API forum. Drop by and hang out. Ask questions — or answer a few. Exchange ideas, share code, propose hacks or apps. And, of course, show off what you've built (we'd love to feature your work on our blog).

back to the top

Authenticate yourself

The Stikkit API doesn't maintain any state between connections, so with each request you must provide your authentication credentials. You can do so by using your API key or with basic HTTP authentication.

Using your API Key

The easiest way to let the Stikkit API know who you are is to tack on your API key as a query string parameter along with your request. Here's an example query string with the API key replaced with three x's:

http://api.stikkit.com/stikkits.atom?api_key=xxx

To get your API key, visit this page while logged into Stikkit (your unique API key will appear below), or visit your Stikkit account settings page.

IMPORTANT: Be sure to keep your API key private—you shouldn't share it with anyone or display it in example code.

Using basic HTTP authentication

To use basic HTTP authentication, just send the email address and Stikkit password combination you normally use to log in along with the request.

curl http://api.stikkit.com/stikkits.atom -u user@example.com:password

IMPORTANT: Be sure to keep the email address and Stikkit password combination you use to log in a secret; you shouldn't share them with anyone or display them in example code.

HTTP authentication also allows you to securely view your stikkits' feeds in newsreaders.

back to the top

Available Methods

Here's a handy link list to the available methods:

• Listing stikkits
• Determining a stikkit's ID
• Getting a stikkit
• Creating a stikkit
• Updating a stikkit
• Deleting a stikkit
• Listing comments
• Making comments
• Sharing stikkits
• Toggling todos
• Listing tags

Structuring Your HTTP Request

Each of the Stikkit API methods accepts HTTP requests that are structured as follows:

METHOD

The HTTP request method tells the Stikkit API what to do (whether it should get, create, update, or delete a stikkit or stikkits).

/stikkit_method

The Stikkit API method (the following table shows which HTTP request methods to use with each Stikkit API method).

.extension

An extension (atom, json, txt, etc) tells the Stikkit API how you'd like the response returned (only required if you're not passing in an Accept: header with a mime type).

mime type

A mime type forces each Stikkit API method call to respond with a particular data format. This overrides extensions (only necessary if you're not specifying a file extension).

The following table shows which API methods accept which HTTP request methods, with the resulting behaviors:

back to the top

Sample responses

Nearly every Stikkit API method can respond with one of the follow types of data. These are generalized a bit but should help you determine the structure of sample responses

Atom

Every Stikkit API call can return Atom formatted data. This sample shows two sample stikkits, each represented as "entries" within the feed.

<?xml version="1.0" encoding="UTF-8"?>
<feed xml:lang="en-US" xmlns="http://www.w3.org/2005/Atom">
  <title>stikkit: stikkits</title>
  <id>api.stikkit.com:/stikkits?api_key=85a4fd5ae3bf841c1d98fdc9d91c8039</id>
  <entry>
    <title>stikkit title</title>
    <summary>contents of the stikkit</summary>
    <content type="html">contents of the stikkit</content>
    <id>http://api.stikkit.com/stikkits/155157</id>
    <published>2007-02-02T04:06:41Z</published>
    <updated>2007-02-02T04:24:22Z</updated>
    <link href="http://api.stikkit.com/stikkits/[stikkit id]" rel="alternate" type="text/html"/>
  </entry>
</feed>

vCard

In theory, all Stikkit API methods can return vCard formatted information, but only if the Stikkit is returning peeps. For example, if you call /stikkits.vcf, you'll get vCard formatted data only if there is peep information available. Calling /calendar.vcf will always result in no vCard information being return, given that you can't exactly force an event's data into the vCard format.

BEGIN:VCARD
VERSION:3.0
N:Buffington;Michael;;;
FN:Michael Buffington
EMAIL:mike@valuesofn.com
TEL:+1 503-555-1111
TEL:+1 503-555-2222
ADR:;;1631 NE Broadway Ave;Portland;OR;;
END:VCARD

iCal

As explained in the vCard section above, all Stikkit API methods allow you to ask for iCal formatted data, but you'll only get vCard formatted data back for events. Calling /peeps.ics will return no data, while /calendar.ics will return your events formatted like so:

BEGIN:VCALENDAR
VERSION:2.0
METHOD:PUBLISH
PRODID:-//Values of n//NONSGML Stikkit//EN
BEGIN:VEVENT
DTSTART;TZID=America/Los_Angeles:20070303T160000
SUMMARY:meeting with marketing on march 3rd at 4pm
DESCRIPTION:meeting with marketing on march 3rd at 4pm
CATEGORIES:
URL:http://www.stikkit.com/stikkits/173902
CLASS:PRIVATE
CREATED:20070203T003105
LAST-MODIFIED:20070203T003105
SEQ:1
UID:http://www.stikkit.com/stikkits/173902
END:VEVENT
END:VCALENDARConnection closed by foreign host.

JSON

Every Stikkit API method supports returning data formatted as JSON:

[{"completed":0,"end_timezone":"","name":"Remember to pay water bill [sample stikkit]","updated":"2007-01-03T14:24:27Z","text":"Remember to pay water bill [sample stikkit]

This stikkit is a to-do. Stikkit knows this because it recognizes the magic word "remember." 
Other magic words Stikkit recognizes as to-dos are: todo:, remember, get, put, buy, find, and visit.

You can also specify a to-do item by prefacing it with a hyphen, like so: 

- pay water bill

To-dos show up in your Stikkit [To-do List](http://www.stikkit.com/todos); there you can filter and sort them, mark them as done or undone, even export them to iCal or Microsoft Outlook.

Find out more about Stikkit To-dos at:
* <http://community.valuesofn.com/stikkit/index.php/topic,82.0.html>
* <http://community.valuesofn.com/stikkit/index.php/topic,129.0.html>

*This is a sample stikkit to get you off to a good start. Read, fiddle, make any changes you like: this is your stikkit and only yours. And when you're quite through with it, feel free to throw it away (click the **save** or **cancel** button followed by the trash-can icon at the top-right of this stikkit note).*

*Much of what you're reading in this sample stikkit will make more sense if you click the edit pencil at the top-right and read the plain text of the note itself.*

tag as sample
","tags":["sample"],"created":"2007-01-03T14:24:27Z","url":"http://www.stikkit.com/todos)","id":89702,"start_timezone":"","end":null,"start":null}]

Text

Every Stikkit API method supports returning information in plain text form. Form feed characters (ascii character 12) separate each stikkit.

meeting with marketing on march 3rd at 4pm
[invisible form feed character]
- finish tree pruning this saturday

back to the top

Listing stikkits

There are five methods available to help you retrieve lists of stikkits, with the first behaving just slightly different than the last four. Let's look at each of the available methods and describe what they do. Each method can be supplied with any number of optional arguments to help narrow which stikkits you'd like to get back.

/stikkits

This method allows you to get and search for every kind of stikkit regardless of their type.

/calendar

This methods allows you to get upcoming calendar stikkits.

/todos

This method allows you to get your to-dos, both done and undone.

/peeps

This method allows you to get your peeps.

/bookmarks

This method allows you to get your bookmarks.

You can retrieve a list of your stikkits in batches of 25 at a time — very much like the Stikkit web site breaks up those long lists into pages. And in the same manner, you can "page" your way through those stikkits by passing Stikkit a page number in the form of a page argument. Leave page out or blank and you'll always see the latest 25; pass page=2 and you'll get stikkits 26-50.

The following examples all retrieve the first 25 stikkits, albeit the first 25 events, to-dos, peeps, or bookmarks, respectively. (And notice, too, that these examples all ask for their stikkits in Atom format.)

In addition to narrowing your list of stikkits by kind (events, to-dos, peeps, or bookmarks), you can narrow the results still further using a combination of these arguments:

name

Search for stikkits by name

text

Search the stikkit's text (including its name)

tags

Search a stikkit's tags.

created

Search by creation date (yyyy-mm-dd)

updated

Search by last updated date (yyyy-mm-dd)

kind

Search for a particular kind of stikkit (see table below for possible values)

page

As mentioned above, returns a specific page of results (by default, stikkits 1-25).

/stikkits

The following examples show how to ask for the first 25 stikkits without applying any sort of filtering:

curl 'http://api.stikkit.com/stikkits.atom?api_key=xxx'

The following examples show how to ask for the first 25 stikkits created on February 8th that are also tagged as "foo":

curl 'http://api.stikkit.com/stikkits.atom?tags=foo&created=2007-02-08&api_key=xxx'

/calendar

In addition to the optional arguments that all methods share, the calendar method allows for some specific arguments to help narrow down when events are occurring.

dates

Search for events for a specific day or time period, or events that start before or end after a specific day or time period. (yyyy-mm-dd, today, tomorrow, this+week, this+month, next+30+days)

done

Search events that are also todos by their done or undone status (1 for done, 0 for undone.)

The following examples get your first 25 upcoming events without any sort of filtering:

curl 'http://api.stikkit.com/calendar.atom?api_key=xxx'

The following examples narrow down events for this week by using the optional dates argument:

curl 'http://api.stikkit.com/calendar.atom?dates=this+week&api_key=xxx'

/todos

In addition to the optional arguments that all methods share, the todos method allows for some specific arguments to help narrow down what todos are done, and when they're due.

dates

Search for todos for a specific day or time period, or events that start before or end after a specific day or time period. (yyyy-mm-dd, today, tomorrow, this+week, this+month, next+30+days)

done

Search todos by their done or undone status (1 for done, 0 for undone.)

The following examples get your first 25 todos, whether they're done or undone:

curl 'http://api.stikkit.com/todos.atom?api_key=xxx'

The following examples get the first 25 undone todos for today:

curl 'http://api.stikkit.com/todos.atom?done=0&dates=today&api_key=xxx'

/peeps

In addition to the optional arguments that all methods share, the peeps method allows for an additional argument to make retrieval of peeps by the letter of their first name.

letter

Search for peeps starting with a specific letter (a-z)

The following examples shows how to get the first 25 of your peeps without any filtering:

curl 'http://api.stikkit.com/peeps.atom?api_key=xxx'

The following examples show how to get the first 25 of your peeps starting with the letter D:

curl 'http://api.stikkit.com/peeps.atom?letter=D&api_key=xxx'

/bookmarks

The following examples show how to get a list of your first 25 bookmarks:

curl 'http://api.stikkit.com/bookmarks.atom?api_key=xxx'

Stikkit kinds

In addition to having dedicated methods for specific kinds of stikkits, you can have fine control over exactly what kinds of stikkits you want to get back by passing the kind argument to the /stikkits method. Your app might need to get back all to-dos that are also bookmarks and peeps at the same time, and passing a kind value will allows you that control.

Getting a mix of kinds back in a single call is as easy as adding up each kind's bitfield value. So, to get stikkits that are to-dos, bookmarks, and peeps at the same, you'd add each value together. In this case, that'd be 128+1+32, or 161. Getting just events and bookmarks would be 2+1, or 3.

Here's a list of the kinds and their bitfield values:

• Events - 2
• To-dos - 128
• Peeps - 32
• Bookmarks - 1

The following examples show how to get the first 25 stikkits that are to-dos, bookmarks, and peeps:

curl 'http://api.stikkit.com/stikkits.atom?kind=161&api_key=xxx'

back to the top

Determining a stikkit's ID

Before you can get, update, delete, or find the comments for a particular stikkit, you first need to determine its ID. Most of the formats include the ID in some form: it's easy to find if you know where to look.

This table lists each of the Stikkit API's data formats, along with where in their output you'll find the stikkit's ID (notice the id in each).

Note: Not every data format includes stikkit IDs (i.e. vCard, text); you'll need to grab a list of stikkits in another data format to glean the IDs you need.

Getting a stikkit

/stikkits/n

You can retrieve a single stikkit by supplying its id as part of the request URL, as well as get a specific response format (in this case as Atom) like so:

curl 'http://api.stikkit.com/stikkits/1.atom?api_key=xxx'

Creating a stikkit

/stikkits

You can create a stikkit by simply posting a single text string, exactly as if you were typing in the textarea inside the Stikkit web application. Stikkit parses the text and interprets it just as it does in real time in the web application.

curl -d 'raw_text=foo&api_key=xxx' http://api.stikkit.com/stikkits.atom

back to the top

Updating a stikkit

/stikkits/n

To update an existing stikkit, make a PUT request and supply the text you want to replace the contents of the current stikkit. The Stikkit API will return the updated stikkit, along with the stikkit kind and other information gleaned by parsing the text.

Keep in mind that not all clients and/or languages support the PUT HTTP request method. Adding the parameter _method=put will force the server to assume a POST is actually the same as a PUT. Here's an HTTP example using PUT:

And here is an HTTP example using _method=put:

Curl and Ruby both allow an explicit PUT request:

curl -X PUT -F 'raw_text=foo' -F 'api_key=xxx' \ http://api.stikkit.com/stikkits/1.atom

back to the top

Deleting a stikkit

/stikkits/n

To delete a stikkit, make a DELETE request and provide the stikkit's id.

Keep in mind that not all clients and/or languages support the DELETE HTTP request method. Adding the parameter _method=delete will force the server to assume a POST is actually the same as a DELETE. Here's an HTTP example using DELETE:

And here is an HTTP example using _method=delete:

Curl and Ruby both allow an explicit DELETE request:

curl -X DELETE 'http://api.stikkit.com/stikkits/1.atom?api_key=xxx'

back to the top

Listing comments

/stikkits/n/comments

The following request returns a list of a particular stikkit's comments.

curl 'http://api.stikkit.com/stikkits/1/comments.atom?api_key=xxx'

back to the top

Making a comment

/stikkits/n/comments

Use a POST request to add a new comment to a particular stikkit.

curl -F 'api_key=xxx' -F 'comment=Blah' \ http://api.stikkit.com/stikkits/1/comments.atom

back to the top

Sharing a stikkit

/stikkits/n/share

Make a POST request as follows to share a stikkit.

curl -F 'api_key=xxx' -F 'share_with=other@example.com' \ http://api.stikkit.com/stikkits/1/share.atom

back to the top

Unsharing a stikkit

/stikkits/1/unshare

Use a POST request to unshare a stikkit, as follows.

curl -F 'api_key=xxx' -F 'unshare=other@example.com' \ http://api.stikkit.com/stikkits/1/unshare.atom

back to the top

Toggling a todo

/todos/1;toggle

The following PUT request toggles the specified todo as done or undone.

curl -X PUT -F 'api_key=xxx' 'http://api.stikkit.com/todos/1.atom;toggle'

back to the top

Listing tags

/tags

The following request returns all the tags you've used.

curl 'http://api.stikkit.com/tags.atom?api_key=xxx'

back to the top