This post is about how to use the Clockify API to start a timer for a specific project. Clockify is a time-tracking and project management tool that allows users to track the time spent on different tasks and projects. This is useful for freelancers, remote teams, and businesses that bill their clients by the hour.

import requests
import datetime
import random
import os

clockify_api_key = os.environ["clockify_api_key"]
clockify_workspace_id = os.environ["clockify_workspace_id"]
clockify_project_id = os.environ["clockify_project_id"]



def start_clockify_timer(project_id: str, description: str) -> dict:
  # Get the current time
  start_time = datetime.datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%SZ")
  end_time = (datetime.datetime.utcnow() + datetime.timedelta(hours=12)).strftime("%Y-%m-%dT%H:%M:%SZ")

  # Define the headers and payload for the API request
  headers = {
    "X-Api-Key": clockify_api_key,
    "Content-Type": "application/json",
  }
  payload = {
    "start": start_time,
    "end": end_time,
    "billable": True,
    "description": description,
    "projectId": project_id,
  }

  # Define the URL and make the API request
  url = f"https://api.clockify.me/api/v1/workspaces/{clockify_workspace_id}/time-entries"
  response = requests.post(url, headers=headers, json=payload)
  if response.status_code != 201:
    raise Exception(f"Failed to start timer: {response.text}")

  # Return the response as a JSON object
  return response.json()

The first step is to import the necessary libraries: requests, datetime, and os. The requests library is used to make the API call to Clockify, datetime is used to get the current time, and os is used to get the Clockify API key and workspace ID from the environment variables.

The start_clockify_timer function takes two arguments: project_id and description. The project_id argument is the ID of the project for which the timer is to be started, and the description argument is a string that describes the task being worked on.

The function starts by getting the current time, then defines the timer's start and end time. The end time is set to 12 hours after the start time. This is just an example, you can set it to any duration you want.

The headers and payload for the API request are then defined. The headers include the Clockify API key and the content type, while the payload includes the start and end time of the timer, whether the timer is billable, the description of the task, and the project ID.

The API endpoint URL is then defined, and the API request is made using the requests.post method. If the response status code is not 201, the function raises an exception with the response text. If the request is successful, the function returns the response as a JSON object.

In order to use this function, you need to set the clockify_api_key, clockify_workspace_id and clockify_project_id as environment variables.

With this function, you can easily start a timer for any project in Clockify using the API. This can be a very useful tool for automating time tracking and for creating a more accurate record of time spent on different projects.