Skip to main content

API: Linear integration

Optional plugin (on by default, unlike the others). Enable/disable per application in Settings → Plugins; every route below 404s while disabled. See Linear integration for setup and how the fingerprint-based upsert avoids duplicating or clobbering your changes.

Settings — /?api=linear-settings​

MethodPurpose
GET{enabled, labels, assigned_to_me, assignees, status_writeback, team_key, api_key_configured, api_key_source, webhook_configured, at_rest_encrypted, env_key_locked, updated_at} — never the raw key.
PUT / POSTUpdate any subset: {enabled?, labels?, assigned_to_me?, assignees?, status_writeback?, team_key?, api_key?, webhook_secret?}.
PUT /?api=linear-settings
{"enabled":true,"labels":["billing","urgent"],"assigned_to_me":true,"status_writeback":true,"api_key":"lin_api_…"}

Setting api_key/webhook_secret to an explicit empty string clears the stored value; omitting the field leaves it untouched. If LOG_LENS_LINEAR_API_KEY is set in the environment, api_key here is rejected — the environment variable is the sole source of truth and is never written to the database.

POST /?api=linear-test​

Verifies the configured key and reports the authenticated Linear account: {ok, viewer}. Useful to confirm exactly whose "assigned to me" will resolve, since Linear evaluates that server-side from the key.

POST /?api=linear-sync​

Pulls every issue matching the configured labels/assignee/team filter and upserts it now. Returns a per-run summary:

{"ok":true,"pulled":24,"created":20,"updated":4,"tags_created":3,"synced_at":"2026-08-18 08:45:36"}

Requires at least one filter configured (labels, assigned-to-me, specific assignees, or a team key) — refuses to pull an entire Linear workspace by accident.

POST /?api=linear-webhook​

Signed receiver for real-time updates — point a Linear webhook at …/?api=linear-webhook&app={id}. Guard-exempt (no dashboard token needed) because it authenticates itself: the raw request body's HMAC (Linear-Signature header) is verified against the configured webhook secret. An invalid or missing signature is rejected; a verified webhook simply triggers the same sync as linear-sync.

  • Linear integration — priority/status mapping, keeping the key secure, real-time vs. scheduled vs. manual sync.
  • API conventions — why this route and ingest are the only two guard-exempt ones.