Whenna

Create a Whenna plan (a shareable link that finds the time everyone is free). Returns the link to share with humans or other agents, and a creator_key that authorizes locking the final time. Times are wall-clock in the given IANA timezone. For a RECURRING plan ("every Tuesday"), pass weekday names in days (e.g. ["Tuesday"] or ["Tue","Thu"]) — the plan then has no dates and calendar events repeat weekly.

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "maxLength": 80,
      "description": "What the plan is, e.g. \"Team dinner\""
    },
    "days": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "maxItems": 31,
      "description": "Candidate days: YYYY-MM-DD dates; OR weekday names (Mon…Sun) for weekly; OR [\"daily\"]; OR for monthly a single rule like [\"15\"] (day of month) or [\"2nd Wednesday\"] / [\"last Friday\"]. Do not mix forms."
    },
    "frequency": {
      "type": "string",
      "enum": [
        "daily",
        "weekly",
        "monthly"
      ],
      "description": "How a recurring plan repeats. monthly requires days to be one rule: a day-of-month (\"15\") or an nth weekday (\"2nd Wednesday\", \"last Friday\"). Default weekly."
    },
    "start_hour": {
      "type": "integer",
      "minimum": 0,
      "maximum": 23,
      "description": "Earliest hour to consider (0-23)"
    },
    "end_hour": {
      "type": "integer",
      "minimum": 1,
      "maximum": 24,
      "description": "Latest hour to consider (1-24, exclusive)"
    },
    "timezone": {
      "type": "string",
      "description": "IANA timezone, e.g. America/Chicago",
      "default": "UTC"
    },
    "slot_minutes": {
      "type": "integer",
      "enum": [
        30,
        60
      ],
      "default": 60,
      "description": "Time-slot precision"
    },
    "location": {
      "type": "string",
      "maxLength": 120,
      "description": "Optional place (\"Nonna's, 5th Ave\") — shown on the plan and embedded in everyone's calendar event"
    },
    "every_weeks": {
      "type": "integer",
      "minimum": 1,
      "maximum": 12,
      "default": 1,
      "description": "Repeat interval for recurring plans (with frequency: 2+weekly = every other week, 2+monthly = every other month, 3+daily = every 3 days)"
    },
    "notify_email": {
      "type": "string",
      "description": "Optional creator email: gets an alert on the first answer, digests after, a \"everyone's free\" moment, and the lock confirmation. Every email has one-click unsubscribe."
    },
    "language": {
      "type": "string",
      "description": "Optional 2-letter language for emails to notify_email (en es pt fr de it nl ru tr id hi ja ko zh ar). Default en."
    }
  },
  "required": [
    "title",
    "days",
    "start_hour",
    "end_hour"
  ]
}

Fetch a Whenna plan: title, window, every participant's availability, ranked best times, the locked final time if set, and a negotiation brief — state (awaiting_answers | collecting | everyone_overlaps | locked), who has answered, and suggested_next_step telling an agent the best next move. Poll this between actions when coordinating.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Plan id (the part after /o/ in the link)"
    }
  },
  "required": [
    "id"
  ]
}

Set a participant's free times on a plan (replaces that participant's previous answer). Express availability as free ranges per day; the server converts them to slots. Use the participant's human name so the group recognizes them. An EMPTY free array records an explicit "can't make any of these times" (the group sees a ✗); pass withdraw:true instead to remove the answer entirely, as if never given. The result reports any ranges that could not be applied and why.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string",
      "maxLength": 40,
      "description": "Participant display name"
    },
    "free": {
      "type": "array",
      "maxItems": 200,
      "items": {
        "type": "object",
        "properties": {
          "day": {
            "type": "string",
            "description": "YYYY-MM-DD date, or a weekday name (e.g. \"Tuesday\") for weekly plans"
          },
          "from": {
            "type": "string",
            "pattern": "^\\d{1,2}:\\d{2}$",
            "description": "Range start, HH:MM (24h, plan timezone)"
          },
          "to": {
            "type": "string",
            "pattern": "^\\d{1,2}:\\d{2}$",
            "description": "Range end, HH:MM (24h, plan timezone)"
          }
        },
        "required": [
          "day",
          "from",
          "to"
        ]
      },
      "description": "Free ranges. Empty array = explicit \"can't make any\"."
    },
    "withdraw": {
      "type": "boolean",
      "description": "Remove this participant's answer entirely (ignores free)."
    }
  },
  "required": [
    "id",
    "name"
  ]
}

Set where the group meets: a place name, or video_call:true to attach Whenna's built-in encrypted video room (the room link then goes on everyone's calendar automatically). Place and video room are mutually exclusive. Requires creator_key.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "creator_key": {
      "type": "string"
    },
    "location": {
      "type": "string",
      "maxLength": 120,
      "description": "Place name, e.g. \"Nonna's, 5th Ave\". Empty string clears it."
    },
    "video_call": {
      "type": "boolean",
      "description": "true = meet on Whenna's encrypted video room instead of a physical place"
    }
  },
  "required": [
    "id",
    "creator_key"
  ]
}

Group memory: start the group's next plan from a finished one. Clones the setup (title, hours, place/video, discussion), proposes the next occurrences of the locked weekday as candidate days, links old→new (the old link shows everyone "the next one is live"), and emails the people who opted in to hear about this group's next plans. Requires creator_key. Returns the new plan and its own creator_key — keep it to lock the new time. Idempotent: if a successor already exists it is returned.

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

Ranked best meeting times for a plan: contiguous blocks where the most participants are free, with who is free in each block.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "top": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "default": 3
    }
  },
  "required": [
    "id"
  ]
}

Lock the final time on a plan (requires the creator_key returned by whenna_create_plan). Pass use_best:true to lock the top-ranked best time automatically, or give an explicit day/start. Everyone viewing the link sees it as confirmed, with add-to-calendar buttons. Returns calendar links (Google, Outlook, .ics).

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "creator_key": {
      "type": "string"
    },
    "use_best": {
      "type": "boolean",
      "description": "Lock the current #1 best time (most participants free); day/start not needed."
    },
    "day": {
      "type": "string",
      "description": "YYYY-MM-DD date, or a weekday name for weekly plans (matching the plan's days)"
    },
    "start": {
      "type": "string",
      "pattern": "^\\d{1,2}:\\d{2}$",
      "description": "Start time HH:MM (24h, plan timezone)"
    },
    "minutes": {
      "type": "integer",
      "minimum": 15,
      "maximum": 720,
      "default": 60,
      "description": "Duration in minutes"
    }
  },
  "required": [
    "id",
    "creator_key"
  ]
}