API Documentation

Authentication

The ClockEye API supports two authentication methods:

curl -H "X-API-Key: your-api-key" \
  https://api.clockeye.ai/api/projects

curl -H "Authorization: Bearer your-access-token" \
  https://api.clockeye.ai/api/time-entries

Base URL

Rate Limits

Error Handling

Errors return JSON with the following structure:

{
  "error": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE",
  "details": {}
}

List Time Entries

Retrieve a paginated list of time entries.

Query Parameters

curl -H "X-API-Key: your-api-key" \
  "https://api.clockeye.ai/api/time-entries?start_date=2024-01-01&end_date=2024-01-31"

Start Timer

Start a new timer. If a timer is already running, it will be stopped first.

curl -X POST https://api.clockeye.ai/api/time-entries/start \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_123",
    "task_id": "task_456",
    "description": "Working on feature"
  }'

Stop Timer

Stop the current running timer and save the time entry.

curl -X POST https://api.clockeye.ai/api/time-entries/stop \
  -H "X-API-Key: your-api-key"

JavaScript / TypeScript

npm install @clockeye/sdk

import { ClockEyeClient } from '@clockeye/sdk';

const client = new ClockEyeClient({
  apiKey: 'your-api-key'
});

// List projects
const projects = await client.projects.list();

// Start timer
const timer = await client.timeEntries.start({
  projectId: 'proj_123',
  description: 'Working on feature'
});

// Stop timer
const entry = await client.timeEntries.stop();

Python

pip install clockeye

from clockeye import ClockEyeClient

client = ClockEyeClient(api_key='your-api-key')

# List projects
projects = client.projects.list()

# Start timer
timer = client.time_entries.start(
    project_id='proj_123',
    description='Working on feature'
)

# Stop timer
entry = client.time_entries.stop()

Create Webhook

curl -X POST https://api.clockeye.ai/api/webhooks \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/clockeye",
    "events": ["time_entry.created", "time_entry.stopped"]
  }'

Available Events

• time_entry.created - New time entry created
• time_entry.updated - Time entry modified
• time_entry.deleted - Time entry removed
• time_entry.started - Timer started
• time_entry.stopped - Timer stopped
• screenshot.captured - Screenshot taken
• project.created - New project created
• project.updated - Project modified
• project.deleted - Project removed
• user.invited - User invitation sent
• user.joined - User accepted invitation
• user.removed - User removed

Verify Signature

All webhook requests include a signature header for verification:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = `sha256=${crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex')}`;

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}