Log time
log_timeLog work hours against a work package or project, validated against OpenProject rules for allowed activities and permissions. Returns the created time entry.
Instructions
Book time against a work package or a project.
Use it when the user says "log 2 hours on #1234" or "book half a day to project X". The call is validated through OpenProject's own form endpoint first, so an activity this project does not allow, a missing permission or a closed cost-reporting period comes back as a typed error listing what would be accepted — nothing half-written is left behind.
Returns the created entry: {id, hours, spent_on, comment, user, activity, work_package, project, created_at, updated_at, lock_version}. hours comes back as a float.
Pitfalls. This is not idempotent — calling it twice books the time
twice, so never blind-retry after a timeout; list the day's entries
first. The time is always booked for the token owner; you cannot log
time on someone else's behalf through this tool. Logging time does not
change the work package's status, estimate or progress — those are
separate fields, and on instances that derive progress from work the
percentage is read-only anyway. The work package's spent_hours
reflects the new entry on the next read.
Cross-references: the activities and ids this project accepts come from
get_project_metadata(project_id=...); review what is already booked
with list_time_entries; fix a mistake with update_time_entry or
delete_time_entry.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| hours | Yes | Duration in hours as a float: 1.5 is one and a half hours, 0.25 is fifteen minutes. Must be positive; OpenProject stores it to the minute. | |
| comment | No | What the time was spent on. Short and factual: it shows up in cost reports next to the hours. | |
| activity | No | Activity name ('Development') or numeric id. Omit to take the instance default from the form. Names are resolved against this project's allowed activities; an unknown name fails with the valid ones listed. | |
| spent_on | Yes | The date the work was done, ISO YYYY-MM-DD. Required and never inferred — 'today' on the server may not be today for the user. | |
| project_id | No | Project to book the time on when the work belongs to no single ticket (numeric id or identifier). Required when work_package_id is omitted. | |
| work_package_id | No | Work package to book the time on. Ids come from search_work_packages or list_work_packages. Either this or project_id is required; passing both books on the work package inside that project. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Time entry id. Feed it to update_time_entry or delete_time_entry. | |
| user | No | User the time is booked for. | |
| hours | No | Logged duration in hours as a float (1.5 = one and a half hours), converted from OpenProject's ISO 8601 duration. | |
| comment | No | Free-text comment as entered (raw); html is dropped. | |
| project | No | Project the entry belongs to. | |
| activity | No | Time-entry activity (Development, Management, …); instance-defined. | |
| spent_on | No | The date the work was done, ISO YYYY-MM-DD. | |
| created_at | No | ISO 8601 UTC timestamp. | |
| updated_at | No | ISO 8601 UTC timestamp. | |
| lock_version | No | Optimistic-locking version, when this instance reports one for time entries; null means the resource is updated without a lock version. | |
| work_package | No | Work package the time is booked on; null for project-level entries. |