API: Time entries

Actions

Link Description Condition
updateImmediately Directly perform edits on this time entry Permission: ‘edit time entries’ or ‘edit own time entries’ if the time entry belongs to the user, or ‘log own time’ if the time entry is ongoing
update Form endpoint that aids in preparing and performing edits on a TimeEntry Permission: ‘edit time entries’ or ‘edit own time entries’ if the time entry belongs to the user, or ‘log own time’ if the time entry is ongoing
delete Delete this time entry Permission: ‘edit time entries’ or ‘edit own time entries’ if the time entry belongs to the user, or ‘log own time’ if the time entry is ongoing

Linked Properties

Link Description Type Constraints Supported operations Condition
self This time entry TimeEntry not null READ
project The project the time entry is bundled in. The project might be different from the work package’s project once the workPackage is moved. Project not null READ / WRITE
workPackage The work package the time entry is created on WorkPackage READ / WRITE
user The user the time entry tracks expenditures for User not null READ / WRITE Permission: Log time for other users permission
activity The time entry activity the time entry is categorized as TimeEntriesActivity READ / WRITE

Depending on custom fields defined for time entries, additional links might exist.

Time entries are either linked to a work package or to a project. If they are linked to a project, the work package reference is empty. If they are linked to a work package, the project reference is filled up automatically to point to the work package’s project.

Local Properties

Property Description Type Constraints Supported operations Condition
id Time entries’ id Integer x > 0 READ
comment A text provided by the user detailing the time entry String READ / WRITE
spentOn The date the expenditure is booked for Date READ / WRITE
hours The time quantifying the expenditure Time READ / WRITE
ongoing Whether the time entry is actively tracking Boolean READ / WRITE
createdAt The time the time entry was created DateTime READ
updatedAt The time the time entry was last updated DateTime READ

Depending on custom fields defined for time entries, additional properties might exist.

Methods

List time entries

Lists time entries. The time entries returned depend on the filters provided and also on the permission of the requesting user.

offset
integer

optional query

Page number inside the requested collection.

Default:
1

Example:
25

pageSize
integer

optional query

Number of elements to display per page.

Example:
25

sortBy
string

optional query

JSON specifying sort criteria. Accepts the same format as returned by the queries endpoint. Currently supported sorts are:

  • id: Sort by primary key

  • hours: Sort by logged hours

  • spent_on: Sort by spent on date

  • created_at: Sort by time entry creation datetime

  • updated_at: Sort by the time the time entry was updated last

Default:
["spent_on", "asc"]

Example:
[["spent_on", "asc"]]

filters
string

optional query

JSON specifying filter conditions. Accepts the same format as returned by the queries endpoint. Currently supported filters are:

  • work_package: Filter time entries by work package

  • project: Filter time entries by project

  • user: Filter time entries by users

  • ongoing: Filter for your ongoing timers

  • spent_on: Filter time entries by spent on date

  • created_at: Filter time entries by creation datetime

  • updated_at: Filter time entries by the last time they where updated

  • activity: Filter time entries by time entry activity

Example:
[{ "work_package": { "operator": "=", "values": ["1", "2"] } }, { "project": { "operator": "=", "values": ["1"] } }]

200

OK

{
  "_type": "Collection",
  "total": 39,
  "count": 2,
  "pageSize": 2,
  "offset": 1,
  "_embedded": {
    "elements": [
      {
        "_type": "TimeEntry",
        "id": 5,
        "comment": {
          "format": "plain",
          "raw": "Some comment",
          "html": "<p>Some comment</p>"
        },
        "spentOn": "2015-03-20",
        "hours": "PT5H",
        "startTime": "2015-03-20T10:00:00.000Z",
        "endTime": "2015-03-20T15:00:00.000Z",
        "createdAt": "2015-03-20T12:56:56.803Z",
        "updatedAt": "2015-03-20T12:56:56.803Z",
        "_links": {
          "self": {
            "href": "/api/v3/time_entries/1"
          },
          "updateImmediately": {
            "href": "/api/v3/time_entries/1",
            "method": "patch"
          },
          "delete": {
            "href": "/api/v3/time_entries/1",
            "method": "delete"
          },
          "project": {
            "href": "/api/v3/projects/1",
            "title": "Some project"
          },
          "workPackage": {
            "href": "/api/v3/work_packages/1",
            "title": "Some work package"
          },
          "user": {
            "href": "/api/v3/users/2",
            "title": "Some user"
          },
          "activity": {
            "href": "/api/v3/time_entries/activities/18",
            "title": "Some time entry activity"
          }
        }
      },
      {
        "_type": "TimeEntry",
        "id": 10,
        "comment": {
          "format": "plain",
          "raw": "Another comment",
          "html": "<p>Another comment</p>"
        },
        "spentOn": "2015-03-21",
        "hours": "PT7H",
        "startTime": "2015-03-20T15:00:00.000Z",
        "endTime": "2015-03-20T22:00:00.000Z",
        "createdAt": "2015-03-20T12:56:56.569Z",
        "updatedAt": "2015-03-20T12:56:56.371Z",
        "_links": {
          "self": {
            "href": "/api/v3/time_entries/2"
          },
          "project": {
            "href": "/api/v3/projects/42",
            "title": "Some other project"
          },
          "workPackage": {
            "href": "/api/v3/work_packages/541",
            "title": "Some other work package"
          },
          "user": {
            "href": "/api/v3/users/6",
            "title": "Some other project"
          },
          "activity": {
            "href": "/api/v3/time_entries/activities/14",
            "title": "some other time entry activity"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/time_entries?offset=1&pageSize=2"
    },
    "jumpTo": {
      "href": "/api/v3/time_entries?offset=%7Boffset%7D&pageSize=2",
      "templated": true
    },
    "changeSize": {
      "href": "/api/v3/time_entries?offset=1&pageSize=%7Bsize%7D",
      "templated": true
    },
    "nextByOffset": {
      "href": "/api/v3/time_entries?offset=2&pageSize=2"
    },
    "createTimeEntry": {
      "href": "/api/v3/time_entries/form",
      "method": "post"
    },
    "createTimeEntryImmediately": {
      "href": "/api/v3/time_entries",
      "method": "post"
    }
  }
}
TimeEntryCollectionModel
{
  "type": "object",
  "allOf": [
    {
      "$ref": "#/components/schemas/CollectionModel"
    },
    {
      "type": "object",
      "required": [
        "_links",
        "_embedded"
      ],
      "properties": {
        "_links": {
          "type": "object",
          "required": [
            "self"
          ],
          "properties": {
            "self": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "This time entry collection\n\n**Resource**: TimeEntryCollectionModel"
                }
              ]
            }
          }
        },
        "_embedded": {
          "type": "object",
          "required": [
            "elements"
          ],
          "properties": {
            "elements": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/TimeEntryModel"
              }
            }
          }
        }
      }
    }
  ],
  "examples": [
    {
      "_type": "Collection",
      "total": 39,
      "count": 2,
      "pageSize": 2,
      "offset": 1,
      "_embedded": {
        "elements": [
          {
            "_type": "TimeEntry",
            "id": 5,
            "comment": {
              "format": "plain",
              "raw": "Some comment",
              "html": "<p>Some comment</p>"
            },
            "spentOn": "2015-03-20",
            "hours": "PT5H",
            "startTime": "2015-03-20T10:00:00.000Z",
            "endTime": "2015-03-20T15:00:00.000Z",
            "createdAt": "2015-03-20T12:56:56.803Z",
            "updatedAt": "2015-03-20T12:56:56.803Z",
            "_links": {
              "self": {
                "href": "/api/v3/time_entries/1"
              },
              "updateImmediately": {
                "href": "/api/v3/time_entries/1",
                "method": "patch"
              },
              "delete": {
                "href": "/api/v3/time_entries/1",
                "method": "delete"
              },
              "project": {
                "href": "/api/v3/projects/1",
                "title": "Some project"
              },
              "workPackage": {
                "href": "/api/v3/work_packages/1",
                "title": "Some work package"
              },
              "user": {
                "href": "/api/v3/users/2",
                "title": "Some user"
              },
              "activity": {
                "href": "/api/v3/time_entries/activities/18",
                "title": "Some time entry activity"
              }
            }
          },
          {
            "_type": "TimeEntry",
            "id": 10,
            "comment": {
              "format": "plain",
              "raw": "Another comment",
              "html": "<p>Another comment</p>"
            },
            "spentOn": "2015-03-21",
            "hours": "PT7H",
            "startTime": "2015-03-20T15:00:00.000Z",
            "endTime": "2015-03-20T22:00:00.000Z",
            "createdAt": "2015-03-20T12:56:56.569Z",
            "updatedAt": "2015-03-20T12:56:56.371Z",
            "_links": {
              "self": {
                "href": "/api/v3/time_entries/2"
              },
              "project": {
                "href": "/api/v3/projects/42",
                "title": "Some other project"
              },
              "workPackage": {
                "href": "/api/v3/work_packages/541",
                "title": "Some other work package"
              },
              "user": {
                "href": "/api/v3/users/6",
                "title": "Some other project"
              },
              "activity": {
                "href": "/api/v3/time_entries/activities/14",
                "title": "some other time entry activity"
              }
            }
          }
        ]
      },
      "_links": {
        "self": {
          "href": "/api/v3/time_entries?offset=1&pageSize=2"
        },
        "jumpTo": {
          "href": "/api/v3/time_entries?offset=%7Boffset%7D&pageSize=2",
          "templated": true
        },
        "changeSize": {
          "href": "/api/v3/time_entries?offset=1&pageSize=%7Bsize%7D",
          "templated": true
        },
        "nextByOffset": {
          "href": "/api/v3/time_entries?offset=2&pageSize=2"
        },
        "createTimeEntry": {
          "href": "/api/v3/time_entries/form",
          "method": "post"
        },
        "createTimeEntryImmediately": {
          "href": "/api/v3/time_entries",
          "method": "post"
        }
      }
    }
  ]
}

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

403

Returned if the client is not logged in and login is required.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to view this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Create time entry

Creates a new time entry applying the attributes provided in the body. Please note that while there is a fixed set of attributes, custom fields can extend a time entries’ attributes and are accepted by the endpoint.

No parameters 
{
  "id": {
    "type": "integer",
    "description": "The id of the time entry",
    "minimum": 1
  },
  "comment": {
    "type": "string",
    "description": "A comment to the time entry"
  },
  "spentOn": {
    "type": "string",
    "format": "date",
    "description": "The date the expenditure is booked for"
  },
  "hours": {
    "type": "string",
    "format": "duration",
    "description": "The time quantifying the expenditure"
  },
  "ongoing": {
    "type": "boolean",
    "description": "Whether the time entry is actively tracking time"
  },
  "createdAt": {
    "type": "string",
    "format": "date-time",
    "description": "The time the time entry was created"
  },
  "startTime": {
    "type": [
      "string",
      "null"
    ],
    "format": "date-time",
    "description": "The time the time entry was started, or null if the time entry does not have a start time.\n\nThe time is returned as UTC time, if presented to the user it should be converted to the user's timezone.\n\nThis field is only available if the global `allow_tracking_start_and_end_times` setting is enabled."
  },
  "endTime": {
    "type": [
      "string",
      "null"
    ],
    "format": "date-time",
    "description": "The time the time entry was ended, or null if the time entry does not have a start time.\n\nThe time is returned as UTC time, if presented to the user it should be converted to the user's timezone.\n\nThis field is only available if the global `allow_tracking_start_and_end_times` setting is enabled."
  },
  "updatedAt": {
    "type": "string",
    "format": "date-time",
    "description": "The time the time entry was last updated"
  },
  "_links": {
    "type": "object",
    "required": [
      "self",
      "project",
      "user",
      "activity"
    ],
    "properties": {
      "self": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Link"
          },
          {
            "description": "This time entry\n\n**Resource**: TimeEntry"
          }
        ]
      },
      "updateImmediately": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Link"
          },
          {
            "description": "Directly perform edits on this time entry\n\n# Conditions\n\n**Permission**: 'edit time entries' or 'edit own time entries' if the time entry belongs to the user"
          }
        ]
      },
      "update": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Link"
          },
          {
            "description": "Form endpoint that aids in preparing and performing edits on a TimeEntry\n\n# Conditions\n\n**Permission**: 'edit time entries' or 'edit own time entries' if the time entry belongs to the user"
          }
        ]
      },
      "delete": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Link"
          },
          {
            "description": "Delete this time entry\n\n# Conditions\n\n**Permission**: 'edit time entries' or 'edit own time entries' if the time entry belongs to the user"
          }
        ]
      },
      "schema": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Link"
          },
          {
            "description": "The time entry schema\n\n**Resource**: Schema"
          }
        ]
      },
      "project": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Link"
          },
          {
            "description": "The project the time entry is bundled in. The project might be different from the work package's project once the workPackage is moved.\n\n**Resource**: Project"
          }
        ]
      },
      "workPackage": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Link"
          },
          {
            "description": "The work package the time entry is created on\n\n**Resource**: WorkPackage"
          }
        ]
      },
      "user": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Link"
          },
          {
            "description": "The user the time entry tracks expenditures for\n\n**Resource**: User"
          }
        ]
      },
      "activity": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Link"
          },
          {
            "description": "The time entry activity the time entry is categorized as\n\n**Resource**: TimeEntriesActivity"
          }
        ]
      }
    }
  }
}

201

Created

{
  "_type": "TimeEntry",
  "id": 42,
  "comment": {
    "format": "plain",
    "raw": "The force shall set me free.",
    "html": "<p>The force shall set me free.</p>"
  },
  "spentOn": "2023-01-11",
  "hours": "PT4H",
  "startTime": "2023-01-11T09:58:00.000Z",
  "endTime": "2023-01-11T13:58:00.000Z",
  "createdAt": "2023-01-11T13:58:24.927Z",
  "updatedAt": "2023-01-11T13:58:24.927Z",
  "_links": {
    "self": {
      "href": "/api/v3/time_entries/42"
    },
    "updateImmediately": {
      "href": "/api/v3/time_entries/42",
      "method": "patch"
    },
    "update": {
      "href": "/api/v3/time_entries/42/form",
      "method": "post"
    },
    "delete": {
      "href": "/api/v3/time_entries/42",
      "method": "delete"
    },
    "schema": {
      "href": "/api/v3/time_entries/schema"
    },
    "project": {
      "href": "/api/v3/projects/11",
      "title": "DeathStarV2"
    },
    "workPackage": {
      "href": "/api/v3/work_packages/77",
      "title": "Build new hangar"
    },
    "user": {
      "href": "/api/v3/users/3",
      "title": "Darth Vader"
    },
    "activity": {
      "href": "/api/v3/time_entries/activities/1",
      "title": "Management"
    }
  }
}
TimeEntryModel
{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "The id of the time entry",
      "minimum": 1
    },
    "comment": {
      "type": "string",
      "description": "A comment to the time entry"
    },
    "spentOn": {
      "type": "string",
      "format": "date",
      "description": "The date the expenditure is booked for"
    },
    "hours": {
      "type": "string",
      "format": "duration",
      "description": "The time quantifying the expenditure"
    },
    "ongoing": {
      "type": "boolean",
      "description": "Whether the time entry is actively tracking time"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the time entry was created"
    },
    "startTime": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "The time the time entry was started, or null if the time entry does not have a start time.\n\nThe time is returned as UTC time, if presented to the user it should be converted to the user's timezone.\n\nThis field is only available if the global `allow_tracking_start_and_end_times` setting is enabled."
    },
    "endTime": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "The time the time entry was ended, or null if the time entry does not have a start time.\n\nThe time is returned as UTC time, if presented to the user it should be converted to the user's timezone.\n\nThis field is only available if the global `allow_tracking_start_and_end_times` setting is enabled."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the time entry was last updated"
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "project",
        "user",
        "activity"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This time entry\n\n**Resource**: TimeEntry"
            }
          ]
        },
        "updateImmediately": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Directly perform edits on this time entry\n\n# Conditions\n\n**Permission**: 'edit time entries' or 'edit own time entries' if the time entry belongs to the user"
            }
          ]
        },
        "update": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Form endpoint that aids in preparing and performing edits on a TimeEntry\n\n# Conditions\n\n**Permission**: 'edit time entries' or 'edit own time entries' if the time entry belongs to the user"
            }
          ]
        },
        "delete": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Delete this time entry\n\n# Conditions\n\n**Permission**: 'edit time entries' or 'edit own time entries' if the time entry belongs to the user"
            }
          ]
        },
        "schema": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The time entry schema\n\n**Resource**: Schema"
            }
          ]
        },
        "project": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The project the time entry is bundled in. The project might be different from the work package's project once the workPackage is moved.\n\n**Resource**: Project"
            }
          ]
        },
        "workPackage": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The work package the time entry is created on\n\n**Resource**: WorkPackage"
            }
          ]
        },
        "user": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The user the time entry tracks expenditures for\n\n**Resource**: User"
            }
          ]
        },
        "activity": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The time entry activity the time entry is categorized as\n\n**Resource**: TimeEntriesActivity"
            }
          ]
        }
      }
    }
  },
  "examples": [
    {
      "_type": "TimeEntry",
      "id": 42,
      "comment": {
        "format": "plain",
        "raw": "The force shall set me free.",
        "html": "<p>The force shall set me free.</p>"
      },
      "spentOn": "2023-01-11",
      "hours": "PT4H",
      "startTime": "2023-01-11T09:58:00.000Z",
      "endTime": "2023-01-11T13:58:00.000Z",
      "createdAt": "2023-01-11T13:58:24.927Z",
      "updatedAt": "2023-01-11T13:58:24.927Z",
      "_links": {
        "self": {
          "href": "/api/v3/time_entries/42"
        },
        "updateImmediately": {
          "href": "/api/v3/time_entries/42",
          "method": "patch"
        },
        "update": {
          "href": "/api/v3/time_entries/42/form",
          "method": "post"
        },
        "delete": {
          "href": "/api/v3/time_entries/42",
          "method": "delete"
        },
        "schema": {
          "href": "/api/v3/time_entries/schema"
        },
        "project": {
          "href": "/api/v3/projects/11",
          "title": "DeathStarV2"
        },
        "workPackage": {
          "href": "/api/v3/work_packages/77",
          "title": "Build new hangar"
        },
        "user": {
          "href": "/api/v3/users/3",
          "title": "Darth Vader"
        },
        "activity": {
          "href": "/api/v3/time_entries/activities/1",
          "title": "Management"
        }
      }
    }
  ]
}

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: Log time

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

406

Occurs when the client did not send a Content-Type header

"Missing content-type header"

{
  "type": "string"
}

415

Occurs when the client sends an unsupported Content-Type header.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

422

Returned if:

  • a constraint for a property was violated (PropertyConstraintViolation)
{
  "_embedded": {
    "details": {
      "attribute": "workPackage"
    }
  },
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "Work package is invalid."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Get time entry

Retrieves a single time entry identified by the given id.

id
integer

required path

time entry id

Example:
1

200

OK

{
  "_type": "TimeEntry",
  "id": 42,
  "comment": {
    "format": "plain",
    "raw": "The force shall set me free.",
    "html": "<p>The force shall set me free.</p>"
  },
  "spentOn": "2023-01-11",
  "hours": "PT4H",
  "startTime": "2023-01-11T09:58:00.000Z",
  "endTime": "2023-01-11T13:58:00.000Z",
  "createdAt": "2023-01-11T13:58:24.927Z",
  "updatedAt": "2023-01-11T13:58:24.927Z",
  "_links": {
    "self": {
      "href": "/api/v3/time_entries/42"
    },
    "updateImmediately": {
      "href": "/api/v3/time_entries/42",
      "method": "patch"
    },
    "update": {
      "href": "/api/v3/time_entries/42/form",
      "method": "post"
    },
    "delete": {
      "href": "/api/v3/time_entries/42",
      "method": "delete"
    },
    "schema": {
      "href": "/api/v3/time_entries/schema"
    },
    "project": {
      "href": "/api/v3/projects/11",
      "title": "DeathStarV2"
    },
    "workPackage": {
      "href": "/api/v3/work_packages/77",
      "title": "Build new hangar"
    },
    "user": {
      "href": "/api/v3/users/3",
      "title": "Darth Vader"
    },
    "activity": {
      "href": "/api/v3/time_entries/activities/1",
      "title": "Management"
    }
  }
}
TimeEntryModel
{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "The id of the time entry",
      "minimum": 1
    },
    "comment": {
      "type": "string",
      "description": "A comment to the time entry"
    },
    "spentOn": {
      "type": "string",
      "format": "date",
      "description": "The date the expenditure is booked for"
    },
    "hours": {
      "type": "string",
      "format": "duration",
      "description": "The time quantifying the expenditure"
    },
    "ongoing": {
      "type": "boolean",
      "description": "Whether the time entry is actively tracking time"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the time entry was created"
    },
    "startTime": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "The time the time entry was started, or null if the time entry does not have a start time.\n\nThe time is returned as UTC time, if presented to the user it should be converted to the user's timezone.\n\nThis field is only available if the global `allow_tracking_start_and_end_times` setting is enabled."
    },
    "endTime": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "The time the time entry was ended, or null if the time entry does not have a start time.\n\nThe time is returned as UTC time, if presented to the user it should be converted to the user's timezone.\n\nThis field is only available if the global `allow_tracking_start_and_end_times` setting is enabled."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the time entry was last updated"
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "project",
        "user",
        "activity"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This time entry\n\n**Resource**: TimeEntry"
            }
          ]
        },
        "updateImmediately": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Directly perform edits on this time entry\n\n# Conditions\n\n**Permission**: 'edit time entries' or 'edit own time entries' if the time entry belongs to the user"
            }
          ]
        },
        "update": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Form endpoint that aids in preparing and performing edits on a TimeEntry\n\n# Conditions\n\n**Permission**: 'edit time entries' or 'edit own time entries' if the time entry belongs to the user"
            }
          ]
        },
        "delete": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Delete this time entry\n\n# Conditions\n\n**Permission**: 'edit time entries' or 'edit own time entries' if the time entry belongs to the user"
            }
          ]
        },
        "schema": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The time entry schema\n\n**Resource**: Schema"
            }
          ]
        },
        "project": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The project the time entry is bundled in. The project might be different from the work package's project once the workPackage is moved.\n\n**Resource**: Project"
            }
          ]
        },
        "workPackage": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The work package the time entry is created on\n\n**Resource**: WorkPackage"
            }
          ]
        },
        "user": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The user the time entry tracks expenditures for\n\n**Resource**: User"
            }
          ]
        },
        "activity": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The time entry activity the time entry is categorized as\n\n**Resource**: TimeEntriesActivity"
            }
          ]
        }
      }
    }
  },
  "examples": [
    {
      "_type": "TimeEntry",
      "id": 42,
      "comment": {
        "format": "plain",
        "raw": "The force shall set me free.",
        "html": "<p>The force shall set me free.</p>"
      },
      "spentOn": "2023-01-11",
      "hours": "PT4H",
      "startTime": "2023-01-11T09:58:00.000Z",
      "endTime": "2023-01-11T13:58:00.000Z",
      "createdAt": "2023-01-11T13:58:24.927Z",
      "updatedAt": "2023-01-11T13:58:24.927Z",
      "_links": {
        "self": {
          "href": "/api/v3/time_entries/42"
        },
        "updateImmediately": {
          "href": "/api/v3/time_entries/42",
          "method": "patch"
        },
        "update": {
          "href": "/api/v3/time_entries/42/form",
          "method": "post"
        },
        "delete": {
          "href": "/api/v3/time_entries/42",
          "method": "delete"
        },
        "schema": {
          "href": "/api/v3/time_entries/schema"
        },
        "project": {
          "href": "/api/v3/projects/11",
          "title": "DeathStarV2"
        },
        "workPackage": {
          "href": "/api/v3/work_packages/77",
          "title": "Build new hangar"
        },
        "user": {
          "href": "/api/v3/users/3",
          "title": "Darth Vader"
        },
        "activity": {
          "href": "/api/v3/time_entries/activities/1",
          "title": "Management"
        }
      }
    }
  ]
}

404

Returned if the time entry does not exist or if the user does not have permission to view them.

Required permission

  • view time entries in the project the time entry is assigned to or
  • view own time entries for time entries belonging to the user
{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Delete time entry

Permanently deletes the specified time entry.

id
integer

required path

Time entry id

Example:
1

204

Returned if the time entry was deleted successfully.

403

Returned if the client does not have sufficient permissions

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

404

Returned if the time entry does not exist or if the user does not have sufficient permissions to see the time entry.

Required permission view time entries in the project the time entry is assigned to or view own time entries for time entries belonging to the user

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

406

Occurs when the client did not send a Content-Type header

"Missing content-type header"

{
  "type": "string"
}

415

Occurs when the client sends an unsupported Content-Type header.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}