openapi: 3.0.3
info:
title: Everhour API
description: >-
The Everhour API is a RESTful interface providing programmatic access to
time tracking, timesheets, timers, projects, tasks, clients, invoices,
expenses, resource scheduling, time off, and reporting data in Everhour.
The API accepts and returns JSON (UTF-8 only). All requests are
authenticated with an X-Api-Key header carrying an API key found at the
bottom of your Everhour profile page. An optional X-Accept-Version header
pins a specific API version (the most recent, 1.2, is used by default).
The API is labeled BETA by Everhour, meaning some calls can be slightly
adjusted; breaking changes are pushed in separate API versions. Time
values are in seconds and money amounts are in cents throughout.
version: '1.2'
contact:
name: Everhour
url: https://everhour.com
email: ask@everhour.com
servers:
- url: https://api.everhour.com
description: Everhour production API
security:
- apiKey: []
tags:
- name: Time Records
description: Reported time records for the team, users, tasks, and projects.
- name: Timers
description: Start, inspect, and stop running timers.
- name: Timecards
description: Clock-in/clock-out attendance timecards.
- name: Timesheets
description: Weekly timesheets and the timesheet approval workflow.
- name: Projects
description: Projects, sections, billing, budgets, and integration sync.
- name: Tasks
description: Tasks, task search, and task estimates.
- name: Schedule
description: Resource planner assignments.
- name: Time Off
description: Time off types and allocations.
- name: Clients
description: Clients and client budgets.
- name: Invoices
description: Invoices generated from tracked time and expenses.
- name: Expenses
description: Expenses, expense categories, and attachments.
- name: Reports
description: Dashboard reports for projects, clients, and users.
- name: Users
description: Current user and team members.
- name: Webhooks
description: Webhook subscriptions for resource change events.
paths:
/team/time:
get:
operationId: getAllTimeRecords
tags:
- Time Records
summary: Get all time records
description: >-
Returns time records across the whole team, optionally filtered by
date range and paginated. Pass opts_include_billing=1 to include
billing data (admins with billing permissions only).
parameters:
- $ref: '#/components/parameters/From'
- $ref: '#/components/parameters/To'
- $ref: '#/components/parameters/TimeLimit'
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/IncludeBilling'
responses:
'200':
description: A list of time records.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/TimeRecordExtended'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/users/{userId}/time:
get:
operationId: getUserTimeRecords
tags:
- Time Records
summary: Get user time records
description: Returns time records reported by a specific user.
parameters:
- $ref: '#/components/parameters/UserId'
- $ref: '#/components/parameters/From'
- $ref: '#/components/parameters/To'
- $ref: '#/components/parameters/TimeLimit'
- $ref: '#/components/parameters/Page'
responses:
'200':
description: A list of the user's time records.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/TimeRecord'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/tasks/{taskId}/time:
get:
operationId: getTaskTimeRecords
tags:
- Time Records
summary: Get task time records
description: Returns time records reported against a specific task.
parameters:
- $ref: '#/components/parameters/TaskId'
- $ref: '#/components/parameters/From'
- $ref: '#/components/parameters/To'
- $ref: '#/components/parameters/TimeLimit'
- $ref: '#/components/parameters/Page'
responses:
'200':
description: A list of the task's time records.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/TimeRecordExtended'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/projects/{projectId}/time:
get:
operationId: getProjectTimeRecords
tags:
- Time Records
summary: Get project time records
description: Returns time records reported against a specific project.
parameters:
- $ref: '#/components/parameters/ProjectId'
- $ref: '#/components/parameters/From'
- $ref: '#/components/parameters/To'
- $ref: '#/components/parameters/TimeLimit'
- $ref: '#/components/parameters/Page'
responses:
'200':
description: A list of the project's time records.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/TimeRecordExtended'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/time:
post:
operationId: addTime
tags:
- Time Records
summary: Add time
description: Adds a time record to a task for a user on a given date.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TimeRecordRequest'
responses:
'201':
description: The created time record.
content:
application/json:
schema:
$ref: '#/components/schemas/TimeRecordExtended'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/time/{timeId}:
parameters:
- $ref: '#/components/parameters/TimeId'
put:
operationId: updateTimeRecord
tags:
- Time Records
summary: Update time record
description: Updates an existing time record.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TimeRecordRequest'
responses:
'200':
description: The updated time record.
content:
application/json:
schema:
$ref: '#/components/schemas/TimeRecordExtended'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
delete:
operationId: deleteTimeRecord
tags:
- Time Records
summary: Delete time record
description: Deletes a time record.
responses:
'200':
description: The deleted time record.
content:
application/json:
schema:
$ref: '#/components/schemas/TimeRecordExtended'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/timers:
post:
operationId: startTimer
tags:
- Timers
summary: Start timer
description: Starts a timer on a task for the current user.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TimerRequest'
responses:
'201':
description: The started timer.
content:
application/json:
schema:
$ref: '#/components/schemas/Timer'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/timers/current:
get:
operationId: getRunningTimer
tags:
- Timers
summary: Get running timer
description: Returns the currently running timer for the current user.
responses:
'200':
description: The running timer (status stopped if none is running).
content:
application/json:
schema:
$ref: '#/components/schemas/Timer'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
delete:
operationId: stopTimer
tags:
- Timers
summary: Stop timer
description: Stops the currently running timer and records the tracked time.
responses:
'200':
description: The stopped timer.
content:
application/json:
schema:
$ref: '#/components/schemas/Timer'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/team/timers:
get:
operationId: getAllTeamTimers
tags:
- Timers
summary: Get all team timers
description: Returns all currently running timers across the team.
responses:
'200':
description: A list of running timers.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Timer'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/timecards:
get:
operationId: getAllTimecards
tags:
- Timecards
summary: Get all timecards
description: Returns timecards for the whole team within a date range (last two weeks by default).
parameters:
- $ref: '#/components/parameters/From'
- $ref: '#/components/parameters/To'
responses:
'200':
description: A list of timecards.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Timecard'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/users/{userId}/timecards:
get:
operationId: getUserTimecards
tags:
- Timecards
summary: Get user timecards
description: Returns timecards for a user within a date range (last two weeks by default).
parameters:
- $ref: '#/components/parameters/UserId'
- $ref: '#/components/parameters/From'
- $ref: '#/components/parameters/To'
responses:
'200':
description: A list of the user's timecards.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Timecard'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/users/{userId}/timecards/{date}:
parameters:
- $ref: '#/components/parameters/UserId'
- $ref: '#/components/parameters/Date'
get:
operationId: getTimecard
tags:
- Timecards
summary: Get timecard
description: Returns the timecard for a user on a specific date.
responses:
'200':
description: The timecard.
content:
application/json:
schema:
$ref: '#/components/schemas/Timecard'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
put:
operationId: updateTimecard
tags:
- Timecards
summary: Update timecard
description: Updates clock-in, clock-out, or break time on a timecard.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TimecardUpdateRequest'
responses:
'200':
description: The updated timecard.
content:
application/json:
schema:
$ref: '#/components/schemas/Timecard'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
delete:
operationId: deleteTimecard
tags:
- Timecards
summary: Delete timecard
description: Deletes a user's timecard for a specific date.
responses:
'204':
description: Timecard deleted.
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/users/{userId}/timecards/clock-in:
post:
operationId: clockIn
tags:
- Timecards
summary: Clock in
description: Clocks a user in, creating or updating today's timecard.
parameters:
- $ref: '#/components/parameters/UserId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ClockRequest'
responses:
'200':
description: The timecard after clocking in.
content:
application/json:
schema:
$ref: '#/components/schemas/Timecard'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/users/{userId}/timecards/clock-out:
post:
operationId: clockOut
tags:
- Timecards
summary: Clock out
description: Clocks a user out on today's timecard.
parameters:
- $ref: '#/components/parameters/UserId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ClockRequest'
responses:
'200':
description: The timecard after clocking out.
content:
application/json:
schema:
$ref: '#/components/schemas/Timecard'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/users/{userId}/timesheets:
get:
operationId: getUserTimesheets
tags:
- Timesheets
summary: Get user timesheets
description: Returns weekly timesheets for a user (most recent weeks first).
parameters:
- $ref: '#/components/parameters/UserId'
- name: limit
in: query
description: Max number of weeks to return.
schema:
type: integer
responses:
'200':
description: A list of the user's timesheets.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Timesheet'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/timesheets:
get:
operationId: getTeamTimesheets
tags:
- Timesheets
summary: Get team timesheets
description: >-
Returns timesheets for the whole team for a given week. The week ID is
the two-digit year plus the week number (for example 2535 for week 35
of 2025).
parameters:
- name: weekId
in: query
required: true
description: Week ID (two-digit year + week number).
schema:
type: integer
responses:
'200':
description: A list of team timesheets for the week.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Timesheet'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/timesheets/{timesheetId}/approval:
parameters:
- $ref: '#/components/parameters/TimesheetId'
post:
operationId: submitTimesheetApproval
tags:
- Timesheets
summary: Approve week / request approval
description: >-
Submits a weekly timesheet for approval (or approves it directly when
called by an admin). The timesheet ID is the user ID concatenated with
the week ID.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TimesheetApprovalRequest'
responses:
'200':
description: The timesheet approval.
content:
application/json:
schema:
$ref: '#/components/schemas/TimesheetApproval'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
put:
operationId: reviewTimesheetApproval
tags:
- Timesheets
summary: Approve or reject approval request
description: Approves or rejects a pending timesheet approval request, optionally per day of the week.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TimesheetApprovalReviewRequest'
responses:
'200':
description: The reviewed timesheet approval.
content:
application/json:
schema:
$ref: '#/components/schemas/TimesheetApproval'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/timesheets/{timesheetId}/discard-approval:
put:
operationId: discardTimesheetApproval
tags:
- Timesheets
summary: Discard your approval request
description: Discards a previously submitted timesheet approval request.
parameters:
- $ref: '#/components/parameters/TimesheetId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TimesheetApprovalRequest'
responses:
'200':
description: The timesheet approval after discarding.
content:
application/json:
schema:
$ref: '#/components/schemas/TimesheetApproval'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/projects:
get:
operationId: getAllProjects
tags:
- Projects
summary: Get all projects
description: Returns projects, optionally filtered by name query or source integration platform.
parameters:
- name: limit
in: query
description: Max results.
schema:
type: integer
- name: query
in: query
description: Search projects by name.
schema:
type: string
- name: platform
in: query
description: Filter by integration platform code (for example as, ev, b3, b2, pv, gh, in, tr, jr).
schema:
type: string
responses:
'200':
description: A list of projects.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Project'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
post:
operationId: createProject
tags:
- Projects
summary: Create project
description: Creates a native Everhour project.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectRequest'
responses:
'201':
description: The created project.
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/projects/{projectId}:
parameters:
- $ref: '#/components/parameters/ProjectId'
get:
operationId: getProject
tags:
- Projects
summary: Get project
description: Returns a single project by ID.
responses:
'200':
description: The project.
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
put:
operationId: updateProject
tags:
- Projects
summary: Update project
description: Updates a project.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectRequest'
responses:
'200':
description: The updated project.
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
delete:
operationId: deleteProject
tags:
- Projects
summary: Delete project
description: Deletes a project.
responses:
'204':
description: Project deleted.
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/projects/{projectId}/archive:
patch:
operationId: archiveProject
tags:
- Projects
summary: Archive or unarchive project
description: Archives or unarchives a project.
parameters:
- $ref: '#/components/parameters/ProjectId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
archived:
type: boolean
responses:
'201':
description: The project after archiving/unarchiving.
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/projects/{projectId}/billing:
put:
operationId: updateProjectBilling
tags:
- Projects
summary: Update project billing and budget
description: >-
Updates a project's billing type (non_billable, hourly, fixed_fee),
rate configuration (project_rate or user_rate with per-user
overrides), and budget (money, time, or costs; general, monthly,
weekly, or daily periods).
parameters:
- $ref: '#/components/parameters/ProjectId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectBilling'
responses:
'200':
description: The updated project.
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/projects/{projectId}/sync:
post:
operationId: syncIntegrationProject
tags:
- Projects
summary: Sync integration project
description: >-
Instantly synchronizes a project from a connected integration (Asana,
Trello, ClickUp, GitHub, and more) into Everhour instead of waiting
for background sync. Safe to call multiple times; returns the existing
project if already synced.
parameters:
- $ref: '#/components/parameters/ProjectId'
responses:
'200':
description: The synced project.
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/projects/{projectId}/sections:
parameters:
- $ref: '#/components/parameters/ProjectId'
get:
operationId: getProjectSections
tags:
- Projects
summary: Get project sections
description: Returns the sections of a project.
responses:
'200':
description: A list of sections.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Section'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
post:
operationId: createSection
tags:
- Projects
summary: Create section
description: Creates a section in a project.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SectionRequest'
responses:
'201':
description: The created section.
content:
application/json:
schema:
$ref: '#/components/schemas/Section'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/sections/{sectionId}:
parameters:
- name: sectionId
in: path
required: true
description: Section ID.
schema:
type: integer
get:
operationId: getSection
tags:
- Projects
summary: Get section
description: Returns a single section by ID.
responses:
'200':
description: The section.
content:
application/json:
schema:
$ref: '#/components/schemas/Section'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
put:
operationId: updateSection
tags:
- Projects
summary: Update section
description: Updates a section.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SectionRequest'
responses:
'200':
description: The updated section.
content:
application/json:
schema:
$ref: '#/components/schemas/Section'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
delete:
operationId: deleteSection
tags:
- Projects
summary: Delete section
description: Deletes a section.
responses:
'204':
description: Section deleted.
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/projects/{projectId}/tasks:
parameters:
- $ref: '#/components/parameters/ProjectId'
get:
operationId: getProjectTasks
tags:
- Tasks
summary: Get project tasks
description: Returns the tasks of a project, paginated up to 250 per page.
parameters:
- name: page
in: query
description: Results page.
schema:
type: integer
- name: limit
in: query
description: Tasks per page, 250 max.
schema:
type: integer
- name: exclude-closed
in: query
description: Exclude closed/completed tasks.
schema:
type: boolean
- name: query
in: query
description: Search tasks by name.
schema:
type: string
responses:
'200':
description: A list of tasks.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Task'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
post:
operationId: createTask
tags:
- Tasks
summary: Create task
description: Creates a task in a project section.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TaskRequest'
responses:
'201':
description: The created task.
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/tasks/search:
get:
operationId: searchTasks
tags:
- Tasks
summary: Search tasks
description: Searches tasks across all projects by name.
parameters:
- name: query
in: query
description: Search query.
schema:
type: string
- name: limit
in: query
description: Max number of search results.
schema:
type: integer
- name: searchInClosed
in: query
description: Also search closed/completed tasks.
schema:
type: boolean
responses:
'200':
description: Matching tasks.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Task'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/projects/{projectId}/tasks/search:
get:
operationId: searchProjectTasks
tags:
- Tasks
summary: Search project tasks
description: Searches tasks within a single project by name.
parameters:
- $ref: '#/components/parameters/ProjectId'
- name: query
in: query
description: Search query.
schema:
type: string
- name: limit
in: query
description: Max number of search results.
schema:
type: integer
- name: searchInClosed
in: query
description: Also search closed/completed tasks.
schema:
type: boolean
responses:
'200':
description: Matching tasks.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Task'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/tasks/{taskId}:
parameters:
- $ref: '#/components/parameters/TaskId'
get:
operationId: getTask
tags:
- Tasks
summary: Get task
description: >-
Returns a single task by ID. Pass opts_include_billing=1 to include
billing data (admins with billing permissions only).
parameters:
- $ref: '#/components/parameters/IncludeBilli
# --- truncated at 32 KB (96 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/everhour/refs/heads/main/openapi/everhour-openapi.yml