Menu
Developers welcome! The mite.api is looking forward to your precious hacking. Have a look at the detailed documentation to kick-start your coding.

Please note: A user with the role time tracker can only access his own time entries. Only administrators are able to create, modify and delete entries of other users.

List all time entries

List all time entries of all users, sorted by date_at. Time trackers can only access their own entries.

GET /time_entries.xml
GET /time_entries.json

Parameters

user_id Filters the list by user. Can be either a single ID, current for the authenticated user, or multiple comma-separated IDs.
customer_id Filters the list by customer. Can be either a single ID, or multiple comma-separated IDs.
project_id Filters the list by project. Can be either a single ID, or multiple comma-separated IDs.
service_id Filters the list by service. Can be either a single ID, or multiple comma-separated IDs.
note Search within the notes. To filter by multiple criteria connected with OR, set the parameter as note[] multiple times.
at The date of the entry.
today, yesterday, this_week, last_week, this_month, last_month, this_year, last_year or date formatted as YYYY-MM-DD
from,to The date span the time entry falls into – both attributes can be formatted like at.
billable Is the time entry billable or not?
true or false
locked Is the time entry locked or not?
true or false
tracking Is a timer running on the time entry?
true or false
sort What to sort results by. Can be either date, user, customer, project, service, note, minutes, or revenue.
Default: date
direction The direction of the sort. Can be either asc or desc.
Default: depends on sort: date, minutes, and revenue default to desc, all others to asc.
group_by What to group results by. Details
limit Limits the list to the given number of entries.
Default: indefinite
page Allows to access follow-up pages when combined with limit.
Default: 1

Response

Status: 200 OK
[
   {
      "time_entry": {...}
   },
   {
      "time_entry": {...}
   }
]
Status: 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<time-entries type="array">
   <time-entry>
      ...
   </time-entry>
   <time-entry>
      ...
   </time-entry>
</time_entries>

List all time entries for a specific date

Get all time entries of the authenticated user for the current date:

GET /daily.xml
GET /daily.json

This is simply a convenient alias for the longer form:

GET /time_entries.xml?user_id=current&at=today
GET /time_entries.json?user_id=current&at=today

Get all time entries of the authenticated user for February 7th, 2015:

GET /daily/2015/2/7.xml
GET /daily/2015/2/7.json

Which again is the same as:

GET /time_entries.xml?user_id=current&at=2015-02-07
GET /time_entries.json?user_id=current&at=2015-02-07

Group time entries

When accessing /time_entries, the returned results can be grouped using the parameter group_by. This parameter can contain the following values:

With the parameter group_by you are able to group the time entries. Allowed values are user, customer, project, service, day, week, month, and year.

Example

GET /time_entries.xml?group_by=user
GET /time_entries.json?group_by=user

Response

Status: 200 OK
[
   {
      "time_entry_group": {
         "minutes": 10733,
         "revenue": 91568.333333333,
         "user_id": 26144,
         "user_name": "Virgil Hamilton",
         "from": "2014-05-03",
         "to": "2014-09-23",
         "time_entries_params": {
            "user_id": 26144
         }
      }
   },
   {
      "time_entry_group": {
         "minutes": 57289,
         "revenue": 788439.3666668,
         "user_id": 246,
         "user_name": "Annie Butler",
         "from": "2013-04-19",
         "to": "2015-08-19",
         "time_entries_params": {
            "user_id": 246
         }
      }
   }
]
Status: 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<time-entry-groups type="array">
   <time-entry-group>
      <minutes type="integer">10733</minutes>
      <revenue type="float">91568.3333333334</revenue>
      <user-id type="integer">26144</user-id>
      <user-name>Virgil Hamilton</user-name>
      <from type="date">2014-05-03</from>
      <to type="date">2014-09-23</to>
      <time-entries-params>
         <user-id>26144</user-id>
      </time-entries-params>
   </time-entry-group>
   <time-entry-group>
      <minutes type="integer">57289</minutes>
      <revenue type="float">788439.36666681</revenue>
      <user-id type="integer">246</user-id>
      <user-name>Annie Butler</user-name>
      <from type="date">2013-04-19</from>
      <to type="date">2015-08-19</to>
      <time-entries-params>
         <user-id>246</user-id>
      </time-entries-params>
   </time-entry-group>
<time-entry-groups type="array">

Besides the accumulated minutes and revenue, the response contains the values shared by the whole group. When grouped by user, the response will contain the user_id and the user_name, for example. Furthermore, all parameters that can be used to list individual time entries will be listed under time-entries-params.

Several values can be combined: just separate them by comma. The order of the values determine how the results will be sorted.

For example, to get the last week of all users as a group:

GET /time_entries.xml?group_by=user,week&at=last_week
GET /time_entries.json?group_by=user,week&at=last_week

Or for all month of all projects of a specific customer:

GET /time_entries.xml?group_by=project,month&customer_id=123
GET /time_entries.json?group_by=project,month&customer_id=123

Get a single time entry

Get a single time entry by its id. The entry can belong to any user of the account, as long as the authenticated user is not a time tracker. 

GET /time_entries/:id.xml
GET /time_entries/:id.json

Response

Status: 200 OK
{
   "time_entry": {
      "id": 36159117,
      "minutes": 15,
      "date_at": "2015-10-16",
      "note": "Rework description of authentication process",
      "billable": true,
      "locked": false,
      "revenue": null,
      "hourly_rate": 0,
      "user_id": 211,
      "user_name": "Noah Scott",
      "project_id": 88309,
      "project_name": "API Docs",
      "customer_id": 3213,
      "customer_name": "King Inc.",
      "service_id": 12984,
      "service_name": "Writing",
      "created_at": "2015-10-16T12:39:00+02:00",
      "updated_at": "2015-10-16T12:39:00+02:00"
   }
}
Status: 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<time-entry>
   <id type="integer">36159117</id>
   <date-at type="date">2015-10-16</date-at>
   <minutes type="integer">15</minutes>
   <revenue type="float" nil="true"></revenue>
   <hourly-rate type="integer">0</hourly-rate>
   <billable type="boolean">true</billable>
   <note>Rework description of authentication process</note>
   <user-id type="integer">211</user-id>
   <user-name>Noah Scott</user-name>
   <project-id type="integer">88309</project-id>
   <project-name>API v2</project-name>
   <service-id type="integer">12984</service-id>
   <service-name>Writing</service-name>
   <customer-id type="integer">3213</customer-id>
   <customer-name>King Inc.</customer-name>
   <locked type="boolean">false</locked>
   <created-at type="datetime">2015-10-16T12:39:00+02:00</created-at>
   <updated-at type="datetime">2015-10-16T12:39:00+02:00</updated-at>
</time-entry>

If the timer is running on this exact time entry, some more information will be returned: since when the timer is ticking and how many minutes have been measured in total (measured time + existing minutes).

Status: 200 OK
{
   "time_entry": {
      ...
      "tracking": {
         "since": "2015-10-16T12:44:17+02:00",
         "minutes": 12
      }
   }
}
Status: 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<time-entry>
   ...
   <tracking>
      <since type="datetime">2015-01-22T14:58:13+01:00</since>
      <minutes type="integer">12</minutes>
   </tracking>
</time-entry>

Create a time entry

Create a new time entry. All attributes are optional. 

POST /time_entries.xml
POST /time_entries.json

Attributes

date_at Date of the time entry formatted as YYYY-MM-DD.
Default: today
minutes Default: 0
note Default: "" (empty string)
user_id Can only be set by an administrator.
Default: ID of the authenticated user
project_id Default: null (without a project)
service_id Default: null (without a service)
locked Can only be set by an administrator. A locked entry can not be modified or deleted. Details
false (Default) or true

Request

Content-Type: application/json
{
   "time_entry": {
      "date_at": "2015-9-15",
      "minutes": 185,
      "service_id": 243
   }
}
Content-Type: application/xml
<time-entry>
   <date-at>2015-9-12</date-at>
   <minutes>185</minutes>
   <service-id>243</service-id>
</time-entry>

Response

Status: 201 Created
Location: https://demo.mite.de/time_entries/52324.json
{
   "time_entry": {
      "id": 52324,
      "minutes": 185,
      "date_at": "2015-9-12",
      "note": "",
      "billable": true,
      "locked": false,
      "revenue": null,
      "hourly_rate": 0,
      "user_id": 211,
      "user_name": "Noah Scott",
      "project_id": null,
      "service_id": 243,
      "service_name": "Documentation",
      "created_at": "2015-09-13T18:54:45+02:00",
      "updated_at": "2015-09-13T18:54:45+02:00"
   }
}
Status: 201 Created
Location: https://demo.mite.de/time_entries/52324.xml
<?xml version="1.0" encoding="UTF-8"?>
<time-entry>
   <id type="integer">52324</id>
   <date-at type="date">2015-9-12</date-at>
   <minutes type="integer">185</minutes>
   <revenue type="float" nil="true"></revenue>
   <hourly-rate type="integer">0</hourly-rate>
   <billable type="boolean">true</billable>
   <note></note>
   <user-id type="integer">211</user-id>
   <user-name>Noah Scott</user-name>
   <project-id type="integer" nil="true"/>
   <service-id type="integer">243</service-id>
   <service-name>Documentation</service-name>
   <locked type="boolean">false</locked>
   <created-at type="datetime">2015-09-13T18:54:45+02:00</created-at>
   <updated-at type="datetime">2015-09-13T18:54:45+02:00</updated-at>
</time-entry>

Edit a time entry

Update a time entry with the given attributes. Only administrators can update entries of other users; all others only their own. 

PATCH /time_entries/:id.xml
PATCH /time_entries/:id.json
Content-Type: application/json
{
   "time_entry": {
      "minutes": 120,
      "service_id": 3124
   }
}
Content-Type: application/xml
<time-entry>
   <minutes>120</minutes>
   <service-id>3124</service-id>
</time-entry>

Response

Status: 200 OK
{empty}

Delete a time entry

Delete a time entry.

DELETE /time_entries/:id.xml
DELETE /time_entries/:id.json

Response

Status: 200 OK
{empty}

Such as when updating a entry, only an administrator can delete entries not owned by himself. If for example a coworker tries to delete a time entry of another user, our API will return a 404 Not Found error.

Locked time entries

When an administrator sets the attribute locked of a time entry to true, the entry can not be modified or deleted by any user from then on. If you try to modify it, you get a error:

Status: 423 Locked
{
  "error": "Time entry cannot be updated: it is locked."
}
Status: 423 Locked
<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Time entry cannot be updated: it is locked.</error>
</errors>}

And when you try to delete a locked entry:

Status: 423 Locked
{
  "error": "Time entry cannot be deleted: it is locked."
}
Status: 423 Locked
<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Time entry cannot be deleted: it is locked.</error>
</errors>}

Administrators can use the attribute force to bypass this restriction, for example to set locked back to false:

PATCH /time_entries/:id.xml
PATCH /time_entries/:id.json
Content-Type: application/json
{
   "time_entry": {
      "force": true,
      "locked": false
   }
}
Content-Type: application/xml
<time-entry>
   <force>true</force>
   <locked>false</locked>
</time-entry>

Response

Status: 200 OK
{empty}

Or to delete the entry:

DELETE /time_entries/:id.xml
DELETE /time_entries/:id.json
Content-Type: application/json
{
   "time_entry": {
      "force": true
   }
}
Content-Type: application/xml
<time-entry>
   <force>true</force>
</time-entry>

Response

Status: 200 OK
{empty}