{"openapi":"3.1.0","info":{"title":"WakaTime (BYOK) API","version":"0.1.0","description":"WakaTime (BYOK) lets an AI assistant read your own WakaTime data through the WakaTime API with a key you supply (OAuth access token (WakaTime documents API keys as write-only, so reading needs an access token from an OAuth app)). Read-only: 8 tools (get_stats, get_all_time_since_today, list_projects, get_durations, get_heartbeats, list_goals, get_insight, get_leaders). The BYOK key travels with...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-wakatime.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-wakatime/docs"},"termsOfService":"https://connectorbay.com/byok-wakatime/terms"},"servers":[{"url":"https://byok-wakatime.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-wakatime/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_stats":{"post":{"operationId":"get_stats","summary":"Get your total coding time and daily average for a period (last 7 days, 30 days, a year, a month, all time), plus time p","description":"Get your total coding time and daily average for a period (last 7 days, 30 days, a year, a month, all time), plus time per category. Use for \"How many hours did I code in the last 7 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"period":{"description":"Time range: last_7_days, last_30_days, last_6_months, last_year, all_time, a year like 2026 or a month like 2026-03.","maxLength":20,"title":"Period","type":"string"},"timeout":{"anyOf":[{"maximum":120,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Keystroke timeout in minutes used to merge activity into durations; leave out to use your account setting.","title":"Timeout"},"writes_only":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to count only time spent writing (saving files), false to count all activity; leave out to use your account setting.","title":"Writes Only"}},"required":["period"],"title":"get_statsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_all_time_since_today":{"post":{"operationId":"get_all_time_since_today","summary":"Get your total coding time since you started using WakaTime, or for one project, with the date range covered. Use for \"H","description":"Get your total coding time since you started using WakaTime, or for one project, with the date range covered. Use for \"How much time have I spent coding in total with WakaTime\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this project name.","title":"Project"}},"title":"get_all_time_since_todayArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_projects":{"post":{"operationId":"list_projects","summary":"List your WakaTime projects with repository, first and last activity time. Can filter by name. Use for \"Which projects h","description":"List your WakaTime projects with repository, first and last activity time. Can filter by name. Use for \"Which projects have I tracked time on in WakaTime\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only projects whose name contains this text.","title":"Q"}},"title":"list_projectsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_durations":{"post":{"operationId":"get_durations","summary":"Get your coding sessions for one day as blocks with start time, length in seconds and project (or another slice). Use fo","description":"Get your coding sessions for one day as blocks with start time, length in seconds and project (or another slice). Use for \"When did I code yesterday and on which projects\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"date":{"description":"Day to read, as YYYY-MM-DD in your account's timezone.","maxLength":10,"title":"Date","type":"string"},"project":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this project name.","title":"Project"},"branches":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated branch names to include.","title":"Branches"},"slice_by":{"anyOf":[{"enum":["project","entity","language","dependencies","os","editor","category","machine"],"type":"string"},{"type":"null"}],"default":null,"description":"How to split sessions: project, entity, language, dependencies, os, editor, category or machine (default project).","title":"Slice By"},"timeout":{"anyOf":[{"maximum":120,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Keystroke timeout in minutes used to merge activity into durations; leave out to use your account setting.","title":"Timeout"},"writes_only":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to count only time spent writing (saving files), false to count all activity; leave out to use your account setting.","title":"Writes Only"},"timezone":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"IANA timezone for the day, for example 'America/Los_Angeles'; leave out to use your account's.","title":"Timezone"}},"required":["date"],"title":"get_durationsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_heartbeats":{"post":{"operationId":"get_heartbeats","summary":"Get the raw activity records (heartbeats) of one day: file, language, project, branch, category and time. Use for \"What ","description":"Get the raw activity records (heartbeats) of one day: file, language, project, branch, category and time. Use for \"What files was I editing on 2026-10-01\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"date":{"description":"Day to read, as YYYY-MM-DD in your account's timezone.","maxLength":10,"title":"Date","type":"string"}},"required":["date"],"title":"get_heartbeatsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_goals":{"post":{"operationId":"list_goals","summary":"List your WakaTime coding goals with title, type, target seconds, status and the latest progress. Use for \"Am I on track","description":"List your WakaTime coding goals with title, type, target seconds, status and the latest progress. Use for \"Am I on track with my WakaTime goals\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_goalsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_insight":{"post":{"operationId":"get_insight","summary":"Get one insight over a period, such as your languages, editors, projects, categories, best day or weekday pattern, as re","description":"Get one insight over a period, such as your languages, editors, projects, categories, best day or weekday pattern, as returned by WakaTime. Use for \"Which programming languages did I use most in the last 30 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"insight_type":{"description":"Insight: stats, weekdays, days, ai_days, best_day, daily_average, projects, languages, editors, categories, machines or operating_systems.","enum":["stats","weekdays","days","ai_days","best_day","daily_average","projects","languages","editors","categories","machines","operating_systems"],"title":"Insight Type","type":"string"},"period":{"description":"Time range: last_7_days, last_30_days, last_6_months, last_year, all_time, a year like 2026 or a month like 2026-03.","maxLength":20,"title":"Period","type":"string"},"timeout":{"anyOf":[{"maximum":120,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Keystroke timeout in minutes used to merge activity into durations; leave out to use your account setting.","title":"Timeout"},"writes_only":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to count only time spent writing (saving files), false to count all activity; leave out to use your account setting.","title":"Writes Only"}},"required":["insight_type","period"],"title":"get_insightArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_leaders":{"post":{"operationId":"get_leaders","summary":"Get the public WakaTime leaderboard (top coders by time), optionally for one language or country, plus your own rank. Us","description":"Get the public WakaTime leaderboard (top coders by time), optionally for one language or country, plus your own rank. Use for \"Who are the top Python coders on WakaTime\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"language":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only coders of this programming language, for example 'Python'.","title":"Language"},"country_code":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter country code, for example 'US'.","title":"Country Code"},"board_type":{"anyOf":[{"enum":["time","manual","ai","spend"],"type":"string"},{"type":"null"}],"default":null,"description":"Board: time (default), manual (time excluding AI coding), ai (AI lines) or spend (AI spend).","title":"Board Type"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Page number, starting at 1.","title":"Page"}},"title":"get_leadersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}