canonical: https://jentic.com/apis/kimai.org/kimai

# Kimai API

Jentic publishes the only available OpenAPI specification for Kimai API, keeping it validated and agent-ready. Kimai is an open-source time-tracking application and its REST API exposes the full timesheet, project, customer, activity, user, team, and tag model. Operations cover starting and stopping running timesheets, duplicating or exporting entries, and the standard CRUD surface for projects and customers. Self-hosted Kimai installations expose this API at a host-specific base URL with either bearer or X-AUTH-TOKEN header authentication.

## For AI agents

Start, stop, and edit Kimai timesheets, manage the projects and customers they roll up to, and read recent or running entries from a self-hosted Kimai instance.

## Scope

Does not handle invoicing, payroll, or expense management - use for time tracking, project, and customer records inside a Kimai instance only.

## Capabilities

- Start and stop running timesheets for the authenticated user
- Create timesheet entries with project, activity, and tag attribution
- Duplicate and export existing timesheet entries
- Maintain the project and customer hierarchy that timesheets roll up to
- Read currently running and recent timesheet activities for dashboards
- Update timesheet meta fields used for custom reporting

## Use cases

### Stop the running timer at end of day

An automation can list active timesheets with GET `/api/timesheets/active` and stop them with PATCH `/api/timesheets/{id}/stop` on a schedule, ensuring no entry is left running overnight. The combined call typically completes in well under a second per user.

Example prompt: Call GET `/api/timesheets/active`, then PATCH `/api/timesheets/{id}/stop` for every entry returned.

### Daily timesheet creation from a calendar

A morning workflow can read the day's calendar events and POST `/api/timesheets` for each meeting, attaching the right project and activity. Kimai records the entries against the customer hierarchy so they can be invoiced or reported on without manual entry.

Example prompt: For each calendar event today, POST a timesheet to `/api/timesheets` with begin, end, project, and activity.

### Customer and project hygiene

Operations teams can keep the project list aligned with the active client roster by reading customers via GET `/api/customers`, comparing them with the source system, and PATCH-ing project records that need to be archived or relabeled. The endpoint set covers the full project and customer CRUD needed for that sync.

Example prompt: Compare GET `/api/customers` with the master roster and PATCH `/api/projects/{id}` to archive any project tied to a deactivated customer.

### Invoice export pipeline

Before an invoice run, a script can call PATCH `/api/timesheets/{id}/export` on every billable entry for a customer so that Kimai marks them as exported and they do not appear on the next run. This keeps the billable-versus-exported state consistent across runs.

Example prompt: List timesheets for a customer over the billing period and PATCH `/api/timesheets/{id}/export` on each one before generating the invoice.

### Agent integration via Jentic

A productivity agent can use Jentic to discover the Kimai timesheet operations, load their schemas, and execute them with a vaulted bearer token, letting a user start, stop, or duplicate entries by speaking to the agent.

Example prompt: Search Jentic for 'stop the running Kimai timesheet', load PATCH `/api/timesheets/{id}/stop`, and execute it for the authenticated user's active entry.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/timesheets` | List timesheet entries |
| POST | `/api/timesheets` | Create a timesheet entry |
| PATCH | `/api/timesheets/{id}/stop` | Stop a running timesheet |
| PATCH | `/api/timesheets/{id}/restart` | Restart a timesheet |
| GET | `/api/timesheets/active` | Get currently running timesheets |
| GET | `/api/projects` | List projects |
| GET | `/api/customers` | List customers |

## Key resources

- **Timesheets** — List, create, update, stop, restart, duplicate, and export time entries
- **Projects** — Manage projects that timesheets roll up to
- **Customers** — Manage customers that own projects
- **Activities** — Manage activity types attached to timesheets
- **Users** — Read user records on the Kimai instance
- **Teams** — Manage team membership and visibility
- **Tags** — Tag timesheets for cross-project reporting

## Why Jentic

- **Setup:** Wiring Kimai by hand means learning its bearer token or X-AUTH-TOKEN header auth and pointing at your own self-hosted instance host yourself. Through Jentic you install once, import Kimai from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Kimai puts the timesheet id in the URL path (`/api/timesheets/{id}/stop`), so a rule can pin your agent to acting on the timesheets it is given: it can start, stop, or restart those entries and nothing else. You choose the operations it may call, so writes you do not need are not included unless you add them.
- **Credential handling:** Your Kimai token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'start a timesheet' or 'list active time entries', and Jentic returns the matching Kimai operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Toggl Track API** — Toggl Track is a hosted time-tracking service while Kimai is self-hosted
- **Clockify API** — Clockify offers a free hosted alternative to a self-hosted Kimai instance
- **Everhour API** — Everhour is a hosted time-tracking service that integrates with project tools
- **Asana API** — Asana holds the projects and tasks that Kimai timesheets reference

## FAQ

### Why is there no official OpenAPI spec for Kimai API?

The Kimai project does not publish a hosted OpenAPI specification under its own domain. Jentic generates and maintains this spec so that AI agents and developers can call Kimai API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Kimai API use?

Kimai supports two schemes: HTTP bearer authentication and a legacy X-AUTH-TOKEN header. Jentic stores the credential in the vault and injects whichever scheme the instance accepts on each request.

### Can I stop a running timesheet with the Kimai API?

Yes. Call PATCH `/api/timesheets/{id}/stop` on the entry you want to stop. To find the entry, list active timers first with GET `/api/timesheets/active.`

### What are the rate limits for the Kimai API?

Kimai is self-hosted, so the rate limit depends on the instance configuration rather than a public quota. Treat list endpoints as paginated reads and avoid polling `/api/timesheets/active` more often than once a minute.

### How do I create a timesheet entry with the Kimai API through Jentic?

Run pip install jentic, search Jentic for 'create a Kimai timesheet entry', load the POST `/api/timesheets` operation, and execute it with begin, end, project, and activity. Jentic injects the bearer or X-AUTH-TOKEN credential from the vault.

### Can I limit what my agent is allowed to do with the Kimai API?

Yes. Because you run Jentic One yourself, your own rules decide which Kimai operations and credentials the agent may use, and Kimai puts the timesheet id in the URL path, so you can pin the agent to acting only on the entries it is given. You might allow just PATCH `/api/timesheets/{id}/stop` and PATCH `/api/timesheets/{id}/restart` while withholding writes to `/api/projects` or `/api/customers`, so the agent can start, stop, and restart those timesheets and nothing else. The token is injected at execution time and never enters the agent's prompt or logs, and you add write operations only if you explicitly need them.