{"openapi":"3.1.0","info":{"title":"Humaans (BYOK) API","version":"0.1.0","description":"Humaans (BYOK) lets an AI assistant read your own Humaans data through the Humaans API with a key you supply (Humaans API access token (public:read or private:read scope)). Read-only: 12 tools (get_token_info, list_companies, list_people, get_person, list_job_roles, list_locations, list_org_units, list_time_away, list_time_away_periods, list_time_away_types, list_public_holiday_calendars,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-humaans.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-humaans/docs"},"termsOfService":"https://connectorbay.com/byok-humaans/terms"},"servers":[{"url":"https://byok-humaans.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-humaans/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_token_info":{"post":{"operationId":"get_token_info","summary":"Show the scopes the token has and when it expires. Use for \"Which scopes does my Humaans token have and when does it exp","description":"Show the scopes the token has and when it expires. Use for \"Which scopes does my Humaans token have and when does it expire\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_token_infoArguments","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_companies":{"post":{"operationId":"list_companies","summary":"List the company the token belongs to with name, status, payment status and dates. Use for \"Which Humaans company is thi","description":"List the company the token belongs to with name, status, payment status and dates. Use for \"Which Humaans company is this token for\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Items per page (1 to 250).","title":"Limit"},"skip":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of records to skip, for paging (0 for the first page).","title":"Skip"}},"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_people":{"post":{"operationId":"list_people","summary":"List people with name, work email, status, job role, location, contract type, start and end dates, teams and holiday cal","description":"List people with name, work email, status, job role, location, contract type, start and end dates, teams and holiday calendar; active people by default, filter by status, work email or start date range. Home address, birthday and tax fields are left out. Use for \"Who joined the company this year\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["active","newHire","offboarded","all"],"type":"string"},{"type":"null"}],"default":"active","description":"Which people: active (default), newHire, offboarded or all.","title":"Status"},"email":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only the person with this work email.","title":"Email"},"started_from":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only people who started on or after this date (YYYY-MM-DD).","title":"Started From"},"started_to":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only people who started on or before this date (YYYY-MM-DD).","title":"Started To"},"left_from":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only people whose last working day is on or after this date (YYYY-MM-DD).","title":"Left From"},"space_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only people of this space id.","title":"Space Id"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Items per page (1 to 250).","title":"Limit"},"skip":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of records to skip, for paging (0 for the first page).","title":"Skip"}},"title":"list_peopleArguments","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_person":{"post":{"operationId":"get_person","summary":"Get one person by id with name, work email, status, job role, location, contract type, start and end dates, teams and ho","description":"Get one person by id with name, work email, status, job role, location, contract type, start and end dates, teams and holiday calendar. Home address, birthday and tax fields are left out. Use for \"Show the profile of person abc123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"person_id":{"description":"Humaans person id.","maxLength":200,"title":"Person Id","type":"string"}},"required":["person_id"],"title":"get_personArguments","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_job_roles":{"post":{"operationId":"list_job_roles","summary":"List job roles (job title, department, effective dates, who they report to); use as_of to get the role in effect on a da","description":"List job roles (job title, department, effective dates, who they report to); use as_of to get the role in effect on a date for each person. Use for \"What is everyone's job title as of today\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"person_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only job roles of this person id.","title":"Person Id"},"department":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only job roles in this department name.","title":"Department"},"as_of":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only the role in effect on this date, one per person (YYYY-MM-DD).","title":"As Of"},"effective_from":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only roles effective on or after this date (YYYY-MM-DD).","title":"Effective From"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Items per page (1 to 250).","title":"Limit"},"skip":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of records to skip, for paging (0 for the first page).","title":"Skip"}},"title":"list_job_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_locations":{"post":{"operationId":"list_locations","summary":"List company locations with label, code, city, country, timezone and the time away policy and working pattern in use. Us","description":"List company locations with label, code, city, country, timezone and the time away policy and working pattern in use. Use for \"Where are our offices\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Items per page (1 to 250).","title":"Limit"},"skip":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of records to skip, for paging (0 for the first page).","title":"Skip"}},"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_org_units":{"post":{"operationId":"list_org_units","summary":"List org units (departments, teams, legal entities) with name, code, parent, hierarchy and reporting leader. Use for \"Wh","description":"List org units (departments, teams, legal entities) with name, code, parent, hierarchy and reporting leader. Use for \"What is our org structure\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"parent_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only the direct children of this org unit id.","title":"Parent Id"},"org_hierarchy_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only units of this org hierarchy id.","title":"Org Hierarchy Id"},"org_unit_type_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only units of this org unit type id.","title":"Org Unit Type Id"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Items per page (1 to 250).","title":"Limit"},"skip":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of records to skip, for paging (0 for the first page).","title":"Skip"}},"title":"list_org_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_time_away":{"post":{"operationId":"list_time_away","summary":"List time away records (leave, remote work, training) with person, dates, half-day periods, type, days, request status a","description":"List time away records (leave, remote work, training) with person, dates, half-day periods, type, days, request status and reviewer; filter by person, type, status or date range. Use for \"Who is on leave next week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"person_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only time away of this person id.","title":"Person Id"},"time_away_type_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only time away of this type id.","title":"Time Away Type Id"},"request_status":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Only requests in this status, for example approved, pending or declined.","title":"Request Status"},"start_from":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only time away starting on or after this date (YYYY-MM-DD).","title":"Start From"},"start_to":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only time away starting on or before this date (YYYY-MM-DD).","title":"Start To"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Items per page (1 to 250).","title":"Limit"},"skip":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of records to skip, for paging (0 for the first page).","title":"Skip"}},"title":"list_time_awayArguments","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_away_periods":{"post":{"operationId":"list_time_away_periods","summary":"List leave balance periods with allowance, carried over, used, pending, upcoming, current balance and end-of-year balanc","description":"List leave balance periods with allowance, carried over, used, pending, upcoming, current balance and end-of-year balance; defaults to the pto type. Use for \"How many holiday days does everyone have left\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"person_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only periods of this person id.","title":"Person Id"},"time_away_type_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Time away type id, or all for every type (pto when empty).","title":"Time Away Type Id"},"current_only":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Only the current period of each person.","title":"Current Only"},"as_of":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Work out the figures as of this date (YYYY-MM-DD); today when empty.","title":"As Of"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Items per page (1 to 250).","title":"Limit"},"skip":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of records to skip, for paging (0 for the first page).","title":"Skip"}},"title":"list_time_away_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}},"/v1/tools/list_time_away_types":{"post":{"operationId":"list_time_away_types","summary":"List time away types (pto, sick, parental and company-specific ones) with name, category and base type. Use for \"What ki","description":"List time away types (pto, sick, parental and company-specific ones) with name, category and base type. Use for \"What kinds of leave can people book\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Items per page (1 to 250).","title":"Limit"},"skip":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of records to skip, for paging (0 for the first page).","title":"Skip"}},"title":"list_time_away_typesArguments","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_public_holiday_calendars":{"post":{"operationId":"list_public_holiday_calendars","summary":"List public holiday calendars with name, country, region and number of days. Use for \"Which holiday calendars do we use\"","description":"List public holiday calendars with name, country, region and number of days. Use for \"Which holiday calendars do we use\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Items per page (1 to 250).","title":"Limit"},"skip":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of records to skip, for paging (0 for the first page).","title":"Skip"}},"title":"list_public_holiday_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_public_holidays":{"post":{"operationId":"list_public_holidays","summary":"List the public holidays of one calendar between two dates. Use for \"What are the public holidays in the GB calendar thi","description":"List the public holidays of one calendar between two dates. Use for \"What are the public holidays in the GB calendar this year\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"calendar_id":{"description":"Public holiday calendar id (a country code such as GB, a country-region code such as ES-MD, or a calendar id).","maxLength":40,"title":"Calendar Id","type":"string"},"date_from":{"description":"First date to include (YYYY-MM-DD).","maxLength":30,"title":"Date From","type":"string"},"date_to":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Last date to include (YYYY-MM-DD).","title":"Date To"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Items per page (1 to 250).","title":"Limit"},"skip":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of records to skip, for paging (0 for the first page).","title":"Skip"}},"required":["calendar_id","date_from"],"title":"list_public_holidaysArguments","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}}}}