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.

For typed request models, see Python SDK activity uploads and Go SDK activity uploads.

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.