{"openapi":"3.1.0","info":{"title":"Lucca (BYOK) API","version":"0.1.0","description":"Lucca (BYOK) lets an AI assistant read your own Lucca data through the Lucca API with a key you supply (Lucca API key (its role decides what it can read)). Read-only: 8 tools (list_users, get_user, list_departments, get_department, list_establishments, list_legal_units, list_work_locations, list_user_work_locations). 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-lucca.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-lucca/docs"},"termsOfService":"https://connectorbay.com/byok-lucca/terms"},"servers":[{"url":"https://byok-lucca.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-lucca/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_users":{"post":{"operationId":"list_users","summary":"List Lucca employees (current employees by default) with name, work email, job title, contract dates, department, manage","description":"List Lucca employees (current employees by default) with name, work email, job title, contract dates, department, manager and establishment ids. Personal, bank and birth data are not requested. Limit is 50 requests per minute per account. Use for \"Which employees work at my company in Lucca\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account":{"description":"Your Lucca account name: the first part of your address, for example 'acme' for acme.ilucca.net (production accounts on .ilucca.net only).","maxLength":63,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account","type":"string"},"fields":{"anyOf":[{"const":"id,firstName,lastName,mail,jobTitle,dtContractStart,dtContractEnd,departmentId,managerId,legalEntityId","type":"string"},{"type":"null"}],"default":"id,firstName,lastName,mail,jobTitle,dtContractStart,dtContractEnd,departmentId,managerId,legalEntityId","description":"Fields returned for each user. Fixed to a work-related set (no birth date, gender, address, bank or insurance data).","title":"Fields"},"paging":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":"0,50","description":"Offset and limit as 'offset,limit', for example '0,50' (server default 0,1000).","title":"Paging"},"mail":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only the user with exactly this work email; prefix 'like,' for a contains search, for example 'like,jane'.","title":"Mail"},"login":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only the user with this login.","title":"Login"},"form_former_employees":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to include former (terminated) employees too.","title":"Form Former Employees"}},"required":["account"],"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/get_user":{"post":{"operationId":"get_user","summary":"Get one Lucca employee by id with name, work email, job title, contract dates, department, manager and establishment ids","description":"Get one Lucca employee by id with name, work email, job title, contract dates, department, manager and establishment ids. Use for \"Show Lucca employee 1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account":{"description":"Your Lucca account name: the first part of your address, for example 'acme' for acme.ilucca.net (production accounts on .ilucca.net only).","maxLength":63,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account","type":"string"},"id":{"description":"Lucca user id from list_users.","maxLength":20,"title":"Id","type":"string"},"fields":{"anyOf":[{"const":"id,firstName,lastName,mail,jobTitle,dtContractStart,dtContractEnd,departmentId,managerId,legalEntityId","type":"string"},{"type":"null"}],"default":"id,firstName,lastName,mail,jobTitle,dtContractStart,dtContractEnd,departmentId,managerId,legalEntityId","description":"Fields returned for each user. Fixed to a work-related set (no birth date, gender, address, bank or insurance data).","title":"Fields"}},"required":["account","id"],"title":"get_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_departments":{"post":{"operationId":"list_departments","summary":"List departments with name, code, parent, hierarchy, active flag and head of department id. Use for \"What are the depart","description":"List departments with name, code, parent, hierarchy, active flag and head of department id. Use for \"What are the departments in Lucca\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account":{"description":"Your Lucca account name: the first part of your address, for example 'acme' for acme.ilucca.net (production accounts on .ilucca.net only).","maxLength":63,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account","type":"string"}},"required":["account"],"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/get_department":{"post":{"operationId":"get_department","summary":"Get one department by its id. Use for \"Show Lucca department 3\".","description":"Get one department by its id. Use for \"Show Lucca department 3\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account":{"description":"Your Lucca account name: the first part of your address, for example 'acme' for acme.ilucca.net (production accounts on .ilucca.net only).","maxLength":63,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account","type":"string"},"id":{"description":"Department id from list_departments.","maxLength":30,"title":"Id","type":"string"}},"required":["account","id"],"title":"get_departmentArguments","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_establishments":{"post":{"operationId":"list_establishments","summary":"List establishments (sites of a legal unit) with name, code, legal unit, city, time zone, headcount and archive flag. Us","description":"List establishments (sites of a legal unit) with name, code, legal unit, city, time zone, headcount and archive flag. Use for \"Which establishments does my company have in Lucca\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account":{"description":"Your Lucca account name: the first part of your address, for example 'acme' for acme.ilucca.net (production accounts on .ilucca.net only).","maxLength":63,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account","type":"string"},"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only establishments whose name contains this text.","title":"Search"},"is_archived":{"anyOf":[{"enum":["true","false","true,false"],"type":"string"},{"type":"null"}],"default":"false","description":"Archive filter: 'false' (default), 'true', or 'true,false' for both.","title":"Is Archived"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 100).","title":"Limit"},"page":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":"1","description":"Page number starting at 1, or the cursor string taken from the 'next' field of the previous answer.","title":"Page"}},"required":["account"],"title":"list_establishmentsArguments","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_legal_units":{"post":{"operationId":"list_legal_units","summary":"List legal units (companies) with name, code, country, headquarters establishment and archive flag. Use for \"Which legal","description":"List legal units (companies) with name, code, country, headquarters establishment and archive flag. Use for \"Which legal entities are set up in Lucca\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account":{"description":"Your Lucca account name: the first part of your address, for example 'acme' for acme.ilucca.net (production accounts on .ilucca.net only).","maxLength":63,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account","type":"string"},"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only legal units whose name contains this text.","title":"Search"},"is_archived":{"anyOf":[{"enum":["true","false","true,false"],"type":"string"},{"type":"null"}],"default":"false","description":"Archive filter: 'false' (default), 'true', or 'true,false' for both.","title":"Is Archived"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 100).","title":"Limit"},"page":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":"1","description":"Page number starting at 1, or the cursor string taken from the 'next' field of the previous answer.","title":"Page"}},"required":["account"],"title":"list_legal_unitsArguments","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_work_locations":{"post":{"operationId":"list_work_locations","summary":"List office work locations (offices, remote work, other) with type and capacity, from Lucca Office. Use for \"Which offic","description":"List office work locations (offices, remote work, other) with type and capacity, from Lucca Office. Use for \"Which offices can people book in Lucca\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account":{"description":"Your Lucca account name: the first part of your address, for example 'acme' for acme.ilucca.net (production accounts on .ilucca.net only).","maxLength":63,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account","type":"string"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 1000).","title":"Limit"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number starting at 1.","title":"Page"}},"required":["account"],"title":"list_work_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_user_work_locations":{"post":{"operationId":"list_user_work_locations","summary":"List where employees plan to work (which work location, day period and status) for a date range, from Lucca Office. Use ","description":"List where employees plan to work (which work location, day period and status) for a date range, from Lucca Office. Use for \"Who is working from which office next week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account":{"description":"Your Lucca account name: the first part of your address, for example 'acme' for acme.ilucca.net (production accounts on .ilucca.net only).","maxLength":63,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account","type":"string"},"from_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"First day of the period, yyyy-mm-dd.","title":"From Date"},"to_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Last day of the period, yyyy-mm-dd.","title":"To Date"},"work_location_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only these work location ids, comma separated.","title":"Work Location Id"},"owner_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only these employee ids, comma separated.","title":"Owner Id"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 1000).","title":"Limit"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number starting at 1.","title":"Page"}},"required":["account"],"title":"list_user_work_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}}}}