api documentation

weekdone api is restful interface, providing access to the data in weekdone system. the api supports json output.

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 //www.int-bau.com/oauth_authorize passing parameters in query string.

namerequireddescription
client_idyesthe client id uniquely identifies the application making the request.
redirect_uriyesthe uri to redirect to on success or error. this must match the redirect url specified in the application settings.
response_typeyesmust be ‘code’ (as other authorization flows are not supported).
statenoencodes 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:

namedescription
codethis is the code your app can exchange for a token
statethe 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 //www.int-bau.com/oauth_token passing following parameters in form-encoded post body:

namerequireddescription
codeyesthe code you are exchanging for an auth token
grant_typeyesmust be authorization_code
client_idyesthe client id uniquely identifies the application making the request.
client_secretyesthe client secret belonging to the app, found in application details
redirect_uriyesmust 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:

namedescription
access_tokenthe token to use in future requests against the api
refresh_tokenif exchanging a code, a long-lived token that can be used to get new access tokens when old ones expire.
usera json object encoding a few key fields about the logged-in user

requesting new access token with refresh token

access_token will expire in 60 minutes and new tokens must be requested using refresh_token. to request new access token the app must make post request to //www.int-bau.com/oauth_token passing following parameters in form-encoded post body:

namerequireddescription
refresh_tokenyesthe refresh_token
grant_typeyesmust be refresh_token
client_idyesthe client id uniquely identifies the application making the request.
client_secretyesthe client secret belonging to the app, found in application details
redirect_uriyesmust 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:

nametypedescription
idnumberuniquely identifies each item
inserteddatetimewhen the item was added to weekdone
descriptionstringthe textual description of the item
type_idnumberin which report category the item belongs to:
0 = plans on hold
1 = progress
2 = plans
3 = problems
4... = custom types
nrnumberposition of the item within the same type_id
user_idnumberid of user who added the task or to whom the task was assigned
team_idnumberid of the team where item was added
sourcenumbersource of the item 0 = weekdone
1 = jira
2 = asana
3 = basecamp
4 = googletasks
5 = slack
source_idstringid of the item in external system. maximum length is 50 characters
prioritynumber0 = not specified
1 = green
2 = amber
3 = red
commentcountnumbernumber of comments
likecountnumbernumber of likes
from_idnumberwho assigned this item
due_ondatewhen the item is due
privatenumberwho 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.www.int-bau.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.www.int-bau.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 patch https://api.www.int-bau.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 patch https://api.www.int-bau.com/1/item/<item id>/assign?token=<oauth token>
supported fields:
name required
user_id yes
delete item delete https://api.www.int-bau.com/1/item/<item id>?token=<oauth token>
get item likes get https://api.www.int-bau.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.www.int-bau.com/1/item/<item id>/likes?token=<oauth token>
delete item like delete https://api.www.int-bau.com/1/item/<item id>/likes?token=<oauth token>
sort items post https://api.www.int-bau.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.www.int-bau.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.www.int-bau.com/1/item/<item id>/comments?token=<oauth token>
supported fields:
name required
comment yes
delete item comment delete https://api.www.int-bau.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.

nametypeurlsample response:
get reportgethttps://api.www.int-bau.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": [], "ratings": { "333":5 } }, { "id": 2, "name": "second testuser", "items": [], "rate": 5, "reviews": [], "ratings": [] } ] } ] }
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:

nametypedescription
idnumberuniquely identifies each team
namestring
privacynumberwho may see team reports
1 = everybody in the company
1 = team members
2 = team manager only
external_reportsstringadditional addresses to whom team reports are sent
following fields exist when each team uses it’s own template
rate_questionstringquestion for rating week with 5 stars
reportsdue_daynumberweekday when the report will be sent
reportsdue_hournumbertime of day when the report will be sent
reportreminder_daynumberweekday when the report reminders will be sent
reportreminder_hournumbertime of day when the report reminders will be sent
timezonestringtimezone of the team. used to calculate reportsdue and reportreminder values
nametypeurlsample response:
get all teamsgethttps://api.www.int-bau.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

nametypedescription
idnumberuniquely identifies each user
inserteddatetimewhen the item was created
adminnumberwhether this is company level admin
team_idnumberuser’s primary team
teamsarrayall teams user belongs to. each user has two parameters in each team: observer and admin
nametypeurldescription
get all usersgethttps://api.www.int-bau.com/1/users?token=<oauth token>example:{ "status": "ok", "users": [ { "id": 1, "name": "test user", "picture": "//www.int-bau.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:

nametypedescription
idnumberid 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.
namestringname of the type
carryoverbooleanwhether items in this category will carry over to next week
overduebooleanwhen items carry over to next week, whether to count items as overdue when they have been carried over more than twice
nametypeurldescription
get all typesgethttps://api.www.int-bau.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 } ] }

tags

tags added to elements. optional field “status”

nametypeurldescription
get all tagsgethttps://api.www.int-bau.com/1/tag?token=<oauth token>example:{ "status": "ok", "tags": [ { "id": 23, "tag": "design", "status": { "status": "design is on track", "updated": "2015-01-05 11:33:21", "user_id": 321232 } }, { "id": 44, "tag": "website" } ] }
get single taggethttps://api.www.int-bau.com/1/tag/<tag id>?token=<oauth token>example:{ "status": "ok", "tag": { "id": 32, "tag": "products", "status": { "status": "products are on time", "updated": "2015-04-02 12:51:22", "user_id": 531232 } } }
update tag prioritypatchhttps://api.www.int-bau.com/1/tag/<tag id>/priority?token=<oauth token>
supported fields:
name required description
priority yes 0 – this is not priority tag, 1 – this is a priority tag
update tag statuspatchhttps://api.www.int-bau.com/1/tag/<tag id>/status?token=<oauth token>
supported fields:
name required description
status yes

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.

nametypedescription
idnumberid of the objective
typestringtype of objective (company, department, team, user)
descriptionstringdescription of the objective
periodstringquarter of the objective in form yyyyq
commentsnumbernumber of comments
progressnumberpercentage of objective completion
resultsarraylist of key results
parent_listarraylist of parent objectives

key results

nametypedescription
idnumberid of the key result
resultstringkey result description
inserteddatetimekey result creation time
typestringtype of key result (default %)
startvalnumberkey result minumum value
maxvalnumberkey result maximum value
weightnumberkey result weight -4…+4
progressnumberkey result progress
updateddatetimelast key result progress update date
user_idnumberid of user who updated key result progress
commentsarraylist of key result comments
name type url description
get all objectives get https://api.www.int-bau.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.www.int-bau.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 patch https://api.www.int-bau.com/1/objective/<objective_id>?token=<oauth token>
supported fields:
name required description
description yes
delete objective delete https://api.www.int-bau.com/1/objective/<objective_id>?token=<oauth token>
list objective comments get https://api.www.int-bau.com/1/objective/<objective_id>/comments?token=<oauth token>
add objective comment post https://api.www.int-bau.com/1/objective/<objective_id>/comments?token=<oauth token>
update objective comment patch https://api.www.int-bau.com/1/objective/<objective_id>/comments/<comment_id>?token=<oauth token>
delete objective comment delete https://api.www.int-bau.com/1/objective/<objective_id>/comments/<comment_id>?token=<oauth token>
add objective result post https://api.www.int-bau.com/1/objective/<objective_id>/result?token=<oauth token>
supported fields:
name required description
description yes key result description
update objective result patch https://api.www.int-bau.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.www.int-bau.com/1/objective/<objective_id>/result/<result_id>?token=<oauth token>

company details

each company has several configuration settings:

nametypedescription
same_schedulebooleanwhether all teams use the same schedule
same_templatebooleanwhether all teams use the same template
external_emailsstringlist of e-mail addresses where company reports are sent
company_objectivesbooleanwhether company objectives are used
team_objectivesbooleanwhether team objectives are used
user_objectivesbooleanwhether personal objectives are used
following fields are only present when same_schedule=true
reportsdue_daynumberweekday when reports will be sent
reportsdue_hournumbertime of day when reports will be sent
reportreminder_daynumberweekday when report reminders will be sent
reportreminder_hournumbertime of day when report reminders will be sent
timezonestringtimezone of the company. used to calculate reportsdue and reportreminder values
nametypeurlsample response:
get company infogethttps://api.www.int-bau.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

statusresponse
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@www.int-bau.com