openapi: 3.1.0
info:
  title: Harvest API v2
  version: 2.0.0
  description: |
    REST API for Harvest time tracking, projects, clients, invoices,
    estimates, expenses, tasks, users, roles, company settings, and reports.
    Authentication uses a personal access token or OAuth 2.0 bearer token in
    the Authorization header together with the Harvest-Account-Id header.
  contact:
    name: Harvest API Documentation
    url: https://help.getharvest.com/api-v2/
servers:
  - url: https://api.harvestapp.com/v2
    description: Harvest production API
security:
  - bearerAuth: []
tags:
  - name: TimeEntries
  - name: Projects
  - name: Clients
  - name: Users
  - name: Invoices
  - name: Expenses
  - name: Estimates
  - name: Tasks
  - name: Roles
  - name: Company
  - name: Reports
paths:
  /time_entries:
    get:
      summary: List time entries
      operationId: listTimeEntries
      tags: [TimeEntries]
      responses:
        "200":
          description: List of time entries.
    post:
      summary: Create a time entry
      operationId: createTimeEntry
      tags: [TimeEntries]
      responses:
        "201":
          description: Time entry created.
  /time_entries/{time_entry_id}:
    get:
      summary: Retrieve a time entry
      operationId: getTimeEntry
      tags: [TimeEntries]
      parameters:
        - in: path
          name: time_entry_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Time entry details.
    patch:
      summary: Update a time entry
      operationId: updateTimeEntry
      tags: [TimeEntries]
      parameters:
        - in: path
          name: time_entry_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Time entry updated.
    delete:
      summary: Delete a time entry
      operationId: deleteTimeEntry
      tags: [TimeEntries]
      parameters:
        - in: path
          name: time_entry_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Time entry deleted.
  /time_entries/{time_entry_id}/restart:
    patch:
      summary: Restart a stopped time entry
      operationId: restartTimeEntry
      tags: [TimeEntries]
      parameters:
        - in: path
          name: time_entry_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Time entry restarted.
  /time_entries/{time_entry_id}/stop:
    patch:
      summary: Stop a running time entry
      operationId: stopTimeEntry
      tags: [TimeEntries]
      parameters:
        - in: path
          name: time_entry_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Time entry stopped.
  /time_entries/{time_entry_id}/external_reference:
    delete:
      summary: Remove external reference from a time entry
      operationId: deleteTimeEntryExternalReference
      tags: [TimeEntries]
      parameters:
        - in: path
          name: time_entry_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: External reference removed.
  /projects:
    get:
      summary: List projects
      operationId: listProjects
      tags: [Projects]
      responses:
        "200":
          description: List of projects.
    post:
      summary: Create a project
      operationId: createProject
      tags: [Projects]
      responses:
        "201":
          description: Project created.
  /projects/{project_id}:
    get:
      summary: Retrieve a project
      operationId: getProject
      tags: [Projects]
      parameters:
        - in: path
          name: project_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Project details.
    patch:
      summary: Update a project
      operationId: updateProject
      tags: [Projects]
      parameters:
        - in: path
          name: project_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Project updated.
    delete:
      summary: Delete a project
      operationId: deleteProject
      tags: [Projects]
      parameters:
        - in: path
          name: project_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Project deleted.
  /clients:
    get:
      summary: List clients
      operationId: listClients
      tags: [Clients]
      responses:
        "200":
          description: List of clients.
    post:
      summary: Create a client
      operationId: createClient
      tags: [Clients]
      responses:
        "201":
          description: Client created.
  /clients/{client_id}:
    get:
      summary: Retrieve a client
      operationId: getClient
      tags: [Clients]
      parameters:
        - in: path
          name: client_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Client details.
    patch:
      summary: Update a client
      operationId: updateClient
      tags: [Clients]
      parameters:
        - in: path
          name: client_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Client updated.
    delete:
      summary: Delete a client
      operationId: deleteClient
      tags: [Clients]
      parameters:
        - in: path
          name: client_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Client deleted.
  /users:
    get:
      summary: List users
      operationId: listUsers
      tags: [Users]
      responses:
        "200":
          description: List of users.
    post:
      summary: Create a user
      operationId: createUser
      tags: [Users]
      responses:
        "201":
          description: User created.
  /users/me:
    get:
      summary: Retrieve the currently authenticated user
      operationId: getMe
      tags: [Users]
      responses:
        "200":
          description: Authenticated user details.
  /users/{user_id}:
    get:
      summary: Retrieve a user
      operationId: getUser
      tags: [Users]
      parameters:
        - in: path
          name: user_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: User details.
    patch:
      summary: Update a user
      operationId: updateUser
      tags: [Users]
      parameters:
        - in: path
          name: user_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: User updated.
    delete:
      summary: Delete a user
      operationId: deleteUser
      tags: [Users]
      parameters:
        - in: path
          name: user_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: User deleted.
  /invoices:
    get:
      summary: List invoices
      operationId: listInvoices
      tags: [Invoices]
      responses:
        "200":
          description: List of invoices.
    post:
      summary: Create an invoice
      operationId: createInvoice
      tags: [Invoices]
      responses:
        "201":
          description: Invoice created.
  /invoices/{invoice_id}:
    get:
      summary: Retrieve an invoice
      operationId: getInvoice
      tags: [Invoices]
      parameters:
        - in: path
          name: invoice_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Invoice details.
    patch:
      summary: Update an invoice
      operationId: updateInvoice
      tags: [Invoices]
      parameters:
        - in: path
          name: invoice_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Invoice updated.
    delete:
      summary: Delete an invoice
      operationId: deleteInvoice
      tags: [Invoices]
      parameters:
        - in: path
          name: invoice_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Invoice deleted.
  /expenses:
    get:
      summary: List expenses
      operationId: listExpenses
      tags: [Expenses]
      responses:
        "200":
          description: List of expenses.
    post:
      summary: Create an expense
      operationId: createExpense
      tags: [Expenses]
      responses:
        "201":
          description: Expense created.
  /expenses/{expense_id}:
    get:
      summary: Retrieve an expense
      operationId: getExpense
      tags: [Expenses]
      parameters:
        - in: path
          name: expense_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Expense details.
    patch:
      summary: Update an expense
      operationId: updateExpense
      tags: [Expenses]
      parameters:
        - in: path
          name: expense_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Expense updated.
    delete:
      summary: Delete an expense
      operationId: deleteExpense
      tags: [Expenses]
      parameters:
        - in: path
          name: expense_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Expense deleted.
  /estimates:
    get:
      summary: List estimates
      operationId: listEstimates
      tags: [Estimates]
      responses:
        "200":
          description: List of estimates.
    post:
      summary: Create an estimate
      operationId: createEstimate
      tags: [Estimates]
      responses:
        "201":
          description: Estimate created.
  /estimates/{estimate_id}:
    get:
      summary: Retrieve an estimate
      operationId: getEstimate
      tags: [Estimates]
      parameters:
        - in: path
          name: estimate_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Estimate details.
    patch:
      summary: Update an estimate
      operationId: updateEstimate
      tags: [Estimates]
      parameters:
        - in: path
          name: estimate_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Estimate updated.
    delete:
      summary: Delete an estimate
      operationId: deleteEstimate
      tags: [Estimates]
      parameters:
        - in: path
          name: estimate_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Estimate deleted.
  /tasks:
    get:
      summary: List tasks
      operationId: listTasks
      tags: [Tasks]
      responses:
        "200":
          description: List of tasks.
    post:
      summary: Create a task
      operationId: createTask
      tags: [Tasks]
      responses:
        "201":
          description: Task created.
  /tasks/{task_id}:
    get:
      summary: Retrieve a task
      operationId: getTask
      tags: [Tasks]
      parameters:
        - in: path
          name: task_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Task details.
    patch:
      summary: Update a task
      operationId: updateTask
      tags: [Tasks]
      parameters:
        - in: path
          name: task_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Task updated.
    delete:
      summary: Delete a task
      operationId: deleteTask
      tags: [Tasks]
      parameters:
        - in: path
          name: task_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Task deleted.
  /roles:
    get:
      summary: List roles
      operationId: listRoles
      tags: [Roles]
      responses:
        "200":
          description: List of roles.
    post:
      summary: Create a role
      operationId: createRole
      tags: [Roles]
      responses:
        "201":
          description: Role created.
  /roles/{role_id}:
    get:
      summary: Retrieve a role
      operationId: getRole
      tags: [Roles]
      parameters:
        - in: path
          name: role_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Role details.
    patch:
      summary: Update a role
      operationId: updateRole
      tags: [Roles]
      parameters:
        - in: path
          name: role_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Role updated.
    delete:
      summary: Delete a role
      operationId: deleteRole
      tags: [Roles]
      parameters:
        - in: path
          name: role_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Role deleted.
  /company:
    get:
      summary: Retrieve company settings
      operationId: getCompany
      tags: [Company]
      responses:
        "200":
          description: Company settings.
    patch:
      summary: Update company settings
      operationId: updateCompany
      tags: [Company]
      responses:
        "200":
          description: Company settings updated.
  /reports/time/clients:
    get:
      summary: Clients time report
      operationId: getClientsTimeReport
      tags: [Reports]
      parameters:
        - in: query
          name: from
          required: true
          schema:
            type: string
            format: date
        - in: query
          name: to
          required: true
          schema:
            type: string
            format: date
      responses:
        "200":
          description: Clients time report.
  /reports/time/projects:
    get:
      summary: Projects time report
      operationId: getProjectsTimeReport
      tags: [Reports]
      parameters:
        - in: query
          name: from
          required: true
          schema:
            type: string
            format: date
        - in: query
          name: to
          required: true
          schema:
            type: string
            format: date
      responses:
        "200":
          description: Projects time report.
  /reports/time/tasks:
    get:
      summary: Tasks time report
      operationId: getTasksTimeReport
      tags: [Reports]
      parameters:
        - in: query
          name: from
          required: true
          schema:
            type: string
            format: date
        - in: query
          name: to
          required: true
          schema:
            type: string
            format: date
      responses:
        "200":
          description: Tasks time report.
  /reports/time/team:
    get:
      summary: Team time report
      operationId: getTeamTimeReport
      tags: [Reports]
      parameters:
        - in: query
          name: from
          required: true
          schema:
            type: string
            format: date
        - in: query
          name: to
          required: true
          schema:
            type: string
            format: date
      responses:
        "200":
          description: Team time report.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        Personal access token or OAuth 2.0 access token passed in the
        Authorization header. The Harvest-Account-Id header (or account_id
        query parameter) is also required.
  parameters:
    HarvestAccountId:
      in: header
      name: Harvest-Account-Id
      required: true
      schema:
        type: string
      description: Harvest account identifier.