{"openapi":"3.1.0","info":{"title":"Harvest (BYOK) API","version":"0.1.0","description":"Harvest (BYOK) lets an AI assistant read your own Harvest data through the Harvest API with a key you supply (personal access token). Read-only: 8 tools (get_current_user, list_time_entries, list_projects, list_clients, list_tasks, list_invoices, list_expenses, list_users). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is only...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-harvest.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-harvest/docs"},"termsOfService":"https://connectorbay.com/byok-harvest/terms"},"servers":[{"url":"https://byok-harvest.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-harvest/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_current_user":{"post":{"operationId":"get_current_user","summary":"Show the Harvest user the token belongs to: name, email, time zone, weekly capacity, roles and active flag. Use for \"Whi","description":"Show the Harvest user the token belongs to: name, email, time zone, weekly capacity, roles and active flag. Use for \"Which Harvest user am I signed in as\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_current_userArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_time_entries":{"post":{"operationId":"list_time_entries","summary":"List time entries (newest first) with date, hours, user, client, project, task, notes, billed and running flags. Filter ","description":"List time entries (newest first) with date, hours, user, client, project, task, notes, billed and running flags. Filter by user, client, project, task or date range. Use for \"How many hours did I log in Harvest last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"user_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only entries of this Harvest user id.","title":"User Id"},"client_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only entries for this client id.","title":"Client Id"},"project_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only entries for this project id.","title":"Project Id"},"task_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only entries for this task id.","title":"Task Id"},"is_billed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for only billed entries, false for only unbilled ones.","title":"Is Billed"},"is_running":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for only timers that are running now.","title":"Is Running"},"approval_status":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only entries with this approval status, for example unsubmitted, submitted or approved.","title":"Approval Status"},"updated_since":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records updated on or after this ISO 8601 time, for example 2026-01-01T00:00:00Z.","title":"Updated Since"},"from_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only entries on or after this date (YYYY-MM-DD).","title":"From Date"},"to_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only entries on or before this date (YYYY-MM-DD).","title":"To Date"},"per_page":{"anyOf":[{"maximum":2000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many records per page (1 to 2000, default 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1. The answer includes total_pages and next_page.","title":"Page"}},"title":"list_time_entriesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_projects":{"post":{"operationId":"list_projects","summary":"List projects with client, code, billing type, budget, dates and active flag. Needs an administrator or a manager role. ","description":"List projects with client, code, billing type, budget, dates and active flag. Needs an administrator or a manager role. Use for \"Which Harvest projects are active\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for only active projects, false for only inactive ones. Leave out for all.","title":"Is Active"},"client_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only projects of this client id.","title":"Client Id"},"updated_since":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records updated on or after this ISO 8601 time, for example 2026-01-01T00:00:00Z.","title":"Updated Since"},"per_page":{"anyOf":[{"maximum":2000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many records per page (1 to 2000, default 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1. The answer includes total_pages and next_page.","title":"Page"}},"title":"list_projectsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_clients":{"post":{"operationId":"list_clients","summary":"List clients with name, currency, address and active flag. Use for \"Who are my clients in Harvest\".","description":"List clients with name, currency, address and active flag. Use for \"Who are my clients in Harvest\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for only active clients, false for only inactive ones. Leave out for all.","title":"Is Active"},"updated_since":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records updated on or after this ISO 8601 time, for example 2026-01-01T00:00:00Z.","title":"Updated Since"},"per_page":{"anyOf":[{"maximum":2000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many records per page (1 to 2000, default 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1. The answer includes total_pages and next_page.","title":"Page"}},"title":"list_clientsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_tasks":{"post":{"operationId":"list_tasks","summary":"List the task types that can be tracked, with default billing and hourly rate. Needs an administrator or a manager role.","description":"List the task types that can be tracked, with default billing and hourly rate. Needs an administrator or a manager role. Use for \"What task types exist in Harvest\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for only active tasks, false for only inactive ones. Leave out for all.","title":"Is Active"},"updated_since":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records updated on or after this ISO 8601 time, for example 2026-01-01T00:00:00Z.","title":"Updated Since"},"per_page":{"anyOf":[{"maximum":2000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many records per page (1 to 2000, default 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1. The answer includes total_pages and next_page.","title":"Page"}},"title":"list_tasksArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_invoices":{"post":{"operationId":"list_invoices","summary":"List invoices (newest issue date first) with number, client, amount, amount still due, currency, state and dates. Needs ","description":"List invoices (newest issue date first) with number, client, amount, amount still due, currency, state and dates. Needs an administrator or a manager role. Use for \"Which Harvest invoices are still open\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"anyOf":[{"enum":["draft","open","paid","closed"],"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices in this state: draft, open, paid or closed.","title":"State"},"client_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only invoices of this client id.","title":"Client Id"},"project_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only invoices for this project id.","title":"Project Id"},"updated_since":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records updated on or after this ISO 8601 time, for example 2026-01-01T00:00:00Z.","title":"Updated Since"},"from_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices issued on or after this date (YYYY-MM-DD).","title":"From Date"},"to_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices issued on or before this date (YYYY-MM-DD).","title":"To Date"},"per_page":{"anyOf":[{"maximum":2000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many records per page (1 to 2000, default 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1. The answer includes total_pages and next_page.","title":"Page"}},"title":"list_invoicesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_expenses":{"post":{"operationId":"list_expenses","summary":"List expenses with date, project, client, category, user, total cost and billing state. Use for \"What expenses were logg","description":"List expenses with date, project, client, category, user, total cost and billing state. Use for \"What expenses were logged in Harvest this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"user_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only expenses of this user id.","title":"User Id"},"client_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only expenses for this client id.","title":"Client Id"},"project_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only expenses for this project id.","title":"Project Id"},"is_billed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for only billed expenses, false for unbilled.","title":"Is Billed"},"approval_status":{"anyOf":[{"enum":["unsubmitted","submitted","approved"],"type":"string"},{"type":"null"}],"default":null,"description":"Only expenses with this status.","title":"Approval Status"},"updated_since":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records updated on or after this ISO 8601 time, for example 2026-01-01T00:00:00Z.","title":"Updated Since"},"from_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only expenses on or after this date (YYYY-MM-DD).","title":"From Date"},"to_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only expenses on or before this date (YYYY-MM-DD).","title":"To Date"},"per_page":{"anyOf":[{"maximum":2000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many records per page (1 to 2000, default 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1. The answer includes total_pages and next_page.","title":"Page"}},"title":"list_expensesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_users":{"post":{"operationId":"list_users","summary":"List the people in the Harvest account with name, email, roles, weekly capacity and active flag. Needs an administrator ","description":"List the people in the Harvest account with name, email, roles, weekly capacity and active flag. Needs an administrator or a manager role. Use for \"Who is on my Harvest team\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for only active users, false for only inactive ones. Leave out for all.","title":"Is Active"},"updated_since":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records updated on or after this ISO 8601 time, for example 2026-01-01T00:00:00Z.","title":"Updated Since"},"per_page":{"anyOf":[{"maximum":2000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many records per page (1 to 2000, default 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1. The answer includes total_pages and next_page.","title":"Page"}},"title":"list_usersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}