WakaTime Swagger API Documentation

openapi.yaml

openapi: 3.0.0
info:
  title: WakaTime API
  version: v1
  description: |
    REST API for accessing your WakaTime coding activity stats.
    - Uses GET for retrieval, POST/PUT/PATCH for modification.
    - All requests must use HTTPS.
    - Responses are JSON objects. Data is in the `data` key, errors in `error` or `errors`.
    - Refer to WakaTime usage guidelines when using the trademark or logo.
  contact:
    url: https://wakatime.com/contact
  license:
    name: WakaTime API Terms
    url: https://wakatime.com/terms
servers:
  - url: https://api.wakatime.com/api/v1
    description: Production WakaTime API server
tags:
  - name: Users
    description: Operations related to user data, profiles, and settings.
  - name: Stats
    description: Accessing aggregated coding statistics over various time ranges.
  - name: Summaries
    description: Accessing daily summaries of coding activity.
  - name: Heartbeats
    description: Raw coding activity events.
  - name: Durations
    description: Processed coding activity durations derived from heartbeats.
  - name: External Durations
    description: Coding activity from external sources (e.g., Calendar).
  - name: Projects
    description: Operations related to specific projects tracked by WakaTime.
  - name: Commits
    description: Accessing commit data linked to coding activity.
  - name: Goals
    description: Managing and viewing coding goals.
  - name: Leaderboards
    description: Accessing public and private leaderboards.
  - name: Organizations
    description: Operations related to WakaTime organizations and dashboards.
  - name: Data Dumps
    description: Managing exports of user coding data.
  - name: Insights
    description: Specific calculated insights based on coding activity.
  - name: Meta
    description: General API metadata.
  - name: Resources
    description: Information about supported resources like editors and languages.
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 Authorization Code Grant for user-delegated access.
      flows:
        authorizationCode:
          authorizationUrl: https://wakatime.com/oauth/authorize
          tokenUrl: https://wakatime.com/oauth/token
          refreshUrl: https://wakatime.com/oauth/token # Same endpoint for refresh
          scopes:
            read_summaries: Access Summaries and Stats (categories, dependencies, editors, languages, machines, operating systems, projects).
            read_summaries.categories: Access Summaries and Stats (limited to categories).
            read_summaries.dependencies: Access Summaries and Stats (limited to dependencies).
            read_summaries.editors: Access Summaries and Stats (limited to editors).
            read_summaries.languages: Access Summaries and Stats (limited to languages).
            read_summaries.machines: Access Summaries and Stats (limited to machines).
            read_summaries.operating_systems: Access Summaries and Stats (limited to operating systems).
            read_summaries.projects: Access Summaries and Stats (limited to projects).
            read_stats: Access Stats (categories, dependencies, editors, languages, machines, operating systems, projects).
            read_stats.best_day: Access Stats (limited to best day).
            read_stats.categories: Access Stats (limited to categories).
            read_stats.dependencies: Access Stats (limited to dependencies).
            read_stats.editors: Access Stats (limited to editors).
            read_stats.languages: Access Stats (limited to languages).
            read_stats.machines: Access Stats (limited to machines).
            read_stats.operating_systems: Access Stats (limited to operating systems).
            read_stats.projects: Access Stats (limited to projects).
            read_goals: Access Goals.
            read_orgs: Access organizations and dashboard member activity.
            write_orgs: Modify organizations and dashboards.
            read_private_leaderboards: Access private leaderboards.
            write_private_leaderboards: Modify private leaderboards.
            read_heartbeats: Access coding activity, projects, files, editors, languages, OS, dependencies, Stats, Durations, External Durations, and Heartbeats.
            write_heartbeats: Modify coding activity (create, edit, delete Heartbeats and External Durations).
            email: Access user's private email address.
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication using your Secret API Key (Base64 encoded). **Do NOT use in public websites.**
    apiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Authenticate using your Secret API Key as a query parameter. **Do NOT use in public websites.**

  schemas:
    # Basic Types & Common Structures
    Range:
      type: object
      properties:
        start:
          type: string
          format: date-time
          description: Start of the time range as ISO 8601 UTC datetime.
        end:
          type: string
          format: date-time
          description: End of the time range as ISO 8601 UTC datetime.
        start_date:
          type: string
          format: date
          description: Start date as Date string in YEAR-MONTH-DAY format.
        end_date:
          type: string
          format: date
          description: End date as Date string in YEAR-MONTH-DAY format.
        start_text:
          type: string
          description: Start of range in human-readable format.
        end_text:
          type: string
          description: End of range in human-readable format.
        date:
          type: string
          format: date
          description: The specific date for this data point (e.g., in summaries, goals chart).
        text:
          type: string
          description: The time range in human-readable format.
        timezone:
          type: string
          description: Timezone used in Olson Country/Region format (e.g., "America/Los_Angeles").
        name:
          type: string
          description: Name of the range (e.g., "last_7_days").
    GrandTotal:
      type: object
      properties:
        decimal:
          type: string
          description: Total coding activity in decimal format.
        digital:
          type: string
          description: Total coding activity in digital clock format (HH:MM).
        hours:
          type: integer
          description: Hours portion of coding activity.
        minutes:
          type: integer
          description: Minutes portion of coding activity.
        text:
          type: string
          description: Total coding activity in human readable format (e.g., "3 hrs 45 mins").
        total_seconds:
          type: number
          format: float
          description: Total coding activity as seconds.
    CategoryStat:
      type: object
      properties:
        name:
          type: string
          description: Name of the category (e.g., "Coding", "Debugging").
        total_seconds:
          type: number
          format: float
          description: Total coding activity as seconds.
        percent:
          type: number
          format: float
          description: Percent of time spent in this category.
        digital:
          type: string
          description: Total coding activity for this category in digital clock format.
        text:
          type: string
          description: Total coding activity in human readable format.
        hours:
          type: integer
          description: Hours portion of coding activity for this category.
        minutes:
          type: integer
          description: Minutes portion of coding activity for this category.
        seconds:
          type: integer
          description: Seconds portion of coding activity for this category.
    ProjectStat:
      allOf:
        - $ref: '#/components/schemas/CategoryStat' # Shares most fields
        - type: object
          properties:
            name:
              type: string
              description: Project name.
    LanguageStat:
      allOf:
        - $ref: '#/components/schemas/CategoryStat' # Shares most fields
        - type: object
          properties:
            name:
              type: string
              description: Language name.
    EditorStat:
      allOf:
        - $ref: '#/components/schemas/CategoryStat' # Shares most fields
        - type: object
          properties:
            name:
              type: string
              description: Editor name.
    OperatingSystemStat:
      allOf:
        - $ref: '#/components/schemas/CategoryStat' # Shares most fields
        - type: object
          properties:
            name:
              type: string
              description: Operating system name.
    DependencyStat:
      allOf:
        - $ref: '#/components/schemas/CategoryStat' # Shares most fields
        - type: object
          properties:
            name:
              type: string
              description: Dependency name.
    MachineStat:
      allOf:
        - $ref: '#/components/schemas/CategoryStat' # Shares most fields
        - type: object
          properties:
            name:
              type: string
              description: Machine hostname and IP address.
            machine_name_id:
              type: string
              description: Unique ID of this machine.
    BranchStat:
      allOf:
        - $ref: '#/components/schemas/CategoryStat' # Shares most fields
        - type: object
          properties:
            name:
              type: string
              description: Branch name.
    EntityStat:
      allOf:
        - $ref: '#/components/schemas/CategoryStat' # Shares most fields
        - type: object
          properties:
            name:
              type: string
              description: Entity name (e.g., file path).
    City:
      type: object
      properties:
        country_code:
          type: string
          description: Two letter country code (e.g., US, UK).
        name:
          type: string
          description: City name (e.g., San Francisco).
        state:
          type: string
          description: State name (e.g., California).
        title:
          type: string
          description: Combined location string (e.g., "San Francisco, CA").
    UserSummary:
      type: object
      description: Basic user information.
      properties:
        id:
          type: string
          description: Unique ID of the user.
        email:
          type: string
          format: email
          description: Email address (may be null if not public or permitted).
        username:
          type: string
          description: User's public username.
        full_name:
          type: string
          description: Full name of the user.
        display_name:
          type: string
          description: Display name (from full_name or username).
        website:
          type: string
          format: url
          description: User's website URL.
        human_readable_website:
          type: string
          description: Website without protocol.
        is_hireable:
          type: boolean
          description: Represents the 'hireable' badge status.
        city:
          $ref: '#/components/schemas/City'
        is_email_public:
          type: boolean
          description: Whether the user's email is public on leaderboards.
        photo_public:
          type: boolean
          description: Whether the user's photo is public on leaderboards.
        photo:
          type: string
          format: url
          description: URL of the user's photo.
    Repository:
      type: object
      properties:
        default_branch:
          type: string
          description: Default branch name.
        description:
          type: string
          description: Repository description.
        fork_count:
          type: integer
          description: Number of forks.
        full_name:
          type: string
          description: Full repository name (e.g., "wakatime/wakatime-cli").
        homepage:
          type: string
          format: url
          description: Repository homepage URL.
        html_url:
          type: string
          format: url
          description: HTML URL for the repository.
        id:
          type: string # Often numeric, but API docs use string type
          description: Unique ID of the repository.
        is_fork:
          type: boolean
          description: Whether the repository is a fork.
        is_private:
          type: boolean
          description: Whether the repository is private.
        last_synced_at:
          type: string
          format: date-time
          description: Last sync time with the provider (ISO 8601).
        name:
          type: string
          description: Repository name.
        provider:
          type: string
          description: Repository provider (e.g., "github").
        star_count:
          type: integer
          description: Number of stars.
        url:
          type: string
          format: url
          description: API URL of the remote repository.
        watch_count:
          type: integer
          description: Number of watchers.
    ProjectSummary:
      type: object
      properties:
        id:
          type: string
          description: Unique ID of the project.
        name:
          type: string
          description: Project name.
        privacy:
          type: string
          description: Project privacy setting.
        repository:
          $ref: '#/components/schemas/Repository'
    DailyAverage:
      type: object
      properties:
        holidays:
          type: integer
          description: Number of days in the range with no coding time logged.
        days_including_holidays:
          type: integer
          description: Total number of days in the range.
        days_minus_holidays:
          type: integer
          description: Number of days in the range with coding activity.
        seconds:
          type: number
          format: float
          description: Average coding activity per day (seconds, excluding 'Other' language).
        text:
          type: string
          description: Daily average (excluding 'Other' language) as human-readable string.
        seconds_including_other_language:
          type: number
          format: float
          description: Average coding activity per day (seconds, including 'Other' language).
        text_including_other_language:
          type: string
          description: Daily average (including 'Other' language) as human-readable string.
    CumulativeTotal:
      type: object
      properties:
        seconds:
          type: number
          format: float
          description: Cumulative number of seconds over the date range.
        text:
          type: string
          description: Cumulative total coding activity in human readable format.
        decimal:
          type: string
          description: Cumulative total as a decimal string.
        digital:
          type: string
          description: Cumulative total in digital clock format (HH:MM).
    Error:
      type: object
      properties:
        error:
          type: string
          description: Single error message.
        errors:
          type: array
          items:
            type: string
          description: List of error messages.

    # Endpoint Specific Schemas
    AllTimeSinceToday:
      type: object
      properties:
        daily_average:
          type: number
          format: float
          description: Average coding activity per day (seconds).
        decimal:
          type: string
          description: Total coding activity in decimal format.
        digital:
          type: string
          description: Total coding activity in digital clock format.
        is_up_to_date:
          type: boolean
          description: True if stats are up-to-date.
        percent_calculated:
          type: integer
          description: Percentage completion of stats calculation (0-100).
        range:
          $ref: '#/components/schemas/Range'
        text:
          type: string
          description: Total time logged since account creation (human-readable).
        timeout:
          type: integer
          description: Keystroke timeout setting in minutes.
        total_seconds:
          type: number
          format: float
          description: Total seconds logged since account creation.
    Commit:
      type: object
      properties:
        author_avatar_url:
          type: string
          format: url
        author_date:
          type: string
          format: date-time
        author_email:
          type: string
          format: email
        author_html_url:
          type: string
          format: url
        author_name:
          type: string
        author_url:
          type: string
          format: url
        author_username:
          type: string
        branch:
          type: string
        committer_avatar_url:
          type: string
          format: url
        committer_date:
          type: string
          format: date-time
        committer_email:
          type: string
          format: email
        committer_html_url:
          type: string
          format: url
        committer_name:
          type: string
        committer_url:
          type: string
          format: url
        committer_username:
          type: string
        created_at:
          type: string
          format: date-time
        hash:
          type: string
        html_url:
          type: string
          format: url
        human_readable_total:
          type: string
        human_readable_total_with_seconds:
          type: string
        id:
          type: string
        message:
          type: string
        ref:
          type: string
        total_seconds:
          type: number
          format: float
        truncated_hash:
          type: string
        url:
          type: string
          format: url
    CommitDetailResponse:
      type: object
      properties:
        commit:
          $ref: '#/components/schemas/Commit'
        branch:
          type: string
        project:
          $ref: '#/components/schemas/ProjectSummary'
        status:
          type: string
    CommitsListResponse:
      type: object
      properties:
        commits:
          type: array
          items:
            $ref: '#/components/schemas/Commit'
        author:
          type: string
          nullable: true
        next_page:
          type: integer
          nullable: true
        next_page_url:
          type: string
          format: url
          nullable: true
        page:
          type: integer
        prev_page:
          type: integer
          nullable: true
        prev_page_url:
          type: string
          format: url
          nullable: true
        branch:
          type: string
        project:
          $ref: '#/components/schemas/ProjectSummary'
        status:
          type: string
        total:
          type: integer
        total_pages:
          type: integer
    DataDump:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum: ['Pending…', 'Processing coding activity…', 'Uploading…', 'Completed']
        percent_complete:
          type: number
          format: float
        download_url:
          type: string
          format: url
          nullable: true
        type:
          type: string
          enum: [daily, heartbeats]
        is_processing:
          type: boolean
        is_stuck:
          type: boolean
        has_failed:
          type: boolean
        expires:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
    DataDumpRequest:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum: [daily, heartbeats]
          description: Required export type.
        email_when_finished:
          type: boolean
          default: true
          description: Optional flag to disable email notification.
    Duration:
      type: object
      properties:
        project:
          type: string
          nullable: true
        time:
          type: number
          format: float
          description: Start of duration as UNIX epoch timestamp.
        duration:
          type: number
          format: float
          description: Length of duration in seconds.
    DurationsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Duration'
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        timezone:
          type: string
    EditorResource:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        color:
          type: string
        website:
          type: string
          format: url
        repository:
          type: string
          format: url
        version:
          type: string
        version_url:
          type: string
          format: url
        history_url:
          type: string
          format: url
        released:
          type: boolean
        hidden:
          type: boolean
    ExternalDuration:
      type: object
      properties:
        id:
          type: string
        external_id:
          type: string
        entity:
          type: string
        type:
          type: string
          enum: [file, app, domain]
        provider:
          type: string
        category:
          type: string
          enum: [coding, building, indexing, debugging, browsing, running tests, writing tests, manual testing, writing docs, communicating, code reviewing, researching, learning, designing]
        start_time:
          type: number
          format: float
          description: UNIX epoch timestamp.
        end_time:
          type: number
          format: float
          description: UNIX epoch timestamp.
        project:
          type: string
          nullable: true
        branch:
          type: string
          nullable: true
        language:
          type: string
          nullable: true
        meta:
          type: string
          nullable: true
    ExternalDurationsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ExternalDuration'
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        timezone:
          type: string
    ExternalDurationRequest:
      type: object
      required:
        - external_id
        - entity
        - type
        - start_time
        - end_time
      properties:
        external_id:
          type: string
        entity:
          type: string
        type:
          type: string
          enum: [file, app, domain]
        category:
          type: string
          enum: [coding, building, indexing, debugging, browsing, running tests, writing tests, manual testing, writing docs, communicating, code reviewing, researching, learning, designing]
          description: Optional category.
        start_time:
          type: number
          format: float
        end_time:
          type: number
          format: float
        project:
          type: string
          nullable: true
        branch:
          type: string
          nullable: true
        language:
          type: string
          nullable: true
        meta:
          type: string
          maxLength: 2083
          nullable: true
    BulkDeleteRequest:
      type: object
      required:
        - date
        - ids
      properties:
        date:
          type: string
          format: date
          description: Date in YYYY-MM-DD format for deletion scope.
        ids:
          type: array
          items:
            type: string
          description: List of ExternalDuration or Heartbeat IDs to delete.
    GoalChartData:
      type: object
      properties:
        actual_seconds:
          type: number
          format: float
        actual_seconds_text:
          type: string
        goal_seconds:
          type: integer
        goal_seconds_text:
          type: string
        range:
          $ref: '#/components/schemas/Range'
        range_status:
          type: string
          enum: [success, fail, pending, ignored]
        range_status_reason:
          type: string
    GoalSharedWith:
      type: object
      properties:
        display_name:
          type: string
        email:
          type: string
          format: email
          nullable: true
        full_name:
          type: string
          nullable: true
        id:
          type: string
        photo:
          type: string
          format: url
        status:
          type: string
        user_id:
          type: string
          nullable: true
        username:
          type: string
          nullable: true
    GoalSubscriber:
      type: object
      properties:
        email:
          type: string
          format: email
          nullable: true
        email_frequency:
          type: string
        full_name:
          type: string
          nullable: true
        user_id:
          type: string
        username:
          type: string
          nullable: true
    Goal:
      type: object
      properties:
        average_status:
          type: string
          enum: [fail, success]
        chart_data:
          type: array
          items:
            $ref: '#/components/schemas/GoalChartData'
        created_at:
          type: string
          format: date-time
        cumulative_status:
          type: string
          enum: [success, fail, ignored]
        custom_title:
          type: string
          nullable: true
        delta:
          type: string
          enum: [day, week]
        editors:
          type: array
          items:
            type: string
        id:
          type: string
        ignore_days:
          type: array
          items:
            type: string
        ignore_zero_days:
          type: boolean
        improve_by_percent:
          type: number
          format: float
          nullable: true
        is_current_user_owner:
          type: boolean
        is_enabled:
          type: boolean
        is_inverse:
          type: boolean
        is_snoozed:
          type: boolean
        is_tweeting:
          type: boolean
        languages:
          type: array
          items:
            type: string
        modified_at:
          type: string
          format: date-time
          nullable: true
        owner:
          $ref: '#/components/schemas/UserSummary'
        projects:
          type: array
          items:
            type: string
        range_text:
          type: string
        seconds:
          type: integer
        shared_with:
          type: array
          items:
            $ref: '#/components/schemas/GoalSharedWith'
        snooze_until:
          type: string
          format: date-time
          nullable: true
        status:
          type: string
          enum: [success, fail, ignored, pending]
        status_percent_calculated:
          type: integer
        subscribers:
          type: array
          items:
            $ref: '#/components/schemas/GoalSubscriber'
        title:
          type: string
        type:
          type: string
    GoalDetailResponse:
      type: object
      properties:
        cached_at:
          type: string
          format: date-time
        data:
          $ref: '#/components/schemas/Goal'
    GoalsListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Goal'
        total:
          type: integer
        total_pages:
          type: integer
    Heartbeat:
      type: object
      properties:
        entity:
          type: string
        type:
          type: string
          enum: [file, app, domain]
        category:
          type: string
          enum: [coding, building, indexing, debugging, browsing, running tests, writing tests, manual testing, writing docs, code reviewing, communicating, researching, learning, designing]
        time:
          type: number
          format: float
          description: UNIX epoch timestamp.
        project:
          type: string
          nullable: true
        project_root_count:
          type: integer
          nullable: true
        branch:
          type: string
          nullable: true
        language:
          type: string
          nullable: true
        dependencies:
          type: string # Comma separated list
          nullable: true
        machine_name_id:
          type: string
        line_additions:
          type: integer
          nullable: true
        line_deletions:
          type: integer
          nullable: true
        lines:
          type: integer
          nullable: true
        lineno:
          type: integer
          nullable: true
        cursorpos:
          type: integer
          nullable: true
        is_write:
          type: boolean
    HeartbeatsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Heartbeat'
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        timezone:
          type: string
    HeartbeatRequest:
      type: object
      required:
        - entity
        - type
        - time
      properties:
        entity:
          type: string
        type:
          type: string
          enum: [file, app, domain]
        category:
          type: string
          enum: [coding, building, indexing, debugging, browsing, running tests, writing tests, manual testing, writing docs, communicating, code reviewing, researching, learning, designing]
          description: Optional category.
        time:
          type: number
          format: float
        project:
          type: string
          nullable: true
        project_root_count:
          type: integer
          nullable: true
        branch:
          type: string
          nullable: true
        language:
          type: string
          nullable: true
        dependencies:
          type: string # Comma separated list
          nullable: true
        lines:
          type: integer
          nullable: true
        line_additions:
          type: integer
          nullable: true
        line_deletions:
          type: integer
          nullable: true
        lineno:
          type: integer
          nullable: true
        cursorpos:
          type: integer
          nullable: true
        is_write:
          type: boolean
          nullable: true
    HeartbeatPostResponseData:
      type: object
      properties:
        id:
          type: string
        entity:
          type: string
        type:
          type: string
        time:
          type: number
          format: float
    Insight:
      # This is highly variable based on insight_type, define a generic object
      # or specific ones if needed, but generic might be more practical.
      type: object
      description: Structure varies based on the insight type requested.
      additionalProperties: true
    InsightResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            # The key here matches the insight_type path parameter
            # Using additionalProperties to represent this dynamic key
            additionalProperties:
              $ref: '#/components/schemas/Insight'
            range:
              type: string
            human_readable_range:
              type: string
            status:
              type: string
            is_including_today:
              type: boolean
            is_up_to_date:
              type: boolean
            percent_calculated:
              type: integer
            start:
              type: string
              format: date-time
            end:
              type: string
              format: date-time
            timezone:
              type: string
            timeout:
              type: integer
            writes_only:
              type: boolean
            user_id:
              type: string
            created_at:
              type: string
              format: date-time
            modified_at:
              type: string
              format: date-time
    LeaderRunningTotal:
      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
    Leader:
      type: object
      properties:
        rank:
          type: integer
        running_total:
          $ref: '#/components/schemas/LeaderRunningTotal'
        user:
          $ref: '#/components/schemas/UserSummary'
    LeadersResponse:
      type: object
      properties:
        current_user:
          type: object
          nullable: true
          properties:
            rank:
              type: integer
              nullable: true
            page:
              type: integer
              nullable: true
            user:
              $ref: '#/components/schemas/UserSummary'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Leader'
        page:
          type: integer
        total_pages:
          type: integer
        range:
          $ref: '#/components/schemas/Range'
        language:
          type: string
          nullable: true
        is_hireable:
          type: boolean
          nullable: true
        country_code:
          type: string
          nullable: true
        modified_at:
          type: string
          format: date-time
        timeout:
          type: integer
        writes_only:
          type: boolean
    MachineName:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        value:
          type: string
        ip:
          type: string
          format: ipv4 # Or ipv6? Docs don't specify, assume v4 for now
        last_seen_at:
          type: string
          format: date-time
        timezone:
          type: string
        created_at:
          type: string
          format: date-time
    MetaResponseData:
      type: object
      properties:
        ip_descriptions:
          type: object
          additionalProperties:
            type: string
        ips:
          type: object
          properties:
            api:
              type: array
              items:
                type: string
            website:
              type: array
              items:
                type: string
            worker:
              type: array
              items:
                type: string
        last_modified_at:
          type: string
          format: date-time
    OrgDashboardMember:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
          format: email
        full_name:
          type: string
        photo:
          type: string
          format: url
        username:
          type: string
        default_personal_privacy:
          type: string
          enum: [visible, hidden]
    OrgDashboardDurationMember:
      type: object
      properties:
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        timezone:
          type: string
        member:
          $ref: '#/components/schemas/OrgDashboardMember'
        durations:
          type: array # Docs show object, but likely array of durations
          items:
            $ref: '#/components/schemas/Duration'
    OrgDashboardDurationsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/OrgDashboardDurationMember'
    OrgDashboardMemberDurationsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Duration'
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        timezone:
          type: string
    Summary:
      type: object
      properties:
        grand_total:
          $ref: '#/components/schemas/GrandTotal'
        categories:
          type: array
          items:
            $ref: '#/components/schemas/CategoryStat'
        projects:
          type: array
          items:
            $ref: '#/components/schemas/ProjectStat'
        languages:
          type: array
          items:
            $ref: '#/components/schemas/LanguageStat'
        editors:
          type: array
          items:
            $ref: '#/components/schemas/EditorStat'
        operating_systems:
          type: array
          items:
            $ref: '#/components/schemas/OperatingSystemStat'
        dependencies:
          type: array
          items:
            $ref: '#/components/schemas/DependencyStat'
        machines:
          type: array
          items:
            $ref: '#/components/schemas/MachineStat'
        branches:
          type: array
          description: Included only when 'project' URL parameter is used.
          items:
            $ref: '#/components/schemas/BranchStat'
        entities:
          type: array
          description: Included only when 'project' URL parameter is used.
          items:
            $ref: '#/components/schemas/EntityStat'
        range:
          $ref: '#/components/schemas/Range'
    SummariesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Summary'
        cumulative_total:
          $ref: '#/components/schemas/CumulativeTotal'
        daily_average:
          $ref: '#/components/schemas/DailyAverage'
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
    OrgDashboardMemberSummaryResponse: # Same structure as SummariesResponse but with member privacy info
      allOf:
        - $ref: '#/components/schemas/SummariesResponse'
        - type: object
          properties:
            default_personal_privacy:
              type: string
              enum: [visible, hidden]
    OrgDashboardMemberListItem:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
          format: email
        full_name:
          type: string
        is_view_only:
          type: boolean
        photo:
          type: string
          format: url
        username:
          type: string
    OrgDashboardMembersListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/OrgDashboardMemberListItem'
        next_page:
          type: integer
          nullable: true
        page:
          type: integer
        prev_page:
          type: integer
          nullable: true
        total:
          type: integer
        total_pages:
          type: integer
    OrgDashboardSummaryMember:
      allOf:
        - $ref: '#/components/schemas/Summary'
        - type: object
          properties:
            member:
              $ref: '#/components/schemas/OrgDashboardMember'
    OrgDashboardSummariesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/OrgDashboardSummaryMember'
        cumulative_total:
          $ref: '#/components/schemas/CumulativeTotal' # Aggregated across members for the day
    OrgDashboard:
      type: object
      properties:
        id:
          type: string
        full_name:
          type: string
        created_by:
          type: string
        timezone:
          type: string
        has_changed_timezone:
          type: boolean
        members_count:
          type: integer
        members_count_human_readable:
          type: string
        is_current_user_member:
          type: boolean
        is_viewing_restricted:
          type: boolean
        is_manual_time_hidden:
          type: boolean
        can_current_user_view:
          type: boolean
        can_current_user_request_to_view:
          type: boolean
        can_current_user_request_to_join:
          type: boolean
        can_current_user_add_members:
          type: boolean
        can_current_user_remove_members:
          type: boolean
        can_current_user_delete:
          type: boolean
        created_at:
          type: string
          format: date-time
        modified_at:
          type: string
          format: date-time
    OrgDashboardsListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/OrgDashboard'
        next_page:
          type: integer
          nullable: true
        page:
          type: integer
        prev_page:
          type: integer
          nullable: true
        total:
          type: integer
        total_pages:
          type: integer
    Org:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        default_project_privacy:
          type: string
          enum: [visible, hidden]
        invited_people_count:
          type: integer
        invited_people_count_human_readable:
          type: string
        is_duration_visible:
          type: boolean
        people_count:
          type: integer
        people_count_human_readable:
          type: string
        timeout:
          type: integer
        timezone:
          type: string # Docs say integer, but timezone is usually string
        writes_only:
          type: boolean # Docs say integer, but likely boolean
        can_current_user_list_dashboards:
          type: boolean
        can_current_user_create_dashboards:
          type: boolean
        can_current_user_display_coding_on_dashboards:
          type: boolean
        can_current_user_view_all_dashboards:
          type: boolean
        can_current_user_add_people_to_dashboards:
          type: boolean
        can_current_user_remove_people_from_dashboards:
          type: boolean
        can_current_user_edit_and_delete_dashboards:
          type: boolean
        can_current_user_add_people_to_org:
          type: boolean
        can_current_user_remove_people_from_org:
          type: boolean
        can_current_user_manage_groups:
          type: boolean
        can_current_user_view_audit_log:
          type: boolean
        can_current_user_edit_org:
          type: boolean
        can_current_user_manage_billing:
          type: boolean
        can_current_user_delete_org:
          type: boolean
        created_at:
          type: string
          format: date-time
        modified_at:
          type: string
          format: date-time
    OrgsListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Org'
        next_page:
          type: integer
          nullable: true
        page:
          type: integer
        prev_page:
          type: integer
          nullable: true
        total:
          type: integer
        total_pages:
          type: integer
    PrivateLeaderboard:
      type: object
      properties:
        can_delete:
          type: boolean
        can_edit:
          type: boolean
        created_at:
          type: string
          format: date-time
        has_available_seat:
          type: boolean
        id:
          type: string
        members_count:
          type: integer
        members_with_timezones_count:
          type: integer
        modified_at:
          type: string
          format: date-time
        name:
          type: string
        time_range:
          type: string # Always "last_7_days" according to docs
    PrivateLeaderboardsListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PrivateLeaderboard'
        total:
          type: integer
        total_pages:
          type: integer
    PrivateLeaderboardMember:
      type: object
      properties:
        rank:
          type: integer
        page:
          type: integer
        user:
          $ref: '#/components/schemas/UserSummary'
    PrivateLeaderboardLeadersResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PrivateLeaderboardMember'
        language:
          type: string
          nullable: true
        country_code:
          type: string
          nullable: true
        modified_at:
          type: string
          format: date-time
        page:
          type: integer
        total_pages:
          type: integer
        range:
          $ref: '#/components/schemas/Range'
        timeout:
          type: integer
        writes_only:
          type: boolean
    ProgramLanguage:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        color:
          type: string
        is_verified:
          type: boolean
        created_at:
          type: string
          format: date-time
        modified_at:
          type: string
          format: date-time
    ProgramLanguagesListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ProgramLanguage'
        total:
          type: integer
        total_pages:
          type: integer
    Project:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        repository:
          # Docs say string, but likely refers to the repo URL or name?
          # Assuming it might be the Repository object or just name/URL.
          # Let's use object for flexibility, but mark nullable.
          $ref: '#/components/schemas/Repository'
          nullable: true
        badge:
          type: string # URL?
          nullable: true
        color:
          type: string
          nullable: true
        clients: # Docs say list, but list of what? Assuming strings (client names/ids)
          type: array
          items:
            type: string
        has_public_url:
          type: boolean
        human_readable_last_heartbeat_at:
          type: string
          nullable: true
        last_heartbeat_at:
          type: string
          format: date-time
          nullable: true
        human_readable_first_heartbeat_at:
          type: string
          nullable: true
        first_heartbeat_at:
          type: string
          format: date-time
          nullable: true
        url:
          type: string # Relative URL path
        urlencoded_name:
          type: string
        created_at:
          type: string
          format: date-time
    StatsBestDay:
      type: object
      properties:
        date:
          type: string
          format: date
        text:
          type: string
        total_seconds:
          type: number
          format: float
    Stats:
      type: object
      properties:
        total_seconds:
          type: number
          format: float
        total_seconds_including_other_language:
          type: number
          format: float
        human_readable_total:
          type: string
        human_readable_total_including_other_language:
          type: string
        daily_average:
          type: number
          format: float
        daily_average_including_other_language:
          type: number
          format: float
        human_readable_daily_average:
          type: string
        human_readable_daily_average_including_other_language:
          type: string
        categories:
          type: array
          items:
            $ref: '#/components/schemas/CategoryStat'
        projects:
          type: array
          items:
            $ref: '#/components/schemas/ProjectStat'
        languages:
          type: array
          items:
            $ref: '#/components/schemas/LanguageStat'
        editors:
          type: array
          items:
            $ref: '#/components/schemas/EditorStat'
        operating_systems:
          type: array
          items:
            $ref: '#/components/schemas/OperatingSystemStat'
        dependencies:
          type: array
          items:
            $ref: '#/components/schemas/DependencyStat'
        machines:
          type: array
          items:
            $ref: '#/components/schemas/MachineStat'
        best_day:
          $ref: '#/components/schemas/StatsBestDay'
        range:
          type: string # Name of the range
        human_readable_range:
          type: string
        holidays:
          type: integer
        days_including_holidays:
          type: integer
        days_minus_holidays:
          type: integer
        status:
          type: string
        percent_calculated:
          type: integer
        is_already_updating:
          type: boolean
        is_coding_activity_visible:
          type: boolean
        is_language_usage_visible:
          type: boolean
        is_editor_usage_visible:
          type: boolean
        is_category_usage_visible:
          type: boolean
        is_os_usage_visible:
          type: boolean
        is_stuck:
          type: boolean
        is_including_today:
          type: boolean
        is_up_to_date:
          type: boolean
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        timezone:
          type: string
        timeout:
          type: integer
        writes_only:
          type: boolean
        user_id:
          type: string
        username:
          type: string
        created_at:
          type: string
          format: date-time
        modified_at:
          type: string
          format: date-time
    AggregateStatValue:
      type: object
      properties:
        seconds:
          type: number
          format: float
        text:
          type: string
    AggregateStatCount:
      type: object
      properties:
        text:
          type: string # Number as string
    AggregateStatItem:
      type: object
      properties:
        name:
          type: string
        is_verified:
          type: boolean
        average:
          $ref: '#/components/schemas/AggregateStatValue'
        count:
          $ref: '#/components/schemas/AggregateStatCount'
        max:
          $ref: '#/components/schemas/AggregateStatValue'
        median:
          $ref: '#/components/schemas/AggregateStatValue'
        sum:
          $ref: '#/components/schemas/AggregateStatValue'
    AggregateDailyAverage:
      type: object
      properties:
        average:
          $ref: '#/components/schemas/AggregateStatValue'
        count:
          $ref: '#/components/schemas/AggregateStatCount'
        max:
          $ref: '#/components/schemas/AggregateStatValue'
        median:
          $ref: '#/components/schemas/AggregateStatValue'
    AggregateTotal:
      type: object
      properties:
        average:
          $ref: '#/components/schemas/AggregateStatValue'
        count:
          $ref: '#/components/schemas/AggregateStatCount'
        max:
          $ref: '#/components/schemas/AggregateStatValue'
        median:
          $ref: '#/components/schemas/AggregateStatValue'
        sum:
          $ref: '#/components/schemas/AggregateStatValue'
    AggregateStats:
      type: object
      properties:
        categories:
          type: array
          items:
            $ref: '#/components/schemas/AggregateStatItem'
        daily_average:
          $ref: '#/components/schemas/AggregateDailyAverage'
        editors:
          type: array
          items:
            $ref: '#/components/schemas/AggregateStatItem'
        languages:
          type: array
          items:
            $ref: '#/components/schemas/AggregateStatItem'
        operating_systems:
          type: array
          items:
            $ref: '#/components/schemas/AggregateStatItem'
        total:
          $ref: '#/components/schemas/AggregateTotal'
        range:
          $ref: '#/components/schemas/Range'
        timeout:
          type: integer
        writes_only:
          type: boolean
    StatusBarResponse:
      type: object
      properties:
        cached_at:
          type: string
          format: date-time
        has_team_features:
          type: boolean
        data:
          $ref: '#/components/schemas/Summary' # Status bar uses Summary structure
    UserAgent:
      type: object
      properties:
        id:
          type: string
        value:
          type: string
        editor:
          type: string
          nullable: true
        version:
          type: string
          nullable: true
        os:
          type: string
          nullable: true
        last_seen_at:
          type: string
          format: date-time
        is_browser_extension:
          type: boolean
        is_desktop_app:
          type: boolean
        created_at:
          type: string
          format: date-time
    User:
      type: object
      properties:
        id:
          type: string
        has_premium_features:
          type: boolean
        display_name:
          type: string
        full_name:
          type: string
          nullable: true
        email:
          type: string
          format: email
          nullable: true # Requires 'email' scope
        photo:
          type: string
          format: url
        is_email_public:
          type: boolean
        is_email_confirmed:
          type: boolean
        public_email:
          type: string
          format: email
          nullable: true
        photo_public:
          type: boolean
        timezone:
          type: string
        last_heartbeat_at:
          type: string
          format: date-time
          nullable: true
        last_plugin:
          type: string
          nullable: true
        last_plugin_name:
          type: string
          nullable: true
        last_project:
          type: string
          nullable: true
        last_branch:
          type: string
          nullable: true
        plan:
          type: string
        username:
          type: string
          nullable: true
        website:
          type: string
          format: url
          nullable: true
        human_readable_website:
          type: string
          nullable: true
        wonderfuldev_username:
          type: string
          nullable: true
        github_username:
          type: string
          nullable: true
        twitter_username:
          type: string
          nullable: true
        linkedin_username:
          type: string
          nullable: true
        city:
          $ref: '#/components/schemas/City'
          nullable: true
        logged_time_public:
          type: boolean
        languages_used_public:
          type: boolean
        editors_used_public:
          type: boolean
        categories_used_public:
          type: boolean
        os_used_public:
          type: boolean
        is_hireable:
          type: boolean
        created_at:
          type: string
          format: date-time
        modified_at:
          type: string
          format: date-time
          nullable: true

  parameters:
    UserId:
      name: user
      in: path
      required: true
      description: User ID or 'current' for the authenticated user.
      schema:
        type: string
    ProjectIdPath:
      name: project
      in: path
      required: true
      description: Project ID or name (URL encoded).
      schema:
        type: string
    CommitHash:
      name: hash
      in: path
      required: true
      description: Commit hash.
      schema:
        type: string
    GoalId:
      name: goal
      in: path
      required: true
      description: Goal ID.
      schema:
        type: string
    OrgId:
      name: org
      in: path
      required: true
      description: Organization ID.
      schema:
        type: string
    DashboardId:
      name: dashboard
      in: path
      required: true
      description: Dashboard ID.
      schema:
        type: string
    MemberId:
      name: member
      in: path
      required: true
      description: Member User ID.
      schema:
        type: string
    BoardId:
      name: board
      in: path
      required: true
      description: Private Leaderboard ID.
      schema:
        type: string
    InsightType:
      name: insight_type
      in: path
      required: true
      description: Type of insight to retrieve.
      schema:
        type: string
        enum: [weekday, days, best_day, daily_average, projects, languages, editors, categories, machines, operating_systems]
    RangePathParam:
      name: range
      in: path
      required: true
      description: Time range for stats or insights (e.g., 'last_7_days', 'last_30_days', 'last_6_months', 'last_year', 'all_time', 'YYYY', 'YYYY-MM'). For aggregate stats, 'last_7_days' or 'YYYY'.
      schema:
        type: string
    ProjectQueryParam:
      name: project
      in: query
      required: false
      description: Filter by project name.
      schema:
        type: string
    BranchQueryParam:
      name: branch
      in: query
      required: false
      description: Filter by branch name.
      schema:
        type: string
    BranchesQueryParam:
      name: branches
      in: query
      required: false
      description: Filter by comma-separated list of branch names.
      schema:
        type: string
    PageQueryParam:
      name: page
      in: query
      required: false
      description: Page number for paginated results.
      schema:
        type: integer
        default: 1
    TimeoutQueryParam:
      name: timeout
      in: query
      required: false
      description: Override the user's keystroke timeout setting (in minutes).
      schema:
        type: integer
    WritesOnlyQueryParam:
      name: writes_only
      in: query
      required: false
      description: Override the user's writes_only setting.
      schema:
        type: boolean
    DateQueryParam:
      name: date
      in: query
      required: true
      description: Date in YYYY-MM-DD format.
      schema:
        type: string
        format: date
    StartDateQueryParam:
      name: start
      in: query
      required: true
      description: Start date of the time range (YYYY-MM-DD).
      schema:
        type: string
        format: date
    EndDateQueryParam:
      name: end
      in: query
      required: true
      description: End date of the time range (YYYY-MM-DD).
      schema:
        type: string
        format: date
    TimezoneQueryParam:
      name: timezone
      in: query
      required: false
      description: Override the user's timezone (Olson format, e.g., 'America/Los_Angeles').
      schema:
        type: string
    RangeQueryParam:
      name: range
      in: query
      required: false
      description: Alternative way to specify date range (e.g., 'Today', 'Last 7 Days'). Overrides start/end if provided.
      schema:
        type: string
        enum: ["Today", "Yesterday", "Last 7 Days", "Last 7 Days from Yesterday", "Last 14 Days", "Last 30 Days", "This Week", "Last Week", "This Month", "Last Month"]
    LanguageQueryParam:
      name: language
      in: query
      required: false
      description: Filter by language name.
      schema:
        type: string
    CountryCodeQueryParam:
      name: country_code
      in: query
      required: false
      description: Filter by two-character country code.
      schema:
        type: string
        minLength: 2
        maxLength: 2
    IsHireableQueryParam:
      name: is_hireable
      in: query
      required: false
      description: Filter leaders by hireable status.
      schema:
        type: boolean
    ProjectSearchQueryParam:
      name: q
      in: query
      required: false
      description: Filter project names by search term.
      schema:
        type: string
    AuthorQueryParam:
      name: author
      in: query
      required: false
      description: Filter commits by author username.
      schema:
        type: string
    SliceByQueryParam:
      name: slice_by
      in: query
      required: false
      description: Primary key for slicing durations.
      schema:
        type: string
        enum: [entity, language, dependencies, os, editor, category, machine]
        default: entity
    UnreleasedQueryParam:
      name: unreleased
      in: query
      required: false
      description: Include unreleased editor plugins.
      schema:
        type: boolean
        default: false
    WeekdayQueryParam:
      name: weekday
      in: query
      required: false
      description: Filter 'days' insight by weekday (0-6 or monday-sunday).
      schema:
        oneOf:
          - type: integer
            minimum: 0
            maximum: 6
          - type: string
            enum: [monday, tuesday, wednesday, thursday, friday, saturday, sunday]

  responses:
    UnauthorizedError:
      description: Unauthorized. Invalid authentication credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Unauthorized.
    ForbiddenError:
      description: Forbidden. Insufficient permissions for the requested scope or resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Forbidden.
    NotFoundError:
      description: Not Found. The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Not Found.
    BadRequestError:
      description: Bad Request. Invalid input parameters or request format. Check error message.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors: ["Date is invalid."]
    TooManyRequestsError:
      description: Too Many Requests. Rate limit exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Too Many Requests.
    ServerError:
      description: Internal Server Error. Service unavailable or unexpected error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Service unavailable, try again later.
    Accepted:
      description: Accepted. Request accepted for processing, but not yet complete (e.g., stats calculation).
      content:
        application/json:
          schema:
            # Response body might vary, often includes the resource being processed
            type: object
            properties:
              data:
                type: object # Or specific schema like Stats
                description: Data related to the accepted request.
              message:
                type: string
                example: Stats are calculating and will be ready soon.
    Created:
      description: Created. The resource was successfully created.
      # Content defined per operation
    OK:
      description: OK. The request was successful.
      # Content defined per operation
    OKEmpty:
      description: OK. Request successful, no data returned in body.
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object # Empty object

security:
  - oauth2: []
  - basicAuth: []
  - apiKeyQuery: []

paths:
  /users/{user}/all_time_since_today:
    get:
      tags:
        - Stats
      summary: Get All Time Since Today
      description: Retrieve the total time logged since the user account was created. Available even for Free accounts.
      operationId: getAllTimeSinceToday
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/ProjectQueryParam'
      security:
        - oauth2:
            - read_stats
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved all-time stats.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AllTimeSinceToday'
        '202':
          $ref: '#/components/responses/Accepted'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /users/current/all_time_since_today:
    get:
      tags:
        - Stats
      summary: Get Current User's All Time Since Today
      description: Retrieve the total time logged for the currently authenticated user since their account was created.
      operationId: getCurrentUserAllTimeSinceToday
      parameters:
        - $ref: '#/components/parameters/ProjectQueryParam'
      security:
        - oauth2:
            - read_stats
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved all-time stats.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AllTimeSinceToday'
        '202':
          $ref: '#/components/responses/Accepted'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /users/{user}/projects/{project}/commits/{hash}:
    get:
      tags:
        - Commits
      summary: Get Single Commit
      description: Retrieve details for a single commit within a project, including time spent coding on it.
      operationId: getCommit
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/ProjectIdPath'
        - $ref: '#/components/parameters/CommitHash'
        - $ref: '#/components/parameters/BranchQueryParam'
      security:
        - oauth2:
            - read_heartbeats
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved commit details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommitDetailResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /users/current/projects/{project}/commits/{hash}:
    get:
      tags:
        - Commits
      summary: Get Current User's Single Commit
      description: Retrieve details for a single commit for the current user's project.
      operationId: getCurrentUserCommit
      parameters:
        - $ref: '#/components/parameters/ProjectIdPath'
        - $ref: '#/components/parameters/CommitHash'
        - $ref: '#/components/parameters/BranchQueryParam'
      security:
        - oauth2:
            - read_heartbeats
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved commit details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommitDetailResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /users/{user}/projects/{project}/commits:
    get:
      tags:
        - Commits
      summary: List Project Commits
      description: Retrieve a list of commits for a specific project, showing time spent coding in each.
      operationId: listCommits
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/ProjectIdPath'
        - $ref: '#/components/parameters/AuthorQueryParam'
        - $ref: '#/components/parameters/BranchQueryParam'
        - $ref: '#/components/parameters/PageQueryParam'
      security:
        - oauth2:
            - read_heartbeats
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved list of commits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommitsListResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /users/current/projects/{project}/commits:
    get:
      tags:
        - Commits
      summary: List Current User's Project Commits
      description: Retrieve a list of commits for the current user's project.
      operationId: listCurrentUserCommits
      parameters:
        - $ref: '#/components/parameters/ProjectIdPath'
        - $ref: '#/components/parameters/AuthorQueryParam'
        - $ref: '#/components/parameters/BranchQueryParam'
        - $ref: '#/components/parameters/PageQueryParam'
      security:
        - oauth2:
            - read_heartbeats
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved list of commits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommitsListResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /users/{user}/data_dumps:
    get:
      tags:
        - Data Dumps
      summary: List Data Dumps
      description: Retrieve a list of data exports (dumps) for the user.
      operationId: listDataDumps
      parameters:
        - $ref: '#/components/parameters/UserId'
      security:
        - oauth2:
            - read_heartbeats
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved list of data dumps.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DataDump'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
    post:
      tags:
        - Data Dumps
      summary: Create Data Dump
      description: Start generating a data export in the background. An email will be sent upon completion unless disabled.
      operationId: createDataDump
      parameters:
        - $ref: '#/components/parameters/UserId'
      security:
        - oauth2:
            - read_heartbeats # Although creating, it reads data to export
        - basicAuth: []
        - apiKeyQuery: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataDumpRequest'
      responses:
        '201':
          description: Data dump creation initiated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/DataDump'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /users/current/data_dumps:
    get:
      tags:
        - Data Dumps
      summary: List Current User's Data Dumps
      description: Retrieve a list of data exports (dumps) for the currently authenticated user.
      operationId: listCurrentUserDataDumps
      security:
        - oauth2:
            - read_heartbeats
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved list of data dumps.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DataDump'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
    post:
      tags:
        - Data Dumps
      summary: Create Current User's Data Dump
      description: Start generating a data export for the current user in the background.
      operationId: createCurrentUserDataDump
      security:
        - oauth2:
            - read_heartbeats
        - basicAuth: []
        - apiKeyQuery: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataDumpRequest'
      responses:
        '201':
          description: Data dump creation initiated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/DataDump'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /users/{user}/durations:
    get:
      tags:
        - Durations
      summary: Get User Durations
      description: Retrieve a user's coding activity durations for a specific day. Durations are read-only representations of Heartbeats joined together based on the timeout setting.
      operationId: getUserDurations
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/DateQueryParam'
        - $ref: '#/components/parameters/ProjectQueryParam'
        - $ref: '#/components/parameters/BranchesQueryParam'
        - $ref: '#/components/parameters/TimeoutQueryParam'
        - $ref: '#/components/parameters/WritesOnlyQueryParam'
        - $ref: '#/components/parameters/TimezoneQueryParam'
        - $ref: '#/components/parameters/SliceByQueryParam'
      security:
        - oauth2:
            - read_heartbeats
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved durations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DurationsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /users/current/durations:
    get:
      tags:
        - Durations
      summary: Get Current User Durations
      description: Retrieve the currently authenticated user's coding activity durations for a specific day.
      operationId: getCurrentUserDurations
      parameters:
        - $ref: '#/components/parameters/DateQueryParam'
        - $ref: '#/components/parameters/ProjectQueryParam'
        - $ref: '#/components/parameters/BranchesQueryParam'
        - $ref: '#/components/parameters/TimeoutQueryParam'
        - $ref: '#/components/parameters/WritesOnlyQueryParam'
        - $ref: '#/components/parameters/TimezoneQueryParam'
        - $ref: '#/components/parameters/SliceByQueryParam'
      security:
        - oauth2:
            - read_heartbeats
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved durations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DurationsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /editors:
    get:
      tags:
        - Resources
      summary: List Editors
      description: Retrieve a list of supported WakaTime IDE plugins, versions, and colors.
      operationId: listEditors
      parameters:
        - $ref: '#/components/parameters/UnreleasedQueryParam'
      # No authentication required for this public resource list
      responses:
        '200':
          description: Successfully retrieved list of editors.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EditorResource'

  /users/{user}/external_durations:
    get:
      tags:
        - External Durations
      summary: Get User External Durations
      description: Retrieve a user's external durations (e.g., from calendar integrations) for a specific day.
      operationId: getUserExternalDurations
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/DateQueryParam'
        - $ref: '#/components/parameters/ProjectQueryParam'
        - $ref: '#/components/parameters/BranchesQueryParam'
        - $ref: '#/components/parameters/TimezoneQueryParam'
      security:
        - oauth2:
            - read_heartbeats
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved external durations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalDurationsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
    post:
      tags:
        - External Durations
      summary: Create External Duration
      description: Create a single external duration representing activity like meetings. Uses `external_id` for idempotency.
      operationId: createExternalDuration
      parameters:
        - $ref: '#/components/parameters/UserId'
      security:
        - oauth2:
            - write_heartbeats
        # No Basic/API Key auth for writing external durations? Docs imply OAuth only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalDurationRequest'
      responses:
        '201':
          description: External duration created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ExternalDuration'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /users/current/external_durations:
    get:
      tags:
        - External Durations
      summary: Get Current User External Durations
      description: Retrieve the current user's external durations for a specific day.
      operationId: getCurrentUserExternalDurations
      parameters:
        - $ref: '#/components/parameters/DateQueryParam'
        - $ref: '#/components/parameters/ProjectQueryParam'
        - $ref: '#/components/parameters/BranchesQueryParam'
        - $ref: '#/components/parameters/TimezoneQueryParam'
      security:
        - oauth2:
            - read_heartbeats
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved external durations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalDurationsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
    post:
      tags:
        - External Durations
      summary: Create Current User External Duration
      description: Create a single external duration for the current user.
      operationId: createCurrentUserExternalDuration
      security:
        - oauth2:
            - write_heartbeats
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalDurationRequest'
      responses:
        '201':
          description: External duration created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ExternalDuration'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /users/{user}/external_durations.bulk:
    post:
      tags:
        - External Durations
      summary: Create External Durations (Bulk)
      description: Create multiple external durations in a single request (limit 1000). Returns 201 with individual status codes.
      operationId: createExternalDurationsBulk
      parameters:
        - $ref: '#/components/parameters/UserId'
      security:
        - oauth2:
            - write_heartbeats
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/ExternalDurationRequest'
              maxItems: 1000
      responses:
        '201':
          description: Bulk request processed. Check individual statuses in response.
          content:
            application/json:
              schema:
                type: array # Array of status codes or results per item
                items:
                  type: object # Structure not fully defined, assuming status per item
                  properties:
                    status_code:
                      type: integer
                    data: # Optional data if successful
                      $ref: '#/components/schemas/ExternalDuration'
                    error: # Optional error if failed
                      type: string
        '400':
          $ref: '#/components/responses/BadRequestError' # For overall request format errors
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
    delete:
      tags:
        - External Durations
      summary: Delete External Durations (Bulk)
      description: Permanently delete multiple external durations by ID for a specific date.
      operationId: deleteExternalDurationsBulk
      parameters:
        - $ref: '#/components/parameters/UserId'
      security:
        - oauth2:
            - write_heartbeats
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkDeleteRequest'
      responses:
        '200':
          $ref: '#/components/responses/OKEmpty'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /users/current/external_durations.bulk:
    post:
      tags:
        - External Durations
      summary: Create Current User External Durations (Bulk)
      description: Create multiple external durations for the current user (limit 1000).
      operationId: createCurrentUserExternalDurationsBulk
      security:
        - oauth2:
            - write_heartbeats
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/ExternalDurationRequest'
              maxItems: 1000
      responses:
        '201':
          description: Bulk request processed. Check individual statuses in response.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    status_code:
                      type: integer
                    data:
                      $ref: '#/components/schemas/ExternalDuration'
                    error:
                      type: string
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
    delete:
      tags:
        - External Durations
      summary: Delete Current User External Durations (Bulk)
      description: Permanently delete multiple external durations for the current user by ID for a specific date.
      operationId: deleteCurrentUserExternalDurationsBulk
      security:
        - oauth2:
            - write_heartbeats
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkDeleteRequest'
      responses:
        '200':
          $ref: '#/components/responses/OKEmpty'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /users/{user}/goals/{goal}:
    get:
      tags:
        - Goals
      summary: Get Single Goal
      description: Retrieve details for a specific goal. This endpoint uses cached data and may return an empty structure initially.
      operationId: getGoal
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/GoalId'
      security:
        - oauth2:
            - read_goals
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved goal details (may be cached/empty initially).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoalDetailResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /users/current/goals/{goal}:
    get:
      tags:
        - Goals
      summary: Get Current User's Single Goal
      description: Retrieve details for a specific goal belonging to the current user. Uses cached data.
      operationId: getCurrentUserGoal
      parameters:
        - $ref: '#/components/parameters/GoalId'
      security:
        - oauth2:
            - read_goals
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved goal details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoalDetailResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /users/{user}/goals:
    get:
      tags:
        - Goals
      summary: List User Goals
      description: Retrieve a list of goals for a specific user.
      operationId: listGoals
      parameters:
        - $ref: '#/components/parameters/UserId'
        # Pagination parameters not explicitly mentioned but likely exist for lists
        - $ref: '#/components/parameters/PageQueryParam'
      security:
        - oauth2:
            - read_goals
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved list of goals.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoalsListResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /users/current/goals:
    get:
      tags:
        - Goals
      summary: List Current User Goals
      description: Retrieve a list of goals for the currently authenticated user.
      operationId: listCurrentUserGoals
      parameters:
        - $ref: '#/components/parameters/PageQueryParam'
      security:
        - oauth2:
            - read_goals
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved list of goals.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoalsListResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /users/{user}/heartbeats:
    get:
      tags:
        - Heartbeats
      summary: Get User Heartbeats
      description: Retrieve a user's raw heartbeat data for a specific day.
      operationId: getUserHeartbeats
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/DateQueryParam'
        # Pagination not mentioned, might return all for the day
      security:
        - oauth2:
            - read_heartbeats
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved heartbeats.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeartbeatsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
    post:
      tags:
        - Heartbeats
      summary: Create Heartbeat
      description: Create a single heartbeat event for a user. Editor/OS detected from User-Agent.
      operationId: createHeartbeat
      parameters:
        - $ref: '#/components/parameters/UserId'
      security:
        - oauth2:
            - write_heartbeats
        - basicAuth: [] # API Key can also send heartbeats
        - apiKeyQuery: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HeartbeatRequest'
      responses:
        '201': # Docs say 202, but 201 is more standard for single creation
          description: Heartbeat created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/HeartbeatPostResponseData'
        '202': # Include 202 as documented
          description: Heartbeat accepted for processing.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/HeartbeatPostResponseData'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /users/current/heartbeats:
    get:
      tags:
        - Heartbeats
      summary: Get Current User Heartbeats
      description: Retrieve the current user's raw heartbeat data for a specific day.
      operationId: getCurrentUserHeartbeats
      parameters:
        - $ref: '#/components/parameters/DateQueryParam'
      security:
        - oauth2:
            - read_heartbeats
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved heartbeats.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeartbeatsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
    post:
      tags:
        - Heartbeats
      summary: Create Current User Heartbeat
      description: Create a single heartbeat event for the current user.
      operationId: createCurrentUserHeartbeat
      security:
        - oauth2:
            - write_heartbeats
        - basicAuth: []
        - apiKeyQuery: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HeartbeatRequest'
      responses:
        '201':
          description: Heartbeat created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/HeartbeatPostResponseData'
        '202':
          description: Heartbeat accepted for processing.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/HeartbeatPostResponseData'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /users/{user}/heartbeats.bulk:
    post:
      tags:
        - Heartbeats
      summary: Create Heartbeats (Bulk)
      description: Create multiple heartbeats in a single request (limit 25).
      operationId: createHeartbeatsBulk
      parameters:
        - $ref: '#/components/parameters/UserId'
      security:
        - oauth2:
            - write_heartbeats
        - basicAuth: []
        - apiKeyQuery: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/HeartbeatRequest'
              maxItems: 25
      responses:
        # Bulk POST for heartbeats doesn't specify return format like external durations
        # Assuming 201/202 with potentially aggregated results or just status
        '201':
          description: Heartbeats created successfully.
        '202':
          description: Heartbeats accepted for processing.
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
    delete:
      tags:
        - Heartbeats
      summary: Delete Heartbeats (Bulk)
      description: Permanently delete multiple heartbeats by ID for a specific date.
      operationId: deleteHeartbeatsBulk
      parameters:
        - $ref: '#/components/parameters/UserId'
      security:
        - oauth2:
            - write_heartbeats
        - basicAuth: [] # Allow deletion via API key? Docs imply yes.
        - apiKeyQuery: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkDeleteRequest'
      responses:
        '200':
          $ref: '#/components/responses/OKEmpty'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /users/current/heartbeats.bulk:
    post:
      tags:
        - Heartbeats
      summary: Create Current User Heartbeats (Bulk)
      description: Create multiple heartbeats for the current user (limit 25).
      operationId: createCurrentUserHeartbeatsBulk
      security:
        - oauth2:
            - write_heartbeats
        - basicAuth: []
        - apiKeyQuery: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/HeartbeatRequest'
              maxItems: 25
      responses:
        '201':
          description: Heartbeats created successfully.
        '202':
          description: Heartbeats accepted for processing.
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
    delete:
      tags:
        - Heartbeats
      summary: Delete Current User Heartbeats (Bulk)
      description: Permanently delete multiple heartbeats for the current user by ID for a specific date.
      operationId: deleteCurrentUserHeartbeatsBulk
      security:
        - oauth2:
            - write_heartbeats
        - basicAuth: []
        - apiKeyQuery: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkDeleteRequest'
      responses:
        '200':
          $ref: '#/components/responses/OKEmpty'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /users/{user}/insights/{insight_type}/{range}:
    get:
      tags:
        - Insights
      summary: Get User Insight
      description: Retrieve a specific insight about the user's coding activity for a given type and time range. Check `is_up_to_date`.
      operationId: getUserInsight
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/InsightType'
        - $ref: '#/components/parameters/RangePathParam'
        - $ref: '#/components/parameters/TimeoutQueryParam'
        - $ref: '#/components/parameters/WritesOnlyQueryParam'
        - $ref: '#/components/parameters/WeekdayQueryParam' # Only for 'days' insight
      security:
        - oauth2:
            - read_summaries # Base scope for insights
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved insight data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsightResponse'
        '202':
          $ref: '#/components/responses/Accepted' # If stats are calculating
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError' # If user not found

  /users/current/insights/{insight_type}/{range}:
    get:
      tags:
        - Insights
      summary: Get Current User Insight
      description: Retrieve a specific insight for the currently authenticated user. Check `is_up_to_date`.
      operationId: getCurrentUserInsight
      parameters:
        - $ref: '#/components/parameters/InsightType'
        - $ref: '#/components/parameters/RangePathParam'
        - $ref: '#/components/parameters/TimeoutQueryParam'
        - $ref: '#/components/parameters/WritesOnlyQueryParam'
        - $ref: '#/components/parameters/WeekdayQueryParam'
      security:
        - oauth2:
            - read_summaries
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved insight data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsightResponse'
        '202':
          $ref: '#/components/responses/Accepted'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /leaders:
    get:
      tags:
        - Leaderboards
      summary: Get Public Leaders
      description: Retrieve the public leaderboard, ranking users by coding activity. Updates periodically.
      operationId: getLeaders
      parameters:
        - $ref: '#/components/parameters/LanguageQueryParam'
        - $ref: '#/components/parameters/IsHireableQueryParam'
        - $ref: '#/components/parameters/CountryCodeQueryParam'
        - $ref: '#/components/parameters/PageQueryParam'
      # Authentication is optional, provides current_user info if authenticated
      security:
        - oauth2: [] # No scope needed for public data, but provides context
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved public leaderboard.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadersResponse'
        '400':
          $ref: '#/components/responses/BadRequestError' # e.g., invalid country code

  /users/{user}/machine_names:
    get:
      tags:
        - Users
      summary: List User Machine Names
      description: Retrieve a list of machines (hostnames, IPs) associated with the user's coding activity.
      operationId: listMachineNames
      parameters:
        - $ref: '#/components/parameters/UserId'
      security:
        - oauth2:
            - read_stats.machines
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved machine names.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/MachineName'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /users/current/machine_names:
    get:
      tags:
        - Users
      summary: List Current User Machine Names
      description: Retrieve a list of machines associated with the current user.
      operationId: listCurrentUserMachineNames
      security:
        - oauth2:
            - read_stats.machines
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved machine names.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/MachineName'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /meta:
    get:
      tags:
        - Meta
      summary: Get API Meta Information
      description: Retrieve metadata about the WakaTime service, such as server IP addresses. Useful for firewall configuration.
      operationId: getMeta
      # No authentication required
      responses:
        '200':
          description: Successfully retrieved meta information.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/MetaResponseData'

  /users/{user}/orgs/{org}/dashboards/{dashboard}/durations:
    get:
      tags:
        - Organizations
      summary: Get Org Dashboard Durations
      description: Retrieve coding durations for all members of an organization dashboard for a specific day.
      operationId: getOrgDashboardDurations
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/DashboardId'
        - $ref: '#/components/parameters/DateQueryParam'
        - $ref: '#/components/parameters/ProjectQueryParam'
        - $ref: '#/components/parameters/BranchesQueryParam'
      security:
        - oauth2:
            - read_orgs
        # Org data likely requires OAuth
      responses:
        '200':
          description: Successfully retrieved dashboard durations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgDashboardDurationsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /users/current/orgs/{org}/dashboards/{dashboard}/durations:
    get:
      tags:
        - Organizations
      summary: Get Current User's Org Dashboard Durations
      description: Retrieve coding durations for all members of an organization dashboard the current user has access to.
      operationId: getCurrentUserOrgDashboardDurations
      parameters:
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/DashboardId'
        - $ref: '#/components/parameters/DateQueryParam'
        - $ref: '#/components/parameters/ProjectQueryParam'
        - $ref: '#/components/parameters/BranchesQueryParam'
      security:
        - oauth2:
            - read_orgs
      responses:
        '200':
          description: Successfully retrieved dashboard durations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgDashboardDurationsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /users/{user}/orgs/{org}/dashboards/{dashboard}/members/{member}/durations:
    get:
      tags:
        - Organizations
      summary: Get Org Dashboard Member Durations
      description: Retrieve coding durations for a specific member of an organization dashboard for a given day.
      operationId: getOrgDashboardMemberDurations
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/DashboardId'
        - $ref: '#/components/parameters/MemberId'
        - $ref: '#/components/parameters/DateQueryParam'
        - $ref: '#/components/parameters/ProjectQueryParam'
        - $ref: '#/components/parameters/BranchesQueryParam'
      security:
        - oauth2:
            - read_orgs
      responses:
        '200':
          description: Successfully retrieved member durations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgDashboardMemberDurationsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /users/current/orgs/{org}/dashboards/{dashboard}/members/{member}/durations:
    get:
      tags:
        - Organizations
      summary: Get Current User's Org Dashboard Member Durations
      description: Retrieve coding durations for a specific member of an organization dashboard the current user has access to.
      operationId: getCurrentUserOrgDashboardMemberDurations
      parameters:
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/DashboardId'
        - $ref: '#/components/parameters/MemberId'
        - $ref: '#/components/parameters/DateQueryParam'
        - $ref: '#/components/parameters/ProjectQueryParam'
        - $ref: '#/components/parameters/BranchesQueryParam'
      security:
        - oauth2:
            - read_orgs
      responses:
        '200':
          description: Successfully retrieved member durations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgDashboardMemberDurationsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /users/{user}/orgs/{org}/dashboards/{dashboard}/members/{member}/summaries:
    get:
      tags:
        - Organizations
      summary: Get Org Dashboard Member Summaries
      description: Retrieve daily summaries for a specific member of an organization dashboard over a given time range.
      operationId: getOrgDashboardMemberSummaries
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/DashboardId'
        - $ref: '#/components/parameters/MemberId'
        - $ref: '#/components/parameters/StartDateQueryParam'
        - $ref: '#/components/parameters/EndDateQueryParam'
        - $ref: '#/components/parameters/ProjectQueryParam'
        - $ref: '#/components/parameters/BranchesQueryParam'
        - $ref: '#/components/parameters/RangeQueryParam'
      security:
        - oauth2:
            - read_orgs
      responses:
        '200':
          description: Successfully retrieved member summaries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgDashboardMemberSummaryResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /users/current/orgs/{org}/dashboards/{dashboard}/members/{member}/summaries:
    get:
      tags:
        - Organizations
      summary: Get Current User's Org Dashboard Member Summaries
      description: Retrieve daily summaries for a specific member of an organization dashboard the current user has access to.
      operationId: getCurrentUserOrgDashboardMemberSummaries
      parameters:
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/DashboardId'
        - $ref: '#/components/parameters/MemberId'
        - $ref: '#/components/parameters/StartDateQueryParam'
        - $ref: '#/components/parameters/EndDateQueryParam'
        - $ref: '#/components/parameters/ProjectQueryParam'
        - $ref: '#/components/parameters/BranchesQueryParam'
        - $ref: '#/components/parameters/RangeQueryParam'
      security:
        - oauth2:
            - read_orgs
      responses:
        '200':
          description: Successfully retrieved member summaries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgDashboardMemberSummaryResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /users/{user}/orgs/{org}/dashboards/{dashboard}/members:
    get:
      tags:
        - Organizations
      summary: List Org Dashboard Members
      description: Retrieve a list of members belonging to a specific organization dashboard.
      operationId: listOrgDashboardMembers
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/DashboardId'
        - $ref: '#/components/parameters/PageQueryParam'
      security:
        - oauth2:
            - read_orgs
      responses:
        '200':
          description: Successfully retrieved dashboard members.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgDashboardMembersListResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /users/current/orgs/{org}/dashboards/{dashboard}/members:
    get:
      tags:
        - Organizations
      summary: List Current User's Org Dashboard Members
      description: Retrieve a list of members for an organization dashboard the current user has access to.
      operationId: listCurrentUserOrgDashboardMembers
      parameters:
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/DashboardId'
        - $ref: '#/components/parameters/PageQueryParam'
      security:
        - oauth2:
            - read_orgs
      responses:
        '200':
          description: Successfully retrieved dashboard members.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgDashboardMembersListResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /users/{user}/orgs/{org}/dashboards/{dashboard}/summaries:
    get:
      tags:
        - Organizations
      summary: Get Org Dashboard Summaries
      description: Retrieve daily summaries for all members of an organization dashboard for a specific day.
      operationId: getOrgDashboardSummaries
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/DashboardId'
        - $ref: '#/components/parameters/DateQueryParam'
        - $ref: '#/components/parameters/ProjectQueryParam'
        - $ref: '#/components/parameters/BranchesQueryParam'
      security:
        - oauth2:
            - read_orgs
      responses:
        '200':
          description: Successfully retrieved dashboard summaries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgDashboardSummariesResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /users/current/orgs/{org}/dashboards/{dashboard}/summaries:
    get:
      tags:
        - Organizations
      summary: Get Current User's Org Dashboard Summaries
      description: Retrieve daily summaries for all members of an organization dashboard the current user has access to.
      operationId: getCurrentUserOrgDashboardSummaries
      parameters:
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/DashboardId'
        - $ref: '#/components/parameters/DateQueryParam'
        - $ref: '#/components/parameters/ProjectQueryParam'
        - $ref: '#/components/parameters/BranchesQueryParam'
      security:
        - oauth2:
            - read_orgs
      responses:
        '200':
          description: Successfully retrieved dashboard summaries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgDashboardSummariesResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /users/{user}/orgs/{org}/dashboards:
    get:
      tags:
        - Organizations
      summary: List Org Dashboards
      description: Retrieve a list of dashboards within a specific organization.
      operationId: listOrgDashboards
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/PageQueryParam'
      security:
        - oauth2:
            - read_orgs
      responses:
        '200':
          description: Successfully retrieved organization dashboards.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgDashboardsListResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /users/current/orgs/{org}/dashboards:
    get:
      tags:
        - Organizations
      summary: List Current User's Org Dashboards
      description: Retrieve a list of dashboards for an organization the current user belongs to.
      operationId: listCurrentUserOrgDashboards
      parameters:
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/PageQueryParam'
      security:
        - oauth2:
            - read_orgs
      responses:
        '200':
          description: Successfully retrieved organization dashboards.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgDashboardsListResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /users/{user}/orgs:
    get:
      tags:
        - Organizations
      summary: List User Organizations
      description: Retrieve a list of organizations the specified user belongs to.
      operationId: listOrgs
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/PageQueryParam'
      security:
        - oauth2:
            - read_orgs
      responses:
        '200':
          description: Successfully retrieved organizations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgsListResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /users/current/orgs:
    get:
      tags:
        - Organizations
      summary: List Current User Organizations
      description: Retrieve a list of organizations the currently authenticated user belongs to.
      operationId: listCurrentUserOrgs
      parameters:
        - $ref: '#/components/parameters/PageQueryParam'
      security:
        - oauth2:
            - read_orgs
      responses:
        '200':
          description: Successfully retrieved organizations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgsListResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /users/{user}/leaderboards:
    get:
      tags:
        - Leaderboards
      summary: List User Private Leaderboards
      description: Retrieve a list of private leaderboards the user is a member of.
      operationId: listPrivateLeaderboards
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/PageQueryParam'
      security:
        - oauth2:
            - read_private_leaderboards
        # Private data likely requires OAuth
      responses:
        '200':
          description: Successfully retrieved private leaderboards.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivateLeaderboardsListResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /users/current/leaderboards:
    get:
      tags:
        - Leaderboards
      summary: List Current User Private Leaderboards
      description: Retrieve a list of private leaderboards the current user is a member of.
      operationId: listCurrentUserPrivateLeaderboards
      parameters:
        - $ref: '#/components/parameters/PageQueryParam'
      security:
        - oauth2:
            - read_private_leaderboards
      responses:
        '200':
          description: Successfully retrieved private leaderboards.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivateLeaderboardsListResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /users/{user}/leaderboards/{board}:
    get:
      tags:
        - Leaderboards
      summary: Get Private Leaderboard Leaders
      description: Retrieve the ranked list of members within a specific private leaderboard.
      operationId: getPrivateLeaderboardLeaders
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/BoardId'
        - $ref: '#/components/parameters/LanguageQueryParam'
        - $ref: '#/components/parameters/CountryCodeQueryParam'
        - $ref: '#/components/parameters/PageQueryParam'
      security:
        - oauth2:
            - read_private_leaderboards
      responses:
        '200':
          description: Successfully retrieved private leaderboard members.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivateLeaderboardLeadersResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /users/current/leaderboards/{board}:
    get:
      tags:
        - Leaderboards
      summary: Get Current User's Private Leaderboard Leaders
      description: Retrieve the ranked list of members for a private leaderboard the current user belongs to.
      operationId: getCurrentUserPrivateLeaderboardLeaders
      parameters:
        - $ref: '#/components/parameters/BoardId'
        - $ref: '#/components/parameters/LanguageQueryParam'
        - $ref: '#/components/parameters/CountryCodeQueryParam'
        - $ref: '#/components/parameters/PageQueryParam'
      security:
        - oauth2:
            - read_private_leaderboards
      responses:
        '200':
          description: Successfully retrieved private leaderboard members.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivateLeaderboardLeadersResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /program_languages:
    get:
      tags:
        - Resources
      summary: List Programming Languages
      description: Retrieve a list of all verified programming languages supported by WakaTime.
      operationId: listProgramLanguages
      parameters:
        - $ref: '#/components/parameters/PageQueryParam'
      # No authentication required
      responses:
        '200':
          description: Successfully retrieved programming languages.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProgramLanguagesListResponse'

  /users/{user}/projects:
    get:
      tags:
        - Projects
      summary: List User Projects
      description: Retrieve a list of projects associated with the specified user.
      operationId: listProjects
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/ProjectSearchQueryParam'
        - $ref: '#/components/parameters/PageQueryParam'
      security:
        - oauth2:
            - read_stats.projects
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved projects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Project'
                  # Pagination fields like total, total_pages might exist
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /users/current/projects:
    get:
      tags:
        - Projects
      summary: List Current User Projects
      description: Retrieve a list of projects associated with the currently authenticated user.
      operationId: listCurrentUserProjects
      parameters:
        - $ref: '#/components/parameters/ProjectSearchQueryParam'
        - $ref: '#/components/parameters/PageQueryParam'
      security:
        - oauth2:
            - read_stats.projects
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved projects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /users/{user}/stats:
    get:
      tags:
        - Stats
      summary: Get User Stats (Default Range)
      description: Retrieve coding activity statistics for the user over their public profile's default time range. Check `is_up_to_date`.
      operationId: getUserStatsDefaultRange
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/TimeoutQueryParam'
        - $ref: '#/components/parameters/WritesOnlyQueryParam'
      security:
        - oauth2:
            - read_stats
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved stats.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Stats'
        '202':
          $ref: '#/components/responses/Accepted'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /users/current/stats:
    get:
      tags:
        - Stats
      summary: Get Current User Stats (Default Range)
      description: Retrieve coding activity statistics for the current user over their public profile's default time range. Check `is_up_to_date`.
      operationId: getCurrentUserStatsDefaultRange
      parameters:
        - $ref: '#/components/parameters/TimeoutQueryParam'
        - $ref: '#/components/parameters/WritesOnlyQueryParam'
      security:
        - oauth2:
            - read_stats
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved stats.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Stats'
        '202':
          $ref: '#/components/responses/Accepted'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /users/{user}/stats/{range}:
    get:
      tags:
        - Stats
      summary: Get User Stats (Specific Range)
      description: Retrieve coding activity statistics for the user over a specific time range. Check `is_up_to_date`.
      operationId: getUserStatsForRange
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/RangePathParam'
        - $ref: '#/components/parameters/TimeoutQueryParam'
        - $ref: '#/components/parameters/WritesOnlyQueryParam'
      security:
        - oauth2:
            - read_stats
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved stats.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Stats'
        '202':
          $ref: '#/components/responses/Accepted'
        '400':
          $ref: '#/components/responses/BadRequestError' # Invalid range
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /users/current/stats/{range}:
    get:
      tags:
        - Stats
      summary: Get Current User Stats (Specific Range)
      description: Retrieve coding activity statistics for the current user over a specific time range. Check `is_up_to_date`.
      operationId: getCurrentUserStatsForRange
      parameters:
        - $ref: '#/components/parameters/RangePathParam'
        - $ref: '#/components/parameters/TimeoutQueryParam'
        - $ref: '#/components/parameters/WritesOnlyQueryParam'
      security:
        - oauth2:
            - read_stats
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved stats.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Stats'
        '202':
          $ref: '#/components/responses/Accepted'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /stats/{range}:
    get:
      tags:
        - Stats
      summary: Get Aggregate Stats
      description: Retrieve aggregated statistics for all WakaTime users over a specific range ('last_7_days' or 'YYYY'). Uses default public profile settings.
      operationId: getAggregateStats
      parameters:
        - name: range
          in: path
          required: true
          description: Time range ('last_7_days' or a year like '2023').
          schema:
            type: string # Pattern could be added: ^(last_7_days|\d{4})$
      # No authentication required
      responses:
        '200':
          description: Successfully retrieved aggregate stats.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AggregateStats'
        '400':
          $ref: '#/components/responses/BadRequestError' # Invalid range

  /users/{user}/status_bar/today:
    get:
      tags:
        - Summaries
      summary: Get User Status Bar Summary (Today)
      description: Retrieve today's coding activity summary, optimized for status bar display. Uses cached data and may return empty structure initially.
      operationId: getUserStatusBarSummary
      parameters:
        - $ref: '#/components/parameters/UserId'
      security:
        - oauth2:
            - read_summaries
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved status bar summary (may be cached/empty).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusBarResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /users/current/status_bar/today:
    get:
      tags:
        - Summaries
      summary: Get Current User Status Bar Summary (Today)
      description: Retrieve today's coding activity summary for the current user, optimized for status bar display. Uses cached data.
      operationId: getCurrentUserStatusBarSummary
      security:
        - oauth2:
            - read_summaries
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved status bar summary (may be cached/empty).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusBarResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /users/{user}/summaries:
    get:
      tags:
        - Summaries
      summary: Get User Summaries
      description: Retrieve daily summaries of coding activity for a user over a specified date range.
      operationId: getUserSummaries
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/StartDateQueryParam'
        - $ref: '#/components/parameters/EndDateQueryParam'
        - $ref: '#/components/parameters/ProjectQueryParam'
        - $ref: '#/components/parameters/BranchesQueryParam'
        - $ref: '#/components/parameters/TimeoutQueryParam'
        - $ref: '#/components/parameters/WritesOnlyQueryParam'
        - $ref: '#/components/parameters/TimezoneQueryParam'
        - $ref: '#/components/parameters/RangeQueryParam'
      security:
        - oauth2:
            - read_summaries
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved summaries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SummariesResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /users/current/summaries:
    get:
      tags:
        - Summaries
      summary: Get Current User Summaries
      description: Retrieve daily summaries of coding activity for the current user over a specified date range.
      operationId: getCurrentUserSummaries
      parameters:
        - $ref: '#/components/parameters/StartDateQueryParam'
        - $ref: '#/components/parameters/EndDateQueryParam'
        - $ref: '#/components/parameters/ProjectQueryParam'
        - $ref: '#/components/parameters/BranchesQueryParam'
        - $ref: '#/components/parameters/TimeoutQueryParam'
        - $ref: '#/components/parameters/WritesOnlyQueryParam'
        - $ref: '#/components/parameters/TimezoneQueryParam'
        - $ref: '#/components/parameters/RangeQueryParam'
      security:
        - oauth2:
            - read_summaries
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved summaries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SummariesResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /users/{user}/user_agents:
    get:
      tags:
        - Users
      summary: List User Agents
      description: Retrieve a list of user agents (plugins/editors) that have sent data for this user.
      operationId: listUserAgents
      parameters:
        - $ref: '#/components/parameters/UserId'
      security:
        - oauth2:
            - read_stats.editors # Requires editor stats scope
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved user agents.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/UserAgent'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /users/current/user_agents:
    get:
      tags:
        - Users
      summary: List Current User Agents
      description: Retrieve a list of user agents (plugins/editors) that have sent data for the current user.
      operationId: listCurrentUserAgents
      security:
        - oauth2:
            - read_stats.editors
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved user agents.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/UserAgent'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /users/{user}:
    get:
      tags:
        - Users
      summary: Get User Details
      description: Retrieve profile information for a specific user. Requires 'email' scope to view private email.
      operationId: getUser
      parameters:
        - $ref: '#/components/parameters/UserId'
      security:
        - oauth2: # Scope needed depends on desired data (e.g., 'email')
            - email # Example: Add other scopes if needed for specific fields
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved user details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError' # If scope missing for private data
        '404':
          $ref: '#/components/responses/NotFoundError'

  /users/current:
    get:
      tags:
        - Users
      summary: Get Current User Details
      description: Retrieve profile information for the currently authenticated user. Requires 'email' scope to view private email.
      operationId: getCurrentUser
      security:
        - oauth2:
            - email # Example scope
        - basicAuth: []
        - apiKeyQuery: []
      responses:
        '200':
          description: Successfully retrieved user details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

Generated by passing all related information from the https://wakatime.com/developers page to Gemini 2.5 Pro Experimental asking it to generate a openapi swagger spec. Can be viewed online here.

Edit: Please note that some things are just straight missing some things, take machine_names for example, the docs show that it only returns data, when in reality it returns data, total, total_pages, page, prev_page, next_page. The API additionally does not describe how to actually get pages, I presume it is a url param of page however that's entirely a guess.