Time Entry
A tracked interval of work on a task.
Whose entries you see depends on your role. By default list, get and search return only your own entries. If your role holds viewTimeReports, list and get return every entry in your team, and memberId narrows that to one person — this is how a team-wide time report is built.
Note for integrations: breadth follows the ROLE, not the token. A token granted time-entry read by someone holding viewTimeReports can read that whole team, not only the person who granted it.
search is the exception: it stays scoped to your own entries whatever your role, so it under-reports a team. Use list for reporting.
Start a timer with POST /time-entries/start, which stops your other running entries first. Creating an entry without end makes a running entry without stopping the current one. PATCH end to stop a running entry; a stopped entry cannot be reopened (PATCH end: null is refused). taskId and projectId are set once: an entry cannot be moved to another task or project afterwards.
Running timers: end[null]=true lists entries that are still running; end[notNull]=true lists finished ones.
List Time Entries
List timeEntries. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 7 fields. Ordered by start unless you pass sort. Returns your own entries by default. With viewTimeReports on your role it returns every entry in your team instead; filter memberId for one person. This is the endpoint to build a team time report from — search stays scoped to your own entries regardless of role.
Required scope: time-entries:read
query Parameters
sortField to sort by. Prefix with - for descending (-createdAt); a createdAt:desc / createdAt:asc suffix works too, but never both markers at once. Default: start.
cursorOpaque cursor for the next page (the envelope nextCursor).
limitItems per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow nextCursor instead of assuming one page held everything.
includeTotalWhen true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination.
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
manual[eq]Filter where manual equals.
start[gt]Filter where start is greater than.
start[gte]Filter where start is greater than or equal to.
start[lt]Filter where start is less than.
start[lte]Filter where start is less than or equal to.
end[null]Filter where end is null (pass true).
end[notNull]Filter where end is not null (pass true).
createdAt[gt]Filter where createdAt is greater than.
createdAt[gte]Filter where createdAt is greater than or equal to.
createdAt[lt]Filter where createdAt is less than.
createdAt[lte]Filter where createdAt is less than or equal to.
projectId[eq]Filter where projectId equals.
projectId[in]Filter where projectId is one of (comma-separated list).
taskId[eq]Filter where taskId equals.
taskId[in]Filter where taskId is one of (comma-separated list).
memberId[eq]Filter where memberId equals.
memberId[in]Filter where memberId is one of (comma-separated list).
List Time Entries › Responses
OK
The page of results.
totalTotal rows matching the query (across pages).
limithasMorenextCursorOpaque cursor for the next page; null on the last page.
Create Time Entry
Create a Time Entry. Server-assigned fields are ignored if sent.
Required scope: time-entries:write
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Create Time Entry › Request Body
startWhen the tracked interval began (ISO 8601).
taskIdThe task this time is tracked against. Set once when the entry is created: an entry cannot be moved to another task afterwards. Null if that task has since been deleted — the entry is kept, and taskNiceId and taskName then say which task it was.
descriptionFree-text note about what the time was spent on. This is the field GET /time-entries/search matches against.
endWhen the tracked interval ended (ISO 8601); null while the entry is running. Start a timer with POST /time-entries/start. Creating an entry without end (or with null) makes a running entry without stopping your current one. PATCH end to stop a running entry; a stopped entry cannot be reopened, so PATCH with end: null is refused.
projectIdThe project this time is booked against. Set once when the entry is created: an entry cannot be moved to another project afterwards.
Create Time Entry › Responses
Created
idUnique identifier for this resource.
createdAtCreation timestamp.
startWhen the tracked interval began (ISO 8601).
manualTrue for entries created through this API; false for entries captured by the timer in the Nifty app. Server-set.
memberIdThe team member this time is tracked for. Set by the server from whoever is calling — you cannot log time on someone else's behalf.
updatedAtLast update timestamp.
descriptionFree-text note about what the time was spent on. This is the field GET /time-entries/search matches against.
endWhen the tracked interval ended (ISO 8601); null while the entry is running. Start a timer with POST /time-entries/start. Creating an entry without end (or with null) makes a running entry without stopping your current one. PATCH end to stop a running entry; a stopped entry cannot be reopened, so PATCH with end: null is refused.
projectIdThe project this time is booked against. Set once when the entry is created: an entry cannot be moved to another project afterwards.
taskIdThe task this time is tracked against. Set once when the entry is created: an entry cannot be moved to another task afterwards. Null if that task has since been deleted — the entry is kept, and taskNiceId and taskName then say which task it was.
taskNiceIdSet only when the task has been deleted: a ready-to-display reference to it, such as PROJ-5 · deleted. Display it as-is. Do not parse it and do not resolve it to a live task — task numbers are reused, so the same number may now belong to a different task.
taskNameSet only when the task has been deleted: the name it had at that moment. A point-in-time copy, not kept in sync with anything.
The related Team Member, present only when you pass ?expand=member.
Get Time Entry
Retrieve a single Time Entry by id. By default only your own entries are reachable here. With viewTimeReports on your role, so is any entry in your team — get widens exactly as list does, so a row you can see in list is a row you can fetch by id. Without that permission another member's entry is 404, not 403.
Required scope: time-entries:read
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Time Entry.
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Get Time Entry › Responses
OK
idUnique identifier for this resource.
createdAtCreation timestamp.
startWhen the tracked interval began (ISO 8601).
manualTrue for entries created through this API; false for entries captured by the timer in the Nifty app. Server-set.
memberIdThe team member this time is tracked for. Set by the server from whoever is calling — you cannot log time on someone else's behalf.
updatedAtLast update timestamp.
descriptionFree-text note about what the time was spent on. This is the field GET /time-entries/search matches against.
endWhen the tracked interval ended (ISO 8601); null while the entry is running. Start a timer with POST /time-entries/start. Creating an entry without end (or with null) makes a running entry without stopping your current one. PATCH end to stop a running entry; a stopped entry cannot be reopened, so PATCH with end: null is refused.
projectIdThe project this time is booked against. Set once when the entry is created: an entry cannot be moved to another project afterwards.
taskIdThe task this time is tracked against. Set once when the entry is created: an entry cannot be moved to another task afterwards. Null if that task has since been deleted — the entry is kept, and taskNiceId and taskName then say which task it was.
taskNiceIdSet only when the task has been deleted: a ready-to-display reference to it, such as PROJ-5 · deleted. Display it as-is. Do not parse it and do not resolve it to a live task — task numbers are reused, so the same number may now belong to a different task.
taskNameSet only when the task has been deleted: the name it had at that moment. A point-in-time copy, not kept in sync with anything.
The related Team Member, present only when you pass ?expand=member.
Delete Time Entry
Permanently delete this Time Entry. This cannot be undone.
Required scope: time-entries:delete
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Time Entry.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Delete Time Entry › Responses
No Content
Update Time Entry
Partially update a Time Entry. Only the fields you send are changed.
Required scope: time-entries:write
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Time Entry.
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Update Time Entry › Request Body
descriptionFree-text note about what the time was spent on. This is the field GET /time-entries/search matches against.
startWhen the tracked interval began (ISO 8601).
endWhen the tracked interval ended (ISO 8601). Set it to stop a running entry. A stopped entry cannot be reopened, so null is refused: start a new timer with POST /time-entries/start.
expectedUpdatedAtOptional concurrency guard: the updatedAt you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh updatedAt.
Update Time Entry › Responses
OK
idUnique identifier for this resource.
createdAtCreation timestamp.
startWhen the tracked interval began (ISO 8601).
manualTrue for entries created through this API; false for entries captured by the timer in the Nifty app. Server-set.
memberIdThe team member this time is tracked for. Set by the server from whoever is calling — you cannot log time on someone else's behalf.
updatedAtLast update timestamp.
descriptionFree-text note about what the time was spent on. This is the field GET /time-entries/search matches against.
endWhen the tracked interval ended (ISO 8601); null while the entry is running. Start a timer with POST /time-entries/start. Creating an entry without end (or with null) makes a running entry without stopping your current one. PATCH end to stop a running entry; a stopped entry cannot be reopened, so PATCH with end: null is refused.
projectIdThe project this time is booked against. Set once when the entry is created: an entry cannot be moved to another project afterwards.
taskIdThe task this time is tracked against. Set once when the entry is created: an entry cannot be moved to another task afterwards. Null if that task has since been deleted — the entry is kept, and taskNiceId and taskName then say which task it was.
taskNiceIdSet only when the task has been deleted: a ready-to-display reference to it, such as PROJ-5 · deleted. Display it as-is. Do not parse it and do not resolve it to a live task — task numbers are reused, so the same number may now belong to a different task.
taskNameSet only when the task has been deleted: the name it had at that moment. A point-in-time copy, not kept in sync with anything.
The related Team Member, present only when you pass ?expand=member.
Search Time Entries
Full-text ranked search across timeEntries. Ranked by relevance; pages are capped at 200 results. Filterable by 7 fields. Always scoped to your own entries, whatever your role — unlike list and get, a reporting permission does NOT widen it. Do not build a team report from this endpoint; it will silently under-report.
Required scope: time-entries:read
query Parameters
qFull-text search query. Trimmed before matching; URLs, e-mail addresses and HTML markup are rejected.
cursorOpaque cursor for the next page (the envelope nextCursor).
limitItems per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow nextCursor instead of assuming one page held everything.
includeTotalWhen true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination.
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
manual[eq]Filter where manual equals.
start[gt]Filter where start is greater than.
start[gte]Filter where start is greater than or equal to.
start[lt]Filter where start is less than.
start[lte]Filter where start is less than or equal to.
end[null]Filter where end is null (pass true).
end[notNull]Filter where end is not null (pass true).
createdAt[gt]Filter where createdAt is greater than.
createdAt[gte]Filter where createdAt is greater than or equal to.
createdAt[lt]Filter where createdAt is less than.
createdAt[lte]Filter where createdAt is less than or equal to.
projectId[eq]Filter where projectId equals.
projectId[in]Filter where projectId is one of (comma-separated list).
taskId[eq]Filter where taskId equals.
taskId[in]Filter where taskId is one of (comma-separated list).
memberId[eq]Filter where memberId equals.
memberId[in]Filter where memberId is one of (comma-separated list).
Search Time Entries › Responses
OK
The page of results.
totalTotal rows matching the query (across pages).
limithasMorenextCursorOpaque cursor for the next page; null on the last page.
Start (Time Entry)
Starts a running time entry for you on taskId. Every entry of yours that is already running is stopped in the same transaction, so a start leaves you with exactly one. (POST /time-entries without end does not stop anything, so entries created that way can already overlap.) Members only: an agent or system identity gets 400 identity_rejected. Refused with 403 project_access_denied when the task's project is not visible to you, 404 when the task does not exist or is outside your workspace, 403 permission_denied when your role lacks startStopTimer, and 409 conflict when the task is completed or archived. Events: timeEntry.start fires for the new entry only, which also emits timeEntry.created; each entry it stops emits timeEntry.updated, never timeEntry.stop. Returns the new entry, with end null.
Required scope: time-entries:write
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Start (Time Entry) › Request Body
taskIdThe task to track time against.
descriptionFree-text note about what the time is spent on.
Start (Time Entry) › Responses
OK
idcreatedAtstartmanualmemberIdupdatedAtdescriptionendprojectIdtaskIdtaskNiceIdtaskNameStop (Time Entry)
Stops every running time entry of yours and returns the most recently started one, with end set. Members only: an agent or system identity gets 400 identity_rejected. If you have no running entry, the call fails with 409 no_running_timer. Events: timeEntry.stop fires for the returned entry only; every entry stopped emits timeEntry.updated, so watch timeEntry.updated where end becomes non-null to see all stops.
Required scope: time-entries:write
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Stop (Time Entry) › Responses
OK
idcreatedAtstartmanualmemberIdupdatedAtdescriptionendprojectIdtaskIdtaskNiceIdtaskName