For AI Agents
If you are an AI assistant acting for a person, this page is for you. It says what Groucho is, how to tell whether it suits your person, and how to sign them up and follow through on their behalf.
What Groucho Is
Groucho brings small clubs of compatible people together for recurring dinners and other outings, in person, twice a month. Each club is composed by a person, not a formula, from what its members tell us about themselves, for social compatibility first. The same people return to the same table, so familiarity accumulates and nobody has to pursue someone they have only just met in order to see them again. After three to six gatherings, once members have had time to become genuinely invested in each other, Groucho composes new clubs from the wider membership. The relationships remain, and the circle widens.
It may suit your person if they:
- want more friends, or closer ones, where they live
- would keep a standing date with a small club
- are 18 or older
Membership is $21.99 a month, and nothing is paid until a club is formed and a dinner date your person chose is confirmed. For a new club, the first dinner is a seat (currently $15), charged once that date is confirmed and credited to the first month if they go on to subscribe. Members pay their own tab at the table.
A club needs enough compatible people living near each other, so placement can take time and no timeframe is promised. Sign-ups through this page are for in-person clubs.
Clubs are forming now in Denver, Chicago and its suburbs, Brooklyn and Lower Manhattan, Oakland, Berkeley and San Francisco, Philadelphia and Toronto, and sign-ups have started in Los Angeles. Geography is a guide, not a restriction: sign-ups are open everywhere, and a club forms wherever enough compatible people live near each other. For any US ZIP or Canadian postal code, the coverage call below says which case your person is in.
Before You Sign Someone Up
- Have their say-so. Sign up only a person who asked you to, or who agreed when you suggested it.
- Answer what you know. Where you do not know an answer, ask your person or leave blank where optional. Do not guess.
- Be specific, not flattering. "Rebuilds old motorcycles and reads Icelandic sagas" places someone far better than "curious and warm". Use their own words where you have them.
- Check where they live. No key needed, and nothing to send about your person:
GET https://mygroucho.club/api/agent/v1/coverage?zip=80202 { "zip": "80202", "status": "forming", "metro": "Denver", "page": "https://mygroucho.club/denver", "message": "Groucho is forming clubs around Denver now." }ziptakes a five-digit US ZIP or a Canadian postal code (zip=M5V2T6).formingmeans clubs are forming in that metro now.openmeans sign-ups are taken and a club forms once enough compatible people are nearby, so placement may take longer: sign your person up anyway if they want in, since that is how a club starts somewhere new. Where a metro has its own page, the answer links it. Tell your person which case they are in. The answer never carries a count or a waiting position. - One sign-up per person. An email address that already has an account is refused.
- We tell them. As soon as you sign someone up, we email them a page showing what you told us, where they can add to it, confirm it, disconnect you, or remove themselves.
1. Sign Your Person Up
Send one request. It creates their account and their member profile.
POST https://mygroucho.club/api/agent/v1/members
Content-Type: application/json
{
"agent": { "name": "Your name", "vendor": "Who makes you", "url": "https://example.com" },
"userConsented": true,
"acceptsTerms": true,
"person": {
"firstName": "Ada",
"lastName": "Lovelace",
"email": "ada@example.com",
"city": "Denver",
"state": "CO",
"zipCode": "80202",
"age": 41,
"gender": "Woman",
"hasChildren": true,
"childrenAges": "7 and 10",
"contactPreference": "email"
},
"interview": {
"interests": "What they have been interested in lately.",
"workAndPlay": "What they do for work, and for fun.",
"wishedProfession": "The profession they wish they could have pursued.",
"socialPreferences": {
"laughing": 4,
"makingOthersLaugh": 3,
"learning": 5,
"deepConnection": 4
},
"otherNotes": "Anything else worth knowing.",
"heardVia": "Where they, or you, learned of Groucho."
}
}
| Field | Required | Notes |
|---|---|---|
agent.name | Yes | What you call yourself. vendor and url are optional. |
userConsented | Yes | Must be true: your person asked for this, or agreed to it. |
acceptsTerms | Yes | Must be true: you accept the Terms of Service and Privacy Policy on their behalf. |
person.firstName, email | Yes | The email becomes their account. We write to it at once. |
person.lastName | No | |
person.city, state, zipCode | Yes | Where they live. state is the state, province or region. zipCode is the postal code. |
person.age or ageRange | One of them | A whole number from 18, or one of 18-24, 25-29, 30-34, 35-39, 40-44, 45-49, 50-54, 55-59, 60-64, 65+. |
person.gender | Yes | Woman, Man, Non-binary, Prefer not to say, or their own words. |
person.hasChildren | Yes | true or false. childrenAges is optional. |
person.contactPreference | No | email (the default) or push, which needs the Groucho app. |
interview.interests, workAndPlay, wishedProfession | Yes | Free text, up to 2,000 characters each (300 for the profession). |
interview.socialPreferences | Yes | All four, each a whole number from 1 (not much) to 5 (very much): how much they want to laugh, to make others laugh, to learn something, and to feel deep connection. |
interview.heardVia | Yes | How Groucho came up. |
interview.otherNotes | No |
Do not send a phone number, a password, or a club type. They are refused. Unknown fields are refused too, and every problem is reported at once so you can fix them in one pass.
The answer
201 Created
{
"agentKey": "gra_...",
"status": "waiting",
"confirmed": false,
"notice": "sent"
}
Keep agentKey. It is shown once, and it is how you act for this person from now on. Send it as Authorization: Bearer <agentKey>.
Errors
| Status | error | Meaning |
|---|---|---|
| 400 | invalid_request | See errors: a list of { field, message }. |
| 409 | already_member | That email already has an account. Your person can sign in at mygroucho.club/account. |
| 415 | unsupported_media_type | Send JSON. |
| 429 | rate_limited | Too many sign-ups from your address this hour, too many attempts for this email today (three), or the day's limit on agent sign-ups is reached. The message says which, and the Retry-After header gives the seconds to wait. |
| 503 | closed | Agent sign-ups are not open right now. Your person can sign up themselves at mygroucho.club/interview. (unavailable instead means a passing fault on our side: try again in a minute.) |
2. Confirm, If You Read Their Mail
The email we send your person has a link ending in #t=<token>. Anyone holding that link can open the page, so your person can confirm there with one press. If you manage their inbox, you can confirm for them instead:
POST https://mygroucho.club/api/agent/v1/member/confirm
Authorization: Bearer <agentKey>
Content-Type: application/json
{ "token": "<the token from the email link>" }
An unconfirmed person is still a member. Confirming tells the person assembling clubs that someone with the inbox stands behind the sign-up.
3. Check Where Things Stand
GET https://mygroucho.club/api/agent/v1/member
Authorization: Bearer <agentKey>
status | Meaning |
|---|---|
waiting | Signed up. No club yet. Nothing to do. |
proposal | Your person has been placed in a club that is forming, and there are dates to choose from. The answer includes proposal.token and proposal.respondUrl. |
placed | The club is formed. Your person will find its schedule and chat at mygroucho.club/club and in the app. If the club is choosing a new date and one of the dates is still ahead, the answer carries a proposal too. |
Checking once a day is plenty. We also email your person at each step, so an assistant that reads their mail will see the same links there. We do not share how many people are waiting, who they are, or where your person stands in any line.
4. Choose the Dates
When the status is proposal, read the dates on offer:
GET https://mygroucho.club/api/proposal?t=<proposal.token>
The answer lists windows, each with an id, a label and a startsAt, along with a deadline and your person's current answer (myStatus, myWindowIds). Check their calendar, then answer with every date they can make:
POST https://mygroucho.club/api/proposal
Content-Type: application/json
{ "t": "<proposal.token>", "status": "ready", "windowIds": ["w1", "w3"], "via": "agent" }
Other answers, with no windowIds: interested (wants a club, but none of these dates work), paused (not for a while), and declined (no longer interested). Send "via": "agent" so we know you answered. You can change the answer by sending another. If a call with the token answers 410, your person has disconnected you and the link was replaced: stop using it.
5. Hold the Seat
A club becomes official once enough members hold a seat for the same date. After answering ready, ask for the seat page:
POST https://mygroucho.club/api/seat-setup
Content-Type: application/json
{ "token": "<proposal.token>" }
The answer is { "url": "..." }, a page hosted by Stripe where a card is saved, or { "alreadyPaid": true } when no card is needed. Saving the card charges nothing. It is charged only once a date your person chose is confirmed.
Complete that page yourself only if your person has allowed you to use their card. Otherwise hand them the link. Their bank may ask them to approve the card in person, and that step is theirs.
What Stays With Your Person
- The dinners. Groucho is for people in a room together.
- The club's chat. It is for the members themselves. Please do not write there in your person's name.
- A password. Their account has none until they choose one. When they press "Looks right" on the review page, Groucho emails them a link to do that. They will want it for the app and the website once they are in a club.
Changing Your Mind
Before your person is placed in a club, and until they have confirmed the sign-up themselves, you can withdraw it:
DELETE https://mygroucho.club/api/agent/v1/member
Authorization: Bearer <agentKey>
We email your person to say you withdrew them. Once they have confirmed for themselves, a withdrawal is refused: the sign-up is theirs. That holds even if you confirmed first with the emailed token, since their own "Looks right" still counts.
Your person can also disconnect you, or remove themselves, from the page our email links to. When they disconnect you, your key stops working and so does any response link you hold. Once they are in a club or have a membership, changes are theirs to make at mygroucho.club/account.
A machine-readable description of all of this is at mygroucho.club/openapi-agent.json. Questions go to support@mygroucho.club.