Skip to main content

​
Overview

The Timetracker API is a RESTful interface that provides programmatic access to your time tracking data and workspace management features. It offers predictable URLs to access resources and uses standard HTTP methods to receive commands and return responses, making it easy to integrate with various environments—from command-line tools to web applications and mobile apps.
The Timetracker API is currently in BETA. While we strive to maintain backward compatibility, some API endpoints may be adjusted in future releases. We’ll communicate any breaking changes well in advance and provide migration guides when necessary.

​
API Characteristics

  • RESTful Design: Follows REST principles with intuitive resource-based URLs
  • JSON Format: Accepts and returns JSON content exclusively
  • UTF-8 Encoding: Supports UTF-8 character encoding for all requests and responses
  • HTTP Standards: Leverages built-in HTTP features for authentication, status codes, and headers

​
Getting Started

To begin using the Timetracker API, you’ll need:
  1. API Key: Obtain your personal API key from your Timetracker account settings
  2. Base URL: All API requests should be made to https://api.timetracker.in/v1
  3. Authentication: Include your API key in every request header

​
Authentication

To use the Timetracker API, every request must include an authentication header. Use X-Api-Key with your personal API key. 
curl -X GET "https://api.timetracker.in/v1/workspaces" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY_HERE"
Keep your API key secure and never expose it in client-side code or public repositories. Treat it like a password.

​
API Versioning

The Timetracker API uses semantic versioning. You can specify a specific API version using the X-Accept-Version request header. If no version is specified, you’ll automatically use the latest stable version. 
curl -X GET "https://api.timetracker.in/v1/workspaces" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY_HERE" \
  -H "X-Accept-Version: 1.0"

​
Rate Limiting

To ensure fair usage and maintain API performance, we implement rate limiting:
  • Standard Limit: 100 requests per minute per API key
  • Burst Limit: Up to 10 requests per second for short periods
  • Response: Exceeding limits returns HTTP 429 (Too Many Requests)
  • Retry-After: Response headers indicate when you can resume making requests
If you need to perform bulk operations or have high-volume requirements, please contact our support team. We may be able to provide alternative solutions or adjust rate limits for your use case.

​
Webhooks

Webhooks help keep your add-on in sync with the latest activity inside Timetracker. With Timetracker’s webhooks, you can receive real-time notifications whenever key events occur—such as when a user starts a timer, stops tracking, or deletes a time entry. This means your integrations can react instantly to changes, without needing to constantly poll the API.

Webhook Setup

Learn how to configure webhooks and handle incoming notifications in your application.

​
Error Handling

The API returns appropriate HTTP status codes and detailed error messages in JSON format. Common status codes include:
  • 200: Success
  • 400: Bad Request (invalid parameters)
  • 401: Unauthorized (invalid or missing API key)
  • 403: Forbidden (insufficient permissions)
  • 404: Not Found (resource doesn’t exist)
  • 429: Too Many Requests (rate limit exceeded)
  • 500: Internal Server Error
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid parameter value",
    "details": {
      "field": "start_time",
      "issue": "Must be a valid ISO 8601 timestamp"
    }
  }
}
  • INVALID_API_KEY: API key is invalid or expired
  • RATE_LIMIT_EXCEEDED: Too many requests in time period
  • RESOURCE_NOT_FOUND: Requested resource doesn’t exist
  • PERMISSION_DENIED: Insufficient permissions for operation
  • VALIDATION_ERROR: Request parameters are invalid