This is page 2 of 2. Use http://codebase.md/adrian-dotco/harvest-mcp-server?lines=false&page={x} to view the full context.
# Directory Structure
```
├── .github
│ └── workflows
│ ├── claude-code-review.yml
│ └── claude.yml
├── .gitignore
├── docs
│ └── harvest_api_docs
│ ├── 01_introduction
│ │ ├── 01_overview.md
│ │ ├── 02_postman_collection.md
│ │ ├── 03_code_samples.md
│ │ ├── 04_supported_timezones.md
│ │ ├── 05_supported_currencies.md
│ │ ├── 06_pagination.md
│ │ └── README.md
│ ├── 02_authentication
│ │ ├── 01_authentication.md
│ │ └── README.md
│ ├── 03_clients_api
│ │ ├── 01_clients.md
│ │ ├── 02_client_contacts.md
│ │ └── README.md
│ ├── 04_company
│ │ ├── 01_company.md
│ │ └── README.md
│ ├── 05_invoices
│ │ ├── 01_invoice_item_categories.md
│ │ ├── 02_invoice_messages.md
│ │ ├── 03_invoice_payments.md
│ │ ├── 04_invoices.md
│ │ └── README.md
│ ├── 06_estimates
│ │ ├── 01_estimate_item_categories.md
│ │ ├── 02_estimate_messages.md
│ │ ├── 03_estimates.md
│ │ └── README.md
│ ├── 07_expenses
│ │ ├── expense_categories.md
│ │ └── expenses.md
│ ├── 08_tasks
│ │ └── tasks.md
│ ├── 09_timesheets
│ │ └── time_entries.md
│ ├── 10_projects
│ │ ├── project_task_assignments.md
│ │ ├── project_user_assignments.md
│ │ └── projects.md
│ ├── 11_roles
│ │ └── roles.md
│ ├── 12_users
│ │ ├── billable_rates.md
│ │ ├── cost_rates.md
│ │ ├── project_assignments.md
│ │ ├── teammates.md
│ │ └── users.md
│ ├── 13_reports
│ │ ├── expenses.md
│ │ ├── project_budget.md
│ │ ├── time.md
│ │ └── uninvoiced.md
│ └── README.md
├── LICENSE
├── llms-install.md
├── package-lock.json
├── package.json
├── README.md
├── src
│ ├── index.ts
│ ├── setup.ts
│ └── types
│ └── chrono-node.d.ts
└── tsconfig.json
```
# Files
--------------------------------------------------------------------------------
/docs/harvest_api_docs/10_projects/project_task_assignments.md:
--------------------------------------------------------------------------------
```markdown
Project Task Assignments
Admin or Project Manager permissions required.
The task assignment object⚭
Attribute Type Description
id integer Unique ID for the task assignment.
project object An object containing the id, name, and code of the associated project.
task object An object containing the id and name of the associated task.
is_active boolean Whether the task assignment is active or archived.
billable boolean Whether the task assignment is billable or not. For example: if set to true, all time tracked on this project for the associated task will be marked as billable.
hourly_rate decimal Rate used when the project’s bill_by is Tasks.
budget decimal Budget used when the project’s budget_by is task or task_fees.
created_at datetime Date and time the task assignment was created.
updated_at datetime Date and time the task assignment was last updated.
List all task assignments⚭
Returns a list of your task assignments. The task assignments are returned sorted by creation date, with the most recently created task assignments appearing first.
The response contains an object with a task_assignments property that contains an array of up to per_page task assignments. Each entry in the array is a separate task assignment object. If no more task assignments are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your task assignments.
GET /v2/task_assignments
Parameter Type Description
is_active boolean Pass true to only return active task assignments and false to return inactive task assignments.
updated_since datetime Only return task assignments that have been updated since the given date and time.
page integer DEPRECATED The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
per_page integer The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
This endpoint supports cursor-based pagination and therefore deprecates the page parameter. For more information, visit the pagination guide.
Example Request:
curl "https://api.harvestapp.com/v2/task_assignments" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"task_assignments":[
{
"id":160726647,
"billable":false,
"is_active":true,
"created_at":"2017-08-22T17:36:54Z",
"updated_at":"2017-08-22T17:36:54Z",
"hourly_rate":100.0,
"budget":null,
"project":{
"id":14808188,
"name":"Task Force",
"code":"TF"
},
"task":{
"id":8083369,
"name":"Research"
}
},
{
"id":160726646,
"billable":true,
"is_active":true,
"created_at":"2017-08-22T17:36:54Z",
"updated_at":"2017-08-22T17:36:54Z",
"hourly_rate":100.0,
"budget":null,
"project":{
"id":14808188,
"name":"Task Force",
"code":"TF"
},
"task":{
"id":8083368,
"name":"Project Management"
}
},
{
"id":160726645,
"billable":true,
"is_active":true,
"created_at":"2017-08-22T17:36:54Z",
"updated_at":"2017-08-22T17:36:54Z",
"hourly_rate":100.0,
"budget":null,
"project":{
"id":14808188,
"name":"Task Force",
"code":"TF"
},
"task":{
"id":8083366,
"name":"Programming"
}
},
{
"id":160726644,
"billable":true,
"is_active":true,
"created_at":"2017-08-22T17:36:54Z",
"updated_at":"2017-08-22T17:36:54Z",
"hourly_rate":100.0,
"budget":null,
"project":{
"id":14808188,
"name":"Task Force",
"code":"TF"
},
"task":{
"id":8083365,
"name":"Graphic Design"
}
},
{
"id":155505153,
"billable":false,
"is_active":true,
"created_at":"2017-06-26T21:53:20Z",
"updated_at":"2017-06-26T21:54:31Z",
"hourly_rate":100.0,
"budget":null,
"project":{
"id":14307913,
"name":"Marketing Website",
"code":"MW"
},
"task":{
"id":8083369,
"name":"Research"
}
},
{
"id":155505016,
"billable":false,
"is_active":true,
"created_at":"2017-06-26T21:52:18Z",
"updated_at":"2017-06-26T21:54:06Z",
"hourly_rate":100.0,
"budget":null,
"project":{
"id":14308069,
"name":"Online Store - Phase 1",
"code":"OS1"
},
"task":{
"id":8083369,
"name":"Research"
}
},
{
"id":155505015,
"billable":true,
"is_active":true,
"created_at":"2017-06-26T21:52:18Z",
"updated_at":"2017-06-26T21:52:18Z",
"hourly_rate":100.0,
"budget":null,
"project":{
"id":14308069,
"name":"Online Store - Phase 1",
"code":"OS1"
},
"task":{
"id":8083368,
"name":"Project Management"
}
},
{
"id":155505014,
"billable":true,
"is_active":true,
"created_at":"2017-06-26T21:52:18Z",
"updated_at":"2017-06-26T21:52:18Z",
"hourly_rate":100.0,
"budget":null,
"project":{
"id":14308069,
"name":"Online Store - Phase 1",
"code":"OS1"
},
"task":{
"id":8083366,
"name":"Programming"
}
},
{
"id":155505013,
"billable":true,
"is_active":true,
"created_at":"2017-06-26T21:52:18Z",
"updated_at":"2017-06-26T21:52:18Z",
"hourly_rate":100.0,
"budget":null,
"project":{
"id":14308069,
"name":"Online Store - Phase 1",
"code":"OS1"
},
"task":{
"id":8083365,
"name":"Graphic Design"
}
},
{
"id":155502711,
"billable":true,
"is_active":true,
"created_at":"2017-06-26T21:36:23Z",
"updated_at":"2017-06-26T21:36:23Z",
"hourly_rate":100.0,
"budget":null,
"project":{
"id":14307913,
"name":"Marketing Website",
"code":"MW"
},
"task":{
"id":8083368,
"name":"Project Management"
}
},
{
"id":155502710,
"billable":true,
"is_active":true,
"created_at":"2017-06-26T21:36:23Z",
"updated_at":"2017-06-26T21:36:23Z",
"hourly_rate":100.0,
"budget":null,
"project":{
"id":14307913,
"name":"Marketing Website",
"code":"MW"
},
"task":{
"id":8083366,
"name":"Programming"
}
},
{
"id":155502709,
"billable":true,
"is_active":true,
"created_at":"2017-06-26T21:36:23Z",
"updated_at":"2017-06-26T21:36:23Z",
"hourly_rate":100.0,
"budget":null,
"project":{
"id":14307913,
"name":"Marketing Website",
"code":"MW"
},
"task":{
"id":8083365,
"name":"Graphic Design"
}
}
],
"per_page":2000,
"total_pages":1,
"total_entries":12,
"next_page":null,
"previous_page":null,
"page":1,
"links":{
"first":"https://api.harvestapp.com/v2/task_assignments?page=1&per_page=2000",
"next":null,
"previous":null,
"last":"https://api.harvestapp.com/v2/task_assignments?page=1&per_page=2000"
}
}
List all task assignments for a specific project⚭
Returns a list of your task assignments for the project identified by PROJECT_ID. The task assignments are returned sorted by creation date, with the most recently created task assignments appearing first.
The response contains an object with a task_assignments property that contains an array of up to per_page task assignments. Each entry in the array is a separate task assignment object. If no more task assignments are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your task assignments.
GET /v2/projects/{PROJECT_ID}/task_assignments
Parameter Type Description
is_active boolean Pass true to only return active task assignments and false to return inactive task assignments.
updated_since datetime Only return task assignments that have been updated since the given date and time.
page integer The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
per_page integer The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
Example Request:
curl "https://api.harvestapp.com/v2/projects/14308069/task_assignments" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"task_assignments":[
{
"id":155505016,
"billable":false,
"is_active":true,
"created_at":"2017-06-26T21:52:18Z",
"updated_at":"2017-06-26T21:54:06Z",
"hourly_rate":100.0,
"budget":null,
"project":{
"id":14308069,
"name":"Online Store - Phase 1",
"code":"OS1"
},
"task":{
"id":8083369,
"name":"Research"
}
},
{
"id":155505015,
"billable":true,
"is_active":true,
"created_at":"2017-06-26T21:52:18Z",
"updated_at":"2017-06-26T21:52:18Z",
"hourly_rate":100.0,
"budget":null,
"project":{
"id":14308069,
"name":"Online Store - Phase 1",
"code":"OS1"
},
"task":{
"id":8083368,
"name":"Project Management"
}
},
{
"id":155505014,
"billable":true,
"is_active":true,
"created_at":"2017-06-26T21:52:18Z",
"updated_at":"2017-06-26T21:52:18Z",
"hourly_rate":100.0,
"budget":null,
"project":{
"id":14308069,
"name":"Online Store - Phase 1",
"code":"OS1"
},
"task":{
"id":8083366,
"name":"Programming"
}
},
{
"id":155505013,
"billable":true,
"is_active":true,
"created_at":"2017-06-26T21:52:18Z",
"updated_at":"2017-06-26T21:52:18Z",
"hourly_rate":100.0,
"budget":null,
"project":{
"id":14308069,
"name":"Online Store - Phase 1",
"code":"OS1"
},
"task":{
"id":8083365,
"name":"Graphic Design"
}
}
],
"per_page":2000,
"total_pages":1,
"total_entries":4,
"next_page":null,
"previous_page":null,
"page":1,
"links":{
"first":"https://api.harvestapp.com/v2/projects/14308069/task_assignments?page=1&per_page=2000",
"next":null,
"previous":null,
"last":"https://api.harvestapp.com/v2/projects/14308069/task_assignments?page=1&per_page=2000"
}
}
Retrieve a task assignment⚭
Retrieves the task assignment with the given ID. Returns a task assignment object and a 200 OK response code if a valid identifier was provided.
GET /v2/projects/{PROJECT_ID}/task_assignments/{TASK_ASSIGNMENT_ID}
Example Request:
curl "https://api.harvestapp.com/v2/projects/14308069/task_assignments/155505016" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"id":155505016,
"billable":false,
"is_active":true,
"created_at":"2017-06-26T21:52:18Z",
"updated_at":"2017-06-26T21:54:06Z",
"hourly_rate":100.0,
"budget":null,
"project":{
"id":14308069,
"name":"Online Store - Phase 1",
"code":"OS1"
},
"task":{
"id":8083369,
"name":"Research"
}
}
Create a task assignment⚭
Creates a new task assignment object. Returns a task assignment object and a 201 Created response code if the call succeeded.
POST /v2/projects/{PROJECT_ID}/task_assignments
Parameter Type Required Description
task_id integer required The ID of the task to associate with the project.
is_active boolean optional Whether the task assignment is active or archived. Defaults to true.
billable boolean optional Whether the task assignment is billable or not. Defaults to false.
hourly_rate decimal optional Rate used when the project’s bill_by is Tasks. Defaults to null when billing by task hourly rate, otherwise 0.
budget decimal optional Budget used when the project’s budget_by is task or task_fees.
Example Request:
curl "https://api.harvestapp.com/v2/projects/14308069/task_assignments" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])" \
-X POST \
-H "Content-Type: application/json" \
-d '{"task_id":8083800,"is_active":true,"billable":true,"hourly_rate":75.50}'
Example Response:
{
"id":155506339,
"billable":true,
"is_active":true,
"created_at":"2017-06-26T22:10:43Z",
"updated_at":"2017-06-26T22:10:43Z",
"hourly_rate":75.5,
"budget":null,
"project":{
"id":14308069,
"name":"Online Store - Phase 1",
"code":"OS1"
},
"task":{
"id":8083800,
"name":"Business Development"
}
}
Update a task assignment⚭
Updates the specific task assignment by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns a task assignment object and a 200 OK response code if the call succeeded.
PATCH /v2/projects/{PROJECT_ID}/task_assignments/{TASK_ASSIGNMENT_ID}
Parameter Type Description
is_active boolean Whether the task assignment is active or archived.
billable boolean Whether the task assignment is billable or not.
hourly_rate decimal Rate used when the project’s bill_by is Tasks.
budget decimal Budget used when the project’s budget_by is task or task_fees.
Example Request:
curl "https://api.harvestapp.com/v2/projects/14308069/task_assignments/155506339" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])" \
-X PATCH \
-H "Content-Type: application/json" \
-d '{"budget":120}'
Example Response:
{
"id":155506339,
"billable":true,
"is_active":true,
"created_at":"2017-06-26T22:10:43Z",
"updated_at":"2017-06-26T22:11:27Z",
"hourly_rate":75.5,
"budget":120.0,
"project":{
"id":14308069,
"name":"Online Store - Phase 1",
"code":"OS1"
},
"task":{
"id":8083800,
"name":"Business Development"
}
}
Delete a task assignment⚭
Delete a task assignment. Deleting a task assignment is only possible if it has no time entries associated with it. Returns a 200 OK response code if the call succeeded.
DELETE /v2/projects/{PROJECT_ID}/task_assignments/{TASK_ASSIGNMENT_ID}
Example Request:
curl "https://api.harvestapp.com/v2/projects/14308069/task_assignments/155506339" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])" \
-X DELETE
```
--------------------------------------------------------------------------------
/src/index.ts:
--------------------------------------------------------------------------------
```typescript
#!/usr/bin/env node
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import {
CallToolRequestSchema,
ErrorCode,
ListToolsRequestSchema,
McpError,
} from '@modelcontextprotocol/sdk/types.js';
import axios from 'axios';
import * as chrono from 'chrono-node';
// Time report response types
interface TimeReportResult {
client_id?: number;
client_name?: string;
project_id?: number;
project_name?: string;
task_id?: number;
task_name?: string;
user_id?: number;
user_name?: string;
weekly_capacity?: number;
avatar_url?: string;
is_contractor?: boolean;
total_hours: number;
billable_hours: number;
currency: string;
billable_amount: number;
}
interface TimeReportResponse {
results: TimeReportResult[];
per_page: number;
total_pages: number;
total_entries: number;
next_page: number | null;
previous_page: number | null;
page: number;
}
const HARVEST_ACCESS_TOKEN = process.env.HARVEST_ACCESS_TOKEN;
const HARVEST_ACCOUNT_ID = process.env.HARVEST_ACCOUNT_ID;
const STANDARD_WORK_DAY_HOURS = parseFloat(process.env.STANDARD_WORK_DAY_HOURS || '7.5');
const TIMEZONE = process.env.TIMEZONE || 'Australia/Perth';
if (!HARVEST_ACCESS_TOKEN || !HARVEST_ACCOUNT_ID) {
throw new Error('HARVEST_ACCESS_TOKEN and HARVEST_ACCOUNT_ID environment variables are required');
}
// Special patterns for leave requests
const LEAVE_PATTERNS = {
sick: {
triggers: ['sick', 'ill', 'unwell'],
project: '[LV] Leave',
task: "Person (Sick/Carer's) Leave",
},
annual: {
triggers: ['annual leave', 'vacation', 'holiday', 'time off'],
project: '[LV] Leave',
task: 'Annual Leave',
}
};
class HarvestServer {
private server: Server;
private axiosInstance;
constructor() {
this.server = new Server(
{
name: 'harvest-server',
version: '0.1.0',
},
{
capabilities: {
tools: {},
},
}
);
this.axiosInstance = axios.create({
baseURL: 'https://api.harvestapp.com/v2',
headers: {
'Authorization': `Bearer ${HARVEST_ACCESS_TOKEN}`,
'Harvest-Account-Id': HARVEST_ACCOUNT_ID,
'User-Agent': 'Harvest MCP Server ([email protected])',
},
});
this.setupToolHandlers();
this.server.onerror = (error) => console.error('[MCP Error]', error);
process.on('SIGINT', async () => {
await this.server.close();
process.exit(0);
});
}
private isLeaveRequest(text: string): { isLeave: boolean; type?: keyof typeof LEAVE_PATTERNS } {
const lowercaseText = text.toLowerCase();
for (const [type, pattern] of Object.entries(LEAVE_PATTERNS)) {
if (pattern.triggers.some(trigger => lowercaseText.includes(trigger))) {
return { isLeave: true, type: type as keyof typeof LEAVE_PATTERNS };
}
}
return { isLeave: false };
}
private parseDateRange(text: string): { from: string; to: string } {
const lowercaseText = text.toLowerCase();
const now = new Date(new Date().toLocaleString('en-US', { timeZone: TIMEZONE }));
// Handle common time ranges
if (lowercaseText.includes('last month')) {
const from = new Date(now.getFullYear(), now.getMonth() - 1, 1);
const to = new Date(now.getFullYear(), now.getMonth(), 0);
return {
from: from.toISOString().split('T')[0],
to: to.toISOString().split('T')[0]
};
}
if (lowercaseText.includes('this month')) {
const from = new Date(now.getFullYear(), now.getMonth(), 1);
const to = now;
return {
from: from.toISOString().split('T')[0],
to: to.toISOString().split('T')[0]
};
}
if (lowercaseText.includes('this week')) {
const from = new Date(now);
from.setDate(now.getDate() - now.getDay());
return {
from: from.toISOString().split('T')[0],
to: now.toISOString().split('T')[0]
};
}
if (lowercaseText.includes('last week')) {
const from = new Date(now);
from.setDate(now.getDate() - now.getDay() - 7);
const to = new Date(from);
to.setDate(from.getDate() + 6);
return {
from: from.toISOString().split('T')[0],
to: to.toISOString().split('T')[0]
};
}
// Default to parsing with chrono
const dates = chrono.parse(text);
if (dates.length === 0) {
throw new McpError(ErrorCode.InvalidParams, 'Could not parse date range from input');
}
return {
from: dates[0].start.date().toISOString().split('T')[0],
to: (dates[0].end?.date() || dates[0].start.date()).toISOString().split('T')[0]
};
}
private async parseTimeEntry(text: string) {
const lowercaseText = text.toLowerCase();
const now = new Date(new Date().toLocaleString('en-US', { timeZone: TIMEZONE }));
// Check if this is a leave request
const leaveCheck = this.isLeaveRequest(text);
if (leaveCheck.isLeave && leaveCheck.type) {
// For leave requests, use the full work day
return {
spent_date: now.toISOString().split('T')[0],
hours: STANDARD_WORK_DAY_HOURS,
isLeave: true,
leaveType: leaveCheck.type
};
}
// For regular time entries
let date: Date;
if (lowercaseText.includes('today')) {
date = now;
} else {
const parsed = chrono.parseDate(text);
if (!parsed) {
throw new McpError(ErrorCode.InvalidParams, 'Could not parse date from input');
}
date = parsed;
}
// Extract hours/minutes
const durationMatch = text.match(/(\d+)\s*(hour|hr|h|minute|min|m)s?/i);
if (!durationMatch) {
throw new McpError(ErrorCode.InvalidParams, 'Could not parse duration from input');
}
const amount = parseInt(durationMatch[1]);
const unit = durationMatch[2].toLowerCase();
const hours = unit.startsWith('h') ? amount : amount / 60;
return {
spent_date: date.toISOString().split('T')[0],
hours,
isLeave: false
};
}
private async findProject(text: string, isLeave: boolean = false, leaveType?: keyof typeof LEAVE_PATTERNS): Promise<number> {
const response = await this.axiosInstance.get('/projects');
const projects = response.data.projects;
if (isLeave && leaveType) {
// For leave requests, look for the specific leave project
const leaveProject = projects.find((p: { name: string; id: number }) =>
p.name === LEAVE_PATTERNS[leaveType].project
);
if (leaveProject) {
return leaveProject.id;
}
}
// For regular entries or if leave project not found
const projectMatch = projects.find((p: { name: string; id: number }) =>
text.toLowerCase().includes(p.name.toLowerCase())
);
if (!projectMatch) {
throw new McpError(ErrorCode.InvalidParams, 'Could not find matching project');
}
return projectMatch.id;
}
private async findTask(projectId: number, text: string, isLeave: boolean = false, leaveType?: keyof typeof LEAVE_PATTERNS): Promise<number> {
const response = await this.axiosInstance.get(`/projects/${projectId}/task_assignments`);
const tasks = response.data.task_assignments;
if (isLeave && leaveType) {
// For leave requests, look for the specific leave task
const leaveTask = tasks.find((t: { task: { name: string; id: number } }) =>
t.task.name === LEAVE_PATTERNS[leaveType].task
);
if (leaveTask) {
return leaveTask.task.id;
}
}
// For regular entries or if leave task not found
const taskMatch = tasks.find((t: { task: { name: string; id: number } }) =>
text.toLowerCase().includes(t.task.name.toLowerCase())
);
if (!taskMatch) {
// Default to first task if no match found
return tasks[0].task.id;
}
return taskMatch.task.id;
}
private setupToolHandlers() {
this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: [
{
name: 'log_time',
description: 'Log time entry using natural language',
inputSchema: {
type: 'object',
properties: {
text: {
type: 'string',
description: 'Natural language time entry (e.g. "2 hours on Project X doing development work yesterday")',
},
},
required: ['text'],
},
},
{
name: 'list_projects',
description: 'List available Harvest projects',
inputSchema: {
type: 'object',
properties: {},
},
},
{
name: 'list_tasks',
description: 'List available tasks for a project',
inputSchema: {
type: 'object',
properties: {
project_id: {
type: 'number',
description: 'Project ID',
},
},
required: ['project_id'],
},
},
{
name: 'list_entries',
description: 'List recent time entries',
inputSchema: {
type: 'object',
properties: {
from: {
type: 'string',
description: 'Start date (YYYY-MM-DD)',
},
to: {
type: 'string',
description: 'End date (YYYY-MM-DD)',
},
},
},
},
{
name: 'get_time_report',
description: 'Get time reports using natural language',
inputSchema: {
type: 'object',
properties: {
text: {
type: 'string',
description: 'Natural language query (e.g., "Show time report for last month", "Get time summary for Project X")',
},
},
required: ['text'],
},
},
],
}));
this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
switch (request.params.name) {
case 'log_time': {
const { text } = request.params.arguments as { text: string };
try {
// Parse time entry details
const { spent_date, hours, isLeave, leaveType } = await this.parseTimeEntry(text);
// Find matching project
const project_id = await this.findProject(text, isLeave, leaveType);
// Find matching task
const task_id = await this.findTask(project_id, text, isLeave, leaveType);
// Create time entry
const response = await this.axiosInstance.post('/time_entries', {
project_id,
task_id,
spent_date,
hours,
notes: text,
});
return {
content: [
{
type: 'text',
text: JSON.stringify(response.data, null, 2),
},
],
};
} catch (error) {
if (error instanceof McpError) {
throw error;
}
if (axios.isAxiosError(error)) {
throw new McpError(
ErrorCode.InternalError,
`Harvest API error: ${error.response?.data?.message ?? error.message}`
);
}
throw error;
}
}
case 'list_projects': {
const response = await this.axiosInstance.get('/projects');
return {
content: [
{
type: 'text',
text: JSON.stringify(response.data.projects.map((p: { id: number; name: string; code: string; is_active: boolean }) => ({
id: p.id,
name: p.name,
code: p.code,
is_active: p.is_active,
})), null, 2),
},
],
};
}
case 'list_tasks': {
const { project_id } = request.params.arguments as { project_id: number };
const response = await this.axiosInstance.get(`/projects/${project_id}/task_assignments`);
return {
content: [
{
type: 'text',
text: JSON.stringify(response.data.task_assignments.map((t: { task: { id: number; name: string } }) => ({
id: t.task.id,
name: t.task.name,
})), null, 2),
},
],
};
}
case 'list_entries': {
const { from, to } = request.params.arguments as { from?: string; to?: string };
const params: Record<string, string> = {};
if (from) params.from = from;
if (to) params.to = to;
const response = await this.axiosInstance.get('/time_entries', { params });
return {
content: [
{
type: 'text',
text: JSON.stringify(response.data.time_entries.map((e: { id: number; spent_date: string; hours: number; notes: string; project: { name: string }; task: { name: string } }) => ({
id: e.id,
spent_date: e.spent_date,
hours: e.hours,
notes: e.notes,
project: e.project.name,
task: e.task.name,
})), null, 2),
},
],
};
}
case 'get_time_report': {
const { text } = request.params.arguments as { text: string };
try {
const { from, to } = this.parseDateRange(text);
const lowercaseText = text.toLowerCase();
let endpoint = '/reports/time/projects'; // default to project report
if (lowercaseText.includes('by client') || lowercaseText.includes('for client')) {
endpoint = '/reports/time/clients';
} else if (lowercaseText.includes('by task') || lowercaseText.includes('tasks')) {
endpoint = '/reports/time/tasks';
} else if (lowercaseText.includes('by team') || lowercaseText.includes('by user')) {
endpoint = '/reports/time/team';
}
const response = await this.axiosInstance.get<TimeReportResponse>(endpoint, {
params: { from, to }
});
return {
content: [
{
type: 'text',
text: JSON.stringify(response.data, null, 2),
},
],
};
} catch (error) {
if (error instanceof McpError) {
throw error;
}
if (axios.isAxiosError(error)) {
throw new McpError(
ErrorCode.InternalError,
`Harvest API error: ${error.response?.data?.message ?? error.message}`
);
}
throw error;
}
}
default:
throw new McpError(
ErrorCode.MethodNotFound,
`Unknown tool: ${request.params.name}`
);
}
});
}
async run() {
const transport = new StdioServerTransport();
await this.server.connect(transport);
console.error('Harvest MCP server running on stdio');
}
}
const server = new HarvestServer();
server.run().catch(console.error);
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/12_users/users.md:
--------------------------------------------------------------------------------
```markdown
Users
The user object⚭
Attribute Type Description
id integer Unique ID for the user.
first_name string The first name of the user.
last_name string The last name of the user.
email string The email address of the user.
telephone string The user’s telephone number.
timezone string The user’s timezone.
has_access_to_all_future_projects boolean Whether the user should be automatically added to future projects.
is_contractor boolean Whether the user is a contractor or an employee.
is_active boolean Whether the user is active or archived.
weekly_capacity integer The number of hours per week this person is available to work in seconds, in half hour increments. For example, if a person’s capacity is 35 hours, the API will return 126000 seconds.
default_hourly_rate decimal The billable rate to use for this user when they are added to a project.
cost_rate decimal The cost rate to use for this user when calculating a project’s costs vs billable amount.
roles array of strings Descriptive names of the business roles assigned to this person. They can be used for filtering reports, and have no effect in their permissions in Harvest.
access_roles array of strings Access role(s) that determine the user’s permissions in Harvest. Possible values: administrator, manager or member. Users with the manager role can additionally be granted one or more of these roles: project_creator, billable_rates_manager, managed_projects_invoice_drafter, managed_projects_invoice_manager, client_and_task_manager, time_and_expenses_manager, estimates_manager.
avatar_url string The URL to the user’s avatar image.
created_at datetime Date and time the user was created.
updated_at datetime Date and time the user was last updated.
Required permissions⚭
You must be an Administrator or Manager with assigned teammates in order to interact with the /v2/users endpoint, except when retrieving the currently authenticated user. Managers cannot edit emails, roles, or permissions, nor can they archive, restore, or delete assigned temmates. Managers with permission to see billable rates will have access to their teammates’ default hourly rates. Insufficient permissions will result in a 403 Forbidden status code.
List all users⚭
Returns a list of your users. The users are returned sorted by creation date, with the most recently created users appearing first.
The response contains an object with a users property that contains an array of up to per_page users. Each entry in the array is a separate user object. If no more users are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your users.
GET /v2/users
Parameter Type Description
is_active boolean Pass true to only return active users and false to return inactive users.
updated_since datetime Only return users that have been updated since the given date and time.
page integer DEPRECATED The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
per_page integer The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
This endpoint supports cursor-based pagination and therefore deprecates the page parameter. For more information, visit the pagination guide.
Example requests:⚭
Curl
Postman
curl "https://api.harvestapp.com/v2/users" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Copy to Clipboard
Example response:
{
"users":[
{
"id":3230547,
"first_name":"Jim",
"last_name":"Allen",
"email":"[email protected]",
"telephone":"",
"timezone":"Mountain Time (US & Canada)",
"has_access_to_all_future_projects":false,
"is_contractor":false,
"is_active":true,
"created_at":"2020-05-01T22:34:41Z",
"updated_at":"2020-05-01T22:34:52Z",
"weekly_capacity":126000,
"default_hourly_rate":100.0,
"cost_rate":50.0,
"roles":["Developer"],
"access_roles": ["member"],
"avatar_url":"https://cache.harvestapp.com/assets/profile_images/abraj_albait_towers.png?1498516481"
},
{
"id":1782959,
"first_name":"Kim",
"last_name":"Allen",
"email":"[email protected]",
"telephone":"",
"timezone":"Eastern Time (US & Canada)",
"has_access_to_all_future_projects":true,
"is_contractor":false,
"is_active":true,
"created_at":"2020-05-01T22:15:45Z",
"updated_at":"2020-05-01T22:32:52Z",
"weekly_capacity":126000,
"default_hourly_rate":100.0,
"cost_rate":50.0,
"roles":["Designer"],
"access_roles": ["member"],
"avatar_url":"https://cache.harvestapp.com/assets/profile_images/cornell_clock_tower.png?1498515345"
},
{
"id":1782884,
"first_name":"Bob",
"last_name":"Powell",
"email":"[email protected]",
"telephone":"",
"timezone":"Mountain Time (US & Canada)",
"has_access_to_all_future_projects":false,
"is_contractor":false,
"is_active":true,
"created_at":"2020-05-01T20:41:00Z",
"updated_at":"2020-05-01T20:42:25Z",
"weekly_capacity":126000,
"default_hourly_rate":100.0,
"cost_rate":75.0,
"roles":["Founder", "CEO"],
"access_roles": ["administrator"],
"avatar_url":"https://cache.harvestapp.com/assets/profile_images/allen_bradley_clock_tower.png?1498509661"
}
],
"per_page":2000,
"total_pages":1,
"total_entries":3,
"next_page":null,
"previous_page":null,
"page":1,
"links":{
"first":"https://api.harvestapp.com/v2/users?page=1&per_page=2000",
"next":null,
"previous":null,
"last":"https://api.harvestapp.com/v2/users?page=1&per_page=2000"
}
}
Retrieve the currently authenticated user⚭
Retrieves the currently authenticated user. Returns a user object and a 200 OK response code.
GET /v2/users/me
Example requests:⚭
Curl
Postman
curl "https://api.harvestapp.com/v2/users/me" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Copy to Clipboard
Example response:⚭
{
"id":1782884,
"first_name":"Bob",
"last_name":"Powell",
"email":"[email protected]",
"telephone":"",
"timezone":"Mountain Time (US & Canada)",
"has_access_to_all_future_projects":false,
"is_contractor":false,
"is_active":true,
"created_at":"2020-05-01T20:41:00Z",
"updated_at":"2020-05-01T20:42:25Z",
"weekly_capacity":126000,
"default_hourly_rate":100.0,
"cost_rate":75.0,
"roles":["Founder", "CEO"],
"access_roles": ["administrator"],
"avatar_url":"https://cache.harvestapp.com/assets/profile_images/allen_bradley_clock_tower.png?1498509661"
}
Retrieve a user⚭
Retrieves the user with the given ID. Returns a user object and a 200 OK response code if a valid identifier was provided.
GET /v2/users/{USER_ID}
Example requests:⚭
Curl
Postman
curl "https://api.harvestapp.com/v2/users/3230547" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Copy to Clipboard
Example response:⚭
{
"id":3230547,
"first_name":"Jim",
"last_name":"Allen",
"email":"[email protected]",
"telephone":"",
"timezone":"Mountain Time (US & Canada)",
"has_access_to_all_future_projects":false,
"is_contractor":false,
"is_active":true,
"created_at":"2020-05-01T22:34:41Z",
"updated_at":"2020-05-01T22:34:52Z",
"weekly_capacity":126000,
"default_hourly_rate":100.0,
"cost_rate":50.0,
"roles":["Developer"],
"access_roles": ["member"],
"avatar_url":"https://cache.harvestapp.com/assets/profile_images/abraj_albait_towers.png?1498516481"
}
Create a user⚭
Creates a new user object and sends an invitation email to the address specified in the email parameter. Returns a user object and a 201 Created response code if the call succeeded.
POST /v2/users
Parameter Type Required Description
first_name string required The first name of the user.
last_name string required The last name of the user.
email string required The email address of the user.
timezone string optional The user’s timezone. Defaults to the company’s timezone. See a list of supported time zones.
has_access_to_all_future_projects boolean optional Whether the user should be automatically added to future projects. Defaults to false.
is_contractor boolean optional Whether the user is a contractor or an employee. Defaults to false.
is_active boolean optional Whether the user is active or archived. Defaults to true.
weekly_capacity integer optional The number of hours per week this person is available to work in seconds. Defaults to 126000 seconds (35 hours).
default_hourly_rate decimal optional The billable rate to use for this user when they are added to a project. Defaults to 0.
cost_rate decimal optional The cost rate to use for this user when calculating a project’s costs vs billable amount. Defaults to 0.
roles array of strings optional Descriptive names of the business roles assigned to this person. They can be used for filtering reports, and have no effect in their permissions in Harvest.
access_roles array of strings optional Access role(s) that determine the user’s permissions in Harvest. Possible values: administrator, manager or member. Users with the manager role can additionally be granted one or more of these roles: project_creator, billable_rates_manager, managed_projects_invoice_drafter, managed_projects_invoice_manager, client_and_task_manager, time_and_expenses_manager, estimates_manager.
Access Roles⚭
To set permissions for a user, use the access_roles parameter. A user must be one of the following: member, manager, or administrator.
If no access_role parameter is sent, a user defaults to ‘member’.
If a user is a manager they can have other access roles set for more specific permissions in Harvest.
The role of people_manager is determined by whether the user has teammates assigned to them, which can be added through the teammates api. If you downgrade a People Manager’s access role to Member, they will no longer be a People Manager and their assigned teammates will be removed.
Access Role Name Description
administrator For users who need the most control to manage your account. Administrators can see and do everything.
manager For users who need more access to people and project reports. Managers can track time and expenses, and edit, approve, and run reports for all time and expenses tracked to selected projects and people.
member For users who just need to track time and expenses.
Additional Manager Access Role Names Description
project_creator User can create projects, and edit projects that they manage.
billable_rates_manager User can see billable rates and amounts for projects and people they manage.
managed_projects_invoice_drafter User can create and edit draft invoices for projects they manage.
managed_projects_invoice_manager User can send and fully manage all invoices for projects they manage (record payments, edit non-drafts, send reminders and thank-yous, delete, etc).
client_and_task_manager User can create and edit all clients and tasks on the account.
time_and_expenses_manager User can create and edit time and expenses for people and projects they manage.
estimates_manager User can create and edit all estimates on the account.
Learn more about team permissions
Example requests:⚭
Curl
Postman
curl "https://api.harvestapp.com/v2/users" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])" \
-X POST \
-H "Content-Type: application/json" \
-d '{"email":"[email protected]","first_name":"George","last_name":"Frank","access_roles":["manager","project_creator","time_and_expenses_manager"]}'
Copy to Clipboard
Example response:⚭
{
"id": 3,
"first_name": "George",
"last_name": "Frank",
"email": "[email protected]",
"telephone": "",
"timezone": "Eastern Time (US & Canada)",
"has_access_to_all_future_projects": false,
"is_contractor": false,
"is_active": true,
"weekly_capacity":126000,
"default_hourly_rate": 0,
"cost_rate": 0,
"roles": [],
"access_roles": [
"manager",
"project_creator",
"time_and_expenses_manager"
],
"avatar_url": "https://{ACCOUNT_SUBDOMAIN}.harvestapp.com/assets/profile_images/big_ben.png?1485372046",
"created_at": "2020-01-25T19:20:46Z",
"updated_at": "2020-01-25T19:20:57Z"
}
Update a user⚭
Updates the specific user by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns a user object and a 200 OK response code if the call succeeded.
PATCH /v2/users/{USER_ID}
Parameter Type Description
first_name string The first name of the user. Can’t be updated if the user is inactive.
last_name string The last name of the user. Can’t be updated if the user is inactive.
email string The email address of the user. Can’t be updated if the user is inactive.
timezone string The user’s timezone. Defaults to the company’s timezone. See a list of supported time zones.
has_access_to_all_future_projects boolean Whether the user should be automatically added to future projects.
is_contractor boolean Whether the user is a contractor or an employee.
is_active boolean Whether the user is active or archived.
weekly_capacity integer The number of hours per week this person is available to work in seconds.
roles array of strings Descriptive names of the business roles assigned to this person. They can be used for filtering reports, and have no effect in their permissions in Harvest.
access_roles array of strings Access role(s) that determine the user’s permissions in Harvest. Possible values: administrator, manager or member. Users with the manager role can additionally be granted one or more of these roles: project_creator, billable_rates_manager, managed_projects_invoice_drafter, managed_projects_invoice_manager, client_and_task_manager, time_and_expenses_manager, estimates_manager.
Example requests:⚭
Curl
Postman
curl "https://api.harvestapp.com/v2/users/3237198" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])" \
-X PATCH \
-H "Content-Type: application/json" \
-d '{"roles":["Product Team"], "access_roles":["manager", "time_and_expenses_manager", "billable_rates_manager"]}'
Copy to Clipboard
Example response:⚭
{
"id": 3237198,
"first_name": "Gary",
"last_name": "Brookes",
"email": "[email protected]",
"telephone": "",
"timezone": "Eastern Time (US & Canada)",
"has_access_to_all_future_projects": true,
"is_contractor": false,
"is_active": true,
"weekly_capacity":126000,
"default_hourly_rate": 120,
"cost_rate": 50,
"roles": ["Product Team"],
"access_roles": [
"manager",
"time_and_expenses_manager",
"billable_rates_manager"
],
"avatar_url": "https://{ACCOUNT_SUBDOMAIN}.harvestapp.com/assets/profile_images/big_ben.png?1485372046",
"created_at": "2018-01-01T19:20:46Z",
"updated_at": "2019-01-25T19:20:57Z"
}
Archive a user⚭
Archives a specific user by setting the value of is_active to false. To make a user active again, simply set is_active to true again. Returns the updated user object and a 200 OK response code if the call succeeded.
PATCH /v2/users/{USER_ID}
Example requests:⚭
Curl
Postman
curl "https://api.harvestapp.com/v2/users/3226125" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])" \
-X PATCH \
-H "Content-Type: application/json" \
-d '{"is_active":false}'
Copy to Clipboard
Example response:⚭
{
"id": 3226125,
"first_name": "Rachel",
"last_name": "Halliday",
"email": "[email protected]",
"telephone": "",
"timezone": "Eastern Time (US & Canada)",
"has_access_to_all_future_projects": true,
"is_contractor": false,
"is_active": false,
"weekly_capacity":126000,
"default_hourly_rate": 120,
"cost_rate": 50,
"roles": ["Developer"],
"access_roles": ["member"],
"avatar_url": "https://{ACCOUNT_SUBDOMAIN}.harvestapp.com/assets/profile_images/big_ben.png?1485372046",
"created_at": "2018-01-01T19:20:46Z",
"updated_at": "2019-01-25T19:20:57Z"
}
Delete a user⚭
Delete a user. Deleting a user is only possible if they have no time entries or expenses associated with them. Returns a 200 OK response code if the call succeeded.
DELETE /v2/users/{USER_ID}
Example requests:⚭
Curl
Postman
curl "https://api.harvestapp.com/v2/users/3237198" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])" \
-X DELETE
Copy to Clipboard
```
--------------------------------------------------------------------------------
/docs/harvest_api_docs/09_timesheets/time_entries.md:
--------------------------------------------------------------------------------
```markdown
Time Entries
The time entry object⚭
Attribute Type Description
id bigint Unique ID for the time entry.
spent_date date Date of the time entry.
user object An object containing the id and name of the associated user.
user_assignment object A user assignment object of the associated user.
client object An object containing the id and name of the associated client.
project object An object containing the id and name of the associated project.
task object An object containing the id and name of the associated task.
task_assignment object A task assignment object of the associated task.
external_reference object An object containing the id, group_id, account_id, permalink, service, and service_icon_url of the associated external reference.
invoice object Once the time entry has been invoiced, this field will include the associated invoice’s id and number.
hours decimal Number of (decimal time) hours tracked in this time entry.
hours_without_timer decimal Number of (decimal time) hours already tracked in this time entry, before the timer was last started.
rounded_hours decimal Number of (decimal time) hours tracked in this time entry used in summary reports and invoices. This value is rounded according to the Time Rounding setting in your Preferences.
notes string Notes attached to the time entry.
is_locked boolean Whether or not the time entry has been locked.
locked_reason string Why the time entry has been locked.
is_closed boolean Whether or not the time entry has been approved via Timesheet Approval.
is_billed boolean Whether or not the time entry has been marked as invoiced.
timer_started_at datetime Date and time the running timer was started (if tracking by duration). Use the ISO 8601 Format. Returns null for stopped timers.
started_time time Time the time entry was started (if tracking by start/end times).
ended_time time Time the time entry was ended (if tracking by start/end times).
is_running boolean Whether or not the time entry is currently running.
billable boolean Whether or not the time entry is billable.
budgeted boolean Whether or not the time entry counts towards the project budget.
billable_rate decimal The billable rate for the time entry.
cost_rate decimal The cost rate for the time entry.
created_at datetime Date and time the time entry was created. Use the ISO 8601 Format.
updated_at datetime Date and time the time entry was last updated. Use the ISO 8601 Format.
Required permissions⚭
Administrators can see all time entries for the account.
Managers can see time entries for themselves, assigned teammates, and time tracked to projects they manage. Additionally, Managers with permission to edit assigned teammates’ time entries can create, edit, and destroy time entries on their behalf.
Members can only see their own tracked time.
List all time entries⚭
Returns a list of time entries. The time entries are returned sorted by spent_date date. At this time, the sort option can’t be customized.
The response contains an object with a time_entries property that contains an array of up to per_page time entries. Each entry in the array is a separate time entry object. If no more time entries are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your time entries.
GET /v2/time_entries
Parameter Type Description
user_id integer Only return time entries belonging to the user with the given ID.
client_id integer Only return time entries belonging to the client with the given ID.
project_id integer Only return time entries belonging to the project with the given ID.
task_id integer Only return time entries belonging to the task with the given ID.
external_reference_id string Only return time entries with the given external_reference ID.
is_billed boolean Pass true to only return time entries that have been invoiced and false to return time entries that have not been invoiced.
is_running boolean Pass true to only return running time entries and false to return non-running time entries.
updated_since datetime Only return time entries that have been updated since the given date and time. Use the ISO 8601 Format.
from date Only return time entries with a spent_date on or after the given date.
to date Only return time entries with a spent_date on or before the given date.
page integer The page number to use in pagination. For instance, if you make a list request and receive 2000 records, your subsequent call can include page=2 to retrieve the next page of the list. (Default: 1)
per_page integer The number of records to return per page. Can range between 1 and 2000. (Default: 2000)
Example Request:
curl "<https://api.harvestapp.com/v2/time_entries>" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp (<[email protected]>)"
Example Response:
{
"time_entries":[
{
"id":636709355,
"spent_date":"2017-03-02",
"user":{
"id":1782959,
"name":"Kim Allen"
},
"client":{
"id":5735774,
"name":"ABC Corp"
},
"project":{
"id":14307913,
"name":"Marketing Website"
},
"task":{
"id":8083365,
"name":"Graphic Design"
},
"user_assignment":{
"id":125068553,
"is_project_manager":true,
"is_active":true,
"budget":null,
"created_at":"2017-06-26T22:32:52Z",
"updated_at":"2017-06-26T22:32:52Z",
"hourly_rate":100.0
},
"task_assignment":{
"id":155502709,
"billable":true,
"is_active":true,
"created_at":"2017-06-26T21:36:23Z",
"updated_at":"2017-06-26T21:36:23Z",
"hourly_rate":100.0,
"budget":null
},
"hours":2.11,
"hours_without_timer":2.11,
"rounded_hours": 2.25,
"notes":"Adding CSS styling",
"created_at":"2017-06-27T15:50:15Z",
"updated_at":"2017-06-27T16:47:14Z",
"is_locked":true,
"locked_reason":"Item Approved and Locked for this Time Period",
"is_closed":true,
"is_billed":false,
"timer_started_at":null,
"started_time":"3:00pm",
"ended_time":"5:00pm",
"is_running":false,
"invoice":null,
"external_reference":null,
"billable":true,
"budgeted":true,
"billable_rate":100.0,
"cost_rate":50.0
},
{
"id":636708723,
"spent_date":"2017-03-01",
"user":{
"id":1782959,
"name":"Kim Allen"
},
"client":{
"id":5735776,
"name":"123 Industries"
},
"project":{
"id":14308069,
"name":"Online Store - Phase 1"
},
"task":{
"id":8083366,
"name":"Programming"
},
"user_assignment":{
"id":125068554,
"is_project_manager":true,
"is_active":true,
"budget":null,
"created_at":"2017-06-26T22:32:52Z",
"updated_at":"2017-06-26T22:32:52Z",
"hourly_rate":100.0
},
"task_assignment":{
"id":155505014,
"billable":true,
"is_active":true,
"created_at":"2017-06-26T21:52:18Z",
"updated_at":"2017-06-26T21:52:18Z",
"hourly_rate":100.0,
"budget":null
},
"hours":1.35,
"hours_without_timer":1.35,
"rounded_hours":1.5,
"notes":"Importing products",
"created_at":"2017-06-27T15:49:28Z",
"updated_at":"2017-06-27T16:47:14Z",
"is_locked":true,
"locked_reason":"Item Invoiced and Approved and Locked for this Time Period",
"is_closed":true,
"is_billed":true,
"timer_started_at":null,
"started_time":"1:00pm",
"ended_time":"2:00pm",
"is_running":false,
"invoice":{
"id":13150403,
"number":"1001"
},
"external_reference":null,
"billable":true,
"budgeted":true,
"billable_rate":100.0,
"cost_rate":50.0
},
{
"id":636708574,
"spent_date":"2017-03-01",
"user":{
"id":1782959,
"name":"Kim Allen"
},
"client":{
"id":5735776,
"name":"123 Industries"
},
"project":{
"id":14308069,
"name":"Online Store - Phase 1"
},
"task":{
"id":8083369,
"name":"Research"
},
"user_assignment":{
"id":125068554,
"is_project_manager":true,
"is_active":true,
"budget":null,
"created_at":"2017-06-26T22:32:52Z",
"updated_at":"2017-06-26T22:32:52Z",
"hourly_rate":100.0
},
"task_assignment":{
"id":155505016,
"billable":false,
"is_active":true,
"created_at":"2017-06-26T21:52:18Z",
"updated_at":"2017-06-26T21:54:06Z",
"hourly_rate":100.0,
"budget":null
},
"hours":1.0,
"hours_without_timer":1.0,
"rounded_hours":1.0,
"notes":"Evaluating 3rd party libraries",
"created_at":"2017-06-27T15:49:17Z",
"updated_at":"2017-06-27T16:47:14Z",
"is_locked":true,
"locked_reason":"Item Approved and Locked for this Time Period",
"is_closed":true,
"is_billed":false,
"timer_started_at":null,
"started_time":"11:00am",
"ended_time":"12:00pm",
"is_running":false,
"invoice":null,
"external_reference":null,
"billable":false,
"budgeted":true,
"billable_rate":null,
"cost_rate":50.0
},
{
"id":636707831,
"spent_date":"2017-03-01",
"user":{
"id":1782959,
"name":"Kim Allen"
},
"client":{
"id":5735776,
"name":"123 Industries"
},
"project":{
"id":14308069,
"name":"Online Store - Phase 1"
},
"task":{
"id":8083368,
"name":"Project Management"
},
"user_assignment":{
"id":125068554,
"is_project_manager":true,
"is_active":true,
"budget":null,
"created_at":"2017-06-26T22:32:52Z",
"updated_at":"2017-06-26T22:32:52Z",
"hourly_rate":100.0
},
"task_assignment":{
"id":155505015,
"billable":true,
"is_active":true,
"created_at":"2017-06-26T21:52:18Z",
"updated_at":"2017-06-26T21:52:18Z",
"hourly_rate":100.0,
"budget":null
},
"hours":2.0,
"hours_without_timer":2.0,
"rounded_hours":2.0,
"notes":"Planning meetings",
"created_at":"2017-06-27T15:48:24Z",
"updated_at":"2017-06-27T16:47:14Z",
"is_locked":true,
"locked_reason":"Item Invoiced and Approved and Locked for this Time Period",
"is_closed":true,
"is_billed":true,
"timer_started_at":null,
"started_time":"9:00am",
"ended_time":"11:00am",
"is_running":false,
"invoice":{
"id":13150403,
"number":"1001"
},
"external_reference":null,
"billable":true,
"budgeted":true,
"billable_rate":100.0,
"cost_rate":50.0
}
],
"per_page":2000,
"total_pages":1,
"total_entries":4,
"next_page":null,
"previous_page":null,
"page":1,
"links":{
"first":"<https://api.harvestapp.com/v2/time_entries?page=1&per_page=2000>",
"next":null,
"previous":null,
"last":"<https://api.harvestapp.com/v2/time_entries?page=1&per_page=2000>"
}
}
Retrieve a time entry⚭
Retrieves the time entry with the given ID. Returns a time entry object and a 200 OK response code if a valid identifier was provided.
GET /v2/time_entries/{TIME_ENTRY_ID}
Example Request:
curl "<https://api.harvestapp.com/v2/time_entries/636708723>" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp (<[email protected]>)"
Example Response:
{
"id":636708723,
"spent_date":"2017-03-01",
"user":{
"id":1782959,
"name":"Kim Allen"
},
"client":{
"id":5735776,
"name":"123 Industries"
},
"project":{
"id":14308069,
"name":"Online Store - Phase 1"
},
"task":{
"id":8083366,
"name":"Programming"
},
"user_assignment":{
"id":125068554,
"is_project_manager":true,
"is_active":true,
"budget":null,
"created_at":"2017-06-26T22:32:52Z",
"updated_at":"2017-06-26T22:32:52Z",
"hourly_rate":100.0
},
"task_assignment":{
"id":155505014,
"billable":true,
"is_active":true,
"created_at":"2017-06-26T21:52:18Z",
"updated_at":"2017-06-26T21:52:18Z",
"hourly_rate":100.0,
"budget":null
},
"hours":1.0,
"hours_without_timer":1.0,
"rounded_hours":1.0,
"notes":"Importing products",
"created_at":"2017-06-27T15:49:28Z",
"updated_at":"2017-06-27T16:47:14Z",
"is_locked":true,
"locked_reason":"Item Invoiced and Approved and Locked for this Time Period",
"is_closed":true,
"is_billed":true,
"timer_started_at":null,
"started_time":"1:00pm",
"ended_time":"2:00pm",
"is_running":false,
"invoice":{
"id":13150403,
"number":"1001"
},
"external_reference":null,
"billable":true,
"budgeted":true,
"billable_rate":100.0,
"cost_rate":50.0
}
Create a time entry via duration⚭
Creates a new time entry object. Returns a time entry object and a 201 Created response code if the call succeeded.
You should only use this method to create time entries when your account is configured to track time via duration. You can verify this by visiting the Settings page in your Harvest account or by checking if wants_timestamp_timers is false in the Company API.
POST /v2/time_entries
Parameter Type Required Description
user_id integer optional The ID of the user to associate with the time entry. Defaults to the currently authenticated user’s ID.
project_id integer required The ID of the project to associate with the time entry.
task_id integer required The ID of the task to associate with the time entry.
spent_date date required The ISO 8601 formatted date the time entry was spent.
hours decimal optional The current amount of time tracked. If provided, the time entry will be created with the specified hours and is_running will be set to false. If not provided, hours will be set to 0.0 and is_running will be set to true.
notes string optional Any notes to be associated with the time entry.
external_reference object optional An object containing the id, group_id, account_id, and permalink of the external reference.
Example Request:
curl "<https://api.harvestapp.com/v2/time_entries>" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp (<[email protected]>)" \
-X POST \
-H "Content-Type: application/json" \
-d '{"user_id":1782959,"project_id":14307913,"task_id":8083365,"spent_date":"2017-03-21","hours":1.0}'
Example Response:
{
"id":636718192,
"spent_date":"2017-03-21",
"user":{
"id":1782959,
"name":"Kim Allen"
},
"client":{
"id":5735774,
"name":"ABC Corp"
},
"project":{
"id":14307913,
"name":"Marketing Website"
},
"task":{
"id":8083365,
"name":"Graphic Design"
},
"user_assignment":{
"id":125068553,
"is_project_manager":true,
"is_active":true,
"budget":null,
"created_at":"2017-06-26T22:32:52Z",
"updated_at":"2017-06-26T22:32:52Z",
"hourly_rate":100.0
},
"task_assignment":{
"id":155502709,
"billable":true,
"is_active":true,
"created_at":"2017-06-26T21:36:23Z",
"updated_at":"2017-06-26T21:36:23Z",
"hourly_rate":100.0,
"budget":null
},
"hours":1.0,
"rounded_hours":1.0,
"notes":null,
"created_at":"2017-06-27T16:01:23Z",
"updated_at":"2017-06-27T16:01:23Z",
"is_locked":false,
"locked_reason":null,
"is_closed":false,
"is_billed":false,
"timer_started_at":null,
"started_time":null,
"ended_time":null,
"is_running":false,
"invoice":null,
"external_reference": null,
"billable":true,
"budgeted":true,
"billable_rate":100.0,
"cost_rate":50.0
}
Create a time entry via start and end time⚭
Creates a new time entry object. Returns a time entry object and a 201 Created response code if the call succeeded.
You should only use this method to create time entries when your account is configured to track time via start and end time. You can verify this by visiting the Settings page in your Harvest account or by checking if wants_timestamp_timers is true in the Company API.
POST /v2/time_entries
Parameter Type Required Description
user_id integer optional The ID of the user to associate with the time entry. Defaults to the currently authenticated user’s ID.
project_id integer required The ID of the project to associate with the time entry.
task_id integer required The ID of the task to associate with the time entry.
spent_date date required The ISO 8601 formatted date the time entry was spent.
started_time time optional The time the entry started. Defaults to the current time. Example: “8:00am”.
ended_time time optional The time the entry ended. If provided, is_running will be set to false. If not provided, is_running will be set to true.
notes string optional Any notes to be associated with the time entry.
external_reference object optional An object containing the id, group_id, account_id, and permalink of the external reference.
Example Request:
curl "<https://api.harvestapp.com/v2/time_entries>" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp (<[email protected]>)" \
-X POST \
-H "Content-Type: application/json" \
-d '{"user_id":1782959,"project_id":14307913,"task_id":8083365,"spent_date":"2017-03-21","started_time":"8:00am","ended_time":"9:00am"}'
Example Response:
{
"id":636718192,
"spent_date":"2017-03-21",
"user":{
"id":1782959,
"name":"Kim Allen"
},
"client":{
"id":5735774,
"name":"ABC Corp"
},
"project":{
"id":14307913,
"name":"Marketing Website"
},
"task":{
"id":8083365,
"name":"Graphic Design"
},
"user_assignment":{
"id":125068553,
"is_project_manager":true,
"is_active":true,
"budget":null,
"created_at":"2017-06-26T22:32:52Z",
"updated_at":"2017-06-26T22:32:52Z",
"hourly_rate":100.0
},
"task_assignment":{
"id":155502709,
"billable":true,
"is_active":true,
"created_at":"2017-06-26T21:36:23Z",
"updated_at":"2017-06-26T21:36:23Z",
"hourly_rate":100.0,
"budget":null
},
"hours":1.0,
"hours_without_timer":1.0,
"rounded_hours":1.0,
"notes":null,
"created_at":"2017-06-27T16:01:23Z",
"updated_at":"2017-06-27T16:01:23Z",
"is_locked":false,
"locked_reason":null,
"is_closed":false,
"is_billed":false,
"timer_started_at":null,
"started_time": "8:00am",
"ended_time": "9:00am",
"is_running":false,
"invoice":null,
"external_reference": null,
"billable":true,
"budgeted":true,
"billable_rate":100.0,
"cost_rate":50.0
}
Update a time entry⚭
Updates the specific time entry by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns a time entry object and a 200 OK response code if the call succeeded.
PATCH /v2/time_entries/{TIME_ENTRY_ID}
Parameter Type Description
project_id integer The ID of the project to associate with the time entry.
task_id integer The ID of the task to associate with the time entry.
spent_date date The ISO 8601 formatted date the time entry was spent.
started_time time The time the entry started. Defaults to the current time. Example: “8:00am”.
ended_time time The time the entry ended.
hours decimal The current amount of time tracked.
notes string Any notes to be associated with the time entry.
external_reference object An object containing the id, group_id, account_id, and permalink of the external reference.
Example Request:
curl "<https://api.harvestapp.com/v2/time_entries/636718192>" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp (<[email protected]>)" \
-X PATCH \
-H "Content-Type: application/json" \
-d '{"notes":"Updated notes"}'
Example Response:
{
"id":636718192,
"spent_date":"2017-03-21",
"user":{
"id":1782959,
"name":"Kim Allen"
},
"client":{
"id":5735774,
"name":"ABC Corp"
},
"project":{
"id":14307913,
"name":"Marketing Website"
},
"task":{
"id":8083365,
"name":"Graphic Design"
},
"user_assignment":{
"id":125068553,
"is_project_manager":true,
"is_active":true,
"budget":null,
"created_at":"2017-06-26T22:32:52Z",
"updated_at":"2017-06-26T22:32:52Z",
"hourly_rate":100.0
},
"task_assignment":{
"id":155502709,
"billable":true,
"is_active":true,
"created_at":"2017-06-26T21:36:23Z",
"updated_at":"2017-06-26T21:36:23Z",
"hourly_rate":100.0,
"budget":null
},
"hours":1.0,
"hours_without_timer":1.0,
"rounded_hours":1.0,
"notes":"Updated notes",
"created_at":"2017-06-27T16:01:23Z",
"updated_at":"2017-06-27T16:02:40Z",
"is_locked":false,
"locked_reason":null,
"is_closed":false,
"is_billed":false,
"timer_started_at":null,
"started_time":null,
"ended_time":null,
"is_running":false,
"invoice":null,
"external_reference": null,
"billable":true,
"budgeted":true,
"billable_rate":100.0,
"cost_rate":50.0
}
Delete a time entry’s external reference⚭
Delete a time entry’s external reference. Returns a 200 OK response code if the call succeeded.
DELETE /v2/time_entries/{TIME_ENTRY_ID}/external_reference
Example Request:
curl
"<https://api.harvestapp.com/v2/time_entries/636718192/external_reference>" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp (<[email protected]>)" \
-X DELETE
Delete a time entry⚭
Delete a time entry. Deleting a time entry is only possible if it’s not closed and the associated project and task haven’t been archived. However, Admins can delete closed entries. Returns a 200 OK response code if the call succeeded.
DELETE /v2/time_entries/{TIME_ENTRY_ID}
Example Request:
curl "<https://api.harvestapp.com/v2/time_entries/636718192>" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp (<[email protected]>)" \
-X DELETE
Restart a stopped time entry⚭
Restarting a time entry is only possible if it isn’t currently running. Returns a 200 OK response code if the call succeeded.
PATCH /v2/time_entries/{TIME_ENTRY_ID}/restart
Example Request:
curl "<https://api.harvestapp.com/v2/time_entries/662202797/restart>" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp (<[email protected]>)" \
-X PATCH
Example Response:
{
"id": 662204379,
"spent_date": "2017-03-21",
"user": {
"id": 1795925,
"name": "Jane Smith"
},
"client": {
"id": 5735776,
"name": "123 Industries"
},
"project": {
"id": 14808188,
"name": "Task Force"
},
"task": {
"id": 8083366,
"name": "Programming"
},
"user_assignment": {
"id": 130403296,
"is_project_manager": true,
"is_active": true,
"budget": null,
"created_at": "2017-08-22T17:36:54Z",
"updated_at": "2017-08-22T17:36:54Z",
"hourly_rate": 100
},
"task_assignment": {
"id": 160726645,
"billable": true,
"is_active": true,
"created_at": "2017-08-22T17:36:54Z",
"updated_at": "2017-08-22T17:36:54Z",
"hourly_rate": 100,
"budget": null
},
"hours": 0,
"hours_without_timer": 0,
"rounded_hours":0,
"notes": null,
"created_at": "2017-08-22T17:40:24Z",
"updated_at": "2017-08-22T17:40:24Z",
"is_locked": false,
"locked_reason": null,
"is_closed": false,
"is_billed": false,
"timer_started_at": "2017-08-22T17:40:24Z",
"started_time": "11:40am",
"ended_time": null,
"is_running": true,
"invoice": null,
"external_reference": null,
"billable": true,
"budgeted": false,
"billable_rate": 100,
"cost_rate": 75
}
Stop a running time entry⚭
Stopping a time entry is only possible if it’s currently running. Returns a 200 OK response code if the call succeeded.
PATCH /v2/time_entries/{TIME_ENTRY_ID}/stop
Example Request:
curl "<https://api.harvestapp.com/v2/time_entries/662202797/stop>" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp (<[email protected]>)" \
-X PATCH
Example Response:
{
"id": 662202797,
"spent_date": "2017-03-21",
"user": {
"id": 1795925,
"name": "Jane Smith"
},
"client": {
"id": 5735776,
"name": "123 Industries"
},
"project": {
"id": 14808188,
"name": "Task Force"
},
"task": {
"id": 8083366,
"name": "Programming"
},
"user_assignment": {
"id": 130403296,
"is_project_manager": true,
"is_active": true,
"budget": null,
"created_at": "2017-08-22T17:36:54Z",
"updated_at": "2017-08-22T17:36:54Z",
"hourly_rate": 100
},
"task_assignment": {
"id": 160726645,
"billable": true,
"is_active": true,
"created_at": "2017-08-22T17:36:54Z",
"updated_at": "2017-08-22T17:36:54Z",
"hourly_rate": 100,
"budget": null
},
"hours": 0.02,
"hours_without_timer": 0.02,
"rounded_hours":0.25,
"notes": null,
"created_at": "2017-08-22T17:37:13Z",
"updated_at": "2017-08-22T17:38:31Z",
"is_locked": false,
"locked_reason": null,
"is_closed": false,
"is_billed": false,
"timer_started_at": null,
"started_time": "11:37am",
"ended_time": "11:38am",
"is_running": false,
"invoice": null,
"external_reference": null,
"billable": true,
"budgeted": false,
"billable_rate": 100,
"cost_rate": 75
}
```