Hackatime API

https://hackatime.hackclub.com/api-docs/v1/
Admin
Hackatime API provides access to coding activity data and supports the WakaTime spec for use with...
Tokens:25,686
Snippets:94
Trust Score:10
Update:7 months ago
Show doc for...
Tokens:
Raw
### GET /api/v1/leaderboard

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

Alias for /api/v1/leaderboard/daily. Returns the daily leaderboard.

```APIDOC
## GET /api/v1/leaderboard

### Description
Alias for /api/v1/leaderboard/daily. Returns the daily leaderboard.

### Method
GET

### Endpoint
/api/v1/leaderboard

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **period** (string) - The period for the leaderboard. Example: `daily`
- **start_date** (string, format: date) - The start date of the leaderboard period. Example: `2024-03-20`
- **date_range** (string) - The date range covered by the leaderboard.

#### Response Example
```json
{
  "period": "daily",
  "start_date": "2024-03-20",
  "date_range": "2024-03-20 - 2024-03-20"
}
```
```

--------------------------------

### GET /api/admin/v1/user/info_batch

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

Fetches information for multiple users simultaneously using their IDs.

```APIDOC
## GET /api/admin/v1/user/info_batch

### Description
Get info for multiple users.

### Method
GET

### Endpoint
/api/admin/v1/user/info_batch

### Parameters
#### Query Parameters
- **ids** (array of integers) - Required - User IDs

### Response
#### Success Response (200)
- **users** (array) - An array of user objects.
  - **id** (integer) - The user's ID.
  - **username** (string) - The user's username.
  - **display_name** (string) - The user's display name.
  - **slack_uid** (string, nullable) - The user's Slack UID.
  - **slack_username** (string, nullable) - The user's Slack username.
  - **github_username** (string, nullable) - The user's GitHub username.
  - **timezone** (string, nullable) - The user's timezone.
  - **country_code** (string, nullable) - The user's country code.
  - **trust_level** (string) - The user's trust level.
  - **avatar_url** (string, nullable) - The URL of the user's avatar.
  - **slack_avatar_url** (string, nullable) - The URL of the user's Slack avatar.
  - **github_avatar_url** (string, nullable) - The URL of the user's GitHub avatar.

#### Response Example
```json
{
  "users": [
    {
      "id": 1,
      "username": "johndoe",
      "display_name": "John Doe",
      "slack_uid": "U12345",
      "slack_username": "john.doe",
      "github_username": "johndoe",
      "timezone": "UTC",
      "country_code": "US",
      "trust_level": "high",
      "avatar_url": "https://example.com/avatar.jpg",
      "slack_avatar_url": "https://example.com/slack_avatar.jpg",
      "github_avatar_url": "https://example.com/github_avatar.jpg"
    }
  ]
}
```
```

--------------------------------

### GET /api/admin/v1/check

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

Checks the status of the admin API to ensure it is functioning correctly.

```APIDOC
## GET /api/admin/v1/check

### Description
Check if admin API is working.

### Method
GET

### Endpoint
/api/admin/v1/check

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **description** (string) - Indicates a successful response.

#### Response Example
```json
{
  "message": "Admin API is working"
}
```
```

--------------------------------

### GET /api/admin/v1/permissions

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

Lists all system permissions, requiring superadmin privileges. Supports searching for specific permissions.

```APIDOC
## GET /api/admin/v1/permissions

### Description
List system permissions. Requires superadmin privileges.

### Method
GET

### Endpoint
/api/admin/v1/permissions

### Parameters
#### Path Parameters
None

#### Query Parameters
- **search** (string) - Optional - Search query

#### Request Body
None

### Request Example
```bash
curl -X GET "/api/admin/v1/permissions?search=admin"
```

### Response
#### Success Response (200)
- **users** (array) - A list of users with their permissions.
  - **id** (integer) - User ID
  - **username** (string) - Username
  - **display_name** (string) - User's display name (nullable)
  - **slack_username** (string) - User's Slack username (nullable)
  - **github_username** (string) - User's GitHub username (nullable)
  - **admin_level** (string) - User's current admin level
  - **email_addresses** (array) - List of user's email addresses
  - **created_at** (string) - Timestamp of user creation
  - **updated_at** (string) - Timestamp of last user update

#### Response Example
```json
{
  "users": [
    {
      "id": 1,
      "username": "admin_user",
      "display_name": "Admin User",
      "slack_username": "@admin",
      "github_username": "admin",
      "admin_level": "superadmin",
      "email_addresses": ["admin@example.com"],
      "created_at": "2023-01-01T10:00:00Z",
      "updated_at": "2023-01-01T10:00:00Z"
    }
  ]
}
```
```

--------------------------------

### GET /api/hackatime/v1/users/current/stats/last_7_days

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

Returns coding statistics for the last 7 days. Used by some WakaTime dashboards.

```APIDOC
## GET /api/hackatime/v1/users/current/stats/last_7_days

### Description
Returns coding statistics for the last 7 days. Used by some WakaTime dashboards.

### Method
GET

### Endpoint
/api/hackatime/v1/users/current/stats/last_7_days

### Response
#### Success Response (200)
- **data** (object) - Object containing coding statistics for the last 7 days.
  - **username** (string) - User's username.
  - **user_id** (string) - User's ID.
  - **start** (string, format: date-time) - Start timestamp of the range.
  - **end** (string, format: date-time) - End timestamp of the range.
  - **status** (string) - Status of the data retrieval.
  - **total_seconds** (number) - Total seconds coded in the last 7 days.
  - **daily_average** (number) - Average seconds coded per day.
  - **days_including_holidays** (integer) - Number of days in the range, including holidays.
  - **range** (string) - The date range (e.g., "7 days").
  - **human_readable_range** (string) - Human-readable representation of the date range.
  - **human_readable_total** (string) - Human-readable representation of total coding time.
  - **human_readable_daily_average** (string) - Human-readable representation of daily average coding time.
  - **is_coding_activity_visible** (boolean) - Whether coding activity is visible.
  - **is_other_usage_visible** (boolean) - Whether other usage is visible.
  - **editors** (array) - Array of objects, each representing coding time per editor.
    - **name** (string) - Name of the editor.
    - **total_seconds** (integer) - Total seconds coded using this editor.
    - **percent** (number) - Percentage of total coding time spent in this editor.
    - **digital** (string) - Digital representation of time spent.
    - **text** (string) - Human-readable representation of time spent.
    - **hours** (integer) - Hours spent coding in this editor.

#### Response Example
```json
{
  "data": {
    "username": "testuser",
    "user_id": "12345",
    "start": "2023-10-20T00:00:00Z",
    "end": "2023-10-27T00:00:00Z",
    "status": "ok",
    "total_seconds": 25200,
    "daily_average": 3600,
    "days_including_holidays": 7,
    "range": "7 days",
    "human_readable_range": "Last 7 days",
    "human_readable_total": "7 hrs",
    "human_readable_daily_average": "1 hr",
    "is_coding_activity_visible": true,
    "is_other_usage_visible": true,
    "editors": [
      {
        "name": "VS Code",
        "total_seconds": 18000,
        "percent": 71.4,
        "digital": "5:00",
        "text": "5 hrs",
        "hours": 5
      }
    ]
  }
}
```
```

--------------------------------

### GET /api/summary

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

Retrieves a WakaTime-compatible summary of coding activity. This endpoint allows filtering by date range, interval, project, and user (for administrators).

```APIDOC
## GET /api/summary

### 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).

### Method
GET

### Endpoint
/api/summary

### Parameters
#### Query Parameters
- **start** (string) - Optional - Start date (YYYY-MM-DD)
- **end** (string) - Optional - End date (YYYY-MM-DD)
- **interval** (string) - Optional - Interval (e.g. today, yesterday, week, month)
- **project** (string) - Optional - Project name
- **user** (string) - Optional - Slack UID of the user (for admin use)

### Response
#### Success Response (200)
- **user_id** (string) - User ID (nullable)
- **from** (string) - Start of the time range (date_time)
- **to** (string) - End of the time range (date_time)
- **projects** (array) - Array of project objects, each with:
  - **key** (string)
  - **total** (number)
- **languages** (array) - Array of language objects, each with:
  - **key** (string)
  - **total** (number)
- **editors** (object) - Editor statistics (nullable)
- **operating_systems** (object) - Operating system statistics (nullable)
- **machines** (object) - Machine statistics (nullable)
- **categories** (object) - Category statistics (nullable)
- **branches** (object) - Branch statistics (nullable)
- **entities** (object) - Entity statistics (nullable)
- **labels** (object) - Label statistics (nullable)

#### Response Example
{
  "user_id": "user123",
  "from": "2023-10-26T00:00:00Z",
  "to": "2023-10-27T00:00:00Z",
  "projects": [
    {
      "key": "hackathon-api",
      "total": 3600
    }
  ],
  "languages": [
    {
      "key": "Python",
      "total": 1800
    }
  ],
  "editors": {},
  "operating_systems": {},
  "machines": {},
  "categories": {},
  "branches": {},
  "entities": {},
  "labels": {}
}

#### Error Response (400)
- **description**: bad request
```

--------------------------------

### GET /api/v1/ysws_programs

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

List available YSWS (Your Ship We Ship) programs. This endpoint retrieves a list of all programs that can be claimed.

```APIDOC
## GET /api/v1/ysws_programs

### Description
List available YSWS (Your Ship We Ship) programs. This endpoint retrieves a list of all programs that can be claimed.

### Method
GET

### Endpoint
/api/v1/ysws_programs

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **items** (array of strings) - A list of available YSWS program names. Example: `["onboard"]`

#### Response Example
```json
[
  "onboard"
]
```
```

--------------------------------

### GET /my/projects

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

List Project Repo Mappings. Retrieve a list of mappings between local project names and their corresponding Git repositories. Supports filtering by date range and interval.

```APIDOC
## GET /my/projects

### Description
List mappings between local project names and Git repositories.

### Method
GET

### Endpoint
/my/projects

### Parameters
#### Query Parameters
- **interval** (string) - Optional - Time interval (e.g., daily, weekly). Default: daily
- **from** (string) - Optional - Start date (YYYY-MM-DD)
- **to** (string) - Optional - End date (YYYY-MM-DD)

### Response
#### Success Response (200)
- **description**: successful

#### Response Example
(No example provided for successful response)
```

--------------------------------

### GET /api/v1/leaderboard/daily

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

Retrieves the daily leaderboard. This endpoint provides insights into coding activity for the current day.

```APIDOC
## GET /api/v1/leaderboard/daily

### Description
Retrieves the daily leaderboard. This endpoint provides insights into coding activity for the current day.

### Method
GET

### Endpoint
/api/v1/leaderboard/daily

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **period** (string) - The period of the leaderboard (e.g., "daily").
- **start_date** (string) - The start date of the leaderboard period (YYYY-MM-DD).
- **date_range** (string) - A human-readable date range (e.g., "Wed, Mar 20, 2024").
- **generated_at** (string) - The timestamp when the leaderboard was generated (ISO 8601 format).
- **entries** (array) - An array of leaderboard entries.

#### Response Example
```json
{
  "period": "daily",
  "start_date": "2024-03-20",
  "date_range": "Wed, Mar 20, 2024",
  "generated_at": "2024-03-20T10:00:00Z",
  "entries": [
    {
      "user_id": "user123",
      "username": "hacker_one",
      "total_seconds": 3600
    }
  ]
}
```

#### Error Response (503)
- **Error**: A standard error object if the service is unavailable.

```

--------------------------------

### GET /api/v1/users/{username}/project/{project_name}

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

Retrieves detailed statistics for a specific project a user has worked on.

```APIDOC
## GET /api/v1/users/{username}/project/{project_name}

### Description
Get detailed stats for a specific project.

### Method
GET

### Endpoint
/api/v1/users/{username}/project/{project_name}

### Parameters
#### Path Parameters
- **username** (string) - Required - Username
- **project_name** (string) - Required - Project Name

#### Query Parameters
- **start** (string) - Optional - Stats start time (ISO 8601)

### Response
#### Success Response (200)
- The response structure for this endpoint is not fully detailed in the provided text, but it is expected to contain project-specific statistics.

#### Response Example
(Example response structure would be provided here if available)

#### Error Response (404)
- **Error** - Details about the error, indicating the user or project was not found.

#### Error Example
```json
{
  "error": "User or project not found"
}
```
```

--------------------------------

### GET /api/admin/v1/deletion_requests

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

Lists pending deletion requests.

```APIDOC
## GET /api/admin/v1/deletion_requests

### Description
List pending deletion requests.

### Method
GET

### Endpoint
/api/admin/v1/deletion_requests

### Parameters
No parameters are documented for this endpoint.

### Response
#### Success Response (200)
- The response schema for this endpoint is not fully detailed in the provided text, but it is expected to return a JSON object containing information about pending deletion requests.

#### Response Example
(Example response structure not provided in the input text)
```

--------------------------------

### GET /api/v1/authenticated/me

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

Retrieves detailed information about the currently authenticated user.

```APIDOC
## GET /api/v1/authenticated/me

### Description
Returns detailed information about the currently authenticated user.

### Method
GET

### Endpoint
/api/v1/authenticated/me

### Response
#### Success Response (200)
- **id** (integer) - User's unique identifier
- **emails** (array) - Array of user's email addresses
- **slack_id** (string) - User's Slack ID (nullable)
- **github_username** (string) - User's GitHub username (nullable)
- **trust_factor** (object) - User's trust factor, containing:
  - **trust_level** (string)
  - **trust_value** (integer)

#### Response Example
{
  "id": 1,
  "emails": ["user@example.com"],
  "slack_id": "U12345",
  "github_username": "hackerman",
  "trust_factor": {
    "trust_level": "high",
    "trust_value": 100
  }
}

#### Error Response (401)
- **description**: unauthorized
```

--------------------------------

### GET /api/v1/leaderboard/weekly

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

Retrieves the weekly leaderboard, showing coding time over the last 7 days. Requires STATS_API_KEY.

```APIDOC
## GET /api/v1/leaderboard/weekly

### Description
Retrieves the weekly leaderboard, showing coding time over the last 7 days. Requires STATS_API_KEY.

### Method
GET

### Endpoint
/api/v1/leaderboard/weekly

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **period** (string) - The period of the leaderboard (e.g., "last_7_days").
- **start_date** (string) - The start date of the leaderboard period (YYYY-MM-DD).
- **date_range** (string) - A human-readable date range (e.g., "Mar 13 - Mar 20, 2024").
- **generated_at** (string) - The timestamp when the leaderboard was generated (ISO 8601 format).
- **entries** (array) - An array of leaderboard entries.

#### Response Example
```json
{
  "period": "last_7_days",
  "start_date": "2024-03-13",
  "date_range": "Mar 13 - Mar 20, 2024",
  "generated_at": "2024-03-20T10:00:00Z",
  "entries": [
    {
      "user_id": "user123",
      "username": "hacker_one",
      "total_seconds": 25200
    }
  ]
}
```

#### Error Response (503)
- **Error**: A standard error object if the service is unavailable.

```

--------------------------------

### GET /api/v1/users/{username}/projects

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

Retrieves a list of projects a user has recently coded on, typically within the last 30 days.

```APIDOC
## GET /api/v1/users/{username}/projects

### Description
Get a list of projects a user has coded on recently (last 30 days).

### Method
GET

### Endpoint
/api/v1/users/{username}/projects

### Parameters
#### Path Parameters
- **username** (string) - Required - Username

### Response
#### Success Response (200)
- **projects** (array) - An array of project names the user has worked on.
  - (string) - Example: 'hackatime'

#### Response Example
```json
{
  "projects": [
    "hackatime",
    "another-project"
  ]
}
```

#### Error Response (404)
- **Error** - Details about the error, indicating the user was not found.

#### Error Example
```json
{
  "error": "User not found"
}
```
```

--------------------------------

### GET /api/admin/v1/user/info

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

Retrieves detailed information about a specific user. Requires superadmin or admin privileges.

```APIDOC
## GET /api/admin/v1/user/info

### Description
Get detailed info about a user. Requires superadmin/admin privileges.

### Method
GET

### Endpoint
/api/admin/v1/user/info

### Parameters
#### Query Parameters
- **user_id** (string) - Required - User ID

### Response
#### Success Response (200)
- **user** (object) - An object containing the user's details.
  - **id** (integer) - The user's ID.
  - **username** (string) - The user's username.
  - **display_name** (string) - The user's display name.
  - **slack_uid** (string, nullable) - The user's Slack UID.
  - **slack_username** (string, nullable) - The user's Slack username.
  - **github_username** (string, nullable) - The user's GitHub username.
  - **timezone** (string, nullable) - The user's timezone.
  - **country_code** (string, nullable) - The user's country code.
  - **trust_level** (string) - The user's trust level.
  - **avatar_url** (string, nullable) - The URL of the user's avatar.
  - **slack_avatar_url** (string, nullable) - The URL of the user's Slack avatar.
  - **github_avatar_url** (string, nullable) - The URL of the user's GitHub avatar.

#### Response Example
```json
{
  "user": {
    "id": 1,
    "username": "johndoe",
    "display_name": "John Doe",
    "slack_uid": "U12345",
    "slack_username": "john.doe",
    "github_username": "johndoe",
    "timezone": "UTC",
    "country_code": "US",
    "trust_level": "high",
    "avatar_url": "https://example.com/avatar.jpg",
    "slack_avatar_url": "https://example.com/slack_avatar.jpg",
    "github_avatar_url": "https://example.com/github_avatar.jpg"
  }
}
```
```

--------------------------------

### GET /api/v1/authenticated/heartbeats/latest

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

Fetches the absolutely latest heartbeat processed for the authenticated user.

```APIDOC
## GET /api/v1/authenticated/heartbeats/latest

### Description
Returns the absolutely latest heartbeat processed for the user.

### Method
GET

### Endpoint
/api/v1/authenticated/heartbeats/latest

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
(Response schema not fully provided in the input, but typically includes heartbeat details like timestamp, project, language, etc.)

#### Response Example
(Example response structure would depend on the full schema, but might look like this)
```json
{
  "time": "2024-03-15T10:05:00Z",
  "project": "hackatime",
  "language": "Python"
}
```
```

--------------------------------

### GET /api/v1/users/{username}/projects/details

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

Retrieves a detailed breakdown of all projects associated with a specific user. This endpoint allows filtering by project name, and time ranges for discovery and statistics calculation.

```APIDOC
## GET /api/v1/users/{username}/projects/details

### Description
Get detailed breakdown of all user projects. This endpoint allows filtering by project name, and time ranges for discovery and statistics calculation.

### Method
GET

### Endpoint
/api/v1/users/{username}/projects/details

### Parameters
#### Path Parameters
- **username** (string) - Required - Username

#### Query Parameters
- **projects** (string) - Optional - Comma-separated list of projects to filter
- **since** (string) - Optional - Start time (ISO 8601) for project discovery
- **until** (string) - Optional - End time (ISO 8601) for project discovery
- **until_date** (string) - Optional - End time (ISO 8601) for project discovery
- **start** (string) - Optional - Stats start time (ISO 8601)
- **end** (string) - Optional - Stats end time (ISO 8601)
- **start_date** (string) - Optional - Start date (ISO 8601) for stats calculation
- **end_date** (string) - Optional - End date (ISO 8601) for stats calculation

### Response
#### Success Response (200)
- **projects** (array) - An array of project objects, each containing:
  - **name** (string) - The name of the project.
  - **total_seconds** (number) - The total time spent on the project in seconds.
  - **languages** (array) - A list of programming languages used in the project.
  - **repo_url** (string, nullable) - The URL of the project repository.
  - **total_heartbeats** (integer) - The total number of heartbeats recorded for the project.
  - **first_heartbeat** (string, format: date_time, nullable) - The timestamp of the first heartbeat.
  - **last_heartbeat** (string, format: date_time, nullable) - The timestamp of the last heartbeat.

#### Response Example
```json
{
  "projects": [
    {
      "name": "example-project",
      "total_seconds": 3600,
      "languages": ["Python", "JavaScript"],
      "repo_url": "https://github.com/user/example-project",
      "total_heartbeats": 120,
      "first_heartbeat": "2023-10-26T10:00:00Z",
      "last_heartbeat": "2023-10-26T11:00:00Z"
    }
  ]
}
```
```

--------------------------------

### GET /api/admin/v1/user/get_users_by_ip

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

Finds users associated with a given IP address. Returns a list of users, their IP addresses, and machine information.

```APIDOC
## GET /api/admin/v1/user/get_users_by_ip

### Description
Find users associated with an IP address. This endpoint is useful for identifying all users who have accessed the system from a particular IP.

### Method
GET

### Endpoint
/api/admin/v1/user/get_users_by_ip

### Parameters
#### Query Parameters
- **ip** (string) - Required - IP Address

### Response
#### Success Response (200)
- **users** (array) - A list of users associated with the IP address.
  - **user_id** (integer) - The ID of the user.
  - **ip_address** (string) - The IP address associated with the user.
  - **machine** (string) - The machine ID associated with the user (nullable).
  - **user_agent** (string) - The user agent string for the user's request (nullable).
```

--------------------------------

### GET /api/admin/v1/user/get_users_by_machine

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

Retrieves users associated with a specific machine ID. Returns a list of users and their corresponding machine IDs.

```APIDOC
## GET /api/admin/v1/user/get_users_by_machine

### Description
Find users associated with a machine ID. This endpoint helps in identifying all users logged in or associated with a particular machine.

### Method
GET

### Endpoint
/api/admin/v1/user/get_users_by_machine

### Parameters
#### Query Parameters
- **machine** (string) - Required - Machine ID

### Response
#### Success Response (200)
- **users** (array) - A list of users associated with the machine ID.
  - **user_id** (integer) - The ID of the user.
  - **machine** (string) - The machine ID associated with the user.
```

--------------------------------

### GET /api/hackatime/v1/users/{id}/statusbar/today

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

Returns the total coding time for today. Used by editor plugins to display the status bar widget.

```APIDOC
## GET /api/hackatime/v1/users/{id}/statusbar/today

### Description
Returns the total coding time for today. Used by editor plugins to display the status bar widget.

### Method
GET

### Endpoint
/api/hackatime/v1/users/{id}/statusbar/today

### Parameters
#### Path Parameters
- **id** (string) - Required - User ID or "current"

### Response
#### Success Response (200)
- **data** (object) - Object containing today's coding statistics.
  - **grand_total** (object) - Object containing grand total coding time.
    - **total_seconds** (number) - Total seconds coded today.
    - **text** (string) - Human-readable representation of total time (e.g., "2 hrs").

#### Response Example
```json
{
  "data": {
    "grand_total": {
      "total_seconds": 7200.0,
      "text": "2 hrs"
    }
  }
}
```
```

--------------------------------

### GET /api/v1/authenticated/api_keys

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

Retrieves the API keys associated with the authenticated user. This endpoint returns sensitive information and should be used with caution.

```APIDOC
## GET /api/v1/authenticated/api_keys

### Description
Returns the API keys for the authenticated user. Warning: This returns sensitive information.

### Method
GET

### Endpoint
/api/v1/authenticated/api_keys

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **token** (string) - The API key token.

#### Response Example
```json
{
  "token": "waka_..."
}
```
```

--------------------------------

### GET /api/v1/authenticated/projects

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

Fetches a list of projects associated with the authenticated user, with options to filter by archived status, specific project names, and time ranges.

```APIDOC
## GET /api/v1/authenticated/projects

### Description
Returns a list of projects associated with the authenticated user.

### Method
GET

### Endpoint
/api/v1/authenticated/projects

### Parameters
#### Query Parameters
- **include_archived** (boolean) - Optional - Include archived projects (true/false)
- **projects** (string) - Optional - Comma-separated list of project names
- **since** (string) - Optional - Project discovery start time (ISO 8601)
- **until** (string) - Optional - Project discovery end time (ISO 8601)
- **until_date** (string) - Optional - Alias for until
- **start** (string) - Optional - Stats start time (ISO 8601)
- **end** (string) - Optional - Stats end time (ISO 8601)
- **start_date** (string) - Optional - Alias for start
- **end_date** (string) - Optional - Alias for end

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **projects** (array) - A list of project objects.
  - **name** (string) - The name of the project.
  - **total_seconds** (number) - Total seconds coded for the project.
  - **most_recent_heartbeat** (string) - The timestamp of the most recent heartbeat (nullable).
  - **languages** (array) - A list of programming languages used in the project.
  - **archived** (boolean) - Whether the project is archived.

#### Response Example
```json
{
  "projects": [
    {
      "name": "hackatime",
      "total_seconds": 3600.0,
      "most_recent_heartbeat": "2024-03-15T10:00:00Z",
      "languages": ["Python", "JavaScript"],
      "archived": false
    }
  ]
}
```
```

--------------------------------

### GET /api/admin/v1/user/projects

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

Retrieves a list of projects associated with a specific user, including project details and aggregated statistics. This endpoint is intended for administrative use.

```APIDOC
## GET /api/admin/v1/user/projects

### Description
Retrieves a list of projects for a user, providing an administrative view of their contributions and activity.

### Method
GET

### Endpoint
/api/admin/v1/user/projects

### Parameters
#### Query Parameters
- **user_id** (string) - Required - The unique identifier of the user whose projects are to be retrieved.

### Response
#### Success Response (200)
- **user_id** (integer) - The ID of the user.
- **username** (string) - The username of the user.
- **total_projects** (integer) - The total number of projects associated with the user.
- **projects** (array) - A list of project objects, each containing:
  - **name** (string) - The name of the project.
  - **total_heartbeats** (integer) - The total number of heartbeats recorded for the project.
  - **total_duration** (number) - The total duration of activity in the project.
  - **first_heartbeat** (number) - Timestamp of the first heartbeat.
  - **last_heartbeat** (number) - Timestamp of the last heartbeat.
  - **languages** (array of strings) - A list of programming languages used in the project.
  - **repo** (string) - The repository URL of the project.
  - **repo_mapping_id** (integer) - The ID mapping for the repository.
  - **archived** (boolean) - Indicates if the project is archived.

#### Error Response (404)
- **description** (string) - 'user not found'

### Response Example
```json
{
  "user_id": 123,
  "username": "example_user",
  "total_projects": 5,
  "projects": [
    {
      "name": "Project Alpha",
      "total_heartbeats": 1500,
      "total_duration": 7200.5,
      "first_heartbeat": 1678886400,
      "last_heartbeat": 1678972800,
      "languages": ["Python", "JavaScript"],
      "repo": "https://github.com/user/project-alpha",
      "repo_mapping_id": 101,
      "archived": false
    }
  ]
}
```
```

--------------------------------

### GET /api/v1/users/lookup_email/{email}

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

Lookup a user by their email address. This endpoint is useful for integrations that need to map email addresses to Hackatime user IDs. It requires an API key for authentication.

```APIDOC
## GET /api/v1/users/lookup_email/{email}

### Description
Find a user ID by their email address. Useful for integrations that need to map emails to Hackatime users. Requires STATS_API_KEY.

### Method
GET

### Endpoint
/api/v1/users/lookup_email/{email}

### Parameters
#### Path Parameters
- **email** (string) - Required - Email address to lookup

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **user_id** (integer) - The unique identifier for the user.
- **email** (string) - The email address of the user.

#### Response Example
```json
{
  "user_id": 42,
  "email": "test@example.com"
}
```

#### Error Response (404)
- **error** (string) - Error message indicating the user was not found.
- **email** (string) - The email address that was not found.

#### Response Example
```json
{
  "error": "User not found",
  "email": "unknown@example.com"
}
```
```

--------------------------------

### GET /api/v1/stats

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

Retrieves statistics related to user activity, operating systems, and machines. This endpoint provides aggregated data on usage patterns.

```APIDOC
## GET /api/v1/stats

### Description
Retrieves statistics related to user activity, operating systems, and machines. This endpoint provides aggregated data on usage patterns.

### Method
GET

### Endpoint
/api/v1/stats

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **key** (string) - The name or identifier of the statistic (e.g., 'VS Code', 'Mac', 'MacBook-Pro').
- **total** (number) - The aggregated count or value associated with the key.
- **operating_systems** (array) - An array of objects, where each object represents statistics for an operating system.
  - **key** (string) - The name of the operating system.
  - **total** (number) - The total usage for that operating system.
- **machines** (array) - An array of objects, where each object represents statistics for a specific machine type.
  - **key** (string) - The name of the machine type.
  - **total** (number) - The total usage for that machine type.

#### Response Example
```json
{
  "key": "VS Code",
  "total": 3600.0,
  "operating_systems": [
    {
      "key": "Mac",
      "total": 3600.0
    }
  ],
  "machines": [
    {
      "key": "MacBook-Pro",
      "total": 3600.0
    }
  ]
}
```
```

--------------------------------

### GET /api/v1/stats

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

Get total coding time (Admin Only). Retrieves the total coding time across all users. This endpoint requires administrator privileges and can be filtered by username, start date, and end date.

```APIDOC
## GET /api/v1/stats

### Description
Returns the total coding time for all users, optionally filtered by user or date range. Requires admin privileges via STATS_API_KEY.

### Method
GET

### Endpoint
/api/v1/stats

### Parameters
#### Query Parameters
- **start_date** (string) - Optional - Start date (YYYY-MM-DD), defaults to 10 years ago
- **end_date** (string) - Optional - End date (YYYY-MM-DD), defaults to today
- **username** (string) - Optional - Filter by username

### Response
#### Success Response (200)
- **description**: successful

#### Response Example
(No example provided for successful response)
```

--------------------------------

### POST /my/settings/rotate_api_key

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

Rotate API Key. Generate a new API key for your account. The old token will become invalid immediately upon successful rotation.

```APIDOC
## POST /my/settings/rotate_api_key

### Description
Rotate your API key. Returns the new token. Warning: Old token will stop working immediately.

### Method
POST

### Endpoint
/my/settings/rotate_api_key

### Response
#### Success Response (200)
- **description**: successful

#### Response Example
(No example provided for successful response)
```

--------------------------------

### My Settings

Source: https://hackatime.hackclub.com/api-docs/v1/api-docs/index

Endpoints for managing user settings, including rotating API keys, migrating heartbeats, and managing deletion requests.

```APIDOC
## My Settings

### Description
Endpoints for managing user settings, including rotating API keys, migrating heartbeats, and managing deletion requests.

### Rotate API Key

*   **Method**: POST
*   **Endpoint**: `/my/settings/rotate_api_key`

### Migrate Heartbeats

*   **Method**: POST
*   **Endpoint**: `/my/settings/migrate_heartbeats`

### Create Deletion Request

*   **Method**: POST
*   **Endpoint**: `/deletion`

### Cancel Deletion Request

*   **Method**: DELETE
*   **Endpoint**: `/deletion`
```

--------------------------------

### My Projects

Source: https://hackatime.hackclub.com/api-docs/v1/api-docs/index

Endpoints for managing project repository mappings, including listing, updating, archiving, and unarchiving.

```APIDOC
## My Projects

### Description
Endpoints for managing project repository mappings, including listing, updating, archiving, and unarchiving.

### List Project Repo Mappings

*   **Method**: GET
*   **Endpoint**: `/my/projects`

### Update Project Repo Mapping

*   **Method**: PATCH
*   **Endpoint**: `/my/project_repo_mappings/{project_name}`
*   **Path Parameters**:
    *   `project_name` (string) - Required - The name of the project mapping to update.

### Archive Project Mapping

*   **Method**: PATCH
*   **Endpoint**: `/my/project_repo_mappings/{project_name}/archive`
*   **Path Parameters**:
    *   `project_name` (string) - Required - The name of the project mapping to archive.

### Unarchive Project Mapping

*   **Method**: PATCH
*   **Endpoint**: `/my/project_repo_mappings/{project_name}/unarchive`
*   **Path Parameters**:
    *   `project_name` (string) - Required - The name of the project mapping to unarchive.
```

--------------------------------

### GET /api/admin/v1/timeline/leaderboard_users

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

Retrieves users for the timeline leaderboard based on recent activity.

```APIDOC
## GET /api/admin/v1/timeline/leaderboard_users

### Description
Get users who should appear on the timeline leaderboard based on recent activity.

### Method
GET

### Endpoint
/api/admin/v1/timeline/leaderboard_users

### Parameters
#### Query Parameters
- **period** (string) - Required - Leaderboard period. Enum: ["daily", "last_7_days"]

### Response
#### Success Response (200)
- **users** (array) - An array of user objects.
  - **id** (integer) - The user's ID.
  - **display_name** (string, nullable) - The user's display name.
  - **avatar_url** (string, nullable) - The URL of the user's avatar.

#### Response Example
```json
{
  "users": [
    {
      "id": 1,
      "display_name": "Jane Smith",
      "avatar_url": "https://example.com/avatar.jpg"
    }
  ]
}
```
```

--------------------------------

### GET /api/admin/v1/deletion_requests/{id}

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

Retrieves the details of a specific user deletion request.

```APIDOC
## GET /api/admin/v1/deletion_requests/{id}

### Description
Show details of a deletion request.

### Method
GET

### Endpoint
/api/admin/v1/deletion_requests/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the deletion request.

### Response
#### Success Response (200)
- **DeletionRequest** (object) - The details of the deletion request.

#### Response Example
```json
{
  "id": 123,
  "user_id": 456,
  "user": {
    "id": 456,
    "username": "testuser",
    "display_name": "Test User"
  },
  "status": "pending",
  "requested_at": "2023-10-27T10:00:00Z",
  "scheduled_deletion_at": "2023-11-27T10:00:00Z",
  "completed_at": null,
  "admin_approved_by": null,
  "created_at": "2023-10-27T10:00:00Z",
  "updated_at": "2023-10-27T10:00:00Z"
}
```
```

--------------------------------

### POST /my/settings/migrate_heartbeats

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

Migrate Heartbeats. Initiate a process to migrate heartbeats from legacy formats or external systems into the current platform.

```APIDOC
## POST /my/settings/migrate_heartbeats

### Description
Trigger a migration of heartbeats from legacy formats or systems.

### Method
POST

### Endpoint
/my/settings/migrate_heartbeats

### Response
#### Success Response (302)
- **description**: redirect

#### Response Example
(No example provided for redirect response)
```

--------------------------------

### Slack Integrations

Source: https://hackatime.hackclub.com/api-docs/v1/api-docs/index

Endpoints for handling Slack commands for various services.

```APIDOC
## Slack Integrations

### Description
Endpoints for handling Slack commands for various services.

### Handle Sailor's Log Command

*   **Method**: POST
*   **Endpoint**: `/sailors_log/slack/commands`

### Handle Timedump Command

*   **Method**: POST
*   **Endpoint**: `/timedump/slack/commands`
```

--------------------------------

### GET /api/admin/v1/banned_users

Source: https://hackatime.hackclub.com/api-docs/v1/swagger

Retrieves a list of users who have been banned from the platform. Supports pagination.

```APIDOC
## GET /api/admin/v1/banned_users

### Description
Get a list of banned users.

### Method
GET

### Endpoint
/api/admin/v1/banned_users

### Parameters
#### Path Parameters
None

#### Query Parameters
- **limit** (integer) - Optional - Max results to return (default: 200, max: 1000)
- **offset** (integer) - Optional - Number of results to skip for pagination (default: 0)

#### Request Body
None

### Request Example
```bash
curl -X GET "/api/admin/v1/banned_users?limit=50&offset=100"
```

### Response
#### Success Response (200)
- **banned_users** (array) - A list of banned users.
  - **id** (integer) - User ID
  - **username** (string) - Username
  - **email** (string) - Primary email or "no email"

#### Response Example
```json
{
  "banned_users": [
    {
      "id": 123,
      "username": "john_doe",
      "email": "john.doe@example.com"
    }
  ]
}
```
```
Tokens:
Raw