The ingest API

1. Get a device token

Each editor on each machine is its own device, with its own token, revocable from Settings. There are no account-wide API keys. Start a device sign-in, show the user the link, and poll until they approve it with GitHub:

Content-Type: application/json

{ "client_name": "my-plugin", "editor": "vscode", "platform": "linux" }

{
  "device_code": "…",
  "user_code": "ABCD-1234",
  "verification_uri": "https://inlinr.com/activate",
  "verification_uri_complete": "https://inlinr.com/activate?code=ABCD-1234",
  "expires_in": 900,
  "interval": 5
}

Content-Type: application/json

{ "device_code": "…" }

{ "error": "authorization_pending" }

{ "error": "expired_token" }

{ "access_token": "in_d_…", "device": { … }, "user": { … } }

Send the token as Authorization: Bearer in_d_… on every call below. POST /api/auth/device/revoke with the same header signs the device out.

2. Send heartbeats

A heartbeat says “this file was active at this time”. Send one about every two minutes of activity per file, plus one on each save. Durations are computed on the server from consecutive beats, so never send a duration. Up to 1000 beats per request.

Authorization: Bearer in_d_…
Content-Type: application/json

[
  {
    "entity": "src/routes/index.tsx",
    "time": 1734523920.123,
    "project_git_remote": "git@github.com:you/app.git",
    "type": "file",
    "category": "coding",
    "language": "typescript",
    "branch": "main",
    "is_write": false,
    "lineno": 42,
    "cursorpos": 1023,
    "lines": 180,
    "lines_added": 14,
    "lines_deleted": 2,
    "ai_tool": "copilot",
    "ai_lines_added": 12,
    "ai_lines_deleted": 1,
    "editor": "vscode",
    "editor_version": "1.99.3",
    "plugin": "my-plugin/0.1.0"
  }
]

{ "responses": [[{ "id": "hb_0" }, 201]], "accepted": 1 }

Heartbeat fields

entityRequired

File path relative to the repository, a URL or an app name.

timeRequired

Unix seconds; fractions are kept.

project_git_remoteRequired

The repository's remote. The project is created or found from it.

type

file (default), app or domain.

category

coding, debugging, building, code-reviewing, writing-tests or ai-coding.

is_write

true when the beat comes from a save. Defaults to false.

lines_addedlines_deleted

Lines changed since the previous beat. 0 means none; leave the field out if you do not count.

ai_tool

copilot, cursor, claude-code, codeium, windsurf or aider. Any other value is rejected. Send it only when you saw the assistant edit.

ai_lines_addedai_lines_deleted

The part of the line counts the assistant wrote.

ai_sessionai_model

One assistant conversation, and the model it used.

ai_input_tokensai_output_tokensai_cache_read_tokensai_cache_write_tokens

Token counts. Cache tokens are separate because they bill at different rates.

editoreditor_version

The host editor, e.g. vscode, cursor, windsurf; and its version.

plugin

Your client, user-agent style: name/version.

branchlanguagelinenocursorposlines

Optional context. lines is the file's total line count.

Status codes

• 200Stored. The responses array has one entry per beat, in order, so you can drop exactly what was accepted from your queue.
• 400Malformed. Do not retry the same payload.
• 401The token is missing or revoked. Ask the user to sign in again.
• 5xxOr a network error: keep the beats and retry later.

3. Commit line counts (optional)

Counts only, read from git log --numstat on the machine: no commit message, no author email. Up to 1000 commits per request.

Authorization: Bearer in_d_…
Content-Type: application/json

{
  "project_git_remote": "git@github.com:you/app.git",
  "commits": [
    { "sha": "9f2c1ab", "committed_at": "2026-10-14T09:12:00Z",
      "files_changed": 3, "insertions": 120, "deletions": 14 }
  ]
}

{ "accepted": 1, "backfilled": 0 }

{ "accepted": 0, "reason": "unknown project" }

4. Your time

For a status bar clock: time tracked today in the user's own time zone, with the same counting rule as the dashboard.

Authorization: Bearer in_d_…

{ "seconds": 12840, "beats": 214, "top_projects": [ … ], "by_category": [ … ] }

A period's totals, by project and language, and the time, lines and cost of AI assistants, as the AI usage page shows them. period takes the dashboard's presets (today, 7d, month…) or custom with from and to; project takes a project name or its git remote.

Authorization: Bearer in_d_…

{
  "period": "Last 7 days",
  "since": "2026-10-09T00:00:00.000Z",
  "until": null,
  "project": "acme-app",
  "total_seconds": 44940,
  "by_project": [{ "name": "acme-app", "seconds": 44940, "ai_seconds": 9120 }],
  "by_language": [{ "name": "typescript", "seconds": 38100 }],
  "ai": { "seconds": 9120, "sessions": 14, "lines_added": 1820,
          "total_lines_added": 2410, "tokens": { … }, "cost_usd": 18.42,
          "unpriced_tokens": 0, "prices_verified_on": "2026-10-01",
          "by_tool": [ … ] }
}

Logs a manual entry. Only minutes is required (1 to 1440). type is one of meeting, call, review, doc, research, testing, email or custom (the default), and started_at defaults to that many minutes ago.

Authorization: Bearer in_d_…
Content-Type: application/json

{ "minutes": 45, "type": "meeting", "label": "Kick-off", "billable": true, "project": "acme-app" }

{ "id": "cm…", "type": "meeting", "label": "Kick-off",
  "started_at": "2026-10-15T09:15:00.000Z", "minutes": 45,
  "billable": true, "project": "acme-app" }

5. Package releases

What the public package pages say, as JSON, for a script, a bot or an AI agent: an npm package's releases with their notes and advisories, what changes between two of its versions, and a check of a whole package.json. No token needed. Scoped names go in the path as they are: /api/v1/packages/@tanstack/react-router/releases.

No body.

{
  "name": "react",
  "latest_version": "19.2.0",
  "deprecated": null,
  "license": "MIT",
  "repository_url": "https://github.com/facebook/react",
  "homepage": "https://react.dev/",
  "history_refreshed_at": "2026-10-15T08:00:00.000Z",
  "history_stale": false,
  "releases": [
    { "version": "19.2.0", "published_at": "2026-10-01T16:00:00.000Z",
      "prerelease": false, "notes": "## 19.2.0 …",
      "notes_url": "https://github.com/facebook/react/releases/tag/v19.2.0" }
  ],
  "advisories": []
}

limit goes up to 100, since takes an ISO date, and prereleases=1 keeps release candidates. Leave to out of an upgrade to go to the latest release:

No body.

{
  "name": "react",
  "latest_version": "19.2.0",
  "history_refreshed_at": "2026-10-15T08:00:00.000Z",
  "history_stale": false,
  "from": "18.3.1",
  "to": "19.0.0",
  "releases": 1,
  "releases_with_notes": 1,
  "releases_without_notes": [],
  "breaking": [{ "version": "19.0.0", "markdown": "Remove propTypes …" }],
  "deprecations": [],
  "fixed_advisories": [],
  "remaining_advisories": [],
  "security": [],
  "features": [{ "version": "19.0.0", "markdown": "Actions …" }],
  "fixes": [],
  "other": [],
  "internal_lines": 0,
  "guides": [{ "label": "React 19 upgrade guide", "url": "https://react.dev/…" }]
}

{ "error": "not_found", "message": "No published release 19.9.9 after 18.3.1." }

Content-Type: application/json

{ "packages": ["react@^18.2.0", "request"] }

{
  "summary": { "checked": 2, "with_advisories": 1, "deprecated": 1,
               "majors_behind": 1, "behind": 1, "unchecked": 0 },
  "truncated": 0,
  "dependencies": [
    { "name": "request", "range": null, "kind": "prod",
      "resolved_name": null, "status": "checked", "unchecked_reason": null,
      "latest": "2.88.2", "gap": null, "floor": null,
      "deprecated": "request has been deprecated …",
      "advisories": [{ "id": "GHSA-p8p7-x288-28g6", "summary": "…",
                       "severity": "moderate", "url": "…", "fixed_in": null }],
      "advisories_unknown": false }
  ]
}

Without a token, an address gets 60 reads and 10 checks every ten minutes. A device token raises that to 600 and 60, and each answer then lists your_projects: your own followed projects that declare the package, with the range and the installed version. Past the limit the answer is 429 with Retry-After. 503 busy means npm could not be read for a package we had never seen; try again in a minute. A range we cannot read, like workspace:*, is reported as unchecked, never as up to date.

WakaTime plugins

Any stock WakaTime plugin can send time here, unchanged. Create a WakaTime key in Settings → Editors (it starts with waka_), then point the plugin at Inlinr in ~/.wakatime.cfg:

[settings]
api_url = https://inlinr.com/api/compat/wakatime/v1
api_key = waka_…

The key travels as HTTP Basic auth, the way wakatime-cli sends it. Projects are matched by name, since WakaTime plugins do not send a git remote, and the plugin's status bar shows today's time from Inlinr. Setup for each editor is on the WakaTime integration page. Inlinr is not affiliated with or endorsed by WakaTime.

Before you write a client

The Inlinr CLI already does sign-in, an offline queue and retries. Most plugins only spawn inlinr heartbeat with flags, which is how the VS Code extension works. How time is computed from beats is in this guide, and what we store is on the security page.