openapi: 3.0.3
info:
  title: WakaTime Commits Users 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: Users
  description: Authenticated user profile and public user lookups.
paths:
  /users/current:
    get:
      operationId: getCurrentUser
      summary: Get Current User
      description: Returns the authenticated user's profile.
      tags:
      - Users
      security:
      - oauth2:
        - email
      - apiKey: []
      responses:
        '200':
          description: The authenticated user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/User'
              examples:
                GetCurrentUser200Example:
                  summary: Default getCurrentUser 200 response
                  x-microcks-default: true
                  value:
                    data:
                      id: 5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
                      username: kinlane
                      display_name: Kin Lane
                      full_name: Kin Lane
                      email: support@example.com
                      photo: https://wakatime.com/photo/5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
                      photo_public: true
                      is_email_public: true
                      is_email_confirmed: true
                      timezone: America/Los_Angeles
                      last_heartbeat_at: '2026-05-30T12:34:56Z'
                      last_plugin: vscode-wakatime/24.0.0 vscode-wakatime/24.0.0
                      last_plugin_name: vscode
                      last_project: wakatime-cli
                      plan: free
                      bio: Founder of API Evangelist.
                      location: Hermosa Beach, CA
                      languages_used_public: true
                      logged_time_public: true
                      website: https://wakatime.com
                      human_readable_website: wakatime.com
                      wonderfuldev_username: kinlane
                      github_username: kinlane
                      twitter_username: kinlane
                      linkedin_username: kinlane
                      created_at: '2026-05-30T12:34:56Z'
                      modified_at: '2026-05-30T12:34:56Z'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users/{user}:
    get:
      operationId: getUser
      summary: Get User
      description: Returns the public profile for the given user.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/UserPath'
      responses:
        '200':
          description: The requested user's public profile.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PublicUser'
              examples:
                GetUser200Example:
                  summary: Default getUser 200 response
                  x-microcks-default: true
                  value:
                    data:
                      id: 5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
                      username: kinlane
                      display_name: Kin Lane
                      full_name: Kin Lane
                      email: support@example.com
                      photo: https://wakatime.com/photo/5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
                      photo_public: true
                      is_email_public: true
                      is_email_confirmed: true
                      timezone: America/Los_Angeles
                      last_heartbeat_at: '2026-05-30T12:34:56Z'
                      last_plugin: vscode-wakatime/24.0.0 vscode-wakatime/24.0.0
                      last_plugin_name: vscode
                      last_project: wakatime-cli
                      plan: free
                      bio: Founder of API Evangelist.
                      location: Hermosa Beach, CA
                      languages_used_public: true
                      logged_time_public: true
                      website: https://wakatime.com
                      human_readable_website: wakatime.com
                      wonderfuldev_username: kinlane
                      github_username: kinlane
                      twitter_username: kinlane
                      linkedin_username: kinlane
                      created_at: '2026-05-30T12:34:56Z'
                      modified_at: '2026-05-30T12:34:56Z'
      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'
    PublicUser:
      allOf:
      - $ref: '#/components/schemas/User'
  parameters:
    UserPath:
      name: user
      in: path
      required: true
      description: User id, username, or "current".
      schema:
        type: string
      example: example
  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_...`.