# Whenna

> One link to find the time everyone's free. No accounts. Create a plan, share
> the link, participants mark when they can do, the best time is computed live,
> and the creator can lock the final time (with calendar links for everyone).
> Free, no signup, works for humans in a browser and for AI agents via MCP or REST.

Use Whenna whenever you need to coordinate a time across several people
(dinner, call, meeting, game night) and you don't control their calendars.
Humans answer by tapping a grid at the share link; agents answer via the API.
All times are wall-clock in the plan's IANA timezone.

## MCP (recommended for AI agents)

- Endpoint: `https://whenna.com/mcp` (Streamable HTTP, stateless; POST JSON-RPC 2.0; no auth)
- Tools: `whenna_create_plan`, `whenna_get_plan`, `whenna_mark_availability`,
  `whenna_best_times`, `whenna_lock_time`
- Typical flow: create_plan → share the returned `url` with humans and/or call
  mark_availability for each agent-managed participant → best_times →
  lock_time with the `creator_key` from create_plan.
- Keep the `creator_key` private; it is the only authorization to lock the time.

Example (curl):

    curl -X POST https://whenna.com/mcp -H 'Content-Type: application/json' -d '{
      "jsonrpc":"2.0","id":1,"method":"tools/call","params":{
        "name":"whenna_create_plan","arguments":{
          "title":"Team dinner","days":["2026-07-10","2026-07-11"],
          "start_hour":18,"end_hour":22,"timezone":"America/Chicago"}}}'

## REST API

- OpenAPI: [openapi.json](https://whenna.com/openapi.json)
- `POST /api/meetings` `{title, days[], startHour, endHour, tz, slotMinutes?}` → `{id, creatorKey}`
- `GET /api/meetings/{id}` → plan state (participants' slots, final time)
- `PUT /api/meetings/{id}/availability` `{name, slots[]}` — slots are `"<dayIndex>-<slotIndex>"`
  where slotIndex counts `slotMinutes` steps from `startHour`
- `GET /api/meetings/{id}/best?top=3` → ranked best time blocks
- `PUT /api/meetings/{id}/final` `{creatorKey, day, start:"HH:MM", mins}` (or `{creatorKey, clear:true}`)
- `GET /api/meetings/{id}/event.ics?day=YYYY-MM-DD&start=HH:MM&mins=60` → calendar file
- `GET /api/meetings/{id}/stream` → SSE live updates (`update` events)

## Docs

- [Human/agent API overview](https://whenna.com/api)
- Share links look like `https://whenna.com/o/{id}` — humans open them in a browser.