Skip to main content

Activities

Plugins and the Desktop Agent upload aggregated activity, not raw keystroke streams or file contents.

All write routes below require Bearer authentication.

IDE / plugin activity sync​

Primary bulk upload used by VS Code, JetBrains, and compatible editors:

POST /main/api/v1/sync/activities
Authorization: Bearer <token>
Content-Type: application/json

Request body​

{
  "activities": [
    {
      "language": "go",
      "lines": 10,
      "time": 60,
      "date": "2026-06-15",
      "hour": 14,
      "path": "/home/user/project/main.go",
      "project_name": "my-app",
      "ide_name": "VSCode",
      "filename": "main.go"
    }
  ]
}
FieldRequiredNotes
languageyesLanguage / grammar id
timeyesSeconds in this bucket
linesnoNon-negative line metric
daterecommendedYYYY-MM-DD
hourrecommended0–23
pathnoFile or workspace path metadata
project_namenoProject / workspace label
ide_namenoe.g. VSCode, JetBrains, IntelliJ
filenamenoBasename helper for charts

Response (typical)​

JSON acknowledging how many activities were accepted / grouped. Clients should retry on network failure and keep a local queue.

There is also a single-record create variant under the activities API for specialized clients. Prefer batch sync for normal plugin traffic.

Desktop Agent activity sync​

Used by the Desktop Agent for focused-application time:

POST /main/api/v1/sync/activities/desktop
Authorization: Bearer <token>
Content-Type: application/json

Request body​

{
  "activities": [
    {
      "platform": "Linux",
      "program_name": "firefox",
      "path": "/usr/lib/firefox/firefox",
      "filename": "firefox",
      "time": 120,
      "date": "2026-06-15",
      "hour": 14
    }
  ]
}
FieldRequiredNotes
platformyesLinux, Windows, Darwin, …
timeyesSeconds focused
dateyesYYYY-MM-DD
houryes0–23
pathyes*Executable / app path when known
filenameyes*Basename
program_nameyes*App identity

*Required by the desktop sync contract; send empty strings only when the OS cannot resolve a value (prefer omitting empty uploads).

A single-record desktop create endpoint exists for parity with IDE create, but the agent uses batch sync in production.

Guidance for plugin authors​

  1. Bucket by language (and project) + date + hour before upload.
  2. Send compact batches on an interval (seconds to a minute), not per keystroke.
  3. Never upload file bodies, diffs, or clipboard data.
  4. Set ide_name so dashboards can split VS Code vs JetBrains time.
  5. Back off on 5xx / network errors; keep an offline queue.