# Clockify API Documentation Index
## Overview
This documentation provides comprehensive guides for integrating with the Clockify API. Each guide is structured for AI consumption with clear patterns, examples, and implementation details.
---
## Quick Reference
### Base URLs
```
Main API (Global): https://api.clockify.me/api/v1
Reports API (Global): https://reports.api.clockify.me/v1
Regional APIs:
EU (Germany): https://euc1.clockify.me/api/v1
USA: https://use2.clockify.me/api/v1
UK: https://euw2.clockify.me/api/v1
AU: https://apse2.clockify.me/api/v1
```
### Authentication
```http
X-Api-Key: YOUR_API_KEY
X-Addon-Token: YOUR_ADDON_TOKEN
```
### Rate Limiting
- **API Key**: No explicit limit
- **Addon Token**: 50 requests/second per workspace
---
## Documentation Structure
### Core API Guides
#### 01. User API (`01_USER_API.md`)
**Purpose**: Manage users, profiles, custom fields, and manager roles
**Key Endpoints**:
- GET `/v1/user` - Get current user info
- GET `/v1/workspaces/{workspaceId}/users` - List workspace users
- POST `/v1/workspaces/{workspaceId}/users/info` - Filter users with advanced criteria
- PATCH `/v1/workspaces/{workspaceId}/member-profile/{userId}` - Update member profile
- PUT `/v1/workspaces/{workspaceId}/users/{userId}/custom-field/{customFieldId}/value` - Update custom field
- POST/DELETE `/v1/workspaces/{workspaceId}/users/{userId}/roles` - Manage manager roles
**Use Cases**:
- User onboarding
- Team management
- Custom field management
- Permission management
---
#### 02. Workspace API (`02_WORKSPACE_API.md`)
**Purpose**: Manage workspaces, settings, rates, and user membership
**Key Endpoints**:
- GET `/v1/workspaces` - Get all user workspaces
- POST `/v1/workspaces` - Create new workspace
- GET `/v1/workspaces/{workspaceId}` - Get workspace details
- PUT `/v1/workspaces/{workspaceId}/cost-rate` - Update cost rate
- PUT `/v1/workspaces/{workspaceId}/hourly-rate` - Update billable rate
- POST `/v1/workspaces/{workspaceId}/users` - Add user to workspace
- PUT `/v1/workspaces/{workspaceId}/users/{userId}` - Update user status
**Use Cases**:
- Workspace setup
- Rate management
- User access control
- Billing configuration
---
#### 03. Time Entry API (`03_TIME_ENTRY_API.md`)
**Purpose**: Create, update, delete, and query time tracking entries
**Key Endpoints**:
- POST `/v1/workspaces/{workspaceId}/time-entries` - Create time entry
- GET `/v1/workspaces/{workspaceId}/user/{userId}/time-entries` - Get user's time entries
- PUT `/v1/workspaces/{workspaceId}/time-entries/{timeEntryId}` - Update time entry
- DELETE `/v1/workspaces/{workspaceId}/time-entries/{timeEntryId}` - Delete time entry
- PATCH `/v1/workspaces/{workspaceId}/user/{userId}/time-entries` - Stop timer
- PUT `/v1/workspaces/{workspaceId}/time-entries/bulk-edit` - Bulk edit entries
- POST `/v1/workspaces/{workspaceId}/time-entries/{timeEntryId}/duplicate` - Duplicate entry
**Use Cases**:
- Time tracking automation
- Timer management
- Time entry synchronization
- Bulk operations
---
#### 04. Project API (`04_PROJECT_API.md`)
**Purpose**: Manage projects, tasks, estimates, and team assignments
**Key Endpoints**:
- GET `/v1/workspaces/{workspaceId}/projects` - List projects with filtering
- POST `/v1/workspaces/{workspaceId}/projects` - Create project
- PUT `/v1/workspaces/{workspaceId}/projects/{projectId}` - Update project
- PATCH `/v1/workspaces/{workspaceId}/projects/{projectId}/estimate` - Update estimates
- POST `/v1/workspaces/{workspaceId}/projects/{projectId}/users` - Assign users
- PUT `/v1/workspaces/{workspaceId}/projects/{projectId}/users/{userId}/hourly-rate` - Set user rate
**Use Cases**:
- Project setup
- Team assignment
- Budget management
- Rate configuration
---
#### 05. Reports API (`05_REPORTS_API.md`)
**Purpose**: Generate detailed, summary, and weekly reports with filtering
**Key Endpoints**:
- POST `/workspaces/{workspaceId}/reports/detailed` - Detailed time entry report
- POST `/workspaces/{workspaceId}/reports/summary` - Aggregated summary report
- POST `/workspaces/{workspaceId}/reports/weekly` - Week-by-week breakdown
- POST `/workspaces/{workspaceId}/reports/expenses` - Expense report
**Use Cases**:
- Invoice generation
- Time analysis
- Project profitability
- Team utilization
- Client billing
**Note**: Reports API uses different base URL than main API
---
#### 06. Webhooks API (`06_WEBHOOKS_API.md`)
**Purpose**: Configure real-time event notifications
**Key Endpoints**:
- GET `/v1/workspaces/{workspaceId}/webhooks` - List webhooks
- POST `/v1/workspaces/{workspaceId}/webhooks` - Create webhook
- PUT `/v1/workspaces/{workspaceId}/webhooks/{webhookId}` - Update webhook
- DELETE `/v1/workspaces/{workspaceId}/webhooks/{webhookId}` - Delete webhook
- PATCH `/v1/workspaces/{workspaceId}/webhooks/{webhookId}/token` - Regenerate token
- POST `/v1/workspaces/{workspaceId}/webhooks/{webhookId}/logs` - Get logs
**Event Types**: 40+ events covering time entries, projects, users, approvals, expenses, etc.
**Use Cases**:
- Real-time integrations
- Event-driven workflows
- Notification systems
- Audit logging
---
## Additional API Sections
### Client API
**Endpoints**: Create, list, update, delete clients
**Path**: `/v1/workspaces/{workspaceId}/clients`
### Task API
**Endpoints**: Manage tasks within projects
**Path**: `/v1/workspaces/{workspaceId}/projects/{projectId}/tasks`
### Tag API
**Endpoints**: Create, list, update, delete tags
**Path**: `/v1/workspaces/{workspaceId}/tags`
### Custom Fields API
**Endpoints**: Manage workspace and project custom fields
**Path**: `/v1/workspaces/{workspaceId}/custom-fields`
### Approval API
**Endpoints**: Submit and manage time entry approvals
**Path**: `/v1/workspaces/{workspaceId}/approval-requests`
### Time Off API
**Endpoints**: Request and manage time off (PTO)
**Path**: `/v1/workspaces/{workspaceId}/time-off`
### Expense API
**Endpoints**: Track and manage expenses
**Path**: `/v1/workspaces/{workspaceId}/expenses`
### Invoice API
**Endpoints**: Generate and manage invoices
**Path**: `/v1/workspaces/{workspaceId}/invoices`
### Scheduling API
**Endpoints**: Manage resource scheduling and assignments
**Path**: `/v1/workspaces/{workspaceId}/scheduling`
### Group API
**Endpoints**: Manage user groups
**Path**: `/v1/workspaces/{workspaceId}/groups`
---
## Common Integration Patterns
### Pattern 1: Basic Time Tracking Integration
```
1. Get current user → GET /v1/user
2. List workspaces → GET /v1/workspaces
3. Get projects → GET /v1/workspaces/{id}/projects
4. Create time entry → POST /v1/workspaces/{id}/time-entries
```
### Pattern 2: Project Management Integration
```
1. Create project → POST /v1/workspaces/{id}/projects
2. Add team members → POST /v1/workspaces/{id}/projects/{pid}/users
3. Create tasks → POST /v1/workspaces/{id}/projects/{pid}/tasks
4. Set estimates → PATCH /v1/workspaces/{id}/projects/{pid}/estimate
```
### Pattern 3: Reporting & Analytics
```
1. Get detailed report → POST /workspaces/{id}/reports/detailed
2. Get summary report → POST /workspaces/{id}/reports/summary
3. Process and analyze data locally
```
### Pattern 4: Real-Time Event Processing
```
1. Create webhook → POST /v1/workspaces/{id}/webhooks
2. Configure event type and trigger sources
3. Implement webhook endpoint to receive events
4. Process events asynchronously
```
### Pattern 5: User Onboarding
```
1. Add users → POST /v1/workspaces/{id}/users
2. Set custom fields → PUT /v1/workspaces/{id}/users/{uid}/custom-field/{cfid}/value
3. Assign to projects → POST /v1/workspaces/{id}/projects/{pid}/users
4. Set rates → PUT /v1/workspaces/{id}/projects/{pid}/users/{uid}/hourly-rate
```
---
## Data Model Hierarchy
### Rate Priority (highest to lowest)
1. Task-specific rate
2. Project-specific user rate
3. User workspace rate
4. Project default rate
5. Workspace default rate
### Entity Relationships
```
Workspace
├── Users (with workspace rates)
├── Projects
│ ├── Tasks (with task rates)
│ ├── Team Members (with project-specific rates)
│ └── Time Entries
├── Clients
├── Tags
├── Custom Fields
└── User Groups
```
---
## Common Data Formats
### Dates & Times
- **Format**: ISO-8601 with timezone
- **Example**: `2024-01-29T14:30:00Z`
- **Always use UTC** (append 'Z')
### Durations
- **Format**: ISO-8601 duration
- **Examples**:
- `PT2H30M` = 2 hours 30 minutes
- `PT45M` = 45 minutes
- `PT8H` = 8 hours
### Money Amounts
- **Format**: Integer in smallest currency unit
- **Example**: `15000` = $150.00 USD
- **Always in cents** (for USD)
### Colors
- **Format**: Hex color code
- **Example**: `#0B83D9`
---
## Error Handling
### Common HTTP Status Codes
| Code | Meaning | Common Causes |
|------|---------|---------------|
| 200 | OK | Successful GET/PUT/PATCH |
| 201 | Created | Successful POST |
| 204 | No Content | Successful DELETE |
| 400 | Bad Request | Invalid parameters, validation failed |
| 401 | Unauthorized | Invalid/missing API key |
| 403 | Forbidden | Insufficient permissions |
| 404 | Not Found | Resource doesn't exist |
| 409 | Conflict | Duplicate resource |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Server Error | Clockify server issue |
### Error Response Format
```json
{
"message": "Detailed error message",
"code": 400
}
```
---
## Best Practices
### General
1. **Use Regional URLs**: Use correct regional endpoint for workspace
2. **Handle Pagination**: Implement pagination for large datasets
3. **Cache Appropriately**: Cache reference data (projects, users, tags)
4. **Exponential Backoff**: Implement for rate limit handling
5. **Validate Input**: Validate data before API calls
6. **Log Requests**: Log API requests for debugging
7. **Secure Keys**: Store API keys securely
### Performance
1. **Batch Operations**: Use bulk endpoints when available
2. **Filter Server-Side**: Use API filters instead of client-side
3. **Minimize Calls**: Combine related data in single requests
4. **Use Webhooks**: For real-time updates instead of polling
5. **Optimize Date Ranges**: Keep report date ranges reasonable
### Security
1. **HTTPS Only**: All API calls must use HTTPS
2. **Rotate Keys**: Periodically rotate API keys
3. **Verify Webhooks**: Always verify webhook signatures
4. **Least Privilege**: Use appropriate permission levels
5. **Environment Variables**: Store credentials in env vars
---
## Quick Start Examples
### Python Setup
```python
import requests
API_KEY = "your_api_key_here"
BASE_URL = "https://api.clockify.me/api/v1"
REPORTS_BASE_URL = "https://reports.api.clockify.me/v1"
headers = {
"X-Api-Key": API_KEY,
"Content-Type": "application/json"
}
# Get current user
response = requests.get(f"{BASE_URL}/user", headers=headers)
user = response.json()
print(f"Logged in as: {user['name']}")
```
### JavaScript/Node.js Setup
```javascript
const axios = require('axios');
const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://api.clockify.me/api/v1';
const headers = {
'X-Api-Key': API_KEY,
'Content-Type': 'application/json'
};
// Get current user
axios.get(`${BASE_URL}/user`, { headers })
.then(response => {
console.log(`Logged in as: ${response.data.name}`);
});
```
---
## Support Resources
### Official Documentation
- API Docs: https://docs.clockify.me/
- Support: https://support.clockify.com/
### Community
- Stack Overflow: Tag questions with "clockify"
- CAKE Marketplace: https://marketplace.cake.com
---
## Version Information
- **API Version**: v1
- **Documentation Date**: January 2025
- **Minimum TLS**: 1.2
---
## Getting Help
### When Reading These Guides
1. Start with the relevant section (User, Project, Time Entry, etc.)
2. Review the endpoint list and use cases
3. Check implementation examples
4. Refer to data models for structure
5. Review best practices section
### For Implementation
1. Set up authentication with API key
2. Test with simple GET request (current user)
3. Explore workspace structure
4. Implement core functionality
5. Add error handling and logging
6. Implement webhooks for real-time updates
### For AI Integration
- These guides are structured with clear patterns
- Examples show complete request/response cycles
- Data models define exact structure
- Use cases explain when to use each endpoint
- Implementation examples show practical usage
---
## Document Updates
To regenerate or update any section:
1. Fetch latest API documentation from https://docs.clockify.me/
2. Review breaking changes section
3. Update endpoint details and examples
4. Test code examples for correctness
5. Update data models if schema changed
---
## Copyright & License
These guides document the Clockify API which is © CAKE.com (Clockify parent company).
API usage subject to Clockify Terms of Service.
