• Getting Started
• Documentation
• Libraries and Integrations
• Have questions or feedback?

Getting Started

Getting an Access Key

1. Sign into your account
2. Click the “My Profile” link along the top of the page
3. Click the “Access Keys” link in the right sidebar of the page
4. Fill in the “Create New Access Key” form at the bottom of the page and click “Create Access Key”
5. Note value for your new key

Making requests

Fetching data via the Sifter API involves passing your access key as an HTTP header and providing an appropriate Accepts header. Sifter uses the X-Sifter-Token header to look up the access key that grants access to the data in your account. Additionally, you should specify the MIME type you wish the response encoded with. Currently, only JSON is supported, and all API requests must use SSL.

A properly formatted request, using curl looks like this:

curl -H 'X-Sifter-Token: 343b1b831066a40e308e0af92e0f06f0' \
       -H 'Accept: application/json' \
       'https://example.sifterapp.com/api/projects'

A Word on ID’s

If you look at a response, you may notice that we don’t explicitly include ID’s as a field. You might ask, “How am I supposed to construct URL’s then?” The simple answer is that you shouldn’t ever need to build URL’s manually.

We explicitly include all of the relevant and available resource endpoints in the response. So you can simply follow those URL’s and you won’t ever need to build URL’s yourself.

By taking this approach, we’re future-proofing our resources and giving ourselves some flexibility with regards to changing URL’s as the application grows and adapts.

{
  "projects": [
    {
      "name": "Elephant",
      "primary_company_name": "Apple",
      "archived": false,
      "url": "https://example.sifterapp.com/projects/1",
      "issues_url": "https://example.sifterapp.com/projects/1/issues",
      "milestones_url": "https://example.sifterapp.com/projects/1/milestones",
      "api_url": "https://example.sifterapp.com/api/projects/1",
      "api_issues_url": "https://example.sifterapp.com/api/projects/1/issues",
      "api_milestones_url": "https://example.sifterapp.com/api/projects/1/milestones",
      "api_categories_url": "https://example.sifterapp.com/api/projects/1/categories",
      "api_people_url": "https://example.sifterapp.com/api/projects/1/people"
    },
    {
      "name": "Zebra",
      "primary_company_name": "Google",
      "archived": true,
      "url": "https://example.sifterapp.com/projects/1",
      "issues_url": "https://example.sifterapp.com/projects/2/issues",
      "milestones_url": "https://example.sifterapp.com/projects/2/milestones",
      "api_url": "https://example.sifterapp.com/api/projects/2",
      "api_issues_url": "https://example.sifterapp.com/api/projects/2/issues",
      "api_milestones_url": "https://example.sifterapp.com/api/projects/2/milestones",
      "api_categories_url": "https://example.sifterapp.com/api/projects/2/categories",
      "api_people_url": "https://example.sifterapp.com/api/projects/2/people"
    }
  ]
}

Dealing with errors

The Sifter API can return a handful of error codes you’ll want to handle in your client:

• 403 Forbidden: this means you have requested a project, issue, or other data that is not accessible to the user your API token is associated with.
• 404 Not Found: this means you have requested a non-existent resource. If you’re properly traversing URLs returned by the API, you shouldn’t see this happen.
• 406 Not Acceptable: this means you have requested a response format (e.g. XML, YAML, CSV) that the Sifter API doesn’t support.
• 429 Too many requests: this means you have exceeded the 60 requests per minute quota assigned to Sifter API tokens. The API will set the Retry-After header (e.g. Retry-After: 60) to the number of seconds your application should wait before making another request.
• 500 Server Error: this means something went wrong on our end. This is due to a mistake on our part or a temporary infrastructure issue.

If you observe an extended period of 500 errors or are getting 4xx errors when you wouldn’t expect to, contact support with an example request you’re sending and the response from Sifter. cURL examples help a lot!

Documentation

The following resources are currently available for read-only access via the API. Write-access is in the works, but we can’t offer an estimate of when it will be ready.

• Projects
  • Listing
  • Detail
  • Milestones
  • Categories
  • People
• Issues
  • Listing
  • Detail
  • Create
• Comments
  • Create
• Statuses
• Priorities

Libraries and Integrations

Client Access Libraries

There are client libraries available for accessing the Sifter API. If you have built a client library and would like to share it, let us know so that we can add it to the list.

• Ruby (Official)
• .Net (Unofficial)
• Python (Unofficial)
• Node.js (Unofficial)
• Java (Unofficial)
• Powershell (Unofficial)

Resources using the Sifter API

We’ll keep a list of available 3rd party tools that use the API here.

• SifterClient for Android
• TurtleSift plugin for Sifter and TortoiseSVN
• Siftboard plugin for integrating with Panic’s Status Board

Integrations

To help make it easier to integrate with your other tools, Sifter offers several pre-built integrations with tools like Beanstalk, GitHub, Zapier, and more.

More about integrations…

Have questions or feedback?

If you have any questions or suggestions, we’re all ears. Just reach out via whichever method works best for you.

• Send us an email
• Share with the Google group
• Reach out to our API Twitter account @sifterapi