Wakapi unofficial
POST/users/{user}/heartbeats

Submit a heartbeat for a user

Submits a single heartbeat for a specified user. Send the heartbeat as a JSON object containing activity data such as entity, category, and language.

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

1 parameter · 25 body fields
userstringrequired
Username to submit the heartbeat for, or `current` for the current user.

A JSON object containing a single heartbeat and its activity data.

ai_input_tokensintegeroptional
Number of AI input tokens associated with the heartbeat.
ai_line_changesintegeroptional
Number of line changes attributed to AI.
ai_output_tokensintegeroptional
Number of AI output tokens associated with the heartbeat.
ai_prompt_lengthintegeroptional
Length of the AI prompt.
ai_sessionstringoptional
Identifier for the AI session.
branchstringoptional
Name of the source-control branch associated with the activity.
categorystringoptional
Category of the recorded activity.
created_atnumberoptional
https://gorm.io/docs/conventions.html#CreatedAt
cursorposintegeroptional
Cursor position as an integer.
editorstringoptional
ignored because editor might be parsed differently by wakatime
entitystringoptional
File or other entity associated with the activity.
human_line_changesintegeroptional
Number of line changes attributed to a human.
is_writebooleanoptional
Whether the activity represents a write operation.
languagestringoptional
Programming language associated with the activity.
line_additionsintegeroptional
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

Use user as a username or current to select the user for the heartbeat. The schema does not mark any heartbeat fields as required; use the documented field types, such as an integer for cursorpos and a number for created_at.