From d75f782c25ff0f57710b8ae3ae08945f486acc9f Mon Sep 17 00:00:00 2001 From: Fitz Elliott Date: Tue, 1 Jul 2014 10:15:07 -0400 Subject: [PATCH 001/113] add backlinks to report docs + consistentify! * I am a dummy and it took me awhile to figure out that the standard query parameters are listed in reports.md. This patch adds a "Request" section to each report file that links backs to the sandard request parameters in reports.md. It also adds links back to the standard response parameters. --- reports/detailed.md | 14 ++++++++------ reports/summary.md | 15 ++++++++++----- reports/weekly.md | 17 ++++++++++------- 3 files changed, 28 insertions(+), 18 deletions(-) diff --git a/reports/detailed.md b/reports/detailed.md index b23e834..e8e8bfa 100644 --- a/reports/detailed.md +++ b/reports/detailed.md @@ -1,15 +1,17 @@ #Detailed report# The detailed report returns the time entries for the requested parameters/filters. -There is one additional parameter in detailed reports. As the returned data is paginated you have to add the page parameter. -* page: integer, default 1 -##Response## +##Request## + +In addition to the [standard request parameters](../reports.md#request-parameters), there is one additional parameter in detailed reports. As the returned data is paginated you have to add the page parameter. +* `page`: integer, default 1 -General data -* total_count: total number of time entries that were found for the request. Pay attention to the fact that the amount of time entries returned is max the number which is returned with the `per_page` field (currently 50). To get the next batch of time entries you need to do a new request with same parameters and the incremented `page` parameter. It is not possible to get all the time entries with one request. -* per_page: how many time entries are displayed in one request +##Response## +The repsonse will include the [standard response parameters](../reports.md#successful-response), as well as: +* `total_count`: total number of time entries that were found for the request. Pay attention to the fact that the amount of time entries returned is max the number which is returned with the `per_page` field (currently 50). To get the next batch of time entries you need to do a new request with same parameters and the incremented `page` parameter. It is not possible to get all the time entries with one request. +* `per_page`: how many time entries are displayed in one request ###Data array### diff --git a/reports/summary.md b/reports/summary.md index 009166b..f9dccc0 100644 --- a/reports/summary.md +++ b/reports/summary.md @@ -1,11 +1,14 @@ #Summary report# Summary report returns the aggregated time entries data. -Additional parameters for this report -* grouping -* subgrouping -* subgrouping_ids (boolean) - whether returned items will contain 'ids' key containing coma separated group item ID values -* grouped_time_entry_ids (boolean) - whether returned items will contain 'time_entry_ids' key containing coma separated time entries ID values for given item + +##Request## + +In addition to the [standard request parameters](../reports.md#request-parameters), summaries accept the following additional parameters: +* `grouping` +* `subgrouping` +* `subgrouping_ids` (boolean) - whether returned items will contain 'ids' key containing coma separated group item ID values +* `grouped_time_entry_ids` (boolean) - whether returned items will contain 'time_entry_ids' key containing coma separated time entries ID values for given item Use the grouping and subgrouping params to organize the data as needed. By default `grouping:projects` and `subgrouping:time_entries` @@ -27,6 +30,8 @@ Following groupings with subgroupings are available in the summary report ##Response## +The repsonse will include the [standard response parameters](../reports.md#successful-response). + ###Data array### General structure of the item in the data array diff --git a/reports/weekly.md b/reports/weekly.md index ac430f8..b770d6c 100644 --- a/reports/weekly.md +++ b/reports/weekly.md @@ -1,16 +1,19 @@ #Weekly report# -The weekly report gives aggregated 7 day durations or earnings grouped by users and projects. The `until` parameter is ignored for weekly report, 7 days starting from since are shown. +The weekly report gives aggregated 7 day durations or earnings grouped by users and projects. -Additional parameters for this report are: -* grouping: users/projects, default projects. If one grouping is selected, the other acts as subgrouping. -* calculate: time/earnings, default time +##Request## +The weekly report accepts all of the [standard request parameters](../reports.md#request-parameters), with the exception of the `until` parameter. Instead, 7 days starting from `since` are shown. + +Additional request parameters for this report are: +* `grouping`: `users`/`projects`, default projects. If one grouping is selected, the other acts as subgrouping. +* `calculate`: `time`/`earnings`, default time ##Response## -General data -* week_totals: array of total amounts/hours for every day (null if there's no work on a certain day) +The repsonse will include the [standard response parameters](../reports.md#successful-response), as well as: +* `week_totals`: array of total amounts/hours for every day (null if there's no work on a certain day) ###Data array### @@ -155,4 +158,4 @@ resp = http.request(req) puts resp.body puts JSON.parse(resp.body) -``` \ No newline at end of file +``` From a05f58de80ac45a51074231c2cd399395bf431e4 Mon Sep 17 00:00:00 2001 From: Margus Mahler Date: Fri, 5 Sep 2014 18:46:46 +0300 Subject: [PATCH 002/113] Added link to Node.js library, closes #97 --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 148a032..d9222c3 100644 --- a/README.md +++ b/README.md @@ -51,3 +51,6 @@ The Toggl API has moved to Github so you could actively participate in helping u ### Ruby ### * [Tom Kane](https://github.com/kanet77) has written a Ruby wrapper for Toggl API v8: https://github.com/kanet77/togglv8 + +### Node.js ### +* [Alexander Makarenko](https://github.com/estliberitas) has written a library for Node.js for Toggl API v8: https://github.com/7eggs/node-toggl-api From 7f89bdbd03561ea8cc5823129d296f968d1cc399 Mon Sep 17 00:00:00 2001 From: Margus Mahler Date: Mon, 15 Sep 2014 00:50:17 +0300 Subject: [PATCH 003/113] Added link to python toggl-cli --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index d9222c3..693d8b1 100644 --- a/README.md +++ b/README.md @@ -48,6 +48,7 @@ The Toggl API has moved to Github so you could actively participate in helping u ### Python ### * [Mosab Ahmad](https://github.com/mos3abof) has created a project using Toggl API to calculate how many hours he should work to achieve monthly goals: https://github.com/mos3abof/toggl_target +* [Beau Raines](https://github.com/beauraines) has updated the older v6 [toggl-cli](https://github.com/drobertadams/toggl-cli) to Toggl API v8: https://github.com/beauraines/toggl-cli ### Ruby ### * [Tom Kane](https://github.com/kanet77) has written a Ruby wrapper for Toggl API v8: https://github.com/kanet77/togglv8 From 9da64c5626fadd28e4800141890cadedb999fa83 Mon Sep 17 00:00:00 2001 From: Tanel Lebedev Date: Wed, 17 Sep 2014 14:45:52 +0300 Subject: [PATCH 004/113] fix typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 693d8b1..9993200 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ The result of each action is communicated via standard HTTP response codes. Times and dates use the ISO 8601 standard, more specifically a subset described in [RFC 3339](http://www.ietf.org/rfc/rfc3339.txt). -Please do note that the times and dates are parsed stored in UTC (GMT), on return the data is set into the appropriate timezone according to the setting in user profile. +Please do note that the times and dates are stored in UTC (GMT), on return the data is set into the appropriate timezone according to the setting in user profile. 3rd party applications should make sure that they are using correct timezones and also consider daylight saving (where applicable). ###Example requests### From 67929d0e098a3e0ff545951f838c5a897d0a5433 Mon Sep 17 00:00:00 2001 From: Tanel Lebedev Date: Wed, 17 Sep 2014 14:48:42 +0300 Subject: [PATCH 005/113] Update README.md --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 9993200..7d983c4 100644 --- a/README.md +++ b/README.md @@ -55,3 +55,7 @@ The Toggl API has moved to Github so you could actively participate in helping u ### Node.js ### * [Alexander Makarenko](https://github.com/estliberitas) has written a library for Node.js for Toggl API v8: https://github.com/7eggs/node-toggl-api + +### C++ ### + +TogglDesktop has a [open source, cross platform library](https://github.com/toggl/toggldesktop/tree/master/src/lib) that can be reused in your own apps. From b79e851dd30e4e7aeda416ed32fffa76b0a0620c Mon Sep 17 00:00:00 2001 From: Tanel Lebedev Date: Wed, 17 Sep 2014 14:49:08 +0300 Subject: [PATCH 006/113] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7d983c4..54e73b1 100644 --- a/README.md +++ b/README.md @@ -58,4 +58,4 @@ The Toggl API has moved to Github so you could actively participate in helping u ### C++ ### -TogglDesktop has a [open source, cross platform library](https://github.com/toggl/toggldesktop/tree/master/src/lib) that can be reused in your own apps. +TogglDesktop has an [open source, cross platform library](https://github.com/toggl/toggldesktop/tree/master/src/lib) that can be reused in your own apps. From d8b1f2f5cdce626a0ff34c24b5f9c660c8751fc3 Mon Sep 17 00:00:00 2001 From: Tanel Lebedev Date: Wed, 17 Sep 2014 15:09:40 +0300 Subject: [PATCH 007/113] Update README.md --- README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 54e73b1..caecc36 100644 --- a/README.md +++ b/README.md @@ -58,4 +58,8 @@ The Toggl API has moved to Github so you could actively participate in helping u ### C++ ### -TogglDesktop has an [open source, cross platform library](https://github.com/toggl/toggldesktop/tree/master/src/lib) that can be reused in your own apps. +* TogglDesktop has an [open source, cross platform library](https://github.com/toggl/toggldesktop/tree/master/src/lib) that can be reused in your own apps. + +### .NET ### + +Our mobile apps have a [shared C# library (Phoebe)](https://github.com/toggl/mobile/tree/master/Phoebe) which provides access to API and also some common clientside business logic we use. Feel free to use as little or much of it you want. From 0fe9cae8869249b5cf4035ac213c0324f5b2e958 Mon Sep 17 00:00:00 2001 From: Tanel Lebedev Date: Wed, 17 Sep 2014 15:10:09 +0300 Subject: [PATCH 008/113] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index caecc36..0b25ab9 100644 --- a/README.md +++ b/README.md @@ -62,4 +62,4 @@ The Toggl API has moved to Github so you could actively participate in helping u ### .NET ### -Our mobile apps have a [shared C# library (Phoebe)](https://github.com/toggl/mobile/tree/master/Phoebe) which provides access to API and also some common clientside business logic we use. Feel free to use as little or much of it you want. +* Toggl mobile apps have a [shared C# library (Phoebe)](https://github.com/toggl/mobile/tree/master/Phoebe) which provides access to API and also some common clientside business logic we use. Feel free to use as little or much of it you want. From 607cae3edb2a0bb4623308263a528efee34491d7 Mon Sep 17 00:00:00 2001 From: Margus Mahler Date: Tue, 4 Nov 2014 15:54:30 +0200 Subject: [PATCH 009/113] cookie name change, see #112 --- chapters/authentication.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/chapters/authentication.md b/chapters/authentication.md index d0103a2..1a82962 100644 --- a/chapters/authentication.md +++ b/chapters/authentication.md @@ -113,7 +113,7 @@ Response `POST https://www.toggl.com/api/v8/sessions` -It's possible to create a session. The session creation request sets a cookie in the response header `toggl_api_session`, which you can use for authentication in all the API requests. The cookie expires in 24 hours. +It's possible to create a session. The session creation request sets a cookie in the response header `toggl_api_session_new`, which you can use for authentication in all the API requests. The cookie expires in 24 hours. Example request @@ -124,7 +124,7 @@ curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token -X POST https://www.toggl. Successful response header includes the cookie ```shell -< Set-Cookie: toggl_api_session=MTM2MzA4MJa8jA3OHxEdi1CQkFFQ180SUFBUkFCRUFBQVlQLUNBQUVHYzNSeWFXNW5EQXdBQ25ObGMzTnBiMjVmYVdRR2MzUnlhVzVuREQ0QVBIUnZaMmRzTFdGd2FTMXpaWE56YVc5dUxUSXRaalU1WmpaalpEUTVOV1ZsTVRoaE1UaGhaalpqWkRkbU5XWTJNV0psWVRnd09EWmlPVEV3WkE9PXweAkG7kI6NBG-iqvhNn1MSDhkz2Pz_UYTzdBvZjCaA==; Path=/; Expires=Wed, 13 Mar 2013 09:54:38 UTC; Max-Age=86400; HttpOnly +< Set-Cookie: toggl_api_session_new=MTM2MzA4MJa8jA3OHxEdi1CQkFFQ180SUFBUkFCRUFBQVlQLUNBQUVHYzNSeWFXNW5EQXdBQ25ObGMzTnBiMjVmYVdRR2MzUnlhVzVuREQ0QVBIUnZaMmRzTFdGd2FTMXpaWE56YVc5dUxUSXRaalU1WmpaalpEUTVOV1ZsTVRoaE1UaGhaalpqWkRkbU5XWTJNV0psWVRnd09EWmlPVEV3WkE9PXweAkG7kI6NBG-iqvhNn1MSDhkz2Pz_UYTzdBvZjCaA==; Path=/; Expires=Wed, 13 Mar 2013 09:54:38 UTC; Max-Age=86400; HttpOnly ``` And body contains user's data @@ -167,7 +167,7 @@ Destroy the session manually by sending an according request to the API. Example request ```shell -curl -v --cookie toggl_api_session=MTM2MzA4MJa8jA3OHxEdi1CQkFFQ180SUFBUkFCRUFBQVlQLUNBQUVHYzNSeWFXNW5EQXdBQ25ObGMzTnBiMjVmYVdRR2MzUnlhVzVuREQ0QVBIUnZaMmRzTFdGd2FTMXpaWE56YVc5dUxUSXRaalU1WmpaalpEUTVOV1ZsTVRoaE1UaGhaalpqWkRkbU5XWTJNV0psWVRnd09EWmlPVEV3WkE9PXweAkG7kI6NBG-iqvhNn1MSDhkz2Pz_UYTzdBvZjCaA== -X DELETE https://www.toggl.com/api/v8/sessions +curl -v --cookie toggl_api_session_new=MTM2MzA4MJa8jA3OHxEdi1CQkFFQ180SUFBUkFCRUFBQVlQLUNBQUVHYzNSeWFXNW5EQXdBQ25ObGMzTnBiMjVmYVdRR2MzUnlhVzVuREQ0QVBIUnZaMmRzTFdGd2FTMXpaWE56YVc5dUxUSXRaalU1WmpaalpEUTVOV1ZsTVRoaE1UaGhaalpqWkRkbU5XWTJNV0psWVRnd09EWmlPVEV3WkE9PXweAkG7kI6NBG-iqvhNn1MSDhkz2Pz_UYTzdBvZjCaA== -X DELETE https://www.toggl.com/api/v8/sessions ``` Successful request will return `200 OK`. From 662ae94d5869b1673ef917e3e45573a375935ed5 Mon Sep 17 00:00:00 2001 From: Margus Mahler Date: Tue, 4 Nov 2014 17:24:58 +0200 Subject: [PATCH 010/113] added created_with into example request --- chapters/time_entries.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/chapters/time_entries.md b/chapters/time_entries.md index c3b0a88..1c68463 100644 --- a/chapters/time_entries.md +++ b/chapters/time_entries.md @@ -26,7 +26,7 @@ Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -H "Content-Type: application/json" \ - -d '{"time_entry":{"description":"Meeting with possible clients","tags":["billed"],"duration":1200,"start":"2013-03-05T07:58:58.000Z","pid":123}}' \ + -d '{"time_entry":{"description":"Meeting with possible clients","tags":["billed"],"duration":1200,"start":"2013-03-05T07:58:58.000Z","pid":123,"created_with":"curl"}}' \ -X POST https://www.toggl.com/api/v8/time_entries ``` @@ -57,7 +57,7 @@ Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -H "Content-Type: application/json" \ - -d '{"time_entry":{"description":"Meeting with possible clients","tags":["billed"],"pid":123}}' \ + -d '{"time_entry":{"description":"Meeting with possible clients","tags":["billed"],"pid":123,"created_with":"curl"}}' \ -X POST https://www.toggl.com/api/v8/time_entries/start ``` From 253da1ec4d98ccacc483410482a486861ebafd63 Mon Sep 17 00:00:00 2001 From: Margus Mahler Date: Wed, 5 Nov 2014 10:31:48 +0200 Subject: [PATCH 011/113] Link to dashboard --- toggl_api.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/toggl_api.md b/toggl_api.md index 5abb902..e4d0370 100644 --- a/toggl_api.md +++ b/toggl_api.md @@ -129,4 +129,6 @@ If authentication fails, HTTP status code 403 is returned. You can read more abo - update workspace user - delete workspace user - get workspace users for a workspace +* [Dashboard](chapters/dashboard.md) + - Get a generic overview of your team From 1c469e9d3913a836deba679bb3272e49fc5ea4b2 Mon Sep 17 00:00:00 2001 From: Margus Mahler Date: Mon, 1 Dec 2014 13:53:58 +0200 Subject: [PATCH 012/113] Added a python code example, closes #118 --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 0b25ab9..2d3111b 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,7 @@ The Toggl API has moved to Github so you could actively participate in helping u ### Python ### * [Mosab Ahmad](https://github.com/mos3abof) has created a project using Toggl API to calculate how many hours he should work to achieve monthly goals: https://github.com/mos3abof/toggl_target * [Beau Raines](https://github.com/beauraines) has updated the older v6 [toggl-cli](https://github.com/drobertadams/toggl-cli) to Toggl API v8: https://github.com/beauraines/toggl-cli +* [Mikhail Novikov](https://github.com/kurtgn) has created a graphical utility for displaying historical data: https://github.com/kurtgn/chronicl ### Ruby ### * [Tom Kane](https://github.com/kanet77) has written a Ruby wrapper for Toggl API v8: https://github.com/kanet77/togglv8 From 92827c10dee7cd719319df72784f25b2215932cd Mon Sep 17 00:00:00 2001 From: Tanel Lebedev Date: Mon, 1 Dec 2014 20:44:25 +0200 Subject: [PATCH 013/113] toggl-cli is now new and improved with more of an MVC model, and reusable Python objects independent of the CLI. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2d3111b..67cf108 100644 --- a/README.md +++ b/README.md @@ -48,8 +48,8 @@ The Toggl API has moved to Github so you could actively participate in helping u ### Python ### * [Mosab Ahmad](https://github.com/mos3abof) has created a project using Toggl API to calculate how many hours he should work to achieve monthly goals: https://github.com/mos3abof/toggl_target -* [Beau Raines](https://github.com/beauraines) has updated the older v6 [toggl-cli](https://github.com/drobertadams/toggl-cli) to Toggl API v8: https://github.com/beauraines/toggl-cli * [Mikhail Novikov](https://github.com/kurtgn) has created a graphical utility for displaying historical data: https://github.com/kurtgn/chronicl +* [Robert Adams](https://github.com/drobertadams) and [Beau Raines](https://github.com/beauraines) have updated [toggl-cli](https://github.com/drobertadams/toggl-cli) to API v8. It provides a set of Python objects for interacting with Toggl, as well as a command-line interface: https://github.com/drobertadams/toggl-cli ### Ruby ### * [Tom Kane](https://github.com/kanet77) has written a Ruby wrapper for Toggl API v8: https://github.com/kanet77/togglv8 From 880ab69c39603a0549117e2cec675cf02a529722 Mon Sep 17 00:00:00 2001 From: Margus Mahler Date: Fri, 2 Jan 2015 10:52:27 +0200 Subject: [PATCH 014/113] Link to toggl-cli (scala version) added --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 67cf108..89af263 100644 --- a/README.md +++ b/README.md @@ -64,3 +64,6 @@ The Toggl API has moved to Github so you could actively participate in helping u ### .NET ### * Toggl mobile apps have a [shared C# library (Phoebe)](https://github.com/toggl/mobile/tree/master/Phoebe) which provides access to API and also some common clientside business logic we use. Feel free to use as little or much of it you want. + +### Scala ### +* [Gabriele Alese](https://github.com/gabalese) has written a command line client for Toggl: https://github.com/gabalese/toggl-cli From 88637013196e65b9fc56fee7744c3c65a463039c Mon Sep 17 00:00:00 2001 From: Margus Mahler Date: Tue, 13 Jan 2015 17:31:44 +0200 Subject: [PATCH 015/113] KDE plasmoid link --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 89af263..3a8aa07 100644 --- a/README.md +++ b/README.md @@ -67,3 +67,6 @@ The Toggl API has moved to Github so you could actively participate in helping u ### Scala ### * [Gabriele Alese](https://github.com/gabalese) has written a command line client for Toggl: https://github.com/gabalese/toggl-cli + +##3rd party apps## +* [Federico Vaga](https://github.com/FedericoVaga) has writtena little plasmoid for KDE: https://github.com/FedericoVaga/plasmoggl (on opendesktop: http://opendesktop.org/content/show.php/Plasmoggl?content=168536) From 04b4a0708ca2446b3fb7b6eb9eb4322f8a480829 Mon Sep 17 00:00:00 2001 From: Arend-Jan Tetteroo Date: Thu, 15 Jan 2015 19:05:37 +0100 Subject: [PATCH 016/113] Update readme with link to PHP toggl library --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 3a8aa07..318cf76 100644 --- a/README.md +++ b/README.md @@ -68,5 +68,8 @@ The Toggl API has moved to Github so you could actively participate in helping u ### Scala ### * [Gabriele Alese](https://github.com/gabalese) has written a command line client for Toggl: https://github.com/gabalese/toggl-cli +### PHP ### +* [Arend Jan Tetteroo](https://github.com/arendjantetteroo) has written a library for PHP for Toggl API v8, based on the excellent Guzzle library: https://github.com/arendjantetteroo/guzzle-toggl + ##3rd party apps## * [Federico Vaga](https://github.com/FedericoVaga) has writtena little plasmoid for KDE: https://github.com/FedericoVaga/plasmoggl (on opendesktop: http://opendesktop.org/content/show.php/Plasmoggl?content=168536) From 36ea2c739c36bb2154128c07bbef36cf383325b6 Mon Sep 17 00:00:00 2001 From: Connor Peet Date: Thu, 22 Jan 2015 22:13:11 -0500 Subject: [PATCH 017/113] username === email --- chapters/authentication.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/chapters/authentication.md b/chapters/authentication.md index 1a82962..14b055b 100644 --- a/chapters/authentication.md +++ b/chapters/authentication.md @@ -3,6 +3,8 @@ Authentication To use the API, you need to authenticate yourself. This can be done via HTTP POST or HTTP Basic Auth. After successful authentication a session is created using a cookie. +In the current API implementation and for this documentation, the "username" is simply the user's email. + For HTTP Basic Auth you have to add the Authorization header with the request. The Authorization header is constructed as follows: * Username and password are combined into a string `username:password` or if you use the api token it should be combined `xxxx:api_token` (xxx indicating user's personal token) * The resulting string literal is then encoded using Base64 From e2bcba7983108b1c9c06df6142a37584faabcaff Mon Sep 17 00:00:00 2001 From: Nicolas Besnard Date: Wed, 25 Feb 2015 08:45:53 +0000 Subject: [PATCH 018/113] Update authentication.md --- chapters/authentication.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/chapters/authentication.md b/chapters/authentication.md index 14b055b..516b32c 100644 --- a/chapters/authentication.md +++ b/chapters/authentication.md @@ -38,7 +38,12 @@ Response "store_start_and_stop_time":true, "beginning_of_week":1, "language":"en_US", + "duration_format": "improved", "image_url":"https://www.toggl.com/images/profile.png", + "at": "2015-02-17T16:58:53+00:00", + "created_at": "2014-07-31T07:51:17+00:00", + "timezone": "Europe/London", + "retention": 9, "new_blog_post":{}, "projects": [ { @@ -61,7 +66,15 @@ Response "tasks": [], "workspaces": [ { - "id":777,"name":"John's WS","at":"2012-11-28T11:56:49+00:00" + "id":777, + "name":"John's WS", + "at":"2012-11-28T11:56:49+00:00", + "default_hourly_rate": 0, + "default_currency": "USD", + "projects_billable_by_default": true, + "rounding": 1, + "rounding_minutes": 0, + "api_token": "ea897...", } ], "clients": [] From 3c5be305a23e14f209d8879471e7ffce21e3fe49 Mon Sep 17 00:00:00 2001 From: Margus Mahler Date: Mon, 2 Mar 2015 11:49:13 +0200 Subject: [PATCH 019/113] added project color information to summary report --- reports/summary.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/reports/summary.md b/reports/summary.md index f9dccc0..645c210 100644 --- a/reports/summary.md +++ b/reports/summary.md @@ -70,6 +70,9 @@ General structure of the item in the data array } ``` +##Project colors## +When grouped by project the title part of the return will contain color and color_hex fields. First one contains the color id (returned also by APIv8), second one will return the corresponding HEX value. (Please note: color return is a subject of change). + ##Example## Example request From b6d936001df43a202108c868133e42d3706aff09 Mon Sep 17 00:00:00 2001 From: Matthieu Auger Date: Wed, 4 Mar 2015 22:50:50 +0100 Subject: [PATCH 020/113] Fix small typos in json responses --- chapters/projects.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/chapters/projects.md b/chapters/projects.md index 222ba36..0bdc7bc 100644 --- a/chapters/projects.md +++ b/chapters/projects.md @@ -43,7 +43,7 @@ Successful response "is_private":true, "active":true, "at":"2013-03-06T12:15:37+00:00", - "template_id":10237 + "template_id":10237, "color": "5" } } @@ -73,7 +73,7 @@ Successful response "is_private":true, "active":true, "at":"2013-03-06T12:15:37+00:00", - "template":true + "template":true, "color": "5" } } @@ -178,7 +178,7 @@ Successful response is an array of the project's tasks "pid":777, "active":false, "at":"2013-02-26T15:09:52+00:00", - "estimated_seconds":3600, + "estimated_seconds":3600 }, { "name":"Another task", "id":1335076911, @@ -186,7 +186,7 @@ Successful response is an array of the project's tasks "wid":888, "pid":777, "active":false, - "at":"2013-02-26T15:09:52+00:00", + "at":"2013-02-26T15:09:52+00:00" } ] ``` From 7aa5ab67122a13321a2a7934e242208a608b1e95 Mon Sep 17 00:00:00 2001 From: Margus Mahler Date: Fri, 20 Mar 2015 15:34:08 +0200 Subject: [PATCH 021/113] added TogglAPI.Net link, closes #134 --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 318cf76..2d86b06 100644 --- a/README.md +++ b/README.md @@ -64,6 +64,7 @@ The Toggl API has moved to Github so you could actively participate in helping u ### .NET ### * Toggl mobile apps have a [shared C# library (Phoebe)](https://github.com/toggl/mobile/tree/master/Phoebe) which provides access to API and also some common clientside business logic we use. Feel free to use as little or much of it you want. +* [Ilya Pirozhenko](https://github.com/sochix) has written a .NET library: https://www.nuget.org/packages/TogglAPI.Net/ ### Scala ### * [Gabriele Alese](https://github.com/gabalese) has written a command line client for Toggl: https://github.com/gabalese/toggl-cli From 62f436c007c96acb19c13fdb7c8ed426eedef97a Mon Sep 17 00:00:00 2001 From: Matthew Downey Date: Mon, 27 Apr 2015 19:08:09 -0700 Subject: [PATCH 022/113] Update reports.md Changed "The workspace which data you want to access" to "The workspace whose data you want to access" --- reports.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reports.md b/reports.md index 8f4d233..8e523d8 100644 --- a/reports.md +++ b/reports.md @@ -33,7 +33,7 @@ The API expects the request parameters as the query string of the URL. The following parameters and filters can be used in all of the reports * user_agent: string, **required**, the name of your application or your email address so we can get in touch in case you're doing something wrong. -* workspace_id: integer, **required**. The workspace which data you want to access. +* workspace_id: integer, **required**. The workspace whose data you want to access. * since: string, ISO 8601 date (YYYY-MM-DD), by default until - 6 days. * until: string, ISO 8601 date (YYYY-MM-DD), by default today * billable: possible values: yes/no/both, default both From 94d639b0c8757d4c19dd32aab2a8366dc97d097b Mon Sep 17 00:00:00 2001 From: Margus Mahler Date: Mon, 4 May 2015 12:35:20 +0300 Subject: [PATCH 023/113] togglpy project reference added --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 2d86b06..655f60c 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,7 @@ The Toggl API has moved to Github so you could actively participate in helping u * [Mosab Ahmad](https://github.com/mos3abof) has created a project using Toggl API to calculate how many hours he should work to achieve monthly goals: https://github.com/mos3abof/toggl_target * [Mikhail Novikov](https://github.com/kurtgn) has created a graphical utility for displaying historical data: https://github.com/kurtgn/chronicl * [Robert Adams](https://github.com/drobertadams) and [Beau Raines](https://github.com/beauraines) have updated [toggl-cli](https://github.com/drobertadams/toggl-cli) to API v8. It provides a set of Python objects for interacting with Toggl, as well as a command-line interface: https://github.com/drobertadams/toggl-cli +* [Matthew Downey](https://github.com/matthewdowney) has started a Toggl API wrapper: https://github.com/matthewdowney/TogglPy ### Ruby ### * [Tom Kane](https://github.com/kanet77) has written a Ruby wrapper for Toggl API v8: https://github.com/kanet77/togglv8 From 5d34c09fc17f2ba5ab97d2b04e97059dbba34ba0 Mon Sep 17 00:00:00 2001 From: Margus Mahler Date: Mon, 18 May 2015 16:42:39 +0300 Subject: [PATCH 024/113] added note about HTTP 429 responses --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 655f60c..08e1ecc 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,8 @@ Times and dates use the ISO 8601 standard, more specifically a subset described Please do note that the times and dates are stored in UTC (GMT), on return the data is set into the appropriate timezone according to the setting in user profile. 3rd party applications should make sure that they are using correct timezones and also consider daylight saving (where applicable). +For rate limiting we have implemented a [Leaky bucket](http://en.wikipedia.org/wiki/Leaky_bucket). When a limit has been hit the request will get a HTTP 429 response and it's the task of the client to sleep/wait until bucket is empty. Limits will and can change during time, but a safe window will be *1 request per second*. + ###Example requests### The example requests here are done using a command line tool called [cURL](http://en.wikipedia.org/wiki/CURL). If you want to try the requests out yourself, you can download cURL from [here](http://curl.haxx.se/download.html). It is available for all possible operating systems. @@ -74,4 +76,4 @@ The Toggl API has moved to Github so you could actively participate in helping u * [Arend Jan Tetteroo](https://github.com/arendjantetteroo) has written a library for PHP for Toggl API v8, based on the excellent Guzzle library: https://github.com/arendjantetteroo/guzzle-toggl ##3rd party apps## -* [Federico Vaga](https://github.com/FedericoVaga) has writtena little plasmoid for KDE: https://github.com/FedericoVaga/plasmoggl (on opendesktop: http://opendesktop.org/content/show.php/Plasmoggl?content=168536) +* [Federico Vaga](https://github.com/FedericoVaga) has written a little plasmoid for KDE: https://github.com/FedericoVaga/plasmoggl (on opendesktop: http://opendesktop.org/content/show.php/Plasmoggl?content=168536) From 47a7e61ee4a2e717eebede3fbd27dcd0fa5c3b47 Mon Sep 17 00:00:00 2001 From: Margus Mahler Date: Mon, 18 May 2015 16:49:27 +0300 Subject: [PATCH 025/113] added note about rate being per token per ip --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 08e1ecc..842c33d 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,7 @@ Please do note that the times and dates are stored in UTC (GMT), on return the d 3rd party applications should make sure that they are using correct timezones and also consider daylight saving (where applicable). For rate limiting we have implemented a [Leaky bucket](http://en.wikipedia.org/wiki/Leaky_bucket). When a limit has been hit the request will get a HTTP 429 response and it's the task of the client to sleep/wait until bucket is empty. Limits will and can change during time, but a safe window will be *1 request per second*. +Limiting is applied per api token per IP, meaning two users from the same IP will get their rate allocated separately. ###Example requests### From 45cd9fb76ada37a995c72e4dbbd5f44057ec4481 Mon Sep 17 00:00:00 2001 From: ervin Date: Mon, 1 Jun 2015 15:37:37 +0300 Subject: [PATCH 026/113] rate limiting --- reports.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/reports.md b/reports.md index 8e523d8..a26289d 100644 --- a/reports.md +++ b/reports.md @@ -20,6 +20,12 @@ Summary report URL: `GET https://toggl.com/reports/api/v2/summary` For PDF response add .pdf to the end of the URL. +##Rate limiting## + +There is rate limiting of 1 request per second (per IP per API token), this +limit may change in future. In case client application exceeds rate limit +HTTP status 429 will be returned. Excessive requests may yield in stricter +limits set upon token/IP combination. ##Authentication## From 0d65cd04b612e515e268154dc5c8b6cb2d54cb38 Mon Sep 17 00:00:00 2001 From: ervin Date: Mon, 1 Jun 2015 15:40:14 +0300 Subject: [PATCH 027/113] additional info on errors --- reports.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/reports.md b/reports.md index a26289d..a45b895 100644 --- a/reports.md +++ b/reports.md @@ -96,3 +96,25 @@ Example error } ``` + +Notable error codes: + + 402 Payment Required - feature is not included in current subscription level of + workspace + 410 Gone - this api version is deprecated. Update your client. + 429 Too Many Requests - add delay between requests. + + +To provide third-party developers with important information, we will use +[Warning](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.46) HTTP +header in api responses. We recommend to set up automated notifications for +Warning headers in all responses, in addition to notifying you about failed requests. + +Example warning + + Warning:Human readable warning message + +There are two test endpoints, that return error so you can test client side +error handling: [Error 400](https://www.toggl.com/reports/api/v2/error400) and +[Error 500](https://www.toggl.com/reports/api/v2/error500) both of them set +Warning header to test value. \ No newline at end of file From 64282bb72f653ea55cecbe9daa5d899427d71bac Mon Sep 17 00:00:00 2001 From: Ervin Date: Tue, 2 Jun 2015 12:48:27 +0300 Subject: [PATCH 028/113] publishing project dashboard json schema --- reports/project_dashboard_schema.json | 171 ++++++++++++++++++++++++++ 1 file changed, 171 insertions(+) create mode 100644 reports/project_dashboard_schema.json diff --git a/reports/project_dashboard_schema.json b/reports/project_dashboard_schema.json new file mode 100644 index 0000000..ec2fe17 --- /dev/null +++ b/reports/project_dashboard_schema.json @@ -0,0 +1,171 @@ +{ + "$schema": "http://json-schema.org/draft-04/schema#", + "description": "Toggl Project dashboard", + "type": "object", + "required": [ + "name", + "duration", + "duration_without_task", + "billable_duration", + "billable_amount", + "tasks_count", + "currency", + "estimated_seconds", + "task_estimated_seconds", + "use_task_estimated_seconds", + "tasks_per_page", + "users", + "top_tasks", + "tasks_page" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of project" + }, + "duration": { + "type": "integer", + "description": "Total time tracked for this project (ms)" + }, + "duration_without_task": { + "type": "integer", + "description": "Time that was tracked without task" + }, + "billable_duration": { + "type": ["integer", "null"], + "description": "Billable time tracked for this project (ms) " + }, + "billable_amount": { + "type": ["number", "null"], + "description": "Billable amount sum " + }, + "tasks_count": { + "type": "integer", + "description": "Total number of tasks in this project" + }, + "currency": { + "type": "string", + "description": "Currency of billable_amount " + }, + "estimated_seconds": { + "type": ["integer", "null"], + "description": "Estimate of how long project would take in seconds" + }, + "task_estimated_seconds": { + "type": ["integer", "null"], + "description": "Total of each task time estimations in seconds" + }, + "use_task_estimated_seconds": { + "type": "boolean", + "description": "Flag indicating if total of task time estimations (true) should be used as grand-estimate, for false value estimated_seconds should be used instead" + }, + "tasks_per_page": { + "type": "integer", + "description": "Number of tasks per page in #tasks_page, use together with #tasks_count to display user with pagination links" + }, + "users": { + "type": "array", + "description": "All users who contributed time to project", + "minItems": 0, + "uniqueItems": true, + "items": { + "type": "object", + "required": [ + "name", + "duration", + "billable_duration", + "billable_amount" + ], + "properties": { + "name": { + "type": "string", + "description": "Toggl user name" + }, + "duration": { + "type": "integer", + "description": "Time tracked for this project by given user (ms)" + }, + "billable_duration": { + "type": "integer", + "description": "Billable time tracked for this project by given user (ms) " + }, + "billable_amount": { + "type": "number", + "description": "Billable amount contributed by given user " + } + } + } + }, + "top_tasks": { + "type": ["array", "null"], + "description": "Tasks that contributed more than 10% of total time to project", + "minItems": 1, + "uniqueItems": true, + "items": { + "type": "object", + "required": [ + "duration", + "billable_amount" + ], + "properties": { + "duration": { + "type": "integer", + "description": "Time tracked for this project (ms)" + }, + "billable_amount": { + "type": "number", + "description": "Billable amount contributed by this task " + }, + "name": { + "type": ["string", "null"], + "description": "Name of task, null value for name has special meaning - 'Sum of Others'" + }, + "estimated_seconds": { + "type": ["integer", "null"], + "description": "Estimate of how long task should take in seconds" + }, + "asignee": { + "type":["string", "null"], + "description": "Toggl user assigned to this task" + } + } + } + }, + "tasks_page": { + "type": ["array", "null"], + "description": "Paginated list of tasks", + "minItems": 1, + "uniqueItems": true, + "items": { + "type": "object", + "required": [ + "name", + "duration", + "billable_amount" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of task" + }, + "assignee": { + "type": "string", + "description": "Toggl user assigned to this task" + }, + "estimated_seconds": { + "type": "integer", + "description": "Estimate of how long task should take in seconds" + }, + "duration": { + "type": "integer", + "description": "Time tracked for this project (ms)" + }, + "billable_amount": { + "type": "number", + "description": "Billable amount contributed by this task " + } + } + } + } + } +} From 331e29ecb0f7934968641a4f763d3d84f610bef1 Mon Sep 17 00:00:00 2001 From: Ervin Date: Tue, 2 Jun 2015 14:34:06 +0300 Subject: [PATCH 029/113] project dashboard documentation --- reports.md | 1 + reports/project.md | 158 ++++++++++++++++++++++++++ reports/project_dashboard_schema.json | 4 +- 3 files changed, 161 insertions(+), 2 deletions(-) create mode 100644 reports/project.md diff --git a/reports.md b/reports.md index a45b895..622e745 100644 --- a/reports.md +++ b/reports.md @@ -7,6 +7,7 @@ More detailed information for the reports. * [Weekly report](reports/weekly.md) * [Detailed report](reports/detailed.md) * [Summary report](reports/summary.md) +* [Project dashboard](reports/project.md) ##URLs## diff --git a/reports/project.md b/reports/project.md new file mode 100644 index 0000000..e3a670a --- /dev/null +++ b/reports/project.md @@ -0,0 +1,158 @@ +#Project dashboard# + +[Project dashboard](http://support.toggl.com/project-dashboard/) returns at-a glance information for a single project. This feature is only available with Toggl pro. + +##Request## + +`GET /reports/api/v2/project` + +Parameters are: + +* `user_agent` string, **required**, email, or other way to contact client + application developer +* `workspace_id` integer, **required**. The workspace whose data you want to + access +* `project_id` integer, **required**. The project whose data you want to + access +* `page` integer, optional. number of 'tasks_page' you want to fetch +* `order_field` string: name/assignee/duration/billable_amount/estimated_seconds +* `order_desc` string: on/off, `on` for descending and `off` for ascending +order + +##Response## + +Project dashboard response has following strucure: ([json schema] +(project/project_dashboard_schema.json)) + +```json +{ + "name": "string, name of project", + "duration": "integer, total time tracked for this project (ms)", + "billable_duration": "integer, billable time tracked for this project (ms)", + "billable_amount": "number, sum of earnings", + "tasks_count": "integer, total number of tasks in this project", + "currency": "string, currency of billable_amount", + "estimated_seconds": "integer, estimate of how long project would take in seconds", + "task_estimated_seconds": "integer, total of each task time estimations in seconds", + "use_task_estimated_seconds": "boolean, flag indicating if total of task time estimations (true) should be used as grand-estimate, for false value estimated_seconds should be used instead", + "tasks_per_page": "integer, number of tasks per page in #tasks_page, use together with #tasks_count to build pagination links", + "users": [{ + "name": "string, toggl user name", + "duration": "integer, time tracked for this project by given user (ms)", + "billable_duration": "integer, billable time tracked for this project by given user (ms)", + "billable_amount": "number, billable amount contributed by given user" + }], + "top_tasks": [{ + "duration": "integer, time tracked for this project (ms)", + "billable_amount": "number, billable amount contributed by this task", + "name": "string, name of task, null value for name has special meaning - 'Sum of Others'", + "estimated_seconds": "integer, estimate of how long task should take in seconds", + "asignee": "string, toggl user assigned to this task" + }], + "tasks_page": [{ + "name": "string, name of task", + "assignee": "string, toggl user assigned to this task", + "estimated_seconds": "integer, estimate of how long task should take in seconds", + "duration": "integer, time tracked for this project (ms)", + "billable_amount": "number, billable amount contributed by this task" +}] +} +``` + +* `users` array holds all users who contributed time to project +* `top_tasks` is array of tasks that contributed more than 10% of total time + to project +* `tasks_page` is array holding all tasks of given project, one page + at a time + +##Example## + +request: +```shell +curl -u my-secret-toggl-api-token:api_token -X GET "https://www.toggl.com/reports/api/v2/project/?page=1&user_agent=devteam@example.com&workspace_id=1&project_id=2" +``` + +response (formatted for readability): +```json +{ + "name": "Accounting", + "duration": 74417000, + "duration_without_task": 21137000, + "billable_duration": 43097000, + "billable_amount": 838, + "tasks_count": 4, + "currency": "USD", + "estimated_seconds": 25200, + "task_estimated_seconds": 72000, + "use_task_estimated_seconds": true, + "tasks_per_page": 10, + "users": [ + { + "name": "Paul McMurdoh", + "duration": 74417000, + "billable_duration": 43097000, + "billable_amount": 838 + } + ], + "top_tasks": [ + { + "duration": 25200000, + "billable_amount": 371, + "name": "Invoices", + "estimated_seconds": 18000, + "asignee": null + }, + { + "duration": 10800000, + "billable_amount": null, + "name": "Writing", + "estimated_seconds": 21600, + "asignee": null + }, + { + "duration": 10080000, + "billable_amount": 196, + "name": "Planning", + "estimated_seconds": 14400, + "asignee": null + }, + { + "duration": 7200000, + "billable_amount": 140, + "name": "Billing", + "estimated_seconds": 18000, + "asignee": null + } + ], + "tasks_page": [ + { + "name": "Billing", + "assignee": null, + "estimated_seconds": 18000, + "duration": 7200000, + "billable_amount": 140 + }, + { + "name": "Invoices", + "assignee": null, + "estimated_seconds": 18000, + "duration": 25200000, + "billable_amount": 371 + }, + { + "name": "Planning", + "assignee": null, + "estimated_seconds": 14400, + "duration": 10080000, + "billable_amount": 196 + }, + { + "name": "Writing", + "assignee": null, + "estimated_seconds": 21600, + "duration": 10800000, + "billable_amount": null + } + ] +} +``` \ No newline at end of file diff --git a/reports/project_dashboard_schema.json b/reports/project_dashboard_schema.json index ec2fe17..1177278 100644 --- a/reports/project_dashboard_schema.json +++ b/reports/project_dashboard_schema.json @@ -99,7 +99,7 @@ "top_tasks": { "type": ["array", "null"], "description": "Tasks that contributed more than 10% of total time to project", - "minItems": 1, + "minItems": 0, "uniqueItems": true, "items": { "type": "object", @@ -134,7 +134,7 @@ "tasks_page": { "type": ["array", "null"], "description": "Paginated list of tasks", - "minItems": 1, + "minItems": 0, "uniqueItems": true, "items": { "type": "object", From ad7c582d6ce89d947496c7af879efa5438a6a44b Mon Sep 17 00:00:00 2001 From: Ervin Date: Tue, 2 Jun 2015 14:48:24 +0300 Subject: [PATCH 030/113] fixed json schema relative url --- reports/project.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reports/project.md b/reports/project.md index e3a670a..6886222 100644 --- a/reports/project.md +++ b/reports/project.md @@ -22,7 +22,7 @@ order ##Response## Project dashboard response has following strucure: ([json schema] -(project/project_dashboard_schema.json)) +(project_dashboard_schema.json)) ```json { From 83c3de72c2e527375f2f5c6b6b41f6ab4117342f Mon Sep 17 00:00:00 2001 From: Daniel Widerin Date: Wed, 19 Aug 2015 09:14:56 +0200 Subject: [PATCH 031/113] Fix commas to avoid invalid json example. --- chapters/authentication.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/chapters/authentication.md b/chapters/authentication.md index 516b32c..4c30ae7 100644 --- a/chapters/authentication.md +++ b/chapters/authentication.md @@ -52,7 +52,7 @@ Response "name":"Our best project", "billable":true, "active":true, - "at":"2013-02-12T09:47:57+00:00" + "at":"2013-02-12T09:47:57+00:00", "color":"5" } ], @@ -74,7 +74,7 @@ Response "projects_billable_by_default": true, "rounding": 1, "rounding_minutes": 0, - "api_token": "ea897...", + "api_token": "ea897..." } ], "clients": [] From 599dcf9c4d4a55db35a23ef1c848400c92196c71 Mon Sep 17 00:00:00 2001 From: tk Date: Thu, 20 Aug 2015 02:54:16 -0500 Subject: [PATCH 032/113] Fix typo (doesn'y -> doesn't) --- chapters/dashboard.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapters/dashboard.md b/chapters/dashboard.md index 25313fc..d66c26b 100644 --- a/chapters/dashboard.md +++ b/chapters/dashboard.md @@ -9,7 +9,7 @@ Dashboard request returns two objects: The activity object holds the data of 10 latest actions in the workspace. Activity object has the following properties * user_id: user ID -* project_id: project ID (ID is 0 if time entry doesn'y have project connected to it) +* project_id: project ID (ID is 0 if time entry doesn't have project connected to it) * duration: time entry duration in seconds. If the time entry is currently running, the duration attribute contains a negative value, denoting the start of the time entry in seconds since epoch (Jan 1 1970). The correct duration can be calculated as current_time + duration, where current_time is the current time in seconds since epoch. * description: (Description property is not present if time entry description is empty) * stop: time entry stop time (ISO 8601 date and time. Stop property is not present when time entry is still running) From 2a5f573bd877d05173897123f7919fb76b657c0f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20da=20Silva=20Cont=C3=ADn?= Date: Tue, 25 Aug 2015 11:29:02 +0200 Subject: [PATCH 033/113] Add rounding type table to workspace docs Not sure if table position and column naming is good though. --- chapters/workspaces.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/chapters/workspaces.md b/chapters/workspaces.md index c8e35f9..74029d4 100644 --- a/chapters/workspaces.md +++ b/chapters/workspaces.md @@ -14,6 +14,13 @@ Workspace has the following properties * at: timestamp that indicates the time workspace was last updated * logo_url: URL pointing to the logo (if set, otherwise omited) (string) +### Rounding type +| Type | Integer | +| ---------- | :-----: | +| round down | -1 | +| nearest | 0 | +| round up | 1 | + ##Get workspaces## From b7fe4ab97fd432a64c1a2a2961f4a5b4996ee669 Mon Sep 17 00:00:00 2001 From: Chris Rinaldi Date: Wed, 2 Sep 2015 09:50:49 -0400 Subject: [PATCH 034/113] Fixed spelling mistake --- reports/weekly.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reports/weekly.md b/reports/weekly.md index b770d6c..a0b4e18 100644 --- a/reports/weekly.md +++ b/reports/weekly.md @@ -12,7 +12,7 @@ Additional request parameters for this report are: ##Response## -The repsonse will include the [standard response parameters](../reports.md#successful-response), as well as: +The response will include the [standard response parameters](../reports.md#successful-response), as well as: * `week_totals`: array of total amounts/hours for every day (null if there's no work on a certain day) ###Data array### From 2db1ffefef7b2d7f79aed07571cf856f709e4515 Mon Sep 17 00:00:00 2001 From: barryels Date: Sat, 24 Oct 2015 10:10:10 +0200 Subject: [PATCH 035/113] Update projects.md Grammatical update --- chapters/projects.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapters/projects.md b/chapters/projects.md index 0bdc7bc..3a6e801 100644 --- a/chapters/projects.md +++ b/chapters/projects.md @@ -10,7 +10,7 @@ Project has the following properties * template: whether the project can be used as a template (boolean, not required) * template_id: id of the template project used on current project's creation * billable: whether the project is billable or not (boolean, default true, available only for pro workspaces) -* auto_estimates: whether the estimated hours is calculated based on task estimations or is fixed manually (boolean, default false, not required, premium functionality) +* auto_estimates: whether the estimated hours are automatically calculated based on task estimations or manually fixed based on the value of 'estimated_hours' (boolean, default false, not required, premium functionality) * estimated_hours: if auto_estimates is true then the sum of task estimations is returned, otherwise user inserted hours (integer, not required, premium functionality) * at: timestamp that is sent in the response for PUT, indicates the time task was last updated (read-only) * color: id of the color selected for the project From 0a7944390affa9e5dbadf8f32cafe7120fdcb748 Mon Sep 17 00:00:00 2001 From: jkruczynski Date: Mon, 26 Oct 2015 11:16:53 -0400 Subject: [PATCH 036/113] Update README.md --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 842c33d..5beb690 100644 --- a/README.md +++ b/README.md @@ -78,3 +78,6 @@ The Toggl API has moved to Github so you could actively participate in helping u ##3rd party apps## * [Federico Vaga](https://github.com/FedericoVaga) has written a little plasmoid for KDE: https://github.com/FedericoVaga/plasmoggl (on opendesktop: http://opendesktop.org/content/show.php/Plasmoggl?content=168536) +* +### Perl ### +* [Jason Kruczynski] (https://github.com/jkruczynski) has written a perl wrapper for the API. It creates and authenticates a session for API V8 or API V2 depending on the URL. It implements a few functions for exporting reports. https://github.com/jkruczynski/Toggl-API-Wrapper-Perl From 303c7d7ba7e9c85085c7b4f87968db870f195a38 Mon Sep 17 00:00:00 2001 From: jkruczynski Date: Mon, 26 Oct 2015 11:17:18 -0400 Subject: [PATCH 037/113] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5beb690..bbc6e5d 100644 --- a/README.md +++ b/README.md @@ -78,6 +78,6 @@ The Toggl API has moved to Github so you could actively participate in helping u ##3rd party apps## * [Federico Vaga](https://github.com/FedericoVaga) has written a little plasmoid for KDE: https://github.com/FedericoVaga/plasmoggl (on opendesktop: http://opendesktop.org/content/show.php/Plasmoggl?content=168536) -* + ### Perl ### * [Jason Kruczynski] (https://github.com/jkruczynski) has written a perl wrapper for the API. It creates and authenticates a session for API V8 or API V2 depending on the URL. It implements a few functions for exporting reports. https://github.com/jkruczynski/Toggl-API-Wrapper-Perl From f29a3e3ca923e30c125df4a10b2708f5c6b62d09 Mon Sep 17 00:00:00 2001 From: tk Date: Mon, 30 Nov 2015 01:36:48 -0600 Subject: [PATCH 038/113] Update list of Project API actions Update list of Project API actions on `toggl_api.md` to match `chapters/projects.md` --- toggl_api.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/toggl_api.md b/toggl_api.md index e4d0370..5d6554e 100644 --- a/toggl_api.md +++ b/toggl_api.md @@ -83,8 +83,10 @@ If authentication fails, HTTP status code 403 is returned. You can read more abo - create a project - get project data - update project data + - delete a project - get project users - get project tasks + - delete multiple projects * [Project users](chapters/project_users.md) - create a project user - update a project user From a3af2ed6c9bb3cf88db65fb4122fad4a718dd9ab Mon Sep 17 00:00:00 2001 From: Margus Mahler Date: Mon, 11 Jan 2016 18:11:03 +0200 Subject: [PATCH 039/113] maximum span of report mentioned also in docs, closes #168 There is also a human readable return if span is outside of allowed bounds; if extended period is needed - multiple requests and merge on the client side. --- reports.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/reports.md b/reports.md index 622e745..f310c61 100644 --- a/reports.md +++ b/reports.md @@ -61,6 +61,8 @@ The following parameters and filters can be used in all of the reports * rounding: on/off, default off, rounds time according to workspace settings * display_hours: decimal/minutes, display hours with minutes or as a decimal number, default minutes +NB! Maximum date span (until - since) is one year. + ##Successful response## The general structure of the successful response @@ -118,4 +120,4 @@ Example warning There are two test endpoints, that return error so you can test client side error handling: [Error 400](https://www.toggl.com/reports/api/v2/error400) and [Error 500](https://www.toggl.com/reports/api/v2/error500) both of them set -Warning header to test value. \ No newline at end of file +Warning header to test value. From 75b55b55d21e864f94717dddc1c931956b5d97da Mon Sep 17 00:00:00 2001 From: Michael Baldwin Date: Thu, 21 Jan 2016 23:22:31 -0500 Subject: [PATCH 040/113] Corrected spelling mistake for "response" --- reports/detailed.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reports/detailed.md b/reports/detailed.md index e8e8bfa..8b4a601 100644 --- a/reports/detailed.md +++ b/reports/detailed.md @@ -9,7 +9,7 @@ In addition to the [standard request parameters](../reports.md#request-parameter ##Response## -The repsonse will include the [standard response parameters](../reports.md#successful-response), as well as: +The response will include the [standard response parameters](../reports.md#successful-response), as well as: * `total_count`: total number of time entries that were found for the request. Pay attention to the fact that the amount of time entries returned is max the number which is returned with the `per_page` field (currently 50). To get the next batch of time entries you need to do a new request with same parameters and the incremented `page` parameter. It is not possible to get all the time entries with one request. * `per_page`: how many time entries are displayed in one request From 6fff1ffbc972f6e553601c0396ee09489331ea2d Mon Sep 17 00:00:00 2001 From: tk Date: Thu, 21 Jan 2016 23:14:19 -0600 Subject: [PATCH 041/113] Fix link for Toggl reports page --- reports.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reports.md b/reports.md index f310c61..5af1ba8 100644 --- a/reports.md +++ b/reports.md @@ -1,7 +1,7 @@ Toggl Reports API v2 ================= -Here you can get the general information about how to use Toggl reports API, from how to authenticate, what filters to use and how the response is structured. The available reports are similar to the reports available in [Toggl reports page](https://www.toggl.com/report/show). +Here you can get the general information about how to use Toggl reports API, from how to authenticate, what filters to use and how the response is structured. The available reports are similar to the reports available in [Toggl reports page](https://www.toggl.com/app/reports). More detailed information for the reports. * [Weekly report](reports/weekly.md) From a4bf9237d167016edec5e02c79a89b3dbb35da1d Mon Sep 17 00:00:00 2001 From: SirLamer Date: Wed, 3 Feb 2016 02:56:05 -0700 Subject: [PATCH 042/113] Fix incorrect property name in header Fix incorrectly documented timestamp property name from 'created_at' to 'at' --- chapters/projects.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapters/projects.md b/chapters/projects.md index 3a6e801..fdc2fb0 100644 --- a/chapters/projects.md +++ b/chapters/projects.md @@ -15,7 +15,7 @@ Project has the following properties * at: timestamp that is sent in the response for PUT, indicates the time task was last updated (read-only) * color: id of the color selected for the project * rate: hourly rate of the project (float, not required, premium functionality) -* created_at: timestamp indicating when the project was created (UTC time), read-only +* at: timestamp indicating when the project was created (UTC time), read-only ##Create project## From 190a3c1418b4f037203627b37e1fa637b89875c0 Mon Sep 17 00:00:00 2001 From: Damian Mee Date: Mon, 15 Feb 2016 18:32:24 +0800 Subject: [PATCH 043/113] add meedamian/toggl-cli to README --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index bbc6e5d..6b12b47 100644 --- a/README.md +++ b/README.md @@ -59,6 +59,7 @@ The Toggl API has moved to Github so you could actively participate in helping u * [Tom Kane](https://github.com/kanet77) has written a Ruby wrapper for Toggl API v8: https://github.com/kanet77/togglv8 ### Node.js ### +* [Damian Mee](https://github.com/meeDamian) has written a CLI tool in Node.js for Toggl API v8: https://github.com/meeDamian/toggl-cli * [Alexander Makarenko](https://github.com/estliberitas) has written a library for Node.js for Toggl API v8: https://github.com/7eggs/node-toggl-api ### C++ ### From 4d4925d1f3e7bcce5d140423103da7f813b9db4e Mon Sep 17 00:00:00 2001 From: Victor Viruete Date: Wed, 16 Mar 2016 11:43:51 +0100 Subject: [PATCH 044/113] Updated readme with link to Elixir wrapper library --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 6b12b47..893c43a 100644 --- a/README.md +++ b/README.md @@ -77,6 +77,10 @@ The Toggl API has moved to Github so you could actively participate in helping u ### PHP ### * [Arend Jan Tetteroo](https://github.com/arendjantetteroo) has written a library for PHP for Toggl API v8, based on the excellent Guzzle library: https://github.com/arendjantetteroo/guzzle-toggl +### Elixir ### + +* [Víctor Viruete](https://github.com/hopsor) has written an Elixir wrapper for Toggl API v8 and Reports API: https://github.com/diacode/togglex + ##3rd party apps## * [Federico Vaga](https://github.com/FedericoVaga) has written a little plasmoid for KDE: https://github.com/FedericoVaga/plasmoggl (on opendesktop: http://opendesktop.org/content/show.php/Plasmoggl?content=168536) From e6f888ed38ab1bf5daf629b339c380ced166df4d Mon Sep 17 00:00:00 2001 From: "Mark J. Lehman" Date: Fri, 27 May 2016 10:53:35 -0700 Subject: [PATCH 045/113] Fix typo --- reports/summary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reports/summary.md b/reports/summary.md index 645c210..d13c03a 100644 --- a/reports/summary.md +++ b/reports/summary.md @@ -30,7 +30,7 @@ Following groupings with subgroupings are available in the summary report ##Response## -The repsonse will include the [standard response parameters](../reports.md#successful-response). +The response will include the [standard response parameters](../reports.md#successful-response). ###Data array### From 5df1dc25af5969d0f46665d871fcba4ac7e47555 Mon Sep 17 00:00:00 2001 From: "Mark J. Lehman" Date: Fri, 27 May 2016 11:36:45 -0700 Subject: [PATCH 046/113] Fix a couple more typos --- reports/summary.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reports/summary.md b/reports/summary.md index d13c03a..13cdb69 100644 --- a/reports/summary.md +++ b/reports/summary.md @@ -7,8 +7,8 @@ Summary report returns the aggregated time entries data. In addition to the [standard request parameters](../reports.md#request-parameters), summaries accept the following additional parameters: * `grouping` * `subgrouping` -* `subgrouping_ids` (boolean) - whether returned items will contain 'ids' key containing coma separated group item ID values -* `grouped_time_entry_ids` (boolean) - whether returned items will contain 'time_entry_ids' key containing coma separated time entries ID values for given item +* `subgrouping_ids` (boolean) - whether returned items will contain 'ids' key containing comma separated group item ID values +* `grouped_time_entry_ids` (boolean) - whether returned items will contain 'time_entry_ids' key containing comma separated time entries ID values for given item Use the grouping and subgrouping params to organize the data as needed. By default `grouping:projects` and `subgrouping:time_entries` From 27bf8860a50f7a3475ff51280f165c699f3b12f4 Mon Sep 17 00:00:00 2001 From: Douglas Chimento Date: Sun, 5 Jun 2016 18:41:02 -0400 Subject: [PATCH 047/113] Adding go code example --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 6b12b47..a3de512 100644 --- a/README.md +++ b/README.md @@ -77,6 +77,9 @@ The Toggl API has moved to Github so you could actively participate in helping u ### PHP ### * [Arend Jan Tetteroo](https://github.com/arendjantetteroo) has written a library for PHP for Toggl API v8, based on the excellent Guzzle library: https://github.com/arendjantetteroo/guzzle-toggl +### Go ### +* [Doug Chimento] (https://github.com/dougEfresh) has written a go wrapper for the API. https://github.com/dougEfresh/gtoggl + ##3rd party apps## * [Federico Vaga](https://github.com/FedericoVaga) has written a little plasmoid for KDE: https://github.com/FedericoVaga/plasmoggl (on opendesktop: http://opendesktop.org/content/show.php/Plasmoggl?content=168536) From 6a224873b33d6c2151c478d923cca01e4073c327 Mon Sep 17 00:00:00 2001 From: Douglas Chimento Date: Sun, 5 Jun 2016 18:42:55 -0400 Subject: [PATCH 048/113] Adding V8 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a3de512..5921228 100644 --- a/README.md +++ b/README.md @@ -78,7 +78,7 @@ The Toggl API has moved to Github so you could actively participate in helping u * [Arend Jan Tetteroo](https://github.com/arendjantetteroo) has written a library for PHP for Toggl API v8, based on the excellent Guzzle library: https://github.com/arendjantetteroo/guzzle-toggl ### Go ### -* [Doug Chimento] (https://github.com/dougEfresh) has written a go wrapper for the API. https://github.com/dougEfresh/gtoggl +* [Doug Chimento] (https://github.com/dougEfresh) has written a Go wrapper for Toggl API v8: https://github.com/dougEfresh/gtoggl ##3rd party apps## * [Federico Vaga](https://github.com/FedericoVaga) has written a little plasmoid for KDE: https://github.com/FedericoVaga/plasmoggl (on opendesktop: http://opendesktop.org/content/show.php/Plasmoggl?content=168536) From 02f90cb8a41e182bf0fc7ce03baadcbcb188b5a7 Mon Sep 17 00:00:00 2001 From: Ervin Weber Date: Tue, 21 Jun 2016 12:03:25 +0300 Subject: [PATCH 049/113] + group_ids added information about group related filters --- reports.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/reports.md b/reports.md index 5af1ba8..5b7c9c3 100644 --- a/reports.md +++ b/reports.md @@ -47,6 +47,8 @@ The following parameters and filters can be used in all of the reports * client_ids: client ids separated by a comma, **0** if you want to filter out time entries without a client * project_ids: project ids separated by a comma, **0** if you want to filter out time entries without a project * user_ids: user ids separated by a comma +* members_of_group_ids: group ids separated by a comma. This limits provided user_ids to the provided group members +* or_members_of_group_ids: group ids separated by a comma. This extends provided user_ids with the provided group members * tag_ids: tag ids separated by a comma, **0** if you want to filter out time entries without a tag * task_ids: task ids separated by a comma, **0** if you want to filter out time entries without a task * time_entry_ids: time entry ids separated by a comma From 9ed05c9bdb72b058e5c9930474039d10431c7c55 Mon Sep 17 00:00:00 2001 From: Benjamin Cooper Date: Thu, 21 Jul 2016 13:58:45 -0500 Subject: [PATCH 050/113] Update README.md Link to the proper repo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6b12b47..bd2c8c2 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ The Toggl API has moved to Github so you could actively participate in helping u ##Code examples## ### Java ### -* [Benno](https://github.com/bennob) has updated JToggl, a Java wrapper for the Toggl API to support v8: http://code.google.com/p/jtoggl/ +* [Benno](https://github.com/bennob) has updated JToggl, a Java wrapper for the Toggl API to support v8: https://github.com/bbaumgartner/jtoggl ### Python ### * [Mosab Ahmad](https://github.com/mos3abof) has created a project using Toggl API to calculate how many hours he should work to achieve monthly goals: https://github.com/mos3abof/toggl_target From 6843ce126b2c09a1ff648bc9640df34aa3396221 Mon Sep 17 00:00:00 2001 From: Benjamin Cooper Date: Thu, 21 Jul 2016 16:13:20 -0500 Subject: [PATCH 051/113] Update dashboard.md The API actually does submit the last 20 tasks as part of the Activity object. --- chapters/dashboard.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapters/dashboard.md b/chapters/dashboard.md index d66c26b..d921298 100644 --- a/chapters/dashboard.md +++ b/chapters/dashboard.md @@ -6,7 +6,7 @@ Dashboard request returns two objects: * Activity * Most active user -The activity object holds the data of 10 latest actions in the workspace. +The activity object holds the data of 20 latest actions in the workspace. Activity object has the following properties * user_id: user ID * project_id: project ID (ID is 0 if time entry doesn't have project connected to it) From 85ace21eba4d32f888e2a7529ef7cd89b2e9cc7a Mon Sep 17 00:00:00 2001 From: zainengineer Date: Thu, 11 Aug 2016 16:49:19 +0930 Subject: [PATCH 052/113] Get project tasks available in pro only Get project tasks available in pro workspace only https://github.com/toggl/toggl_api_docs/issues/194 --- chapters/projects.md | 1 + 1 file changed, 1 insertion(+) diff --git a/chapters/projects.md b/chapters/projects.md index fdc2fb0..66b5b9e 100644 --- a/chapters/projects.md +++ b/chapters/projects.md @@ -156,6 +156,7 @@ Successful response is an array of the project's users ``` ##Get project tasks## +Available only for pro workspaces `GET https://www.toggl.com/api/v8/projects/{project_id}/tasks` Read more about task fields from [here](tasks.md). From f44c37d908108248246865283439c8f78e0e20ab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Fon=C3=B3?= Date: Tue, 6 Sep 2016 18:07:46 +0200 Subject: [PATCH 053/113] Add info about admin editing TE in their ws --- chapters/time_entries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapters/time_entries.md b/chapters/time_entries.md index 1c68463..32e8401 100644 --- a/chapters/time_entries.md +++ b/chapters/time_entries.md @@ -1,7 +1,7 @@ Time Entries ==================== -The requests are scoped with the user whose API token is used. Only his/her time entries are updated, retrieved and created. +The requests are scoped with the user whose API token is used. Only his/her time entries and time entries in a workspace where the user is an admin are updated, retrieved and created. Time entry has the following properties * description: (string, strongly suggested to be used) From b0f82ea849cc1cabd3dac9e956e35c2c9a46ae1a Mon Sep 17 00:00:00 2001 From: Margus Mahler Date: Mon, 12 Sep 2016 11:12:02 +0300 Subject: [PATCH 054/113] docs for ws list of project users, closes #198 --- chapters/project_users.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/chapters/project_users.md b/chapters/project_users.md index ee798d5..f81d80d 100644 --- a/chapters/project_users.md +++ b/chapters/project_users.md @@ -94,6 +94,14 @@ Successful request will return `200 OK`. If the user has no access to delete, yo ##Mass Actions## +###Get list of project users in a Workspace### +```shell +curl -v -u TOKEN:api_token https://www.toggl.com/api/v8/workspaces/{workspace_id}/project_users +``` + +Successful request will return a list of all project users in the workspace. +Note: Does not support the `fields` parameter (hence a `fullname` field won't be returned) + ###Create multiple project users for single project### To create multiple project users for a single project, you must add multiple user ids separated with a comma with the `uid` parameter. From 4c74e97019c8e5530cb7ef80237abd74270858b9 Mon Sep 17 00:00:00 2001 From: Margus Mahler Date: Tue, 13 Sep 2016 10:40:12 +0300 Subject: [PATCH 055/113] removed hrate and cur fields, as pointed out in #201 --- chapters/clients.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/chapters/clients.md b/chapters/clients.md index d0a7f46..c26383f 100644 --- a/chapters/clients.md +++ b/chapters/clients.md @@ -5,8 +5,6 @@ Client has the following properties * name: The name of the client (string, required, unique in workspace) * wid: workspace ID, where the client will be used (integer, required) * notes: Notes for the client (string, not required) -* hrate: The hourly rate for this client (float, not required, available only for pro workspaces) -* cur: The name of the client's currency (string, not required, available only for pro workspaces) * at: timestamp that is sent in the response, indicates the time client was last updated ##Create a client## @@ -55,9 +53,7 @@ Successful response "wid":777, "name":"Very Big Company", "at":"2013-02-26T08:45:28+00:00", - "notes": "Contact: John Jacob Jingleheimer Schmidt", - "hrate": 12, - "cur": "AUD" + "notes": "Contact: John Jacob Jingleheimer Schmidt" } } ``` From b1f73c36b9cbeb56d74f8a10067edbf47aa444a1 Mon Sep 17 00:00:00 2001 From: Matthias Date: Wed, 2 Nov 2016 11:46:38 +0100 Subject: [PATCH 056/113] Added link to togglore --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 0e946c0..11c97de 100644 --- a/README.md +++ b/README.md @@ -54,6 +54,7 @@ The Toggl API has moved to Github so you could actively participate in helping u * [Mikhail Novikov](https://github.com/kurtgn) has created a graphical utility for displaying historical data: https://github.com/kurtgn/chronicl * [Robert Adams](https://github.com/drobertadams) and [Beau Raines](https://github.com/beauraines) have updated [toggl-cli](https://github.com/drobertadams/toggl-cli) to API v8. It provides a set of Python objects for interacting with Toggl, as well as a command-line interface: https://github.com/drobertadams/toggl-cli * [Matthew Downey](https://github.com/matthewdowney) has started a Toggl API wrapper: https://github.com/matthewdowney/TogglPy +* [Matthias Büchi](https://github.com/ynop) has created a simple tool to calculate the difference between the tracked hours in toggle and the hours one should work in a given period: https://github.com/ynop/togglore ### Ruby ### * [Tom Kane](https://github.com/kanet77) has written a Ruby wrapper for Toggl API v8: https://github.com/kanet77/togglv8 From beb9597e6cf902ce375dd929c35f8e5c6e690bb1 Mon Sep 17 00:00:00 2001 From: James Ross Date: Tue, 8 Nov 2016 09:38:49 +0000 Subject: [PATCH 057/113] Improve clarity of authentication When I first came to this section, I read "token" in the 3rd sentence as being the value of the Authorization header, and created a header value of ":api_token". I've tried to re-word it slightly so that it is clearer that it should be ":api_token". --- reports.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reports.md b/reports.md index 5b7c9c3..46791bb 100644 --- a/reports.md +++ b/reports.md @@ -31,7 +31,7 @@ limits set upon token/IP combination. ##Authentication## You can authenticate in the reports API **only** with your API token. For HTTP Basic Auth you have to add the Authorization header with the request. -The token is sent as user name and the string 'api_token' as the password. +The API token is the user name and the string 'api_token' is the password. Whenever possible please use the tools and interfaces provided by your http library to do Basic Auth (for example, curl uses the -u switch for that). ##Request Parameters## From 30c6421319ce0537601af291241eb94908d32330 Mon Sep 17 00:00:00 2001 From: Michael Danilov Date: Mon, 28 Nov 2016 20:01:06 +0600 Subject: [PATCH 058/113] add docs for groups --- chapters/groups.md | 75 ++++++++++++++++++++++++++++++++++++++++++ chapters/workspaces.md | 28 ++++++++++++++++ toggl_api.md | 5 +++ 3 files changed, 108 insertions(+) create mode 100644 chapters/groups.md diff --git a/chapters/groups.md b/chapters/groups.md new file mode 100644 index 0000000..8c8db8b --- /dev/null +++ b/chapters/groups.md @@ -0,0 +1,75 @@ +Groups +==================== + +Group has the following properties +* name: The name of the group (string, required) +* wid: workspace ID, where the group will be used (integer, required) +* at: timestamp that is sent in the response, indicates the time group was last updated + +##Create a group## + +`POST https://www.toggl.com/api/v8/groups` + +Example request + +```shell +curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ + -H "Content-Type: application/json" \ + -d '{"group":{"name":"Developers","wid":777}}' \ + -X POST https://www.toggl.com/api/v8/groups + +``` + +Successful response +```json +{ + "data": { + "id":1239455, + "wid":777, + "name":"Developers", + "at":"2013-02-26T08:45:28+00:00" + } +} +``` + +##Update a group## +`PUT https://www.toggl.com/api/v8/groups/{group_id}` + +Workspace id (wid) can't be changed. + +Example request +```shell +curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ + -H "Content-Type: application/json" \ + -d '{"group":{"name":"Front-end Developers"}}' \ + -X PUT https://www.toggl.com/api/v8/groups/1239455 +``` + +Successful response +```json +{ + "data": { + "id":1239455, + "wid":777, + "name":"Front-end Developers", + "at":"2013-02-26T08:55:28+00:00" + } +} +``` + +##Delete a group## + +`DELETE https://www.toggl.com/api/v8/groups/{group_id}` + +Example request +```shell +curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ + -X DELETE https://www.toggl.com/api/v8/groups/1239455 +``` + +Successful request will return `200 OK`. If the user has no access to delete, you'll get a status code `4xx` + + +##Get workspace groups## + +Retrieving workspace groups is documented [here](workspaces.md#get-workspace-groups). diff --git a/chapters/workspaces.md b/chapters/workspaces.md index 74029d4..aa490c8 100644 --- a/chapters/workspaces.md +++ b/chapters/workspaces.md @@ -225,6 +225,34 @@ Successful response is an array of workspace clients ] ``` +##Get workspace groups## + +To get a successful response, the token owner must be workspace admin. +`GET https://www.toggl.com/api/v8/workspaces/{workspace_id}/groups` + +Example request +```shell +curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ +-X GET https://www.toggl.com/api/v8/workspaces/777/groups +``` + +Successful response is an array of workspace groups +```json +[ + { + "id":123, + "wid":777, + "name":"Management", + "at":"2013-03-06T09:06:13+00:00" + },{ + "id":987, + "wid":777, + "name":"Developers", + "at":"2013-03-06T09:05:40+00:00" + } +] +``` + ##Get workspace projects## To get a successful response, the token owner must be workspace admin. diff --git a/toggl_api.md b/toggl_api.md index 5d6554e..8667acc 100644 --- a/toggl_api.md +++ b/toggl_api.md @@ -79,6 +79,10 @@ If authentication fails, HTTP status code 403 is returned. You can read more abo - delete a client - get clients visible to user - get client projects +* [Groups](chapters/groups.md) + - create a group + - update a group + - delete a group * [Projects](chapters/projects.md) - create a project - get project data @@ -123,6 +127,7 @@ If authentication fails, HTTP status code 403 is returned. You can read more abo - get user workspaces - get workspace users - get workspace clients + - get workspace groups - get workspace projects - get workspace tasks - get workspace tags From ec08f9bb21ab89a0f81acb95ff72d043e7a71119 Mon Sep 17 00:00:00 2001 From: vincent guyader Date: Wed, 7 Dec 2016 13:37:25 +0100 Subject: [PATCH 059/113] Update README.md add R implementation --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 0e946c0..30598c7 100644 --- a/README.md +++ b/README.md @@ -88,3 +88,7 @@ The Toggl API has moved to Github so you could actively participate in helping u ### Perl ### * [Jason Kruczynski] (https://github.com/jkruczynski) has written a perl wrapper for the API. It creates and authenticates a session for API V8 or API V2 depending on the URL. It implements a few functions for exporting reports. https://github.com/jkruczynski/Toggl-API-Wrapper-Perl + +### R ### +* [Vincent Guyader] (http://thinkr.fr) has written a simple R and Rstudio implementation for the API. https://github.com/ThinkRstat/togglr + From 5e06019e78c8c3636fa82e7f1c9cb5dbcb2cab2b Mon Sep 17 00:00:00 2001 From: David Cako Date: Tue, 20 Dec 2016 14:47:18 -0700 Subject: [PATCH 060/113] Update README.md --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index fea3630..66e94ff 100644 --- a/README.md +++ b/README.md @@ -55,6 +55,7 @@ The Toggl API has moved to Github so you could actively participate in helping u * [Robert Adams](https://github.com/drobertadams) and [Beau Raines](https://github.com/beauraines) have updated [toggl-cli](https://github.com/drobertadams/toggl-cli) to API v8. It provides a set of Python objects for interacting with Toggl, as well as a command-line interface: https://github.com/drobertadams/toggl-cli * [Matthew Downey](https://github.com/matthewdowney) has started a Toggl API wrapper: https://github.com/matthewdowney/TogglPy * [Matthias Büchi](https://github.com/ynop) has created a simple tool to calculate the difference between the tracked hours in toggle and the hours one should work in a given period: https://github.com/ynop/togglore +* [David Cako](https://github.com/david-cako) has written an efficient command line interface for inputting time-insensitive toggl entries: https://github.com/david-cako/toggl-hammer ### Ruby ### * [Tom Kane](https://github.com/kanet77) has written a Ruby wrapper for Toggl API v8: https://github.com/kanet77/togglv8 From d3f9cd744a1f954802a1f0899e08644a3bfafd34 Mon Sep 17 00:00:00 2001 From: Cezary Kosko Date: Mon, 9 Jan 2017 16:20:55 +0100 Subject: [PATCH 061/113] CORS docs added --- chapters/cors.md | 77 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 chapters/cors.md diff --git a/chapters/cors.md b/chapters/cors.md new file mode 100644 index 0000000..ac91772 --- /dev/null +++ b/chapters/cors.md @@ -0,0 +1,77 @@ +CORS whitelists +==================== + +A CORS whitelist record has the following properties +* id: record ID, where the record will be saved (integer) +* user_id: user ID, for whom the domain is whitelisted (integer) +* domain: the whitelisted domain (string) + +Record id (id) can't be changed on update. + +##Actions## +###Create an entry### + +`POST https://www.toggl.com/api/v9/me/cors` + +Example request + +```shell +curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ + -H "Content-Type: application/json" \ + -d '{"domain":"url.com"}' \ + -X POST https://www.toggl.com/api/v9/me/cors + +``` + +Successful response +```json +{ + "id":1335076912, + "domain":"url.com", + "user_id":456 +} +``` + +###Get entries for current user### + +`GET https://www.toggl.com/api/v9/me/cors` + +Example request + +```shell +curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ + -X GET https://www.toggl.com/api/v9/cors +``` + +Successful response +```json +[ + { + "id":1335076912, + "domain":"url.com", + "user_id":456 + }, + { + "id":1335076982, + "domain":"url2.com", + "user_id":456 + }, + { + "id":1335076993, + "domain":"url3.com", + "user_id":456 + } +] +``` + +###Delete an entry### + +`DELETE https://www.toggl.com/api/v9/me/cors/{id}` + +Example request +```shell +curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ + -X DELETE https://www.toggl.com/api/v9/me/cors/1335076912 +``` + +Successful request will return `200 OK`. If the user has no access to delete, you'll get a status code `4xx` \ No newline at end of file From 70bcde58cc160eebfe4ade2e3e3d1bcf0f6c9c43 Mon Sep 17 00:00:00 2001 From: Bjarne Bonde Date: Wed, 18 Jan 2017 09:08:17 +0100 Subject: [PATCH 062/113] Updated readme with PHP implementation --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 66e94ff..f12ac4a 100644 --- a/README.md +++ b/README.md @@ -78,6 +78,7 @@ The Toggl API has moved to Github so you could actively participate in helping u ### PHP ### * [Arend Jan Tetteroo](https://github.com/arendjantetteroo) has written a library for PHP for Toggl API v8, based on the excellent Guzzle library: https://github.com/arendjantetteroo/guzzle-toggl +* [Morning Train](https://morningtrain.dk) has written PHP classes for Toggl API v8 (It is based on Guzzle 6): https://github.com/Morning-Train/toggl-api ### Go ### * [Doug Chimento] (https://github.com/dougEfresh) has written a Go wrapper for Toggl API v8: https://github.com/dougEfresh/gtoggl From db9544c160595a55b5c0148881ebb4b695c5c2cd Mon Sep 17 00:00:00 2001 From: Margus Mahler Date: Wed, 25 Jan 2017 11:45:06 +0200 Subject: [PATCH 063/113] CORS listing has changed --- toggl_api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/toggl_api.md b/toggl_api.md index 8667acc..150ba10 100644 --- a/toggl_api.md +++ b/toggl_api.md @@ -8,7 +8,7 @@ The result of each action is communicated via standard HTTP response codes. ###CORS### -If you wish to use the API using CORS, we'll need to whitelist you first. Please send us a note at support@toggl.com to whitelist your domain(s). +If you wish to use the API using CORS, we'll need to whitelist you first. Please refer to the [CORS documentation](https://github.com/toggl/toggl_api_docs/blob/master/chapters/cors.md) ###Successful requests### From 54b630d444085dfb6634c163641d9786c5863622 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Madis=20L=C3=B5hmus?= Date: Wed, 25 Jan 2017 11:49:37 +0200 Subject: [PATCH 064/113] Fix typo --- chapters/cors.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/chapters/cors.md b/chapters/cors.md index ac91772..cbaf1da 100644 --- a/chapters/cors.md +++ b/chapters/cors.md @@ -40,7 +40,7 @@ Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ - -X GET https://www.toggl.com/api/v9/cors + -X GET https://www.toggl.com/api/v9/me/cors ``` Successful response @@ -74,4 +74,4 @@ curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -X DELETE https://www.toggl.com/api/v9/me/cors/1335076912 ``` -Successful request will return `200 OK`. If the user has no access to delete, you'll get a status code `4xx` \ No newline at end of file +Successful request will return `200 OK`. If the user has no access to delete, you'll get a status code `4xx` From 8df1d0f89fc8dca2aea3ca274a76e0eac05dca70 Mon Sep 17 00:00:00 2001 From: Joshua Baker Date: Fri, 3 Feb 2017 12:06:03 -0800 Subject: [PATCH 065/113] Improve the clarity of "Request Parameters" --- reports.md | 48 +++++++++++++++++++++++------------------------- 1 file changed, 23 insertions(+), 25 deletions(-) diff --git a/reports.md b/reports.md index 46791bb..dc685e8 100644 --- a/reports.md +++ b/reports.md @@ -39,31 +39,29 @@ Whenever possible please use the tools and interfaces provided by your http libr The API expects the request parameters as the query string of the URL. The following parameters and filters can be used in all of the reports -* user_agent: string, **required**, the name of your application or your email address so we can get in touch in case you're doing something wrong. -* workspace_id: integer, **required**. The workspace whose data you want to access. -* since: string, ISO 8601 date (YYYY-MM-DD), by default until - 6 days. -* until: string, ISO 8601 date (YYYY-MM-DD), by default today -* billable: possible values: yes/no/both, default both -* client_ids: client ids separated by a comma, **0** if you want to filter out time entries without a client -* project_ids: project ids separated by a comma, **0** if you want to filter out time entries without a project -* user_ids: user ids separated by a comma -* members_of_group_ids: group ids separated by a comma. This limits provided user_ids to the provided group members -* or_members_of_group_ids: group ids separated by a comma. This extends provided user_ids with the provided group members -* tag_ids: tag ids separated by a comma, **0** if you want to filter out time entries without a tag -* task_ids: task ids separated by a comma, **0** if you want to filter out time entries without a task -* time_entry_ids: time entry ids separated by a comma -* description: string, time entry description -* without_description: true/false, filters out the time entries which do not have a description ('(no description)') -* order_field: - * date/description/duration/user in detailed reports - * title/duration/amount in summary reports - * title/day1/day2/day3/day4/day5/day6/day7/week_total in weekly report -* order_desc: on/off, `on` for descending and `off` for ascending order -* distinct_rates: on/off, default off -* rounding: on/off, default off, rounds time according to workspace settings -* display_hours: decimal/minutes, display hours with minutes or as a decimal number, default minutes - -NB! Maximum date span (until - since) is one year. +* `user_agent`: **Required**. The name of your application or your email address so we can get in touch in case you're doing something wrong. +* `workspace_id`: **Required**. The workspace whose data you want to access. +* `since`: ISO 8601 date (YYYY-MM-DD) format. Defaults to 6 days before `until`. +* `until`: ISO 8601 date (YYYY-MM-DD) format. Defaults to today's date. (Note: Maximum date span (`until - since`) is one year.) +* `billable`: "yes", "no", or "both". Defaults to "both". +* `client_ids`: A list of client IDs separated by a comma. Use "0" if you want to filter out time entries without a client. +* `project_ids`: A list of project IDs separated by a comma. Use "0" if you want to filter out time entries without a project. +* `user_ids`: A list of user IDs separated by a comma. +* `members_of_group_ids`: A list of group IDs separated by a comma. This limits provided `user_ids` to the members of the given groups. +* `or_members_of_group_ids`: A list of group IDs separated by a comma. This extends provided `user_ids` with the members of the given groups. +* `tag_ids`: A list of tag IDs separated by a comma. Use "0" if you want to filter out time entries without a tag. +* `task_ids`: A list of task IDs separated by a comma. Use "0" if you want to filter out time entries without a task. +* `time_entry_ids`: A list of time entry IDs separated by a comma. +* `description`: Matches against time entry descriptions. +* `without_description`: "true" or "false". Filters out the time entries which do not have a description (literally "(no description)"). +* `order_field`: + * For detailed reports: "date", "description", "duration", or "user" + * For summary reports: "title", "duration", or "amount" + * For weekly reports: "title", "day1", "day2", "day3", "day4", "day5", "day6", "day7", or "week_total" +* `order_desc`: "on" for descending, or "off" for ascending order. +* `distinct_rates`: "on" or "off". Defaults to "off". +* `rounding`: "on" or "off". Defaults to "off". Rounds time according to workspace settings. +* `display_hours`: "decimal" or "minutes". Defaults to "minutes". Determines whether to display hours as a decimal number or with minutes. ##Successful response## From de49e0c5d9bcbe23caaa58efcb38d775761cdb4d Mon Sep 17 00:00:00 2001 From: Peteous Date: Fri, 17 Feb 2017 10:09:01 -0600 Subject: [PATCH 066/113] Fixed typo of 'toggle' in Python section to 'Toggl' --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f12ac4a..ce15f86 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,7 @@ The Toggl API has moved to Github so you could actively participate in helping u * [Mikhail Novikov](https://github.com/kurtgn) has created a graphical utility for displaying historical data: https://github.com/kurtgn/chronicl * [Robert Adams](https://github.com/drobertadams) and [Beau Raines](https://github.com/beauraines) have updated [toggl-cli](https://github.com/drobertadams/toggl-cli) to API v8. It provides a set of Python objects for interacting with Toggl, as well as a command-line interface: https://github.com/drobertadams/toggl-cli * [Matthew Downey](https://github.com/matthewdowney) has started a Toggl API wrapper: https://github.com/matthewdowney/TogglPy -* [Matthias Büchi](https://github.com/ynop) has created a simple tool to calculate the difference between the tracked hours in toggle and the hours one should work in a given period: https://github.com/ynop/togglore +* [Matthias Büchi](https://github.com/ynop) has created a simple tool to calculate the difference between the tracked hours in Toggl and the hours one should work in a given period: https://github.com/ynop/togglore * [David Cako](https://github.com/david-cako) has written an efficient command line interface for inputting time-insensitive toggl entries: https://github.com/david-cako/toggl-hammer ### Ruby ### From 2ea96851bdc137898a1fc92968fed457b5a8e7d5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marten=20Prie=C3=9F?= Date: Tue, 7 Mar 2017 09:55:49 +0100 Subject: [PATCH 067/113] Update README.md added java report api wrapper --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index f12ac4a..46ed7ba 100644 --- a/README.md +++ b/README.md @@ -48,6 +48,7 @@ The Toggl API has moved to Github so you could actively participate in helping u ### Java ### * [Benno](https://github.com/bennob) has updated JToggl, a Java wrapper for the Toggl API to support v8: https://github.com/bbaumgartner/jtoggl +* [rocketbase-io](https://github.com/rocketbase-io) build Toggl-Report-Api, a Java wrapper for the Toggl Report API: https://github.com/rocketbase-io/toggl-report-api ### Python ### * [Mosab Ahmad](https://github.com/mos3abof) has created a project using Toggl API to calculate how many hours he should work to achieve monthly goals: https://github.com/mos3abof/toggl_target From b5187f701fcc5f2028191334a65702b491fb55d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marten=20Prie=C3=9F?= Date: Sun, 19 Mar 2017 15:42:48 +0100 Subject: [PATCH 068/113] Update README.md added new 3rd party app --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index f12ac4a..9bee60b 100644 --- a/README.md +++ b/README.md @@ -88,6 +88,7 @@ The Toggl API has moved to Github so you could actively participate in helping u ##3rd party apps## * [Federico Vaga](https://github.com/FedericoVaga) has written a little plasmoid for KDE: https://github.com/FedericoVaga/plasmoggl (on opendesktop: http://opendesktop.org/content/show.php/Plasmoggl?content=168536) +* [rocketbase-io](https://github.com/rocketbase-io/toggl-reporter) has written a tiny SpringBoot-Application, build with vaadin and mongodb, that pulls your TimeEntries from toggl. The stored information allow a fine grained reporting and analysis that aren't possible within toggl (like detailed working hours in comparison between team-members and many more). A [docker-image](https://hub.docker.com/r/rocketbaseio/toggl-reporter/) is also provided... ### Perl ### * [Jason Kruczynski] (https://github.com/jkruczynski) has written a perl wrapper for the API. It creates and authenticates a session for API V8 or API V2 depending on the URL. It implements a few functions for exporting reports. https://github.com/jkruczynski/Toggl-API-Wrapper-Perl From 53b6e7866d8f9d0fbdab8c70bff679d7a54d86e9 Mon Sep 17 00:00:00 2001 From: Dominique Clijsters Date: Sun, 19 Mar 2017 19:41:57 +0100 Subject: [PATCH 069/113] Update users properties list Insert fullname like listed in the example responses, Insert some missing spaces. --- chapters/users.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/chapters/users.md b/chapters/users.md index e32d25b..484aafb 100644 --- a/chapters/users.md +++ b/chapters/users.md @@ -5,14 +5,15 @@ User has the following properties * api_token: (string) * default_wid: default workspace id (integer) * email: (string) +* fullname: (string) * jquery_timeofday_format: (string) -* jquery_date_format:(string) +* jquery_date_format: (string) * timeofday_format: (string) * date_format: (string) * store_start_and_stop_time: whether start and stop time are saved on time entry (boolean) * beginning_of_week: (integer 0-6, Sunday=0) * language: user's language (string) -* image_url: url with the user's profile picture(string) +* image_url: url with the user's profile picture (string) * sidebar_piechart: should a piechart be shown on the sidebar (boolean) * at: timestamp of last changes * new_blog_post: an object with toggl blog post title and link From af72f77a062604bd29f4b57c5e5223a871a256fd Mon Sep 17 00:00:00 2001 From: Dominique Clijsters Date: Sun, 19 Mar 2017 19:50:02 +0100 Subject: [PATCH 070/113] Insert missing comma in JSON response --- chapters/users.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapters/users.md b/chapters/users.md index e32d25b..ee980c4 100644 --- a/chapters/users.md +++ b/chapters/users.md @@ -122,7 +122,7 @@ Successful response "name":"Important project", "billable":false, "active":false, - "at":"2013-03-06T09:13:31+00:00" + "at":"2013-03-06T09:13:31+00:00", "color":"5" } ], From 8e131eb4b606602d84e163e3bb2a86c338fc4646 Mon Sep 17 00:00:00 2001 From: Vitalii Zurian Date: Mon, 27 Mar 2017 13:00:48 +0200 Subject: [PATCH 071/113] Update detailed.md --- reports/detailed.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/reports/detailed.md b/reports/detailed.md index 8b4a601..35c4e60 100644 --- a/reports/detailed.md +++ b/reports/detailed.md @@ -1,19 +1,19 @@ -#Detailed report# +# Detailed report The detailed report returns the time entries for the requested parameters/filters. -##Request## +## Request In addition to the [standard request parameters](../reports.md#request-parameters), there is one additional parameter in detailed reports. As the returned data is paginated you have to add the page parameter. * `page`: integer, default 1 -##Response## +## Response The response will include the [standard response parameters](../reports.md#successful-response), as well as: * `total_count`: total number of time entries that were found for the request. Pay attention to the fact that the amount of time entries returned is max the number which is returned with the `per_page` field (currently 50). To get the next batch of time entries you need to do a new request with same parameters and the incremented `page` parameter. It is not possible to get all the time entries with one request. * `per_page`: how many time entries are displayed in one request -###Data array### +### Data array Time entry data * id: time entry id @@ -35,7 +35,7 @@ Time entry data * cur: billable amount currency * tags: array of tag names, which assigned for the time entry -##Example## +## Example Example request ```shell From 20b166a3a891b27f42ddf8fd75ef3bbfa57ab717 Mon Sep 17 00:00:00 2001 From: Vitalii Zurian Date: Thu, 30 Mar 2017 16:14:33 +0200 Subject: [PATCH 072/113] Update README.md --- README.md | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index f12ac4a..38938b1 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ For changing data, including tracking time, you'll need to use the **Toggl API** If you want to get time entries of all the workspace users and aggregated data for reporting, you need to use the read-only **Reports API**, which gives you many options for filtering, grouping and sorting. -##The API Format## +## The API Format The API accepts only JSON requests. Please make sure you're setting `Content-Type: application/json`in your request header. Each request returns a **JSON-encoded** body. @@ -25,7 +25,7 @@ Please do note that the times and dates are stored in UTC (GMT), on return the d For rate limiting we have implemented a [Leaky bucket](http://en.wikipedia.org/wiki/Leaky_bucket). When a limit has been hit the request will get a HTTP 429 response and it's the task of the client to sleep/wait until bucket is empty. Limits will and can change during time, but a safe window will be *1 request per second*. Limiting is applied per api token per IP, meaning two users from the same IP will get their rate allocated separately. -###Example requests### +### Example requests The example requests here are done using a command line tool called [cURL](http://en.wikipedia.org/wiki/CURL). If you want to try the requests out yourself, you can download cURL from [here](http://curl.haxx.se/download.html). It is available for all possible operating systems. @@ -35,21 +35,21 @@ Under Ubuntu installing cURL is very easy: sudo apt-get install curl ``` -##API token## +## API token Each user in Toggl.com has an API token. They can find it under "My Profile" in their Toggl account. -##Help us towards a better API## +## Help us towards a better API The Toggl API has moved to Github so you could actively participate in helping us making the API better. If you have any requests or you found a bug, you can use Github issues to let us know. You can also fork the docs and send a pull request with improvements -##Code examples## +## Code examples -### Java ### +### Java * [Benno](https://github.com/bennob) has updated JToggl, a Java wrapper for the Toggl API to support v8: https://github.com/bbaumgartner/jtoggl -### Python ### +### Python * [Mosab Ahmad](https://github.com/mos3abof) has created a project using Toggl API to calculate how many hours he should work to achieve monthly goals: https://github.com/mos3abof/toggl_target * [Mikhail Novikov](https://github.com/kurtgn) has created a graphical utility for displaying historical data: https://github.com/kurtgn/chronicl * [Robert Adams](https://github.com/drobertadams) and [Beau Raines](https://github.com/beauraines) have updated [toggl-cli](https://github.com/drobertadams/toggl-cli) to API v8. It provides a set of Python objects for interacting with Toggl, as well as a command-line interface: https://github.com/drobertadams/toggl-cli @@ -57,41 +57,41 @@ The Toggl API has moved to Github so you could actively participate in helping u * [Matthias Büchi](https://github.com/ynop) has created a simple tool to calculate the difference between the tracked hours in toggle and the hours one should work in a given period: https://github.com/ynop/togglore * [David Cako](https://github.com/david-cako) has written an efficient command line interface for inputting time-insensitive toggl entries: https://github.com/david-cako/toggl-hammer -### Ruby ### +### Ruby * [Tom Kane](https://github.com/kanet77) has written a Ruby wrapper for Toggl API v8: https://github.com/kanet77/togglv8 -### Node.js ### +### Node.js * [Damian Mee](https://github.com/meeDamian) has written a CLI tool in Node.js for Toggl API v8: https://github.com/meeDamian/toggl-cli * [Alexander Makarenko](https://github.com/estliberitas) has written a library for Node.js for Toggl API v8: https://github.com/7eggs/node-toggl-api -### C++ ### +### C++ * TogglDesktop has an [open source, cross platform library](https://github.com/toggl/toggldesktop/tree/master/src/lib) that can be reused in your own apps. -### .NET ### +### .NET * Toggl mobile apps have a [shared C# library (Phoebe)](https://github.com/toggl/mobile/tree/master/Phoebe) which provides access to API and also some common clientside business logic we use. Feel free to use as little or much of it you want. * [Ilya Pirozhenko](https://github.com/sochix) has written a .NET library: https://www.nuget.org/packages/TogglAPI.Net/ -### Scala ### +### Scala * [Gabriele Alese](https://github.com/gabalese) has written a command line client for Toggl: https://github.com/gabalese/toggl-cli -### PHP ### +### PHP * [Arend Jan Tetteroo](https://github.com/arendjantetteroo) has written a library for PHP for Toggl API v8, based on the excellent Guzzle library: https://github.com/arendjantetteroo/guzzle-toggl * [Morning Train](https://morningtrain.dk) has written PHP classes for Toggl API v8 (It is based on Guzzle 6): https://github.com/Morning-Train/toggl-api -### Go ### +### Go * [Doug Chimento] (https://github.com/dougEfresh) has written a Go wrapper for Toggl API v8: https://github.com/dougEfresh/gtoggl -### Elixir ### +### Elixir * [Víctor Viruete](https://github.com/hopsor) has written an Elixir wrapper for Toggl API v8 and Reports API: https://github.com/diacode/togglex -##3rd party apps## +## 3rd party apps * [Federico Vaga](https://github.com/FedericoVaga) has written a little plasmoid for KDE: https://github.com/FedericoVaga/plasmoggl (on opendesktop: http://opendesktop.org/content/show.php/Plasmoggl?content=168536) -### Perl ### +### Perl * [Jason Kruczynski] (https://github.com/jkruczynski) has written a perl wrapper for the API. It creates and authenticates a session for API V8 or API V2 depending on the URL. It implements a few functions for exporting reports. https://github.com/jkruczynski/Toggl-API-Wrapper-Perl -### R ### +### R * [Vincent Guyader] (http://thinkr.fr) has written a simple R and Rstudio implementation for the API. https://github.com/ThinkRstat/togglr From 0c7396d09d75a29a4ed5c1b049cf501e9d733f03 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filip=20Dupanovi=C4=87?= Date: Thu, 30 Mar 2017 21:14:25 +0200 Subject: [PATCH 073/113] Fix MD syntax for user references --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index f12ac4a..3fd0d2d 100644 --- a/README.md +++ b/README.md @@ -81,7 +81,7 @@ The Toggl API has moved to Github so you could actively participate in helping u * [Morning Train](https://morningtrain.dk) has written PHP classes for Toggl API v8 (It is based on Guzzle 6): https://github.com/Morning-Train/toggl-api ### Go ### -* [Doug Chimento] (https://github.com/dougEfresh) has written a Go wrapper for Toggl API v8: https://github.com/dougEfresh/gtoggl +* [Doug Chimento](https://github.com/dougEfresh) has written a Go wrapper for Toggl API v8: https://github.com/dougEfresh/gtoggl ### Elixir ### * [Víctor Viruete](https://github.com/hopsor) has written an Elixir wrapper for Toggl API v8 and Reports API: https://github.com/diacode/togglex @@ -90,8 +90,8 @@ The Toggl API has moved to Github so you could actively participate in helping u * [Federico Vaga](https://github.com/FedericoVaga) has written a little plasmoid for KDE: https://github.com/FedericoVaga/plasmoggl (on opendesktop: http://opendesktop.org/content/show.php/Plasmoggl?content=168536) ### Perl ### -* [Jason Kruczynski] (https://github.com/jkruczynski) has written a perl wrapper for the API. It creates and authenticates a session for API V8 or API V2 depending on the URL. It implements a few functions for exporting reports. https://github.com/jkruczynski/Toggl-API-Wrapper-Perl +* [Jason Kruczynski](https://github.com/jkruczynski) has written a perl wrapper for the API. It creates and authenticates a session for API V8 or API V2 depending on the URL. It implements a few functions for exporting reports. https://github.com/jkruczynski/Toggl-API-Wrapper-Perl ### R ### -* [Vincent Guyader] (http://thinkr.fr) has written a simple R and Rstudio implementation for the API. https://github.com/ThinkRstat/togglr +* [Vincent Guyader](http://thinkr.fr) has written a simple R and Rstudio implementation for the API. https://github.com/ThinkRstat/togglr From c550e185eeb7c1d998907196e91f1a03cd109523 Mon Sep 17 00:00:00 2001 From: Jan Oris Date: Sun, 2 Apr 2017 21:08:17 +0200 Subject: [PATCH 074/113] Add ixudra/toggl package to readme file --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index f12ac4a..7d61e60 100644 --- a/README.md +++ b/README.md @@ -79,6 +79,7 @@ The Toggl API has moved to Github so you could actively participate in helping u ### PHP ### * [Arend Jan Tetteroo](https://github.com/arendjantetteroo) has written a library for PHP for Toggl API v8, based on the excellent Guzzle library: https://github.com/arendjantetteroo/guzzle-toggl * [Morning Train](https://morningtrain.dk) has written PHP classes for Toggl API v8 (It is based on Guzzle 6): https://github.com/Morning-Train/toggl-api +* [Ixudra](https://ixudra.be) has written a Laravel PHP library for Toggl API v8: https://github.com/ixudra/toggl ### Go ### * [Doug Chimento] (https://github.com/dougEfresh) has written a Go wrapper for Toggl API v8: https://github.com/dougEfresh/gtoggl From 6f61af7cd8388a8004ca6cdd905c01731711a869 Mon Sep 17 00:00:00 2001 From: Margus Mahler Date: Wed, 5 Apr 2017 12:40:34 +0300 Subject: [PATCH 075/113] first hints of a new API version.... --- api_v9_repots_v3_basics.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 api_v9_repots_v3_basics.md diff --git a/api_v9_repots_v3_basics.md b/api_v9_repots_v3_basics.md new file mode 100644 index 0000000..89e4087 --- /dev/null +++ b/api_v9_repots_v3_basics.md @@ -0,0 +1,29 @@ +# API v9, Reports API v3 - Basics and recommendations + +Given the age of API v8 and Reports API v2 we've are working for new versions of those API-s, +old API-s will still be up and running and there will be an official announcement before the final deprecation. +The documentation for the new API endpoints will become available gradually and there can and will be changes at first. + +## Authentication options + - api_token and basic auth header + - username and password to get a session cookie + + This list may get aditional options + +## Generic responses and what to do +We're using standard HTTP status codes and kindly ask the API clients to respect some recommendations: + - in case of 4xx error - don't try another request with the same payload, inspect the response body, most of the times it has a readable message + - in case of 5xx error - have a random delay before the next request + - in case of 429 (Too Many Requests) - back off for a few minutes (you can expect a rate of 1req/sec to be available) + - in case of 410 (Gone) - don't try this endpoint again + - in case of 402 (Payment required) - workspace should be upgraded to have access to said feature, don't repeat the request until that has happened + +## General principles + - API format is JSON (be nice and include a `Content-type: application/json` header to your request) + - in case of an update request, send only the fields that have changed + - do not include fields that aren't available for current workspace subscription level (example: on a free plan don't send the default workspace rate when updating workspace) + - fetch only the data you need + +## "Scopes" +Endpoints have been grouped by the scope of the entity using it. +Data that's for the currently logged in user is under `/me/*` endpoints, data for one workspace is under `/workspace/{workspace_id}/*` endpoints. From a4ec0da36e3e33f055cb6b4ad2fa38ed4b8c21d1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Fon=C3=B3?= Date: Tue, 2 May 2017 12:16:16 +0200 Subject: [PATCH 076/113] fix header formatting --- chapters/users.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/chapters/users.md b/chapters/users.md index ec1e414..41aa973 100644 --- a/chapters/users.md +++ b/chapters/users.md @@ -162,7 +162,7 @@ Successful response } ``` -##Update user data## +## Update user data ## `PUT https://www.toggl.com/api/v8/me` @@ -229,7 +229,7 @@ Successful response } ``` -##Reset API token## +## Reset API token ## `POST https://www.toggl.com/api/v8/reset_token` Example request @@ -245,11 +245,11 @@ Successful response is a string with the new API token: ``` -##Get workspace users## +## Get workspace users ## Retrieving workspace users is documented [here](workspaces.md#get-workspace-users). -##Sign up new user## +## Sign up new user ## To create a user you must provide these parameters for the user: * email: a valid email for the user whose account is created (string, required) From 1c8f4409d6d86ec7854ec421d71116acdd0b180c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Fon=C3=B3?= Date: Tue, 2 May 2017 13:47:06 +0200 Subject: [PATCH 077/113] remove API_token from user signup example --- chapters/users.md | 1 - 1 file changed, 1 deletion(-) diff --git a/chapters/users.md b/chapters/users.md index 41aa973..4afce00 100644 --- a/chapters/users.md +++ b/chapters/users.md @@ -271,7 +271,6 @@ Successful response includes created user's data and API token { "data":{ "id":599978901, - "api_token":"808lolae4eab897cce9729a53642124effe", "default_wid":983493, "email":"test.user@toggl.com", "fullname":"Test User", From 9917c7b75c8646bafc2d91255c91f5a0b4c8e389 Mon Sep 17 00:00:00 2001 From: Paul Scharf Date: Wed, 17 May 2017 10:08:57 +0200 Subject: [PATCH 078/113] Update reference to C# libraries in mobile app --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index de98194..8cd85e3 100644 --- a/README.md +++ b/README.md @@ -71,7 +71,7 @@ The Toggl API has moved to Github so you could actively participate in helping u ### .NET -* Toggl mobile apps have a [shared C# library (Phoebe)](https://github.com/toggl/mobile/tree/master/Phoebe) which provides access to API and also some common clientside business logic we use. Feel free to use as little or much of it you want. +* The Toggl mobile apps have [shared C# libraries](https://github.com/toggl/mobileapp) which provide access to the API and also common clientside business logic we use. Feel free to use as little or much of it as you want. * [Ilya Pirozhenko](https://github.com/sochix) has written a .NET library: https://www.nuget.org/packages/TogglAPI.Net/ ### Scala From e85aac564744340daa6f249fcd420c9ad6ccfbad Mon Sep 17 00:00:00 2001 From: Charles Suggs Date: Wed, 5 Jul 2017 23:27:48 -0500 Subject: [PATCH 079/113] JSON arrays end with no comma. --- chapters/project_users.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/chapters/project_users.md b/chapters/project_users.md index f81d80d..183cee6 100644 --- a/chapters/project_users.md +++ b/chapters/project_users.md @@ -11,15 +11,15 @@ Project user has the following properties Workspace id (wid), project id (pid) and user id (uid) can't be changed on update. -###Additional fields### +### Additional fields It's possible to get user's fullname. For that you have to send the `fields` parameter in request with desired property name. * fullname: full name of the user, who is added to the project -##Actions for single project user## +## Actions for single project user -###Create a project user### +### Create a project user `POST https://www.toggl.com/api/v8/project_users` @@ -49,7 +49,7 @@ Successful response ``` -###Update a project user### +### Update a project user `PUT https://www.toggl.com/api/v8/project_users/{project_user_id}` @@ -79,7 +79,7 @@ Successful response } ``` -###Delete a project user### +### Delete a project user `DELETE https://www.toggl.com/api/v8/project_users/{project_user_id}` @@ -92,9 +92,9 @@ curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ Successful request will return `200 OK`. If the user has no access to delete, you'll get a status code `4xx` -##Mass Actions## +## Mass Actions -###Get list of project users in a Workspace### +### Get list of project users in a Workspace ```shell curl -v -u TOKEN:api_token https://www.toggl.com/api/v8/workspaces/{workspace_id}/project_users ``` @@ -102,7 +102,7 @@ curl -v -u TOKEN:api_token https://www.toggl.com/api/v8/workspaces/{workspace_id Successful request will return a list of all project users in the workspace. Note: Does not support the `fields` parameter (hence a `fullname` field won't be returned) -###Create multiple project users for single project### +### Create multiple project users for single project To create multiple project users for a single project, you must add multiple user ids separated with a comma with the `uid` parameter. `POST https://www.toggl.com/api/v8/project_users` @@ -127,28 +127,28 @@ Successful response is an array of project_users. "uid":1267998, "wid":99, "manager":true, - "rate":4, + "rate":4 },{ "id":4692192, "pid":777, "uid":29624, "wid":99, "manager":true, - "rate":4, + "rate":4 },{ "id":4692191, "pid":777, "uid":112047, "wid":99, "manager":true, - "rate":4, + "rate":4 } ] } ``` -###Mass update for project users### +### Mass update for project users By supplying multiple project user ids, you can mass update project users. `PUT https://www.toggl.com/api/v8/project_users/{project_user_ids}` @@ -195,7 +195,7 @@ Successful response is an array of project_users. } ``` -###Delete multiple project users### +### Delete multiple project users By supplying multiple project user ids, you can mass delete project users. `DELETE https://www.toggl.com/api/v8/project_users/{project_user_ids}` From 6061dce2a6d345fef3c3d9ce0cc09c47a3eb0efd Mon Sep 17 00:00:00 2001 From: Charles Suggs Date: Wed, 5 Jul 2017 23:28:07 -0500 Subject: [PATCH 080/113] Correct headings for markdown. --- chapters/authentication.md | 6 +++--- chapters/clients.md | 14 +++++++------- chapters/cors.md | 8 ++++---- chapters/dashboard.md | 2 +- chapters/groups.md | 8 ++++---- chapters/projects.md | 18 +++++++++--------- chapters/tags.md | 6 +++--- chapters/tasks.md | 16 ++++++++-------- chapters/time_entries.md | 16 ++++++++-------- chapters/workspace_users.md | 8 ++++---- chapters/workspaces.md | 18 +++++++++--------- reports.md | 12 ++++++------ toggl_api.md | 10 +++++----- 13 files changed, 71 insertions(+), 71 deletions(-) diff --git a/chapters/authentication.md b/chapters/authentication.md index 4c30ae7..4de6db2 100644 --- a/chapters/authentication.md +++ b/chapters/authentication.md @@ -13,7 +13,7 @@ For HTTP Basic Auth you have to add the Authorization header with the request. T If authentication fails, HTTP status code 403 is returned. -## HTTP Basic Auth with e-mail and password ## +## HTTP Basic Auth with e-mail and password Example request ([See also chapter about getting detailed user data](users.md)) ```shell @@ -83,7 +83,7 @@ Response ``` -##HTTP Basic Auth with API token## +##HTTP Basic Auth with API token When using Basic Auth and API token, use the API token as username and string "api_token" as password. Example request @@ -124,7 +124,7 @@ Response ``` -## Authentication with a session cookie ## +## Authentication with a session cookie `POST https://www.toggl.com/api/v8/sessions` diff --git a/chapters/clients.md b/chapters/clients.md index c26383f..21feae8 100644 --- a/chapters/clients.md +++ b/chapters/clients.md @@ -7,7 +7,7 @@ Client has the following properties * notes: Notes for the client (string, not required) * at: timestamp that is sent in the response, indicates the time client was last updated -##Create a client## +## Create a client `POST https://www.toggl.com/api/v8/clients` @@ -33,7 +33,7 @@ Successful response } ``` -##Get client details## +## Get client details `GET https://www.toggl.com/api/v8/clients/{client_id}` @@ -58,7 +58,7 @@ Successful response } ``` -##Update a client## +## Update a client `PUT https://www.toggl.com/api/v8/clients/{client_id}` Workspace id (wid) can't be changed. @@ -84,7 +84,7 @@ Successful response } ``` -##Delete a client## +## Delete a client `DELETE https://www.toggl.com/api/v8/clients/{client_id}` @@ -97,12 +97,12 @@ curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ Successful request will return `200 OK`. If the user has no access to delete, you'll get a status code `4xx` -##Get workspace clients## +## Get workspace clients Retrieving workspace clients is documented [here](workspaces.md#get-workspace-clients). -##Get clients visible to user## +## Get clients visible to user `GET https://www.toggl.com/api/v8/clients` @@ -131,7 +131,7 @@ Successful response is an array of clients ] ``` -##Get client projects## +## Get client projects `GET https://www.toggl.com/api/v8/clients/{client_id}/projects` diff --git a/chapters/cors.md b/chapters/cors.md index cbaf1da..8e42b5a 100644 --- a/chapters/cors.md +++ b/chapters/cors.md @@ -8,8 +8,8 @@ A CORS whitelist record has the following properties Record id (id) can't be changed on update. -##Actions## -###Create an entry### +## Actions +### Create an entry `POST https://www.toggl.com/api/v9/me/cors` @@ -32,7 +32,7 @@ Successful response } ``` -###Get entries for current user### +### Get entries for current user `GET https://www.toggl.com/api/v9/me/cors` @@ -64,7 +64,7 @@ Successful response ] ``` -###Delete an entry### +### Delete an entry `DELETE https://www.toggl.com/api/v9/me/cors/{id}` diff --git a/chapters/dashboard.md b/chapters/dashboard.md index d921298..d97250d 100644 --- a/chapters/dashboard.md +++ b/chapters/dashboard.md @@ -20,7 +20,7 @@ Most active user object has the following properties * user_id: user ID * duration: Sum of time entry durations that have been created during last 7 days -##Get Dashboard data## +## Get Dashboard data `GET https://www.toggl.com/api/v8/dashboard/{workspace_id}` diff --git a/chapters/groups.md b/chapters/groups.md index 8c8db8b..c63f807 100644 --- a/chapters/groups.md +++ b/chapters/groups.md @@ -6,7 +6,7 @@ Group has the following properties * wid: workspace ID, where the group will be used (integer, required) * at: timestamp that is sent in the response, indicates the time group was last updated -##Create a group## +## Create a group `POST https://www.toggl.com/api/v8/groups` @@ -32,7 +32,7 @@ Successful response } ``` -##Update a group## +## Update a group `PUT https://www.toggl.com/api/v8/groups/{group_id}` Workspace id (wid) can't be changed. @@ -57,7 +57,7 @@ Successful response } ``` -##Delete a group## +## Delete a group `DELETE https://www.toggl.com/api/v8/groups/{group_id}` @@ -70,6 +70,6 @@ curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ Successful request will return `200 OK`. If the user has no access to delete, you'll get a status code `4xx` -##Get workspace groups## +## Get workspace groups Retrieving workspace groups is documented [here](workspaces.md#get-workspace-groups). diff --git a/chapters/projects.md b/chapters/projects.md index 66b5b9e..5f97fda 100644 --- a/chapters/projects.md +++ b/chapters/projects.md @@ -18,7 +18,7 @@ Project has the following properties * at: timestamp indicating when the project was created (UTC time), read-only -##Create project## +## Create project `POST https://www.toggl.com/api/v8/projects` @@ -49,7 +49,7 @@ Successful response } ``` -##Get project data## +## Get project data `GET https://www.toggl.com/api/v8/projects/{project_id}` @@ -79,7 +79,7 @@ Successful response } ``` -##Update project data## +## Update project data `PUT https://www.toggl.com/api/v8/projects/{project_id}` @@ -110,7 +110,7 @@ Successful response } ``` -##Delete a project## +## Delete a project `DELETE https://www.toggl.com/api/v8/projects/{project_id}` @@ -120,7 +120,7 @@ curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -X DELETE https://www.toggl.com/api/v8/projects/4692190 ``` -##Get project users## +## Get project users `GET https://www.toggl.com/api/v8/projects/{project_id}/project_users` Read more about project user fields from [here](project_users.md). @@ -155,7 +155,7 @@ Successful response is an array of the project's users ] ``` -##Get project tasks## +## Get project tasks Available only for pro workspaces `GET https://www.toggl.com/api/v8/projects/{project_id}/tasks` @@ -192,14 +192,14 @@ Successful response is an array of the project's tasks ] ``` -##Get workspace projects## +## Get workspace projects Retrieving workspace projects is documented [here](workspaces.md#get-workspace-projects). -##Mass Actions## +## Mass Actions -###Delete multiple projects### +### Delete multiple projects By supplying multiple projectuser ids, you can mass delete projects. `DELETE https://www.toggl.com/api/v8/projects/{project_ids}` diff --git a/chapters/tags.md b/chapters/tags.md index f95bc53..2510e7f 100644 --- a/chapters/tags.md +++ b/chapters/tags.md @@ -5,7 +5,7 @@ Tag has the following properties * name: The name of the tag (string, required, unique in workspace) * wid: workspace ID, where the tag will be used (integer, required) -##Create tag## +## Create tag `POST https://www.toggl.com/api/v8/tags` @@ -30,7 +30,7 @@ Successful response } ``` -##Update a tag## +## Update a tag `PUT https://www.toggl.com/api/v8/tags/{tag_id}` Workspace id (wid) can't be changed. @@ -54,7 +54,7 @@ Successful response } ``` -##Delete a tag## +## Delete a tag `DELETE https://www.toggl.com/api/v8/tags/{tag_id}` diff --git a/chapters/tasks.md b/chapters/tasks.md index d210e34..517c503 100644 --- a/chapters/tasks.md +++ b/chapters/tasks.md @@ -14,8 +14,8 @@ Task has the following properties Workspace id (wid) and project id (pid) can't be changed on update. -##Actions for single project user## -###Create a task### +## Actions for single project user +### Create a task `POST https://www.toggl.com/api/v8/tasks` @@ -43,7 +43,7 @@ Successful response } ``` -###Get task details### +### Get task details `GET https://www.toggl.com/api/v8/tasks/{task_id}` @@ -68,7 +68,7 @@ Successful response } ``` -###Update a task### +### Update a task `PUT https://www.toggl.com/api/v8/tasks/{task_id}` @@ -97,7 +97,7 @@ Successful response } ``` -###Delete a task### +### Delete a task `DELETE https://www.toggl.com/api/v8/tasks/{task_id}` @@ -109,9 +109,9 @@ curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ Successful request will return `200 OK`. If the user has no access to delete, you'll get a status code `4xx` -##Mass Actions## +## Mass Actions -###Update multiple tasks### +### Update multiple tasks By supplying multiple task ids, you can mass update tasks. This is good for marking tasks as done or not done (`active`). @@ -153,7 +153,7 @@ Successful response is an array of tasks. } ``` -###Delete multiple tasks### +### Delete multiple tasks By supplying multiple task ids, you can mass delete tasks. `DELETE https://www.toggl.com/api/v8/tasks/{task_ids}` diff --git a/chapters/time_entries.md b/chapters/time_entries.md index 32e8401..d7b1d58 100644 --- a/chapters/time_entries.md +++ b/chapters/time_entries.md @@ -17,7 +17,7 @@ Time entry has the following properties * duronly: should Toggl show the start and stop time of this time entry? (boolean, not required) * at: timestamp that is sent in the response, indicates the time item was last updated -##Create a time entry## +## Create a time entry `POST https://www.toggl.com/api/v8/time_entries` @@ -48,7 +48,7 @@ Successful response } ``` -##Start a time entry## +## Start a time entry `POST https://www.toggl.com/api/v8/time_entries/start` @@ -79,7 +79,7 @@ Successful response } ``` -##Stop a time entry## +## Stop a time entry `PUT https://www.toggl.com/api/v8/time_entries/{time_entry_id}/stop` @@ -107,7 +107,7 @@ Successful response } ``` -##Get time entry details## +## Get time entry details `GET https://www.toggl.com/api/v8/time_entries/{time_entry_id}` @@ -138,7 +138,7 @@ Successful response ``` -##Get running time entry## +## Get running time entry `GET https://www.toggl.com/api/v8/time_entries/current` @@ -166,7 +166,7 @@ Successful response ``` -##Update a time entry## +## Update a time entry `PUT https://www.toggl.com/api/v8/time_entries/{time_entry_id}` Example request @@ -198,7 +198,7 @@ Successful response } ``` -##Delete a time entry## +## Delete a time entry `DELETE https://www.toggl.com/api/v8/time_entries/{time_entry_id}` @@ -212,7 +212,7 @@ curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ Successful request will return `200 OK` -##Get time entries started in a specific time range## +## Get time entries started in a specific time range `GET https://www.toggl.com/api/v8/time_entries` diff --git a/chapters/workspace_users.md b/chapters/workspace_users.md index 0ea5bf6..c7c3993 100644 --- a/chapters/workspace_users.md +++ b/chapters/workspace_users.md @@ -8,7 +8,7 @@ Workspace user has the following properties: * active: if the workspace user has accepted the invitation to this workspace (boolean) * invite_url: if user has not accepted the invitation the url for accepting his/her invitation is sent when the request is made by workspace_admin -##Invite users to workspace## +## Invite users to workspace You can add users to workspace by email addresses. A letter inviting the user to your workspace is sent to the user's email. @@ -48,7 +48,7 @@ Successful response ``` -##Update workspace user## +## Update workspace user Only the admin flag can be changed. @@ -77,7 +77,7 @@ Successful response } ``` -##Delete workspace user## +## Delete workspace user `DELETE https://www.toggl.com/api/v8/workspace_users/{workspace_user_id}` @@ -89,7 +89,7 @@ curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ Successful request will return `200 OK`. If the user has no access to delete, you'll get a status code `4xx` -##Get workspace users## +## Get workspace users This request returns not the user objects, but the `workspace_user` objects (the connection between user and workspace) `GET https://www.toggl.com/api/v8/workspaces/{workspace_id}/workspace_users` diff --git a/chapters/workspaces.md b/chapters/workspaces.md index aa490c8..f133126 100644 --- a/chapters/workspaces.md +++ b/chapters/workspaces.md @@ -22,7 +22,7 @@ Workspace has the following properties | round up | 1 | -##Get workspaces## +## Get workspaces `GET https://www.toggl.com/api/v8/workspaces` Get data about all the workspaces where the token owner belongs to. @@ -65,7 +65,7 @@ Successful response is an array of workspaces ] ``` -##Get single workspace## +## Get single workspace `GET https://www.toggl.com/api/v8/workspaces/{workspace_id}` Example request @@ -94,7 +94,7 @@ Successful response } ``` -##Update workspace## +## Update workspace `PUT https://www.toggl.com/api/v8/workspaces/{workspace_id}` @@ -129,7 +129,7 @@ Successful response } ``` -##Get workspace users## +## Get workspace users To get a successful response, the token owner must be workspace admin. `GET https://www.toggl.com/api/v8/workspaces/{workspace_id}/users` @@ -191,7 +191,7 @@ Successful response is an array of workspace users ] ``` -##Get workspace clients## +## Get workspace clients To get a successful response, the token owner must be workspace admin. `GET https://www.toggl.com/api/v8/workspaces/{workspace_id}/clients` @@ -225,7 +225,7 @@ Successful response is an array of workspace clients ] ``` -##Get workspace groups## +## Get workspace groups To get a successful response, the token owner must be workspace admin. `GET https://www.toggl.com/api/v8/workspaces/{workspace_id}/groups` @@ -253,7 +253,7 @@ Successful response is an array of workspace groups ] ``` -##Get workspace projects## +## Get workspace projects To get a successful response, the token owner must be workspace admin. `GET https://www.toggl.com/api/v8/workspaces/{workspace_id}/projects` @@ -298,7 +298,7 @@ Successful response is an array of active workspace projects ] ``` -##Get workspace tasks## +## Get workspace tasks Available only for pro workspaces To get a successful response, the token owner must be workspace admin. @@ -348,7 +348,7 @@ Successful response is an array of workspace tasks ] ``` -##Get workspace tags## +## Get workspace tags `GET https://www.toggl.com/api/v8/workspaces/{workspace_id}/tags` diff --git a/reports.md b/reports.md index dc685e8..0a551a1 100644 --- a/reports.md +++ b/reports.md @@ -9,7 +9,7 @@ More detailed information for the reports. * [Summary report](reports/summary.md) * [Project dashboard](reports/project.md) -##URLs## +## URLs The reports API base URL is `https://toggl.com/reports/api/v2` @@ -21,20 +21,20 @@ Summary report URL: `GET https://toggl.com/reports/api/v2/summary` For PDF response add .pdf to the end of the URL. -##Rate limiting## +## Rate limiting There is rate limiting of 1 request per second (per IP per API token), this limit may change in future. In case client application exceeds rate limit HTTP status 429 will be returned. Excessive requests may yield in stricter limits set upon token/IP combination. -##Authentication## +## Authentication You can authenticate in the reports API **only** with your API token. For HTTP Basic Auth you have to add the Authorization header with the request. The API token is the user name and the string 'api_token' is the password. Whenever possible please use the tools and interfaces provided by your http library to do Basic Auth (for example, curl uses the -u switch for that). -##Request Parameters## +## Request Parameters The API expects the request parameters as the query string of the URL. @@ -63,7 +63,7 @@ The following parameters and filters can be used in all of the reports * `rounding`: "on" or "off". Defaults to "off". Rounds time according to workspace settings. * `display_hours`: "decimal" or "minutes". Defaults to "minutes". Determines whether to display hours as a decimal number or with minutes. -##Successful response## +## Successful response The general structure of the successful response ```json @@ -81,7 +81,7 @@ The response may include some additional attributes depending on the report type * total_currencies: an array with amounts and currencies for the selected report * data: an array with detailed information of the requested report. The structure of the data in the array depends on the report. -##Failed requests## +## Failed requests In case of unsuccessful request the API returns the error in JSON and corresponding HTTP status code * message: the general message of the occurred error diff --git a/toggl_api.md b/toggl_api.md index 150ba10..39a3fc2 100644 --- a/toggl_api.md +++ b/toggl_api.md @@ -6,11 +6,11 @@ If the time entry is currently running, the *duration* attribute contains a nega The result of each action is communicated via standard HTTP response codes. -###CORS### +### CORS If you wish to use the API using CORS, we'll need to whitelist you first. Please refer to the [CORS documentation](https://github.com/toggl/toggl_api_docs/blob/master/chapters/cors.md) -###Successful requests### +### Successful requests When request is successful (2xx), a nested response object is returned. Fields which value is NULL are not in the response. @@ -43,7 +43,7 @@ Response } ``` -###Failed requests### +### Failed requests If a create or update action failed, HTTP status code 404 and an array of localized error messages will be returned. @@ -59,13 +59,13 @@ Response `["Start can't be blank"]` -##Authentication## +## Authentication To use the API, you need to authenticate yourself. This can be done via HTTP POST or HTTP Basic Auth. After successful authentication a session is created using a cookie. If authentication fails, HTTP status code 403 is returned. You can read more about authentication and see sample requests [here](chapters/authentication.md). -##Supported API requests## +## Supported API requests * [Authenticate and get user data](chapters/authentication.md) - HTTP Basic Auth with e-mail and password From 7cb91568ec00f63ecf9c57d2c0d32b413e77f5f6 Mon Sep 17 00:00:00 2001 From: Jordan Date: Fri, 28 Jul 2017 15:45:36 +0930 Subject: [PATCH 081/113] Update projects.md --- chapters/projects.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapters/projects.md b/chapters/projects.md index 5f97fda..a6f80ff 100644 --- a/chapters/projects.md +++ b/chapters/projects.md @@ -156,7 +156,7 @@ Successful response is an array of the project's users ``` ## Get project tasks -Available only for pro workspaces +Available only for Starter workspaces `GET https://www.toggl.com/api/v8/projects/{project_id}/tasks` Read more about task fields from [here](tasks.md). From ab0adb6fac2ff47d18a10f5a6f3eaa607e19f49e Mon Sep 17 00:00:00 2001 From: Jordan Date: Fri, 28 Jul 2017 15:46:58 +0930 Subject: [PATCH 082/113] Update projects.md --- chapters/projects.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapters/projects.md b/chapters/projects.md index a6f80ff..abc2bab 100644 --- a/chapters/projects.md +++ b/chapters/projects.md @@ -156,7 +156,7 @@ Successful response is an array of the project's users ``` ## Get project tasks -Available only for Starter workspaces +Available for Starter, Premium and Enterprise workspaces `GET https://www.toggl.com/api/v8/projects/{project_id}/tasks` Read more about task fields from [here](tasks.md). From daa9260716ddbb5828913d8855e8860a95b293e1 Mon Sep 17 00:00:00 2001 From: Margus Mahler Date: Tue, 15 Aug 2017 10:08:42 +0300 Subject: [PATCH 083/113] improved wording --- reports.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reports.md b/reports.md index 0a551a1..06c8226 100644 --- a/reports.md +++ b/reports.md @@ -41,8 +41,8 @@ The API expects the request parameters as the query string of the URL. The following parameters and filters can be used in all of the reports * `user_agent`: **Required**. The name of your application or your email address so we can get in touch in case you're doing something wrong. * `workspace_id`: **Required**. The workspace whose data you want to access. -* `since`: ISO 8601 date (YYYY-MM-DD) format. Defaults to 6 days before `until`. -* `until`: ISO 8601 date (YYYY-MM-DD) format. Defaults to today's date. (Note: Maximum date span (`until - since`) is one year.) +* `since`: ISO 8601 date (YYYY-MM-DD) format. Defaults to today - 6 days. +* `until`: ISO 8601 date (YYYY-MM-DD) format. Note: Maximum date span (`until - since`) is one year. Defaults to today, unless since is in future or more than year ago, in this case until is since + 6 days. * `billable`: "yes", "no", or "both". Defaults to "both". * `client_ids`: A list of client IDs separated by a comma. Use "0" if you want to filter out time entries without a client. * `project_ids`: A list of project IDs separated by a comma. Use "0" if you want to filter out time entries without a project. From a230ff142b5e468697a1113c4ffa484d7c17365e Mon Sep 17 00:00:00 2001 From: Tim Malone Date: Thu, 17 Aug 2017 11:54:09 +1000 Subject: [PATCH 084/113] Minor: fix markdown headings in reports/summary --- reports/summary.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/reports/summary.md b/reports/summary.md index 13cdb69..14bb073 100644 --- a/reports/summary.md +++ b/reports/summary.md @@ -1,8 +1,8 @@ -#Summary report# +# Summary report Summary report returns the aggregated time entries data. -##Request## +## Request In addition to the [standard request parameters](../reports.md#request-parameters), summaries accept the following additional parameters: * `grouping` @@ -28,11 +28,11 @@ Following groupings with subgroupings are available in the summary report * projects * clients -##Response## +## Response The response will include the [standard response parameters](../reports.md#successful-response). -###Data array### +### Data array General structure of the item in the data array * id: the id of the grouping object @@ -70,10 +70,10 @@ General structure of the item in the data array } ``` -##Project colors## +## Project colors When grouped by project the title part of the return will contain color and color_hex fields. First one contains the color id (returned also by APIv8), second one will return the corresponding HEX value. (Please note: color return is a subject of change). -##Example## +## Example Example request ```shell From fb1ee2684f0f95bf251d006889405eb484788ef2 Mon Sep 17 00:00:00 2001 From: Tim Malone Date: Thu, 17 Aug 2017 11:54:14 +1000 Subject: [PATCH 085/113] Minor: fix markdown headings in reports/weekly --- reports/weekly.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/reports/weekly.md b/reports/weekly.md index a0b4e18..65b8171 100644 --- a/reports/weekly.md +++ b/reports/weekly.md @@ -1,8 +1,8 @@ -#Weekly report# +# Weekly report The weekly report gives aggregated 7 day durations or earnings grouped by users and projects. -##Request## +## Request The weekly report accepts all of the [standard request parameters](../reports.md#request-parameters), with the exception of the `until` parameter. Instead, 7 days starting from `since` are shown. @@ -10,12 +10,12 @@ Additional request parameters for this report are: * `grouping`: `users`/`projects`, default projects. If one grouping is selected, the other acts as subgrouping. * `calculate`: `time`/`earnings`, default time -##Response## +## Response The response will include the [standard response parameters](../reports.md#successful-response), as well as: * `week_totals`: array of total amounts/hours for every day (null if there's no work on a certain day) -###Data array### +### Data array Grouping is `projects` the main grouping looks like this * title: object containing project and client name @@ -87,7 +87,7 @@ If `calculate=earnings`, it is an array of objects with currency string and the ] ``` -##Example## +## Example Example request ```shell From e045b9a97de707ee1b0192a10832ae7ed4f9408d Mon Sep 17 00:00:00 2001 From: Tim Malone Date: Thu, 17 Aug 2017 11:55:17 +1000 Subject: [PATCH 086/113] Minor: fix markdown headings in reports/project --- reports/project.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/reports/project.md b/reports/project.md index 6886222..6b33bfd 100644 --- a/reports/project.md +++ b/reports/project.md @@ -1,8 +1,8 @@ -#Project dashboard# +# Project dashboard -[Project dashboard](http://support.toggl.com/project-dashboard/) returns at-a glance information for a single project. This feature is only available with Toggl pro. +[Project dashboard](http://support.toggl.com/project-dashboard/) returns at-a glance information for a single project. This feature is only available with paid Toggl plans. -##Request## +## Request `GET /reports/api/v2/project` @@ -19,7 +19,7 @@ Parameters are: * `order_desc` string: on/off, `on` for descending and `off` for ascending order -##Response## +## Response Project dashboard response has following strucure: ([json schema] (project_dashboard_schema.json)) @@ -65,7 +65,7 @@ Project dashboard response has following strucure: ([json schema] * `tasks_page` is array holding all tasks of given project, one page at a time -##Example## +## Example request: ```shell @@ -155,4 +155,4 @@ response (formatted for readability): } ] } -``` \ No newline at end of file +``` From 22d0ed02b4ec4c24ea7cc308e601c43270c91f9f Mon Sep 17 00:00:00 2001 From: Eric Shtivelberg Date: Mon, 25 Sep 2017 18:40:45 +0300 Subject: [PATCH 087/113] Update header --- chapters/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapters/authentication.md b/chapters/authentication.md index 4de6db2..b9ea967 100644 --- a/chapters/authentication.md +++ b/chapters/authentication.md @@ -83,7 +83,7 @@ Response ``` -##HTTP Basic Auth with API token +## HTTP Basic Auth with API token When using Basic Auth and API token, use the API token as username and string "api_token" as password. Example request From 6ab603a500bbff85e6d6cb035e6715a243cc83e8 Mon Sep 17 00:00:00 2001 From: AnEmortalKid Date: Mon, 2 Oct 2017 10:26:34 -0500 Subject: [PATCH 088/113] Update README.md Fix broken name links --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 8cd85e3..bdf3eac 100644 --- a/README.md +++ b/README.md @@ -83,7 +83,7 @@ The Toggl API has moved to Github so you could actively participate in helping u * [Ixudra](https://ixudra.be) has written a Laravel PHP library for Toggl API v8: https://github.com/ixudra/toggl ### Go -* [Doug Chimento] (https://github.com/dougEfresh) has written a Go wrapper for Toggl API v8: https://github.com/dougEfresh/gtoggl +* [Doug Chimento](https://github.com/dougEfresh) has written a Go wrapper for Toggl API v8: https://github.com/dougEfresh/gtoggl ### Elixir * [Víctor Viruete](https://github.com/hopsor) has written an Elixir wrapper for Toggl API v8 and Reports API: https://github.com/diacode/togglex @@ -93,8 +93,8 @@ The Toggl API has moved to Github so you could actively participate in helping u * [rocketbase-io](https://github.com/rocketbase-io/toggl-reporter) has written a tiny SpringBoot-Application, build with vaadin and mongodb, that pulls your TimeEntries from toggl. The stored information allow a fine grained reporting and analysis that aren't possible within toggl (like detailed working hours in comparison between team-members and many more). A [docker-image](https://hub.docker.com/r/rocketbaseio/toggl-reporter/) is also provided... ### Perl -* [Jason Kruczynski] (https://github.com/jkruczynski) has written a perl wrapper for the API. It creates and authenticates a session for API V8 or API V2 depending on the URL. It implements a few functions for exporting reports. https://github.com/jkruczynski/Toggl-API-Wrapper-Perl +* [Jason Kruczynski](https://github.com/jkruczynski) has written a perl wrapper for the API. It creates and authenticates a session for API V8 or API V2 depending on the URL. It implements a few functions for exporting reports. https://github.com/jkruczynski/Toggl-API-Wrapper-Perl ### R -* [Vincent Guyader] (http://thinkr.fr) has written a simple R and Rstudio implementation for the API. https://github.com/ThinkRstat/togglr +* [Vincent Guyader](http://thinkr.fr) has written a simple R and Rstudio implementation for the API. https://github.com/ThinkRstat/togglr From 26e6b952489ad9de41b1c089dcc71e1a7bf098c9 Mon Sep 17 00:00:00 2001 From: Ervin Weber Date: Wed, 11 Oct 2017 11:51:23 +0300 Subject: [PATCH 089/113] provide empty data for post --- chapters/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapters/authentication.md b/chapters/authentication.md index b9ea967..262ca57 100644 --- a/chapters/authentication.md +++ b/chapters/authentication.md @@ -133,7 +133,7 @@ It's possible to create a session. The session creation request sets a cookie in Example request ```shell -curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token -X POST https://www.toggl.com/api/v8/sessions +curl --data="" -v -u 1971800d4d82861d8f2c1651fea4d212:api_token -X POST https://www.toggl.com/api/v8/sessions ``` Successful response header includes the cookie From d646a240bf18ea69155658a059065980f52764c7 Mon Sep 17 00:00:00 2001 From: Nick Date: Fri, 1 Jun 2018 11:29:59 +0300 Subject: [PATCH 090/113] Update tasks.md --- chapters/tasks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapters/tasks.md b/chapters/tasks.md index 517c503..c6c35be 100644 --- a/chapters/tasks.md +++ b/chapters/tasks.md @@ -1,6 +1,6 @@ Tasks ==================== -Tasks are available only for pro workspaces. +Tasks are available only for starter and other paid workspaces. Task has the following properties * name: The name of the task (string, required, unique in project) From ca37fed128b03a6caf0fa43fe47d028265db3e7a Mon Sep 17 00:00:00 2001 From: Mauricio Ferreira Date: Tue, 31 Jul 2018 17:51:54 +0100 Subject: [PATCH 091/113] Rename api_v9_repots_v3_basics.md to api_v9_reports_v3_basics.md Fixed file typo. --- api_v9_repots_v3_basics.md => api_v9_reports_v3_basics.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename api_v9_repots_v3_basics.md => api_v9_reports_v3_basics.md (100%) diff --git a/api_v9_repots_v3_basics.md b/api_v9_reports_v3_basics.md similarity index 100% rename from api_v9_repots_v3_basics.md rename to api_v9_reports_v3_basics.md From 7a265122d106f632ee0806d8d7ba6a91e4fb7cfa Mon Sep 17 00:00:00 2001 From: Nghia Tran Date: Mon, 29 Oct 2018 00:00:15 +0700 Subject: [PATCH 092/113] Add Toggl Swift example --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index bdf3eac..b12c604 100644 --- a/README.md +++ b/README.md @@ -98,3 +98,6 @@ The Toggl API has moved to Github so you could actively participate in helping u ### R * [Vincent Guyader](http://thinkr.fr) has written a simple R and Rstudio implementation for the API. https://github.com/ThinkRstat/togglr +### Swift +* [Nghia Tran](https://github.com/NghiaTranUIT) has written a macOS wrapper in Swift 4.2. So, we can integrate the Toggl API v8 to your own app easier: https://github.com/NghiaTranUIT/Toggl-Swift + From 94b8a58483677faa3e969c01350dd7bb05550f2c Mon Sep 17 00:00:00 2001 From: Dmitry Kutkovskiy Date: Tue, 27 Nov 2018 22:01:28 +0300 Subject: [PATCH 093/113] Update reports.md Added a couple of words for the CSV output ability. Since this kind of request is available to the users but not documented here. --- reports.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reports.md b/reports.md index 06c8226..71dceb2 100644 --- a/reports.md +++ b/reports.md @@ -19,7 +19,7 @@ Detailed report URL: `GET https://toggl.com/reports/api/v2/details` Summary report URL: `GET https://toggl.com/reports/api/v2/summary` -For PDF response add .pdf to the end of the URL. +For PDF response add .pdf to the end of the URL. For CSV response add .csv as well. ## Rate limiting From ab61c0237eb8c7002e6b96590cd89bb3afeecd56 Mon Sep 17 00:00:00 2001 From: Eric Shtivelberg Date: Mon, 24 Dec 2018 15:01:44 +0200 Subject: [PATCH 094/113] Note that CORS API is disabled --- chapters/cors.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/chapters/cors.md b/chapters/cors.md index 8e42b5a..f0a3d72 100644 --- a/chapters/cors.md +++ b/chapters/cors.md @@ -1,3 +1,9 @@ +**Notice** +> This portion of the API is disabled, if you require CORS whitelisting for your website please contact support@toggl.com for further assistance. + +
+


+ CORS whitelists ==================== From 75e2a40d35b271d827edfa48c8f71841ac68f70e Mon Sep 17 00:00:00 2001 From: Maja Date: Fri, 18 Oct 2019 16:22:06 +0200 Subject: [PATCH 095/113] Fixed wrong column name --- chapters/projects.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapters/projects.md b/chapters/projects.md index abc2bab..94f5bba 100644 --- a/chapters/projects.md +++ b/chapters/projects.md @@ -15,7 +15,7 @@ Project has the following properties * at: timestamp that is sent in the response for PUT, indicates the time task was last updated (read-only) * color: id of the color selected for the project * rate: hourly rate of the project (float, not required, premium functionality) -* at: timestamp indicating when the project was created (UTC time), read-only +* created_at: timestamp indicating when the project was created (UTC time), read-only ## Create project From 110d5205db4d3cd04eb8bccf2b153970a268a700 Mon Sep 17 00:00:00 2001 From: Tiago Ilieve Date: Mon, 9 Dec 2019 11:19:12 -0300 Subject: [PATCH 096/113] authentication: update cookie name --- chapters/authentication.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/chapters/authentication.md b/chapters/authentication.md index 262ca57..805f1d4 100644 --- a/chapters/authentication.md +++ b/chapters/authentication.md @@ -128,7 +128,7 @@ Response `POST https://www.toggl.com/api/v8/sessions` -It's possible to create a session. The session creation request sets a cookie in the response header `toggl_api_session_new`, which you can use for authentication in all the API requests. The cookie expires in 24 hours. +It's possible to create a session. The session creation request sets a cookie in the response header `__Host-timer-session`, which you can use for authentication in all the API requests. Example request @@ -139,7 +139,7 @@ curl --data="" -v -u 1971800d4d82861d8f2c1651fea4d212:api_token -X POST https:// Successful response header includes the cookie ```shell -< Set-Cookie: toggl_api_session_new=MTM2MzA4MJa8jA3OHxEdi1CQkFFQ180SUFBUkFCRUFBQVlQLUNBQUVHYzNSeWFXNW5EQXdBQ25ObGMzTnBiMjVmYVdRR2MzUnlhVzVuREQ0QVBIUnZaMmRzTFdGd2FTMXpaWE56YVc5dUxUSXRaalU1WmpaalpEUTVOV1ZsTVRoaE1UaGhaalpqWkRkbU5XWTJNV0psWVRnd09EWmlPVEV3WkE9PXweAkG7kI6NBG-iqvhNn1MSDhkz2Pz_UYTzdBvZjCaA==; Path=/; Expires=Wed, 13 Mar 2013 09:54:38 UTC; Max-Age=86400; HttpOnly +< Set-Cookie: __Host-timer-session=MTM2MzA4MJa8jA3OHxEdi1CQkFFQ180SUFBUkFCRUFBQVlQLUNBQUVHYzNSeWFXNW5EQXdBQ25ObGMzTnBiMjVmYVdRR2MzUnlhVzVuREQ0QVBIUnZaMmRzTFdGd2FTMXpaWE56YVc5dUxUSXRaalU1WmpaalpEUTVOV1ZsTVRoaE1UaGhaalpqWkRkbU5XWTJNV0psWVRnd09EWmlPVEV3WkE9PXweAkG7kI6NBG-iqvhNn1MSDhkz2Pz_UYTzdBvZjCaA==; Path=/; HttpOnly; Secure; SameSite=Lax ``` And body contains user's data @@ -182,7 +182,7 @@ Destroy the session manually by sending an according request to the API. Example request ```shell -curl -v --cookie toggl_api_session_new=MTM2MzA4MJa8jA3OHxEdi1CQkFFQ180SUFBUkFCRUFBQVlQLUNBQUVHYzNSeWFXNW5EQXdBQ25ObGMzTnBiMjVmYVdRR2MzUnlhVzVuREQ0QVBIUnZaMmRzTFdGd2FTMXpaWE56YVc5dUxUSXRaalU1WmpaalpEUTVOV1ZsTVRoaE1UaGhaalpqWkRkbU5XWTJNV0psWVRnd09EWmlPVEV3WkE9PXweAkG7kI6NBG-iqvhNn1MSDhkz2Pz_UYTzdBvZjCaA== -X DELETE https://www.toggl.com/api/v8/sessions +curl -v --cookie __Host-timer-session=MTM2MzA4MJa8jA3OHxEdi1CQkFFQ180SUFBUkFCRUFBQVlQLUNBQUVHYzNSeWFXNW5EQXdBQ25ObGMzTnBiMjVmYVdRR2MzUnlhVzVuREQ0QVBIUnZaMmRzTFdGd2FTMXpaWE56YVc5dUxUSXRaalU1WmpaalpEUTVOV1ZsTVRoaE1UaGhaalpqWkRkbU5XWTJNV0psWVRnd09EWmlPVEV3WkE9PXweAkG7kI6NBG-iqvhNn1MSDhkz2Pz_UYTzdBvZjCaA== -X DELETE https://www.toggl.com/api/v8/sessions ``` Successful request will return `200 OK`. From 6fc73db9946720b4eb863d9daa78ba1159f40595 Mon Sep 17 00:00:00 2001 From: masaru kojo Date: Sat, 11 Jan 2020 23:27:53 +0900 Subject: [PATCH 097/113] Fixed broken link --- reports/project.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reports/project.md b/reports/project.md index 6b33bfd..51bc0a6 100644 --- a/reports/project.md +++ b/reports/project.md @@ -1,6 +1,6 @@ # Project dashboard -[Project dashboard](http://support.toggl.com/project-dashboard/) returns at-a glance information for a single project. This feature is only available with paid Toggl plans. +[Project dashboard](https://support.toggl.com/en/articles/3167701-project-dashboard) returns at-a glance information for a single project. This feature is only available with paid Toggl plans. ## Request From 2f2fec8c370c64b0b2703cbca015149d5c09d82d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Elan=20Ruusam=C3=A4e?= Date: Thu, 23 Jan 2020 12:27:31 +0200 Subject: [PATCH 098/113] Update api doc list formmatting --- toggl_api.md | 119 +++++++++++++++++++++++++-------------------------- 1 file changed, 59 insertions(+), 60 deletions(-) diff --git a/toggl_api.md b/toggl_api.md index 39a3fc2..5fd8be5 100644 --- a/toggl_api.md +++ b/toggl_api.md @@ -68,74 +68,73 @@ If authentication fails, HTTP status code 403 is returned. You can read more abo ## Supported API requests * [Authenticate and get user data](chapters/authentication.md) - - HTTP Basic Auth with e-mail and password - - HTTP Basic Auth with API token - - Authentication with a session cookie - - Destroy the session + - HTTP Basic Auth with e-mail and password + - HTTP Basic Auth with API token + - Authentication with a session cookie + - Destroy the session * [Clients](chapters/clients.md) - - create a client - - get client details - - update a client - - delete a client - - get clients visible to user - - get client projects + - create a client + - get client details + - update a client + - delete a client + - get clients visible to user + - get client projects * [Groups](chapters/groups.md) - - create a group - - update a group - - delete a group + - create a group + - update a group + - delete a group * [Projects](chapters/projects.md) - - create a project - - get project data - - update project data - - delete a project - - get project users - - get project tasks - - delete multiple projects + - create a project + - get project data + - update project data + - delete a project + - get project users + - get project tasks + - delete multiple projects * [Project users](chapters/project_users.md) - - create a project user - - update a project user - - delete a project user - - add multiple users to a project - - update multiple project users - - delete multiple project users + - create a project user + - update a project user + - delete a project user + - add multiple users to a project + - update multiple project users + - delete multiple project users * [Tags](chapters/tags.md) - - create a tag - - update a tag - - delete a tag + - create a tag + - update a tag + - delete a tag * [Tasks](chapters/tasks.md) *(available only for pro workspaces)* - - create a task - - get task details - - update a task - - delete a task - - update multiple tasks - - delete multiple tasks + - create a task + - get task details + - update a task + - delete a task + - update multiple tasks + - delete multiple tasks * [Time entries](chapters/time_entries.md) - - create a time entry - - start a time entry - - stop a time entry - - get time entry details - - update time entry - - delete time entry - - get time entries started in a specific time range - - bulk update time entries tags + - create a time entry + - start a time entry + - stop a time entry + - get time entry details + - update time entry + - delete time entry + - get time entries started in a specific time range + - bulk update time entries tags * [Users](chapters/users.md) - - get current user data and time entries - - update current user data - - reset API token - - sign up new user + - get current user data and time entries + - update current user data + - reset API token + - sign up new user * [Workspaces](chapters/workspaces.md) - - get user workspaces - - get workspace users - - get workspace clients - - get workspace groups - - get workspace projects - - get workspace tasks - - get workspace tags + - get user workspaces + - get workspace users + - get workspace clients + - get workspace groups + - get workspace projects + - get workspace tasks + - get workspace tags * [Workspace users](chapters/workspace_users.md) - - invite users to workspace - - update workspace user - - delete workspace user - - get workspace users for a workspace + - invite users to workspace + - update workspace user + - delete workspace user + - get workspace users for a workspace * [Dashboard](chapters/dashboard.md) - - Get a generic overview of your team - + - Get a generic overview of your team From 50ca982bba5eb41d1f852cc67e6ca903875524f9 Mon Sep 17 00:00:00 2001 From: gilberthdez Date: Thu, 13 Aug 2020 17:19:14 +0200 Subject: [PATCH 099/113] replace for new api url --- chapters/authentication.md | 12 ++++++------ chapters/clients.md | 24 ++++++++++++------------ chapters/cors.md | 12 ++++++------ chapters/dashboard.md | 4 ++-- chapters/groups.md | 12 ++++++------ chapters/project_users.md | 26 +++++++++++++------------- chapters/projects.md | 28 ++++++++++++++-------------- chapters/tags.md | 12 ++++++------ chapters/tasks.md | 24 ++++++++++++------------ chapters/time_entries.md | 36 ++++++++++++++++++------------------ chapters/users.md | 18 +++++++++--------- chapters/workspace_users.md | 16 ++++++++-------- chapters/workspaces.md | 36 ++++++++++++++++++------------------ toggl_api.md | 4 ++-- 14 files changed, 132 insertions(+), 132 deletions(-) diff --git a/chapters/authentication.md b/chapters/authentication.md index 805f1d4..996e552 100644 --- a/chapters/authentication.md +++ b/chapters/authentication.md @@ -17,7 +17,7 @@ If authentication fails, HTTP status code 403 is returned. Example request ([See also chapter about getting detailed user data](users.md)) ```shell -curl -v -u john.doe@gmail.com:secret -X GET https://www.toggl.com/api/v8/me +curl -v -u john.doe@gmail.com:secret -X GET https://api.track.toggl.com/api/v8/me ``` @@ -88,7 +88,7 @@ When using Basic Auth and API token, use the API token as username and string "a Example request ```shell -curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token -X GET https://www.toggl.com/api/v8/me +curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token -X GET https://api.track.toggl.com/api/v8/me ``` Response @@ -126,14 +126,14 @@ Response ## Authentication with a session cookie -`POST https://www.toggl.com/api/v8/sessions` +`POST https://api.track.toggl.com/api/v8/sessions` It's possible to create a session. The session creation request sets a cookie in the response header `__Host-timer-session`, which you can use for authentication in all the API requests. Example request ```shell -curl --data="" -v -u 1971800d4d82861d8f2c1651fea4d212:api_token -X POST https://www.toggl.com/api/v8/sessions +curl --data="" -v -u 1971800d4d82861d8f2c1651fea4d212:api_token -X POST https://api.track.toggl.com/api/v8/sessions ``` Successful response header includes the cookie @@ -177,12 +177,12 @@ And body contains user's data Destroy the session manually by sending an according request to the API. -`DELETE https://www.toggl.com/api/v8/sessions` +`DELETE https://api.track.toggl.com/api/v8/sessions` Example request ```shell -curl -v --cookie __Host-timer-session=MTM2MzA4MJa8jA3OHxEdi1CQkFFQ180SUFBUkFCRUFBQVlQLUNBQUVHYzNSeWFXNW5EQXdBQ25ObGMzTnBiMjVmYVdRR2MzUnlhVzVuREQ0QVBIUnZaMmRzTFdGd2FTMXpaWE56YVc5dUxUSXRaalU1WmpaalpEUTVOV1ZsTVRoaE1UaGhaalpqWkRkbU5XWTJNV0psWVRnd09EWmlPVEV3WkE9PXweAkG7kI6NBG-iqvhNn1MSDhkz2Pz_UYTzdBvZjCaA== -X DELETE https://www.toggl.com/api/v8/sessions +curl -v --cookie __Host-timer-session=MTM2MzA4MJa8jA3OHxEdi1CQkFFQ180SUFBUkFCRUFBQVlQLUNBQUVHYzNSeWFXNW5EQXdBQ25ObGMzTnBiMjVmYVdRR2MzUnlhVzVuREQ0QVBIUnZaMmRzTFdGd2FTMXpaWE56YVc5dUxUSXRaalU1WmpaalpEUTVOV1ZsTVRoaE1UaGhaalpqWkRkbU5XWTJNV0psWVRnd09EWmlPVEV3WkE9PXweAkG7kI6NBG-iqvhNn1MSDhkz2Pz_UYTzdBvZjCaA== -X DELETE https://api.track.toggl.com/api/v8/sessions ``` Successful request will return `200 OK`. diff --git a/chapters/clients.md b/chapters/clients.md index 21feae8..cc89e51 100644 --- a/chapters/clients.md +++ b/chapters/clients.md @@ -9,7 +9,7 @@ Client has the following properties ## Create a client -`POST https://www.toggl.com/api/v8/clients` +`POST https://api.track.toggl.com/api/v8/clients` Example request @@ -17,7 +17,7 @@ Example request curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -H "Content-Type: application/json" \ -d '{"client":{"name":"Very Big Company","wid":777}}' \ - -X POST https://www.toggl.com/api/v8/clients + -X POST https://api.track.toggl.com/api/v8/clients ``` @@ -35,13 +35,13 @@ Successful response ## Get client details -`GET https://www.toggl.com/api/v8/clients/{client_id}` +`GET https://api.track.toggl.com/api/v8/clients/{client_id}` Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ - -X GET https://www.toggl.com/api/v8/clients/1239455 + -X GET https://api.track.toggl.com/api/v8/clients/1239455 ``` @@ -59,7 +59,7 @@ Successful response ``` ## Update a client -`PUT https://www.toggl.com/api/v8/clients/{client_id}` +`PUT https://api.track.toggl.com/api/v8/clients/{client_id}` Workspace id (wid) can't be changed. @@ -68,7 +68,7 @@ Example request curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -H "Content-Type: application/json" \ -d '{"client":{"name":"Very Big Company","notes":"something about the client"}}' \ - -X PUT https://www.toggl.com/api/v8/clients/1239455 + -X PUT https://api.track.toggl.com/api/v8/clients/1239455 ``` Successful response @@ -86,12 +86,12 @@ Successful response ## Delete a client -`DELETE https://www.toggl.com/api/v8/clients/{client_id}` +`DELETE https://api.track.toggl.com/api/v8/clients/{client_id}` Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ - -X DELETE https://www.toggl.com/api/v8/clients/1239455 + -X DELETE https://api.track.toggl.com/api/v8/clients/1239455 ``` Successful request will return `200 OK`. If the user has no access to delete, you'll get a status code `4xx` @@ -104,12 +104,12 @@ Retrieving workspace clients is documented [here](workspaces.md#get-workspace-cl ## Get clients visible to user -`GET https://www.toggl.com/api/v8/clients` +`GET https://api.track.toggl.com/api/v8/clients` Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ - -X GET https://www.toggl.com/api/v8/clients + -X GET https://api.track.toggl.com/api/v8/clients ``` Successful response is an array of clients @@ -133,12 +133,12 @@ Successful response is an array of clients ## Get client projects -`GET https://www.toggl.com/api/v8/clients/{client_id}/projects` +`GET https://api.track.toggl.com/api/v8/clients/{client_id}/projects` Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ - -X GET https://www.toggl.com/api/v8/clients/1239455/projects + -X GET https://api.track.toggl.com/api/v8/clients/1239455/projects ``` To filter projects by their state you can add the additional param to the request url: diff --git a/chapters/cors.md b/chapters/cors.md index f0a3d72..5c5ad49 100644 --- a/chapters/cors.md +++ b/chapters/cors.md @@ -17,7 +17,7 @@ Record id (id) can't be changed on update. ## Actions ### Create an entry -`POST https://www.toggl.com/api/v9/me/cors` +`POST https://api.track.toggl.com/api/v9/me/cors` Example request @@ -25,7 +25,7 @@ Example request curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -H "Content-Type: application/json" \ -d '{"domain":"url.com"}' \ - -X POST https://www.toggl.com/api/v9/me/cors + -X POST https://api.track.toggl.com/api/v9/me/cors ``` @@ -40,13 +40,13 @@ Successful response ### Get entries for current user -`GET https://www.toggl.com/api/v9/me/cors` +`GET https://api.track.toggl.com/api/v9/me/cors` Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ - -X GET https://www.toggl.com/api/v9/me/cors + -X GET https://api.track.toggl.com/api/v9/me/cors ``` Successful response @@ -72,12 +72,12 @@ Successful response ### Delete an entry -`DELETE https://www.toggl.com/api/v9/me/cors/{id}` +`DELETE https://api.track.toggl.com/api/v9/me/cors/{id}` Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ - -X DELETE https://www.toggl.com/api/v9/me/cors/1335076912 + -X DELETE https://api.track.toggl.com/api/v9/me/cors/1335076912 ``` Successful request will return `200 OK`. If the user has no access to delete, you'll get a status code `4xx` diff --git a/chapters/dashboard.md b/chapters/dashboard.md index d97250d..3836ced 100644 --- a/chapters/dashboard.md +++ b/chapters/dashboard.md @@ -22,12 +22,12 @@ Most active user object has the following properties ## Get Dashboard data -`GET https://www.toggl.com/api/v8/dashboard/{workspace_id}` +`GET https://api.track.toggl.com/api/v8/dashboard/{workspace_id}` Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ --X GET https://www.toggl.com/api/v8/dashboard/3134975 +-X GET https://api.track.toggl.com/api/v8/dashboard/3134975 ``` Successful response diff --git a/chapters/groups.md b/chapters/groups.md index c63f807..b897fbb 100644 --- a/chapters/groups.md +++ b/chapters/groups.md @@ -8,7 +8,7 @@ Group has the following properties ## Create a group -`POST https://www.toggl.com/api/v8/groups` +`POST https://api.track.toggl.com/api/v8/groups` Example request @@ -16,7 +16,7 @@ Example request curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -H "Content-Type: application/json" \ -d '{"group":{"name":"Developers","wid":777}}' \ - -X POST https://www.toggl.com/api/v8/groups + -X POST https://api.track.toggl.com/api/v8/groups ``` @@ -33,7 +33,7 @@ Successful response ``` ## Update a group -`PUT https://www.toggl.com/api/v8/groups/{group_id}` +`PUT https://api.track.toggl.com/api/v8/groups/{group_id}` Workspace id (wid) can't be changed. @@ -42,7 +42,7 @@ Example request curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -H "Content-Type: application/json" \ -d '{"group":{"name":"Front-end Developers"}}' \ - -X PUT https://www.toggl.com/api/v8/groups/1239455 + -X PUT https://api.track.toggl.com/api/v8/groups/1239455 ``` Successful response @@ -59,12 +59,12 @@ Successful response ## Delete a group -`DELETE https://www.toggl.com/api/v8/groups/{group_id}` +`DELETE https://api.track.toggl.com/api/v8/groups/{group_id}` Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ - -X DELETE https://www.toggl.com/api/v8/groups/1239455 + -X DELETE https://api.track.toggl.com/api/v8/groups/1239455 ``` Successful request will return `200 OK`. If the user has no access to delete, you'll get a status code `4xx` diff --git a/chapters/project_users.md b/chapters/project_users.md index 183cee6..95d3d73 100644 --- a/chapters/project_users.md +++ b/chapters/project_users.md @@ -21,7 +21,7 @@ It's possible to get user's fullname. For that you have to send the `fields` par ### Create a project user -`POST https://www.toggl.com/api/v8/project_users` +`POST https://api.track.toggl.com/api/v8/project_users` Example request @@ -29,7 +29,7 @@ Example request curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -H "Content-Type: application/json" \ -d '{"project_user":{"pid":777,"uid":123,"rate":4.0,"manager":true}}' \ - -X POST https://www.toggl.com/api/v8/project_users + -X POST https://api.track.toggl.com/api/v8/project_users ``` @@ -51,7 +51,7 @@ Successful response ### Update a project user -`PUT https://www.toggl.com/api/v8/project_users/{project_user_id}` +`PUT https://api.track.toggl.com/api/v8/project_users/{project_user_id}` Workspace id (wid), project id (pid) and user id (uid) can't be changed. @@ -60,7 +60,7 @@ Example request curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -H "Content-Type: application/json" \ -d '{"project_user":{"manager":false,"rate":15,"fields":"fullname"}}' \ - -X PUT https://www.toggl.com/api/v8/project_users/4692190 + -X PUT https://api.track.toggl.com/api/v8/project_users/4692190 ``` Successful response @@ -81,12 +81,12 @@ Successful response ### Delete a project user -`DELETE https://www.toggl.com/api/v8/project_users/{project_user_id}` +`DELETE https://api.track.toggl.com/api/v8/project_users/{project_user_id}` Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ - -X DELETE https://www.toggl.com/api/v8/project_users/4692190 + -X DELETE https://api.track.toggl.com/api/v8/project_users/4692190 ``` Successful request will return `200 OK`. If the user has no access to delete, you'll get a status code `4xx` @@ -96,7 +96,7 @@ Successful request will return `200 OK`. If the user has no access to delete, yo ### Get list of project users in a Workspace ```shell -curl -v -u TOKEN:api_token https://www.toggl.com/api/v8/workspaces/{workspace_id}/project_users +curl -v -u TOKEN:api_token https://api.track.toggl.com/api/v8/workspaces/{workspace_id}/project_users ``` Successful request will return a list of all project users in the workspace. @@ -105,7 +105,7 @@ Note: Does not support the `fields` parameter (hence a `fullname` field won't be ### Create multiple project users for single project To create multiple project users for a single project, you must add multiple user ids separated with a comma with the `uid` parameter. -`POST https://www.toggl.com/api/v8/project_users` +`POST https://api.track.toggl.com/api/v8/project_users` Example request @@ -113,7 +113,7 @@ Example request curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -H "Content-Type: application/json" \ -d '{"project_user":{"pid":777,"uid":"1267998,29624,112047","rate":4.0,"manager":true,"fields":"fullname"}}' \ - -X POST https://www.toggl.com/api/v8/project_users + -X POST https://api.track.toggl.com/api/v8/project_users ``` @@ -151,7 +151,7 @@ Successful response is an array of project_users. ### Mass update for project users By supplying multiple project user ids, you can mass update project users. -`PUT https://www.toggl.com/api/v8/project_users/{project_user_ids}` +`PUT https://api.track.toggl.com/api/v8/project_users/{project_user_ids}` Example request @@ -159,7 +159,7 @@ Example request curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -H "Content-Type: application/json" \ -d '{"project_user":{"manager":false,"rate":15,"fields":"fullname"}}' \ - -X PUT https://www.toggl.com/api/v8/project_users/4692190,4692192,4692191 + -X PUT https://api.track.toggl.com/api/v8/project_users/4692190,4692192,4692191 ``` Successful response is an array of project_users. @@ -198,12 +198,12 @@ Successful response is an array of project_users. ### Delete multiple project users By supplying multiple project user ids, you can mass delete project users. -`DELETE https://www.toggl.com/api/v8/project_users/{project_user_ids}` +`DELETE https://api.track.toggl.com/api/v8/project_users/{project_user_ids}` Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ - -X DELETE https://www.toggl.com/api/v8/project_users/4692190,4692192,4692193 + -X DELETE https://api.track.toggl.com/api/v8/project_users/4692190,4692192,4692193 ``` Successful request will return `200 OK`. If the user has no access to delete, you'll get a status code `4xx` diff --git a/chapters/projects.md b/chapters/projects.md index 94f5bba..e12fc36 100644 --- a/chapters/projects.md +++ b/chapters/projects.md @@ -20,7 +20,7 @@ Project has the following properties ## Create project -`POST https://www.toggl.com/api/v8/projects` +`POST https://api.track.toggl.com/api/v8/projects` Example request @@ -28,7 +28,7 @@ Example request curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -H "Content-Type: application/json" \ -d '{"project":{"name":"An awesome project","wid":777,"template_id":10237,"is_private":true,"cid":123397}}' \ - -X POST https://www.toggl.com/api/v8/projects + -X POST https://api.track.toggl.com/api/v8/projects ``` Successful response @@ -51,13 +51,13 @@ Successful response ## Get project data -`GET https://www.toggl.com/api/v8/projects/{project_id}` +`GET https://api.track.toggl.com/api/v8/projects/{project_id}` Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ - -X GET https://www.toggl.com/api/v8/projects/193838628 + -X GET https://api.track.toggl.com/api/v8/projects/193838628 ``` @@ -81,7 +81,7 @@ Successful response ## Update project data -`PUT https://www.toggl.com/api/v8/projects/{project_id}` +`PUT https://api.track.toggl.com/api/v8/projects/{project_id}` Example request @@ -89,7 +89,7 @@ Example request curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -H "Content-Type: application/json" \ -d '{"project":{"name":"Changed the name","is_private":false,"cid":123398, "color": "6"}}' \ - -X PUT https://www.toggl.com/api/v8/projects/193838628 + -X PUT https://api.track.toggl.com/api/v8/projects/193838628 ``` @@ -112,24 +112,24 @@ Successful response ## Delete a project -`DELETE https://www.toggl.com/api/v8/projects/{project_id}` +`DELETE https://api.track.toggl.com/api/v8/projects/{project_id}` Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ - -X DELETE https://www.toggl.com/api/v8/projects/4692190 + -X DELETE https://api.track.toggl.com/api/v8/projects/4692190 ``` ## Get project users -`GET https://www.toggl.com/api/v8/projects/{project_id}/project_users` +`GET https://api.track.toggl.com/api/v8/projects/{project_id}/project_users` Read more about project user fields from [here](project_users.md). Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ - -X GET https://www.toggl.com/api/v8/projects/193838628/project_users + -X GET https://api.track.toggl.com/api/v8/projects/193838628/project_users ``` @@ -158,14 +158,14 @@ Successful response is an array of the project's users ## Get project tasks Available for Starter, Premium and Enterprise workspaces -`GET https://www.toggl.com/api/v8/projects/{project_id}/tasks` +`GET https://api.track.toggl.com/api/v8/projects/{project_id}/tasks` Read more about task fields from [here](tasks.md). Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ - -X GET https://www.toggl.com/api/v8/projects/777/tasks + -X GET https://api.track.toggl.com/api/v8/projects/777/tasks ``` @@ -202,10 +202,10 @@ Retrieving workspace projects is documented [here](workspaces.md#get-workspace-p ### Delete multiple projects By supplying multiple projectuser ids, you can mass delete projects. -`DELETE https://www.toggl.com/api/v8/projects/{project_ids}` +`DELETE https://api.track.toggl.com/api/v8/projects/{project_ids}` Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ - -X DELETE https://www.toggl.com/api/v8/projects/4692190,4692192,4692193 + -X DELETE https://api.track.toggl.com/api/v8/projects/4692190,4692192,4692193 ``` diff --git a/chapters/tags.md b/chapters/tags.md index 2510e7f..e8013ed 100644 --- a/chapters/tags.md +++ b/chapters/tags.md @@ -7,7 +7,7 @@ Tag has the following properties ## Create tag -`POST https://www.toggl.com/api/v8/tags` +`POST https://api.track.toggl.com/api/v8/tags` Example request @@ -15,7 +15,7 @@ Example request curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -H "Content-Type: application/json" \ -d '{"tag":{"name":"billed","wid":777}}' \ - -X POST https://www.toggl.com/api/v8/tags + -X POST https://api.track.toggl.com/api/v8/tags ``` @@ -31,7 +31,7 @@ Successful response ``` ## Update a tag -`PUT https://www.toggl.com/api/v8/tags/{tag_id}` +`PUT https://api.track.toggl.com/api/v8/tags/{tag_id}` Workspace id (wid) can't be changed. @@ -40,7 +40,7 @@ Example request curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -H "Content-Type: application/json" \ -d '{"tag":{"name":"not billed"}}' \ - -X PUT https://www.toggl.com/api/v8/tags/1239455 + -X PUT https://api.track.toggl.com/api/v8/tags/1239455 ``` Successful response @@ -56,12 +56,12 @@ Successful response ## Delete a tag -`DELETE https://www.toggl.com/api/v8/tags/{tag_id}` +`DELETE https://api.track.toggl.com/api/v8/tags/{tag_id}` Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ - -X DELETE https://www.toggl.com/api/v8/tags/1239455 + -X DELETE https://api.track.toggl.com/api/v8/tags/1239455 ``` Successful request will return `200 OK`. If the user has no access to delete, you'll get a status code `4xx` \ No newline at end of file diff --git a/chapters/tasks.md b/chapters/tasks.md index c6c35be..e56d330 100644 --- a/chapters/tasks.md +++ b/chapters/tasks.md @@ -17,7 +17,7 @@ Workspace id (wid) and project id (pid) can't be changed on update. ## Actions for single project user ### Create a task -`POST https://www.toggl.com/api/v8/tasks` +`POST https://api.track.toggl.com/api/v8/tasks` Example request @@ -25,7 +25,7 @@ Example request curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -H "Content-Type: application/json" \ -d '{"task":{"name":"A new task","pid":777}}' \ - -X POST https://www.toggl.com/api/v8/tasks + -X POST https://api.track.toggl.com/api/v8/tasks ``` @@ -45,13 +45,13 @@ Successful response ### Get task details -`GET https://www.toggl.com/api/v8/tasks/{task_id}` +`GET https://api.track.toggl.com/api/v8/tasks/{task_id}` Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ - -X GET https://www.toggl.com/api/v8/tasks/1335076912 + -X GET https://api.track.toggl.com/api/v8/tasks/1335076912 ``` Successful response @@ -70,14 +70,14 @@ Successful response ### Update a task -`PUT https://www.toggl.com/api/v8/tasks/{task_id}` +`PUT https://api.track.toggl.com/api/v8/tasks/{task_id}` Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -H "Content-Type: application/json" \ -d '{"task":{"active":false,"estimated_seconds":3600,"fields":"done_seconds,uname"}}' \ - -X PUT https://www.toggl.com/api/v8/tasks/1335076912 + -X PUT https://api.track.toggl.com/api/v8/tasks/1335076912 ``` Successful response @@ -99,12 +99,12 @@ Successful response ### Delete a task -`DELETE https://www.toggl.com/api/v8/tasks/{task_id}` +`DELETE https://api.track.toggl.com/api/v8/tasks/{task_id}` Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ - -X DELETE https://www.toggl.com/api/v8/tasks/1335076912 + -X DELETE https://api.track.toggl.com/api/v8/tasks/1335076912 ``` Successful request will return `200 OK`. If the user has no access to delete, you'll get a status code `4xx` @@ -115,14 +115,14 @@ Successful request will return `200 OK`. If the user has no access to delete, yo By supplying multiple task ids, you can mass update tasks. This is good for marking tasks as done or not done (`active`). -`PUT https://www.toggl.com/api/v8/tasks/{task_ids}` +`PUT https://api.track.toggl.com/api/v8/tasks/{task_ids}` Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -H "Content-Type: application/json" \ -d '{"task":{"active":false,"fields":"done_seconds,uname"}}' \ - -X PUT https://www.toggl.com/api/v8/tasks/1335076912,1335076911 + -X PUT https://api.track.toggl.com/api/v8/tasks/1335076912,1335076911 ``` Successful response is an array of tasks. @@ -155,12 +155,12 @@ Successful response is an array of tasks. ### Delete multiple tasks By supplying multiple task ids, you can mass delete tasks. -`DELETE https://www.toggl.com/api/v8/tasks/{task_ids}` +`DELETE https://api.track.toggl.com/api/v8/tasks/{task_ids}` Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ - -X DELETE https://www.toggl.com/api/v8/tasks/1335076912,1335076911,1335076910 + -X DELETE https://api.track.toggl.com/api/v8/tasks/1335076912,1335076911,1335076910 ``` Successful request will return `200 OK`. If the user has no access to delete, you'll get a status code `4xx` diff --git a/chapters/time_entries.md b/chapters/time_entries.md index d7b1d58..a538042 100644 --- a/chapters/time_entries.md +++ b/chapters/time_entries.md @@ -19,7 +19,7 @@ Time entry has the following properties ## Create a time entry -`POST https://www.toggl.com/api/v8/time_entries` +`POST https://api.track.toggl.com/api/v8/time_entries` Example request @@ -27,7 +27,7 @@ Example request curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -H "Content-Type: application/json" \ -d '{"time_entry":{"description":"Meeting with possible clients","tags":["billed"],"duration":1200,"start":"2013-03-05T07:58:58.000Z","pid":123,"created_with":"curl"}}' \ - -X POST https://www.toggl.com/api/v8/time_entries + -X POST https://api.track.toggl.com/api/v8/time_entries ``` @@ -50,7 +50,7 @@ Successful response ## Start a time entry -`POST https://www.toggl.com/api/v8/time_entries/start` +`POST https://api.track.toggl.com/api/v8/time_entries/start` Example request @@ -58,7 +58,7 @@ Example request curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -H "Content-Type: application/json" \ -d '{"time_entry":{"description":"Meeting with possible clients","tags":["billed"],"pid":123,"created_with":"curl"}}' \ - -X POST https://www.toggl.com/api/v8/time_entries/start + -X POST https://api.track.toggl.com/api/v8/time_entries/start ``` @@ -81,13 +81,13 @@ Successful response ## Stop a time entry -`PUT https://www.toggl.com/api/v8/time_entries/{time_entry_id}/stop` +`PUT https://api.track.toggl.com/api/v8/time_entries/{time_entry_id}/stop` Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -H "Content-Type: application/json" \ - -X PUT https://www.toggl.com/api/v8/time_entries/436694100/stop + -X PUT https://api.track.toggl.com/api/v8/time_entries/436694100/stop ``` Successful response @@ -109,13 +109,13 @@ Successful response ## Get time entry details -`GET https://www.toggl.com/api/v8/time_entries/{time_entry_id}` +`GET https://api.track.toggl.com/api/v8/time_entries/{time_entry_id}` Example request: ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ --X GET https://www.toggl.com/api/v8/time_entries/436694100 +-X GET https://api.track.toggl.com/api/v8/time_entries/436694100 ``` Successful response @@ -140,13 +140,13 @@ Successful response ## Get running time entry -`GET https://www.toggl.com/api/v8/time_entries/current` +`GET https://api.track.toggl.com/api/v8/time_entries/current` Example request: ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ --X GET https://www.toggl.com/api/v8/time_entries/current +-X GET https://api.track.toggl.com/api/v8/time_entries/current ``` Successful response @@ -167,7 +167,7 @@ Successful response ## Update a time entry -`PUT https://www.toggl.com/api/v8/time_entries/{time_entry_id}` +`PUT https://api.track.toggl.com/api/v8/time_entries/{time_entry_id}` Example request @@ -175,7 +175,7 @@ Example request curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -H "Content-Type: application/json" \ -d '{"time_entry":{"description":"Meeting with possible clients","tags":[""],"duration":1240,"start":"2013-03-05T07:58:58.000Z","stop":"2013-03-05T08:58:58.000Z","duronly":true,"pid":123,"billable":true}}' \ - -X PUT https://www.toggl.com/api/v8/time_entries/436694100 + -X PUT https://api.track.toggl.com/api/v8/time_entries/436694100 ``` @@ -201,12 +201,12 @@ Successful response ## Delete a time entry -`DELETE https://www.toggl.com/api/v8/time_entries/{time_entry_id}` +`DELETE https://api.track.toggl.com/api/v8/time_entries/{time_entry_id}` Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ - -X DELETE https://www.toggl.com/api/v8/time_entries/1239455 + -X DELETE https://api.track.toggl.com/api/v8/time_entries/1239455 ``` Successful request will return `200 OK` @@ -214,7 +214,7 @@ Successful request will return `200 OK` ## Get time entries started in a specific time range -`GET https://www.toggl.com/api/v8/time_entries` +`GET https://api.track.toggl.com/api/v8/time_entries` With `start_date` and `end_date` parameters you can specify the date range of the time entries returned. If `start_date` and `end_date` are not specified, time entries started during the last 9 days are returned. **The limit of returned time entries is 1000.** So only the first 1000 found time entries are returned. To get all time entries for a specific time span, you should consider using the [detailed report](../reports/detailed.md) request, which returns paginated results, but enables you to get all the asked time entries with multiple requests. @@ -224,7 +224,7 @@ Example request with start date 2013-03-10T15:42:46+02:00 and end_date 2013-03-1 ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ - -X GET "https://www.toggl.com/api/v8/time_entries?start_date=2013-03-10T15%3A42%3A46%2B02%3A00&end_date=2013-03-12T15%3A42%3A46%2B02%3A00" + -X GET "https://api.track.toggl.com/api/v8/time_entries?start_date=2013-03-10T15%3A42%3A46%2B02%3A00&end_date=2013-03-12T15%3A42%3A46%2B02%3A00" ``` Successful response @@ -257,7 +257,7 @@ Successful response ## Bulk update time entries tags ## -`PUT https://www.toggl.com/api/v8/time_entries/{time_entry_ids_separated_by_a_comma}` +`PUT https://api.track.toggl.com/api/v8/time_entries/{time_entry_ids_separated_by_a_comma}` You can mass assign and remove tags from time entries. Just instead of one `time_entry_id`, you need to send all the time entry ids, which you want to update, separated by a comma in the request url. The request is similar to regular time entry update. @@ -274,7 +274,7 @@ Example request curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -H "Content-Type: application/json" \ -d '{"time_entry":{"tags":["billed","productive"], "tag_action": "add"}}' \ - -X PUT https://www.toggl.com/api/v8/time_entries/436694100,436694101 + -X PUT https://api.track.toggl.com/api/v8/time_entries/436694100,436694101 ``` Successful response diff --git a/chapters/users.md b/chapters/users.md index 4afce00..fc0571d 100644 --- a/chapters/users.md +++ b/chapters/users.md @@ -24,7 +24,7 @@ User has the following properties * timezone: (string) timezone user has set on the "My profile" page ( [IANA TZ timezones](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones) ) ## Get current user data ## -`GET https://www.toggl.com/api/v8/me` +`GET https://api.track.toggl.com/api/v8/me` By default the request responds with user properties. To get all the workspaces, clients, projects, tasks, time entries and tags which the user can see, add the parameter `with_related_data=true` @@ -33,7 +33,7 @@ If you want to retrieve objects which have changed after certain time, add `sinc Example request *without* related data ```shell -curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token -X GET https://www.toggl.com/api/v8/me +curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token -X GET https://api.track.toggl.com/api/v8/me ``` Successful response @@ -70,7 +70,7 @@ Successful response Example request with all the connected data ```shell -curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token -X GET https://www.toggl.com/api/v8/me?with_related_data=true +curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token -X GET https://api.track.toggl.com/api/v8/me?with_related_data=true ``` Successful response @@ -164,7 +164,7 @@ Successful response ## Update user data ## -`PUT https://www.toggl.com/api/v8/me` +`PUT https://api.track.toggl.com/api/v8/me` You can update the following user fields: * fullname: string @@ -190,7 +190,7 @@ Example request curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -H "Content-Type: application/json" \ -d '{"user":{"fullname":"John Smith"}}' \ - -X PUT https://www.toggl.com/api/v8/me + -X PUT https://api.track.toggl.com/api/v8/me ``` Successful response @@ -230,13 +230,13 @@ Successful response ``` ## Reset API token ## -`POST https://www.toggl.com/api/v8/reset_token` +`POST https://api.track.toggl.com/api/v8/reset_token` Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ - -X POST https://www.toggl.com/api/v8/reset_token + -X POST https://api.track.toggl.com/api/v8/reset_token ``` Successful response is a string with the new API token: @@ -257,13 +257,13 @@ To create a user you must provide these parameters for the user: * timezone: for example "Etc/UTC" (string, required) * created_with: in free form, name of the app that signed the user app (string, required) -`POST https://www.toggl.com/api/v8/signups` +`POST https://api.track.toggl.com/api/v8/signups` Example request ```shell curl -H "Content-Type: application/json" \ -d '{"user":{"email":"test.user@toggl.com","password":"StrongPassword"}}' \ --X POST https://www.toggl.com/api/v8/signups +-X POST https://api.track.toggl.com/api/v8/signups ``` Successful response includes created user's data and API token diff --git a/chapters/workspace_users.md b/chapters/workspace_users.md index c7c3993..44355a9 100644 --- a/chapters/workspace_users.md +++ b/chapters/workspace_users.md @@ -12,7 +12,7 @@ Workspace user has the following properties: You can add users to workspace by email addresses. A letter inviting the user to your workspace is sent to the user's email. -`POST https://www.toggl.com/api/v8/workspaces/{workspace_id}/invite` +`POST https://api.track.toggl.com/api/v8/workspaces/{workspace_id}/invite` Request has the following properties: * emails: array of emails @@ -28,7 +28,7 @@ Example request curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -H "Content-Type: application/json" \ -d '{"emails":["john.doe@toggl.com", "Jane.Swift@toggl.com"]}' \ - -X POST https://www.toggl.com/api/v8/workspaces/777/invite + -X POST https://api.track.toggl.com/api/v8/workspaces/777/invite ``` Successful response @@ -52,7 +52,7 @@ Successful response Only the admin flag can be changed. -`PUT https://www.toggl.com/api/v8/workspace_users/{workspace_user_id}` +`PUT https://api.track.toggl.com/api/v8/workspace_users/{workspace_user_id}` Example request @@ -60,7 +60,7 @@ Example request curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -H "Content-Type: application/json" \ -d '{"workspace_user":{"admin":false}}' \ - -X PUT https://www.toggl.com/api/v8/workspace_users/19012628 + -X PUT https://api.track.toggl.com/api/v8/workspace_users/19012628 ``` @@ -79,12 +79,12 @@ Successful response ## Delete workspace user -`DELETE https://www.toggl.com/api/v8/workspace_users/{workspace_user_id}` +`DELETE https://api.track.toggl.com/api/v8/workspace_users/{workspace_user_id}` Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ - -X DELETE https://www.toggl.com/api/v8/workspace_users/19012628 + -X DELETE https://api.track.toggl.com/api/v8/workspace_users/19012628 ``` Successful request will return `200 OK`. If the user has no access to delete, you'll get a status code `4xx` @@ -92,12 +92,12 @@ Successful request will return `200 OK`. If the user has no access to delete, yo ## Get workspace users This request returns not the user objects, but the `workspace_user` objects (the connection between user and workspace) -`GET https://www.toggl.com/api/v8/workspaces/{workspace_id}/workspace_users` +`GET https://api.track.toggl.com/api/v8/workspaces/{workspace_id}/workspace_users` Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ --X GET https://www.toggl.com/api/v8/workspaces/777/workspace_users +-X GET https://api.track.toggl.com/api/v8/workspaces/777/workspace_users ``` Successful response is an array of workspace's workspace users diff --git a/chapters/workspaces.md b/chapters/workspaces.md index f133126..3b97dc0 100644 --- a/chapters/workspaces.md +++ b/chapters/workspaces.md @@ -24,13 +24,13 @@ Workspace has the following properties ## Get workspaces -`GET https://www.toggl.com/api/v8/workspaces` +`GET https://api.track.toggl.com/api/v8/workspaces` Get data about all the workspaces where the token owner belongs to. Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ --X GET https://www.toggl.com/api/v8/workspaces +-X GET https://api.track.toggl.com/api/v8/workspaces ``` Successful response is an array of workspaces @@ -66,12 +66,12 @@ Successful response is an array of workspaces ``` ## Get single workspace -`GET https://www.toggl.com/api/v8/workspaces/{workspace_id}` +`GET https://api.track.toggl.com/api/v8/workspaces/{workspace_id}` Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ --X GET https://www.toggl.com/api/v8/workspaces/3134975 +-X GET https://api.track.toggl.com/api/v8/workspaces/3134975 ``` Successful response @@ -96,7 +96,7 @@ Successful response ## Update workspace -`PUT https://www.toggl.com/api/v8/workspaces/{workspace_id}` +`PUT https://api.track.toggl.com/api/v8/workspaces/{workspace_id}` Example request @@ -105,7 +105,7 @@ Example request curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -H "Content-Type: application/json" \ -d '{"workspace":{"default_currency": "EUR", "default_hourly_rate": 50, "name": "John's ws", "only_admins_may_create_projects": false, "only_admins_see_billable_rates": true, "rounding": 1, "rounding_minutes": 60}}' \ - -X PUT https://www.toggl.com/api/v8/workspaces/3134975 + -X PUT https://api.track.toggl.com/api/v8/workspaces/3134975 ``` @@ -132,12 +132,12 @@ Successful response ## Get workspace users To get a successful response, the token owner must be workspace admin. -`GET https://www.toggl.com/api/v8/workspaces/{workspace_id}/users` +`GET https://api.track.toggl.com/api/v8/workspaces/{workspace_id}/users` Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ --X GET https://www.toggl.com/api/v8/workspaces/777/users +-X GET https://api.track.toggl.com/api/v8/workspaces/777/users ``` Successful response is an array of workspace users @@ -194,12 +194,12 @@ Successful response is an array of workspace users ## Get workspace clients To get a successful response, the token owner must be workspace admin. -`GET https://www.toggl.com/api/v8/workspaces/{workspace_id}/clients` +`GET https://api.track.toggl.com/api/v8/workspaces/{workspace_id}/clients` Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ --X GET https://www.toggl.com/api/v8/workspaces/777/clients +-X GET https://api.track.toggl.com/api/v8/workspaces/777/clients ``` Successful response is an array of workspace clients @@ -228,12 +228,12 @@ Successful response is an array of workspace clients ## Get workspace groups To get a successful response, the token owner must be workspace admin. -`GET https://www.toggl.com/api/v8/workspaces/{workspace_id}/groups` +`GET https://api.track.toggl.com/api/v8/workspaces/{workspace_id}/groups` Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ --X GET https://www.toggl.com/api/v8/workspaces/777/groups +-X GET https://api.track.toggl.com/api/v8/workspaces/777/groups ``` Successful response is an array of workspace groups @@ -256,7 +256,7 @@ Successful response is an array of workspace groups ## Get workspace projects To get a successful response, the token owner must be workspace admin. -`GET https://www.toggl.com/api/v8/workspaces/{workspace_id}/projects` +`GET https://api.track.toggl.com/api/v8/workspaces/{workspace_id}/projects` To filter projects by their state you can add the additional param to the request url: * active: possible values `true`/`false`/`both`. By default true. If false, only archived projects are returned. @@ -270,7 +270,7 @@ To get only project templates add the additional param to the request url: Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ --X GET https://www.toggl.com/api/v8/workspaces/777/projects +-X GET https://api.track.toggl.com/api/v8/workspaces/777/projects ``` Successful response is an array of active workspace projects @@ -303,7 +303,7 @@ Successful response is an array of active workspace projects Available only for pro workspaces To get a successful response, the token owner must be workspace admin. Get all not done tasks in this workspace. -`GET https://www.toggl.com/api/v8/workspaces/{workspace_id}/tasks` +`GET https://api.track.toggl.com/api/v8/workspaces/{workspace_id}/tasks` To filter tasks by their state you can add the additional param to the request url: * active: possible values `true`/`false`/`both`. By default true. If false, only done tasks are returned. @@ -312,7 +312,7 @@ To filter tasks by their state you can add the additional param to the request u Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ --X GET https://www.toggl.com/api/v8/workspaces/777/tasks +-X GET https://api.track.toggl.com/api/v8/workspaces/777/tasks ``` Successful response is an array of workspace tasks @@ -350,12 +350,12 @@ Successful response is an array of workspace tasks ## Get workspace tags -`GET https://www.toggl.com/api/v8/workspaces/{workspace_id}/tags` +`GET https://api.track.toggl.com/api/v8/workspaces/{workspace_id}/tags` Example request ```shell curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ --X GET https://www.toggl.com/api/v8/workspaces/777/tags +-X GET https://api.track.toggl.com/api/v8/workspaces/777/tags ``` Successful response is an array of active workspace tags diff --git a/toggl_api.md b/toggl_api.md index 5fd8be5..31616c8 100644 --- a/toggl_api.md +++ b/toggl_api.md @@ -20,7 +20,7 @@ Example request curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -H "Content-Type: application/json" \ -d '{"time_entry":{"description":"New time entry","created_with":"API example code","start":"2012-02-12T15:35:47+02:00","duration":1200,"wid":31366}}' \ - -X POST https://www.toggl.com/api/v8/time_entries + -X POST https://api.track.toggl.com/api/v8/time_entries ``` Response @@ -51,7 +51,7 @@ If a create or update action failed, HTTP status code 404 and an array of locali curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \ -H 'Content-Type: application/json' \ -d '{"time_entry":{"description":"New time entry","created_with":"API example code"}}' \ - -X POST https://www.toggl.com/api/v8/time_entries + -X POST https://api.track.toggl.com/api/v8/time_entries ``` Response From 68f72605bf86c80da472b731d37e12c64706403b Mon Sep 17 00:00:00 2001 From: gilberthdez Date: Mon, 7 Sep 2020 12:10:08 +0200 Subject: [PATCH 100/113] update url --- reports.md | 8 ++++---- reports/detailed.md | 2 +- reports/summary.md | 2 +- reports/weekly.md | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/reports.md b/reports.md index 71dceb2..f0041f6 100644 --- a/reports.md +++ b/reports.md @@ -11,13 +11,13 @@ More detailed information for the reports. ## URLs -The reports API base URL is `https://toggl.com/reports/api/v2` +The reports API base URL is `https://api.track.toggl.com/reports/api/v2` -Weekly report URL `GET https://toggl.com/reports/api/v2/weekly` +Weekly report URL `GET https://api.track.toggl.com/reports/api/v2/weekly` -Detailed report URL: `GET https://toggl.com/reports/api/v2/details` +Detailed report URL: `GET https://api.track.toggl.com/reports/api/v2/details` -Summary report URL: `GET https://toggl.com/reports/api/v2/summary` +Summary report URL: `GET https://api.track.toggl.com/reports/api/v2/summary` For PDF response add .pdf to the end of the URL. For CSV response add .csv as well. diff --git a/reports/detailed.md b/reports/detailed.md index 35c4e60..8c814c6 100644 --- a/reports/detailed.md +++ b/reports/detailed.md @@ -39,7 +39,7 @@ Time entry data Example request ```shell -curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token -X GET "https://toggl.com/reports/api/v2/details?workspace_id=123&since=2013-05-19&until=2013-05-20&user_agent=api_test" +curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token -X GET "https://api.track.toggl.com/reports/api/v2/details?workspace_id=123&since=2013-05-19&until=2013-05-20&user_agent=api_test" ``` diff --git a/reports/summary.md b/reports/summary.md index 14bb073..0081c2f 100644 --- a/reports/summary.md +++ b/reports/summary.md @@ -77,7 +77,7 @@ When grouped by project the title part of the return will contain color and colo Example request ```shell -curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token -X GET "https://toggl.com/reports/api/v2/summary?workspace_id=123&since=2013-05-19&until=2013-05-20&user_agent=api_test" +curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token -X GET "https://api.track.toggl.com/reports/api/v2/summary?workspace_id=123&since=2013-05-19&until=2013-05-20&user_agent=api_test" ``` diff --git a/reports/weekly.md b/reports/weekly.md index 65b8171..70c8141 100644 --- a/reports/weekly.md +++ b/reports/weekly.md @@ -91,7 +91,7 @@ If `calculate=earnings`, it is an array of objects with currency string and the Example request ```shell -curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token -X GET "https://toggl.com/reports/api/v2/weekly?workspace_id=123&since=2013-05-19&until=2013-05-20&user_agent=api_test" +curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token -X GET "https://api.track.toggl.com/reports/api/v2/weekly?workspace_id=123&since=2013-05-19&until=2013-05-20&user_agent=api_test" ``` Successful response @@ -148,7 +148,7 @@ require 'JSON' wsid = # your workspace id api_token = #your api token -uri = URI("https://toggl.com/reports/api/v2/weekly?workspace_id=#{wsid}&since=2014-03-01&until=2014-03-05&user_agent=api_example_test") +uri = URI("https://api.track.toggl.com/reports/api/v2/weekly?workspace_id=#{wsid}&since=2014-03-01&until=2014-03-05&user_agent=api_example_test") req = Net::HTTP::Get.new(uri) req.basic_auth api_token, 'api_token' From 7a5133ef0d92cecccb778856ba322787e7067d07 Mon Sep 17 00:00:00 2001 From: gilberthdez Date: Mon, 7 Sep 2020 12:20:29 +0200 Subject: [PATCH 101/113] other urls fixes --- reports.md | 6 +++--- reports/project.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/reports.md b/reports.md index f0041f6..64fa08a 100644 --- a/reports.md +++ b/reports.md @@ -1,7 +1,7 @@ Toggl Reports API v2 ================= -Here you can get the general information about how to use Toggl reports API, from how to authenticate, what filters to use and how the response is structured. The available reports are similar to the reports available in [Toggl reports page](https://www.toggl.com/app/reports). +Here you can get the general information about how to use Toggl reports API, from how to authenticate, what filters to use and how the response is structured. The available reports are similar to the reports available in [Toggl reports page](https://track.toggl.com/reports). More detailed information for the reports. * [Weekly report](reports/weekly.md) @@ -118,6 +118,6 @@ Example warning Warning:Human readable warning message There are two test endpoints, that return error so you can test client side -error handling: [Error 400](https://www.toggl.com/reports/api/v2/error400) and -[Error 500](https://www.toggl.com/reports/api/v2/error500) both of them set +error handling: [Error 400](https://api.track.toggl.com/reports/api/v2/error400) and +[Error 500](https://api.track.toggl.com/reports/api/v2/error500) both of them set Warning header to test value. diff --git a/reports/project.md b/reports/project.md index 51bc0a6..d11aea9 100644 --- a/reports/project.md +++ b/reports/project.md @@ -69,7 +69,7 @@ Project dashboard response has following strucure: ([json schema] request: ```shell -curl -u my-secret-toggl-api-token:api_token -X GET "https://www.toggl.com/reports/api/v2/project/?page=1&user_agent=devteam@example.com&workspace_id=1&project_id=2" +curl -u my-secret-toggl-api-token:api_token -X GET "https://api.track.toggl.com/reports/api/v2/project/?page=1&user_agent=devteam@example.com&workspace_id=1&project_id=2" ``` response (formatted for readability): From 6ff8bb35c5dc271d7a455a0177dde2b82872a9f7 Mon Sep 17 00:00:00 2001 From: Patrick Jusic Date: Fri, 27 Nov 2020 10:44:22 +0100 Subject: [PATCH 102/113] Update C++ open source lib reference from private toggldestkop to toggl-open-source --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b12c604..1de724c 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ The Toggl API has moved to Github so you could actively participate in helping u ### C++ -* TogglDesktop has an [open source, cross platform library](https://github.com/toggl/toggldesktop/tree/master/src/lib) that can be reused in your own apps. +* TogglDesktop has an [open source, cross platform library](https://github.com/toggl-open-source/toggldesktop/tree/master/src/lib) that can be reused in your own apps. ### .NET From f66abca700a8f505c3591775af44455eef3f255b Mon Sep 17 00:00:00 2001 From: gilberthdez Date: Tue, 16 Mar 2021 19:29:48 +0100 Subject: [PATCH 103/113] add warning --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 1de724c..a20687f 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,13 @@ Toggl API Documentation ==================== +> :warning: **Using the API from toggl.com or www.toggl.com will be dropped soon use api.track.toggl.com** + Toggl API is divided into two * [Toggl API](toggl_api.md) * [Reports API](reports.md) - For changing data, including tracking time, you'll need to use the **Toggl API**. If you want to get time entries of all the workspace users and aggregated data for reporting, you need to use the read-only **Reports API**, which gives you many options for filtering, grouping and sorting. From 980338a33befcdfcb6caa331bcd2d84dc3eb8837 Mon Sep 17 00:00:00 2001 From: gilberthdez Date: Fri, 23 Apr 2021 16:16:38 +0200 Subject: [PATCH 104/113] add end date --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a20687f..d1c86e1 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ Toggl API Documentation ==================== -> :warning: **Using the API from toggl.com or www.toggl.com will be dropped soon use api.track.toggl.com** +> :warning: **Using the API from toggl.com or www.toggl.com will be dropped at The End of June 2021. Switch to api.track.toggl.com** Toggl API is divided into two From 92052f71fa62a047102d6d44cf0b7b8b38b96ae6 Mon Sep 17 00:00:00 2001 From: "M. Kevin Piotrkowski" Date: Wed, 20 Oct 2021 12:33:17 -0300 Subject: [PATCH 105/113] Remove reference to TogglAPI.Net project This project is still using the old toggl.com domain in its defaul settings. SRE is gradually dropping support for the old domain by reducing the number of allowed requests. We should not keep listing a project which has not updated the default domain after more than a year from the rebranding. --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index d1c86e1..f24e665 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,6 @@ The Toggl API has moved to Github so you could actively participate in helping u ### .NET * The Toggl mobile apps have [shared C# libraries](https://github.com/toggl/mobileapp) which provide access to the API and also common clientside business logic we use. Feel free to use as little or much of it as you want. -* [Ilya Pirozhenko](https://github.com/sochix) has written a .NET library: https://www.nuget.org/packages/TogglAPI.Net/ ### Scala * [Gabriele Alese](https://github.com/gabalese) has written a command line client for Toggl: https://github.com/gabalese/toggl-cli From 9248b78f8a9f199d5e5b2d754d925718251cf98d Mon Sep 17 00:00:00 2001 From: "M. Kevin Piotrkowski" Date: Mon, 24 Jan 2022 10:16:11 -0300 Subject: [PATCH 106/113] Add reference to Arduino project --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index d1c86e1..87e1e9c 100644 --- a/README.md +++ b/README.md @@ -92,6 +92,7 @@ The Toggl API has moved to Github so you could actively participate in helping u ## 3rd party apps * [Federico Vaga](https://github.com/FedericoVaga) has written a little plasmoid for KDE: https://github.com/FedericoVaga/plasmoggl (on opendesktop: http://opendesktop.org/content/show.php/Plasmoggl?content=168536) * [rocketbase-io](https://github.com/rocketbase-io/toggl-reporter) has written a tiny SpringBoot-Application, build with vaadin and mongodb, that pulls your TimeEntries from toggl. The stored information allow a fine grained reporting and analysis that aren't possible within toggl (like detailed working hours in comparison between team-members and many more). A [docker-image](https://hub.docker.com/r/rocketbaseio/toggl-reporter/) is also provided... + * [Chingiz Nazar](https://github.com/sultanbekuly) created an Arduino project to track time using Toggl Track API. This project allows building a home-made paper cube which can be configured to start tracking time depending on which side of the cube is facing upwards: [time_tracker_cube](https://github.com/sultanbekuly/time_tracker_cube). An article explaining the development and usage of this project is also available: [Building an Arduino Time Tracker Cube with Toggl's Open API](https://hackernoon.com/building-an-arduino-time-tracker-cube-with-toggls-open-api). ### Perl * [Jason Kruczynski](https://github.com/jkruczynski) has written a perl wrapper for the API. It creates and authenticates a session for API V8 or API V2 depending on the URL. It implements a few functions for exporting reports. https://github.com/jkruczynski/Toggl-API-Wrapper-Perl From d1e73668f272e7070ad3d4e2279638b5d84bf77d Mon Sep 17 00:00:00 2001 From: "M. Kevin Piotrkowski" Date: Tue, 31 May 2022 00:17:48 -0300 Subject: [PATCH 107/113] Add docs for Webhooks API v1 --- README.md | 7 +- webhooks.md | 248 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 252 insertions(+), 3 deletions(-) create mode 100644 webhooks.md diff --git a/README.md b/README.md index c5d7f28..61fc600 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,18 @@ Toggl API Documentation ==================== -> :warning: **Using the API from toggl.com or www.toggl.com will be dropped at The End of June 2021. Switch to api.track.toggl.com** - -Toggl API is divided into two +Toggl API is divided into three: * [Toggl API](toggl_api.md) * [Reports API](reports.md) +* [Webhooks API](webhooks.md) For changing data, including tracking time, you'll need to use the **Toggl API**. If you want to get time entries of all the workspace users and aggregated data for reporting, you need to use the read-only **Reports API**, which gives you many options for filtering, grouping and sorting. +For monitoring data changes in a workspace, you'll need the **Webhooks API**. + ## The API Format The API accepts only JSON requests. Please make sure you're setting `Content-Type: application/json`in your request header. Each request returns a **JSON-encoded** body. diff --git a/webhooks.md b/webhooks.md new file mode 100644 index 0000000..a5adb3c --- /dev/null +++ b/webhooks.md @@ -0,0 +1,248 @@ +Toggl Webhooks API v1 +===================== + +Here you can get the general information about how to use Toggl Webhooks API: how to authenticate, create and list webhooks subscription, validate their URL endpoints and validate the received payloads. + +## Authentication +
+ +You can authenticate to the Webhooks API **only** with your API token. For HTTP Basic Auth you have to add the Authorization header with the request. +The API token is the user name and the string `api_token` is the password. +Whenever possible, please use the tools and interfaces provided by your http library to do Basic Auth (for example, curl uses the -u switch to allow for it). +
+ +## Interacting with the API +
+ +**Notes**: + * the Webhooks API base URL is `https://track.toggl.com/webhooks/api/v1`, + * we provide example requests using [curl](https://curl.se/), + * we parse request responses using [jq](https://stedolan.github.io/jq/), + * in the examples you should replace `{}` with the corresponding value. + +### Request Parameters + +The API expects the following parameters: +* `workspace_id`: **Required**. The workspace ID for your webhooks subscription/s, to be provided in the URL path. +* `User-Agent`: **Suggested**. The name of your application or your email address so we can get in touch in case you're doing something wrong. To be provided as a HTTP header. + + +### List available subscriptions for a given workspace +``` +curl -u {api_token}:api_token \ + -H 'User-Agent: {user_agent}' \ + https://track.toggl.com/webhooks/api/v1/subscriptions/{workspace_id} | jq . +``` + +### Create a subscription +``` +curl -u {api_token}:api_token \ + -d '{ + "url_callback": "{url_callback}", + "event_filters": [ + {"entity": "project", "action": "created"}, + {"entity": "tag", "action": "*"} + ], + "enabled": true, + "description": "My first Webhooks subscription" + }' \ + -H 'User-Agent: {user_agent}' \ + https://track.toggl.com/webhooks/api/v1/subscriptions/{workspace_id} | jq . +``` +Response example: +```json +{ + "subscription_id": 1, + "workspace_id": {workspace_id}, + "user_id": ..., + "enabled": true, + "description": "My first Webhooks subscription", + "event_filters": [ + { + "entity": "project", + "action": "created" + }, + { + "entity": "tag", + "action": "*" + } + ], + "url_callback": {url_callback}, + "secret": ..., + "validated_at": null, + "has_pending_events": false, + "created_at": "2022-05-31T02:50:45.984607Z" +} +``` + +**Notes**: + * replace `{url_callback}` with the URL endpoint that will receive request for this webhooks subscription, + * after creating the subscription you still need to [validate](#validating-a-url-endpoint) its `url_callback`. + +#### About Event Filters +Event Filters allow you to reduce the scope of received events. They currently provide filtering capabilities by entity type and HTTP action applied over them. + +Some possible event filters that you can build would be: +1. All events for created projects: +```js + event_filters": [ + {"entity": "project", "action": "created"} + ] +``` +2. All events for tags: +```js + event_filters": [ + {"entity": "tag", "action": "*"} + ] +``` +3. All events that occurred in a workspace: +```js + event_filters": [ + {"entity": "*", "action": "*"} + ] +``` +4. All updated time entries and clients: +```js + event_filters": [ + {"entity": "time_entry", "action": "updated"}, + {"entity": "client", "action": "updated"} + ] +``` +In any case, there would be authorization checks in place to also filter out the events that the creator of the subscription does not have permission to see. + +You can get a list of supported entities and actions by using the endpoint `https://track.toggl.com/webhooks/api/v1/event_filters` +``` +curl -u {api_token}:api_token \ + -H 'User-Agent: {user_agent}' \ + https://track.toggl.com/webhooks/api/v1/event_filters | jq . +``` + +### Update a subscription +``` +curl -u {api_token}:api_token \ + -X PUT \ + -d '{ + "url_callback": "{url_callback}", + "event_filters": [ + {"entity": "*", "action": "*"} + ] + "enabled": true, + "secret": "new secret string", + "description": "My first Webhooks subscription" + }' \ + -H 'User-Agent: {user_agent}' \ + https://track.toggl.com/webhooks/api/v1/subscriptions/{workspace_id}/{subscription_id} | jq . +``` + +### Change enabled flag in a subscription +``` +curl -u {api_token}:api_token \ + -X PATCH \ + -d '{"enabled": false}' \ + -H 'User-Agent: {user_agent}' \ + https://track.toggl.com/webhooks/api/v1/subscriptions/{workspace_id}/{subscription_id} | jq . +``` + +### Delete a subscription +``` +curl -u {api_token}:api_token \ + -X DELETE \ + -H 'User-Agent: {user_agent}' \ + https://track.toggl.com/webhooks/api/v1/subscriptions/{workspace_id}/{subscription_id} | jq . +``` + +### Ping a subscription to test the setup +You will receive a dummy event in the registered URL endpoint for `{subscription_id}`. +``` +curl -u {api_token}:api_token \ + -X POST \ + -H 'User-Agent: {user_agent}' \ + https://track.toggl.com/webhooks/api/v1/ping/{workspace_id}/{subscription_id} | jq . +``` + +### Get information about matching events for a subscription +We store events that we attempted to deliver to a subscription for a week, you can get information about them (creation date, number of failed delivery attempts, last delivery error, ...) by using the special endpoint `/subscriptions/{workspace_id}/{subscription_id}/events`. + +``` +curl -u {api_token}:api_token \ + -H 'User-Agent: {user_agent}' \ + https://track.toggl.com/webhooks/api/v1/subscriptions/{workspace_id}/{subscription_id}/events` | jq . +``` +Response example: +```json +{ + "total": 2, + "events": [ + { + "event_id": ..., + "created_at": "2022-05-31T02:56:52.493Z", + "creator_id": ..., + "metadata": { + "path": "/api/v9/workspaces/{workspace_id}/projects", + "model": "project", + "action": "created", + "project_id": ..., + "request_type": "POST", + "workspace_id": "{workspace_id}", + "event_user_id": ... + }, + "payload": { + ... + }, + "consumer_id": ..., + "last_delivery_attempt": "2022-05-31T02:56:54.205984Z", + "last_delivery_error": null, + "failed_delivery_attempts": 3 + }, + ... + ] +} +``` +
+ +## Validating a URL endpoint + +
+For a subscription to receive events it has to be both enabled and validated. +The objective of the validation is for the end user to prove that they have access to the events we will send to the URL endpoint. Otherwise, a malicious user could provide us with a valid URL endpoint, that accepts POST requests and returns the expected 2xx status to our requests but that is not associated with the user who created the subscription. In such a scenario we would be sending unsolicited requests to this URL, potentially creating a denial of service. +The validation part can take any of two forms: one synchronous and one asynchronous. + +#### Synchronous Validation +In our special PING events the system will include the `validation_code` field for non-validated subscriptions and we will read the response body trying to parse this structure: +```json + {"validation_code": ""} +``` +Where `` must be the code we included in our PING event. + +#### Asynchronous Validation +Requiring users to implement this behavior in their endpoints could be too much of a burden or they could not even be able to accomplish it if the endpoint service is provided by a third party. In such scenarios we also provide an alternative asynchronous validation scheme where end users need to perform a GET request to `/webhooks/api/v1/validate/{workspace_id}/{subscription_id}/{validation_code}`. If everything is fine, then an OK response will be returned and the subscription will be set as validated. +
+ +## Validating received events + +
+ +In order to be sure that Toggl is the one sending events to your URL endpoint we include a special HTTP header `X-Webhook-Signature-256` that you can use to validate that no one else is sending those requests. + +In order to perform this validation you should: +- Set the field `secret` while creating a new subscription. If omitted, the system will assign one automatically. +- When delivering events to your subscription's URL endpoint the system will add the `X-Webhook-Signature-256` header. +- Signature has the form of `sha256={value}` where value is a HMAC hash based on SHA256 algorithm + secret + body. +- Example: `sha256=6d011bcd0b5bfb7e45372af01bc18f30cc04599df72eca189cdac1094008b095`. +
+ + +## Glossary + +
+ +Common used terms in this document + + +* **Event Filter**: allows you to specify which events a given subscription should receive in its configured URL callback. A subscription may have multiple event filters, but must have at least one. +* **Subscription**: a Webhooks subscription is an entity tied to a single workspace and user creator that has a description, a secret, a set of event filters, a url callback and a enabled and validation status. A user may have multiple subscriptions and a workspace may have multiple subscriptions from different users, but there's a limit of subscriptions per user and workspace. +* **URL callback**: is the URL destination endpoint for a subscription. The system will validate that it's both reachable and returns a 2xx status before starting to forward events to it. +* **User Creator**: given a subscription, the user creator is the one who set it up. Any event sent to the configured url callback will be validated using the permissions of this user. If the user creator doesn't have permission to see some entity, then events related to that entity won't be forwarded to the URL callback. A workspace administrator may list and edit subscriptions from other users in that workspace. +* **Validation Status**: each created subscription must be validated before it can start receiving events. This validation step is to ensure that the creator has access to the provided URL callback. Otherwise, it would mean that Toggl is sending unsolicited events to the configured URL. A non-validated and not enabled subscription may still receive the special PING event which is useful to test that you can receive events from Toggl. + +
From 1d7a95b9419560b1df9caca10afbd05553b73e33 Mon Sep 17 00:00:00 2001 From: Kevin Piotrkowski Date: Mon, 20 Jun 2022 19:48:36 -0300 Subject: [PATCH 108/113] Add links to new official documentation channel --- toggl_api.md | 6 ++++++ webhooks.md | 6 ++++++ 2 files changed, 12 insertions(+) diff --git a/toggl_api.md b/toggl_api.md index 31616c8..dd9ceb4 100644 --- a/toggl_api.md +++ b/toggl_api.md @@ -1,6 +1,12 @@ Toggl API v8 ==================== +### Important + +Toggl API **v9** is our current supported version which is documented at https://developers.track.toggl.com/docs + +---- + The API accepts only JSON requests. Please make sure you're setting `Content-Type: application/json`in your request header. Each request returns a **JSON-encoded** body. If the time entry is currently running, the *duration* attribute contains a negative value, denoting the start of the time entry in seconds since epoch (Jan 1 1970). The correct duration can be calculated as current_time + duration, where current_time is the current time in seconds since epoch. diff --git a/webhooks.md b/webhooks.md index a5adb3c..3feb505 100644 --- a/webhooks.md +++ b/webhooks.md @@ -1,6 +1,12 @@ Toggl Webhooks API v1 ===================== +### Important + +This document has been migrated to https://developers.track.toggl.com/docs/webhooks_start + +---- + Here you can get the general information about how to use Toggl Webhooks API: how to authenticate, create and list webhooks subscription, validate their URL endpoints and validate the received payloads. ## Authentication From d4232e9cb0cca021adad49f42a9c9eefa9e01336 Mon Sep 17 00:00:00 2001 From: Kevin Piotrkowski Date: Wed, 22 Jun 2022 08:42:52 -0300 Subject: [PATCH 109/113] Add deprecation notice for docs in this repo Also, guide devs towards https://developers.track.toggl.space/docs/ --- README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/README.md b/README.md index 61fc600..0d430d7 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,14 @@ Toggl API Documentation ==================== +## Important + +We're moving to https://developers.track.toggl.space/docs/ where you will find up-to date docs for both the Toggl API and Webhooks API services. + +In the meanwhile you can continue using these docs for the Reports API. + +---- + Toggl API is divided into three: * [Toggl API](toggl_api.md) From f0e932d1311474c304e4954b6de3946f2ee98618 Mon Sep 17 00:00:00 2001 From: Kevin Piotrkowski Date: Wed, 22 Jun 2022 11:09:27 -0300 Subject: [PATCH 110/113] Use production URL for new docs --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0d430d7..6ef7360 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ Toggl API Documentation ## Important -We're moving to https://developers.track.toggl.space/docs/ where you will find up-to date docs for both the Toggl API and Webhooks API services. +We're moving to https://developers.track.toggl.com/docs/ where you will find up-to date docs for both the Toggl API and Webhooks API services. In the meanwhile you can continue using these docs for the Reports API. From 0c92b6d824b81d14e2a7675b7dd41e22060badc3 Mon Sep 17 00:00:00 2001 From: Joeri Harleman <60932572+joeriharleman@users.noreply.github.com> Date: Thu, 23 Jun 2022 10:19:57 +0200 Subject: [PATCH 111/113] Update README.md --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 6ef7360..a07e74a 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@ Toggl API Documentation ==================== -## Important +## ⚠️ Important ⚠️ -We're moving to https://developers.track.toggl.com/docs/ where you will find up-to date docs for both the Toggl API and Webhooks API services. +We're moving our documentation to https://developers.track.toggl.com/docs/ where you will find up-to date docs for both the Toggl API and Webhooks API services. We're also working on moving the Reports API documentation soon, but for now this repository can still be used for the Reports API. -In the meanwhile you can continue using these docs for the Reports API. +If you're running into issues or require help with anything, please contact our dedicated 24/5 support staff over on [our support pages](https://support.toggl.com/en/). You can chat with them using the icon on the right bottom. ---- From 34f78fa35322d74df9d514d5d7fcf06c90ab52b7 Mon Sep 17 00:00:00 2001 From: Kevin Piotrkowski Date: Fri, 24 Jun 2022 22:40:22 -0300 Subject: [PATCH 112/113] Update webhooks.md Add missing comma to get a valid JSON for the PUT example --- webhooks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/webhooks.md b/webhooks.md index 3feb505..8454745 100644 --- a/webhooks.md +++ b/webhooks.md @@ -131,7 +131,7 @@ curl -u {api_token}:api_token \ "url_callback": "{url_callback}", "event_filters": [ {"entity": "*", "action": "*"} - ] + ], "enabled": true, "secret": "new secret string", "description": "My first Webhooks subscription" From 43bfadea8edd2c66fd19013fffdf2d0bd9b032f1 Mon Sep 17 00:00:00 2001 From: Kevin Piotrkowski Date: Mon, 28 Nov 2022 09:11:22 -0300 Subject: [PATCH 113/113] Remove note about new Reports docs still being worked on --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a07e74a..93c1159 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ Toggl API Documentation ## ⚠️ Important ⚠️ -We're moving our documentation to https://developers.track.toggl.com/docs/ where you will find up-to date docs for both the Toggl API and Webhooks API services. We're also working on moving the Reports API documentation soon, but for now this repository can still be used for the Reports API. +We have migrated our documentation to https://developers.track.toggl.com/docs/. There, you will find up-to date API docs for the Toggl Track, Reports and Webhooks services. If you're running into issues or require help with anything, please contact our dedicated 24/5 support staff over on [our support pages](https://support.toggl.com/en/). You can chat with them using the icon on the right bottom.