Wakapi unofficial
POST/compat/wakatime/v1/users/{user}/heartbeats

Create a coding heartbeat

Creates a single heartbeat for a user from a WakaTime-compatible request. Send the heartbeat as a JSON object; created_at is numeric, and the editor field is ignored.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 25 body fields
userstringrequired
The username to create the heartbeat for, or `current` to use the authenticated user.

A single heartbeat object; no individual fields are marked as required.

ai_input_tokensintegeroptional
The number of AI input tokens associated with the heartbeat.
ai_line_changesintegeroptional
The number of code line changes attributed to AI.
ai_output_tokensintegeroptional
The number of AI output tokens associated with the heartbeat.
ai_prompt_lengthintegeroptional
The length of the AI prompt associated with the heartbeat.
ai_sessionstringoptional
The AI session identifier.
branchstringoptional
The version-control branch associated with the heartbeat.
categorystringoptional
The activity category for the heartbeat.
created_atnumberoptional
https://gorm.io/docs/conventions.html#CreatedAt
cursorposintegeroptional
The cursor position associated with the heartbeat.
editorstringoptional
ignored because editor might be parsed differently by wakatime
entitystringoptional
The file or other entity associated with the heartbeat.
human_line_changesintegeroptional
The number of code line changes attributed to human activity.
is_writebooleanoptional
Whether the heartbeat records a write action.
languagestringoptional
The programming language associated with the heartbeat.
line_additionsintegeroptional
The number of lines added.
line_deletionsintegeroptional
linenointegeroptional
linesintegeroptional
machinestringoptional
ignored because wakatime api doesn't return machines currently
operating_systemstringoptional
ignored because os might be parsed differently by wakatime
projectstringoptional
project_root_countintegeroptional
timenumberoptional
note: on sqlite, table will have an additional column `time_real`, introduced "manually" by migration 20260111 see https://github.com/muety/wakapi/issues/882 for details
typestringoptional
user_agentstringoptional

1 status code
201Returns confirmation that the heartbeat was created.

Error handling

The user path parameter must identify the username or be set to current. Send a single JSON object for the heartbeat; created_at, if supplied, must be numeric.