Time-off requests for calendar sync

Use keito_list_time_off_requests in Claude or another Keito MCP client to read team time off. The connection must belong to a current internal workspace owner or administrator, on Pro or Business with Time off enabled. Managers, assigned approvers, members, clients and restricted accountants cannot use this listing.

Example tool arguments:

{"from":"2027-01-01","to":"2027-12-31","status":"APPROVED","per_page":100,"page":1}

from and to match overlapping leave dates inclusively, including future dates. Either may be omitted; no dates means no date restriction. Optional user_id selects a person in the connected workspace. status accepts REQUESTED (alias for PENDING), PENDING, APPROVED, REJECTED or CANCELLED. Omit it for all statuses. updated_since is an inclusive ISO timestamp filter on the request row. page starts at 1; per_page is 1–200 (default 100). Optional inputs accept null.

The response contains time_off_requests, page metadata and coverage.partial. A result with more than one page is partial even on its last page; collect every page before treating the complete collection as authoritative. The API sorts by immutable creation time and ID. Concurrent changes can affect pages: this is a current-state listing, without a transactional snapshot across calls.

Each request includes id, user (ID, name, email), type (catalogue ID or null, name), start_date, end_date, portion, hours_per_day, day_fraction, requester notes, status, approved_by, approved_at, cancelled_at and updated_at. Full days use FULL_DAY with null hours/fraction. Half days use HALF_DAY and fraction 0.5. Fixed hours use HOURS and hours per day. These describe the booking; they are not a computed total of working hours. Do not assume an eight-hour day. Dates are civil dates, without timezone conversion; Keito does not store morning/afternoon timing here. Approval details can be null for automatic or legacy approval. Rejected/cancelled requests do not present their reviewer as an approver. Private reviewer notes and provider identifiers are excluded.

REST authentication

The matching REST endpoint is GET https://app.keito.ai/api/v2/time_off_requests, with the same filters and standard pagination links. Use a full-access API v2 key for an eligible owner/admin:

curl --get 'https://app.keito.ai/api/v2/time_off_requests' \
  --header "Authorization: Bearer $KEITO_API_KEY" \
  --header "Keito-Account-Id: $KEITO_ACCOUNT_ID" \
  --data-urlencode 'from=2027-01-01' \
  --data-urlencode 'to=2027-12-31' \
  --data-urlencode 'status=APPROVED'

The full-access preset uses *; there is no dedicated time-off token scope in this release. Personal read-only sync keys and cost-rate keys do not grant team leave access. The endpoint performs reads only; a full-access key has broader permissions elsewhere, so store it securely. Hosted MCP uses the existing OAuth connection and internal keito:read capability; its OAuth authorization scopes remain openid profile email offline_access. Current server-side workspace role, plan and Time off checks apply to both paths.

GET /api/v2/time-off remains the separate Business Planning endpoint. It is not a full request/change feed.

Reconcile changes and cancellations

Use (workspace ID, request ID) as the downstream event identity. For a normal daily approved-leave snapshot, collect all pages for the managed window and update existing events by ID.

Periodically collect all pages without status or updated_since, then reconcile the complete current set. Native cancellations remain CANCELLED; externally managed leave can be deleted. Request edits may move dates outside a previously queried window. Compare only calendar events owned by this sync within its managed scope, or reconcile without date restrictions when tracking requests across changing windows. Never delete downstream events after any failed, denied or incomplete listing. Preserve prior state and retry a full pass. If changes occur during paging, repeat the pass before destructive reconciliation.

updated_since and updated_at help poll changed request rows, but are not a durable event stream. Person/email/type renames do not update the request timestamp, and deleted external records cannot appear in a delta. Use complete reconciliation to detect those changes. This connector does not create Google Calendar events, approve leave or create future time entries; the downstream automation owns those actions.