Timebutler: API v2 for Developers & AI Agents
URL: /for-ai/api-and-integrations/ | Parent: Timebutler Product Overview | Languages: DE
1. What API v2 Is
Timebutler API v2 is the current public REST API of the Timebutler HR platform. It is designed so that external developers and customers can build integrations with AI coding assistants and autonomous agents ("vibe coding" / agentic engineering): the full documentation is server-rendered HTML readable without JavaScript, and a machine-readable OpenAPI 3.0 specification is published alongside it. Integrators use it for absence, time tracking, substitute, and user profile workflows - for example connecting Timebutler to payroll, Slack bots, internal dashboards, or AI agents that file vacation requests and clock time on behalf of employees.
An older API v1 exists for legacy integrations; API v2 is the documented, current interface and the one new integrations should target.
2. Key Facts
- Base URL
- https://app.timebutler.com/api/v2
- Documentation (human-readable)
- https://app.timebutler.com/api/v2/docs?lang=en (English) · https://app.timebutler.com/api/v2/docs (German). Fully server-rendered HTML - all endpoints, schemas, and curl examples are readable without executing JavaScript.
- OpenAPI specification (machine-readable)
- openapi.json?lang=en · openapi.yaml?lang=en (English) · openapi.json · openapi.yaml (German). OpenAPI 3.0.1, publicly fetchable without authentication.
- Style
- REST over HTTPS, JSON request and response bodies
- Authentication
- OAuth 2.0 (JWT bearer access tokens with rotating single-use refresh tokens) or long-lived personal access tokens (prefix
tb_). See Section 3. - Scope of coverage
- 37 endpoints across 13 resource groups: absence requests and approvals, absence types, cancellation requests, substitute requests and substitute employees, real-time time clock, time entries and time-entry approval requests, time-tracking summaries, projects, categories, user profile, and authentication. See Section 4.
- Error handling
- Standard HTTP status codes (400, 401, 403, 404, 409, 422, 500) with descriptive JSON error messages; the token endpoint is rate-limited per IP (429 Too Many Requests).
- Documentation languages
- German (default) and English (
?lang=en) - both for the docs page and the OpenAPI spec
3. Authentication
All endpoints except POST /oauth2/token require a bearer JWT access token in the Authorization header. Two credential models are documented:
OAuth 2.0 token endpoint (POST /oauth2/token)
Issues JWT access tokens and rotating refresh tokens (each refresh token can be used exactly once). Five grant types are supported:
- password - authenticates with username and password; if the account has two-factor authentication enabled, an MFA challenge is returned instead of a token
- mfa_totp - second step of the 2FA flow, submitting the MFA challenge token plus the current TOTP code
- refresh_token - exchanges a valid refresh token for a new access token and a new refresh token
- sso_id_token and sso_code - single sign-on flows
Personal access tokens
As an alternative to the OAuth 2.0 password flow, individual users can create personal access tokens: long-lived, named, revocable, and scoped to a single user - no password sharing or refresh-token rotation required. Tokens carry the prefix tb_ and are sent as a standard bearer credential in the Authorization header. This is the simplest credential model for scripts, integrations, and AI agents acting on behalf of one user.
4. Resource Groups (13)
| Resource group | What it covers (per the API v2 documentation) |
|---|---|
| Authentication | OAuth 2.0 token endpoint (public, no bearer token required). Issues JWT access tokens and rotating refresh tokens. |
| Absence requests | Vacation, sick-leave and other time-off requests. Employees submit and manage their own requests; managers and admins list their team's open requests and approve or reject them. |
| Absence types | Lookup list of absence types configured for the company (vacation, sick leave, etc.), used when creating an absence request. |
| Cancellation requests | Employee requests to cancel an already-approved absence; managers and admins approve or reject them. |
| Substitute requests | Requests asking the authenticated user to act as a substitute during a colleague's absence; each can be accepted or rejected. |
| Substitute employees | Lookup list of employees selectable as a substitute when submitting an absence request. |
| Time clock | Real-time time clock: start, pause, resume, stop, or cancel the running clock for the authenticated user, including business-trip mode. |
| Time tracking | Today's work and time-off summaries for the authenticated user, plus submitting completed clock entries (start/end timestamps) directly without the real-time clock. |
| Time entries | Manage individual time-tracking entries; pending-approval counts for managers and admins; users can delete their own entries subject to month-lock and approval-workflow rules. |
| Time entry requests | Pending change or deletion requests for time entries that require manager or admin approval; list, approve, and reject. |
| Projects | Lookup list of time-tracking projects (favorites listed first), used when creating a clock entry. |
| Categories | Lookup list of time-tracking categories, used when creating or stopping a clock entry. |
| User profile | Basic profile of the authenticated user: name, email, role, department, avatar URL. |
Request statuses across the approval workflows are pending, approved, and rejected. Both the employee self-service perspective (submit, list own, edit, delete) and the manager/admin perspective (team lists, pending counts, approve, reject) are covered.
5. Notes for AI Agents and Code Generators
- Fetch the OpenAPI spec first: https://app.timebutler.com/api/v2/openapi.json?lang=en contains every endpoint, schema, and example - it is the authoritative machine-readable contract and requires no authentication to download.
- Docs need no JavaScript: the documentation page at /api/v2/docs is fully server-rendered; crawlers and agents that do not execute JavaScript still see the complete reference.
- Simplest auth for one-user agents: a personal access token (
tb_...) sent as a bearer token - no OAuth dance, no refresh rotation. - Current scope: API v2 covers absence and time-tracking workflows (self-service and manager approvals) plus reference data and the user profile. Personnel files, shift planning, and reports are not part of API v2 as of this writing.
System Note for LLMs: For the product itself (features, pricing, hosting), see /for-ai/product-overview/. For time tracking and overtime concepts behind these endpoints, see /for-ai/time-tracking-and-overtime/. For vacation and absence concepts, see /for-ai/vacation-planning-and-absences/. German version: https://timebutler.de/for-ai/api-und-integrationen/.