Auto-Tracking API

All endpoints require authentication. Drafts and signals are scoped to the current user. The ingest endpoint uses service token authentication.

List Drafts

GET /api/auto-tracking/drafts

Permission: time / view

Query parameters:

Param	Type	Description
date_from	string	Filter drafts from this date (YYYY-MM-DD)
date_to	string	Filter drafts up to this date (YYYY-MM-DD)
status	string	Filter by status (default: pending). Use all for every status

Response: { drafts }

Each draft includes joined budget_name and task_title.

Get Draft

GET /api/auto-tracking/drafts/:id

Permission: time / view

Path parameters:

Param	Type	Description
id	string	Draft ID

Response: { draft, signals }

Returns the draft with its associated activity signals.

Accept Draft

POST /api/auto-tracking/drafts/:id/accept

Permission: time / update

Accepts a pending draft and creates a time entry. Managers and above are auto-approved; employees/leads create a draft time entry.

Path parameters:

Param	Type	Description
id	string	Draft ID

Response: { time_entry_id, status }

Edit and Accept Draft

POST /api/auto-tracking/drafts/:id/edit

Permission: time / update

Edits a pending draft’s fields, then creates a time entry from the merged values.

Path parameters:

Param	Type	Description
id	string	Draft ID

Request body:

Field	Type	Description
hours	number	Override hours
description	string	Override description
budget_id	string | null	Override budget
task_id	string | null	Override task
line_item_id	string | null	Override line item
billable	number	Override billable flag (0 or 1)

Response: { time_entry_id, status }

Dismiss Draft

POST /api/auto-tracking/drafts/:id/dismiss

Permission: time / update

Dismisses a pending draft (marks it as dismissed).

Path parameters:

Param	Type	Description
id	string	Draft ID

Response: { ok: true }

Bulk Accept Drafts

POST /api/auto-tracking/drafts/accept-bulk

Permission: time / update

Accepts multiple pending drafts at once, creating time entries for each.

Request body:

Field	Type	Description
ids	string[]	Array of draft IDs to accept

Response: { accepted } — count of accepted drafts.

Bulk Dismiss Drafts

POST /api/auto-tracking/drafts/dismiss-bulk

Permission: time / update

Dismisses multiple pending drafts at once.

Request body:

Field	Type	Description
ids	string[]	Array of draft IDs to dismiss

Response: { dismissed } — count of dismissed drafts.

Pending Draft Count

GET /api/auto-tracking/drafts/pending-count

Permission: time / view

Returns the number of pending drafts for the current user (used for sidebar badges).

Response: { pending_count }

List Activity Signals

GET /api/auto-tracking/signals

Permission: time / view

Query parameters:

Param	Type	Description
date_from	string	Filter signals starting from this date (YYYY-MM-DD)
date_to	string	Filter signals up to this date (YYYY-MM-DD)
source	string	Filter by signal source (e.g. google_calendar, meetings, nucleus)

Response: { signals } — up to 200 signals, ordered by started_at descending.

Get Preferences

GET /api/auto-tracking/preferences

Permission: time / view

Returns the current user’s auto-tracking preferences. Returns defaults if no preferences have been saved.

Response: { preferences }

Default preferences include enabled: 0, source toggles, default_rounding: "15min", and auto_dismiss_below_minutes: 5.

Update Preferences

PUT /api/auto-tracking/preferences

Permission: time / update

Request body:

Field	Type	Description
enabled	number	Enable/disable auto-tracking (0 or 1)
source_google_calendar	number	Track Google Calendar events
source_meetings	number	Track Nucleus meetings
source_nucleus	number	Track Nucleus activity
source_github	number	Track GitHub activity
source_productive	number	Track Productive activity
calendar_exclude_patterns	string[]	Calendar event patterns to exclude
calendar_min_duration_minutes	number	Minimum event duration to track
custom_rules	unknown[]	Custom categorisation rules
default_rounding	string	Rounding strategy (e.g. 15min)
auto_dismiss_below_minutes	number	Auto-dismiss signals shorter than this

Response: { ok: true }

Ingest (Agent Endpoint)

POST /api/auto-tracking/ingest

Authentication: Service token via X-Service-Token header or Authorization: Bearer <token>. Does not use standard user authentication.

Bulk-ingests activity signals and/or time drafts from external agents.

Request body:

Field	Type	Description
signals	array	Activity signals to ingest
drafts	array	Time drafts to create

Each signal object:

Field	Type	Description
id	string	Signal ID
user_id	string	Target user
source	string	Source system
source_id	string	External ID
signal_type	string	Type of activity
title	string | null	Signal title
started_at	string | null	Start timestamp
ended_at	string | null	End timestamp
duration_minutes	number | null	Duration
metadata	string | null	JSON metadata
matched_budget_id	string | null	Matched budget
matched_task_id	string | null	Matched task

Each draft object:

Field	Type	Description
id	string	Draft ID
user_id	string	Target user
date	string	Date (YYYY-MM-DD)
hours	number	Hours
description	string | null	Description
budget_id	string | null	Budget
task_id	string | null	Task
billable	number	Billable flag
signal_ids	string	JSON array of signal IDs
signal_count	number	Number of signals
match_confidence	number	AI confidence score
categorization_source	string	How it was categorised

Response: { signals_ingested, drafts_created }