TimeTracker - Smart Time Tracking & Analytics

API in Development

This API is currently under active development. Features and endpoints may change. We recommend testing thoroughly before production use.

1. Automation & Scripts

✨ No Login Required

This API endpoint is special: it does not need a session token. You only need your userId to authenticate. This makes it perfect for Siri Shortcuts, shell scripts, and background tasks where logging in is difficult.

⚠️ Note: Sessions shorter than 5 minutes are automatically discarded.

Use this endpoint to control the time tracker programmatically. It supports simple "start" and "stop" commands.

POST/api/automation

Request Parameters

userId (required): Your unique User ID (found in profile)
action (required): "start" or "stop"
location (required for "start"): "home" or "office"

Example: Start Tracking

curl -X POST https://timetracker.adatepe.dev/api/automation \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "YOUR_USER_ID_HERE",
    "action": "start",
    "location": "home"
  }'

Example: Stop Tracking

curl -X POST https://timetracker.adatepe.dev/api/automation \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "YOUR_USER_ID_HERE",
    "action": "stop"
  }'

📱 iOS Shortcuts Integration

You can trigger this API directly from your iPhone using the Shortcuts app. This is great for creating home screen icons or using with Siri.

⚙️ Step-by-Step Setup

1
Open Shortcuts app and create a new shortcut ("+")
2
Add action: Get Contents of URL
3
Set URL to:
https://timetracker.adatepe.dev/api/automation
4
Tap the arrow to expand options:
Method: POST
Headers: Key: Content-Type, Value: application/json
Request Body: JSON
5
Add new fields under Request Body:
userIdText (Your ID)
actionText ("start" or "stop")
locationText ("home" or "office")

💡

Pro Tip: Create two separate shortcuts: one for "Start Work" and one for "Stop Work". Add them to your Home Screen for one-tap time tracking!

2. Getting Started

What is the TimeTracker API?

The TimeTracker API allows you to programmatically track your work hours, retrieve statistics, and analyze your productivity patterns. Whether you're building a mobile app, setting up NFC tags, or integrating with other tools, this API makes it simple.

Base URL

https://timetracker.adatepe.dev/api

Requirements

A TimeTracker account (sign up for free)
Your Supabase authentication credentials
Basic understanding of HTTP requests (or follow this guide!)

3. Authentication Setup

All API requests require authentication using Supabase Auth. Here's how to get your access token:

Step 1: Get Your Access Token & User ID

After logging into TimeTracker, you can retrieve your access token using the browser console. You can also find your User ID by clicking on your email in the top navigation bar.

JavaScript

// Open browser console (F12) while logged in to TimeTracker
const session = await supabase.auth.getSession();
console.log(session.data.session.access_token);

// Copy the token - you'll need it for API requests

Important: Keep your access token secure! Don't share it publicly or commit it to version control.

Token Expiration: Access tokens expire after 1 hour. For automated scripts or NFC tags, you'll need to implement token refresh or use service role keys.

Step 2: Include Token in Requests

Add your access token to the Authorization header of every API request:

Authorization: Bearer YOUR_ACCESS_TOKEN_HERE

Handling Token Expiration

Access tokens expire after 1 hour. Here's how to refresh them:

JavaScript - Token Refresh

// Check if token is expired and refresh
const { data: { session }, error } = await supabase.auth.getSession();

if (error || !session) {
  // Session expired, refresh it
  const { data: { session: newSession }, error: refreshError } = 
    await supabase.auth.refreshSession();
  
  if (refreshError) {
    console.error('Failed to refresh token:', refreshError);
    // Redirect to login
  } else {
    // Use newSession.access_token for API calls
    console.log('Token refreshed:', newSession.access_token);
  }
} else {
  // Use existing session.access_token
  console.log('Token still valid:', session.access_token);
}

For NFC Tags & Automation

Since NFC tags can't refresh tokens automatically, you have two options:

Option 1: Use a Middleware/Webhook

Instead of calling the API directly, your NFC tag calls a personal webhook/middleware service that handles authentication and token refresh for you.

Option 2: Refresh Token Before Each Call

Store your refresh token securely and use it to get a new access token before each API call. This adds complexity to your Shortcut/automation.

Option 3: Service Role Key (Advanced)

Use Supabase Service Role Key for server-side automations. Warning: This bypasses Row Level Security - only use in secure environments!

Authorization: Bearer YOUR_SUPABASE_SERVICE_ROLE_KEY

4. Your First API Request

Let's start by creating your first time entry. We'll log a work session from today.

Example: Clock In for Today

This request creates a time entry with a start time. You can update it later with an end time.

cURL

curl -X POST https://timetracker.adatepe.dev/api/time-entries \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2025-01-15",
    "start_time": "09:00",
    "location": "office",
    "user_id": "YOUR_USER_ID" // Optional: Validated against your token
  }'

JavaScript (Fetch)

const response = await fetch('https://timetracker.adatepe.dev/api/time-entries', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    date: '2025-01-15',
    start_time: '09:00',
    location: 'office'
  })
});

const data = await response.json();
console.log('Entry created:', data);

Response

If successful, you'll receive a 201 status code with your time entry data:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "your-user-id",
  "date": "2025-01-15",
  "start_time": "09:00",
  "end_time": null,
  "location": "office",
  "duration_minutes": null,
  "created_at": "2025-01-15T09:00:00Z",
  "updated_at": "2025-01-15T09:00:00Z"
}

Clock Out (Update Entry)

To add an end time, make another POST request with the same date:

const response = await fetch('https://timetracker.adatepe.dev/api/time-entries', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    date: '2025-01-15',
    start_time: '09:00',
    end_time: '17:30',  // Added end time
    location: 'office'
  })
});

5. Using NFC Tags for Quick Clock In/Out

NFC tags allow you to clock in/out by simply tapping your phone to a tag at your desk or office entrance. Here's a complete guide to setting this up.

What You'll Need

NFC-enabled smartphone (most modern phones have this)
Programmable NFC tags (NTAG213/215/216 recommended)
NFC tag writing app (e.g., NFC Tools for iOS/Android)

Step-by-Step Setup

Step 1: Create a Shortcut/Task

First, we need to create an automation that makes the API call. We'll use iOS Shortcuts as an example:

1. Open the Shortcuts app on your iPhone

2. Tap the "+" button to create a new shortcut

3. Add "Get Contents of URL" action

4. Configure the action:

URL: https://timetracker.adatepe.dev/api/time-entries
Method: POST
Headers:
  Authorization: Bearer YOUR_ACCESS_TOKEN
  Content-Type: application/json
Request Body:
{
  "date": "CURRENT_DATE",
  "start_time": "CURRENT_TIME",
  "location": "office"
}

Step 2: Get Current Date/Time Dynamically

To automatically use today's date and current time:

1. Add "Get Current Date" action

2. Add "Format Date" action with format "yyyy-MM-dd" (for date field)

3. Add another "Format Date" action with format "HH:mm" (for time field)

4. Use these formatted dates in your JSON body

Step 3: Write to NFC Tag

Now program your NFC tag to trigger this shortcut:

1. Open the Shortcuts app

2. Go to Automation tab → Create Personal Automation

3. Select "NFC" as trigger

4. Tap "Scan" and hold your NFC tag to your phone

5. Name the tag (e.g., "Office Clock In")

6. Add your shortcut as the automation action

7. Disable "Ask Before Running" for instant execution

Step 4: Create Clock Out Tag

Repeat the process for a clock-out tag, but modify the JSON to include an end time:

{
  "date": "CURRENT_DATE",
  "start_time": "START_TIME_FROM_DATABASE",
  "end_time": "CURRENT_TIME",
  "location": "office"
}

Note: For clock-out, you'll need to fetch today's entry first to get the start_time, then update it with an end_time.

Alternative: Android with Tasker

Android users can use Tasker app with AutoApps plugin for similar functionality:

1. Install Tasker and AutoApps (NFC for Tasker)

2. Create a new Task in Tasker

3. Add "HTTP Request" action with your API endpoint

4. Set up NFC trigger through AutoApps

5. Write the task to your NFC tag

Complete Example Shortcut

Here's a complete shortcut configuration for clock-in:

// Shortcut Actions:
1. Get Current Date
2. Format Date (yyyy-MM-dd) → Variable: CurrentDate
3. Format Date (HH:mm) → Variable: CurrentTime
4. Text:
   {
     "date": [CurrentDate],
     "start_time": [CurrentTime],
     "location": "office"
   }
   → Variable: RequestBody
5. Get Contents of URL:
   - URL: https://timetracker.adatepe.dev/api/time-entries
   - Method: POST
   - Headers:
       Authorization: Bearer YOUR_ACCESS_TOKEN
       Content-Type: application/json
   - Request Body: [RequestBody]
6. Show Notification:
   - Title: "Clocked In!"
   - Body: "Started work at [CurrentTime]"

5. API Reference

POST/api/time-entries

Create a new time entry or update an existing one for a specific date.

Request Body

{
  "date": "2025-01-15",        // Required: YYYY-MM-DD
  "start_time": "09:00",       // Required: HH:mm
  "end_time": "17:30",         // Optional: HH:mm
  "location": "office",        // Required: "office" or "home"
  "duration_minutes": 510,     // Optional: auto-calculated
  "user_id": "uuid"            // Optional: Must match authenticated user
}

Response (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "your-user-id",
  "date": "2025-01-15",
  "start_time": "09:00",
  "end_time": "17:30",
  "location": "office",
  "duration_minutes": 510,
  "created_at": "2025-01-15T09:00:00Z",
  "updated_at": "2025-01-15T17:30:00Z"
}

GET/api/time-entries

Retrieve all your time entries, optionally filtered by date.

Query Parameters

?date=2025-01-15&user_id=uuid(optional)

Response (200 OK)

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "date": "2025-01-15",
    "start_time": "09:00",
    "end_time": "17:30",
    "location": "office",
    "duration_minutes": 510
  }
]

GET/api/time-entries/stats

Get comprehensive statistics and analytics about your work patterns.

Query Parameters

?days=30(optional, default: 30)

?range=week(optional: "7d", "30d", "90d", "1y", "week", "month", "all")

Response (200 OK)

{
  "stats": {
    "totalHours": 168.5,
    "totalDays": 21,
    "homeOfficeDays": 8,
    "officeDays": 13,
    "averageHoursPerDay": 8.02,
    "averageStartTime": "09:15",
    "averageEndTime": "17:30",
    "longestDay": 10.5,
    "shortestDay": 6.25
  },
  "entries": [ /* all entries */ ]
}

PATCH/api/time-entries/[id]

Update a specific time entry by its ID. All fields are optional.

Request Body

{
  "end_time": "18:00",      // Only update end time
  "location": "home"        // Or any other field
}

Response (200 OK)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "date": "2025-01-15",
  "start_time": "09:00",
  "end_time": "18:00",     // Updated
  "location": "home",       // Updated
  "duration_minutes": 540
}

6. API Reference (Standard)

These endpoints require a standard Bearer token authentication (as described in Section 2).

Error Responses

401 Unauthorized

Missing or invalid access token. Check your Authorization header.

404 Not Found

Resource doesn't exist or you don't have access to it.

500 Internal Server Error

Server error. Check your request format or contact support.