All 79 REST endpoints exposed by the TimeTrack API at https://api.timetracker.cargoffer.com. Authentication via Bearer token (Clerk JWT). Full machine-readable spec at /api/openapi.json.
https://api.timetracker.cargoffer.com
All endpoints (except /health, /ready, and /config) require a Bearer token:
Authorization: Bearer eyJhbGc...your-clerk-jwtYou can obtain a token via Clerk's frontend SDK or use an API key for server-to-server access.
Manage API keys for programmatic access to TimeTrack. Create, list, revoke, and export keys. Get usage statistics for billing and rate limiting. Each user can have one active key at a time.
/api/v1/api-keys
List all API keys for the authenticated user (without raw key).
/api/v1/api-keys
Create a new API key for the authenticated user.
The raw key is returned ONLY in this response. Store it securely.
Max 1 active key per account.
Args:
name: Optional name/label for the key (default: 'Default').
Returns:
The full key details INCLUDING raw_key (one-time only).
required
/api/v1/api-keys/{key_id}
Revoke (soft-delete) an API key. It will no longer work.
key_id (path) required — /api/v1/api-keys/stats
Get usage stats for the user's active API key.
Only works if the user has exactly one active key.
period (query) optional — Period: 24h, 7d, 30d, 90d/api/v1/api-keys/export
Export usage logs as CSV for the user's active API key.
period (query) optional — Period: 30d, 90d, allStripe-powered subscription billing. Create checkout sessions for new subscriptions, manage existing subscriptions via the customer portal, retrieve plans, and handle webhooks. The billing module is shared with the TentPole ecosystem.
/api/v1/billing/plans
Return cached pricing plans from Stripe.
Public endpoint — no authentication required.
Cache TTL is 10 minutes. Falls back to cache if Stripe is unreachable.
Use ?refresh=true to force a fresh fetch from Stripe.
refresh (query) optional — /api/v1/billing/create-checkout-session
Create a Stripe Checkout Session for the authenticated user's organization.
Requires authentication. Uses the user's org from their token.
required
/api/v1/billing/create-portal-session
Create a Stripe Billing Portal session for the authenticated user's organization.
Requires authentication. Customer must already exist.
required
/api/v1/billing/webhook
Handle incoming Stripe webhook events.
No authentication — relies on Stripe webhook signature verification.
The raw request body is required for signature verification.
/api/v1/billing/subscription
Get the current subscription status for the authenticated user's organization.
Returns the plan type, subscription status, and related Stripe info.
CRUD operations for client management. Clients are organizations you bill time to. Each client can have multiple projects, and you can track time against those projects.
/api/v1/clients
/api/v1/clients
required
/api/v1/clients/{client_id}
Get a single client by ID.
client_id (path) required — /api/v1/clients/{client_id}
client_id (path) required — required
/api/v1/clients/{client_id}
client_id (path) required — Dashboard analytics endpoints. Get real-time stats on active timers, today's totals, and weekly summaries. Designed for the main dashboard view in the frontend.
/api/v1/dashboard/active-now
Get all members with active timers.
/api/v1/dashboard/today
Get today's hours for the user's organization.
/api/v1/dashboard/week
Get this week's hours.
Geolocation endpoints for time entries. Attach GPS coordinates to time entries to verify where work was performed. Useful for distributed teams and contractor verification.
/api/v1/time-entries/{entry_id}/location
Store geolocation data on a time entry.
Body: { lat: float, lng: float, accuracy?: float, timestamp?: str }
entry_id (path) required — required
Health check and readiness endpoints for monitoring the TimeTrack API. The /health endpoint returns 200 OK when the service is running. /ready checks database connectivity. /config exposes the public Clerk publishable key for client-side initialization.
/api/v1/health
/api/v1/ready
/api/v1/config
Return Firebase web config for frontend initialization.
Time-off management. Request leaves, approve/reject requests, and manage organization holidays. Supports vacation, sick leave, and custom leave types.
/api/v1/leaves
/api/v1/leaves
required
/api/v1/leaves/{leave_id}/status
leave_id (path) required — required
/api/v1/holidays
year (query) optional — /api/v1/holidays
required
Team membership management. Invite members to your organization, assign roles (admin, manager, member), and activate/deactivate accounts.
/api/v1/members
List all members of the current user's organization.
/api/v1/members/invite
Invite a new member to the organization. Admin only.
required
/api/v1/members/{member_id}/role
Change a member's role. Admin only.
member_id (path) required — required
/api/v1/members/{member_id}
Remove a member. Admin only.
member_id (path) required — /api/v1/members/{member_id}/status
Toggle or set a member's active status. Admin only.
member_id (path) required — required
Organization management. Create, update, and query organizations. Each organization is the top-level container for projects, members, and time entries.
/api/v1/organization
Get the user's current organization (or first one if multiple).
/api/v1/organization
Update organization settings. Admin only.
required
/api/v1/organization
Create a new organization. The creator becomes the owner.
Only users with 'multiple_orgs' feature can create more than one org.
required
/api/v1/organization/all
List ALL organizations this user belongs to.
Used by frontend to populate team selector dropdown.
/api/v1/organization/{org_id}/invite
Invite a user to the organization.
Admin/Manager only. Creates an invitation token sent via email.
org_id (path) required — required
/api/v1/organization/invitations
Get pending invitations for the current user.
/api/v1/organization/join
Join an organization using invitation token.
required
/api/v1/organization/{org_id}/members
List all members of an organization. Admin/Manager only.
org_id (path) required — /api/v1/organization/{org_id}/members/{member_id}
Remove a member from organization. Admin only.
org_id (path) required — member_id (path) required — Pomodoro technique integration. Configure work/break intervals, start/pause/resume sessions, and track completed cycles. Syncs with the timer module.
/api/v1/pomodoro/config
Get the pomodoro configuration for the current user.
/api/v1/pomodoro/config
Update pomodoro configuration.
required
/api/v1/pomodoro/start
Start or restart the pomodoro timer.
/api/v1/pomodoro/pause
Pause the running pomodoro timer.
/api/v1/pomodoro/resume
Resume a paused pomodoro timer.
/api/v1/pomodoro/complete
Mark the current pomodoro session as completed and advance phase.
required
/api/v1/pomodoro/stats
Get pomodoro statistics for today or this week.
period (query) optional — Project CRUD operations. Create projects with budgets, hourly rates, and team assignments. Track time and costs against projects.
/api/v1/projects
List projects for the user's organization.
/api/v1/projects
Create a new project.
required
/api/v1/projects/{project_id}
Get a single project with its time entries summary.
project_id (path) required — /api/v1/projects/{project_id}
Update a project.
project_id (path) required — required
/api/v1/projects/{project_id}
Archive a project (soft delete).
project_id (path) required — Reporting and analytics. Generate summary reports, detailed time entry lists, weekly breakdowns, and attendance reports. Export to CSV for accounting.
/api/v1/reports/summary
Aggregated summary by project/user.
required
/api/v1/reports/detailed
List all time entries with filters.
required
/api/v1/reports/export/csv
Export detailed report as CSV download.
required
/api/v1/reports/weekly
Weekly breakdown — hours per day per member.
required
/api/v1/reports/attendance
Compare tracked vs expected hours.
required
Task management within projects. Create tasks, assign them to team members, and track time spent on each task independently.
/api/v1/projects/{project_id}/tasks
project_id (path) required — /api/v1/projects/{project_id}/tasks
project_id (path) required — required
/api/v1/projects/tasks/{task_id}
task_id (path) required — required
/api/v1/projects/tasks/{task_id}
task_id (path) required — Core time tracking. Start/stop timers, create manual entries, retrieve active and recent entries. The heart of the application.
/api/v1/time-entries/active
Get the currently active timer for the user.
/api/v1/time-entries/active
Update the active timer (assign project/task while running).
required
/api/v1/time-entries/recent
Get recent entries for quick continue.
limit (query) optional — /api/v1/time-entries/start
Start a new timer.
required
/api/v1/time-entries/stop
Stop the active timer.
optional
/api/v1/time-entries
Create a manual time entry.
required
/api/v1/time-entries
Get paginated entries with filters.
page (query) optional — page_size (query) optional — project_id (query) optional — client_id (query) optional — task_id (query) optional — start_date (query) optional — end_date (query) optional — /api/v1/time-entries/continue/{entry_id}
Start a new timer reusing a previous entry's details.
entry_id (path) required — /api/v1/time-entries/{entry_id}
Get a single time entry by ID.
entry_id (path) required — /api/v1/time-entries/{entry_id}/history
Get audit history for a time entry.
entry_id (path) required — Weekly timesheet management. Submit timesheets for approval, approve or reject submissions. Designed for payroll and billing workflows.
/api/v1/timesheets
List timesheets. If year+week provided, get that week.
year (query) optional — week (query) optional — /api/v1/timesheets/current
Get or build the current week's timesheet.
/api/v1/timesheets/submit
Submit current week's timesheet for approval.
/api/v1/timesheets/approve/{timesheet_id}
Approve a timesheet. Manager/Admin only.
timesheet_id (path) required — /api/v1/timesheets/reject/{timesheet_id}
Reject a timesheet with reason. Manager/Admin only.
timesheet_id (path) required — required
User profile and team management. Retrieve teams the user belongs to and switch active team context.
/api/v1/user/teams
List all organizations this user belongs to.
/api/v1/user/active-team
Set the active team for the current user session.
The frontend stores this in localStorage — this endpoint
just validates that the user belongs to the requested team.
required
TimeTrack uses Clerk for authentication. There are two ways to authenticate API requests:
When a user logs in via the frontend, Clerk issues a JWT. Pass this token in the Authorization header:
curl -H "Authorization: Bearer $CLERK_JWT" \
https://api.timetracker.cargoffer.com/api/v1/time-entries/activeCreate an API key via POST /api/v1/api-keys or in the Account settings. Use it the same way:
curl -H "Authorization: Bearer $API_KEY" \
https://api.timetracker.cargoffer.com/api/v1/projectsAPI keys have usage tracking and can be revoked at any time. See api-keys module for details.
The API allows CORS from any origin (CORS_ORIGINS=*) for development. In production, configure your specific frontend domain.
API requests are rate-limited per API key. Limits depend on your subscription plan:
| Plan | Requests/minute | Requests/day |
|---|---|---|
| Free | 60 | 1,000 |
| Pro | 300 | 50,000 |
| Enterprise | Custom | Custom |
Rate-limited responses include the headers X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.
All error responses follow the standard FastAPI error format:
{"detail": "Error message describing what went wrong"}| Status | Meaning |
|---|---|
200 | Successful response |
401 | Missing or invalid authentication |
403 | Authenticated but lacks permission for this resource |
404 | Resource not found |
422 | Validation error (invalid input) |
429 | Rate limit exceeded |
500 | Internal server error |