{"openapi":"3.1.0","info":{"title":"Taktovka API","version":"1.0.0","description":"Read-only access to a company's own data in Taktovka: locations, people, the published roster, attendance, hours, absences and leave balances.\n\nSend the key as `Authorization: Bearer tk_…`; the owner creates keys in the app (Firma → API a integrácie). Never put a key in the URL or in a browser: CORS is off.\n\nJSON fields are snake_case; `date` is the local date of the location (YYYY-MM-DD), `*_local` its wall-clock time (HH:MM), instants are ISO 8601 with an offset, minutes are integers.\n\nLists answer `{ \"data\": [...], \"next_cursor\": null }`, one object `{ \"data\": {...} }`, errors `{ \"error\": { \"code\", \"message\", \"status\", \"request_id\" } }`.\n\nRate limit: 10 requests a second per key (burst 30), 20 per company; see the RateLimit-* headers.\n\nv1 never changes incompatibly; new fields may be added. Something incompatible would be /v2."},"servers":[{"url":"https://api.taktovka.com/v1"}],"tags":[{"name":"meta","description":"The API itself and the key"},{"name":"company","description":"Locations and positions"},{"name":"people","description":"The roster"},{"name":"schedules","description":"The published roster: weeks, versions, shifts"},{"name":"attendance","description":"Clocked time and hours of a month"},{"name":"absences","description":"Absences and leave balances"}],"security":[{"bearer":[]}],"paths":{"/":{"get":{"operationId":"getIndex","summary":"API index","description":"Where the documentation and the OpenAPI document live. Answers without a key.","tags":["meta"],"x-scopes":[],"security":[],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Index"}},"required":["data"],"additionalProperties":false},"example":{"data":{"api":"taktovka","version":"v1","docs":"https://taktovka.com/integracie","openapi":"https://api.taktovka.com/openapi.json"}}}}},"429":{"description":"rate_limited (with retry_after and a Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me":{"get":{"operationId":"getMe","summary":"The company and the key","description":"Which company this key reads, the scopes it carries and the rate limit it is held to. Any live key may call it.","tags":["meta"],"x-scopes":[],"security":[{"bearer":[]}],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Me"}},"required":["data"],"additionalProperties":false},"example":{"data":{"company":{"id":"5b0f2c1e-8d4a-4c7e-9a1b-2f3d4e5a6b7c","name":"Kaviareň pri fontáne","country":"SK","currency":"EUR","locale":"sk","tz":"Europe/Bratislava","plan":"kaviaren"},"key":{"id":"6e5d4c3b-2a19-4807-9f6e-5d4c3b2a1908","name":"Účtovníčka","scopes":["company:read","people:read","schedules:read","attendance:read"],"created_at":"2026-09-24T09:30:00.000Z","expires_at":null},"rate_limit":{"per_second":10,"burst":30}}}}}},"400":{"description":"key_in_query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthenticated, invalid_key, key_revoked or key_expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope (with required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (with retry_after and a Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/locations":{"get":{"operationId":"getLocations","summary":"Locations","description":"The company's places (prevádzky) with their time zone, whether the QR door scan is on and the averaging period of an uneven working week. Paged by id: `next_cursor` is null on the last page, otherwise pass it back as `cursor`.","tags":["company"],"x-scopes":["company:read"],"security":[{"bearer":[]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"Rows per page, 1–500","schema":{"default":200,"type":"integer","minimum":1,"maximum":500}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` of the previous page","schema":{"type":"string","pattern":"^[\\w-]{1,64}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Location"}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false},"example":{"data":[{"id":"0c8e6a42-1f3b-4d5e-8a9b-7c6d5e4f3a2b","name":"Kaviareň Hlavná","tz":"Europe/Bratislava","address":"Hlavná 12, Košice","active":true,"attendance_enabled":true,"work_time":null}],"next_cursor":null}}}},"400":{"description":"validation_failed, range_too_long or key_in_query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthenticated, invalid_key, key_revoked or key_expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope (with required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (with retry_after and a Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/positions":{"get":{"operationId":"getPositions","summary":"Positions","description":"Roles shifts are planned for (barista, kitchen, floor). Paged by id: `next_cursor` is null on the last page, otherwise pass it back as `cursor`.","tags":["company"],"x-scopes":["company:read"],"security":[{"bearer":[]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"Rows per page, 1–500","schema":{"default":200,"type":"integer","minimum":1,"maximum":500}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` of the previous page","schema":{"type":"string","pattern":"^[\\w-]{1,64}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Position"}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false},"example":{"data":[{"id":"9e1d2c3b-4a5f-4e6d-8c7b-1a2b3c4d5e6f","name":"Barista","color":"#b45309","sort_order":0,"active":true}],"next_cursor":null}}}},"400":{"description":"validation_failed, range_too_long or key_in_query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthenticated, invalid_key, key_revoked or key_expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope (with required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (with retry_after and a Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/employees":{"get":{"operationId":"getEmployees","summary":"People","description":"Roster cards: name, contract, agreed weekly hours, home location and positions. `email` and `phone` are in the answer only for a key with people:contact. Hourly rates, birth dates and material liability are never sent. Paged by id: `next_cursor` is null on the last page, otherwise pass it back as `cursor`.","tags":["people"],"x-scopes":["people:read"],"x-optional-scopes":["people:contact"],"security":[{"bearer":[]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"Rows per page, 1–500","schema":{"default":200,"type":"integer","minimum":1,"maximum":500}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` of the previous page","schema":{"type":"string","pattern":"^[\\w-]{1,64}$"}},{"name":"active","in":"query","required":false,"description":"Active cards (default), former ones, or all","schema":{"default":"true","type":"string","enum":["true","false","all"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Employee"}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false},"example":{"data":[{"id":"3f2e1d0c-9b8a-4765-8432-10fedcba9876","first_name":"Eva","last_name":"Nováková","active":true,"contract_type":"TPP","max_hours_week":40,"home_location_id":"0c8e6a42-1f3b-4d5e-8a9b-7c6d5e4f3a2b","position_ids":["9e1d2c3b-4a5f-4e6d-8c7b-1a2b3c4d5e6f"],"created_at":"2026-03-02T08:15:00.000Z","updated_at":"2026-09-01T10:00:00.000Z"}],"next_cursor":null}}}},"400":{"description":"validation_failed, range_too_long or key_in_query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthenticated, invalid_key, key_revoked or key_expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope (with required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (with retry_after and a Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/employees/{id}":{"get":{"operationId":"getEmployee","summary":"One person","description":"One roster card, active or not; `email` and `phone` only with people:contact. A person of another company answers 404, like one that does not exist.","tags":["people"],"x-scopes":["people:read"],"x-optional-scopes":["people:contact"],"security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Employee"}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"3f2e1d0c-9b8a-4765-8432-10fedcba9876","first_name":"Eva","last_name":"Nováková","active":true,"contract_type":"TPP","max_hours_week":40,"home_location_id":"0c8e6a42-1f3b-4d5e-8a9b-7c6d5e4f3a2b","position_ids":["9e1d2c3b-4a5f-4e6d-8c7b-1a2b3c4d5e6f"],"email":"eva.novakova@example.com","phone":"+421 900 123 456","created_at":"2026-03-02T08:15:00.000Z","updated_at":"2026-09-01T10:00:00.000Z"}}}}},"400":{"description":"validation_failed, range_too_long or key_in_query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthenticated, invalid_key, key_revoked or key_expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope (with required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: no such object in this company","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (with retry_after and a Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/schedules":{"get":{"operationId":"getSchedules","summary":"Published weeks","description":"Weeks (planning periods) touching the range that have been published, each at its latest version. A week that was never published is not listed. `from` and `to` at most 366 days apart; `next_cursor` is always null.","tags":["schedules"],"x-scopes":["schedules:read"],"security":[{"bearer":[]}],"parameters":[{"name":"from","in":"query","required":true,"description":"First day, YYYY-MM-DD, included; years 2000–2100","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":true,"description":"Last day, YYYY-MM-DD, included; years 2000–2100","schema":{"type":"string","format":"date"}},{"name":"location","in":"query","required":false,"description":"Only this location","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Schedule"}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false},"example":{"data":[{"schedule_id":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","location_id":"0c8e6a42-1f3b-4d5e-8a9b-7c6d5e4f3a2b","period_start":"2026-10-19","period_end":"2026-10-25","version":2,"published_at":"2026-10-09T14:12:05.000Z","sha256":"4f1a0c7e9b2d3a6f8e5c1b0d9a7f6e4c3b2a1908f7e6d5c4b3a291807f6e5d4c"}],"next_cursor":null}}}},"400":{"description":"validation_failed, range_too_long or key_in_query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthenticated, invalid_key, key_revoked or key_expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope (with required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (with retry_after and a Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/schedules/{schedule_id}":{"get":{"operationId":"getSchedule","summary":"One published week with its shifts","description":"The week as it was announced to people: the latest published version, or any earlier one with `version`. Versions never change once published. Changes the manager has not published yet are never in it.","tags":["schedules"],"x-scopes":["schedules:read"],"security":[{"bearer":[]}],"parameters":[{"name":"schedule_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"version","in":"query","required":false,"description":"A past version; the latest published one when left out","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ScheduleDetail"}},"required":["data"],"additionalProperties":false},"example":{"data":{"schedule_id":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","location_id":"0c8e6a42-1f3b-4d5e-8a9b-7c6d5e4f3a2b","period_start":"2026-10-19","period_end":"2026-10-25","version":2,"published_at":"2026-10-09T14:12:05.000Z","sha256":"4f1a0c7e9b2d3a6f8e5c1b0d9a7f6e4c3b2a1908f7e6d5c4b3a291807f6e5d4c","shifts":[{"id":"7d6c5b4a-3f2e-4d1c-8b0a-9f8e7d6c5b4a","schedule_id":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","version":2,"location_id":"0c8e6a42-1f3b-4d5e-8a9b-7c6d5e4f3a2b","position_id":"9e1d2c3b-4a5f-4e6d-8c7b-1a2b3c4d5e6f","date":"2026-10-24","start_local":"22:00","end_local":"06:00","tz":"Europe/Bratislava","starts_at":"2026-10-24T22:00:00+02:00","ends_at":"2026-10-25T06:00:00+01:00","break_min":30,"minutes":540,"paid_minutes":510,"headcount":1,"assignments":[{"employee_id":"3f2e1d0c-9b8a-4765-8432-10fedcba9876","state":"confirmed"}]}]}}}}},"400":{"description":"validation_failed, range_too_long or key_in_query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthenticated, invalid_key, key_revoked or key_expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope (with required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: no such object in this company","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (with retry_after and a Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/shifts":{"get":{"operationId":"getShifts","summary":"Published shifts","description":"Shifts starting in the range, from the latest published version of each week. With `employee`, the shifts the person works (a seat they gave back is not theirs). `from` and `to` are local dates, both included, at most 93 days apart; `next_cursor` is always null.","tags":["schedules"],"x-scopes":["schedules:read"],"security":[{"bearer":[]}],"parameters":[{"name":"from","in":"query","required":true,"description":"First day, YYYY-MM-DD, included; years 2000–2100","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":true,"description":"Last day, YYYY-MM-DD, included; years 2000–2100","schema":{"type":"string","format":"date"}},{"name":"location","in":"query","required":false,"description":"Only this location","schema":{"type":"string","format":"uuid"}},{"name":"employee","in":"query","required":false,"description":"Only this person","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Shift"}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false},"example":{"data":[{"id":"7d6c5b4a-3f2e-4d1c-8b0a-9f8e7d6c5b4a","schedule_id":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","version":2,"location_id":"0c8e6a42-1f3b-4d5e-8a9b-7c6d5e4f3a2b","position_id":"9e1d2c3b-4a5f-4e6d-8c7b-1a2b3c4d5e6f","date":"2026-10-24","start_local":"22:00","end_local":"06:00","tz":"Europe/Bratislava","starts_at":"2026-10-24T22:00:00+02:00","ends_at":"2026-10-25T06:00:00+01:00","break_min":30,"minutes":540,"paid_minutes":510,"headcount":1,"assignments":[{"employee_id":"3f2e1d0c-9b8a-4765-8432-10fedcba9876","state":"confirmed"}]}],"next_cursor":null}}}},"400":{"description":"validation_failed, range_too_long or key_in_query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthenticated, invalid_key, key_revoked or key_expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope (with required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (with retry_after and a Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/hours":{"get":{"operationId":"getHours","summary":"Hours of a month","description":"Per person: planned minutes from the published roster, counted minutes from attendance, the working-time fund of an employment contract and the person's own confirmation of the month. The part of the fund that depends on absences is filled only for a key that also has absences:read. `next_cursor` is always null. Counts as 5 requests against the rate limit. Runs one at a time per company; a second call while one is running answers 429 with retry_after.","tags":["attendance"],"x-scopes":["schedules:read","attendance:read"],"x-optional-scopes":["absences:read"],"x-rate-cost":5,"x-heavy":true,"security":[{"bearer":[]}],"parameters":[{"name":"month","in":"query","required":true,"description":"Calendar month, YYYY-MM, years 2000–2100","schema":{"type":"string","pattern":"^(20\\d\\d|2100)-(0[1-9]|1[0-2])$"}},{"name":"employee","in":"query","required":false,"description":"Only this person","schema":{"type":"string","format":"uuid"}},{"name":"location","in":"query","required":false,"description":"Only the plan and the counted time of this location; the fund and the signature stay the person's whole month","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Hours"}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false},"example":{"data":[{"employee_id":"3f2e1d0c-9b8a-4765-8432-10fedcba9876","month":"2026-10","planned_minutes":10620,"paid_planned_minutes":9990,"counted_minutes":9870,"fund":{"weekly_hours":40,"fund_minutes":10560,"holiday_minutes":0,"absence_minutes":960,"target_minutes":9600},"confirmed":{"confirmed_at":"2026-11-02T07:41:10.000Z","counted_minutes":9870,"stale":false},"meals":{"count":20,"second":1,"absence_days":2,"source":"both","form":"choice","choice":"allowance"}}],"next_cursor":null}}}},"400":{"description":"validation_failed, range_too_long or key_in_query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthenticated, invalid_key, key_revoked or key_expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope (with required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (with retry_after and a Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/time-entries":{"get":{"operationId":"getTimeEntries","summary":"Clock-in and clock-out","description":"Attendance records whose clock-in falls on a day of the range on the location's clock, exactly as recorded; `corrected` marks a row a manager entered or changed. `from` and `to` are local dates, both included, at most 93 days apart; `next_cursor` is always null.","tags":["attendance"],"x-scopes":["attendance:read"],"security":[{"bearer":[]}],"parameters":[{"name":"from","in":"query","required":true,"description":"First day, YYYY-MM-DD, included; years 2000–2100","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":true,"description":"Last day, YYYY-MM-DD, included; years 2000–2100","schema":{"type":"string","format":"date"}},{"name":"employee","in":"query","required":false,"description":"Only this person","schema":{"type":"string","format":"uuid"}},{"name":"location","in":"query","required":false,"description":"Only this location","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TimeEntry"}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false},"example":{"data":[{"id":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","employee_id":"3f2e1d0c-9b8a-4765-8432-10fedcba9876","location_id":"0c8e6a42-1f3b-4d5e-8a9b-7c6d5e4f3a2b","shift_id":"7d6c5b4a-3f2e-4d1c-8b0a-9f8e7d6c5b4a","clock_in":"2026-10-24T21:56:00+02:00","clock_out":"2026-10-25T06:04:00+01:00","source":"qr","offline_in":false,"offline_out":false,"corrected":false,"note":null}],"next_cursor":null}}}},"400":{"description":"validation_failed, range_too_long or key_in_query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthenticated, invalid_key, key_revoked or key_expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope (with required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (with retry_after and a Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/absences":{"get":{"operationId":"getAbsences","summary":"Absences","description":"Leave, sick notes and other absences touching the range. Without absences:kinds a sick note, OČR or other absence reads `absence` and has no note, because the kind is health data; with it the real kind and the note are sent and the answer is written to the company's audit log. `from` and `to` are local dates, both included, at most 93 days apart; `next_cursor` is always null.","tags":["absences"],"x-scopes":["absences:read"],"x-optional-scopes":["absences:kinds"],"security":[{"bearer":[]}],"parameters":[{"name":"from","in":"query","required":true,"description":"First day, YYYY-MM-DD, included; years 2000–2100","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":true,"description":"Last day, YYYY-MM-DD, included; years 2000–2100","schema":{"type":"string","format":"date"}},{"name":"employee","in":"query","required":false,"description":"Only this person","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","required":false,"description":"Only requests in this state","schema":{"type":"string","enum":["requested","approved","rejected"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Absence"}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false},"example":{"data":[{"id":"8a9b0c1d-2e3f-4a5b-8c6d-7e8f9a0b1c2d","employee_id":"3f2e1d0c-9b8a-4765-8432-10fedcba9876","kind":"dovolenka","date_from":"2026-10-28","date_to":"2026-10-29","status":"approved","note":null,"created_at":"2026-10-01T12:00:00.000Z","approved_at":"2026-10-01T16:20:00.000Z"}],"next_cursor":null}}}},"400":{"description":"validation_failed, range_too_long or key_in_query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthenticated, invalid_key, key_revoked or key_expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope (with required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (with retry_after and a Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leave-balances":{"get":{"operationId":"getLeaveBalances","summary":"Leave balances","description":"Annual leave of a year per person: the entitlement and what was carried over as the employer entered them, what approved and waiting requests use, and what is left. Working days in SK, hours in CZ. People without an entitlement for the year are not listed. `next_cursor` is always null.","tags":["absences"],"x-scopes":["leave:read"],"security":[{"bearer":[]}],"parameters":[{"name":"year","in":"query","required":false,"description":"Calendar year; the company's current year when left out","schema":{"type":"integer","minimum":2000,"maximum":2100}},{"name":"employee","in":"query","required":false,"description":"Only this person","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LeaveBalance"}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false},"example":{"data":[{"employee_id":"3f2e1d0c-9b8a-4765-8432-10fedcba9876","year":2026,"unit":"day","entitled":25,"carried_over":3,"used":12,"pending":2,"remaining":16}],"next_cursor":null}}}},"400":{"description":"validation_failed, range_too_long or key_in_query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthenticated, invalid_key, key_revoked or key_expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope (with required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (with retry_after and a Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"A company key, tk_ followed by 43 characters"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthenticated","invalid_key","key_revoked","key_expired","insufficient_scope","module_off","validation_failed","range_too_long","key_in_query","not_found","method_not_allowed","rate_limited","server_error"]},"message":{"type":"string"},"status":{"type":"integer"},"request_id":{"type":"string"},"required_scope":{"type":"string","enum":["company:read","people:read","people:contact","schedules:read","attendance:read","absences:read","absences:kinds","leave:read"]},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}},"required":["path","message"],"additionalProperties":false}},"retry_after":{"type":"integer"},"max_days":{"type":"integer"},"module":{"type":"string"}},"required":["code","message","status","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"Index":{"type":"object","properties":{"api":{"type":"string","const":"taktovka"},"version":{"type":"string","const":"v1"},"docs":{"type":"string","format":"uri"},"openapi":{"type":"string","format":"uri"}},"required":["api","version","docs","openapi"],"additionalProperties":false},"Me":{"type":"object","properties":{"company":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"country":{"type":"string","enum":["SK","CZ"]},"currency":{"type":"string","enum":["EUR","CZK"]},"locale":{"type":"string"},"tz":{"type":"string","description":"IANA time zone of the company"},"plan":{"type":"string","enum":["free","kaviaren","restauracia","siet","enterprise"]}},"required":["id","name","country","currency","locale","tz","plan"],"additionalProperties":false},"key":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["company:read","people:read","people:contact","schedules:read","attendance:read","absences:read","absences:kinds","leave:read"]}},"created_at":{"type":"string","format":"date-time","description":"ISO 8601 instant"},"expires_at":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 instant"},{"type":"null"}]}},"required":["id","name","scopes","created_at","expires_at"],"additionalProperties":false},"rate_limit":{"type":"object","properties":{"per_second":{"type":"integer"},"burst":{"type":"integer"}},"required":["per_second","burst"],"additionalProperties":false}},"required":["company","key","rate_limit"],"additionalProperties":false},"Location":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"tz":{"type":"string","description":"IANA time zone the location plans and counts in"},"address":{"type":["string","null"]},"active":{"type":"boolean"},"attendance_enabled":{"type":"boolean","description":"The QR door scan is on here"},"work_time":{"anyOf":[{"type":"object","properties":{"distribution":{"type":"string","enum":["even","uneven"]},"weekly_norm_minutes":{"type":"integer","description":"The standard week the average is held to, e.g. 2400 = 40 h"},"averaging_start":{"anyOf":[{"type":"string","format":"date","description":"Local date of the location, YYYY-MM-DD"},{"type":"null"}],"description":"First day of the first averaging period"},"averaging_length":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Length of one averaging period: months in SK, weeks in CZ"}},"required":["distribution","weekly_norm_minutes","averaging_start","averaging_length"],"additionalProperties":false},{"type":"null"}],"description":"Uneven distribution of working time with an averaging period; null when the week is even"}},"required":["id","name","tz","address","active","attendance_enabled","work_time"],"additionalProperties":false},"Position":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"color":{"type":["string","null"]},"sort_order":{"type":"integer"},"active":{"type":"boolean"}},"required":["id","name","color","sort_order","active"],"additionalProperties":false},"Employee":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string"},"last_name":{"type":"string"},"active":{"type":"boolean"},"contract_type":{"type":"string","enum":["TPP","DoPC","DoBPS","DoVP","HPP","DPP","DPC","DoPCS"],"description":"SK: TPP, DoPC, DoBPS, DoVP, DoPCS; CZ: HPP, DPP, DPC"},"max_hours_week":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Agreed weekly hours"},"home_location_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"position_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"email":{"description":"Only with the people:contact scope","type":["string","null"]},"phone":{"description":"Only with the people:contact scope","type":["string","null"]},"created_at":{"type":"string","format":"date-time","description":"ISO 8601 instant"},"updated_at":{"type":"string","format":"date-time","description":"ISO 8601 instant"}},"required":["id","first_name","last_name","active","contract_type","max_hours_week","home_location_id","position_ids","created_at","updated_at"],"additionalProperties":false},"Schedule":{"type":"object","properties":{"schedule_id":{"type":"string","format":"uuid"},"location_id":{"type":"string","format":"uuid"},"period_start":{"type":"string","format":"date","description":"Local date of the location, YYYY-MM-DD"},"period_end":{"type":"string","format":"date","description":"Local date of the location, YYYY-MM-DD"},"version":{"type":"integer"},"published_at":{"type":"string","format":"date-time","description":"ISO 8601 instant"},"sha256":{"description":"SHA-256 of the canonical snapshot; null for versions published before it was kept","type":["string","null"]}},"required":["schedule_id","location_id","period_start","period_end","version","published_at","sha256"],"additionalProperties":false},"ScheduleDetail":{"type":"object","properties":{"schedule_id":{"type":"string","format":"uuid"},"location_id":{"type":"string","format":"uuid"},"period_start":{"type":"string","format":"date","description":"Local date of the location, YYYY-MM-DD"},"period_end":{"type":"string","format":"date","description":"Local date of the location, YYYY-MM-DD"},"version":{"type":"integer"},"published_at":{"type":"string","format":"date-time","description":"ISO 8601 instant"},"sha256":{"description":"SHA-256 of the canonical snapshot; null for versions published before it was kept","type":["string","null"]},"shifts":{"type":"array","items":{"$ref":"#/components/schemas/Shift"}}},"required":["schedule_id","location_id","period_start","period_end","version","published_at","sha256","shifts"],"additionalProperties":false},"Shift":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"schedule_id":{"type":"string","format":"uuid"},"version":{"type":"integer","description":"The published version the shift is read from"},"location_id":{"type":"string","format":"uuid"},"position_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"date":{"type":"string","format":"date","description":"Local date the shift starts on"},"start_local":{"type":"string","pattern":"^\\d{2}:\\d{2}$","description":"Wall-clock time at the location, HH:MM"},"end_local":{"type":"string","pattern":"^\\d{2}:\\d{2}$","description":"Wall-clock end; not after start_local means the next day"},"tz":{"type":"string","description":"IANA time zone of the location when the version was published"},"starts_at":{"type":"string","format":"date-time","description":"ISO 8601 instant with the location's offset at that moment"},"ends_at":{"type":"string","format":"date-time","description":"ISO 8601 instant with the location's offset at that moment"},"break_min":{"type":"integer","description":"Unpaid break, minutes"},"minutes":{"type":"integer","description":"Elapsed minutes from start to end"},"paid_minutes":{"type":"integer","description":"Elapsed minutes less the break"},"headcount":{"type":"integer","description":"People the shift needs"},"assignments":{"type":"array","items":{"type":"object","properties":{"employee_id":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["assigned","confirmed","swap_requested","declined"],"description":"declined: the person gave the seat back and does not work it"}},"required":["employee_id","state"],"additionalProperties":false}}},"required":["id","schedule_id","version","location_id","position_id","date","start_local","end_local","tz","starts_at","ends_at","break_min","minutes","paid_minutes","headcount","assignments"],"additionalProperties":false},"Hours":{"type":"object","properties":{"employee_id":{"type":"string","format":"uuid"},"month":{"type":"string","pattern":"^(20\\d\\d|2100)-(0[1-9]|1[0-2])$","description":"Calendar month, YYYY-MM, years 2000–2100"},"planned_minutes":{"type":"integer","description":"Elapsed minutes of the published shifts starting in the month"},"paid_planned_minutes":{"type":"integer","description":"The same less the breaks"},"counted_minutes":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Counted time from the door scan and manual entries, matched to the roster the way the app counts it (rounding, the plan, the break the law requires, a minor's break); null when attendance is off at every place of the person and nothing was clocked"},"fund":{"anyOf":[{"type":"object","properties":{"weekly_hours":{"type":"number"},"fund_minutes":{"type":"integer","description":"Weekdays of the month that are not a day-off holiday, times a fifth of the weekly hours"},"holiday_minutes":{"type":"integer","description":"Day-off holidays on weekdays of the month"},"absence_minutes":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Weekdays covered by an approved absence; only with absences:read, null without it"},"target_minutes":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"The fund less approved absences: what the plan should reach; only with absences:read, null without it"}},"required":["weekly_hours","fund_minutes","holiday_minutes","absence_minutes","target_minutes"],"additionalProperties":false},{"type":"null"}],"description":"Only for an employment contract (SK TPP, CZ HPP) with agreed weekly hours"},"confirmed":{"anyOf":[{"type":"object","properties":{"confirmed_at":{"type":"string","format":"date-time","description":"ISO 8601 instant"},"counted_minutes":{"type":"integer","description":"Counted minutes at the moment of the signature"},"stale":{"type":"boolean","description":"The month was corrected or counts differently since the signature"}},"required":["confirmed_at","counted_minutes","stale"],"additionalProperties":false},{"type":"null"}],"description":"The person confirmed the month in the app"},"meals":{"anyOf":[{"type":"object","properties":{"count":{"type":"integer","description":"Shifts that give a meal under the company's policy: more than 4 h of work in Slovakia, at least 3 h in Czechia, the break not counted"},"second":{"type":"integer","description":"Second meals, on shifts longer than 11 h including the break, when the policy gives them"},"absence_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Working days of approved absences that give a meal when the policy includes absences; only with absences:read and without `location`, null otherwise"},"source":{"anyOf":[{"type":"string","enum":["attendance","plan","both"]},{"type":"null"}],"description":"Where the shifts were read: counted time where the person clocked in that day at that place, the published plan elsewhere; null without a meal from work"},"form":{"type":"string","enum":["kitchen","voucher","allowance","choice"],"description":"How the company gives meals at the end of the month"},"choice":{"anyOf":[{"type":"string","enum":["voucher","allowance"]},{"type":"null"}],"description":"With form `choice` (Slovakia): what the person picked, null until they pick"}},"required":["count","second","absence_days","source","form","choice"],"additionalProperties":false},{"type":"null"}],"description":"Meals of the month for the payroll accountant, who applies the amounts; null when the company has set no meal policy in the app or the person's contract is outside it"}},"required":["employee_id","month","planned_minutes","paid_planned_minutes","counted_minutes","fund","confirmed","meals"],"additionalProperties":false},"TimeEntry":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"employee_id":{"type":"string","format":"uuid"},"location_id":{"type":"string","format":"uuid"},"shift_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The planned shift the entry belongs to; null for unplanned work"},"clock_in":{"type":"string","format":"date-time","description":"ISO 8601 instant with the location's offset at that moment"},"clock_out":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 instant with the location's offset at that moment"},{"type":"null"}],"description":"null while the person is still in"},"source":{"type":"string","enum":["qr","manual","pos"]},"offline_in":{"type":"boolean","description":"The clock-in was read on a phone without signal and delivered later"},"offline_out":{"type":"boolean"},"corrected":{"type":"boolean","description":"A manager entered or corrected the row"},"note":{"description":"Reason of the manual entry or the last correction","type":["string","null"]}},"required":["id","employee_id","location_id","shift_id","clock_in","clock_out","source","offline_in","offline_out","corrected","note"],"additionalProperties":false},"Absence":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"employee_id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["dovolenka","pn","ocr","other","absence"],"description":"dovolenka | absence without absences:kinds; dovolenka | pn | ocr | other with it"},"date_from":{"type":"string","format":"date","description":"Local date of the location, YYYY-MM-DD"},"date_to":{"type":"string","format":"date","description":"Local date of the location, YYYY-MM-DD"},"status":{"type":"string","enum":["requested","approved","rejected"]},"note":{"description":"Only with absences:kinds","type":["string","null"]},"created_at":{"type":"string","format":"date-time","description":"ISO 8601 instant"},"approved_at":{"anyOf":[{"type":"string","format":"date-time","description":"ISO 8601 instant"},{"type":"null"}],"description":"When the request was approved; null unless status is approved"}},"required":["id","employee_id","kind","date_from","date_to","status","note","created_at","approved_at"],"additionalProperties":false},"LeaveBalance":{"type":"object","properties":{"employee_id":{"type":"string","format":"uuid"},"year":{"type":"integer"},"unit":{"type":"string","enum":["day","hour"]},"entitled":{"type":"number"},"carried_over":{"type":"number"},"used":{"type":"number","description":"Approved leave of the year, past and planned"},"pending":{"type":"number","description":"Requests of the year still waiting for a decision"},"remaining":{"type":"number","description":"Entitled plus carried over less used; may be below zero"}},"required":["employee_id","year","unit","entitled","carried_over","used","pending","remaining"],"additionalProperties":false}}}}