ReqToggl

A Req plugin for the Toggl Track API v9. Provides a simple, composable interface for time tracking operations including authentication, project management, and time entry creation.

Installation

Add req_toggl to your list of dependencies in mix.exs:

def deps do
  [
    {:req_toggl, "~> 0.1.0"}
  ]
end

Quick Start

# Create a client with your API token
client = ReqToggl.new(api_token: System.fetch_env!("TOGGL_API_TOKEN"))

# Get your workspace ID
{:ok, %{body: user}} = ReqToggl.get_me(client)
workspace_id = user["default_workspace_id"]

# List all projects
{:ok, %{body: projects}} = ReqToggl.list_projects(client, workspace_id)

# Create a time entry
{:ok, %{body: entry}} = ReqToggl.create_time_entry(client,
  workspace_id: workspace_id,
  project_id: 12345,
  date: "2024-01-15",
  start_time: "09:00",
  end_time: "17:00",
  description: "Working on features"
)

Authentication

Get your API token from https://track.toggl.com/profile.

You can pass it directly or use environment variables:

# From environment
client = ReqToggl.new(api_token: System.fetch_env!("TOGGL_API_TOKEN"))

# Or attach to an existing Req request
req = Req.new(base_url: "https://api.track.toggl.com/api/v9")
|> ReqToggl.attach(api_token: "your-api-token")

API Functions

Get User Info

{:ok, %{body: user}} = ReqToggl.get_me(client)
workspace_id = user["default_workspace_id"]

List Projects

# List all projects
{:ok, %{body: projects}} = ReqToggl.list_projects(client, workspace_id)

# Filter by name
{:ok, %{body: projects}} = ReqToggl.list_projects(client, workspace_id, name: "Marketing")

Create Time Entries

ReqToggl supports multiple time formats for flexibility:

Using date and time strings (simplest)

{:ok, %{body: entry}} = ReqToggl.create_time_entry(client,
  workspace_id: workspace_id,
  project_id: 12345,
  date: "2024-01-15",
  start_time: "09:00",
  end_time: "17:00",
  description: "Working on features"
)

Using DateTime structs

{:ok, %{body: entry}} = ReqToggl.create_time_entry(client,
  workspace_id: workspace_id,
  project_id: 12345,
  start: ~U[2024-01-15 09:00:00Z],
  stop: ~U[2024-01-15 17:00:00Z],
  description: "Working on features"
)

Using duration (in seconds)

{:ok, %{body: entry}} = ReqToggl.create_time_entry(client,
  workspace_id: workspace_id,
  project_id: 12345,
  start: ~U[2024-01-15 09:00:00Z],
  duration: 28800,  # 8 hours
  description: "Working on features"
)

Optional Fields

Time entries support additional optional fields:

{:ok, %{body: entry}} = ReqToggl.create_time_entry(client,
  workspace_id: workspace_id,
  project_id: 12345,
  date: "2024-01-15",
  start_time: "09:00",
  end_time: "17:00",
  description: "Working on features",
  billable: true,
  tags: ["development", "feature"]
)

Development

Setup

# Install dependencies
mix deps.get

# Compile
mix compile

# Run tests
mix test

Live Development with Tidewave

Start an interactive session with live reloading:

./tidewave.sh

This starts IEx with Tidewave on port 10002 for live code evaluation.

Toggl API Details

• API Version: v9
• Base URL: https://api.track.toggl.com/api/v9
• Format: JSON only
• Rate Limits: 1 request/second, varying hourly limits by plan
• Time Format: ISO 8601 (RFC 3339) in UTC

Documentation: https://engineering.toggl.com/docs/

License

Copyright 2025

Licensed under the Apache License, Version 2.0.