{"openapi":"3.1.0","info":{"title":"QuickBooks Time (BYOK) API","version":"0.1.0","description":"QuickBooks Time (BYOK) lets an AI assistant read your own QuickBooks Time data through the QuickBooks Time API with a key you supply (QuickBooks Time access token (Manual token, from the Add-ons API setup)). Read-only: 7 tools (list_timesheets, list_jobcodes, list_projects, list_locations, list_groups, list_schedule_calendars, list_schedule_events). The BYOK key travels with each request, is used...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-quickbookstime.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-quickbookstime/docs"},"termsOfService":"https://connectorbay.com/byok-quickbookstime/terms"},"servers":[{"url":"https://byok-quickbookstime.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-quickbookstime/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/list_timesheets":{"post":{"operationId":"list_timesheets","summary":"List time entries between dates with user, job code, start and end, duration, type and notes (pay rates and GPS tracks a","description":"List time entries between dates with user, job code, start and end, duration, type and notes (pay rates and GPS tracks are not requested). Use for \"What hours did the crew log last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_date":{"description":"First date to include, YYYY-MM-DD.","maxLength":10,"title":"Start Date","type":"string"},"end_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Last date to include, YYYY-MM-DD.","title":"End Date"},"user_ids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma separated user ids to filter on.","title":"User Ids"},"jobcode_ids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma separated job code ids to filter on.","title":"Jobcode Ids"},"group_ids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma separated group ids to filter on.","title":"Group Ids"},"on_the_clock":{"anyOf":[{"enum":["yes","no","both"],"type":"string"},{"type":"null"}],"default":"no","description":"Whether to include only entries still running.","title":"On The Clock"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (1 to 200, default 50).","title":"Limit"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["start_date"],"title":"list_timesheetsArguments","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_jobcodes":{"post":{"operationId":"list_jobcodes","summary":"List job codes (jobs, customers and time-off codes) with name, type, parent, billable flag and short code. Use for \"Whic","description":"List job codes (jobs, customers and time-off codes) with name, type, parent, billable flag and short code. Use for \"Which job codes can the crew clock time to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"ids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma separated job code ids to look up.","title":"Ids"},"parent_ids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma separated parent job code ids; -1 returns all.","title":"Parent Ids"},"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Name filter; * is a wildcard and matching starts at the beginning.","title":"Name"},"type":{"anyOf":[{"enum":["regular","pto","paid_break","unpaid_break","all"],"type":"string"},{"type":"null"}],"default":"regular","description":"Job code type.","title":"Type"},"active":{"anyOf":[{"enum":["yes","no","both"],"type":"string"},{"type":"null"}],"default":"yes","description":"Which records to include.","title":"Active"},"modified_since":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records modified since this ISO 8601 date-time, such as 2026-10-01T00:00:00-06:00.","title":"Modified Since"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (1 to 200, default 50).","title":"Limit"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_jobcodesArguments","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 name, status, description, start and due dates and the job code they track time against. Use for \"Whi","description":"List projects with name, status, description, start and due dates and the job code they track time against. Use for \"Which projects are in progress in QuickBooks Time\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"ids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma separated project ids to look up.","title":"Ids"},"jobcode_ids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma separated job code ids linked to projects.","title":"Jobcode Ids"},"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Name filter; * is a wildcard and matching starts at the beginning.","title":"Name"},"active":{"anyOf":[{"enum":["yes","no","both"],"type":"string"},{"type":"null"}],"default":"yes","description":"Which records to include.","title":"Active"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (1 to 200, default 50).","title":"Limit"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","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_locations":{"post":{"operationId":"list_locations","summary":"List the saved work locations with address, label and linked job codes. Use for \"Which work locations are saved in Quick","description":"List the saved work locations with address, label and linked job codes. Use for \"Which work locations are saved in QuickBooks Time\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"ids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma separated location ids to look up.","title":"Ids"},"active":{"anyOf":[{"enum":["yes","no","both"],"type":"string"},{"type":"null"}],"default":"yes","description":"Which records to include.","title":"Active"},"modified_since":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records modified since this ISO 8601 date-time, such as 2026-10-01T00:00:00-06:00.","title":"Modified Since"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (1 to 200, default 50).","title":"Limit"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_locationsArguments","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_groups":{"post":{"operationId":"list_groups","summary":"List the crew groups with name and manager ids. Use for \"Which groups are set up in QuickBooks Time\".","description":"List the crew groups with name and manager ids. Use for \"Which groups are set up in QuickBooks Time\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"ids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma separated group ids to look up.","title":"Ids"},"active":{"anyOf":[{"enum":["yes","no","both"],"type":"string"},{"type":"null"}],"default":"yes","description":"Which records to include.","title":"Active"},"modified_since":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records modified since this ISO 8601 date-time, such as 2026-10-01T00:00:00-06:00.","title":"Modified Since"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (1 to 200, default 50).","title":"Limit"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_groupsArguments","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_schedule_calendars":{"post":{"operationId":"list_schedule_calendars","summary":"List the schedule calendars that scheduled shifts belong to. Use for \"Which schedule calendars exist in QuickBooks Time\"","description":"List the schedule calendars that scheduled shifts belong to. Use for \"Which schedule calendars exist in QuickBooks Time\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"ids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma separated calendar ids to look up.","title":"Ids"},"modified_since":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records modified since this ISO 8601 date-time, such as 2026-10-01T00:00:00-06:00.","title":"Modified Since"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (1 to 200, default 50).","title":"Limit"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_schedule_calendarsArguments","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_schedule_events":{"post":{"operationId":"list_schedule_events","summary":"List scheduled shifts in the given calendars from a start time with user, job code, times and notes. Use for \"Who is sch","description":"List scheduled shifts in the given calendars from a start time with user, job code, times and notes. Use for \"Who is scheduled to work next week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"schedule_calendar_ids":{"description":"Comma separated schedule calendar ids (see list_schedule_calendars).","maxLength":200,"title":"Schedule Calendar Ids","type":"string"},"start":{"description":"Only events starting on or after this ISO 8601 date-time.","maxLength":40,"title":"Start","type":"string"},"end":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only events ending on or before this ISO 8601 date-time.","title":"End"},"jobcode_ids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma separated job code ids to filter on.","title":"Jobcode Ids"},"draft":{"anyOf":[{"enum":["yes","no","both"],"type":"string"},{"type":"null"}],"default":"no","description":"Whether to include draft events.","title":"Draft"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (1 to 200, default 50).","title":"Limit"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["schedule_calendar_ids","start"],"title":"list_schedule_eventsArguments","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}}}}