WhenMeet.me — group scheduling

Rank the best meeting times for the given participants, merging live Google/Microsoft calendar data, hand-marked availability and the heat-map sources. Each participant is filtered (Mon–Fri, waking hours) and scored in their OWN timezone; scores factor in buffer time around existing meetings and prefer sooner slots. Returns up to 8 slots: everyone-free slots first (allFree:true), then — only if there are too few — the best compromise slots (allFree:false) with a freeCount. Defaults to the next 14 days. Requires authentication.

{
  "type": "object",
  "properties": {
    "participants": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Participant emails (the authenticated user is the host and should be included)."
    },
    "from": {
      "type": "number",
      "description": "Window start, unix ms. Default: now."
    },
    "to": {
      "type": "number",
      "description": "Window end, unix ms. Default: now + 14 days."
    },
    "durationMin": {
      "type": "number",
      "enum": [
        15,
        30,
        45,
        60
      ],
      "description": "Meeting length. Default 30."
    },
    "tz": {
      "type": "string",
      "description": "Requester IANA zone, e.g. Europe/Warsaw — the fallback zone for participants whose own timezone is unknown, and the zone for the round-hour scoring bonus."
    }
  },
  "required": [
    "participants"
  ]
}

Confirm a meeting: writes the event into the authenticated host’s calendar with an optional Google Meet/Teams link, emails invites with an ICS attachment, and returns the share URL (/m/<id>). Requires authentication.

{
  "type": "object",
  "properties": {
    "participants": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "startsAt": {
      "type": "number",
      "description": "unix ms"
    },
    "endsAt": {
      "type": "number",
      "description": "unix ms"
    },
    "title": {
      "type": "string"
    },
    "conference": {
      "type": "string",
      "enum": [
        "meet",
        "teams"
      ],
      "description": "Omit for no conference link."
    },
    "tz": {
      "type": "string",
      "description": "IANA zone used to format times in invite emails."
    }
  },
  "required": [
    "participants",
    "startsAt",
    "endsAt"
  ]
}

Read a meeting by its share-link id (the UUID from /m/<id>): time, title, conference URL, host, and any proposed alternate times with their status.

{
  "type": "object",
  "properties": {
    "meetingId": {
      "type": "string"
    }
  },
  "required": [
    "meetingId"
  ]
}

Aggregated group availability for an existing meeting (the symmetric heat-map): per-30-min-slot counts of how many participants are free, plus ranked slots (per-participant timezones, buffer + soonness scoring, allFree:true everyone-free slots and allFree:false compromise slots). Individual calendars are never exposed. No auth needed — the meeting id is the capability.

{
  "type": "object",
  "properties": {
    "meetingId": {
      "type": "string"
    },
    "from": {
      "type": "number",
      "description": "unix ms. Default: now."
    },
    "to": {
      "type": "number",
      "description": "unix ms. Default: now + 14 days."
    },
    "durationMin": {
      "type": "number",
      "enum": [
        15,
        30,
        45,
        60
      ]
    },
    "tz": {
      "type": "string"
    }
  },
  "required": [
    "meetingId"
  ]
}

Propose a different time for an existing meeting on behalf of a guest. The host is notified by email and can accept or decline. Authenticated callers (Bearer PAT) skip the bot challenge; an anonymous caller must pass a Cloudflare Turnstile token in `turnstileToken` (only required when the server is configured with a Turnstile secret).

{
  "type": "object",
  "properties": {
    "meetingId": {
      "type": "string"
    },
    "suggestedBy": {
      "type": "string",
      "description": "Email of the person proposing."
    },
    "startsAt": {
      "type": "number",
      "description": "unix ms"
    },
    "endsAt": {
      "type": "number",
      "description": "unix ms"
    },
    "message": {
      "type": "string"
    },
    "turnstileToken": {
      "type": "string",
      "description": "Cloudflare Turnstile token; required for anonymous callers when a Turnstile secret is configured."
    }
  },
  "required": [
    "meetingId",
    "suggestedBy",
    "startsAt",
    "endsAt"
  ]
}

Accept or decline a proposed alternate time. Accepting moves the meeting (calendar event included) and re-sends invites. Only the meeting host may call this — requires authentication.

{
  "type": "object",
  "properties": {
    "meetingId": {
      "type": "string"
    },
    "suggestionId": {
      "type": "string"
    },
    "action": {
      "type": "string",
      "enum": [
        "accept",
        "decline"
      ]
    }
  },
  "required": [
    "meetingId",
    "suggestionId",
    "action"
  ]
}

Publish hand-marked FREE time slots for an email address (the no-calendar fallback, e.g. Apple iCloud users). Replaces previously marked slots inside the window; the group heat-map updates immediately. Authenticated callers (Bearer PAT) skip the bot challenge; an anonymous caller must pass a Cloudflare Turnstile token in `turnstileToken` (only required when the server is configured with a Turnstile secret).

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string"
    },
    "windowFrom": {
      "type": "number",
      "description": "unix ms"
    },
    "windowTo": {
      "type": "number",
      "description": "unix ms"
    },
    "freeSlots": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "start": {
            "type": "number"
          },
          "end": {
            "type": "number"
          }
        },
        "required": [
          "start",
          "end"
        ]
      }
    },
    "turnstileToken": {
      "type": "string",
      "description": "Cloudflare Turnstile token; required for anonymous callers when a Turnstile secret is configured."
    }
  },
  "required": [
    "email",
    "windowFrom",
    "windowTo",
    "freeSlots"
  ]
}

Read previously hand-marked free slots for an email within a window.

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string"
    },
    "from": {
      "type": "number"
    },
    "to": {
      "type": "number"
    }
  },
  "required": [
    "email",
    "from",
    "to"
  ]
}