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:

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.

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.

Resources using the Sifter API

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

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.