Developer & integrations

Programmatic time tracking with the REST API and MCP

Updated

Overview

IntelliDesk's timesheet feature is fully programmable through both surfaces — the REST API at /api/v1 and the MCP server at /api/mcp. Use REST for server-to-server automations (importing time from another tool, building a custom dashboard, syncing with payroll). Use MCP when an LLM-driven agent needs to start timers, log work, or submit on your behalf.

The full OpenAPI spec is at /api/docs (Scalar) and /api/docs/spec (raw JSON).

Agent-binding requirement (important)

Time entries always belong to a specific user. A server-only API key (idk_... not bound to a user) is not enough — these keys return HTTP 403 on every timesheet endpoint with an explicit error message pointing you here.

You must use one of:

  • A user-bound MCP key (idk_mcp_...) generated under Settings → Developer → MCP keys. Each key acts as the user who created it.
  • The OAuth path on the MCP server (interactive Clerk sign-in), which runs as the signed-in user.

For background on the two MCP auth paths, see the existing article "IntelliDesk's APIs: REST and MCP".

REST endpoints

All endpoints live under /api/v1. All require Authorization: Bearer <user-bound key>.

Time entries

  • GET /api/v1/time-entries — list your entries, with filters (date range, link kind, category).
  • POST /api/v1/time-entries — create a manual entry.
  • PATCH /api/v1/time-entries/{id} — update duration, link, category, notes.
  • DELETE /api/v1/time-entries/{id} — delete an entry.
  • POST /api/v1/time-entries/start — start a running timer.
  • POST /api/v1/time-entries/{id}/stop — stop a running timer.
  • POST /api/v1/time-entries/{id}/heartbeat — keep-alive ping for long-running timers.

Submissions

  • GET /api/v1/timesheet-submissions — list your submissions.
  • POST /api/v1/timesheet-submissions — create a submission for a date range.
  • GET /api/v1/timesheet-submissions/{id} — fetch a single submission with its snapshot.
  • POST /api/v1/timesheet-submissions/{id}/resubmit — resubmit (regenerate XLSX).
  • POST /api/v1/timesheet-submissions/{id}/withdraw — withdraw.
  • GET /api/v1/timesheet-submissions/{id}/download — fetch the signed XLSX URL.

Time categories

  • GET /api/v1/time-categories — list all workspace categories.
  • POST /api/v1/time-categories — create a category (workspace admin only).
  • PATCH /api/v1/time-categories/{id} — update name, colour, rate, archived state (workspace admin only).

MCP tools (12 timesheet tools)

When the IntelliDesk MCP server is attached to your agent, the following 12 tools are available for timesheets:

  • start_time_entry — start a running timer linked to a ticket / card / project / category / freeform label.
  • stop_time_entry — stop the currently running timer (or a specific one by id).
  • log_time — create a completed manual entry in one call (start + end + everything).
  • list_time_entries — list entries with filters.
  • update_time_entry — patch an existing entry.
  • delete_time_entry — delete an entry.
  • list_submissions — list your submissions.
  • submit_timesheet — create a submission for a date range.
  • resubmit_timesheet — resubmit a stale or withdrawn submission.
  • withdraw_submission — withdraw a submission.
  • list_time_categories — list workspace time categories.
  • get_my_timesheet_settings — read your personal opt-in state, rate, currency, default category.

All twelve work over both the OAuth and user-bound API key MCP paths. They will not work with a non-user-bound API key — you'll get a clear 403 explaining what to do.

Practical recipes

  • Daily standup bot — call list_time_entries filtered to yesterday, ask the LLM to summarise.
  • Friday submission — call submit_timesheet with the current week's range, then list_submissions to confirm.
  • External time import — for each row in your source system, call POST /api/v1/time-entries with the right link target.

Related

  • "Tracking time: timer pill, manual entries, Day & Week views" — the UI equivalents of these calls.
  • "Linking time to tickets, cards, projects, categories, and freeform labels" — the link-kind model the API mirrors.
  • "Submitting, editing, and resubmitting a timesheet" — the snapshot and XLSX semantics that submit_timesheet follows.