API Documentation
Complete REST API reference for TimeHunter — 111 endpoints
https://api.timehunter.plGetting Started
Authentication
The API supports two authentication methods: JWT tokens and API keys.
JWT Token (HttpOnly Cookie)
Login via POST /api/auth/login to receive a JWT. It is set as an HttpOnly cookie automatically, or you can send it in the Authorization header.
Authorization: Bearer eyJhbG...API Key
Generate an API key in Settings → API Keys. Send it in the X-Api-Key header. Keys have read/write permissions.
X-Api-Key: th_live_abc123...Rate Limits
Endpoints are rate-limited to prevent abuse. When a limit is exceeded, the API returns HTTP 429.
| Limiter | Window | Max Requests |
|---|---|---|
| auth | 15 min | 20 |
| register | 1 h | 5 |
| qr | 1 min | 30 |
| api | 1 min | 100 |
| ai | 1 min | 10 |
| schema | 5 min | 10 |
| adminOp | 1 h | 5 |
| locationTrail | 30 s | 1 |
Authentication(5)
/api/auth/register-companyPublic5/1 hRegister a new company with admin account and plan selection
Show example
curl -X POST "https://api.timehunter.pl/api/auth/register-company" \
-H "Content-Type: application/json" \
-d '{"companyName":"Moja Firma Sp. z o.o.","nip":"1234567890","email":"admin@mojafirma.pl","password":"SecurePass123!","adminName":"Jan Kowalski","plan":"start","countryCode":"PL"}'{
"companyName": "Moja Firma Sp. z o.o.",
"nip": "1234567890",
"email": "admin@mojafirma.pl",
"password": "SecurePass123!",
"adminName": "Jan Kowalski",
"plan": "start",
"countryCode": "PL"
}{
"success": true,
"message": "Firma zarejestrowana pomyślnie",
"user": {
"id": "uuid",
"email": "admin@mojafirma.pl",
"role": "admin"
}
}/api/auth/loginPublic20/15 minAuthenticate with email and password, receive JWT token
Show example
curl -X POST "https://api.timehunter.pl/api/auth/login" \
-H "Content-Type: application/json" \
-d '{"email":"admin@mojafirma.pl","password":"SecurePass123!"}'{
"email": "admin@mojafirma.pl",
"password": "SecurePass123!"
}{
"success": true,
"user": {
"userId": "uuid",
"email": "admin@mojafirma.pl",
"role": "admin",
"companyId": "uuid"
}
}/api/auth/meJWTGet current user profile and subscription info
Show example
curl -X GET "https://api.timehunter.pl/api/auth/me" \ -H "Authorization: Bearer <token>"
{
"user": {
"id": "uuid",
"email": "admin@mojafirma.pl",
"full_name": "Jan Kowalski",
"role": "admin"
},
"subscription": {
"status": "trial",
"trialEnd": "2026-03-01"
}
}/api/auth/logoutPublicInvalidate session (clear HttpOnly cookie)
Show example
curl -X POST "https://api.timehunter.pl/api/auth/logout"
{
"success": true
}/api/auth/change-passwordJWTChange password for the authenticated user
Show example
curl -X POST "https://api.timehunter.pl/api/auth/change-password" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"currentPassword":"OldPass123!","newPassword":"NewPass456!"}'{
"currentPassword": "OldPass123!",
"newPassword": "NewPass456!"
}{
"success": true,
"message": "Hasło zmienione"
}Work Sessions(8)
/api/work/sessionJWTGet current active work session for the user
Show example
curl -X GET "https://api.timehunter.pl/api/work/session" \ -H "Authorization: Bearer <token>"
{
"session": {
"id": "uuid",
"start_time": "2026-02-15T08:00:00+01:00",
"break_start": null,
"end_time": null
},
"breakLimit": 30
}/api/work/startJWTStart a new work session with optional GPS location
Show example
curl -X POST "https://api.timehunter.pl/api/work/start" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"latitude":50.2649,"longitude":19.0238,"workMode":"office"}'{
"latitude": 50.2649,
"longitude": 19.0238,
"workMode": "office"
}{
"success": true,
"session": {
"id": "uuid",
"start_time": "2026-02-15T08:00:00+01:00"
}
}/api/work/stopJWTEnd the current work session
Show example
curl -X POST "https://api.timehunter.pl/api/work/stop" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"latitude":50.2649,"longitude":19.0238}'{
"latitude": 50.2649,
"longitude": 19.0238
}{
"success": true,
"session": {
"id": "uuid",
"end_time": "2026-02-15T16:00:00+01:00",
"total_hours": 8
}
}/api/work/break-startOptionalStart a break (supports QR token auth)
Show example
curl -X POST "https://api.timehunter.pl/api/work/break-start" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"qrToken":"optional-qr-token"}'{
"qrToken": "optional-qr-token"
}{
"success": true,
"breakStart": "2026-02-15T12:00:00+01:00"
}/api/work/break-endOptionalEnd the current break (supports QR token auth)
Show example
curl -X POST "https://api.timehunter.pl/api/work/break-end" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"qrToken":"optional-qr-token"}'{
"qrToken": "optional-qr-token"
}{
"success": true,
"breakEnd": "2026-02-15T12:30:00+01:00"
}/api/work/break-todayJWTGet total break time for today
Show example
curl -X GET "https://api.timehunter.pl/api/work/break-today" \ -H "Authorization: Bearer <token>"
{
"totalBreakSeconds": 1800
}/api/work/todayAPI Key / JWTGet today's work time summary
Show example
curl -X GET "https://api.timehunter.pl/api/work/today" \ -H "Authorization: Bearer <token>"
{
"totalSeconds": 28800,
"totalHours": "8.00"
}/api/work/location-updateJWTSend GPS location update during active session
Show example
curl -X POST "https://api.timehunter.pl/api/work/location-update" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"latitude":50.2649,"longitude":19.0238}'{
"latitude": 50.2649,
"longitude": 19.0238
}{
"success": true
}QR Code & Scanning(4)
/api/qr/:userIdJWTGet QR code for a user (self or admin)
Show example
curl -X GET "https://api.timehunter.pl/api/qr/:userId" \ -H "Authorization: Bearer <token>"
{
"qrToken": "uuid-token",
"qrCodeUrl": "data:image/png;base64,..."
}/api/work/qr-scanQR Token30/1 minScan QR code to toggle work session (start/stop/break)
Show example
curl -X POST "https://api.timehunter.pl/api/work/qr-scan" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"qrToken":"uuid-token","latitude":50.2649,"longitude":19.0238}'{
"qrToken": "uuid-token",
"latitude": 50.2649,
"longitude": 19.0238
}{
"success": true,
"action": "start",
"session": {
"id": "uuid"
}
}/api/work/qr-scan-statusQR Token30/1 minGet current work status via QR token
Show example
curl -X POST "https://api.timehunter.pl/api/work/qr-scan-status" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"qrToken":"uuid-token"}'{
"qrToken": "uuid-token"
}{
"isWorking": true,
"onBreak": false,
"sessionStart": "2026-02-15T08:00:00+01:00"
}/api/work/photo-uploadQR Token30/1 minUpload verification photo during QR registration
Show example
curl -X POST "https://api.timehunter.pl/api/work/photo-upload" \ -H "Authorization: Bearer <token>"
(multipart/form-data: qrToken, eventId, photo)
{
"success": true,
"photoUrl": "https://..."
}Attendance(3)
/api/attendanceJWT + AdminGet attendance data for all employees (admin)
Show example
curl -X GET "https://api.timehunter.pl/api/attendance" \ -H "Authorization: Bearer <token>"
GET /api/attendance?date=2026-02-15&employeeId=uuid
{
"attendance": [
{
"userId": "uuid",
"fullName": "Jan Kowalski",
"startTime": "08:00",
"endTime": "16:00",
"totalHours": "7.50",
"breaks": 1800
}
]
}/api/employees/statusAPI Key / JWTGet current working status of all employees
Show example
curl -X GET "https://api.timehunter.pl/api/employees/status" \ -H "Authorization: Bearer <token>"
{
"employees": [
{
"id": "uuid",
"fullName": "Jan Kowalski",
"isWorking": true,
"onBreak": false,
"startTime": "08:00"
}
]
}/api/late/todayJWTCheck if the user was late today
Show example
curl -X GET "https://api.timehunter.pl/api/late/today" \ -H "Authorization: Bearer <token>"
{
"isLate": false,
"minutesLate": 0
}Reports(6)
/api/report/dailyAPI Key / JWTGet daily work report
Show example
curl -X GET "https://api.timehunter.pl/api/report/daily" \ -H "Authorization: Bearer <token>"
GET /api/report/daily?date=2026-02-15
{
"date": "2026-02-15",
"totalHours": "8.00",
"sessions": []
}/api/report/weeklyAPI Key / JWTGet weekly work report
Show example
curl -X GET "https://api.timehunter.pl/api/report/weekly" \ -H "Authorization: Bearer <token>"
{
"weekStart": "2026-02-10",
"weekEnd": "2026-02-16",
"totalHours": "40.00"
}/api/report/monthlyAPI Key / JWTGet monthly work report
Show example
curl -X GET "https://api.timehunter.pl/api/report/monthly" \ -H "Authorization: Bearer <token>"
GET /api/report/monthly?month=2026-02
{
"month": "2026-02",
"totalHours": "160.00",
"workDays": 20
}/api/reports/periodJWT + AdminGet report for a custom date range (admin)
Show example
curl -X GET "https://api.timehunter.pl/api/reports/period" \ -H "Authorization: Bearer <token>"
GET /api/reports/period?from=2026-02-01&to=2026-02-28
{
"employees": [],
"summary": {
"totalHours": "320.00"
}
}/api/report/pdf-dataJWTGet report data for PDF generation
Show example
curl -X GET "https://api.timehunter.pl/api/report/pdf-data" \ -H "Authorization: Bearer <token>"
{
"reportData": {}
}/api/reports/monthly-pdfJWT + AdminGenerate monthly PDF report (admin)
Show example
curl -X POST "https://api.timehunter.pl/api/reports/monthly-pdf" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"month":"2026-02","employeeIds":["uuid1","uuid2"]}'{
"month": "2026-02",
"employeeIds": [
"uuid1",
"uuid2"
]
}(PDF binary)
Leave Requests(5)
/api/leave/requestJWTSubmit a new leave request (vacation, sick leave, etc.)
Show example
curl -X POST "https://api.timehunter.pl/api/leave/request" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"leave_type":"vacation","start_date":"2026-03-01","end_date":"2026-03-05","comment":"Urlop wypoczynkowy","request_unit":"days"}'{
"leave_type": "vacation",
"start_date": "2026-03-01",
"end_date": "2026-03-05",
"comment": "Urlop wypoczynkowy",
"request_unit": "days"
}{
"success": true,
"request": {
"id": "uuid",
"status": "pending"
}
}/api/leave/balance/:userIdJWTGet leave balance for a user
Show example
curl -X GET "https://api.timehunter.pl/api/leave/balance/:userId" \ -H "Authorization: Bearer <token>"
{
"balance": {
"total_days": 26,
"used_days": 5,
"pending_days": 3,
"remaining_days": 18
}
}/api/leave/balance/:userIdJWT + AdminUpdate leave balance (admin)
Show example
curl -X PUT "https://api.timehunter.pl/api/leave/balance/:userId" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"total_days":30}'{
"total_days": 30
}{
"success": true
}/api/admin/leave-requestsJWT + AdminList all leave requests (admin)
Show example
curl -X GET "https://api.timehunter.pl/api/admin/leave-requests" \ -H "Authorization: Bearer <token>"
{
"requests": [
{
"id": "uuid",
"employee": "Jan Kowalski",
"leave_type": "vacation",
"status": "pending"
}
]
}/api/admin/leave/:actionJWT + AdminApprove or reject a leave request (admin)
Show example
curl -X POST "https://api.timehunter.pl/api/admin/leave/:action" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"requestId":"uuid","comment":"Zatwierdzono"}'{
"requestId": "uuid",
"comment": "Zatwierdzono"
}{
"success": true,
"status": "approved"
}Holidays(4)
/api/holidaysJWTGet list of holidays for the company
Show example
curl -X GET "https://api.timehunter.pl/api/holidays" \ -H "Authorization: Bearer <token>"
{
"holidays": [
{
"id": 1,
"name": "Nowy Rok",
"date": "2026-01-01",
"country_code": "PL"
}
]
}/api/admin/holidaysJWT + AdminCreate a custom holiday (admin)
Show example
curl -X POST "https://api.timehunter.pl/api/admin/holidays" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"name":"Dzień Firmy","date":"2026-06-15"}'{
"name": "Dzień Firmy",
"date": "2026-06-15"
}{
"success": true,
"holiday": {
"id": 2,
"name": "Dzień Firmy"
}
}/api/admin/holidays/:idJWT + AdminUpdate a holiday (admin)
Show example
curl -X PUT "https://api.timehunter.pl/api/admin/holidays/:id" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"name":"Dzień Firmy (zaktualizowany)","date":"2026-06-16"}'{
"name": "Dzień Firmy (zaktualizowany)",
"date": "2026-06-16"
}{
"success": true
}/api/admin/holidays/:idJWT + AdminDelete a holiday (admin)
Show example
curl -X DELETE "https://api.timehunter.pl/api/admin/holidays/:id" \ -H "Authorization: Bearer <token>"
{
"success": true
}Events(6)
/api/eventsJWTGet events/tasks for a date
Show example
curl -X GET "https://api.timehunter.pl/api/events" \ -H "Authorization: Bearer <token>"
GET /api/events?date=2026-02-15
{
"events": [
{
"id": 1,
"title": "Spotkanie",
"start": "09:00",
"end": "10:00"
}
]
}/api/events/createJWTCreate a new event or task
Show example
curl -X POST "https://api.timehunter.pl/api/events/create" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"title":"Spotkanie","date":"2026-02-20","start_time":"09:00","end_time":"10:00"}'{
"title": "Spotkanie",
"date": "2026-02-20",
"start_time": "09:00",
"end_time": "10:00"
}{
"success": true,
"event": {
"id": 2
}
}/api/events/:idJWT + AdminUpdate an event (admin)
Show example
curl -X PUT "https://api.timehunter.pl/api/events/:id" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"title":"Spotkanie (zmienione)","end_time":"11:00"}'{
"title": "Spotkanie (zmienione)",
"end_time": "11:00"
}{
"success": true
}/api/events/:idJWT + AdminDelete an event (admin)
Show example
curl -X DELETE "https://api.timehunter.pl/api/events/:id" \ -H "Authorization: Bearer <token>"
{
"success": true
}/api/events/bulk-activateJWT + AdminBulk activate events (admin)
Show example
curl -X POST "https://api.timehunter.pl/api/events/bulk-activate" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"ids":[1,2,3]}'{
"ids": [
1,
2,
3
]
}{
"success": true,
"count": 3
}/api/events/bulk-deleteJWT + AdminBulk delete events (admin)
Show example
curl -X POST "https://api.timehunter.pl/api/events/bulk-delete" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"ids":[1,2,3]}'{
"ids": [
1,
2,
3
]
}{
"success": true,
"count": 3
}Requests & Approvals(7)
/api/requestsJWTGet user's requests or all requests (admin)
Show example
curl -X GET "https://api.timehunter.pl/api/requests" \ -H "Authorization: Bearer <token>"
{
"requests": [
{
"id": "uuid",
"leave_type": "vacation",
"status": "pending"
}
]
}/api/requestsJWTCreate a new request
Show example
curl -X POST "https://api.timehunter.pl/api/requests" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"employee_id":"uuid","start_date":"2026-03-01","end_date":"2026-03-05","leave_type":"vacation","comment":"Urlop"}'{
"employee_id": "uuid",
"start_date": "2026-03-01",
"end_date": "2026-03-05",
"leave_type": "vacation",
"comment": "Urlop"
}{
"success": true,
"request": {
"id": "uuid"
}
}/api/requests/:idJWTUpdate request details
Show example
curl -X PUT "https://api.timehunter.pl/api/requests/:id" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"start_date":"2026-03-02","end_date":"2026-03-06"}'{
"start_date": "2026-03-02",
"end_date": "2026-03-06"
}{
"success": true
}/api/requests/:id/statusJWTUpdate request status (approve/reject)
Show example
curl -X PUT "https://api.timehunter.pl/api/requests/:id/status" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"status":"approved","comment":"Zatwierdzono"}'{
"status": "approved",
"comment": "Zatwierdzono"
}{
"success": true
}/api/requests/:idJWTDelete a request
Show example
curl -X DELETE "https://api.timehunter.pl/api/requests/:id" \ -H "Authorization: Bearer <token>"
{
"success": true
}/api/requests/bulk-approveJWTBulk approve requests
Show example
curl -X POST "https://api.timehunter.pl/api/requests/bulk-approve" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"ids":["uuid1","uuid2"]}'{
"ids": [
"uuid1",
"uuid2"
]
}{
"success": true,
"count": 2
}/api/requests/bulk-rejectJWTBulk reject requests
Show example
curl -X POST "https://api.timehunter.pl/api/requests/bulk-reject" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"ids":["uuid1","uuid2"],"comment":"Odrzucono"}'{
"ids": [
"uuid1",
"uuid2"
],
"comment": "Odrzucono"
}{
"success": true,
"count": 2
}Schedules(5)
/api/schedulesAPI Key / JWTGet work schedules
Show example
curl -X GET "https://api.timehunter.pl/api/schedules" \ -H "Authorization: Bearer <token>"
GET /api/schedules?month=2026-02&userId=uuid
{
"schedules": [
{
"id": "uuid",
"date": "2026-02-15",
"start": "08:00",
"end": "16:00"
}
]
}/api/schedulesJWTCreate a work schedule entry
Show example
curl -X POST "https://api.timehunter.pl/api/schedules" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"userId":"uuid","date":"2026-02-20","start_time":"08:00","end_time":"16:00"}'{
"userId": "uuid",
"date": "2026-02-20",
"start_time": "08:00",
"end_time": "16:00"
}{
"success": true,
"schedule": {
"id": "uuid"
}
}/api/schedules/bulkJWTBulk create schedule entries
Show example
curl -X POST "https://api.timehunter.pl/api/schedules/bulk" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"schedules":[{"userId":"uuid","date":"2026-02-20","start_time":"08:00","end_time":"16:00"}]}'{
"schedules": [
{
"userId": "uuid",
"date": "2026-02-20",
"start_time": "08:00",
"end_time": "16:00"
}
]
}{
"success": true,
"count": 5
}/api/schedules/:idJWTUpdate a schedule entry
Show example
curl -X PUT "https://api.timehunter.pl/api/schedules/:id" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"start_time":"09:00","end_time":"17:00"}'{
"start_time": "09:00",
"end_time": "17:00"
}{
"success": true
}/api/schedules/:idJWTDelete a schedule entry
Show example
curl -X DELETE "https://api.timehunter.pl/api/schedules/:id" \ -H "Authorization: Bearer <token>"
{
"success": true
}Employee Management(6)
/api/admin/usersJWT + AdminList all employees in the company (admin)
Show example
curl -X GET "https://api.timehunter.pl/api/admin/users" \ -H "Authorization: Bearer <token>"
{
"users": [
{
"id": "uuid",
"full_name": "Jan Kowalski",
"email": "jan@firma.pl",
"role": "employee"
}
]
}/api/admin/add-employeeJWT + AdminAdd a new employee (admin)
Show example
curl -X POST "https://api.timehunter.pl/api/admin/add-employee" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"fullName":"Anna Nowak","email":"anna@firma.pl","password":"TempPass123!","role":"employee","initialLeaveDays":26}'{
"fullName": "Anna Nowak",
"email": "anna@firma.pl",
"password": "TempPass123!",
"role": "employee",
"initialLeaveDays": 26
}{
"success": true,
"employee": {
"id": "uuid",
"email": "anna@firma.pl"
}
}/api/admin/edit-employee/:idJWT + AdminEdit employee details (admin)
Show example
curl -X PUT "https://api.timehunter.pl/api/admin/edit-employee/:id" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"fullName":"Anna Nowak-Kowalska","role":"manager"}'{
"fullName": "Anna Nowak-Kowalska",
"role": "manager"
}{
"success": true
}/api/admin/update-permissions/:idJWT + AdminUpdate employee permissions (admin)
Show example
curl -X PUT "https://api.timehunter.pl/api/admin/update-permissions/:id" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"permissions":{"dashboard":true,"reports":true,"events":false}}'{
"permissions": {
"dashboard": true,
"reports": true,
"events": false
}
}{
"success": true
}/api/admin/archive-employee/:idJWT + AdminArchive/deactivate an employee (admin)
Show example
curl -X PUT "https://api.timehunter.pl/api/admin/archive-employee/:id" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"archived":true}'{
"archived": true
}{
"success": true
}/api/admin/user-timeJWT + AdminGet user work time summary (admin)
Show example
curl -X GET "https://api.timehunter.pl/api/admin/user-time" \ -H "Authorization: Bearer <token>"
GET /api/admin/user-time?date=2026-02-15
{
"users": [
{
"userId": "uuid",
"fullName": "Jan Kowalski",
"totalHours": "8.00",
"isWorking": true
}
]
}Overtime(5)
/api/overtime/settingsJWTGet overtime settings
Show example
curl -X GET "https://api.timehunter.pl/api/overtime/settings" \ -H "Authorization: Bearer <token>"
{
"dailyThreshold": 8,
"weeklyThreshold": 40,
"multiplier": 1.5
}/api/overtime/settingsJWT + AdminUpdate overtime settings (admin)
Show example
curl -X PUT "https://api.timehunter.pl/api/overtime/settings" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"dailyThreshold":8,"weeklyThreshold":40,"multiplier":1.5}'{
"dailyThreshold": 8,
"weeklyThreshold": 40,
"multiplier": 1.5
}{
"success": true
}/api/overtime/recordsJWTGet overtime records
Show example
curl -X GET "https://api.timehunter.pl/api/overtime/records" \ -H "Authorization: Bearer <token>"
GET /api/overtime/records?month=2026-02
{
"records": [
{
"id": "uuid",
"date": "2026-02-10",
"hours": 2.5,
"status": "pending"
}
]
}/api/overtime/summaryJWTGet overtime summary
Show example
curl -X GET "https://api.timehunter.pl/api/overtime/summary" \ -H "Authorization: Bearer <token>"
{
"totalOvertimeHours": 15.5,
"pendingHours": 5,
"approvedHours": 10.5
}/api/overtime/bulk-approveJWT + AdminBulk approve overtime records (admin)
Show example
curl -X POST "https://api.timehunter.pl/api/overtime/bulk-approve" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"ids":["uuid1","uuid2"]}'{
"ids": [
"uuid1",
"uuid2"
]
}{
"success": true,
"count": 2
}Work Groups(4)
/api/admin/work-groupsJWT + AdminList all work groups (admin)
Show example
curl -X GET "https://api.timehunter.pl/api/admin/work-groups" \ -H "Authorization: Bearer <token>"
{
"groups": [
{
"id": "uuid",
"name": "Produkcja",
"membersCount": 12
}
]
}/api/admin/work-groupsJWT + AdminCreate a work group (admin)
Show example
curl -X POST "https://api.timehunter.pl/api/admin/work-groups" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"name":"Logistyka"}'{
"name": "Logistyka"
}{
"success": true,
"group": {
"id": "uuid",
"name": "Logistyka"
}
}/api/admin/work-groups/:idJWT + AdminUpdate a work group (admin)
Show example
curl -X PUT "https://api.timehunter.pl/api/admin/work-groups/:id" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"name":"Logistyka & Transport"}'{
"name": "Logistyka & Transport"
}{
"success": true
}/api/admin/work-groups/:idJWT + AdminDelete a work group (admin)
Show example
curl -X DELETE "https://api.timehunter.pl/api/admin/work-groups/:id" \ -H "Authorization: Bearer <token>"
{
"success": true
}Announcements(4)
/api/announcementsJWTGet announcements
Show example
curl -X GET "https://api.timehunter.pl/api/announcements" \ -H "Authorization: Bearer <token>"
{
"announcements": [
{
"id": "uuid",
"title": "Nowy regulamin",
"content": "...",
"createdAt": "2026-02-15"
}
]
}/api/announcementsJWT + AdminCreate an announcement (admin)
Show example
curl -X POST "https://api.timehunter.pl/api/announcements" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"title":"Zmiana godzin pracy","content":"Od marca biuro czynne 7-15"}'{
"title": "Zmiana godzin pracy",
"content": "Od marca biuro czynne 7-15"
}{
"success": true,
"announcement": {
"id": "uuid"
}
}/api/announcements/:id/readJWTMark an announcement as read
Show example
curl -X POST "https://api.timehunter.pl/api/announcements/:id/read" \ -H "Authorization: Bearer <token>"
{
"success": true
}/api/announcements/unread-countJWTGet unread announcements count
Show example
curl -X GET "https://api.timehunter.pl/api/announcements/unread-count" \ -H "Authorization: Bearer <token>"
{
"count": 3
}Company Management(7)
/api/company/updateJWT + AdminUpdate company settings (admin)
Show example
curl -X POST "https://api.timehunter.pl/api/company/update" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"name":"Nowa Nazwa Sp. z o.o."}'{
"name": "Nowa Nazwa Sp. z o.o."
}{
"success": true
}/api/company/detailsJWT + AdminGet company details (admin)
Show example
curl -X GET "https://api.timehunter.pl/api/company/details" \ -H "Authorization: Bearer <token>"
{
"company": {
"id": "uuid",
"name": "Moja Firma",
"plan": "start"
}
}/api/company/brandingJWTGet company branding settings
Show example
curl -X GET "https://api.timehunter.pl/api/company/branding" \ -H "Authorization: Bearer <token>"
{
"logoUrl": "https://...",
"primaryColor": "#2563eb"
}/api/company/brandingJWT + AdminUpdate company branding (admin)
Show example
curl -X PUT "https://api.timehunter.pl/api/company/branding" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"primaryColor":"#059669"}'{
"primaryColor": "#059669"
}{
"success": true
}/api/company/logoJWT + AdminUpload company logo (admin)
Show example
curl -X POST "https://api.timehunter.pl/api/company/logo" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"logo_url":"https://example.com/logo.png"}'{
"logo_url": "https://example.com/logo.png"
}{
"success": true
}/api/company/locationJWT + AdminGet company primary location (admin)
Show example
curl -X GET "https://api.timehunter.pl/api/company/location" \ -H "Authorization: Bearer <token>"
{
"location": {
"latitude": 50.2649,
"longitude": 19.0238,
"radius": 200
}
}/api/company/locationJWT + AdminSet company primary location (admin)
Show example
curl -X POST "https://api.timehunter.pl/api/company/location" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"latitude":50.2649,"longitude":19.0238,"radius":200}'{
"latitude": 50.2649,
"longitude": 19.0238,
"radius": 200
}{
"success": true
}Subscriptions & Plans(3)
/api/subscription/statusJWTGet current subscription status
Show example
curl -X GET "https://api.timehunter.pl/api/subscription/status" \ -H "Authorization: Bearer <token>"
{
"status": "trial",
"planId": "uuid",
"trialEnd": "2026-03-01",
"paymentReference": "TH-12345"
}/api/subscription/payment-infoJWTGet payment information for subscription
Show example
curl -X GET "https://api.timehunter.pl/api/subscription/payment-info" \ -H "Authorization: Bearer <token>"
{
"bankName": "mBank",
"iban": "PL...",
"reference": "TH-12345",
"amount": "32.50 PLN"
}/api/plans/publicPublicGet public pricing plans
Show example
curl -X GET "https://api.timehunter.pl/api/plans/public"
{
"plans": [
{
"slug": "micro",
"name": "Micro",
"price_per_user": 3.99,
"max_employees": 5
},
{
"slug": "start",
"name": "Start",
"price_per_user": 6.5,
"max_employees": 15
},
{
"slug": "pro",
"name": "Pro",
"price_per_user": 12.5,
"max_employees": null
}
]
}Add-ons(4)
/api/addonsJWTGet available add-ons
Show example
curl -X GET "https://api.timehunter.pl/api/addons" \ -H "Authorization: Bearer <token>"
{
"addons": [
{
"id": "uuid",
"slug": "photo_registration",
"name": "Rejestracja zdjęciem",
"price": 1
}
]
}/api/addons/:id/activateJWT + AdminActivate an add-on (admin)
Show example
curl -X POST "https://api.timehunter.pl/api/addons/:id/activate" \ -H "Authorization: Bearer <token>"
{
"success": true
}/api/addons/:id/deactivateJWT + AdminDeactivate an add-on (admin)
Show example
curl -X POST "https://api.timehunter.pl/api/addons/:id/deactivate" \ -H "Authorization: Bearer <token>"
{
"success": true
}/api/company/addonsJWTGet company's active add-ons
Show example
curl -X GET "https://api.timehunter.pl/api/company/addons" \ -H "Authorization: Bearer <token>"
{
"activeAddons": [
"photo_registration",
"location_basic"
]
}API Keys(3)
/api/api-keysJWT + AdminList API keys (admin)
Show example
curl -X GET "https://api.timehunter.pl/api/api-keys" \ -H "Authorization: Bearer <token>"
{
"keys": [
{
"id": "uuid",
"name": "Integration Key",
"prefix": "th_live_ab12",
"created_at": "2026-02-01"
}
]
}/api/api-keysJWT + AdminCreate a new API key (admin)
Show example
curl -X POST "https://api.timehunter.pl/api/api-keys" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"name":"ERP Integration","permissions":{"read":true,"write":false}}'{
"name": "ERP Integration",
"permissions": {
"read": true,
"write": false
}
}{
"success": true,
"key": "th_live_abc123...",
"prefix": "th_live_ab12"
}/api/api-keys/:idJWT + AdminDelete an API key (admin)
Show example
curl -X DELETE "https://api.timehunter.pl/api/api-keys/:id" \ -H "Authorization: Bearer <token>"
{
"success": true
}Email Reports(4)
/api/email-reportsJWT + AdminList scheduled email reports (admin)
Show example
curl -X GET "https://api.timehunter.pl/api/email-reports" \ -H "Authorization: Bearer <token>"
{
"reports": [
{
"id": "uuid",
"title": "Raport tygodniowy",
"schedule": "weekly",
"recipients": [
"admin@firma.pl"
]
}
]
}/api/email-reportsJWT + AdminCreate a scheduled email report (admin)
Show example
curl -X POST "https://api.timehunter.pl/api/email-reports" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"title":"Raport dzienny","schedule":"daily","recipients":["admin@firma.pl"]}'{
"title": "Raport dzienny",
"schedule": "daily",
"recipients": [
"admin@firma.pl"
]
}{
"success": true,
"report": {
"id": "uuid"
}
}/api/email-reports/:idJWT + AdminUpdate an email report (admin)
Show example
curl -X PUT "https://api.timehunter.pl/api/email-reports/:id" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"title":"Raport dzienny (v2)","schedule":"daily"}'{
"title": "Raport dzienny (v2)",
"schedule": "daily"
}{
"success": true
}/api/email-reports/:idJWT + AdminDelete an email report (admin)
Show example
curl -X DELETE "https://api.timehunter.pl/api/email-reports/:id" \ -H "Authorization: Bearer <token>"
{
"success": true
}AI Assistant(2)
/api/ai/chat-claudeJWT10/1 minChat with AI assistant about work data
Show example
curl -X POST "https://api.timehunter.pl/api/ai/chat-claude" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"message":"Ile godzin przepracowałem w tym tygodniu?","context":"work_time"}'{
"message": "Ile godzin przepracowałem w tym tygodniu?",
"context": "work_time"
}{
"reply": "W tym tygodniu przepracowałeś 32.5 godziny..."
}/api/ai/analyze-dbJWT + Admin10/1 minAI-powered database analysis (admin)
Show example
curl -X POST "https://api.timehunter.pl/api/ai/analyze-db" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"query":"Pokaż pracowników z nadgodzinami w lutym"}'{
"query": "Pokaż pracowników z nadgodzinami w lutym"
}{
"analysis": "...",
"data": []
}Webhooks(3)
/api/integrations/webhookJWT + AdminGet webhook settings (admin)
Show example
curl -X GET "https://api.timehunter.pl/api/integrations/webhook" \ -H "Authorization: Bearer <token>"
{
"webhookUrl": "https://...",
"events": [
"work.start",
"work.stop"
]
}/api/integrations/webhookJWT + AdminUpdate webhook settings (admin)
Show example
curl -X PUT "https://api.timehunter.pl/api/integrations/webhook" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"webhookUrl":"https://example.com/hook","events":["work.start","work.stop","leave.request"]}'{
"webhookUrl": "https://example.com/hook",
"events": [
"work.start",
"work.stop",
"leave.request"
]
}{
"success": true
}/api/integrations/webhook/testJWT + AdminSend a test webhook (admin)
Show example
curl -X POST "https://api.timehunter.pl/api/integrations/webhook/test" \ -H "Authorization: Bearer <token>"
{
"success": true,
"statusCode": 200
}Dashboard Layouts(2)
/api/dashboard/layoutJWTGet user's custom dashboard layout
Show example
curl -X GET "https://api.timehunter.pl/api/dashboard/layout" \ -H "Authorization: Bearer <token>"
{
"layout": {
"widgets": [
"workStatus",
"breakTimer",
"leaveBalance"
]
}
}/api/dashboard/layoutJWTSave dashboard layout
Show example
curl -X POST "https://api.timehunter.pl/api/dashboard/layout" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"widgets":["workStatus","breakTimer","quickTile"]}'{
"widgets": [
"workStatus",
"breakTimer",
"quickTile"
]
}{
"success": true
}Locations(2)
/api/admin/locationsJWT + AdminGet all registered work locations (admin)
Show example
curl -X GET "https://api.timehunter.pl/api/admin/locations" \ -H "Authorization: Bearer <token>"
{
"locations": [
{
"id": "uuid",
"name": "Biuro",
"latitude": 50.2649,
"longitude": 19.0238,
"radius": 200
}
]
}/api/admin/location-trailJWT + AdminGet GPS location trail for an employee (admin)
Show example
curl -X GET "https://api.timehunter.pl/api/admin/location-trail" \ -H "Authorization: Bearer <token>"
GET /api/admin/location-trail?userId=uuid&date=2026-02-15
{
"trail": [
{
"lat": 50.2649,
"lng": 19.0238,
"timestamp": "08:05"
}
]
}Hour Presets(2)
/api/hour-presetsJWTGet hour presets for quick time entry
Show example
curl -X GET "https://api.timehunter.pl/api/hour-presets" \ -H "Authorization: Bearer <token>"
{
"presets": [
{
"id": "uuid",
"name": "8h standard",
"startTime": "08:00",
"endTime": "16:00"
}
]
}/api/hour-presetsJWT + AdminCreate an hour preset (admin)
Show example
curl -X POST "https://api.timehunter.pl/api/hour-presets" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"name":"Nocna zmiana","startTime":"22:00","endTime":"06:00"}'{
"name": "Nocna zmiana",
"startTime": "22:00",
"endTime": "06:00"
}{
"success": true,
"preset": {
"id": "uuid"
}
}Approval Workflows(2)
/api/approval-workflowsJWT + AdminList approval workflows (admin)
Show example
curl -X GET "https://api.timehunter.pl/api/approval-workflows" \ -H "Authorization: Bearer <token>"
{
"workflows": [
{
"id": "uuid",
"name": "Urlopy",
"steps": [
"manager",
"admin"
]
}
]
}/api/approval-workflowsJWT + AdminCreate an approval workflow (admin)
Show example
curl -X POST "https://api.timehunter.pl/api/approval-workflows" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"name":"Nadgodziny","steps":[{"role":"manager","action":"approve"}]}'{
"name": "Nadgodziny",
"steps": [
{
"role": "manager",
"action": "approve"
}
]
}{
"success": true,
"workflow": {
"id": "uuid"
}
}Audit Logs(1)
/api/audit-logsJWT + AdminView audit logs (admin)
Show example
curl -X GET "https://api.timehunter.pl/api/audit-logs" \ -H "Authorization: Bearer <token>"
GET /api/audit-logs?page=1&limit=50
{
"logs": [
{
"id": "uuid",
"action": "employee.created",
"userId": "uuid",
"timestamp": "2026-02-15T10:30:00"
}
],
"total": 150
}Notifications(1)
/api/notificationsJWTGet user notifications
Show example
curl -X GET "https://api.timehunter.pl/api/notifications" \ -H "Authorization: Bearer <token>"
{
"notifications": [
{
"id": "uuid",
"type": "leave_approved",
"message": "Twój urlop został zatwierdzony",
"read": false
}
]
}Auto-fill(1)
/api/work-sessions/auto-fillJWT + AdminAuto-fill missing work sessions for a month (admin)
Show example
curl -X POST "https://api.timehunter.pl/api/work-sessions/auto-fill" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"userId":"uuid","month":"2026-02","startTime":"08:00","endTime":"16:00"}'{
"userId": "uuid",
"month": "2026-02",
"startTime": "08:00",
"endTime": "16:00"
}{
"success": true,
"sessionsCreated": 20
}Public Endpoints(2)
/PublicHealth check - confirm API is running
Show example
curl -X GET "https://api.timehunter.pl/"
{
"status": "ok",
"version": "1.0.0"
}/api/app/latest-versionPublicGet latest mobile app version info
Show example
curl -X GET "https://api.timehunter.pl/api/app/latest-version"
{
"version": "1.0.0",
"downloadUrl": "https://...",
"releaseDate": "2026-02-12"
}