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

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

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

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

    goals, leaderboards, and team/org dashboards.


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

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

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

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

    over any 5-minute window.


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

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

    '
  contact:
    name: WakaTime Support
    url: https://wakatime.com/contact
    email: support@wakatime.com
  termsOfService: https://wakatime.com/terms
  license:
    name: WakaTime Terms of Service
    url: https://wakatime.com/terms
  x-generated-from: documentation
  x-source-url: https://wakatime.com/developers
  x-last-validated: '2026-05-30'
servers:
- url: https://wakatime.com/api/v1
  description: WakaTime production API
- url: https://api.wakatime.com/api/v1
  description: WakaTime alternate hostname
security:
- oauth2: []
- apiKey: []
- bearerAuth: []
tags:
- name: Commits
  description: Per-project commits enriched with coding time.
paths:
  /users/current/projects/{project}/commits:
    get:
      operationId: listProjectCommits
      summary: List Project Commits
      description: Returns commits for the specified project, each enriched with coding-time totals.
      tags:
      - Commits
      parameters:
      - $ref: '#/components/parameters/ProjectPath'
      - name: page
        in: query
        schema:
          type: integer
          minimum: 1
        example: 1
      - name: author
        in: query
        description: Filter by commit author.
        schema:
          type: string
        example: example
      responses:
        '200':
          description: Commits list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Commit'
              examples:
                ListProjectCommits200Example:
                  summary: Default listProjectCommits 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - id: 5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
                      author_avatar_url: https://wakatime.com/photo/5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
                      author_date: '2026-05-30T12:34:56Z'
                      author_email: kin@apievangelist.com
                      author_html_url: https://github.com/kinlane
                      author_id: 5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
                      author_name: Kin Lane
                      author_url: https://wakatime.com/@kinlane
                      author_username: kinlane
                      branch: main
                      committer_avatar_url: https://wakatime.com/photo/5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
                      created_at: '2026-05-30T12:34:56Z'
                      hash: 9b8c4d2e6f1a3b5c7d9e8f0a1b2c3d4e5f6a7b8c
                      html_url: https://github.com/wakatime/wakatime-cli/commit/9b8c4d2e6f1a3b5c7d9e8f0a1b2c3d4e5f6a7b8c
                      human_readable_natural_total_time: about 4 hours
                      human_readable_total: 4 hrs 12 mins
                      human_readable_total_with_seconds: 4 hrs 12 mins 5 secs
                      is_authored_by_user: true
                      message: Initial commit
                      ref: refs/heads/main
                      total_seconds: 4
                      truncated_hash: 9b8c4d2
                      url: https://wakatime.com/@kinlane/projects/wakatime-cli
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users/current/projects/{project}/commits/{hash}:
    get:
      operationId: getProjectCommit
      summary: Get Project Commit
      description: Returns a single commit for the specified project.
      tags:
      - Commits
      parameters:
      - $ref: '#/components/parameters/ProjectPath'
      - name: hash
        in: path
        required: true
        description: Commit hash.
        schema:
          type: string
        example: example
      responses:
        '200':
          description: Commit details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Commit'
              examples:
                GetProjectCommit200Example:
                  summary: Default getProjectCommit 200 response
                  x-microcks-default: true
                  value:
                    data:
                      id: 5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
                      author_avatar_url: https://wakatime.com/photo/5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
                      author_date: '2026-05-30T12:34:56Z'
                      author_email: kin@apievangelist.com
                      author_html_url: https://github.com/kinlane
                      author_id: 5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
                      author_name: Kin Lane
                      author_url: https://wakatime.com/@kinlane
                      author_username: kinlane
                      branch: main
                      committer_avatar_url: https://wakatime.com/photo/5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
                      created_at: '2026-05-30T12:34:56Z'
                      hash: 9b8c4d2e6f1a3b5c7d9e8f0a1b2c3d4e5f6a7b8c
                      html_url: https://github.com/wakatime/wakatime-cli/commit/9b8c4d2e6f1a3b5c7d9e8f0a1b2c3d4e5f6a7b8c
                      human_readable_natural_total_time: about 4 hours
                      human_readable_total: 4 hrs 12 mins
                      human_readable_total_with_seconds: 4 hrs 12 mins 5 secs
                      is_authored_by_user: true
                      message: Initial commit
                      ref: refs/heads/main
                      total_seconds: 4
                      truncated_hash: 9b8c4d2
                      url: https://wakatime.com/@kinlane/projects/wakatime-cli
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    ProjectPath:
      name: project
      in: path
      required: true
      description: Project name.
      schema:
        type: string
      example: example
  schemas:
    Commit:
      type: object
      properties:
        id:
          type: string
          example: 5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
        author_avatar_url:
          type: string
          format: uri
          nullable: true
          example: https://wakatime.com/photo/5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
        author_date:
          type: string
          format: date-time
          example: '2026-05-30T12:34:56Z'
        author_email:
          type: string
          format: email
          nullable: true
          example: kin@apievangelist.com
        author_html_url:
          type: string
          format: uri
          nullable: true
          example: https://github.com/kinlane
        author_id:
          type: string
          nullable: true
          example: 5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
        author_name:
          type: string
          example: Kin Lane
        author_url:
          type: string
          format: uri
          nullable: true
          example: https://wakatime.com/@kinlane
        author_username:
          type: string
          nullable: true
          example: kinlane
        branch:
          type: string
          nullable: true
          example: main
        committer_avatar_url:
          type: string
          format: uri
          nullable: true
          example: https://wakatime.com/photo/5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
        created_at:
          type: string
          format: date-time
          example: '2026-05-30T12:34:56Z'
        hash:
          type: string
          example: 9b8c4d2e6f1a3b5c7d9e8f0a1b2c3d4e5f6a7b8c
        html_url:
          type: string
          format: uri
          nullable: true
          example: https://github.com/wakatime/wakatime-cli/commit/9b8c4d2e6f1a3b5c7d9e8f0a1b2c3d4e5f6a7b8c
        human_readable_natural_total_time:
          type: string
          nullable: true
          example: about 4 hours
        human_readable_total:
          type: string
          nullable: true
          example: 4 hrs 12 mins
        human_readable_total_with_seconds:
          type: string
          nullable: true
          example: 4 hrs 12 mins 5 secs
        is_authored_by_user:
          type: boolean
          example: true
        message:
          type: string
          example: Initial commit
        ref:
          type: string
          nullable: true
          example: refs/heads/main
        total_seconds:
          type: number
          format: float
          nullable: true
          example: 4
        truncated_hash:
          type: string
          example: 9b8c4d2
        url:
          type: string
          format: uri
          nullable: true
          example: https://wakatime.com/@kinlane/projects/wakatime-cli
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authorization code flow.
      flows:
        authorizationCode:
          authorizationUrl: https://wakatime.com/oauth/authorize
          tokenUrl: https://wakatime.com/oauth/token
          refreshUrl: https://wakatime.com/oauth/token
          scopes:
            email: Read user email.
            read_summaries: Read coding-activity summaries.
            read_stats: Read aggregate stats.
            read_goals: Read coding goals.
            read_heartbeats: Read raw heartbeats.
            write_heartbeats: Send heartbeats.
            read_orgs: Read organization data.
            write_orgs: Modify organization data.
        implicit:
          authorizationUrl: https://wakatime.com/oauth/authorize
          scopes:
            email: Read user email.
            read_summaries: Read coding-activity summaries.
            read_stats: Read aggregate stats.
            read_goals: Read coding goals.
            read_heartbeats: Read raw heartbeats.
            write_heartbeats: Send heartbeats.
            read_orgs: Read organization data.
            write_orgs: Modify organization data.
    apiKey:
      type: http
      scheme: basic
      description: HTTP Basic with the WakaTime API key as the username. Alternatively, pass `?api_key=...` as a query parameter.
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth access token in the Authorization header as `Bearer waka_tok_...`.