Timebutler: API v2 für Entwickler:innen & KI-Agenten

1. Was API v2 ist

Die Timebutler API v2 ist die aktuelle öffentliche REST-API der Timebutler HR-Plattform. Sie ist darauf ausgelegt, dass externe Entwickler:innen und Kund:innen Integrationen mit KI-Coding-Assistenten und autonomen Agenten bauen können („Vibe Coding" / Agentic Engineering): Die vollständige Dokumentation ist serverseitig gerendertes HTML, das ohne JavaScript lesbar ist, und eine maschinenlesbare OpenAPI-3.0-Spezifikation wird parallel dazu veröffentlicht. Integrator:innen nutzen sie für Abwesenheits-, Zeiterfassungs-, Vertretungs- und Benutzerprofilprozesse - zum Beispiel um Timebutler mit Lohnbuchhaltung, Slack-Bots, internen Dashboards oder KI-Agenten zu verbinden, die im Namen von Mitarbeitenden Urlaubsanträge stellen und Zeiten stempeln.

Für Legacy-Integrationen existiert eine ältere API v1; API v2 ist die dokumentierte, aktuelle Schnittstelle, auf die neue Integrationen aufsetzen sollten.

2. Eckdaten

Basis-URL

https://app.timebutler.com/api/v2

Dokumentation (für Menschen)

https://app.timebutler.com/api/v2/docs (Deutsch) · https://app.timebutler.com/api/v2/docs?lang=en (Englisch). Vollständig serverseitig gerendertes HTML - alle Endpunkte, Schemas und curl-Beispiele sind ohne JavaScript-Ausführung lesbar.

OpenAPI-Spezifikation (maschinenlesbar)

openapi.json · openapi.yaml (Deutsch) · openapi.json?lang=en · openapi.yaml?lang=en (Englisch). OpenAPI 3.0.1, öffentlich ohne Authentifizierung abrufbar.

Stil

REST über HTTPS, JSON-Request- und -Response-Bodies

Authentifizierung

OAuth 2.0 (JWT-Bearer-Zugriffstoken mit rotierenden Einmal-Refresh-Token) oder langlebige persönliche Zugriffstoken (Präfix tb_). Siehe Abschnitt 3.

Funktionsumfang

37 Endpunkte in 13 Ressourcengruppen: Abwesenheitsanträge und Freigaben, Abwesenheitsarten, Stornierungsanträge, Vertretungsanfragen und Vertretungsmitarbeiter, Echtzeit-Stempeluhr, Zeiteinträge und Zeiterfassungsanträge, Zeiterfassungs-Zusammenfassungen, Projekte, Kategorien, Benutzerprofil und Authentifizierung. Siehe Abschnitt 4.

Fehlerbehandlung

Standard-HTTP-Statuscodes (400, 401, 403, 404, 409, 422, 500) mit beschreibenden JSON-Fehlermeldungen; der Token-Endpunkt ist pro IP ratenbegrenzt (429 Too Many Requests).

Dokumentationssprachen

Deutsch (Standard) und Englisch (?lang=en) - sowohl für die Docs-Seite als auch für die OpenAPI-Spezifikation

3. Authentifizierung

Alle Endpunkte außer POST /oauth2/token erfordern ein Bearer-JWT-Zugriffstoken im Authorization-Header. Zwei Credential-Modelle sind dokumentiert:

OAuth-2.0-Token-Endpunkt (POST /oauth2/token)

Stellt JWT-Zugriffstoken und rotierende Refresh-Token aus (jedes Refresh-Token ist genau einmal verwendbar). Fünf Grant-Typen werden unterstützt:

• password - Authentifizierung mit Benutzername und Passwort; bei aktivierter Zwei-Faktor-Authentifizierung wird statt eines Tokens eine MFA-Challenge zurückgegeben
• mfa_totp - zweiter Schritt des 2FA-Flows: MFA-Challenge-Token plus aktueller TOTP-Code aus der Authenticator-App
• refresh_token - tauscht ein gültiges Refresh-Token gegen ein neues Zugriffstoken und ein neues Refresh-Token
• sso_id_token und sso_code - Single-Sign-On-Flows

Persönliche Zugriffstoken

Als Alternative zum OAuth-2.0-Passwort-Flow können einzelne Benutzer:innen persönliche Zugriffstoken erstellen: langlebig, benannt, widerrufbar und auf eine:n einzelne:n Benutzer:in beschränkt - kein Passwort-Teilen, keine Refresh-Token-Rotation nötig. Die Token tragen das Präfix tb_ und werden als normales Bearer-Credential im Authorization-Header gesendet. Das ist das einfachste Credential-Modell für Skripte, Integrationen und KI-Agenten, die im Namen einer Person handeln.

4. Ressourcengruppen (13)

Die Antragsstatus in den Genehmigungsworkflows sind pending, approved und rejected. Abgedeckt sind sowohl die Mitarbeitenden-Perspektive (einreichen, eigene auflisten, bearbeiten, löschen) als auch die Vorgesetzten-/Admin-Perspektive (Team-Listen, offene Zähler, genehmigen, ablehnen).

5. Hinweise für KI-Agenten und Code-Generatoren

• Zuerst die OpenAPI-Spezifikation abrufen: https://app.timebutler.com/api/v2/openapi.json enthält jeden Endpunkt, jedes Schema und Beispiele - sie ist der maßgebliche maschinenlesbare Vertrag und ohne Authentifizierung abrufbar.
• Docs brauchen kein JavaScript: Die Dokumentationsseite unter /api/v2/docs ist vollständig serverseitig gerendert; Crawler und Agenten ohne JavaScript-Ausführung sehen die komplette Referenz.
• Einfachste Authentifizierung für Ein-Personen-Agenten: ein persönliches Zugriffstoken (tb_...) als Bearer-Token - kein OAuth-Flow, keine Refresh-Rotation.
• Aktueller Umfang: API v2 deckt Abwesenheits- und Zeiterfassungsworkflows (Self-Service und Vorgesetzten-Freigaben) plus Referenzdaten und Benutzerprofil ab. Personalakte, Schichtplanung und Berichte sind derzeit nicht Teil der API v2.