Wakapi unofficial
POST/heartbeat

Submit a heartbeat

Submits a single heartbeat containing activity data. Send the heartbeat as a JSON object, using fields such as entity, category, and language to describe the recorded activity.

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

25 body fields

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

The schema does not mark any heartbeat fields as required. Supply values using the documented field types, such as an integer for cursorpos and a number for created_at.