{"openapi":"3.1.0","info":{"title":"7shifts (BYOK) API","version":"0.1.0","description":"7shifts (BYOK) lets an AI assistant read your own 7shifts data through the 7shifts API with a key you supply (7shifts access token (Company Settings > Developer Tools)). Read-only: 8 tools (list_companies, list_locations, list_departments, list_roles, list_users, list_shifts, list_time_punches, list_payroll_periods). The BYOK key travels with each request, is used for that one call only and is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-sevenshifts.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-sevenshifts/docs"},"termsOfService":"https://connectorbay.com/byok-sevenshifts/terms"},"servers":[{"url":"https://byok-sevenshifts.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-sevenshifts/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_companies":{"post":{"operationId":"list_companies","summary":"List the 7shifts companies the access token belongs to, with country, plan, status and start of week. Gives the company_","description":"List the 7shifts companies the access token belongs to, with country, plan, status and start of week. Gives the company_id the other tools need. Use for \"Which 7shifts company is my token for\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"modified_since":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only records modified since this date, YYYY-MM-DD.","title":"Modified Since"}},"title":"list_companiesArguments","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 a company's 7shifts locations with address, timezone and city. Use for \"What locations does my 7shifts company have","description":"List a company's 7shifts locations with address, timezone and city. Use for \"What locations does my 7shifts company have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"description":"7shifts company id (get it from list_companies).","maximum":999999999999,"minimum":1,"title":"Company Id","type":"integer"},"modified_since":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only records modified since this date, YYYY-MM-DD.","title":"Modified Since"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many results per page (1 to 500, default 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from meta.cursor.next of the previous answer, to get the next page.","title":"Cursor"}},"required":["company_id"],"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_departments":{"post":{"operationId":"list_departments","summary":"List a company's 7shifts departments, optionally for one location. Use for \"What departments are in 7shifts location 456","description":"List a company's 7shifts departments, optionally for one location. Use for \"What departments are in 7shifts location 4569\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"description":"7shifts company id (get it from list_companies).","maximum":999999999999,"minimum":1,"title":"Company Id","type":"integer"},"location_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only departments of this location id.","title":"Location Id"},"modified_since":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only records modified since this date, YYYY-MM-DD.","title":"Modified Since"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"How many results per page.","title":"Limit"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from meta.cursor.next of the previous answer.","title":"Cursor"}},"required":["company_id"],"title":"list_departmentsArguments","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_roles":{"post":{"operationId":"list_roles","summary":"List 7shifts roles (job positions) with location, department, job code and stations. Needs the Entree plan or higher. Us","description":"List 7shifts roles (job positions) with location, department, job code and stations. Needs the Entree plan or higher. Use for \"What roles can staff be scheduled for in 7shifts\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"description":"7shifts company id (get it from list_companies).","maximum":999999999999,"minimum":1,"title":"Company Id","type":"integer"},"location_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only roles of this location id.","title":"Location Id"},"department_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only roles of this department id.","title":"Department Id"},"modified_since":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only records modified since this date, YYYY-MM-DD.","title":"Modified Since"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"How many results per page.","title":"Limit"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from meta.cursor.next of the previous answer.","title":"Cursor"}},"required":["company_id"],"title":"list_rolesArguments","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 7shifts employees with name, email, type (employee, asst_manager, manager, employer), active flag and timezone. Wag","description":"List 7shifts employees with name, email, type (employee, asst_manager, manager, employer), active flag and timezone. Wages, birth dates and addresses are left out. Needs the Entree plan or higher. Use for \"Who are my active 7shifts employees\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"description":"7shifts company id (get it from list_companies).","maximum":999999999999,"minimum":1,"title":"Company Id","type":"integer"},"status":{"anyOf":[{"enum":["active","inactive"],"type":"string"},{"type":"null"}],"default":null,"description":"active or inactive.","title":"Status"},"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Partial or full employee name to search for.","title":"Name"},"location_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only employees of this location id (not with department_id or role_id).","title":"Location Id"},"department_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only employees of this department id (not with location_id or role_id).","title":"Department Id"},"role_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only employees with this role id (not with location_id or department_id).","title":"Role Id"},"modified_since":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only records modified since this date, YYYY-MM-DD.","title":"Modified Since"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many results per page (1 to 500, default 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from meta.cursor.next of the previous answer, to get the next page.","title":"Cursor"}},"required":["company_id"],"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}},"/v1/tools/list_shifts":{"post":{"operationId":"list_shifts","summary":"List scheduled shifts with user, role, location, start and end, open flag, draft or published status and attendance stat","description":"List scheduled shifts with user, role, location, start and end, open flag, draft or published status and attendance status. Needs the The Works plan or higher. Wage fields are left out. Use for \"What shifts are scheduled at 7shifts location 4569 next week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"description":"7shifts company id (get it from list_companies).","maximum":999999999999,"minimum":1,"title":"Company Id","type":"integer"},"location_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only shifts of this location id.","title":"Location Id"},"department_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only shifts of this department id.","title":"Department Id"},"role_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only shifts of this role id.","title":"Role Id"},"user_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only shifts of this employee id.","title":"User Id"},"start_gte":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Shifts starting at or after this ISO 8601 time, for example 2026-03-02T00:00:00Z.","title":"Start Gte"},"start_lte":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Shifts starting at or before this ISO 8601 time.","title":"Start Lte"},"open":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for open shifts only (not assigned to anyone).","title":"Open"},"draft":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True for shifts still in draft.","title":"Draft"},"sort_dir":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"asc or desc by sort_by.","title":"Sort Dir"},"sort_by":{"anyOf":[{"enum":["start","end"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by start or end.","title":"Sort By"},"modified_since":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only records modified since this date, YYYY-MM-DD.","title":"Modified Since"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many results per page (1 to 500, default 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from meta.cursor.next of the previous answer, to get the next page.","title":"Cursor"}},"required":["company_id"],"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_time_punches":{"post":{"operationId":"list_time_punches","summary":"List clock-in and clock-out records with user, location, role, approval flag, tips and breaks. Needs the Entree plan or ","description":"List clock-in and clock-out records with user, location, role, approval flag, tips and breaks. Needs the Entree plan or higher. Hourly wage is left out. Use for \"How many hours did each 7shifts employee work last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"description":"7shifts company id (get it from list_companies).","maximum":999999999999,"minimum":1,"title":"Company Id","type":"integer"},"location_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only punches at this location id.","title":"Location Id"},"user_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only punches of this employee id.","title":"User Id"},"department_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only punches of this department id.","title":"Department Id"},"role_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only punches of this role id.","title":"Role Id"},"approved":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for approved punches only, false for unapproved only.","title":"Approved"},"clocked_in_gte":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Punches clocked in at or after this UTC ISO 8601 time.","title":"Clocked In Gte"},"clocked_in_lte":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Punches clocked in at or before this UTC ISO 8601 time.","title":"Clocked In Lte"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results per page (default 20).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from meta.cursor.next of the previous answer.","title":"Cursor"}},"required":["company_id"],"title":"list_time_punchesArguments","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_payroll_periods":{"post":{"operationId":"list_payroll_periods","summary":"List 7shifts payroll periods with start, end, closed and finalized flags and whether every punch is approved. Use for \"W","description":"List 7shifts payroll periods with start, end, closed and finalized flags and whether every punch is approved. Use for \"Which 7shifts payroll periods are still open\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"description":"7shifts company id (from list_companies).","maximum":999999999999,"minimum":1,"title":"Company Id","type":"integer"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"How many results per page.","title":"Limit"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from meta.cursor.next of the previous answer.","title":"Cursor"}},"required":["company_id"],"title":"list_payroll_periodsArguments","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}}}}