API documentation

Overview

Weekdone API is RESTful interface, providing access to most of the data in the system. The API accepts form-encoded content and query parameters in requests and all responses are encoded in JSON, including errors. UTF-8 is the only character encoding supported for both requests and responses.

Authentication

All API requests must contain way to authenticate the user and authorize access to requested data. Weekdone API supports OAuth 2.0 Authentication mechanism. A web application with a user's authorization key, may access information and make changes to data stored in Weekdone as if it were that user.

OAuth 2.0

Weekdone API supports only Authorization Code Grant flow of the OAuth 2.0 framework. This is the most common strategy for traditional web applications and native desktop/mobile apps.

Registering your application

Before starting to implement the Weekdone API a new app must be registered with Weekdone to receive Client ID and Client Secret. This can be done from Applications page. All applications added by a client are visible to all admin level accounts of that client.

As with all OAuth apps, you must supply an Application URL as well as a Redirect URL that successful (or failed) authentications will redirect to.

Requesting authorization from the user

Developers should use button with the text "Sign in with Weekdone" when redirecting users to Weekdone to start authorization flow.

To start the authorization flow users must be redirected to https://weekdone.com/oauth_authorize passing parameters in query string.

Name	Required	Description
`client_id`	yes	The Client ID uniquely identifies the application making the request.
`redirect_uri`	yes	The URI to redirect to on success or error. This must match the Redirect URL specified in the application settings.
`response_type`	yes	Must be 'code' (as other authorization flows are not supported).
`state`	no	Encodes state of the app, which will be returned verbatim in the response and can be used to match the response up to a given request.

If either the client_id or redirect_uri do not match, the user will simply see a plain-text error. Otherwise, all errors will be sent back to the redirect_uri specified.

The user then sees a screen giving them the opportunity to accept or reject the request for authorization. In either case, the user will be redirected back to the redirect_uri.

Response back to application

User will be redirected back to redirect_uri with following parameters in the query string on successful authorization:

Name	Description
`code`	This is the code your app can exchange for a token
`state`	The state parameter that was sent with the authorizing request

Token exchange

If user granted access to the application the code received by application must be exchanged for proper access token. The app must make POST request to https://weekdone.com/oauth_token passing following parameters in form-encoded post body:

Name	Required	Description
`code`	yes	The code you are exchanging for an auth token
`grant_type`	yes	Must be `authorization_code`
`client_id`	yes	The Client ID uniquely identifies the application making the request.
`client_secret`	yes	The Client Secret belonging to the app, found in application details
`redirect_uri`	yes	Must match the redirect_uri specified in the original request

Token exchange response

In the response, you will receive a JSON payload with the following parameters:

Name	Description
`access_token`	The token to use in future requests against the API
`refresh_token`	If exchanging a code, a long-lived token that can be used to get new access tokens when old ones expire.
`user`	A JSON object encoding a few key fields about the logged-in user

Requesting new access token with refresh token

access_token will expire and new tokens must be requested using refresh_token. To request new access token the app must make POST request to https://weekdone.com/oauth_token passing following parameters in form-encoded post body:

Name	Required	Description
`refresh_token`	yes	The refresh_token
`grant_type`	yes	Must be `refresh_token`
`client_id`	yes	The Client ID uniquely identifies the application making the request.
`client_secret`	yes	The Client Secret belonging to the app, found in application details
`redirect_uri`	yes	Must match the redirect_uri specified in the original request

Response will be the new access_token

Tips to get you started

There are several OAuth libraries to get you started

We have Zapier integration available if you are already using Zapier

Items

Items are what reports are made of. Each item may belong to one or several reports and evey item has following parameters:

Name	Type	Description
`id`	number	Uniquely identifies each item
`inserted`	datetime	When the item was added to Weekdone
`description`	string	The textual description of the item
`type_id`	number	In which report category the item belongs to: `0 = Plans on Hold 1 = Progress 2 = Plans 3 = Problems 4... = Custom types`
`user_id`	number	ID of user who added the task or to whom the task was assigned
`team_id`	number	ID of the team where item was added
`source`	number	Source of the item `0 = Weekdone 1 = JIRA 2 = Asana 3 = Basecamp 4 = GoogleTasks 5 = Slack`
`source_id`	string	ID of the item in external system. Maximum length is 50 characters
`priority`	number	`0 = not specified 1 = green 2 = amber 3 = red`
`commentcount`	number	Number of comments
`likecount`	number	Number of likes
`from_id`	number	Who assigned this item
`due_on`	date	When the item is due
`private`	number	Who can see the item 0 - public: item has team permissions 1 - private: item is only visible to owner

Each report in Weekdone is identified by it's number. The number is in form YYYYWW where YYYY is the year and WW is the week number.

Name Type URL Sample response:

Search for items

GET

https://api.weekdone.com/1/items?token=<OAuth Token>

{
  "status": "ok",
  "items": [
    {
      "id": 690,
      "inserted": "2013-03-28T13:37:54Z",
      "description": "item is here",
      "likecount": 0,
      "commentcount": 0,
      "type_id": 2,
      "team_id": 3,
      "user_id": 12,
      "priority": 1,
      "from_id": 144,
      "source": 0,
      "due_on": "2014-02-02"
    }
  ]
}

Search parameters
Name	Description
`user_id`	Search by user ID. Special alias 'me' can be used instead of currently authenticated users ID.
`team_id`	Search by team ID
`period`	Search by week number. Defaults to current week

Create item

POST

https://api.weekdone.com/1/item?token=<OAuth Token>

Supported fields:
Name	Required	Description
`description`	yes
`type_id`	yes
`period`	no	Week where to add the item, defaults to current week
`user_id`	no	defaults to OAuth token owner
`team_id`	no	defaults to OAuth token owner primary team ID
`priority`	no
`source_id`	no	ID of the item in external system
`due_on`	no
`private`	no	defaults to 0 (public)

Update item

PUT

https://api.weekdone.com/1/item/<item ID>?token=<OAuth Token>

Supported fields:
Name	Description
`description`
`type_id`	Move item to different category
`period`	Required when updating type_id
`priority`
`due_on`

Assign item to another user

PUT

https://api.weekdone.com/1/item/<item ID>/assign?token=<OAuth Token>

Supported fields:
Name	Required
`user_id`	yes

Delete item DELETE https://api.weekdone.com/1/item/<item ID>?token=<OAuth Token>

Get item likes

GET

https://api.weekdone.com/1/item/<item ID>/likes?token=<OAuth Token>

Sample result

{
  "status": "ok",
  "likes": [
    {
      "id": 1360,
      "name": "John Doe"
    }
  ]
}

Add item like POST https://api.weekdone.com/1/item/<item ID>/likes?token=<OAuth Token>

Delete item like DELETE https://api.weekdone.com/1/item/<item ID>/likes?token=<OAuth Token>

Sort items

PUT

https://api.weekdone.com/1/item/<item ID>/sort?token=<OAuth Token>

Supported fields:
Name	Required
`type_id`	yes
`list`	yes	Comma separated list of item ID's in this category
`period`	yes	Which week to sort

Get item comments

GET

https://api.weekdone.com/1/item/<item ID>/comments?token=<OAuth Token>

Sample result

{
  "status": "ok",
  "comments": [
    {
      "id": 1360,
      "inserted": "2014-02-28T13:37:54Z",
      "comment": "this is item comment",
      "user_id": 12
    }
  ]
}

Add item comment

POST

https://api.weekdone.com/1/item/<item ID>/comments?token=<OAuth Token>

Supported fields:
Name	Required
`comment`	yes

Delete item comment DELETE https://api.weekdone.com/1/item/<item ID>/comments/<comment ID>?token=<OAuth Token>

Report

Get weekly report data grouped by teams. See Items and Users for list of parameters

Each report in Weekdone is identified by it's number. The number is in form YYYYWW where YYYY is the year and WW is the week number. Defaults to current week.

Name Type URL Sample response:

Get report

GET

https://api.weekdone.com/1/report?token=<OAuth Token>

{
  "status": "ok",
  "period": "201504",
  "report": [
    {
      "id": 1,
      "name": "Default Team",
      "users": [
        {
          "id": 1,
          "name": "User name",
          "items": [],
          "rate": null,
          "reviews": []
        },
        {
          "id": 2,
          "name": "Second Testuser",
          "items": [],
          "rate": 5,
          "reviews": []
        }
      ]
    }
  ]
}

Search parameters
Name	Description
`user_id`	Search by user ID. Special alias 'me' can be used instead of currently authenticated users ID.
`team_id`	Search by team ID
`period`	Search by week number. Defaults to current week

Teams

Each company account on Weekdone has one or move teams, which have following parameters:

Name	Type	Description
`id`	number	Uniquely identifies each team
`name`	string
`privacy`	number	Who may see team reports `1 = everybody in the company 1 = team members 2 = team manager only`
`external_reports`	string	Additional addresses to whom team reports are sent
Following fields exist when each team uses it's own template
`rate_question`	string	Question for rating week with 5 stars
`reportsdue_day`	number	Weekday when the report will be sent
`reportsdue_hour`	number	Time of day when the report will be sent
`reportreminder_day`	number	Weekday when the report reminders will be sent
`reportreminder_hour`	number	Time of day when the report reminders will be sent
`timezone`	string	Timezone of the team. Used to calculate reportsdue and reportreminder values

Name	Type	URL	Sample response:
Get all teams	`GET`	`https://api.weekdone.com/1/teams?token=<OAuth Token>`	`{ "status": "ok", "teams": [ { "id": 3, "name": "Arendustiim", "privacy": 3, "external_reports": "external@example.com" } ] }`

Users

User object has following fields

Name	Type	Description
`id`	number	Uniquely identifies each user
`inserted`	datetime	When the item was created
`admin`	number	Whether this is company level admin
`team_id`	number	User's primary team
`teams`	array	All teams user belongs to. Each user has two parameters in each team: observer and admin

Name Type URL Description

Name	Type	URL	Description
Get all users	`GET`	`https://api.weekdone.com/1/users?token=<OAuth Token>`	Example: `{ "status": "ok", "users": [ { "id": 1, "name": "Test User", "picture": "http://weekdone.com/favicon2.php?i=T", "admin": 0, "team_id": 1, "teams": [ { "id": 1, "name": "Testing Team", "observer": 0, "admin": 0 } ] } ] }`

Get all users

GET

https://api.weekdone.com/1/users?token=<OAuth Token>

Example:

{
  "status": "ok",
  "users": [
    {
      "id": 1,
      "name": "Test User",
      "picture": "http://weekdone.com/favicon2.php?i=T",
      "admin": 0,
      "team_id": 1,
      "teams": [
        {
          "id": 1,
          "name": "Testing Team",
          "observer": 0,
          "admin": 0
         }
      ]
    }
  ]
}

Types

Reports are divided into types. When all teams in company use different templates, then team_id will be present. Types may have following fields:

Name	Type	Description
`id`	number	ID of the type. There are three pre-defined types which all reports have: `1 = Progress 2 = Plans 3 = Problems` There is one special type with ID=0 - this is carryover category for 'Plans' (ID=2). Items cannot be added there.
`name`	string	Name of the type
`carryover`	boolean	Whether items in this category will carry over to next week
`overdue`	boolean	When items carry over to next week, whether to count items as overdue when they have been carried over more than twice

Name Type URL Description

Name	Type	URL	Description
Get all types	`GET`	`https://api.weekdone.com/1/types?token=<OAuth Token>`	Example: `{ "status": "ok", "same_template": false, "types": [ { "id": 0, "team_id": 1, "name": "In progress" }, { "id": 1, "team_id": 1, "name": "Progress" }, { "id": 103, "team_id": 1, "name": "Custom item type", "carryover": true, "overdue": false } ] }`

Get all types

GET

https://api.weekdone.com/1/types?token=<OAuth Token>

Example:

{
  "status": "ok",
  "same_template": false,
  "types": [
    {
      "id": 0,
      "team_id": 1,
      "name": "In progress"
    },
    {
      "id": 1,
      "team_id": 1,
      "name": "Progress"
    },
    {
      "id": 103,
      "team_id": 1,
      "name": "Custom item type",
      "carryover": true,
      "overdue": false
    }
  ]
}

Objectives

There are four level of Objectives: Company, Department, Team and Personal. All Objectives have almost same columns with following exceptions

Department Objective has department_id
Team Objective has team_id
Personal Objective has team_id and user_id

"progress" field of Objectives is calculated based on Key Results "progress" and therefore cannot be updated directly.

Name	Type	Description
`id`	number	ID of the Objective
`type`	string	Type of Objective (company, department, team, user)
`description`	string	Description of the Objective
`period`	string	Quarter of the Objective in form YYYYQ
`comments`	number	Number of comments
`progress`	number	Percentage of Objective completion
`results`	array	List of Key Results
`parent_list`	array	List of parent Objectives

Key Results

Name	Type	Description
`id`	number	ID of the Key Result
`result`	string	Key Result description
`inserted`	datetime	Key Result creation time
`type`	string	Type of Key Result (default %)
`startval`	number	Key Result minumum value
`maxval`	number	Key Result maximum value
`weight`	number	Key Result weight -4...+4
`progress`	number	Key Result progress
`updated`	datetime	Last Key Result progress update date
`user_id`	number	ID of user who updated Key Result progress
`comments`	array	List of Key Result comments

Name Type URL Description

Get all Objectives

GET

https://api.weekdone.com/1/objective?token=<OAuth Token>

Example:

{
  "status": "ok",
  "data": [
    {
      "id": 1,
      "description": "Reach the goal"
      "type": "company",
      "progress": 60,
      "results": [
        {
          "id": 1,
          "result": "Do important things 5 times",
          "type": "times",
          "weight": 1,
          "progress": 3,
          "startval": 0,
          "maxval": 5,
          "commentcount": 0,
          "comments": []
        }
      ]
    }
  ]
}

Search parameters
Name	Description
`type`	Return specific type of objectives (company, department, team, user)
`department_id`	Return department objectives
`team_id`	Return team objectives
`user_id`	Return user objectives
`period`	Return objectives for period: YYYYQ or YYYY

Create new Objective

POST

https://api.weekdone.com/1/objective?token=<OAuth Token>

Supported fields:
Name	Required	Description
`type`	yes	Objective type (company, department, team, user). Department requires field department_id Team requires field team_id User requires fields team_id and user_id
`description`	yes
`period`	no	Defaults to current quarter. In format YYYYQ

Update Objective

POST

https://api.weekdone.com/1/objective/<objective_id>?token=<OAuth Token>

Supported fields:
Name	Required	Description
`description`	yes

Delete Objective DELETE https://api.weekdone.com/1/objective/<objective_id>?token=<OAuth Token>

List Objective comments GET https://api.weekdone.com/1/objective/<objective_id>/comments?token=<OAuth Token>

Add Objective comment POST https://api.weekdone.com/1/objective/<objective_id>/comments?token=<OAuth Token>

Update Objective comment POST https://api.weekdone.com/1/objective/<objective_id>/comments/<comment_id>?token=<OAuth Token>

Delete Objective comment DELETE https://api.weekdone.com/1/objective/<objective_id>/comments/<comment_id>?token=<OAuth Token>

Add Objective result

POST

https://api.weekdone.com/1/objective/<objective_id>/result?token=<OAuth Token>

Supported fields:
Name	Required	Description
`description`	yes	Key Result description

Update Objective result

POST

https://api.weekdone.com/1/objective/<objective_id>/result/<result_id>?token=<OAuth Token>

Supported fields:
Name	Required	Description
`description`	no
`progress`	no	Update progress of Key Result in current period

Delete Objective result DELETE https://api.weekdone.com/1/objective/<objective_id>/result/<result_id>?token=<OAuth Token>

Company details

Each company has several configuration settings:

Name	Type	Description
`same_schedule`	boolean	Whether all teams use the same schedule
`same_template`	boolean	Whether all teams use the same template
`external_emails`	string	List of e-mail addresses where company reports are sent
`company_objectives`	boolean	Whether company objectives are used
`team_objectives`	boolean	Whether team objectives are used
`user_objectives`	boolean	Whether personal objectives are used
Following fields are only present when same_schedule=true
`reportsdue_day`	number	Weekday when reports will be sent
`reportsdue_hour`	number	Time of day when reports will be sent
`reportreminder_day`	number	Weekday when report reminders will be sent
`reportreminder_hour`	number	Time of day when report reminders will be sent
`timezone`	string	Timezone of the company. Used to calculate reportsdue and reportreminder values

Name Type URL Sample response:

Name	Type	URL	Sample response:
Get company info	`GET`	`https://api.weekdone.com/1/company?token=<OAuth Token>`	`{ "status": "ok", "data": { "same_schedule": true, "same_template": false, "external_emails": "", "company_objectives": 1, "team_objectives": 1, "user_objectives": 1, "reportsdue_day": 5, "reportsdue_hour": 19, "timezone":"US/Hawaii" } }`

Get company info

GET

https://api.weekdone.com/1/company?token=<OAuth Token>

{
  "status": "ok",
  "data": {
    "same_schedule": true,
    "same_template": false,
    "external_emails": "",
    "company_objectives": 1,
    "team_objectives": 1,
    "user_objectives": 1,
    "reportsdue_day": 5,
    "reportsdue_hour": 19,
    "timezone":"US/Hawaii"
  }
}

Responses

Status	Response
`202`	{"status":"ok"}
`400`	{"status":"error"} - Invalid request, this usually occurs due to missing or invalid parameters in the request.
`401`	{"status":"error"} - No authorization is returned when no valid API key was supplied.
`403`	{"status":"error"} - Forbidden, when OAuth authenticated user does not have permission to access this resource.
`404`	{"status":"error"} - Not found is returned when request method and path are uknown.
`500`	{"status":"error"} - Internal Server error, means that a problem occurred in Weekdone system. This will usually resolve by itself but if consistent, please contact hello@weekdone.com

Weekdone API documentation

Overview

Authentication

OAuth 2.0

Registering your application

Requesting authorization from the user

Response back to application

Token exchange

Token exchange response

Requesting new access token with refresh token

Tips to get you started

Items

Report

Teams

Users

Types

Tags

Objectives

Key Results

Company details

Responses