API Documentation

Complete REST API reference for TimeHunter — 111 endpoints

Base URLhttps://api.timehunter.pl

Getting 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.

LimiterWindowMax Requests
auth15 min20
register1 h5
qr1 min30
api1 min100
ai1 min10
schema5 min10
adminOp1 h5
locationTrail30 s1

Authentication(5)

POST/api/auth/register-companyPublic5/1 h

Register a new company with admin account and plan selection

Show example
cURL
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"}'
Request
{
  "companyName": "Moja Firma Sp. z o.o.",
  "nip": "1234567890",
  "email": "admin@mojafirma.pl",
  "password": "SecurePass123!",
  "adminName": "Jan Kowalski",
  "plan": "start",
  "countryCode": "PL"
}
Response
{
  "success": true,
  "message": "Firma zarejestrowana pomyślnie",
  "user": {
    "id": "uuid",
    "email": "admin@mojafirma.pl",
    "role": "admin"
  }
}
POST/api/auth/loginPublic20/15 min

Authenticate with email and password, receive JWT token

Show example
cURL
curl -X POST "https://api.timehunter.pl/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@mojafirma.pl","password":"SecurePass123!"}'
Request
{
  "email": "admin@mojafirma.pl",
  "password": "SecurePass123!"
}
Response
{
  "success": true,
  "user": {
    "userId": "uuid",
    "email": "admin@mojafirma.pl",
    "role": "admin",
    "companyId": "uuid"
  }
}
GET/api/auth/meJWT

Get current user profile and subscription info

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/auth/me" \
  -H "Authorization: Bearer <token>"
Response
{
  "user": {
    "id": "uuid",
    "email": "admin@mojafirma.pl",
    "full_name": "Jan Kowalski",
    "role": "admin"
  },
  "subscription": {
    "status": "trial",
    "trialEnd": "2026-03-01"
  }
}
POST/api/auth/logoutPublic

Invalidate session (clear HttpOnly cookie)

Show example
cURL
curl -X POST "https://api.timehunter.pl/api/auth/logout"
Response
{
  "success": true
}
POST/api/auth/change-passwordJWT

Change password for the authenticated user

Show example
cURL
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!"}'
Request
{
  "currentPassword": "OldPass123!",
  "newPassword": "NewPass456!"
}
Response
{
  "success": true,
  "message": "Hasło zmienione"
}

Work Sessions(8)

GET/api/work/sessionJWT

Get current active work session for the user

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/work/session" \
  -H "Authorization: Bearer <token>"
Response
{
  "session": {
    "id": "uuid",
    "start_time": "2026-02-15T08:00:00+01:00",
    "break_start": null,
    "end_time": null
  },
  "breakLimit": 30
}
POST/api/work/startJWT

Start a new work session with optional GPS location

Show example
cURL
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"}'
Request
{
  "latitude": 50.2649,
  "longitude": 19.0238,
  "workMode": "office"
}
Response
{
  "success": true,
  "session": {
    "id": "uuid",
    "start_time": "2026-02-15T08:00:00+01:00"
  }
}
POST/api/work/stopJWT

End the current work session

Show example
cURL
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}'
Request
{
  "latitude": 50.2649,
  "longitude": 19.0238
}
Response
{
  "success": true,
  "session": {
    "id": "uuid",
    "end_time": "2026-02-15T16:00:00+01:00",
    "total_hours": 8
  }
}
POST/api/work/break-startOptional

Start a break (supports QR token auth)

Show example
cURL
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"}'
Request
{
  "qrToken": "optional-qr-token"
}
Response
{
  "success": true,
  "breakStart": "2026-02-15T12:00:00+01:00"
}
POST/api/work/break-endOptional

End the current break (supports QR token auth)

Show example
cURL
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"}'
Request
{
  "qrToken": "optional-qr-token"
}
Response
{
  "success": true,
  "breakEnd": "2026-02-15T12:30:00+01:00"
}
GET/api/work/break-todayJWT

Get total break time for today

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/work/break-today" \
  -H "Authorization: Bearer <token>"
Response
{
  "totalBreakSeconds": 1800
}
GET/api/work/todayAPI Key / JWT

Get today's work time summary

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/work/today" \
  -H "Authorization: Bearer <token>"
Response
{
  "totalSeconds": 28800,
  "totalHours": "8.00"
}
POST/api/work/location-updateJWT

Send GPS location update during active session

Show example
cURL
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}'
Request
{
  "latitude": 50.2649,
  "longitude": 19.0238
}
Response
{
  "success": true
}

QR Code & Scanning(4)

GET/api/qr/:userIdJWT

Get QR code for a user (self or admin)

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/qr/:userId" \
  -H "Authorization: Bearer <token>"
Response
{
  "qrToken": "uuid-token",
  "qrCodeUrl": "data:image/png;base64,..."
}
POST/api/work/qr-scanQR Token30/1 min

Scan QR code to toggle work session (start/stop/break)

Show example
cURL
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}'
Request
{
  "qrToken": "uuid-token",
  "latitude": 50.2649,
  "longitude": 19.0238
}
Response
{
  "success": true,
  "action": "start",
  "session": {
    "id": "uuid"
  }
}
POST/api/work/qr-scan-statusQR Token30/1 min

Get current work status via QR token

Show example
cURL
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"}'
Request
{
  "qrToken": "uuid-token"
}
Response
{
  "isWorking": true,
  "onBreak": false,
  "sessionStart": "2026-02-15T08:00:00+01:00"
}
POST/api/work/photo-uploadQR Token30/1 min

Upload verification photo during QR registration

Show example
cURL
curl -X POST "https://api.timehunter.pl/api/work/photo-upload" \
  -H "Authorization: Bearer <token>"
Request
(multipart/form-data: qrToken, eventId, photo)
Response
{
  "success": true,
  "photoUrl": "https://..."
}

Attendance(3)

GET/api/attendanceJWT + Admin

Get attendance data for all employees (admin)

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/attendance" \
  -H "Authorization: Bearer <token>"
Request
GET /api/attendance?date=2026-02-15&employeeId=uuid
Response
{
  "attendance": [
    {
      "userId": "uuid",
      "fullName": "Jan Kowalski",
      "startTime": "08:00",
      "endTime": "16:00",
      "totalHours": "7.50",
      "breaks": 1800
    }
  ]
}
GET/api/employees/statusAPI Key / JWT

Get current working status of all employees

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/employees/status" \
  -H "Authorization: Bearer <token>"
Response
{
  "employees": [
    {
      "id": "uuid",
      "fullName": "Jan Kowalski",
      "isWorking": true,
      "onBreak": false,
      "startTime": "08:00"
    }
  ]
}
GET/api/late/todayJWT

Check if the user was late today

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/late/today" \
  -H "Authorization: Bearer <token>"
Response
{
  "isLate": false,
  "minutesLate": 0
}

Reports(6)

GET/api/report/dailyAPI Key / JWT

Get daily work report

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/report/daily" \
  -H "Authorization: Bearer <token>"
Request
GET /api/report/daily?date=2026-02-15
Response
{
  "date": "2026-02-15",
  "totalHours": "8.00",
  "sessions": []
}
GET/api/report/weeklyAPI Key / JWT

Get weekly work report

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/report/weekly" \
  -H "Authorization: Bearer <token>"
Response
{
  "weekStart": "2026-02-10",
  "weekEnd": "2026-02-16",
  "totalHours": "40.00"
}
GET/api/report/monthlyAPI Key / JWT

Get monthly work report

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/report/monthly" \
  -H "Authorization: Bearer <token>"
Request
GET /api/report/monthly?month=2026-02
Response
{
  "month": "2026-02",
  "totalHours": "160.00",
  "workDays": 20
}
GET/api/reports/periodJWT + Admin

Get report for a custom date range (admin)

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/reports/period" \
  -H "Authorization: Bearer <token>"
Request
GET /api/reports/period?from=2026-02-01&to=2026-02-28
Response
{
  "employees": [],
  "summary": {
    "totalHours": "320.00"
  }
}
GET/api/report/pdf-dataJWT

Get report data for PDF generation

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/report/pdf-data" \
  -H "Authorization: Bearer <token>"
Response
{
  "reportData": {}
}
POST/api/reports/monthly-pdfJWT + Admin

Generate monthly PDF report (admin)

Show example
cURL
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"]}'
Request
{
  "month": "2026-02",
  "employeeIds": [
    "uuid1",
    "uuid2"
  ]
}
Response
(PDF binary)

Leave Requests(5)

POST/api/leave/requestJWT

Submit a new leave request (vacation, sick leave, etc.)

Show example
cURL
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"}'
Request
{
  "leave_type": "vacation",
  "start_date": "2026-03-01",
  "end_date": "2026-03-05",
  "comment": "Urlop wypoczynkowy",
  "request_unit": "days"
}
Response
{
  "success": true,
  "request": {
    "id": "uuid",
    "status": "pending"
  }
}
GET/api/leave/balance/:userIdJWT

Get leave balance for a user

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/leave/balance/:userId" \
  -H "Authorization: Bearer <token>"
Response
{
  "balance": {
    "total_days": 26,
    "used_days": 5,
    "pending_days": 3,
    "remaining_days": 18
  }
}
PUT/api/leave/balance/:userIdJWT + Admin

Update leave balance (admin)

Show example
cURL
curl -X PUT "https://api.timehunter.pl/api/leave/balance/:userId" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"total_days":30}'
Request
{
  "total_days": 30
}
Response
{
  "success": true
}
GET/api/admin/leave-requestsJWT + Admin

List all leave requests (admin)

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/admin/leave-requests" \
  -H "Authorization: Bearer <token>"
Response
{
  "requests": [
    {
      "id": "uuid",
      "employee": "Jan Kowalski",
      "leave_type": "vacation",
      "status": "pending"
    }
  ]
}
POST/api/admin/leave/:actionJWT + Admin

Approve or reject a leave request (admin)

Show example
cURL
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"}'
Request
{
  "requestId": "uuid",
  "comment": "Zatwierdzono"
}
Response
{
  "success": true,
  "status": "approved"
}

Holidays(4)

GET/api/holidaysJWT

Get list of holidays for the company

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/holidays" \
  -H "Authorization: Bearer <token>"
Response
{
  "holidays": [
    {
      "id": 1,
      "name": "Nowy Rok",
      "date": "2026-01-01",
      "country_code": "PL"
    }
  ]
}
POST/api/admin/holidaysJWT + Admin

Create a custom holiday (admin)

Show example
cURL
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"}'
Request
{
  "name": "Dzień Firmy",
  "date": "2026-06-15"
}
Response
{
  "success": true,
  "holiday": {
    "id": 2,
    "name": "Dzień Firmy"
  }
}
PUT/api/admin/holidays/:idJWT + Admin

Update a holiday (admin)

Show example
cURL
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"}'
Request
{
  "name": "Dzień Firmy (zaktualizowany)",
  "date": "2026-06-16"
}
Response
{
  "success": true
}
DELETE/api/admin/holidays/:idJWT + Admin

Delete a holiday (admin)

Show example
cURL
curl -X DELETE "https://api.timehunter.pl/api/admin/holidays/:id" \
  -H "Authorization: Bearer <token>"
Response
{
  "success": true
}

Events(6)

GET/api/eventsJWT

Get events/tasks for a date

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/events" \
  -H "Authorization: Bearer <token>"
Request
GET /api/events?date=2026-02-15
Response
{
  "events": [
    {
      "id": 1,
      "title": "Spotkanie",
      "start": "09:00",
      "end": "10:00"
    }
  ]
}
POST/api/events/createJWT

Create a new event or task

Show example
cURL
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"}'
Request
{
  "title": "Spotkanie",
  "date": "2026-02-20",
  "start_time": "09:00",
  "end_time": "10:00"
}
Response
{
  "success": true,
  "event": {
    "id": 2
  }
}
PUT/api/events/:idJWT + Admin

Update an event (admin)

Show example
cURL
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"}'
Request
{
  "title": "Spotkanie (zmienione)",
  "end_time": "11:00"
}
Response
{
  "success": true
}
DELETE/api/events/:idJWT + Admin

Delete an event (admin)

Show example
cURL
curl -X DELETE "https://api.timehunter.pl/api/events/:id" \
  -H "Authorization: Bearer <token>"
Response
{
  "success": true
}
POST/api/events/bulk-activateJWT + Admin

Bulk activate events (admin)

Show example
cURL
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]}'
Request
{
  "ids": [
    1,
    2,
    3
  ]
}
Response
{
  "success": true,
  "count": 3
}
POST/api/events/bulk-deleteJWT + Admin

Bulk delete events (admin)

Show example
cURL
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]}'
Request
{
  "ids": [
    1,
    2,
    3
  ]
}
Response
{
  "success": true,
  "count": 3
}

Requests & Approvals(7)

GET/api/requestsJWT

Get user's requests or all requests (admin)

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/requests" \
  -H "Authorization: Bearer <token>"
Response
{
  "requests": [
    {
      "id": "uuid",
      "leave_type": "vacation",
      "status": "pending"
    }
  ]
}
POST/api/requestsJWT

Create a new request

Show example
cURL
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"}'
Request
{
  "employee_id": "uuid",
  "start_date": "2026-03-01",
  "end_date": "2026-03-05",
  "leave_type": "vacation",
  "comment": "Urlop"
}
Response
{
  "success": true,
  "request": {
    "id": "uuid"
  }
}
PUT/api/requests/:idJWT

Update request details

Show example
cURL
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"}'
Request
{
  "start_date": "2026-03-02",
  "end_date": "2026-03-06"
}
Response
{
  "success": true
}
PUT/api/requests/:id/statusJWT

Update request status (approve/reject)

Show example
cURL
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"}'
Request
{
  "status": "approved",
  "comment": "Zatwierdzono"
}
Response
{
  "success": true
}
DELETE/api/requests/:idJWT

Delete a request

Show example
cURL
curl -X DELETE "https://api.timehunter.pl/api/requests/:id" \
  -H "Authorization: Bearer <token>"
Response
{
  "success": true
}
POST/api/requests/bulk-approveJWT

Bulk approve requests

Show example
cURL
curl -X POST "https://api.timehunter.pl/api/requests/bulk-approve" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"ids":["uuid1","uuid2"]}'
Request
{
  "ids": [
    "uuid1",
    "uuid2"
  ]
}
Response
{
  "success": true,
  "count": 2
}
POST/api/requests/bulk-rejectJWT

Bulk reject requests

Show example
cURL
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"}'
Request
{
  "ids": [
    "uuid1",
    "uuid2"
  ],
  "comment": "Odrzucono"
}
Response
{
  "success": true,
  "count": 2
}

Schedules(5)

GET/api/schedulesAPI Key / JWT

Get work schedules

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/schedules" \
  -H "Authorization: Bearer <token>"
Request
GET /api/schedules?month=2026-02&userId=uuid
Response
{
  "schedules": [
    {
      "id": "uuid",
      "date": "2026-02-15",
      "start": "08:00",
      "end": "16:00"
    }
  ]
}
POST/api/schedulesJWT

Create a work schedule entry

Show example
cURL
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"}'
Request
{
  "userId": "uuid",
  "date": "2026-02-20",
  "start_time": "08:00",
  "end_time": "16:00"
}
Response
{
  "success": true,
  "schedule": {
    "id": "uuid"
  }
}
POST/api/schedules/bulkJWT

Bulk create schedule entries

Show example
cURL
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"}]}'
Request
{
  "schedules": [
    {
      "userId": "uuid",
      "date": "2026-02-20",
      "start_time": "08:00",
      "end_time": "16:00"
    }
  ]
}
Response
{
  "success": true,
  "count": 5
}
PUT/api/schedules/:idJWT

Update a schedule entry

Show example
cURL
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"}'
Request
{
  "start_time": "09:00",
  "end_time": "17:00"
}
Response
{
  "success": true
}
DELETE/api/schedules/:idJWT

Delete a schedule entry

Show example
cURL
curl -X DELETE "https://api.timehunter.pl/api/schedules/:id" \
  -H "Authorization: Bearer <token>"
Response
{
  "success": true
}

Employee Management(6)

GET/api/admin/usersJWT + Admin

List all employees in the company (admin)

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/admin/users" \
  -H "Authorization: Bearer <token>"
Response
{
  "users": [
    {
      "id": "uuid",
      "full_name": "Jan Kowalski",
      "email": "jan@firma.pl",
      "role": "employee"
    }
  ]
}
POST/api/admin/add-employeeJWT + Admin

Add a new employee (admin)

Show example
cURL
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}'
Request
{
  "fullName": "Anna Nowak",
  "email": "anna@firma.pl",
  "password": "TempPass123!",
  "role": "employee",
  "initialLeaveDays": 26
}
Response
{
  "success": true,
  "employee": {
    "id": "uuid",
    "email": "anna@firma.pl"
  }
}
PUT/api/admin/edit-employee/:idJWT + Admin

Edit employee details (admin)

Show example
cURL
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"}'
Request
{
  "fullName": "Anna Nowak-Kowalska",
  "role": "manager"
}
Response
{
  "success": true
}
PUT/api/admin/update-permissions/:idJWT + Admin

Update employee permissions (admin)

Show example
cURL
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}}'
Request
{
  "permissions": {
    "dashboard": true,
    "reports": true,
    "events": false
  }
}
Response
{
  "success": true
}
PUT/api/admin/archive-employee/:idJWT + Admin

Archive/deactivate an employee (admin)

Show example
cURL
curl -X PUT "https://api.timehunter.pl/api/admin/archive-employee/:id" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"archived":true}'
Request
{
  "archived": true
}
Response
{
  "success": true
}
GET/api/admin/user-timeJWT + Admin

Get user work time summary (admin)

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/admin/user-time" \
  -H "Authorization: Bearer <token>"
Request
GET /api/admin/user-time?date=2026-02-15
Response
{
  "users": [
    {
      "userId": "uuid",
      "fullName": "Jan Kowalski",
      "totalHours": "8.00",
      "isWorking": true
    }
  ]
}

Overtime(5)

GET/api/overtime/settingsJWT

Get overtime settings

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/overtime/settings" \
  -H "Authorization: Bearer <token>"
Response
{
  "dailyThreshold": 8,
  "weeklyThreshold": 40,
  "multiplier": 1.5
}
PUT/api/overtime/settingsJWT + Admin

Update overtime settings (admin)

Show example
cURL
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}'
Request
{
  "dailyThreshold": 8,
  "weeklyThreshold": 40,
  "multiplier": 1.5
}
Response
{
  "success": true
}
GET/api/overtime/recordsJWT

Get overtime records

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/overtime/records" \
  -H "Authorization: Bearer <token>"
Request
GET /api/overtime/records?month=2026-02
Response
{
  "records": [
    {
      "id": "uuid",
      "date": "2026-02-10",
      "hours": 2.5,
      "status": "pending"
    }
  ]
}
GET/api/overtime/summaryJWT

Get overtime summary

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/overtime/summary" \
  -H "Authorization: Bearer <token>"
Response
{
  "totalOvertimeHours": 15.5,
  "pendingHours": 5,
  "approvedHours": 10.5
}
POST/api/overtime/bulk-approveJWT + Admin

Bulk approve overtime records (admin)

Show example
cURL
curl -X POST "https://api.timehunter.pl/api/overtime/bulk-approve" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"ids":["uuid1","uuid2"]}'
Request
{
  "ids": [
    "uuid1",
    "uuid2"
  ]
}
Response
{
  "success": true,
  "count": 2
}

Work Groups(4)

GET/api/admin/work-groupsJWT + Admin

List all work groups (admin)

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/admin/work-groups" \
  -H "Authorization: Bearer <token>"
Response
{
  "groups": [
    {
      "id": "uuid",
      "name": "Produkcja",
      "membersCount": 12
    }
  ]
}
POST/api/admin/work-groupsJWT + Admin

Create a work group (admin)

Show example
cURL
curl -X POST "https://api.timehunter.pl/api/admin/work-groups" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Logistyka"}'
Request
{
  "name": "Logistyka"
}
Response
{
  "success": true,
  "group": {
    "id": "uuid",
    "name": "Logistyka"
  }
}
PUT/api/admin/work-groups/:idJWT + Admin

Update a work group (admin)

Show example
cURL
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"}'
Request
{
  "name": "Logistyka & Transport"
}
Response
{
  "success": true
}
DELETE/api/admin/work-groups/:idJWT + Admin

Delete a work group (admin)

Show example
cURL
curl -X DELETE "https://api.timehunter.pl/api/admin/work-groups/:id" \
  -H "Authorization: Bearer <token>"
Response
{
  "success": true
}

Announcements(4)

GET/api/announcementsJWT

Get announcements

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/announcements" \
  -H "Authorization: Bearer <token>"
Response
{
  "announcements": [
    {
      "id": "uuid",
      "title": "Nowy regulamin",
      "content": "...",
      "createdAt": "2026-02-15"
    }
  ]
}
POST/api/announcementsJWT + Admin

Create an announcement (admin)

Show example
cURL
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"}'
Request
{
  "title": "Zmiana godzin pracy",
  "content": "Od marca biuro czynne 7-15"
}
Response
{
  "success": true,
  "announcement": {
    "id": "uuid"
  }
}
POST/api/announcements/:id/readJWT

Mark an announcement as read

Show example
cURL
curl -X POST "https://api.timehunter.pl/api/announcements/:id/read" \
  -H "Authorization: Bearer <token>"
Response
{
  "success": true
}
GET/api/announcements/unread-countJWT

Get unread announcements count

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/announcements/unread-count" \
  -H "Authorization: Bearer <token>"
Response
{
  "count": 3
}

Company Management(7)

POST/api/company/updateJWT + Admin

Update company settings (admin)

Show example
cURL
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."}'
Request
{
  "name": "Nowa Nazwa Sp. z o.o."
}
Response
{
  "success": true
}
GET/api/company/detailsJWT + Admin

Get company details (admin)

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/company/details" \
  -H "Authorization: Bearer <token>"
Response
{
  "company": {
    "id": "uuid",
    "name": "Moja Firma",
    "plan": "start"
  }
}
GET/api/company/brandingJWT

Get company branding settings

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/company/branding" \
  -H "Authorization: Bearer <token>"
Response
{
  "logoUrl": "https://...",
  "primaryColor": "#2563eb"
}
PUT/api/company/brandingJWT + Admin

Update company branding (admin)

Show example
cURL
curl -X PUT "https://api.timehunter.pl/api/company/branding" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"primaryColor":"#059669"}'
Request
{
  "primaryColor": "#059669"
}
Response
{
  "success": true
}
POST/api/company/logoJWT + Admin

Upload company logo (admin)

Show example
cURL
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"}'
Request
{
  "logo_url": "https://example.com/logo.png"
}
Response
{
  "success": true
}
GET/api/company/locationJWT + Admin

Get company primary location (admin)

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/company/location" \
  -H "Authorization: Bearer <token>"
Response
{
  "location": {
    "latitude": 50.2649,
    "longitude": 19.0238,
    "radius": 200
  }
}
POST/api/company/locationJWT + Admin

Set company primary location (admin)

Show example
cURL
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}'
Request
{
  "latitude": 50.2649,
  "longitude": 19.0238,
  "radius": 200
}
Response
{
  "success": true
}

Subscriptions & Plans(3)

GET/api/subscription/statusJWT

Get current subscription status

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/subscription/status" \
  -H "Authorization: Bearer <token>"
Response
{
  "status": "trial",
  "planId": "uuid",
  "trialEnd": "2026-03-01",
  "paymentReference": "TH-12345"
}
GET/api/subscription/payment-infoJWT

Get payment information for subscription

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/subscription/payment-info" \
  -H "Authorization: Bearer <token>"
Response
{
  "bankName": "mBank",
  "iban": "PL...",
  "reference": "TH-12345",
  "amount": "32.50 PLN"
}
GET/api/plans/publicPublic

Get public pricing plans

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/plans/public"
Response
{
  "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)

GET/api/addonsJWT

Get available add-ons

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/addons" \
  -H "Authorization: Bearer <token>"
Response
{
  "addons": [
    {
      "id": "uuid",
      "slug": "photo_registration",
      "name": "Rejestracja zdjęciem",
      "price": 1
    }
  ]
}
POST/api/addons/:id/activateJWT + Admin

Activate an add-on (admin)

Show example
cURL
curl -X POST "https://api.timehunter.pl/api/addons/:id/activate" \
  -H "Authorization: Bearer <token>"
Response
{
  "success": true
}
POST/api/addons/:id/deactivateJWT + Admin

Deactivate an add-on (admin)

Show example
cURL
curl -X POST "https://api.timehunter.pl/api/addons/:id/deactivate" \
  -H "Authorization: Bearer <token>"
Response
{
  "success": true
}
GET/api/company/addonsJWT

Get company's active add-ons

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/company/addons" \
  -H "Authorization: Bearer <token>"
Response
{
  "activeAddons": [
    "photo_registration",
    "location_basic"
  ]
}

API Keys(3)

GET/api/api-keysJWT + Admin

List API keys (admin)

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/api-keys" \
  -H "Authorization: Bearer <token>"
Response
{
  "keys": [
    {
      "id": "uuid",
      "name": "Integration Key",
      "prefix": "th_live_ab12",
      "created_at": "2026-02-01"
    }
  ]
}
POST/api/api-keysJWT + Admin

Create a new API key (admin)

Show example
cURL
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}}'
Request
{
  "name": "ERP Integration",
  "permissions": {
    "read": true,
    "write": false
  }
}
Response
{
  "success": true,
  "key": "th_live_abc123...",
  "prefix": "th_live_ab12"
}
DELETE/api/api-keys/:idJWT + Admin

Delete an API key (admin)

Show example
cURL
curl -X DELETE "https://api.timehunter.pl/api/api-keys/:id" \
  -H "Authorization: Bearer <token>"
Response
{
  "success": true
}

Email Reports(4)

GET/api/email-reportsJWT + Admin

List scheduled email reports (admin)

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/email-reports" \
  -H "Authorization: Bearer <token>"
Response
{
  "reports": [
    {
      "id": "uuid",
      "title": "Raport tygodniowy",
      "schedule": "weekly",
      "recipients": [
        "admin@firma.pl"
      ]
    }
  ]
}
POST/api/email-reportsJWT + Admin

Create a scheduled email report (admin)

Show example
cURL
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"]}'
Request
{
  "title": "Raport dzienny",
  "schedule": "daily",
  "recipients": [
    "admin@firma.pl"
  ]
}
Response
{
  "success": true,
  "report": {
    "id": "uuid"
  }
}
PUT/api/email-reports/:idJWT + Admin

Update an email report (admin)

Show example
cURL
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"}'
Request
{
  "title": "Raport dzienny (v2)",
  "schedule": "daily"
}
Response
{
  "success": true
}
DELETE/api/email-reports/:idJWT + Admin

Delete an email report (admin)

Show example
cURL
curl -X DELETE "https://api.timehunter.pl/api/email-reports/:id" \
  -H "Authorization: Bearer <token>"
Response
{
  "success": true
}

AI Assistant(2)

POST/api/ai/chat-claudeJWT10/1 min

Chat with AI assistant about work data

Show example
cURL
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"}'
Request
{
  "message": "Ile godzin przepracowałem w tym tygodniu?",
  "context": "work_time"
}
Response
{
  "reply": "W tym tygodniu przepracowałeś 32.5 godziny..."
}
POST/api/ai/analyze-dbJWT + Admin10/1 min

AI-powered database analysis (admin)

Show example
cURL
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"}'
Request
{
  "query": "Pokaż pracowników z nadgodzinami w lutym"
}
Response
{
  "analysis": "...",
  "data": []
}

Webhooks(3)

GET/api/integrations/webhookJWT + Admin

Get webhook settings (admin)

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/integrations/webhook" \
  -H "Authorization: Bearer <token>"
Response
{
  "webhookUrl": "https://...",
  "events": [
    "work.start",
    "work.stop"
  ]
}
PUT/api/integrations/webhookJWT + Admin

Update webhook settings (admin)

Show example
cURL
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"]}'
Request
{
  "webhookUrl": "https://example.com/hook",
  "events": [
    "work.start",
    "work.stop",
    "leave.request"
  ]
}
Response
{
  "success": true
}
POST/api/integrations/webhook/testJWT + Admin

Send a test webhook (admin)

Show example
cURL
curl -X POST "https://api.timehunter.pl/api/integrations/webhook/test" \
  -H "Authorization: Bearer <token>"
Response
{
  "success": true,
  "statusCode": 200
}

Dashboard Layouts(2)

GET/api/dashboard/layoutJWT

Get user's custom dashboard layout

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/dashboard/layout" \
  -H "Authorization: Bearer <token>"
Response
{
  "layout": {
    "widgets": [
      "workStatus",
      "breakTimer",
      "leaveBalance"
    ]
  }
}
POST/api/dashboard/layoutJWT

Save dashboard layout

Show example
cURL
curl -X POST "https://api.timehunter.pl/api/dashboard/layout" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"widgets":["workStatus","breakTimer","quickTile"]}'
Request
{
  "widgets": [
    "workStatus",
    "breakTimer",
    "quickTile"
  ]
}
Response
{
  "success": true
}

Locations(2)

GET/api/admin/locationsJWT + Admin

Get all registered work locations (admin)

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/admin/locations" \
  -H "Authorization: Bearer <token>"
Response
{
  "locations": [
    {
      "id": "uuid",
      "name": "Biuro",
      "latitude": 50.2649,
      "longitude": 19.0238,
      "radius": 200
    }
  ]
}
GET/api/admin/location-trailJWT + Admin

Get GPS location trail for an employee (admin)

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/admin/location-trail" \
  -H "Authorization: Bearer <token>"
Request
GET /api/admin/location-trail?userId=uuid&date=2026-02-15
Response
{
  "trail": [
    {
      "lat": 50.2649,
      "lng": 19.0238,
      "timestamp": "08:05"
    }
  ]
}

Hour Presets(2)

GET/api/hour-presetsJWT

Get hour presets for quick time entry

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/hour-presets" \
  -H "Authorization: Bearer <token>"
Response
{
  "presets": [
    {
      "id": "uuid",
      "name": "8h standard",
      "startTime": "08:00",
      "endTime": "16:00"
    }
  ]
}
POST/api/hour-presetsJWT + Admin

Create an hour preset (admin)

Show example
cURL
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"}'
Request
{
  "name": "Nocna zmiana",
  "startTime": "22:00",
  "endTime": "06:00"
}
Response
{
  "success": true,
  "preset": {
    "id": "uuid"
  }
}

Approval Workflows(2)

GET/api/approval-workflowsJWT + Admin

List approval workflows (admin)

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/approval-workflows" \
  -H "Authorization: Bearer <token>"
Response
{
  "workflows": [
    {
      "id": "uuid",
      "name": "Urlopy",
      "steps": [
        "manager",
        "admin"
      ]
    }
  ]
}
POST/api/approval-workflowsJWT + Admin

Create an approval workflow (admin)

Show example
cURL
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"}]}'
Request
{
  "name": "Nadgodziny",
  "steps": [
    {
      "role": "manager",
      "action": "approve"
    }
  ]
}
Response
{
  "success": true,
  "workflow": {
    "id": "uuid"
  }
}

Audit Logs(1)

GET/api/audit-logsJWT + Admin

View audit logs (admin)

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/audit-logs" \
  -H "Authorization: Bearer <token>"
Request
GET /api/audit-logs?page=1&limit=50
Response
{
  "logs": [
    {
      "id": "uuid",
      "action": "employee.created",
      "userId": "uuid",
      "timestamp": "2026-02-15T10:30:00"
    }
  ],
  "total": 150
}

Notifications(1)

GET/api/notificationsJWT

Get user notifications

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/notifications" \
  -H "Authorization: Bearer <token>"
Response
{
  "notifications": [
    {
      "id": "uuid",
      "type": "leave_approved",
      "message": "Twój urlop został zatwierdzony",
      "read": false
    }
  ]
}

Auto-fill(1)

POST/api/work-sessions/auto-fillJWT + Admin

Auto-fill missing work sessions for a month (admin)

Show example
cURL
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"}'
Request
{
  "userId": "uuid",
  "month": "2026-02",
  "startTime": "08:00",
  "endTime": "16:00"
}
Response
{
  "success": true,
  "sessionsCreated": 20
}

Public Endpoints(2)

GET/Public

Health check - confirm API is running

Show example
cURL
curl -X GET "https://api.timehunter.pl/"
Response
{
  "status": "ok",
  "version": "1.0.0"
}
GET/api/app/latest-versionPublic

Get latest mobile app version info

Show example
cURL
curl -X GET "https://api.timehunter.pl/api/app/latest-version"
Response
{
  "version": "1.0.0",
  "downloadUrl": "https://...",
  "releaseDate": "2026-02-12"
}

TimeHunter API v1.0 © 2026

This website uses cookies

We use cookies to ensure proper functioning of the service, analyze traffic and personalize content. Learn more in our Privacy Policy