mirror of
https://github.com/System-End/hackatime.git
synced 2026-04-19 19:55:16 +00:00
eb3fa24315
* add new icon from bounty * feat: add hackatime normal token revocation * chore: make linter not hate me (its always whitespace) <3 * fix: combine both revocation apis into one (as requested by mahad) * chore: add HKA_REVOCATION_KEY to .env.example * feat: add hackatime normal token revocation * chore: make linter not hate me (its always whitespace) <3 * fix: combine both revocation apis into one (as requested by mahad) * chore: add HKA_REVOCATION_KEY to .env.example * feat: add hackatime normal token revocation * chore: make linter not hate me (its always whitespace) <3 * fix: combine both revocation apis into one (as requested by mahad) * chore: add HKA_REVOCATION_KEY to .env.example * feat: add hackatime normal token revocation * chore: make linter not hate me (its always whitespace) <3 * fix: combine both revocation apis into one (as requested by mahad) * fix: stuff greptile suggested * style: add final newline * docs: apply .env.example suggestion from @skyfallwastaken Co-authored-by: Mahad Kalam <55807755+skyfallwastaken@users.noreply.github.com> * refactor: move apikey rotation to user model * style: remove unnecessary comment * fix: tests passing and inappropriate response codes * refactor: fix response codes * refactor: move key info request back into separate function * fix: broken ci because of merge mistake :/ * refactor: remove unnecessary test line and switch to report_error * fix: returned name for admin & regular keys --------- Co-authored-by: Mahad Kalam <55807755+skyfallwastaken@users.noreply.github.com>
3813 lines
110 KiB
YAML
3813 lines
110 KiB
YAML
---
|
|
openapi: 3.0.1
|
|
info:
|
|
title: Hackatime API
|
|
version: v1
|
|
description: |
|
|
Hackatime's API gives access to coding activity data.
|
|
|
|
We support the WakaTime spec, allowing you to use existing plugins and tools.
|
|
paths:
|
|
"/api/admin/v1/admin_api_keys":
|
|
get:
|
|
summary: List Admin API Keys
|
|
tags:
|
|
- Admin Resources
|
|
description: List all admin API keys.
|
|
security:
|
|
- AdminToken: []
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
admin_api_keys:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
name:
|
|
type: string
|
|
token_preview:
|
|
type: string
|
|
user:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
username:
|
|
type: string
|
|
display_name:
|
|
type: string
|
|
admin_level:
|
|
type: string
|
|
created_at:
|
|
type: string
|
|
format: date_time
|
|
revoked_at:
|
|
type: string
|
|
format: date_time
|
|
nullable: true
|
|
active:
|
|
type: boolean
|
|
post:
|
|
summary: Create Admin API Key
|
|
tags:
|
|
- Admin Resources
|
|
description: Create a new admin API key.
|
|
security:
|
|
- AdminToken: []
|
|
parameters: []
|
|
responses:
|
|
'201':
|
|
description: created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
message:
|
|
type: string
|
|
admin_api_key:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
name:
|
|
type: string
|
|
token:
|
|
type: string
|
|
created_at:
|
|
type: string
|
|
format: date_time
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
"/api/admin/v1/admin_api_keys/{id}":
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
get:
|
|
summary: Show Admin API Key
|
|
tags:
|
|
- Admin Resources
|
|
description: Show details of an admin API key.
|
|
security:
|
|
- AdminToken: []
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
name:
|
|
type: string
|
|
token_preview:
|
|
type: string
|
|
user:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
username:
|
|
type: string
|
|
display_name:
|
|
type: string
|
|
admin_level:
|
|
type: string
|
|
created_at:
|
|
type: string
|
|
format: date_time
|
|
revoked_at:
|
|
type: string
|
|
format: date_time
|
|
nullable: true
|
|
active:
|
|
type: boolean
|
|
delete:
|
|
summary: Revoke Admin API Key
|
|
tags:
|
|
- Admin Resources
|
|
description: Revoke/Delete an admin API key.
|
|
security:
|
|
- AdminToken: []
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
message:
|
|
type: string
|
|
"/api/admin/v1/trust_level_audit_logs":
|
|
get:
|
|
summary: List Trust Level Audit Logs
|
|
tags:
|
|
- Admin Resources
|
|
description: List audit logs for trust level changes.
|
|
security:
|
|
- AdminToken: []
|
|
parameters:
|
|
- name: user_id
|
|
in: query
|
|
description: Filter by User ID
|
|
required: false
|
|
schema:
|
|
type: string
|
|
- name: admin_id
|
|
in: query
|
|
description: Filter by Admin ID
|
|
required: false
|
|
schema:
|
|
type: string
|
|
- name: user_search
|
|
in: query
|
|
description: Search user (fuzzy)
|
|
required: false
|
|
schema:
|
|
type: string
|
|
- name: admin_search
|
|
in: query
|
|
description: Search admin (fuzzy)
|
|
required: false
|
|
schema:
|
|
type: string
|
|
- name: trust_level_filter
|
|
in: query
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- all
|
|
- to_convicted
|
|
- to_trusted
|
|
- to_suspected
|
|
- to_unscored
|
|
description: Filter by trust level change
|
|
required: false
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
audit_logs:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
user:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
username:
|
|
type: string
|
|
display_name:
|
|
type: string
|
|
previous_trust_level:
|
|
type: string
|
|
nullable: true
|
|
new_trust_level:
|
|
type: string
|
|
nullable: true
|
|
changed_by:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
username:
|
|
type: string
|
|
display_name:
|
|
type: string
|
|
admin_level:
|
|
type: string
|
|
reason:
|
|
type: string
|
|
nullable: true
|
|
notes:
|
|
type: string
|
|
nullable: true
|
|
created_at:
|
|
type: string
|
|
total_count:
|
|
type: integer
|
|
"/api/admin/v1/trust_level_audit_logs/{id}":
|
|
get:
|
|
summary: Show Trust Level Audit Log
|
|
tags:
|
|
- Admin Resources
|
|
description: Show details of a trust level audit log.
|
|
security:
|
|
- AdminToken: []
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
user:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
username:
|
|
type: string
|
|
display_name:
|
|
type: string
|
|
current_trust_level:
|
|
type: string
|
|
previous_trust_level:
|
|
type: string
|
|
nullable: true
|
|
new_trust_level:
|
|
type: string
|
|
nullable: true
|
|
changed_by:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
username:
|
|
type: string
|
|
display_name:
|
|
type: string
|
|
admin_level:
|
|
type: string
|
|
reason:
|
|
type: string
|
|
nullable: true
|
|
notes:
|
|
type: string
|
|
nullable: true
|
|
created_at:
|
|
type: string
|
|
format: date_time
|
|
updated_at:
|
|
type: string
|
|
format: date_time
|
|
"/api/admin/v1/deletion_requests":
|
|
get:
|
|
summary: List Deletion Requests
|
|
tags:
|
|
- Admin Resources
|
|
description: List pending deletion requests.
|
|
security:
|
|
- AdminToken: []
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
pending:
|
|
type: array
|
|
items:
|
|
"$ref": "#/components/schemas/DeletionRequest"
|
|
approved:
|
|
type: array
|
|
items:
|
|
"$ref": "#/components/schemas/DeletionRequest"
|
|
completed:
|
|
type: array
|
|
items:
|
|
"$ref": "#/components/schemas/DeletionRequest"
|
|
"/api/admin/v1/deletion_requests/{id}":
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
get:
|
|
summary: Show Deletion Request
|
|
tags:
|
|
- Admin Resources
|
|
description: Show details of a deletion request.
|
|
security:
|
|
- AdminToken: []
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/DeletionRequest"
|
|
"/api/admin/v1/deletion_requests/{id}/approve":
|
|
post:
|
|
summary: Approve Deletion Request
|
|
tags:
|
|
- Admin Resources
|
|
description: Approve and execute a user deletion request.
|
|
security:
|
|
- AdminToken: []
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
message:
|
|
type: string
|
|
deletion_request:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
user_id:
|
|
type: integer
|
|
user:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
username:
|
|
type: string
|
|
display_name:
|
|
type: string
|
|
status:
|
|
type: string
|
|
enum:
|
|
- pending
|
|
- approved
|
|
- cancelled
|
|
- completed
|
|
requested_at:
|
|
type: string
|
|
format: date_time
|
|
scheduled_deletion_at:
|
|
type: string
|
|
format: date_time
|
|
nullable: true
|
|
completed_at:
|
|
type: string
|
|
format: date_time
|
|
nullable: true
|
|
admin_approved_by:
|
|
type: object
|
|
nullable: true
|
|
created_at:
|
|
type: string
|
|
format: date_time
|
|
updated_at:
|
|
type: string
|
|
format: date_time
|
|
"/api/admin/v1/deletion_requests/{id}/reject":
|
|
post:
|
|
summary: Reject Deletion Request
|
|
tags:
|
|
- Admin Resources
|
|
description: Reject a user deletion request.
|
|
security:
|
|
- AdminToken: []
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
message:
|
|
type: string
|
|
deletion_request:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
user_id:
|
|
type: integer
|
|
user:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
username:
|
|
type: string
|
|
display_name:
|
|
type: string
|
|
status:
|
|
type: string
|
|
enum:
|
|
- pending
|
|
- approved
|
|
- cancelled
|
|
- completed
|
|
requested_at:
|
|
type: string
|
|
format: date_time
|
|
scheduled_deletion_at:
|
|
type: string
|
|
format: date_time
|
|
nullable: true
|
|
completed_at:
|
|
type: string
|
|
format: date_time
|
|
nullable: true
|
|
admin_approved_by:
|
|
type: object
|
|
nullable: true
|
|
created_at:
|
|
type: string
|
|
format: date_time
|
|
updated_at:
|
|
type: string
|
|
format: date_time
|
|
"/api/admin/v1/timeline":
|
|
get:
|
|
summary: Get timeline
|
|
tags:
|
|
- Admin Timeline
|
|
description: Get timeline events including coding activity and commits for selected
|
|
users.
|
|
security:
|
|
- AdminToken: []
|
|
parameters:
|
|
- name: date
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date
|
|
description: Date for the timeline (YYYY-MM-DD)
|
|
- name: user_ids
|
|
in: query
|
|
description: Comma-separated list of User IDs
|
|
schema:
|
|
type: string
|
|
- name: slack_uids
|
|
in: query
|
|
description: Comma-separated list of Slack User IDs
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
date:
|
|
type: string
|
|
format: date
|
|
next_date:
|
|
type: string
|
|
format: date
|
|
prev_date:
|
|
type: string
|
|
format: date
|
|
users:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
user:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
username:
|
|
type: string
|
|
display_name:
|
|
type: string
|
|
nullable: true
|
|
slack_username:
|
|
type: string
|
|
nullable: true
|
|
github_username:
|
|
type: string
|
|
nullable: true
|
|
timezone:
|
|
type: string
|
|
nullable: true
|
|
avatar_url:
|
|
type: string
|
|
nullable: true
|
|
spans:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
start_time:
|
|
type: number
|
|
format: float
|
|
end_time:
|
|
type: number
|
|
format: float
|
|
duration:
|
|
type: number
|
|
format: float
|
|
files_edited:
|
|
type: array
|
|
items:
|
|
type: string
|
|
projects_edited_details:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
repo_url:
|
|
type: string
|
|
nullable: true
|
|
editors:
|
|
type: array
|
|
items:
|
|
type: string
|
|
languages:
|
|
type: array
|
|
items:
|
|
type: string
|
|
total_coded_time:
|
|
type: number
|
|
format: float
|
|
commit_markers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
timestamp:
|
|
type: number
|
|
format: float
|
|
additions:
|
|
type: integer
|
|
nullable: true
|
|
deletions:
|
|
type: integer
|
|
nullable: true
|
|
github_url:
|
|
type: string
|
|
nullable: true
|
|
"/api/admin/v1/timeline/search_users":
|
|
get:
|
|
summary: Search timeline users
|
|
tags:
|
|
- Admin Timeline
|
|
description: Search users specifically for the timeline view by username, slack
|
|
username, ID, or email.
|
|
security:
|
|
- AdminToken: []
|
|
parameters:
|
|
- name: query
|
|
in: query
|
|
description: Search query
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
users:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
display_name:
|
|
type: string
|
|
nullable: true
|
|
avatar_url:
|
|
type: string
|
|
nullable: true
|
|
'422':
|
|
description: unprocessable entity
|
|
"/api/admin/v1/timeline/leaderboard_users":
|
|
get:
|
|
summary: Get leaderboard users for timeline
|
|
tags:
|
|
- Admin Timeline
|
|
description: Get users who should appear on the timeline leaderboard based on
|
|
recent activity.
|
|
security:
|
|
- AdminToken: []
|
|
parameters:
|
|
- name: period
|
|
in: query
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- daily
|
|
- last_7_days
|
|
description: Leaderboard period
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
users:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
display_name:
|
|
type: string
|
|
nullable: true
|
|
avatar_url:
|
|
type: string
|
|
nullable: true
|
|
"/api/admin/v1/user/info_batch":
|
|
get:
|
|
summary: Get user info batch
|
|
tags:
|
|
- Admin Utils
|
|
description: Get info for multiple users.
|
|
security:
|
|
- AdminToken: []
|
|
parameters:
|
|
- name: ids
|
|
in: query
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: User IDs
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
users:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
username:
|
|
type: string
|
|
display_name:
|
|
type: string
|
|
slack_uid:
|
|
type: string
|
|
nullable: true
|
|
slack_username:
|
|
type: string
|
|
nullable: true
|
|
github_username:
|
|
type: string
|
|
nullable: true
|
|
timezone:
|
|
type: string
|
|
nullable: true
|
|
country_code:
|
|
type: string
|
|
nullable: true
|
|
trust_level:
|
|
type: string
|
|
avatar_url:
|
|
type: string
|
|
nullable: true
|
|
slack_avatar_url:
|
|
type: string
|
|
nullable: true
|
|
github_avatar_url:
|
|
type: string
|
|
nullable: true
|
|
"/api/admin/v1/user/info":
|
|
get:
|
|
summary: Get user info (Admin)
|
|
tags:
|
|
- Admin
|
|
description: Get detailed info about a user. Requires superadmin/admin privileges.
|
|
security:
|
|
- AdminToken: []
|
|
parameters:
|
|
- name: user_id
|
|
in: query
|
|
description: User ID
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
user:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
username:
|
|
type: string
|
|
display_name:
|
|
type: string
|
|
slack_uid:
|
|
type: string
|
|
nullable: true
|
|
slack_username:
|
|
type: string
|
|
nullable: true
|
|
github_username:
|
|
type: string
|
|
nullable: true
|
|
timezone:
|
|
type: string
|
|
nullable: true
|
|
country_code:
|
|
type: string
|
|
nullable: true
|
|
admin_level:
|
|
type: string
|
|
trust_level:
|
|
type: string
|
|
suspected:
|
|
type: boolean
|
|
banned:
|
|
type: boolean
|
|
created_at:
|
|
type: string
|
|
format: date_time
|
|
updated_at:
|
|
type: string
|
|
format: date_time
|
|
last_heartbeat_at:
|
|
type: number
|
|
nullable: true
|
|
email_addresses:
|
|
type: array
|
|
items:
|
|
type: string
|
|
api_keys_count:
|
|
type: integer
|
|
stats:
|
|
type: object
|
|
properties:
|
|
total_heartbeats:
|
|
type: integer
|
|
total_coding_time:
|
|
type: number
|
|
languages_used:
|
|
type: integer
|
|
projects_worked_on:
|
|
type: integer
|
|
days_active:
|
|
type: integer
|
|
"/api/admin/v1/user/heartbeats":
|
|
get:
|
|
summary: Get user heartbeats (Admin)
|
|
tags:
|
|
- Admin
|
|
description: Get raw heartbeats for a user.
|
|
security:
|
|
- AdminToken: []
|
|
parameters:
|
|
- name: user_id
|
|
in: query
|
|
description: User ID
|
|
schema:
|
|
type: string
|
|
- name: date
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date
|
|
description: Date (YYYY-MM-DD)
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
heartbeats:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
time:
|
|
type: number
|
|
lineno:
|
|
type: integer
|
|
nullable: true
|
|
cursorpos:
|
|
type: integer
|
|
nullable: true
|
|
is_write:
|
|
type: boolean
|
|
nullable: true
|
|
project:
|
|
type: string
|
|
nullable: true
|
|
language:
|
|
type: string
|
|
nullable: true
|
|
entity:
|
|
type: string
|
|
nullable: true
|
|
branch:
|
|
type: string
|
|
nullable: true
|
|
category:
|
|
type: string
|
|
nullable: true
|
|
editor:
|
|
type: string
|
|
nullable: true
|
|
machine:
|
|
type: string
|
|
nullable: true
|
|
user_agent:
|
|
type: string
|
|
nullable: true
|
|
ip_address:
|
|
type: string
|
|
nullable: true
|
|
lines:
|
|
type: integer
|
|
nullable: true
|
|
source_type:
|
|
type: string
|
|
nullable: true
|
|
total_count:
|
|
type: integer
|
|
has_more:
|
|
type: boolean
|
|
'404':
|
|
description: user not found
|
|
'422':
|
|
description: invalid date filter
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/Error"
|
|
"/api/admin/v1/user/heartbeat_values":
|
|
get:
|
|
summary: Get heartbeat values
|
|
tags:
|
|
- Admin Utils
|
|
description: Get specific values from heartbeats.
|
|
security:
|
|
- AdminToken: []
|
|
parameters:
|
|
- name: user_id
|
|
in: query
|
|
description: User ID
|
|
schema:
|
|
type: string
|
|
- name: field
|
|
in: query
|
|
description: Field to retrieve (projects, languages, etc.)
|
|
schema:
|
|
type: string
|
|
- name: start_date
|
|
in: query
|
|
description: Start date (YYYY-MM-DD or timestamp)
|
|
schema:
|
|
type: string
|
|
- name: end_date
|
|
in: query
|
|
description: End date (YYYY-MM-DD or timestamp)
|
|
schema:
|
|
type: string
|
|
- name: limit
|
|
in: query
|
|
description: Limit results
|
|
schema:
|
|
type: integer
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
field:
|
|
type: string
|
|
values:
|
|
type: array
|
|
items:
|
|
type: string
|
|
count:
|
|
type: integer
|
|
'404':
|
|
description: user not found
|
|
'422':
|
|
description: invalid date filter
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/Error"
|
|
"/api/admin/v1/user/get_users_by_ip":
|
|
get:
|
|
summary: Get users by IP
|
|
tags:
|
|
- Admin Utils
|
|
description: Find users associated with an IP address.
|
|
security:
|
|
- AdminToken: []
|
|
parameters:
|
|
- name: ip
|
|
in: query
|
|
description: IP Address
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
users:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
ip_address:
|
|
type: string
|
|
machine:
|
|
type: string
|
|
nullable: true
|
|
user_agent:
|
|
type: string
|
|
nullable: true
|
|
"/api/admin/v1/user/get_users_by_machine":
|
|
get:
|
|
summary: Get users by machine
|
|
tags:
|
|
- Admin Utils
|
|
description: Find users associated with a machine ID.
|
|
security:
|
|
- AdminToken: []
|
|
parameters:
|
|
- name: machine
|
|
in: query
|
|
description: Machine ID
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
users:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
machine:
|
|
type: string
|
|
"/api/admin/v1/user/stats":
|
|
get:
|
|
summary: Get admin user stats
|
|
tags:
|
|
- Admin Utils
|
|
description: Get detailed stats for a user (Admin view).
|
|
security:
|
|
- AdminToken: []
|
|
parameters:
|
|
- name: user_id
|
|
in: query
|
|
description: User ID
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
username:
|
|
type: string
|
|
date:
|
|
type: string
|
|
format: date_time
|
|
timezone:
|
|
type: string
|
|
nullable: true
|
|
total_heartbeats:
|
|
type: integer
|
|
total_duration:
|
|
type: number
|
|
heartbeats:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
time:
|
|
type: string
|
|
created_at:
|
|
type: string
|
|
format: date_time
|
|
project:
|
|
type: string
|
|
nullable: true
|
|
branch:
|
|
type: string
|
|
nullable: true
|
|
category:
|
|
type: string
|
|
nullable: true
|
|
dependencies:
|
|
type: string
|
|
nullable: true
|
|
editor:
|
|
type: string
|
|
nullable: true
|
|
entity:
|
|
type: string
|
|
nullable: true
|
|
language:
|
|
type: string
|
|
nullable: true
|
|
machine:
|
|
type: string
|
|
nullable: true
|
|
operating_system:
|
|
type: string
|
|
nullable: true
|
|
type:
|
|
type: string
|
|
nullable: true
|
|
user_agent:
|
|
type: string
|
|
nullable: true
|
|
line_additions:
|
|
type: integer
|
|
nullable: true
|
|
line_deletions:
|
|
type: integer
|
|
nullable: true
|
|
lineno:
|
|
type: integer
|
|
nullable: true
|
|
lines:
|
|
type: integer
|
|
nullable: true
|
|
cursorpos:
|
|
type: integer
|
|
nullable: true
|
|
project_root_count:
|
|
type: integer
|
|
nullable: true
|
|
is_write:
|
|
type: boolean
|
|
nullable: true
|
|
source_type:
|
|
type: string
|
|
nullable: true
|
|
ysws_program:
|
|
type: string
|
|
nullable: true
|
|
ip_address:
|
|
type: string
|
|
nullable: true
|
|
'404':
|
|
description: user not found
|
|
"/api/admin/v1/user/projects":
|
|
get:
|
|
summary: Get admin user projects
|
|
tags:
|
|
- Admin Utils
|
|
description: Get projects for a user (Admin view).
|
|
security:
|
|
- AdminToken: []
|
|
parameters:
|
|
- name: user_id
|
|
in: query
|
|
description: User ID
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
username:
|
|
type: string
|
|
total_projects:
|
|
type: integer
|
|
projects:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
nullable: true
|
|
total_heartbeats:
|
|
type: integer
|
|
total_duration:
|
|
type: number
|
|
first_heartbeat:
|
|
type: number
|
|
nullable: true
|
|
last_heartbeat:
|
|
type: number
|
|
nullable: true
|
|
languages:
|
|
type: array
|
|
items:
|
|
type: string
|
|
repo:
|
|
type: string
|
|
nullable: true
|
|
repo_mapping_id:
|
|
type: integer
|
|
nullable: true
|
|
archived:
|
|
type: boolean
|
|
'404':
|
|
description: user not found
|
|
"/api/admin/v1/user/trust_logs":
|
|
get:
|
|
summary: Get user trust logs
|
|
tags:
|
|
- Admin Utils
|
|
description: Get trust level audit logs for a user.
|
|
security:
|
|
- AdminToken: []
|
|
parameters:
|
|
- name: user_id
|
|
in: query
|
|
description: User ID
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
trust_logs:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
previous_trust_level:
|
|
type: string
|
|
nullable: true
|
|
new_trust_level:
|
|
type: string
|
|
reason:
|
|
type: string
|
|
nullable: true
|
|
notes:
|
|
type: string
|
|
nullable: true
|
|
created_at:
|
|
type: string
|
|
format: date_time
|
|
changed_by:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
username:
|
|
type: string
|
|
display_name:
|
|
type: string
|
|
admin_level:
|
|
type: string
|
|
"/api/admin/v1/user/get_user_by_email":
|
|
post:
|
|
summary: Get user by email
|
|
tags:
|
|
- Admin Utils
|
|
description: Lookup user by email (POST).
|
|
security:
|
|
- AdminToken: []
|
|
parameters: []
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
email:
|
|
type: string
|
|
"/api/admin/v1/user/search_fuzzy":
|
|
post:
|
|
summary: Fuzzy search users
|
|
tags:
|
|
- Admin Utils
|
|
description: Search users by fuzzy matching.
|
|
security:
|
|
- AdminToken: []
|
|
parameters: []
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
users:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
username:
|
|
type: string
|
|
slack_username:
|
|
type: string
|
|
nullable: true
|
|
github_username:
|
|
type: string
|
|
nullable: true
|
|
slack_avatar_url:
|
|
type: string
|
|
nullable: true
|
|
github_avatar_url:
|
|
type: string
|
|
nullable: true
|
|
email:
|
|
type: string
|
|
rank_score:
|
|
type: number
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
query:
|
|
type: string
|
|
"/api/admin/v1/user/convict":
|
|
post:
|
|
summary: Convict user
|
|
tags:
|
|
- Admin Utils
|
|
description: Mark a user as convicted/banned.
|
|
security:
|
|
- AdminToken: []
|
|
parameters: []
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
message:
|
|
type: string
|
|
user:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
username:
|
|
type: string
|
|
trust_level:
|
|
type: string
|
|
updated_at:
|
|
type: string
|
|
format: date_time
|
|
audit_log:
|
|
type: object
|
|
properties:
|
|
changed_by:
|
|
type: string
|
|
reason:
|
|
type: string
|
|
notes:
|
|
type: string
|
|
nullable: true
|
|
timestamp:
|
|
type: string
|
|
format: date_time
|
|
'404':
|
|
description: user not found
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
reason:
|
|
type: string
|
|
"/api/admin/v1/check":
|
|
get:
|
|
summary: Check status
|
|
tags:
|
|
- Admin
|
|
description: Check if admin API is working.
|
|
security:
|
|
- AdminToken: []
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
"/api/admin/v1/banned_users":
|
|
get:
|
|
summary: Get banned users
|
|
tags:
|
|
- Admin
|
|
description: Get a list of banned users.
|
|
security:
|
|
- AdminToken: []
|
|
parameters:
|
|
- name: limit
|
|
in: query
|
|
required: false
|
|
description: 'Max results to return (default: 200, max: 1000)'
|
|
schema:
|
|
type: integer
|
|
- name: offset
|
|
in: query
|
|
required: false
|
|
description: 'Number of results to skip for pagination (default: 0)'
|
|
schema:
|
|
type: integer
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
banned_users:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: User ID
|
|
username:
|
|
type: string
|
|
description: Username
|
|
email:
|
|
type: string
|
|
description: Primary email or "no email"
|
|
'401':
|
|
description: unauthorized
|
|
"/api/admin/v1/permissions":
|
|
get:
|
|
summary: List Permissions
|
|
tags:
|
|
- Admin Resources
|
|
description: List system permissions. Requires superadmin privileges.
|
|
security:
|
|
- AdminToken: []
|
|
parameters:
|
|
- name: search
|
|
in: query
|
|
description: Search query
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
users:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
username:
|
|
type: string
|
|
display_name:
|
|
type: string
|
|
nullable: true
|
|
slack_username:
|
|
type: string
|
|
nullable: true
|
|
github_username:
|
|
type: string
|
|
nullable: true
|
|
admin_level:
|
|
type: string
|
|
email_addresses:
|
|
type: array
|
|
items:
|
|
type: string
|
|
created_at:
|
|
type: string
|
|
updated_at:
|
|
type: string
|
|
"/api/admin/v1/permissions/{id}":
|
|
patch:
|
|
summary: Update Permission
|
|
tags:
|
|
- Admin Resources
|
|
description: Update a user's admin level. Requires superadmin privileges.
|
|
security:
|
|
- AdminToken: []
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
message:
|
|
type: string
|
|
user:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
username:
|
|
type: string
|
|
display_name:
|
|
type: string
|
|
nullable: true
|
|
admin_level:
|
|
type: string
|
|
previous_admin_level:
|
|
type: string
|
|
updated_at:
|
|
type: string
|
|
'404':
|
|
description: not found handled
|
|
'422':
|
|
description: validation error handled
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
admin_level:
|
|
type: string
|
|
enum:
|
|
- superadmin
|
|
- admin
|
|
- viewer
|
|
- default
|
|
required:
|
|
- admin_level
|
|
"/api/hackatime/v1/users/{id}/heartbeats":
|
|
post:
|
|
summary: Push heartbeats (WakaTime compatible)
|
|
tags:
|
|
- WakaTime Compatibility
|
|
description: Endpoint used by WakaTime plugins to send heartbeat data to the
|
|
server. This is the core endpoint for tracking time.
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
description: User ID or "current" (recommended)
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'202':
|
|
description: accepted
|
|
'401':
|
|
description: unauthorized
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
entity:
|
|
type: string
|
|
type:
|
|
type: string
|
|
time:
|
|
type: number
|
|
project:
|
|
type: string
|
|
branch:
|
|
type: string
|
|
language:
|
|
type: string
|
|
is_write:
|
|
type: boolean
|
|
lineno:
|
|
type: integer
|
|
cursorpos:
|
|
type: integer
|
|
lines:
|
|
type: integer
|
|
category:
|
|
type: string
|
|
"/api/hackatime/v1/users/{id}/statusbar/today":
|
|
get:
|
|
summary: Get status bar today
|
|
tags:
|
|
- WakaTime Compatibility
|
|
description: Returns the total coding time for today. Used by editor plugins
|
|
to display the status bar widget.
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
description: User ID or "current"
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
type: object
|
|
properties:
|
|
grand_total:
|
|
type: object
|
|
properties:
|
|
total_seconds:
|
|
type: number
|
|
example: 7200.0
|
|
text:
|
|
type: string
|
|
example: 2h 30m / 4h today
|
|
goal:
|
|
type: object
|
|
nullable: true
|
|
properties:
|
|
target_seconds:
|
|
type: number
|
|
example: 14400
|
|
tracked_seconds:
|
|
type: number
|
|
example: 9000
|
|
completion_percent:
|
|
type: number
|
|
example: 62
|
|
complete:
|
|
type: boolean
|
|
example: false
|
|
'401':
|
|
description: unauthorized
|
|
"/api/hackatime/v1/users/current/stats/last_7_days":
|
|
get:
|
|
summary: Get last 7 days stats
|
|
tags:
|
|
- WakaTime Compatibility
|
|
description: Returns coding statistics for the last 7 days. Used by some WakaTime
|
|
dashboards.
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
type: object
|
|
properties:
|
|
username:
|
|
type: string
|
|
user_id:
|
|
type: string
|
|
start:
|
|
type: string
|
|
format: date_time
|
|
end:
|
|
type: string
|
|
format: date_time
|
|
status:
|
|
type: string
|
|
total_seconds:
|
|
type: number
|
|
daily_average:
|
|
type: number
|
|
days_including_holidays:
|
|
type: integer
|
|
range:
|
|
type: string
|
|
human_readable_range:
|
|
type: string
|
|
human_readable_total:
|
|
type: string
|
|
human_readable_daily_average:
|
|
type: string
|
|
is_coding_activity_visible:
|
|
type: boolean
|
|
is_other_usage_visible:
|
|
type: boolean
|
|
editors:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
total_seconds:
|
|
type: integer
|
|
percent:
|
|
type: number
|
|
digital:
|
|
type: string
|
|
text:
|
|
type: string
|
|
hours:
|
|
type: integer
|
|
minutes:
|
|
type: integer
|
|
seconds:
|
|
type: integer
|
|
languages:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
total_seconds:
|
|
type: integer
|
|
percent:
|
|
type: number
|
|
digital:
|
|
type: string
|
|
text:
|
|
type: string
|
|
hours:
|
|
type: integer
|
|
minutes:
|
|
type: integer
|
|
seconds:
|
|
type: integer
|
|
machines:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
total_seconds:
|
|
type: integer
|
|
percent:
|
|
type: number
|
|
digital:
|
|
type: string
|
|
text:
|
|
type: string
|
|
hours:
|
|
type: integer
|
|
minutes:
|
|
type: integer
|
|
seconds:
|
|
type: integer
|
|
projects:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
total_seconds:
|
|
type: integer
|
|
percent:
|
|
type: number
|
|
digital:
|
|
type: string
|
|
text:
|
|
type: string
|
|
hours:
|
|
type: integer
|
|
minutes:
|
|
type: integer
|
|
seconds:
|
|
type: integer
|
|
operating_systems:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
total_seconds:
|
|
type: integer
|
|
percent:
|
|
type: number
|
|
digital:
|
|
type: string
|
|
text:
|
|
type: string
|
|
hours:
|
|
type: integer
|
|
minutes:
|
|
type: integer
|
|
seconds:
|
|
type: integer
|
|
categories:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
total_seconds:
|
|
type: integer
|
|
percent:
|
|
type: number
|
|
digital:
|
|
type: string
|
|
text:
|
|
type: string
|
|
hours:
|
|
type: integer
|
|
minutes:
|
|
type: integer
|
|
seconds:
|
|
type: integer
|
|
'401':
|
|
description: unauthorized
|
|
"/api/internal/revoke":
|
|
post:
|
|
summary: Revoke access
|
|
tags:
|
|
- Internal
|
|
description: Internal endpoint to revoke access tokens. Use with caution. Requires
|
|
HKA_REVOCATION_KEY environment variable authentication. This is used for Revoker
|
|
to allow security researchers to revoke compromised tokens.
|
|
security:
|
|
- InternalToken: []
|
|
parameters: []
|
|
responses:
|
|
'201':
|
|
description: created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
status:
|
|
type: string
|
|
token_type:
|
|
type: string
|
|
owner_email:
|
|
type: string
|
|
nullable: true
|
|
key_name:
|
|
type: string
|
|
nullable: true
|
|
'422':
|
|
description: unprocessable entity
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
error:
|
|
type: string
|
|
required:
|
|
- success
|
|
- error
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
token:
|
|
type: string
|
|
submitter:
|
|
type: string
|
|
comment:
|
|
type: string
|
|
required:
|
|
- token
|
|
"/api/summary":
|
|
get:
|
|
summary: Get WakaTime-compatible summary
|
|
tags:
|
|
- WakaTime Compatibility
|
|
description: Returns a summary of coding activity in a format compatible with
|
|
WakaTime clients. This endpoint supports querying by date range, interval,
|
|
or specific user (admin/privileged only).
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
parameters:
|
|
- name: start
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date
|
|
description: Start date (YYYY-MM-DD)
|
|
- name: end
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date
|
|
description: End date (YYYY-MM-DD)
|
|
- name: interval
|
|
in: query
|
|
description: Interval (e.g. today, yesterday, week, month)
|
|
schema:
|
|
type: string
|
|
- name: project
|
|
in: query
|
|
description: Project name (optional)
|
|
schema:
|
|
type: string
|
|
- name: user
|
|
in: query
|
|
description: Slack UID of the user (optional, for admin use)
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
user_id:
|
|
type: string
|
|
nullable: true
|
|
from:
|
|
type: string
|
|
format: date_time
|
|
to:
|
|
type: string
|
|
format: date_time
|
|
projects:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
key:
|
|
type: string
|
|
total:
|
|
type: number
|
|
languages:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
key:
|
|
type: string
|
|
total:
|
|
type: number
|
|
editors:
|
|
type: object
|
|
nullable: true
|
|
operating_systems:
|
|
type: object
|
|
nullable: true
|
|
machines:
|
|
type: object
|
|
nullable: true
|
|
categories:
|
|
type: object
|
|
nullable: true
|
|
branches:
|
|
type: object
|
|
nullable: true
|
|
entities:
|
|
type: object
|
|
nullable: true
|
|
labels:
|
|
type: object
|
|
nullable: true
|
|
'400':
|
|
description: bad request
|
|
"/api/v1/authenticated/me":
|
|
get:
|
|
summary: Get current user info
|
|
tags:
|
|
- Authenticated
|
|
description: Returns detailed information about the currently authenticated
|
|
user.
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
emails:
|
|
type: array
|
|
items:
|
|
type: string
|
|
slack_id:
|
|
type: string
|
|
nullable: true
|
|
github_username:
|
|
type: string
|
|
nullable: true
|
|
trust_factor:
|
|
type: object
|
|
properties:
|
|
trust_level:
|
|
type: string
|
|
trust_value:
|
|
type: integer
|
|
'401':
|
|
description: unauthorized
|
|
"/api/v1/authenticated/hours":
|
|
get:
|
|
summary: Get hours
|
|
tags:
|
|
- Authenticated
|
|
description: Returns the total coding hours for the authenticated user.
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
parameters:
|
|
- name: start_date
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date
|
|
description: Start date (YYYY-MM-DD)
|
|
- name: end_date
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date
|
|
description: End date (YYYY-MM-DD)
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
start_date:
|
|
type: string
|
|
format: date
|
|
example: '2024-03-13'
|
|
end_date:
|
|
type: string
|
|
format: date
|
|
example: '2024-03-20'
|
|
total_seconds:
|
|
type: number
|
|
example: 153000.0
|
|
'401':
|
|
description: unauthorized
|
|
"/api/v1/authenticated/streak":
|
|
get:
|
|
summary: Get streak
|
|
tags:
|
|
- Authenticated
|
|
description: Returns the current streak information (days coded in a row).
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
streak_days:
|
|
type: integer
|
|
example: 5
|
|
'401':
|
|
description: unauthorized
|
|
"/api/v1/authenticated/projects":
|
|
get:
|
|
summary: Get projects
|
|
tags:
|
|
- Authenticated
|
|
description: Returns a list of projects associated with the authenticated user.
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
parameters:
|
|
- name: include_archived
|
|
in: query
|
|
description: Include archived projects (true/false)
|
|
schema:
|
|
type: boolean
|
|
- name: projects
|
|
in: query
|
|
description: Comma-separated list of project names
|
|
schema:
|
|
type: string
|
|
- name: since
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date_time
|
|
description: Project discovery start time (ISO 8601)
|
|
- name: until
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date_time
|
|
description: Project discovery end time (ISO 8601)
|
|
- name: until_date
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date_time
|
|
description: Alias for until
|
|
- name: start
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date_time
|
|
description: Stats start time (ISO 8601)
|
|
- name: end
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date_time
|
|
description: Stats end time (ISO 8601)
|
|
- name: start_date
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date_time
|
|
description: Alias for start
|
|
- name: end_date
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date_time
|
|
description: Alias for end
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
projects:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
example: hackatime
|
|
total_seconds:
|
|
type: number
|
|
example: 3600.0
|
|
most_recent_heartbeat:
|
|
type: string
|
|
format: date_time
|
|
nullable: true
|
|
languages:
|
|
type: array
|
|
items:
|
|
type: string
|
|
archived:
|
|
type: boolean
|
|
'401':
|
|
description: unauthorized
|
|
"/api/v1/authenticated/api_keys":
|
|
get:
|
|
summary: Get API keys
|
|
tags:
|
|
- Authenticated
|
|
description: 'Returns the API keys for the authenticated user. Warning: This
|
|
returns sensitive information.'
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
token:
|
|
type: string
|
|
example: waka_...
|
|
'401':
|
|
description: unauthorized
|
|
"/api/v1/authenticated/heartbeats/latest":
|
|
get:
|
|
summary: Get latest heartbeat
|
|
tags:
|
|
- Authenticated
|
|
description: Returns the absolutely latest heartbeat processed for the user.
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
created_at:
|
|
type: string
|
|
format: date_time
|
|
time:
|
|
type: number
|
|
category:
|
|
type: string
|
|
project:
|
|
type: string
|
|
language:
|
|
type: string
|
|
editor:
|
|
type: string
|
|
operating_system:
|
|
type: string
|
|
machine:
|
|
type: string
|
|
entity:
|
|
type: string
|
|
'401':
|
|
description: unauthorized
|
|
"/api/v1/external/slack/oauth":
|
|
post:
|
|
summary: Create user from Slack OAuth
|
|
tags:
|
|
- External Integrations
|
|
description: Callback endpoint for Slack OAuth to create or update a user.
|
|
security:
|
|
- Bearer: []
|
|
parameters: []
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
username:
|
|
type: string
|
|
email:
|
|
type: string
|
|
nullable: true
|
|
'400':
|
|
description: bad request
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
token:
|
|
type: string
|
|
description: Slack OAuth Token
|
|
required:
|
|
- token
|
|
"/api/v1/ysws_programs":
|
|
get:
|
|
summary: List YSWS Programs
|
|
tags:
|
|
- YSWS Programs
|
|
description: List available YSWS (Your Ship We Ship) programs.
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
example: onboard
|
|
"/api/v1/ysws_programs/claim":
|
|
post:
|
|
summary: Claim YSWS Program
|
|
tags:
|
|
- YSWS Programs
|
|
description: Claim a YSWS program reward.
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
parameters: []
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
example: Successfully claimed 100 heartbeats
|
|
claimed_count:
|
|
type: integer
|
|
example: 100
|
|
'409':
|
|
description: conflict
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
conflicts:
|
|
type: array
|
|
items:
|
|
type: array
|
|
minItems: 2
|
|
maxItems: 2
|
|
items: {}
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
program_id:
|
|
type: integer
|
|
description: YSWS Program ID
|
|
user_id:
|
|
type: string
|
|
description: User ID or Slack UID
|
|
start_time:
|
|
type: string
|
|
format: date_time
|
|
description: Start time of the claim period
|
|
end_time:
|
|
type: string
|
|
format: date_time
|
|
description: End time of the claim period
|
|
project:
|
|
type: string
|
|
description: Project name (optional)
|
|
nullable: true
|
|
required:
|
|
- program_id
|
|
- user_id
|
|
- start_time
|
|
- end_time
|
|
"/api/v1/leaderboard":
|
|
get:
|
|
summary: Get daily leaderboard (Alias)
|
|
tags:
|
|
- Leaderboard
|
|
description: Alias for /api/v1/leaderboard/daily. Returns the daily leaderboard.
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
period:
|
|
type: string
|
|
example: daily
|
|
start_date:
|
|
type: string
|
|
format: date
|
|
example: '2024-03-20'
|
|
date_range:
|
|
type: string
|
|
example: Wed, Mar 20, 2024
|
|
generated_at:
|
|
type: string
|
|
format: date_time
|
|
example: '2024-03-20T10:00:00Z'
|
|
entries:
|
|
type: array
|
|
items:
|
|
"$ref": "#/components/schemas/LeaderboardEntry"
|
|
"/api/v1/leaderboard/daily":
|
|
get:
|
|
summary: Get daily leaderboard
|
|
tags:
|
|
- Leaderboard
|
|
description: Leaderboard is currently being generated
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
period:
|
|
type: string
|
|
example: daily
|
|
start_date:
|
|
type: string
|
|
format: date
|
|
example: '2024-03-20'
|
|
date_range:
|
|
type: string
|
|
example: Wed, Mar 20, 2024
|
|
generated_at:
|
|
type: string
|
|
format: date_time
|
|
example: '2024-03-20T10:00:00Z'
|
|
entries:
|
|
type: array
|
|
items:
|
|
"$ref": "#/components/schemas/LeaderboardEntry"
|
|
'503':
|
|
description: service unavailable
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/Error"
|
|
"/api/v1/leaderboard/weekly":
|
|
get:
|
|
summary: Get weekly leaderboard
|
|
tags:
|
|
- Leaderboard
|
|
description: Returns the weekly leaderboard of coding time (last 7 days). Requires
|
|
STATS_API_KEY.
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
period:
|
|
type: string
|
|
example: last_7_days
|
|
start_date:
|
|
type: string
|
|
format: date
|
|
example: '2024-03-13'
|
|
date_range:
|
|
type: string
|
|
example: Mar 13 - Mar 20, 2024
|
|
generated_at:
|
|
type: string
|
|
format: date_time
|
|
example: '2024-03-20T10:00:00Z'
|
|
entries:
|
|
type: array
|
|
items:
|
|
"$ref": "#/components/schemas/LeaderboardEntry"
|
|
"/api/v1/my/heartbeats/most_recent":
|
|
get:
|
|
summary: Get most recent heartbeat
|
|
tags:
|
|
- My Data
|
|
description: Returns the most recent heartbeat for the authenticated user. Useful
|
|
for checking if the user is currently active.
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
parameters:
|
|
- name: source_type
|
|
in: query
|
|
description: Filter by source type (e.g. "direct_entry")
|
|
schema:
|
|
type: string
|
|
- name: editor
|
|
in: query
|
|
description: Filter by editor name (e.g. "VSCode")
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
'401':
|
|
description: unauthorized
|
|
"/api/v1/my/heartbeats":
|
|
get:
|
|
summary: Get heartbeats
|
|
tags:
|
|
- My Data
|
|
description: Returns a list of heartbeats for the authenticated user within
|
|
a time range. This is the raw data stream.
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
parameters:
|
|
- name: start_time
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date_time
|
|
description: Start time (ISO 8601)
|
|
- name: end_time
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date_time
|
|
description: End time (ISO 8601)
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
'401':
|
|
description: unauthorized
|
|
"/my/heartbeats/export":
|
|
post:
|
|
summary: Export Heartbeats
|
|
tags:
|
|
- My Data
|
|
description: Export your heartbeats as a JSON file.
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
parameters:
|
|
- name: all_data
|
|
in: query
|
|
description: Export all data (true/false)
|
|
schema:
|
|
type: boolean
|
|
- name: start_date
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date
|
|
description: Start date (YYYY-MM-DD)
|
|
- name: end_date
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date
|
|
description: End date (YYYY-MM-DD)
|
|
responses:
|
|
'302':
|
|
description: redirect
|
|
"/my/heartbeat_imports":
|
|
post:
|
|
summary: Create Heartbeat Import
|
|
tags:
|
|
- My Data
|
|
description: Start a development upload import or a one-time remote dump import.
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
parameters: []
|
|
responses:
|
|
'202':
|
|
description: accepted
|
|
requestBody:
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- wakatime_dump
|
|
- hackatime_v1_dump
|
|
description: Remote import provider preset
|
|
"/my/projects":
|
|
get:
|
|
summary: List Project Repo Mappings
|
|
tags:
|
|
- My Projects
|
|
description: List mappings between local project names and Git repositories.
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
parameters:
|
|
- name: interval
|
|
in: query
|
|
description: 'Time interval (e.g., daily, weekly). Default: daily'
|
|
schema:
|
|
type: string
|
|
- name: from
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date
|
|
description: Start date (YYYY-MM-DD)
|
|
- name: to
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date
|
|
description: End date (YYYY-MM-DD)
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
"/my/project_repo_mappings/{project_name}":
|
|
parameters:
|
|
- name: project_name
|
|
in: path
|
|
description: Project name (encoded)
|
|
required: true
|
|
schema:
|
|
type: string
|
|
patch:
|
|
summary: Update Project Repo Mapping
|
|
tags:
|
|
- My Projects
|
|
description: Update the Git repository URL for a project mapping.
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
parameters: []
|
|
responses:
|
|
'302':
|
|
description: redirect
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
repo_url:
|
|
type: string
|
|
example: https://github.com/hackclub/hackatime
|
|
required:
|
|
- repo_url
|
|
"/my/project_repo_mappings/{project_name}/archive":
|
|
parameters:
|
|
- name: project_name
|
|
in: path
|
|
description: Project name (encoded)
|
|
required: true
|
|
schema:
|
|
type: string
|
|
patch:
|
|
summary: Archive Project Mapping
|
|
tags:
|
|
- My Projects
|
|
description: Archive a project mapping so it does not appear in active lists.
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
responses:
|
|
'302':
|
|
description: redirect
|
|
"/my/project_repo_mappings/{project_name}/unarchive":
|
|
parameters:
|
|
- name: project_name
|
|
in: path
|
|
description: Project name (encoded)
|
|
required: true
|
|
schema:
|
|
type: string
|
|
patch:
|
|
summary: Unarchive Project Mapping
|
|
tags:
|
|
- My Projects
|
|
description: Restore an archived project mapping.
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
responses:
|
|
'302':
|
|
description: redirect
|
|
"/my/settings/rotate_api_key":
|
|
post:
|
|
summary: Rotate API Key
|
|
tags:
|
|
- My Settings
|
|
description: 'Rotate your API key. Returns the new token. Warning: Old token
|
|
will stop working immediately.'
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
"/my/heartbeat_imports/{id}":
|
|
get:
|
|
summary: Get Heartbeat Import Status
|
|
tags:
|
|
- My Data
|
|
description: Fetch the latest state for a heartbeat import run.
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
description: Heartbeat import run id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
"/deletion":
|
|
post:
|
|
summary: Create Deletion Request
|
|
tags:
|
|
- My Settings
|
|
description: Request deletion of your account and data.
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
responses:
|
|
'302':
|
|
description: redirect
|
|
delete:
|
|
summary: Cancel Deletion Request
|
|
tags:
|
|
- My Settings
|
|
description: Cancel a pending deletion request.
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
responses:
|
|
'302':
|
|
description: redirect
|
|
"/api/v1/stats":
|
|
get:
|
|
summary: Get total coding time (Admin Only)
|
|
tags:
|
|
- Stats
|
|
description: Returns the total coding time for all users, optionally filtered
|
|
by user or date range. Requires admin privileges via STATS_API_KEY.
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
parameters:
|
|
- name: start_date
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date
|
|
description: Start date (YYYY-MM-DD), defaults to 10 years ago
|
|
- name: end_date
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date
|
|
description: End date (YYYY-MM-DD), defaults to today
|
|
- name: username
|
|
in: query
|
|
description: Filter by username (optional)
|
|
schema:
|
|
type: string
|
|
- name: user_email
|
|
in: query
|
|
description: Filter by user email (optional)
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: successful with invalid credentials
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: integer
|
|
example: 123456
|
|
'404':
|
|
description: user not found
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
"$ref": "#/components/schemas/Error"
|
|
'422':
|
|
description: invalid date
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
"$ref": "#/components/schemas/Error"
|
|
"/api/v1/users/{username}/heartbeats/spans":
|
|
get:
|
|
summary: Get heartbeat spans
|
|
tags:
|
|
- Users
|
|
description: Get time spans of coding activity.
|
|
parameters:
|
|
- name: username
|
|
in: path
|
|
description: Username
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: start_date
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date
|
|
description: Start date (YYYY-MM-DD)
|
|
- name: end_date
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date
|
|
description: End date (YYYY-MM-DD)
|
|
- name: project
|
|
in: query
|
|
description: Filter by specific project
|
|
schema:
|
|
type: string
|
|
- name: filter_by_project
|
|
in: query
|
|
description: Filter by multiple projects (comma-separated)
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
spans:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
start:
|
|
type: number
|
|
end:
|
|
type: number
|
|
project:
|
|
type: string
|
|
'422':
|
|
description: invalid date
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/Error"
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
"/api/v1/users/{username}/trust_factor":
|
|
get:
|
|
summary: Get trust factor
|
|
tags:
|
|
- Users
|
|
description: Get the trust level/factor for a user. Higher trust values indicate
|
|
more verified activity.
|
|
parameters:
|
|
- name: username
|
|
in: path
|
|
description: Username, Slack ID, or User ID
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
trust_level:
|
|
type: string
|
|
example: verified
|
|
trust_value:
|
|
type: integer
|
|
example: 2
|
|
'404':
|
|
description: not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/Error"
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
"/api/v1/users/{username}/projects":
|
|
get:
|
|
summary: Get user projects
|
|
tags:
|
|
- Users
|
|
description: Get a list of projects a user has coded on recently (last 30 days).
|
|
parameters:
|
|
- name: username
|
|
in: path
|
|
description: Username
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
projects:
|
|
type: array
|
|
items:
|
|
type: string
|
|
example: hackatime
|
|
'404':
|
|
description: not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/Error"
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
"/api/v1/users/{username}/project/{project_name}":
|
|
get:
|
|
summary: Get specific project stats
|
|
tags:
|
|
- Users
|
|
description: Get detailed stats for a specific project.
|
|
parameters:
|
|
- name: username
|
|
in: path
|
|
description: Username
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: project_name
|
|
in: path
|
|
description: Project Name
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: start
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date_time
|
|
description: Stats start time (ISO 8601)
|
|
- name: end
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date_time
|
|
description: Stats end time (ISO 8601)
|
|
- name: start_date
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date_time
|
|
description: Start date (ISO 8601) for stats calculation
|
|
- name: end_date
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date_time
|
|
description: End date (ISO 8601) for stats calculation
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
total_seconds:
|
|
type: number
|
|
languages:
|
|
type: array
|
|
items:
|
|
type: string
|
|
repo_url:
|
|
type: string
|
|
nullable: true
|
|
total_heartbeats:
|
|
type: integer
|
|
first_heartbeat:
|
|
type: string
|
|
format: date_time
|
|
nullable: true
|
|
last_heartbeat:
|
|
type: string
|
|
format: date_time
|
|
nullable: true
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
"/api/v1/users/{username}/projects/details":
|
|
get:
|
|
summary: Get detailed project stats
|
|
tags:
|
|
- Users
|
|
description: Get detailed breakdown of all user projects.
|
|
parameters:
|
|
- name: username
|
|
in: path
|
|
description: Username
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: projects
|
|
in: query
|
|
description: Comma-separated list of projects to filter
|
|
schema:
|
|
type: string
|
|
- name: since
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date_time
|
|
description: Start time (ISO 8601) for project discovery
|
|
- name: until
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date_time
|
|
description: End time (ISO 8601) for project discovery
|
|
- name: until_date
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date_time
|
|
description: End time (ISO 8601) for project discovery
|
|
- name: start
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date_time
|
|
description: Stats start time (ISO 8601)
|
|
- name: end
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date_time
|
|
description: Stats end time (ISO 8601)
|
|
- name: start_date
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date_time
|
|
description: Start date (ISO 8601) for stats calculation
|
|
- name: end_date
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date_time
|
|
description: End date (ISO 8601) for stats calculation
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
projects:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
total_seconds:
|
|
type: number
|
|
languages:
|
|
type: array
|
|
items:
|
|
type: string
|
|
repo_url:
|
|
type: string
|
|
nullable: true
|
|
total_heartbeats:
|
|
type: integer
|
|
first_heartbeat:
|
|
type: string
|
|
format: date_time
|
|
nullable: true
|
|
last_heartbeat:
|
|
type: string
|
|
format: date_time
|
|
nullable: true
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
"/api/v1/users/{username}/stats":
|
|
get:
|
|
summary: Get user stats
|
|
tags:
|
|
- Stats
|
|
description: User has disabled public stats lookup
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
parameters:
|
|
- name: username
|
|
in: path
|
|
description: Username, Slack ID, or User ID
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: start_date
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date
|
|
description: Start date (YYYY-MM-DD)
|
|
- name: end_date
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date
|
|
description: End date (YYYY-MM-DD)
|
|
- name: limit
|
|
in: query
|
|
description: Limit number of results
|
|
schema:
|
|
type: integer
|
|
- name: features
|
|
in: query
|
|
description: Comma-separated list of features to include (e.g., languages,projects)
|
|
schema:
|
|
type: string
|
|
- name: filter_by_project
|
|
in: query
|
|
description: Filter results by specific project names (comma-separated)
|
|
schema:
|
|
type: string
|
|
- name: filter_by_category
|
|
in: query
|
|
description: Filter results by category (comma-separated)
|
|
schema:
|
|
type: string
|
|
- name: boundary_aware
|
|
in: query
|
|
description: Use boundary aware calculation
|
|
schema:
|
|
type: boolean
|
|
- name: total_seconds
|
|
in: query
|
|
description: Return only total seconds
|
|
schema:
|
|
type: boolean
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
"$ref": "#/components/schemas/StatsSummary"
|
|
trust_factor:
|
|
type: object
|
|
properties:
|
|
trust_level:
|
|
type: string
|
|
example: blue
|
|
trust_value:
|
|
type: integer
|
|
example: 3
|
|
'403':
|
|
description: forbidden
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/Error"
|
|
'404':
|
|
description: user not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/Error"
|
|
'422':
|
|
description: invalid date
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/Error"
|
|
"/api/v1/users/lookup_email/{email}":
|
|
get:
|
|
summary: Lookup user by email
|
|
tags:
|
|
- Users
|
|
description: Find a user ID by their email address. Useful for integrations
|
|
that need to map emails to Hackatime users. Requires STATS_API_KEY.
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
parameters:
|
|
- name: email
|
|
in: path
|
|
description: Email address to lookup
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
example: 42
|
|
email:
|
|
type: string
|
|
example: test@example.com
|
|
'404':
|
|
description: not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: User not found
|
|
email:
|
|
type: string
|
|
example: unknown@example.com
|
|
"/api/v1/users/lookup_slack_uid/{slack_uid}":
|
|
get:
|
|
summary: Lookup user by Slack UID
|
|
tags:
|
|
- Users
|
|
description: Find a user ID by their Slack User ID. Requires STATS_API_KEY.
|
|
security:
|
|
- Bearer: []
|
|
ApiKeyAuth: []
|
|
parameters:
|
|
- name: slack_uid
|
|
in: path
|
|
description: Slack User ID (e.g. U123456)
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
example: 42
|
|
slack_uid:
|
|
type: string
|
|
example: TEST123456
|
|
'404':
|
|
description: not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: User not found
|
|
slack_uid:
|
|
type: string
|
|
example: U000000
|
|
"/sailors_log/slack/commands":
|
|
post:
|
|
summary: Handle Sailor's Log Command
|
|
tags:
|
|
- Slack
|
|
description: Handle incoming Slack slash commands for Sailor's Log (/sailorslog).
|
|
parameters: []
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
response_type:
|
|
type: string
|
|
text:
|
|
type: string
|
|
nullable: true
|
|
blocks:
|
|
type: array
|
|
items:
|
|
type: object
|
|
requestBody:
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: string
|
|
"/timedump/slack/commands":
|
|
post:
|
|
summary: Handle Timedump Command
|
|
tags:
|
|
- Slack
|
|
description: Handle incoming Slack slash commands for Timedump (/timedump).
|
|
parameters: []
|
|
responses:
|
|
'200':
|
|
description: successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
response_type:
|
|
type: string
|
|
text:
|
|
type: string
|
|
nullable: true
|
|
blocks:
|
|
type: array
|
|
items:
|
|
type: object
|
|
requestBody:
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: string
|
|
components:
|
|
securitySchemes:
|
|
Bearer:
|
|
type: http
|
|
scheme: bearer
|
|
description: User API Key from settings, prefixed with "Bearer"
|
|
AdminToken:
|
|
type: http
|
|
scheme: bearer
|
|
description: Admin API Key, prefixed with "Bearer"
|
|
InternalToken:
|
|
type: http
|
|
scheme: bearer
|
|
description: Internal API Key from env, prefixed with "Bearer"
|
|
ApiKeyAuth:
|
|
type: apiKey
|
|
name: api_key
|
|
in: query
|
|
description: User API Key from settings
|
|
schemas:
|
|
Error:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: Unauthorized
|
|
required:
|
|
- error
|
|
User:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
example: 1
|
|
username:
|
|
type: string
|
|
example: orpheus
|
|
avatar_url:
|
|
type: string
|
|
example: https://hackatime.hackclub.com/images/athena.png
|
|
display_name:
|
|
type: string
|
|
example: Orpheus
|
|
is_admin:
|
|
type: boolean
|
|
example: false
|
|
Heartbeat:
|
|
type: object
|
|
description: A single unit of coding activity representing a specific moment
|
|
in time.
|
|
properties:
|
|
id:
|
|
type: integer
|
|
example: 1024
|
|
entity:
|
|
type: string
|
|
example: "/Users/orpheus/hackatime/app/services/chaos_monkey_service.rb"
|
|
description: File path or app name being accessed
|
|
type:
|
|
type: string
|
|
example: file
|
|
enum:
|
|
- file
|
|
- app
|
|
category:
|
|
type: string
|
|
example: coding
|
|
enum:
|
|
- advising
|
|
- ai coding
|
|
- animating
|
|
- browsing
|
|
- building
|
|
- code reviewing
|
|
- coding
|
|
- communicating
|
|
- configuring
|
|
- debugging
|
|
- designing
|
|
- indexing
|
|
- learning
|
|
- manual testing
|
|
- meeting
|
|
- notes
|
|
- planning
|
|
- researching
|
|
- running tests
|
|
- supporting
|
|
- translating
|
|
- writing docs
|
|
- writing tests
|
|
time:
|
|
type: number
|
|
format: float
|
|
example: 1709251200.0
|
|
description: Unix timestamp of the activity
|
|
project:
|
|
type: string
|
|
example: hackatime
|
|
branch:
|
|
type: string
|
|
example: main
|
|
language:
|
|
type: string
|
|
example: Ruby
|
|
is_write:
|
|
type: boolean
|
|
example: true
|
|
editor:
|
|
type: string
|
|
example: VS Code
|
|
operating_system:
|
|
type: string
|
|
example: Mac
|
|
machine:
|
|
type: string
|
|
example: Orpheus-MacBook-Pro
|
|
cursorpos:
|
|
type: integer
|
|
example: 123
|
|
lineno:
|
|
type: integer
|
|
example: 42
|
|
lines:
|
|
type: integer
|
|
example: 100
|
|
line_additions:
|
|
type: integer
|
|
example: 5
|
|
line_deletions:
|
|
type: integer
|
|
example: 2
|
|
LeaderboardEntry:
|
|
type: object
|
|
properties:
|
|
rank:
|
|
type: integer
|
|
example: 1
|
|
user:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
example: 42
|
|
username:
|
|
type: string
|
|
example: goat_heidi
|
|
avatar_url:
|
|
type: string
|
|
example: https://...
|
|
total_seconds:
|
|
type: number
|
|
example: 14500.5
|
|
description: Total coding duration in seconds for the period
|
|
StatsSummary:
|
|
type: object
|
|
properties:
|
|
total_seconds:
|
|
type: number
|
|
example: 3600.0
|
|
daily_average:
|
|
type: number
|
|
example: 1800.0
|
|
languages:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
example: Ruby
|
|
total_seconds:
|
|
type: number
|
|
example: 2400.0
|
|
percent:
|
|
type: number
|
|
example: 66.6
|
|
projects:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
example: hackatime
|
|
total_seconds:
|
|
type: number
|
|
example: 3600.0
|
|
percent:
|
|
type: number
|
|
example: 100.0
|
|
editors:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
example: VS Code
|
|
total_seconds:
|
|
type: number
|
|
example: 3600.0
|
|
percent:
|
|
type: number
|
|
example: 100.0
|
|
streak:
|
|
type: integer
|
|
example: 7
|
|
description: Number of consecutive days the user has coded
|
|
AdminApiKey:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
example: 1
|
|
name:
|
|
type: string
|
|
example: CI/CD Key
|
|
last_used_at:
|
|
type: string
|
|
format: date-time
|
|
nullable: true
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
DeletionRequest:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
example: 101
|
|
user_id:
|
|
type: integer
|
|
example: 42
|
|
status:
|
|
type: string
|
|
example: pending
|
|
enum:
|
|
- pending
|
|
- approved
|
|
- cancelled
|
|
- completed
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
TrustLevelAuditLog:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
example: 505
|
|
user_id:
|
|
type: integer
|
|
example: 42
|
|
actor_id:
|
|
type: integer
|
|
example: 1
|
|
action:
|
|
type: string
|
|
example: upgraded_to_verified
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
Permission:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
example: 1
|
|
role:
|
|
type: string
|
|
example: admin
|
|
resource_type:
|
|
type: string
|
|
example: User
|
|
resource_id:
|
|
type: integer
|
|
nullable: true
|
|
WakatimeMirror:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
example: 7
|
|
target_url:
|
|
type: string
|
|
example: https://api.wakatime.com/api/v1/users/current/heartbeats
|
|
last_sync_at:
|
|
type: string
|
|
format: date-time
|
|
nullable: true
|
|
status:
|
|
type: string
|
|
example: active
|
|
ProjectRepoMapping:
|
|
type: object
|
|
properties:
|
|
project_name:
|
|
type: string
|
|
example: hackatime
|
|
repository:
|
|
type: object
|
|
properties:
|
|
url:
|
|
type: string
|
|
example: https://github.com/hackclub/hackatime
|
|
homepage:
|
|
type: string
|
|
example: https://hackatime.hackclub.com
|
|
is_archived:
|
|
type: boolean
|
|
example: false
|
|
Extension:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
example: vscode
|
|
name:
|
|
type: string
|
|
example: VS Code
|
|
download_url:
|
|
type: string
|
|
example: https://marketplace.visualstudio.com/items?itemName=WakaTime.vscode-wakatime
|
|
version:
|
|
type: string
|
|
example: 24.0.0
|
|
Summary:
|
|
type: object
|
|
properties:
|
|
user_id:
|
|
type: string
|
|
nullable: true
|
|
example: U123456
|
|
from:
|
|
type: string
|
|
format: date-time
|
|
example: '2023-01-01T00:00:00Z'
|
|
to:
|
|
type: string
|
|
format: date-time
|
|
example: '2023-01-31T23:59:59Z'
|
|
projects:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
key:
|
|
type: string
|
|
example: hackatime
|
|
total:
|
|
type: number
|
|
example: 3600.0
|
|
languages:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
key:
|
|
type: string
|
|
example: Ruby
|
|
total:
|
|
type: number
|
|
example: 1200.0
|
|
editors:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
key:
|
|
type: string
|
|
example: VS Code
|
|
total:
|
|
type: number
|
|
example: 3600.0
|
|
operating_systems:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
key:
|
|
type: string
|
|
example: Mac
|
|
total:
|
|
type: number
|
|
example: 3600.0
|
|
machines:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
key:
|
|
type: string
|
|
example: MacBook-Pro
|
|
total:
|
|
type: number
|
|
example: 3600.0
|
|
servers:
|
|
- url: https://{defaultHost}
|
|
description: Production API
|
|
variables:
|
|
defaultHost:
|
|
default: hackatime.hackclub.com
|
|
- url: http://{localHost}
|
|
description: Local Development API
|
|
variables:
|
|
localHost:
|
|
default: localhost:3000
|