Version 0.1

API Documentation

The endpoint for all API requests is https://api.deftask.com. The path for a resource on deftask.com is the same on api.deftask.com. So, for example,

  • api.deftask.com/users/1?v=0.1 returns the user with id=1
  • api.deftask.com/projects/1/tasks/1?v=0.1 returns task #1 under the project with id=1

Note the presence of the query parameter v=$version in the above URLs. This param is required for API calls.1

Without this parameter, a request will instead return documentation for the latest API version of the given resource. That is,

  • api.deftask.com/projects will return documentation at the latest API version for /projects, which returns a list of projects the user has access to.
  • api.deftask.com/users/<anything> will return documentation for /users/:user-id.

To request documentation for an older API version, use v=$version&show=doc. For example,

  • api.deftask.com/projects?v=0.1&show=doc will return documentation for /projects at API version 0.1.

Authentication

deftask uses access tokens for API authentication. The following sections explain how to generate and use them.

Generating access tokens

To generate an access token, go to https://deftask.com/settings/tokens.

Click on New Token, provide a description (for easy recall later on) and click on Create. Make sure you copy the generated token because it won't be displayed again.

You can delete an access token at any point of time.

Using access tokens

There are two ways to authenticate a request using an access token. Both require you to use the Authorization HTTP header.

  1. Use the Bearer auth scheme followed by the access token

    Authorization: Bearer $access_token

  2. Use HTTP Basic authentication. Provide bearer as the username and the access token as the password. The advantage of using basic authentication is that you can easily test out a GET request in the browser -- just enter the URL and the browser will prompt you for the username and password.

Notes

  1. for POST requests which send a multipart or url encoded form, you can also send the v=$version param in the body instead.