Skip to content
TIMEKEEPER
API DOCS
Log inSign up

Time Entries & Day Summary

Create, close, list, edit, and delete time entries, then attach comments and files to a specific day. Owned-resource handlers return 404 when the record is missing or belongs to another user.

Time Entries#

Punch clock and entries#

POST/api/checkin

Start a new open session for the authenticated user.

Request
  • No request body.
Response
  • 201 with time entry object with id, userId, date, checkIn, checkOut, source, createdAt, and updatedAt; 409 if a session is already open.
POST/api/checkout

Close the current open session.

Request
  • No request body.
Response
  • time entry object with id, userId, date, checkIn, checkOut, source, createdAt, and updatedAt; 404 if no session is open, 422 if under one minute.
GET/api/time-entries

List entries ordered by date descending, then check-in ascending.

Request
  • query date or from / to as YYYY-MM-DD; optional limit capped at 500 and skip
Response
  • array of time entry object with id, userId, date, checkIn, checkOut, source, createdAt, and updatedAt.
POST/api/time-entries

Create a manual time entry and write an audit log.

Request
  • JSON { date: YYYY-MM-DD, checkIn: ISO datetime, checkOut?: ISO datetime | null }
Response
  • 201 with time entry object with id, userId, date, checkIn, checkOut, source, createdAt, and updatedAt.
Notes
  • checkIn must fall on date; check-out must be later.
PATCH/api/time-entries/:id

Update check-in and/or check-out on one owned entry.

Request
  • JSON { checkIn?: ISO datetime, checkOut?: ISO datetime | null }
Response
  • time entry object with id, userId, date, checkIn, checkOut, source, createdAt, and updatedAt; 404 when the entry is missing or not owned.
DELETE/api/time-entries/:id

Delete one owned entry and write an audit log.

Request
  • No request body.
Response
  • JSON { success: true }; 404 when missing or not owned.

Day Summary#

Comments and files#

GET/api/days/:date

Fetch all comments and files for one day.

Request
  • No request body.
Response
  • JSON { comments: DayComment[], files: DayFile[] }.
Notes
  • :date must be YYYY-MM-DD.
GET/api/days/:date/comments

List comments for one day, oldest first.

Request
  • No request body.
Response
  • array of comment object with id, userId, date, content, time, createdAt, and updatedAt.
POST/api/days/:date/comments

Create a day comment and write an audit log.

Request
  • JSON { content: string, time?: ISO datetime | null }; content is 1 to 10000 chars
Response
  • 201 with comment object with id, userId, date, content, time, createdAt, and updatedAt.
GET/api/days/:date/files

List files for one day, oldest first.

Request
  • No request body.
Response
  • array of file object with id, userId, date, filename, storagePath, mimeType, size, time, createdAt, and updatedAt.
POST/api/days/:date/files

Upload one day file with multipart form data.

Request
  • multipart file plus optional time; allowed types are JPEG, PNG, GIF, WebP, PDF, text/plain, and text/csv
Response
  • 201 with file object with id, userId, date, filename, storagePath, mimeType, size, time, createdAt, and updatedAt.
Notes
  • default max size is 52428800 bytes (50 MiB) unless MAX_FILE_SIZE is changed.
PATCH/api/comments/:id

Update one owned comment.

Request
  • JSON { content?: string, time?: ISO datetime | null }
Response
  • comment object with id, userId, date, content, time, createdAt, and updatedAt; 404 when missing or not owned.
DELETE/api/comments/:id

Delete one owned comment and write an audit log.

Request
  • No request body.
Response
  • JSON { success: true }; 404 when missing or not owned.
GET/api/files/:id/download

Download one owned file as an attachment.

Request
  • No request body.
Response
  • file stream with Content-Type, Content-Disposition, and Content-Length headers.
DELETE/api/files/:id

Delete one owned file from storage and audit log.

Request
  • No request body.
Response
  • JSON { success: true }; 404 when missing or not owned.