Time Entries

List time entries

GET /api/v1/time-entries

Any role. Returns the key owner's own entries, newest date first, each with its project (including its client), task (or null) and attachments. Owners and admins can ask for someone else's with userId.

curl "https://<your-instance>/api/v1/time-entries?from=2026-08-01&to=2026-08-31" \
  -H "Authorization: Bearer ch_live_..."

A from or to that isn't a date returns 422 with { "error": { "from": ["Use an ISO date, e.g. 2026-07-23."] } }.

{
  "timeEntries": [
    {
      "id": "cm9...",
      "date": "2026-08-05T00:00:00.000Z",
      "hours": "3.5",
      "description": "API migration",
      "billable": true,
      "rateOverride": null,
      "approvedAt": null,
      "invoiceLineItemId": null,
      "userId": "cm9...",
      "projectId": "cm9...",
      "taskId": null,
      "startTime": "09:00",
      "endTime": "12:30",
      "project": { "id": "cm9...", "name": "API migration", "client": { "id": "cm9...", "name": "Fintra Labs", "...": "..." }, "...": "..." },
      "task": null,
      "attachments": [
        {
          "id": "cm9...",
          "fileName": "Screenshot 2026-08-05 12.31.07.png",
          "contentType": "image/png",
          "sizeBytes": 184213,
          "clientVisible": true,
          "createdAt": "2026-08-05T16:31:09.000Z"
        }
      ]
    }
  ]
}

invoiceLineItemId is set once the entry is on an invoice. startTime and endTime are the local times the entry was worked (HH:MM, 24-hour), or null when only hours were logged; an endTime earlier than startTime ran past midnight.

Log time

POST /api/v1/time-entries

Any role. Returns 201 with { "timeEntry": { ... }, "warnings": [] }. Logging time can trigger budget alerts.

warnings lists anything worth a look that didn't stop the entry being saved: today, other timed entries of the same person that overlap this one, e.g. "Overlaps 09:00–10:30 on Acme · Website".

curl -X POST https://<your-instance>/api/v1/time-entries \
  -H "Authorization: Bearer ch_live_..." \
  -H "Content-Type: application/json" \
  -d '{"projectId": "cm9...", "date": "2026-08-05", "hours": 3.5, "description": "API migration"}'

With times instead of hours:

curl -X POST https://<your-instance>/api/v1/time-entries \
  -H "Authorization: Bearer ch_live_..." \
  -H "Content-Type: application/json" \
  -d '{"projectId": "cm9...", "date": "2026-08-05", "startTime": "09:00", "endTime": "12:30"}'

Update a time entry

PATCH /api/v1/time-entries/{id}

Takes the same body as logging time, and replaces the entry with it: send every field, not just the ones you're changing (projectId, date, and hours or startTime and endTime, are required; leaving out the times clears them). Returns { "timeEntry": { ... }, "warnings": [] }.

• Members can update only their own entries; owners and admins can update anyone's, and can move an entry to another member with userId.
• Moving an entry to a different projectId needs a project the key's owner can see.
• When an owner or admin updates an entry without rateOverride, any existing override is cleared.

Delete a time entry

DELETE /api/v1/time-entries/{id}

Returns { "ok": true }. Members can delete only their own entries; owners and admins can delete anyone's.

Evidence (attachments)

Screenshots or PDFs attached to an entry as evidence. Anyone who can see the entry's project can list and download them; the entry's owner, and owners and admins, can add, share and delete them, even after the entry is invoiced.

List an entry's attachments

GET /api/v1/time-entries/{id}/attachments

Returns { "attachments": [ ... ] }, each as in the list above.

Add attachments

POST /api/v1/time-entries/{id}/attachments

Send multipart/form-data with one or more file parts (PNG, JPEG, GIF, WebP or PDF; checked by contents, up to 5MB each, or 25MB with S3 storage; 20 per entry). Add clientVisible=true to show them on the invoice's time detail. Returns 201 with { "attachments": [ ... ] }.

curl -X POST https://<your-instance>/api/v1/time-entries/cm9.../attachments \
  -H "Authorization: Bearer ch_live_..." \
  -F "file=@screenshot.png" -F "clientVisible=true"

Download an attachment

GET /api/v1/time-entries/{id}/attachments/{attachmentId}

Returns the file itself.

Share or unshare an attachment

PATCH /api/v1/time-entries/{id}/attachments/{attachmentId}

Body: { "clientVisible": true }. Returns { "attachment": { ... } }.

Delete an attachment

DELETE /api/v1/time-entries/{id}/attachments/{attachmentId}

Returns { "ok": true }.

Rules and errors

An entry can't be changed or deleted once it's on an invoice. If your organization requires timesheet approval, a member can't add, change or remove time in a week they've submitted or that's been approved; owners and admins can.

Every failure below returns 422 with { "error": "<message>" }, except validation errors, which return field errors such as { "error": { "hours": ["Hours must be greater than zero"] } }.