openapi: 3.0.3
info:
  title: WakaTime Commits Leaderboards API
  version: v1
  description: 'WakaTime API v1 provides automated time-tracking analytics for software developers. IDE

    plugins (VS Code, JetBrains, Vim, Emacs, Sublime, Xcode, Visual Studio, Eclipse, Zed, and

    many more) send "heartbeats" describing the file, project, language, branch, and editor a

    developer is working in. WakaTime aggregates that data into dashboards, summaries, stats,

    goals, leaderboards, and team/org dashboards.


    Authentication is via OAuth 2.0 (authorize / token / revoke) with scopes such as

    `read_summaries`, `read_stats`, `read_goals`, `read_heartbeats`, `write_heartbeats`,

    `read_orgs`, `write_orgs`, and `email`, or via API Key (HTTP Basic auth or `?api_key=`)

    for personal use. The default rate limit is fewer than 10 requests per second on average

    over any 5-minute window.


    All responses follow the pattern `{"data": ...}` for successful requests or

    `{"error": "message"}` for errors.

    '
  contact:
    name: WakaTime Support
    url: https://wakatime.com/contact
    email: support@wakatime.com
  termsOfService: https://wakatime.com/terms
  license:
    name: WakaTime Terms of Service
    url: https://wakatime.com/terms
  x-generated-from: documentation
  x-source-url: https://wakatime.com/developers
  x-last-validated: '2026-05-30'
servers:
- url: https://wakatime.com/api/v1
  description: WakaTime production API
- url: https://api.wakatime.com/api/v1
  description: WakaTime alternate hostname
security:
- oauth2: []
- apiKey: []
- bearerAuth: []
tags:
- name: Leaderboards
  description: Public and private leaderboard rankings.
paths:
  /leaders:
    get:
      operationId: listLeaders
      summary: List Leaders
      description: Returns the public WakaTime leaderboard.
      tags:
      - Leaderboards
      parameters:
      - name: language
        in: query
        description: Filter by programming language.
        schema:
          type: string
        example: example
      - name: country_code
        in: query
        description: Filter by ISO country code.
        schema:
          type: string
        example: example
      - name: page
        in: query
        schema:
          type: integer
          minimum: 1
        example: 1
      responses:
        '200':
          description: Leaderboard payload.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/LeaderEntry'
              examples:
                ListLeaders200Example:
                  summary: Default listLeaders 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - rank: 1
                      running_total: {}
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users/current/private_leaderboards:
    get:
      operationId: listPrivateLeaderboards
      summary: List Private Leaderboards
      description: Returns the authenticated user's private leaderboards.
      tags:
      - Leaderboards
      responses:
        '200':
          description: Private leaderboards.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users/current/private_leaderboards/{id}/leaders:
    get:
      operationId: listPrivateLeaderboardLeaders
      summary: List Private Leaderboard Leaders
      description: Returns rankings for a specific private leaderboard.
      tags:
      - Leaderboards
      parameters:
      - name: id
        in: path
        required: true
        description: Private leaderboard id.
        schema:
          type: string
        example: example
      responses:
        '200':
          description: Private leaderboard rankings.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    User:
      type: object
      description: The authenticated WakaTime user profile.
      x-schema-source: documentation
      x-source-url: https://wakatime.com/developers
      properties:
        id:
          type: string
          example: 5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
        username:
          type: string
          nullable: true
          example: kinlane
        display_name:
          type: string
          example: Kin Lane
        full_name:
          type: string
          nullable: true
          example: Kin Lane
        email:
          type: string
          format: email
          nullable: true
          example: support@example.com
        photo:
          type: string
          format: uri
          example: https://wakatime.com/photo/5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
        photo_public:
          type: boolean
          example: true
        is_email_public:
          type: boolean
          example: true
        is_email_confirmed:
          type: boolean
          example: true
        timezone:
          type: string
          example: America/Los_Angeles
        last_heartbeat_at:
          type: string
          format: date-time
          nullable: true
          example: '2026-05-30T12:34:56Z'
        last_plugin:
          type: string
          nullable: true
          example: vscode-wakatime/24.0.0 vscode-wakatime/24.0.0
        last_plugin_name:
          type: string
          nullable: true
          example: vscode
        last_project:
          type: string
          nullable: true
          example: wakatime-cli
        plan:
          type: string
          enum:
          - free
          - basic
          - premium
          - team
          - business
          example: free
        bio:
          type: string
          nullable: true
          example: Founder of API Evangelist.
        location:
          type: string
          nullable: true
          example: Hermosa Beach, CA
        languages_used_public:
          type: boolean
          example: true
        logged_time_public:
          type: boolean
          example: true
        website:
          type: string
          format: uri
          nullable: true
          example: https://wakatime.com
        human_readable_website:
          type: string
          nullable: true
          example: wakatime.com
        wonderfuldev_username:
          type: string
          nullable: true
          example: kinlane
        github_username:
          type: string
          nullable: true
          example: kinlane
        twitter_username:
          type: string
          nullable: true
          example: kinlane
        linkedin_username:
          type: string
          nullable: true
          example: kinlane
        created_at:
          type: string
          format: date-time
          example: '2026-05-30T12:34:56Z'
        modified_at:
          type: string
          format: date-time
          nullable: true
          example: '2026-05-30T12:34:56Z'
    LeaderEntry:
      type: object
      properties:
        rank:
          type: integer
          example: 1
        running_total:
          type: object
          properties:
            total_seconds:
              type: number
              format: float
            human_readable_total:
              type: string
            daily_average:
              type: number
              format: float
            human_readable_daily_average:
              type: string
            languages:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  total_seconds:
                    type: number
                    format: float
          example: {}
        user:
          $ref: '#/components/schemas/User'
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authorization code flow.
      flows:
        authorizationCode:
          authorizationUrl: https://wakatime.com/oauth/authorize
          tokenUrl: https://wakatime.com/oauth/token
          refreshUrl: https://wakatime.com/oauth/token
          scopes:
            email: Read user email.
            read_summaries: Read coding-activity summaries.
            read_stats: Read aggregate stats.
            read_goals: Read coding goals.
            read_heartbeats: Read raw heartbeats.
            write_heartbeats: Send heartbeats.
            read_orgs: Read organization data.
            write_orgs: Modify organization data.
        implicit:
          authorizationUrl: https://wakatime.com/oauth/authorize
          scopes:
            email: Read user email.
            read_summaries: Read coding-activity summaries.
            read_stats: Read aggregate stats.
            read_goals: Read coding goals.
            read_heartbeats: Read raw heartbeats.
            write_heartbeats: Send heartbeats.
            read_orgs: Read organization data.
            write_orgs: Modify organization data.
    apiKey:
      type: http
      scheme: basic
      description: HTTP Basic with the WakaTime API key as the username. Alternatively, pass `?api_key=...` as a query parameter.
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth access token in the Authorization header as `Bearer waka_tok_...`.