Astrid API Project

If you're a computer, and you want to talk to Astrid, you've come to the right place.

Current API Version: 7

Introduction

Astrid features an RPC interface for interfacing with the data stored on our servers. In computer-speak, you make a request like this:

POST https://astrid.com/api/7/task_list
Data: "token=12345"

And get some JSON back. XML is also supported by appending .xml to the POST URL (for example, https://astrid.com/api/7/task_list.xml).

Request Format

All requests must be sent via HTTP POST to a URL with the format:

https://astrid.com/api/<API Version>/<Method Name>

Both HTTP and HTTPS are supported, though we recommend use of HTTPS for the safety of your users.

In addition to parameters required by each method, the following POST parameters are required for every request:

app_id

API Key application id (see Getting an API Key)

time

Current time in seconds since epoch, UTC

sig

Request signature. To generate this signature:

Start with the API method (e.g. task_list)
Sort every parameter alphabetically by key first, then value
Concatenate keys and values (skip multi-part file parameters)
Append your API secret
Compute the MD5 digest

For example, for params:

/api/7/task_save?app_id=1&title=baz&tag[]=foo&tag[]=bar&time=1297216408

Your signature string would be

task_saveapp_id1tag[]bartag[]footime=1297216408titlebaz<API Secret>

Then, your request would look like this

/api/7/task_save?app_id=1&title=baz&tag[]=foo&tag[]=bar&time=1297216408&sig=<MD5 Hash>

Getting an API Key

If you got this far, then you may be asking yourself about how you can get your hands on an API key. An API Key is comprised of an application id and a secret token, and allows you to create requests for the Astrid server by providing the application id and signing your request as described above with your secret token.

Use the following link to register for an Astrid API key. Note that you must first have an account on Astrid.com.

Example - JS Library

To show you how to make requests against the Astrid server, we've written an example Astrid API library in coffeescript (a lovely language that compiles into Javascript).

It's not a complete implementation of the Astrid API, but it should at least get you started. It also works well as an actual library if you're writing an application in Javascript. In fact, Astrid's Page Clipper extension for Chrome and Firefox is built on top of api.js.coffee.

Astrid JS Library on Github

API Reference

Our API documentation is automatically generated at deploy time from our API source code.

API Reference

Notes:

Array parameters should be sent with the following format: key[]=value1&key[]=value2&key[]=value3.
Time parameters should be sent as seconds since epoch, UTC. If time should be unset (for example, task deleted_at or due dates), pass 0.
Boolean parameters can be transmitted as either (0, 1) or (false, true).

Throttling

Astrid will automatically throttle inbound requests from your API key. The default rate limit is 1,000 per ten minute interval. We will send an email about once per day if throttling occurs. When you sign up for an API key, you can enter a custom request limit. The Astrid team will then manually review your application limit and, if necessary, follow up via email.

If you need more requests... uh, talk to us? Seriously. At least prepare us for the awesome you're about to unleash on the world.

Support

Moved to tears? Have questions about what you're reading? Submit your epic poetry and support requests to support@astrid.com.

If that doesn't work out so well, maybe someone will make a mailing list or forum. Those things are so useful!

API Changes

Using an old version of the API? Here's what you've missed.

Version 7 (June 22, 2012)

This is the most current version of the API, and the first public preview. We welcome your comments and feedback as we work to make your lives as developers easier.