# The North Pole API

The backend for Santa's hotline. You build a voice agent, Santa, that callers phone to find out whom they buy a
present for in this year's Secret Santa, and to do a few more North Pole errands.

## The caller

Every person in the workshop is an elf in the draw. Each elf has a 4-digit **elf code**, handed out before the
workshop. Nobody hears their giftee before Santa has checked their code.

## Calling the API

- Base URL: `https://dev.santa-workshop.internal.techmellon.com`
- Every tool is `POST /tools/<name>` with a JSON object body, and answers JSON.
- Send the header `x-api-key: $secret.north_pole_key`. The secret already exists in your organization; you never
  see its value.
- Every answer is 200 with `"ok": true`, or `"ok": false` with `"error": "<code>"` and `"message": "<what to do>"`:
  the platform hides a non-2xx body from the model, so refusals come as 200. Only a wrong `x-api-key` is a 401.

## The elf token

`verify_elf` answers an `elf_token` when the code is right. The tools marked **token** need it. It is a key, not
something to say: keep it out of the model's words. Record it as a fact and send it with `fixed`
(`"elf_token": "$<fact>"`), so the model never handles it.

## Tools

### find_elf

`{"name": "Chris"}` → `{"matches": [{"elf_id": "elf_3", "name": "Chris Grigoriadis"}, …], "note": "…"}`

First names, surnames, nicknames (Kostas, Mike, Giannis) and Greek letters all match. Several elves can share a name.

### verify_elf

`{"elf_id": "elf_3", "code": "4821"}` →
`{"verified": true, "elf_token": "elf_…", "first_name": "Chris", "unread_messages": 1}` or
`{"verified": false, "attempts_left": 3}`.

Five wrong codes lock that elf for a minute (`"error": "locked"`).

### reveal_giftee (token)

`{"elf_token": "…"}` → `{"giftee": "Kate Ilia", "their_wishlist": ["Wool scarf"]}`

### add_wish (token)

`{"elf_token": "…", "wish": "A rubber duck"}` → `{"wishlist": ["A rubber duck"]}`. The caller's own wishlist, which
their Secret Santa hears. At most 5 wishes of up to 120 characters.

### leave_hint (token)

`{"elf_token": "…", "message": "Check your desk drawer on Monday"}` → `{"delivered": true, …}`. An anonymous message
to the caller's giftee, up to 200 characters. The giftee gets it from `read_messages`.

### read_messages (token)

`{"elf_token": "…"}` → `{"messages": [{"from": "your Secret Santa", "text": "…", "at": "…"}]}`. Unread messages, which
are then marked read.

### naughty_or_nice (token)

`{"elf_token": "…"}` → `{"list": "nice", "because": "…"}`

### gift_ideas

`{"max_eur": 30, "likes": "coffee, books", "limit": 3}` → `{"total": 41, "gifts": [{"sku": …, "name": …, "price_eur": …,
"tags": […], "warehouse": …, "supplier_ref": …, "stock_units": …, "weight_g": …, "description": …}]}`

All fields are optional. With none, it answers the whole catalog: 300 gifts. `likes` matches tags such as tech, coffee,
food, games, books, sport, music, cats, dogs, funny, calm, greek, christmas, clothes, travel, desk.

### drop_off_slots

`{"day": "2026-12-15", "after": "14:00", "limit": 3}` → `{"total": 20, "slots": [{"slot_id": "dec15-1400",
"day": "2026-12-15", "time": "14:00", "place": "Reception, ground floor"}]}`

Free 10-minute slots for leaving the present at the office, 14–18 December 2026, 09:00–18:00 Athens time. All fields are
optional; with none, it answers every free slot of the week.

### book_drop_off (token)

`{"elf_token": "…", "slot_id": "dec15-1400"}` → `{"booked": {…}}`. One booking per elf; booking again moves it.
`"error": "no_slot"` for a slot_id not from `drop_off_slots`, `"error": "slot_taken"` when someone was faster.
