Chronova logo

API Reference

Chronova exposes a modern JSON API, fully compatible with existing WakaTime tooling

Welcome, developers

The Chronova API mirrors familiar WakaTime endpoints while giving you full control over your data. Authenticate with API keys, send heartbeats, and pull analytics without changing your existing tooling.

Authentication
Authorization: Bearer YOUR_API_KEY

Generate keys in Settings → API. Keys inherit all permissions granted to the owning user.

Base URL
https://chronova.dev/api/v1

Self-hosted deployments replace the hostname with your own domain.

Rate limiting

1,000 requests per hour per API key. Batch heartbeats in a single POST to stay within limits.

Last updated: September 18, 2025

Authentication

Generate API keys and send requests securely.

Rate limits

Understand throughput limits and best practices.

SDKs & tooling

CLI, editor plugins, and migration utilities.

User management

Profile data, privacy preferences, and GDPR exports.

GET/api/v1/users/currentFetch authenticated user profile and subscription state.
  • Requires Bearer token in the Authorization header.

Response example

{
  "data": {
    "id": "user_123",
    "username": "johndoe",
    "display_name": "John Doe",
    "email": "john@example.com",
    "subscriptionPlan": "pro",
    "subscriptionStatus": "active",
    "languages_used_public": true,
    "projects_public": false,
    "created_at": "2024-01-01T00:00:00Z"
  }
}
PATCH/api/v1/users/currentUpdate public profile, privacy toggles, or display preferences.
  • Send only the fields you wish to update.

Request example

{
  "display_name": "John Smith",
  "is_profile_private": false,
  "languages_used_public": true,
  "projects_public": false,
  "displayMinimumDuration": 1
}
GET/api/v1/users/current/exportDownload a complete JSON export for GDPR compliance.

Returns heartbeats, analytics, goals, and organization memberships in a single archive.

Analytics & heartbeats

Pull statistics or push coding heartbeats to Chronova.

GET/api/v1/users/current/stats/{range}Retrieve time-tracking statistics for a predefined range.

Valid ranges: today, yesterday, last_7_days, last_30_days, last_6_months, last_year.

Response example

{
  "data": {
    "total_seconds": 28800,
    "daily_average": 4800,
    "languages": [
      { "name": "TypeScript", "total_seconds": 18000, "percent": 62.5 }
    ],
    "editors": [
      { "name": "VS Code", "total_seconds": 25200, "percent": 87.5 }
    ],
    "projects": [
      { "name": "chronova", "total_seconds": 20000, "percent": 69.4 }
    ]
  }
}
POST/api/v1/users/current/heartbeatsSubmit one or many activity heartbeats.

Request example

[
  {
    "entity": "/path/to/file.ts",
    "type": "file",
    "time": 1640995200,
    "language": "TypeScript",
    "editor": "VS Code",
    "project": "chronova",
    "branch": "main",
    "is_write": true
  }
]
GET/api/v1/users/current/analytics/commit-correlationCorrelate commits with coding sessions to surface productivity patterns.

Organizations & invites

Manage teams, roles, invitations, and billing context.

GET/api/v1/users/current/orgsList organizations the current user belongs to.

Response example

{
  "data": [
    {
      "id": "org_123",
      "name": "ACME Corporation",
      "slug": "acme-corp",
      "role": "admin",
      "memberCount": 15,
      "subscriptionPlan": "team"
    }
  ]
}
POST/api/v1/organizationsCreate a new organization with optional description.

Request example

{
  "name": "My Team",
  "slug": "my-team",
  "description": "Development team for awesome projects"
}
GET/api/v1/organizations/{orgId}/membersRetrieve members, roles, and join metadata for an organization.
POST/api/v1/organizations/{orgId}/invitesSend invitations to join an organization.

Request example

{
  "email": "newmember@example.com",
  "role": "member"
}

Goals & personal tracking

Create, query, and analyze personal productivity goals.

GET/api/v1/users/current/goalsList configured goals with progress metrics.

Response example

{
  "data": [
    {
      "id": "goal_123",
      "type": "daily",
      "target_seconds": 14400,
      "language": "TypeScript",
      "progress": {
        "current_seconds": 10800,
        "percentage": 75,
        "streak": 5
      }
    }
  ]
}
POST/api/v1/users/current/goalsCreate a new goal for language, project, or editor usage.

Request example

{
  "type": "daily",
  "target_seconds": 14400,
  "language": "TypeScript",
  "project": "chronova"
}
GET/api/v1/users/current/goals/analyticsAccess goal analytics including streaks and achievement ratios.

GitHub integration

Sync repositories and correlate commits with heartbeats.

GET/api/v1/users/current/github/repositoriesList connected GitHub repositories with metadata.

Response example

{
  "data": [
    {
      "id": "repo_123",
      "full_name": "username/chronova",
      "html_url": "https://github.com/username/chronova",
      "description": "Time tracking platform",
      "private": false,
      "default_branch": "main"
    }
  ]
}
POST/api/v1/users/current/github/authStart the OAuth flow to connect GitHub to Chronova.
GET/api/v1/users/current/projects/{project}/commitsRetrieve commits for a project with correlated coding time.

WakaTime compatibility layer

Drop-in endpoints for WakaTime CLI and plugins.

GET/api/v1/compat/waka/users/currentReturn user info using WakaTime field names.
POST/api/v1/compat/waka/users/current/heartbeatsAccept heartbeat payloads in WakaTime JSON format.
GET/api/v1/compat/waka/users/current/stats/{range}Stats endpoint mirroring the WakaTime API contract.
GET/api/v1/compat/waka/users/current/summariesReturn summaries in a structure compatible with WakaTime dashboards.

Trademark notice

Chronova is not affiliated with WakaTime LLC. WakaTime® is a registered trademark of WakaTime LLC. Compatibility endpoints exist solely to ease migration from the WakaTime service.

Need help integrating?

Email contact@chronova.dev with request logs or CLI output (wakatime --today) for rapid assistance.