{"openapi":"3.1.0","info":{"title":"Homebase (BYOK) API","version":"0.1.0","description":"Homebase (BYOK) lets an AI assistant read your own Homebase data through the Homebase API with a key you supply (Homebase API key (requested under Settings, Account, API Access)). Read-only: 9 tools (get_company, list_locations, get_location, get_location_plan, list_employees, list_shifts, list_timecards, get_labor_hours, get_labor_hours_by_role). 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-homebase.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-homebase/docs"},"termsOfService":"https://connectorbay.com/byok-homebase/terms"},"servers":[{"url":"https://byok-homebase.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-homebase/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_company":{"post":{"operationId":"get_company","summary":"Show the company name tied to the key and when it was created. Use for \"Which Homebase company is my key connected to\".","description":"Show the company name tied to the key and when it was created. Use for \"Which Homebase company is my key connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_companyArguments","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 company's locations with address, time zone and website. Use for \"What locations does my Homebase account have\"","description":"List the company's locations with address, time zone and website. Use for \"What locations does my Homebase account have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"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/get_location":{"post":{"operationId":"get_location","summary":"Get one location by UUID with address, time zone and website. Use for \"Show Homebase location f9e46145-b6b1-4e9e-92a0-32","description":"Get one location by UUID with address, time zone and website. Use for \"Show Homebase location f9e46145-b6b1-4e9e-92a0-320510e2c1f3\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location_uuid":{"description":"UUID of the Homebase location (see list_locations).","maxLength":200,"title":"Location Uuid","type":"string"}},"required":["location_uuid"],"title":"get_locationArguments","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/get_location_plan":{"post":{"operationId":"get_location_plan","summary":"Show the Homebase plan of a location with trial status, trial end date and last update. Use for \"Which Homebase plan is ","description":"Show the Homebase plan of a location with trial status, trial end date and last update. Use for \"Which Homebase plan is this location on\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location_uuid":{"description":"UUID of the Homebase location (see list_locations).","maxLength":200,"title":"Location Uuid","type":"string"}},"required":["location_uuid"],"title":"get_location_planArguments","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_employees":{"post":{"operationId":"list_employees","summary":"List the employees of a location with name, default role and level (pay, contact details and PINs are left out). Use for","description":"List the employees of a location with name, default role and level (pay, contact details and PINs are left out). Use for \"Who works at this Homebase location\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location_uuid":{"description":"UUID of the Homebase location (see list_locations).","maxLength":200,"title":"Location Uuid","type":"string"},"with_archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include archived employees.","title":"With Archived"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many results per page (1 to 100, default 25).","title":"Per Page"}},"required":["location_uuid"],"title":"list_employeesArguments","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_shifts":{"post":{"operationId":"list_shifts","summary":"List scheduled shifts of a location between two times with employee, role, department, start, end, published and open fl","description":"List scheduled shifts of a location between two times with employee, role, department, start, end, published and open flags and scheduled hours. Use for \"Who is scheduled to work next week at this Homebase location\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location_uuid":{"description":"UUID of the Homebase location (see list_locations).","maxLength":200,"title":"Location Uuid","type":"string"},"start_date":{"description":"Start of the period, ISO 8601 date-time such as 2026-10-19T00:00:00Z.","maxLength":40,"title":"Start Date","type":"string"},"end_date":{"description":"End of the period, ISO 8601 date-time such as 2026-10-25T23:59:59Z.","maxLength":40,"title":"End Date","type":"string"},"open":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to list only open (unassigned) shifts.","title":"Open"},"date_filter":{"anyOf":[{"enum":["start_at","end_at","created_at","updated_at"],"type":"string"},{"type":"null"}],"default":"start_at","description":"Which date the period applies to: start_at, end_at, created_at or updated_at.","title":"Date Filter"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many results per page (1 to 100, default 25).","title":"Per Page"}},"required":["location_uuid","start_date","end_date"],"title":"list_shiftsArguments","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_timecards":{"post":{"operationId":"list_timecards","summary":"List timecards (clock in and out records) of a location between two times with employee, role, approval flag and hours w","description":"List timecards (clock in and out records) of a location between two times with employee, role, approval flag and hours worked (wages and tips are left out). Use for \"How many hours did the team work last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location_uuid":{"description":"UUID of the Homebase location (see list_locations).","maxLength":200,"title":"Location Uuid","type":"string"},"start_date":{"description":"Start of the period, ISO 8601 date-time such as 2026-10-19T00:00:00Z.","maxLength":40,"title":"Start Date","type":"string"},"end_date":{"description":"End of the period, ISO 8601 date-time such as 2026-10-25T23:59:59Z.","maxLength":40,"title":"End Date","type":"string"},"date_filter":{"anyOf":[{"enum":["clock_in","clock_out","created_at","updated_at"],"type":"string"},{"type":"null"}],"default":"clock_in","description":"Which date the period applies to: clock_in, clock_out, created_at or updated_at.","title":"Date Filter"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many results per page (1 to 100, default 25).","title":"Per Page"}},"required":["location_uuid","start_date","end_date"],"title":"list_timecardsArguments","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/get_labor_hours":{"post":{"operationId":"get_labor_hours","summary":"Show total hours (paid, regular, scheduled, overtime) for a location between two times, grouped by day or hour (costs ar","description":"Show total hours (paid, regular, scheduled, overtime) for a location between two times, grouped by day or hour (costs are left out). Use for \"How many labor hours did this location use each day last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location_uuid":{"description":"UUID of the Homebase location (see list_locations).","maxLength":200,"title":"Location Uuid","type":"string"},"start_date":{"description":"Start of the period, ISO 8601 date-time such as 2026-10-19T00:00:00Z.","maxLength":40,"title":"Start Date","type":"string"},"end_date":{"description":"End of the period, ISO 8601 date-time such as 2026-10-25T23:59:59Z.","maxLength":40,"title":"End Date","type":"string"},"group_by":{"anyOf":[{"enum":["day","hour"],"type":"string"},{"type":"null"}],"default":"day","description":"Group the totals by day (default) or hour.","title":"Group By"}},"required":["location_uuid","start_date","end_date"],"title":"get_labor_hoursArguments","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/get_labor_hours_by_role":{"post":{"operationId":"get_labor_hours_by_role","summary":"Show total hours (paid, regular, scheduled, overtime) for a location between two times, grouped by role (costs are left ","description":"Show total hours (paid, regular, scheduled, overtime) for a location between two times, grouped by role (costs are left out). Use for \"How many hours did each role work last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location_uuid":{"description":"UUID of the Homebase location (see list_locations).","maxLength":200,"title":"Location Uuid","type":"string"},"start_date":{"description":"Start of the period, ISO 8601 date-time such as 2026-10-19T00:00:00Z.","maxLength":40,"title":"Start Date","type":"string"},"end_date":{"description":"End of the period, ISO 8601 date-time such as 2026-10-25T23:59:59Z.","maxLength":40,"title":"End Date","type":"string"}},"required":["location_uuid","start_date","end_date"],"title":"get_labor_hours_by_roleArguments","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}}}}