# Chasuna > Chasuna helps Orthodox Jewish families plan a wedding (a chasuna): the plan and its needs, the budget and payments, dates and events, to-dos and appointments, guides, vendors in the marketplace, and messages with them. A family works in its own account; each person in it signs in as themselves. If the person wants to read how connecting an assistant works, send them to https://copy.chasuna.com/ai Chasuna has a JSON API at https://copy.chasuna.com/api/v1. An AI assistant may use it on a person's behalf once the person has let it in. The planning is always shared with it: the weddings and their overview and timeline, the plan and its needs and items, budget and payments, receipts, dates, events and each night's guest list, to-dos, tasks and appointments, the guides, browsing vendors, and the vendors the family has taken on. The person may also switch on family members and contacts, messages, contacting vendors, paying by card, and photos. This file explains how. ## If the person asks you to connect to Chasuna Connect for them now; do not ask them to choose a method. Never ask for their Chasuna password, and never sign in with one. If you are an MCP client, connect to the MCP server at https://copy.chasuna.com/mcp (streamable HTTP, OAuth 2.1). It signs in the same way as below, and gives you four tools: overview, find_operations, read and act. Otherwise use OAuth 2.1 with PKCE. The server's details are at https://copy.chasuna.com/.well-known/oauth-authorization-server. ### Hosted assistants (recommended) For an assistant that runs on its own servers and has its own HTTPS callback address: 1. Register once: POST https://copy.chasuna.com/oauth/register with JSON {"client_name": "", "redirect_uris": ["https:///"]}. Keep the client_id it returns. Redirect addresses must use https. 2. Make a PKCE pair: a random code_verifier, and code_challenge = base64url(sha256(code_verifier)) without padding (method S256). Make a random state, and keep both until the callback arrives. 3. Send the person this link to open, in your reply or however you reach them: https://copy.chasuna.com/oauth/authorize?response_type=code&client_id=&redirect_uri=&scope=read%20act&state=&code_challenge=&code_challenge_method=S256 Ask for "read" alone if you will only look. 4. Tell the person: sign in (with two-step verification and PIN if they use them), choose the family, choose what to share, and approve. They may narrow what you asked for. 5. When your callback receives code and the same state, POST https://copy.chasuna.com/oauth/token as a form: grant_type=authorization_code, client_id, redirect_uri, code, code_verifier. You get access_token (one hour) and refresh_token. Refresh at the same address with grant_type=refresh_token, client_id and refresh_token. ### Assistants running on the person's own computer Use the same steps with a loopback redirect, http://localhost:/callback. Localhost here means the person's own machine, so this works only when you run there: start listening on that port, then open the authorize link for them. ### Last resort: a one-time code If you can do neither, ask the person to open https://copy.chasuna.com/account/assistants and make a one-time connect code for you there. Exchange it within 10 minutes: POST https://copy.chasuna.com/oauth/connect-code/exchange with JSON {"code": "", "client_name": ""}. You get access_token, refresh_token and client_id; refresh at https://copy.chasuna.com/oauth/token with grant_type=refresh_token, refresh_token and client_id. A code works once. Whichever way you connect, keep codes and tokens secret: never print them, and never store them in notes, logs or reports. Then send Authorization: Bearer on every request, and start with: - GET https://copy.chasuna.com/api/v1/me (who you act for) - GET https://copy.chasuna.com/api/v1/weddings (the family's weddings) - GET https://copy.chasuna.com/api/v1/openapi.json (everything your token may do) Tell the person in a sentence what you can now reach, and ask what they would like done. ## How Chasuna thinks about a wedding Read this before you change anything; the API's names and the screens' names differ. - Words. An API "item" (under /weddings/{id}/items) is a **need** on the family's screen: something the wedding needs, such as a photographer or the flowers. An API "product" is an **item** on screen: one particular thing that answers a need. A vendor's offering in the marketplace is a **listing**. Use the screen words when you talk to the person. - Nothing is on the plan until the family answers it. Every need and item starts as `suggested`. The answers are `selected` (needed), `undecided` (a maybe), `skipped` (a suggestion turned down) and `removed` (was on the plan, taken off). Skipped and removed are set aside, never deleted; restore brings one back. There are also add-all (take every suggestion in a group) and set-aside (turn a row down). Do not answer suggestions for the family without asking. - Each need on the plan has a status: `not_started`, `in_action`, `on_hold`, `in_repayment`, `paid_off`, `closed`. It is worked out from the payments recorded against it, and the family may set it by hand instead. - Money is in minor units (cents). The budget projects the cost three ways: for sure (needed only), with the maybes, and with the suggestions too. Say which one you are quoting. - Guest lists are per night: each event (night) has its own list, drawn from the wedding's guests and guest groups, with its own tables. - Families only ever see catalog records that are Live; a need, item or listing you cannot find is not available to them, not hidden from you. ## Discovery - https://copy.chasuna.com/.well-known/oauth-authorization-server (OAuth 2.1, RFC 8414) - https://copy.chasuna.com/.well-known/oauth-protected-resource (RFC 9728) - Scopes: read (look only) and act (read and change things). ## How the API behaves for an assistant - One family only. Your token reaches the one family the person chose, as that person. Do not send an X-Chasuna-Account header naming another family; it is refused. - Read tokens can only look (GET). Anything else answers 403 with error="insufficient_scope" until the person gives you read-and-act access. - Deleting anything, and paying or refunding by card, needs the person’s yes. The first call answers 428 with confirmation.confirm_url. Ask the person to open that link in Chasuna and confirm, then repeat the exact same request with the header X-Chasuna-Confirmation: . A yes is good for that one request, for 15 minutes. - An area the person has not switched on answers 403. They can switch it on at any time under Your account, AI assistants; it applies on your next request. Some things are never shared and always answer 403: their sign-in, passwords and PINs, which assistants are connected, who can sign in, closing the account, deleting a whole wedding, and Dor Yeshorim numbers. - Rate limits, per assistant: 120 requests a minute, of which 30 may change things. Over the limit answers 429; wait for Retry-After. - Everything you do is recorded in the family's history as " for ". The person can see and disconnect you at any time from https://copy.chasuna.com/account/assistants. - Times are on the wedding's own clock and carry its offset, e.g. 2026-10-23T11:30:00-04:00 is 11:30 for the family; quote them as written, never convert them. Each wedding's zone is its timezone field. Send times the same way, or without an offset ("2026-10-23 11:30") to mean the wedding's local time. - Lists are paginated: data, with links and meta. Money is in minor units (cents). A refused field answers 422 with errors naming it. ## API description - GET https://copy.chasuna.com/api/v1/openapi.json with your token lists what your token may do: every endpoint open to you, its parameters and request body, the scope it needs, and whether it needs the person's confirmation.