{"openapi":"3.1.0","info":{"title":"Famly (BYOK) API","version":"0.1.0","description":"Famly (BYOK) lets an AI assistant read your own Famly data through the Famly API with a key you supply (Famly API access token). Read-only: 8 tools (list_sites, list_groups, list_invoices, list_meal_plans, list_work_tags, list_absence_subtypes, list_roles, list_registration_forms). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-famly.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-famly/docs"},"termsOfService":"https://connectorbay.com/byok-famly/terms"},"servers":[{"url":"https://byok-famly.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-famly/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_sites":{"post":{"operationId":"list_sites","summary":"List the centre's sites (settings) with id, title, description, email and address. Child and staff data are not requeste","description":"List the centre's sites (settings) with id, title, description, email and address. Child and staff data are not requested. Use for \"Which sites does my Famly account cover\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_sitesArguments","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 rooms (groups) the token can access, with title, description, staff ratio, order and the site set they belong to. U","description":"List rooms (groups) the token can access, with title, description, staff ratio, order and the site set they belong to. Use for \"What rooms or groups do we have at our nursery\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"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_invoices":{"post":{"operationId":"list_invoices","summary":"List invoice headers for a site and invoice-date range: number, title, total, invoice date and due date. No lines or chi","description":"List invoice headers for a site and invoice-date range: number, title, total, invoice date and due date. No lines or child ids are requested. Paged with a cursor. Use for \"What invoices did my Famly site issue in October\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_id":{"description":"Famly site id (get it from list_sites).","maxLength":64,"title":"Site Id","type":"string"},"from_date":{"description":"First invoice date to include (YYYY-MM-DD).","maxLength":200,"title":"From Date","type":"string"},"to_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Last invoice date to include (YYYY-MM-DD).","title":"To Date"},"next_token":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous page's `next` field.","title":"Next Token"}},"required":["site_id","from_date"],"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_meal_plans":{"post":{"operationId":"list_meal_plans","summary":"List planned meals per day for a site (meal type and item titles), by default the current and coming week. Images and fi","description":"List planned meals per day for a site (meal type and item titles), by default the current and coming week. Images and files are not requested. Use for \"What meals are planned at my Famly site this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_id":{"description":"Famly site id (get it from list_sites).","maxLength":64,"title":"Site Id","type":"string"},"first_day":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"First day (YYYY-MM-DD); defaults to Monday of this week.","title":"First Day"},"last_day":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Last day (YYYY-MM-DD); defaults to two weeks after the first day, at most one year.","title":"Last Day"},"next_token":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous page's `next` field.","title":"Next Token"}},"required":["site_id"],"title":"list_meal_plansArguments","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_tags":{"post":{"operationId":"list_work_tags","summary":"List the shift work tags (name, colour, code) defined for a site set. Use for \"What work tags are defined for our staff ","description":"List the shift work tags (name, colour, code) defined for a site set. Use for \"What work tags are defined for our staff shifts\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_set_id":{"description":"Famly site set id (the institutionSetId shown by list_groups).","maxLength":64,"title":"Site Set Id","type":"string"}},"required":["site_set_id"],"title":"list_work_tagsArguments","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_absence_subtypes":{"post":{"operationId":"list_absence_subtypes","summary":"List the staff absence sub-types (leave type, name, code, paid flag) configured for a site set. Use for \"What kinds of s","description":"List the staff absence sub-types (leave type, name, code, paid flag) configured for a site set. Use for \"What kinds of staff absence can we record\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_set_id":{"description":"Famly site set id (the institutionSetId shown by list_groups).","maxLength":64,"title":"Site Set Id","type":"string"}},"required":["site_set_id"],"title":"list_absence_subtypesArguments","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 permission roles (title, whether locked, source, target, site sets) the token can see; no role assignees are reques","description":"List permission roles (title, whether locked, source, target, site sets) the token can see; no role assignees are requested. Use for \"What permission roles exist in our Famly account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"first":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many roles to return (1 to 100).","title":"First"},"next_token":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous page's `next` field.","title":"Next Token"}},"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_registration_forms":{"post":{"operationId":"list_registration_forms","summary":"List custom registration forms of a site set (name, type, published and shared flags, last edit). Responses and personal","description":"List custom registration forms of a site set (name, type, published and shared flags, last edit). Responses and personal data are not requested. Use for \"Which registration forms do we have and which are published\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_set_id":{"description":"Famly site set id (the institutionSetId shown by list_groups).","maxLength":64,"title":"Site Set Id","type":"string"}},"required":["site_set_id"],"title":"list_registration_formsArguments","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}}}}