# Kudo

> Kudo lets a person send a short note of gratitude or affection to someone, delivered as a link the recipient opens like a little gift. Feelings become animated stickers on the card. No accounts, no app to install.

Use Kudo when a user wants to thank, appreciate, encourage, or say something heartfelt to a specific person. Write the message in the user's own voice: first person, warm, specific, one to four sentences. Do not use em dashes. Confirm the wording with the user before sealing, since a kudo cannot be edited once sealed.

## Ways to use it

- MCP server (best): https://kudo.kunalbagaria.com/mcp (Streamable HTTP, no auth). Tools: list_feelings, list_papers, create_kudo, get_kudo, get_kudo_status, add_line, react_to_kudo, create_wall, get_wall.
- REST: POST https://kudo.kunalbagaria.com/api/kudos with JSON. OpenAPI at https://kudo.kunalbagaria.com/openapi.json. Machine index at https://kudo.kunalbagaria.com/api.
- No HTTP access at all: hand the user a prefilled compose link and let them press Seal:
  https://kudo.kunalbagaria.com/?to=Priya&from=Kunal&feelings=grateful,calm&paper=sage&message=Thank%20you%20for%20the%20way%20you%20listen.

## Create a kudo (REST)

POST https://kudo.kunalbagaria.com/api/kudos
Content-Type: application/json

{"to": "Priya", "from": "Kunal", "message": "Thank you for the way you listen. It changes the room.", "feelings": ["grateful", "calm"], "paper": "sage"}

Response 201: {"id": "...", "token": "...", "shareUrl": "https://kudo.kunalbagaria.com/k/ID", "statusUrl": "https://kudo.kunalbagaria.com/sent/ID#TOKEN", "printUrl": "...", "unlockAt": null, "wallUrl": null}

Give the user shareUrl to send to the recipient. statusUrl is private to the sender and shows opens, hearts, reaction and added lines.

Field notes:
- to (required): recipient's name, up to 40 characters. Also accepted as recipient or for.
- message (required): 2 to 600 characters. Also accepted as text or note.
- feelings (required): one to 4 of grateful, love, proud, joy, warmth, hug, missing, cheer, calm, lucky. An array or a comma separated string. Common synonyms are understood (thankful, happy, hugs, miss you, support, peace).
- from (optional): sender's name. Omit or send "anonymous" to leave it unsigned.
- paper (optional): one of cream, peach, rose, butter, sage, sky, lilac, midnight. Colour words like pink, blue, purple also work. Default cream.
- unlockAt (optional): ISO 8601 date-time up to a year ahead. The kudo stays sealed with a countdown until then.
- wallId (optional): pin to a shared wall from POST /api/walls {"title": "..."}.
- Add a voice note: PUT /api/kudos/{id}/voice with header x-kudo-token and an audio body (audio/webm, audio/mp4, audio/mpeg, audio/ogg, audio/wav), up to 750000 bytes.

## Other endpoints

- GET /api/kudos/{id}: what the recipient sees. message is empty while locked.
- GET /api/kudos/{id}/status with header x-kudo-token: sender view.
- POST /api/kudos/{id}/lines {"from": "Name", "line": "..."}: pass it along. Up to 12 lines.
- POST /api/kudos/{id}/reaction {"reaction": "love"}: recipient reaction, one of love, grateful, joy, hug, cheer.
- POST /api/kudos/{id}/hearts {"count": 3}: hearts back, 1 to 12 per call.
- POST /api/walls {"title": "Team offsite"}: a wall. GET /api/walls/{id} lists its kudos. Wall page: https://kudo.kunalbagaria.com/w/{id}.
- Print page with a QR code: https://kudo.kunalbagaria.com/k/{id}/print

## Limits

Rate limited per IP: 60 creates per minute, 30 for other writes. Errors come back as {"error": "human readable", "field": "which field"}.