Chronova logo
Log inSign up

API Reference

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

Last updated: October 16, 2026

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 Methods

Bearer Token
Authorization: Bearer API_KEY
Basic Auth
Authorization: Basic API_KEY
X-API-KEY Header
X-API-KEY: API_KEY
Query Parameter
?api_key=API_KEY

All methods are supported. Your API key: YOUR_API_KEY

API Information

Base URLhttps://chronova.dev
API Versionv1
Rate Limit
1,000 requests/hour
Standard API limit
Content Typeapplication/json

Authentication Examples

cURL

curl -X GET "https://chronova.dev/api/v1/users/current" \
 -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

const response = await fetch('https://chronova.dev/api/v1/users/current', {
 headers: {
 'Authorization': 'Bearer YOUR_API_KEY'
 }
})

Python

import requests
 
headers = {
 'Authorization': 'Bearer YOUR_API_KEY'
}
response = requests.get('https://chronova.dev/api/v1/users/current', headers=headers)

Metrics & streaming

SSE event stream and Prometheus metrics.

Rate limits

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/current

Fetch authenticated user profile and subscription state.

Important Notes

  • Requires Bearer token in the Authorization header.

Response Example

{
  "data": {
    "id": "user_123",
    "username": "johndoe",
    "display_name": "John Doe",
    "email": "user@example.com",
    "subscriptionPlan": "pro",
    "subscriptionStatus": "active",
    "languages_used_public": true,
    "projects_public": false,
    "created_at": "2024-01-01T00:00:00Z"
  }
}
PATCH/api/v1/users/current

Update public profile, privacy toggles, or display preferences.

Important Notes

  • 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/data-summary

Get comprehensive data overview including heartbeats, analytics, and goals.

Returns summary statistics for all user data including total coding time, project breakdown, and goal progress.

Important Notes

  • Provides GDPR-compliant data overview for compliance purposes.

Response Example

{
  "data": {
    "total_heartbeats": 15000,
    "total_coding_time": 450000,
    "projects_count": 12,
    "languages_count": 8,
    "goals_count": 3,
    "organizations_count": 2,
    "first_heartbeat": "2024-01-01T00:00:00Z",
    "last_heartbeat": "2024-11-29T22:00:00Z"
  }
}
POST/api/v1/users/current/export

Export user data in multiple formats (JSON, Markdown, XML, CSV, XLS).

Returns heartbeats, analytics, goals, and organization memberships in the requested format. Supports JSON, Markdown, XML, CSV, and XLS formats.

DELETE/api/v1/users/current/delete

Permanently delete user account and all associated data.

This action is irreversible and will delete all user data including heartbeats, analytics, goals, and organization memberships.

Important Notes

  • Irreversible action - all data will be permanently deleted.
  • Requires password and confirmation "DELETE MY ACCOUNT".
GET/api/v1/users/current/wakatime

Get WakaTime integration status and configuration.

Response Example

{
  "data": {
    "wakatime_sync_enabled": true,
    "wakatime_plan_status": "premium",
    "last_sync": "2024-11-29T21:30:00Z",
    "sync_jobs_count": 5,
    "imported_heartbeats": 12000
  }
}
PATCH/api/v1/users/current/wakatime

Update WakaTime integration settings.

Important Notes

  • WakaTime Premium required for full sync functionality.
DELETE/api/v1/users/current/wakatime

Disconnect WakaTime integration.

POST/api/v1/users/current/resend-verification

Resend email verification link.

Sends a new verification email if the previous one expired or was not received.

Important Notes

  • Limited to 3 resend attempts per hour.
POST/api/v1/users/current/send-verification-email

Send email verification for account activation.

Sends verification email to confirm email address ownership.

Important Notes

  • Automatically sent during registration, use resend-verification for expired links.
POST/api/v1/users/current/rotate-api-key

Rotate the current API key and generate a new one.

Invalidates the current API key and generates a new one. The old key will stop working immediately.

Important Notes

  • The old API key will be immediately invalidated.
  • Update your applications with the new key.

Request Example

{
  "password": "your_password"
}

Response Example

{
  "data": {
    "api_key": "waka_••••••••",
    "created_at": "2024-11-29T22:00:00Z"
  }
}
POST/api/v1/users/current/reset-heartbeats

Reset all heartbeats for the current user.

Permanently delete all heartbeat data for testing or cleanup purposes.

Important Notes

  • Irreversible action - all heartbeat data will be permanently deleted.
  • Requires password and confirmation.
GET/api/v1/users/current/api-key-history

Get API key rotation history for audit purposes.

Returns the last 10 API key rotations with timestamps and metadata.

Response Example

{
  "data": [
    {
      "id": "history_123",
      "rotatedAt": "2024-11-29T22:00:00Z",
      "rotatedBy": "user",
      "isActive": false
    }
  ]
}
GET/api/v1/users/current/org

Get user organization information and membership details.

Important Notes

  • Returns all organizations the user belongs to with role information.

Response Example

{
  "data": {
    "organizations": [
      {
        "id": "org_123",
        "name": "ACME Corporation",
        "role": "admin",
        "member_count": 15
      }
    ],
    "primary_organization": "org_123"
  }
}
POST/api/v1/users/current/org

Create or join an organization.

PATCH/api/v1/users/current/profile

Update profile (with CSRF protection).

Request Example

{
  "display_name": "John Smith",
  "is_profile_private": false
}
POST/api/v1/users/current/set-password

Set password for first-time OAuth users or password reset.

Allows users who registered via OAuth to set a password for API key access.

GET/api/v1/users/current/google/auth

Start the OAuth flow to connect Google to Chronova.

DELETE/api/v1/users/current/google/auth

Disconnect Google integration.

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. Add ?timezone= with an IANA name such as Europe/Berlin to start "today" at your local midnight; without it "today" follows the server clock. A range of at most one day also returns hourly_timeline, one bucket per hour keyed by its start in epoch seconds.

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 }
    ]
  }
}
GET/api/v1/users/current/all_time_since_today

Get all-time cumulative statistics.

Returns cumulative statistics for all time including total coding time, daily average, and breakdown by language, editor, and project.

Response Example

{
  "data": {
    "total_seconds": 864000,
    "daily_average": 2400,
    "languages": [
      { "name": "TypeScript", "total_seconds": 432000, "percent": 50.0 }
    ],
    "editors": [
      { "name": "VS Code", "total_seconds": 691200, "percent": 80.0 }
    ],
    "projects": [
      { "name": "chronova", "total_seconds": 518400, "percent": 60.0 }
    ]
  }
}
GET/api/v1/users/current/durations

Get detailed duration data for coding sessions.

Returns granular duration data including session start/end times, project, language, and editor information.

Response Example

{
  "data": [
    {
      "start_time": "2024-11-29T09:00:00Z",
      "end_time": "2024-11-29T17:00:00Z",
      "duration": 28800,
      "project": "chronova",
      "language": "TypeScript",
      "editor": "VS Code",
      "branch": "main"
    }
  ]
}
POST/api/v1/users/current/heartbeats

Submit 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/heartbeats

Retrieve heartbeats with pagination.

Supports query parameters: date, page, per_page.

POST/api/v1/users/current/heartbeats.bulk

Submit multiple heartbeats in a single request.

Bulk endpoint for submitting large numbers of heartbeats efficiently.

Important Notes

  • Maximum 1000 heartbeats per request.
  • Recommended for batch processing.
GET/api/v1/users/current/heartbeats.bulk

Retrieve heartbeats in bulk.

GET/api/v1/users/current/analytics/commit-correlation

Correlate commits with coding sessions to surface productivity patterns.

GET/api/v1/users/current/external_durations

Get external duration data from connected services.

Returns duration information from external integrations like GitHub, GitLab, etc.

Response Example

{
  "data": [
    {
      "service": "github",
      "repository": "username/chronova",
      "duration": 7200,
      "date": "2024-11-29",
      "commit_count": 5
    }
  ]
}
POST/api/v1/users/current/external_durations

Create external duration from connected services.

Request Example

{
  "entity": "project/repo/commit",
  "type": "external_duration",
  "project": "chronova",
  "start": 1701292800,
  "end": 1701300000,
  "timezone": "UTC"
}

Response Example

{
  "data": {
    "id": "ed_123",
    "entity": "project/repo/commit",
    "type": "external_duration",
    "project": "chronova",
    "duration": 7200,
    "start": 1701292800,
    "end": 1701300000
  }
}
DELETE/api/v1/users/current/external_durations

Delete external duration by ID.

Remove a specific external duration by its ID. Requires ID query parameter.

Important Notes

  • Delete requires `id` query parameter: `?id=ed_123`
GET/api/v1/users/current/analytics/ai

Get AI-assisted coding analytics.

Returns insights about AI tool usage, including time spent with AI editors, AI contribution percentage, and per-language AI breakdown. Accepts the same ?timezone= parameter as the stats endpoint, and returns hourlyTimeline for a range of at most one day.

Summaries & time

Aggregated daily summaries, streaks, and focus analytics.

GET/api/v1/users/current/summaries

Get daily coding summaries.

Aggregated daily summaries with language, project, and editor breakdowns. Supports query parameters: start, end, project, branches.

Response Example

{
  "data": [
    {
      "date": "2024-11-29",
      "total_seconds": 28800,
      "languages": [
        { "name": "TypeScript", "total_seconds": 18000 }
      ],
      "projects": [
        { "name": "chronova", "total_seconds": 20000 }
      ],
      "editors": [
        { "name": "VS Code", "total_seconds": 25200 }
      ]
    }
  ]
}
GET/api/v1/users/current/streaks

Get current streak information.

Streak data including current, longest, and history.

GET/api/v1/users/current/focus

Get focus metrics.

Focus time analysis including deep work sessions.

GET/api/v1/users/current/analytics/focus

Get detailed focus analytics.

Breakdown by project, language, and time of day.

GET/api/v1/users/current/statusbar/today

Get today's statusbar summary.

Lightweight endpoint for editor statusbar plugins.

Organizations & invites

Manage teams, roles, invitations, and billing context.

GET/api/v1/organizations

List organizations for current user.

POST/api/v1/organizations

Create a new organization.

Request Example

{
  "name": "My Team",
  "slug": "my-team",
  "description": "Development team"
}
GET/api/v1/organizations/{orgId}

Get organization details including name, description, and subscription status.

Response Example

{
  "data": {
    "id": "org_123",
    "name": "ACME Corporation",
    "slug": "acme-corp",
    "description": "Leading software development company",
    "subscription_plan": "team",
    "subscription_status": "active",
    "member_count": 15,
    "created_at": "2024-01-01T00:00:00Z"
  }
}
PATCH/api/v1/organizations/{orgId}

Update organization name, description, or settings.

Important Notes

  • Requires admin or owner role in the organization.
DELETE/api/v1/organizations/{orgId}

Permanently delete an organization and all associated data.

This action is irreversible and will delete all organization data including member records, projects, and analytics.

Important Notes

  • Irreversible action - all organization data will be permanently deleted.
  • Requires owner role in the organization.
GET/api/v1/organizations/{orgId}/public

Get public organization information for display on public profiles.

Important Notes

  • Returns only publicly visible information.

Response Example

{
  "data": {
    "id": "org_123",
    "name": "ACME Corporation",
    "slug": "acme-corp",
    "description": "Leading software development company",
    "member_count": 15,
    "public_projects_count": 8
  }
}
GET/api/v1/organizations/{orgId}/members

List organization members.

POST/api/v1/organizations/{orgId}/members

Add a member to the organization.

PATCH/api/v1/organizations/{orgId}/members/{memberId}

Update member role or permissions within the organization.

Important Notes

  • Requires admin or owner role in the organization.
DELETE/api/v1/organizations/{orgId}/members/{memberId}

Remove a member from the organization.

Important Notes

  • Requires admin or owner role in the organization.
  • Member will lose access to all organization resources.
GET/api/v1/organizations/{orgId}/invites

List organization invites.

POST/api/v1/organizations/{orgId}/invites

Send an invitation to join the organization.

Request Example

{
  "email": "newmember@example.com",
  "role": "member"
}
GET/api/v1/organizations/{orgId}/billing

Get billing information for the organization.

POST/api/v1/organizations/{orgId}/billing

Update billing information for the organization.

GET/api/v1/organizations/{orgId}/analytics

Get organization analytics with member activity and project breakdown.

GET/api/v1/organizations/{orgId}/analytics/ai

Get AI-assisted coding analytics for the organization.

Returns AI tool usage insights across organization members.

GET/api/v1/organizations/{orgId}/logo

Get organization logo.

PUT/api/v1/organizations/{orgId}/logo

Upload or replace organization logo.

Accepts multipart/form-data uploads.

DELETE/api/v1/organizations/{orgId}/logo

Remove organization logo.

GET/api/v1/users/current/orgs

List organizations the current user belongs to.

Response Example

{
  "data": [
    {
      "id": "org_123",
      "name": "ACME Corporation",
      "slug": "acme-corp",
      "role": "admin",
      "memberCount": 15,
      "subscriptionPlan": "team"
    }
  ]
}
GET/api/v1/users/current/orgs/{org}/dashboards

Get organization dashboards.

GET/api/v1/users/current/orgs/{org}/dashboards/{dashboard}/members

Get dashboard members.

GET/api/v1/users/current/orgs/{org}/dashboards/{dashboard}/summaries

Get dashboard summaries.

GET/api/v1/invitations/{token}

View invitation details.

Unauthenticated endpoint to view invitation details before accepting.

POST/api/v1/invitations/{token}

Accept an invitation.

DELETE/api/v1/invitations/{token}

Decline or revoke an invitation.

Goals & personal tracking

Create, query, and analyze personal productivity goals.

GET/api/v1/users/current/goals

List 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/goals

Create a new goal for language, project, or editor usage.

Request Example

{
  "type": "daily",
  "target_seconds": 14400,
  "language": "TypeScript"
}
DELETE/api/v1/users/current/goals

Soft-delete a goal by ID.

Important Notes

  • This performs a soft delete - sets isEnabled to false rather than removing from database.
GET/api/v1/users/current/goals/analytics

Access goal analytics including streaks and achievement ratios.

GET/api/v1/users/current/goals/suggestions

Get personalized goal suggestions based on coding patterns.

Returns AI-powered goal suggestions tailored to your coding habits, project focus, and historical productivity data.

Response Example

{
  "data": {
    "suggestions": [
      {
        "type": "daily",
        "target_seconds": 14400,
        "language": "TypeScript",
        "confidence": 0.85,
        "reason": "You spend 75% of your time on TypeScript projects"
      }
    ],
    "next_refresh": "2024-11-30T02:00:00Z"
  }
}

GitHub integration

Sync repositories and correlate commits with heartbeats.

GET/api/v1/users/current/github/repositories

List 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"
    }
  ]
}
PUT/api/v1/users/current/github/repositories

Update GitHub repository settings.

POST/api/v1/users/current/github/repositories/refresh

Refresh the list of connected GitHub repositories.

Force a refresh of the GitHub repository list to get the latest repository information.

Important Notes

  • Requires active GitHub OAuth connection.
GET/api/v1/users/current/github/auth

Start the OAuth flow to connect GitHub to Chronova.

DELETE/api/v1/users/current/github/auth

Disconnect GitHub integration.

GET/api/v1/users/current/projects

List all tracked projects with metadata and coding statistics.

Response Example

{
  "data": [
    {
      "name": "chronova",
      "repository": "username/chronova",
      "total_seconds": 86400,
      "last_activity": "2024-11-29T22:00:00Z",
      "language_breakdown": {
        "TypeScript": 64800,
        "JavaScript": 21600
      }
    }
  ]
}
GET/api/v1/users/current/projects/privacy

Get project privacy settings.

PATCH/api/v1/users/current/projects/privacy

Update project privacy settings.

GET/api/v1/users/current/projects/{project}/commits

Retrieve commits for a project with correlated coding time.

GET/api/v1/users/current/projects/{project}/commits/{hash}

Get specific commit details.

POST/api/v1/users/current/sync/commits

Sync commits from connected repositories.

GET/api/v1/users/current/sync/commits

Get commit sync status.

POST/api/v1/users/current/coupons/validate

Validate a promotional coupon code.

Request Example

{
  "code": "WELCOME2024"
}
GET/api/v1/github/releases/latest?repo={chronova-cli|chronova-mcp|chronova-android}

Get the latest Chronova release information.

Returns version, release notes, and download links for the latest release of a Chronova repository (chronova-cli, chronova-mcp, or chronova-android; defaults to chronova-cli).

WakaTime Integration

Sync, export, and manage WakaTime data migration.

POST/api/v1/wakatime/sync

Start a WakaTime data sync job.

Initiates synchronization of WakaTime data including heartbeats, summaries, and projects.

Important Notes

  • WakaTime Premium required for full sync functionality.
  • Sync jobs run asynchronously.
POST/api/v1/wakatime/export

Export WakaTime data to Chronova format.

Export WakaTime data for backup or migration purposes.

GET/api/v1/wakatime/jobs/{jobId}

Get status and progress of a WakaTime sync/export job.

Response Example

{
  "data": {
    "id": "job_123",
    "type": "sync",
    "status": "running",
    "progress": 65,
    "total_items": 15000,
    "processed_items": 9750,
    "started_at": "2024-11-29T22:00:00Z",
    "estimated_completion": "2024-11-29T23:30:00Z"
  }
}
DELETE/api/v1/wakatime/jobs/{jobId}

Cancel a running WakaTime sync/export job.

Important Notes

  • Only running jobs can be cancelled.
  • Partial data may be retained.
GET/api/v1/wakatime/jobs/{jobId}/stream

Stream real-time progress updates for a WakaTime job.

Uses Server-Sent Events (SSE) for real-time updates.

Important Notes

  • Uses Server-Sent Events (SSE) for real-time updates.
GET/api/v1/users/current/wakatime/jobs

List all WakaTime sync/export jobs for the current user.

Response Example

{
  "data": [
    {
      "id": "job_123",
      "type": "sync",
      "status": "completed",
      "progress": 100,
      "started_at": "2024-11-29T22:00:00Z",
      "completed_at": "2024-11-29T23:30:00Z",
      "total_items": 15000,
      "successful_items": 14980,
      "failed_items": 20
    }
  ]
}

WakaTime compatibility layer

Drop-in endpoints for WakaTime CLI and plugins.

GET/api/v1/compat/waka/users/current

Return user info using WakaTime field names.

POST/api/v1/compat/waka/users/current/heartbeats

Accept heartbeat payloads in WakaTime JSON format.

GET/api/v1/compat/waka/users/current/heartbeats

Get heartbeats in WakaTime format.

GET/api/v1/compat/waka/users/current/stats/{range}

Stats endpoint mirroring the WakaTime API contract.

GET/api/v1/compat/waka/users/current/summaries

Return summaries in a structure compatible with WakaTime dashboards.

GET/api/v1/compat/waka/users/current/projects

Return projects in WakaTime format.

Response Example

{
  "data": [
    {
      "id": "project_123",
      "name": "chronova",
      "repository": "username/chronova",
      "last_heartbeat": "2024-11-29T22:00:00Z",
      "total_seconds": 86400
    }
  ]
}

Metrics & streaming

Prometheus metrics and real-time SSE event stream.

GET/api/v1/events/stream

Server-Sent Events stream for real-time dashboard updates.

Returns a persistent SSE connection. Events include heartbeat updates, goal progress, and organization activity. Falls back to keep-alive when Redis pub/sub is unavailable.

Important Notes

  • Content-Type: text/event-stream
  • Requires authenticated session or API key.
GET/api/v1/metrics

Prometheus-format application metrics.

Exposes request counters, latency histograms, and cache hit/miss metrics for scraping by Prometheus.

Public & community

Leaderboards, public profiles, and platform statistics.

GET/api/v1/leaders

Get leaderboard data.

Top contributors ranked by coding activity.

GET/api/v1/public/stats

Get public platform statistics.

Aggregated public stats about the Chronova platform.

GET/api/v1/users/{user}

Get public user profile by username.

Returns publicly visible profile information.

GET/api/v1/users/{user}/stats/{range}

Get public user statistics.

Public stats if user's profile is not private.

GET/api/v1/users/{user}/goals

Get public user goals.

Public goals if user has made them visible.

Onboarding

Setup wizard progress and the dashboard tour, tracked per user.

GET/api/v1/onboarding/status

Get wizard progress.

Creates the status on first request; a user who already has heartbeats starts out completed.

POST/api/v1/onboarding/step-complete

Record a wizard step.

Body: step_id (choose-tool, connect, first-heartbeat, first-goal), optional tool and time_spent_ms.

POST/api/v1/onboarding/dismiss

Dismiss the wizard for now.

Resumable; the next step-complete clears it.

POST/api/v1/onboarding/complete

Complete the wizard.

Returns 409 until the first heartbeat has arrived.

POST/api/v1/onboarding/skip

Skip the wizard.

POST/api/v1/onboarding/tour-complete

Record the end of the dashboard tour.

Body: outcome, either finished or closed.

POST/api/v1/onboarding/reset

Reset wizard progress.

Run the wizard again from the start.

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 support@nx-solutions.de with request logs or CLI output (wakatime --today) for rapid assistance.