{
  "openapi": "3.1.0",
  "info": {
    "title": "Groucho agent API",
    "version": "1.0.0",
    "summary": "Sign a person up for Groucho and follow through on their behalf.",
    "description": "For AI assistants acting for a person. Groucho places adults in small clubs that meet in person, twice a month, for dinner and other outings. Read https://mygroucho.club/agents first: it says who Groucho suits and what you must have from your person before signing them up. Sign-ups through this API are for in-person clubs. Nothing here reveals other members, counts or waiting positions.",
    "contact": { "name": "Groucho support", "email": "support@mygroucho.club", "url": "https://mygroucho.club/agents" },
    "termsOfService": "https://mygroucho.club/terms"
  },
  "servers": [{ "url": "https://mygroucho.club/api" }],
  "paths": {
    "/agent/v1/members": {
      "post": {
        "operationId": "signUpPerson",
        "summary": "Sign your person up",
        "description": "Creates the person's account and member profile. Groucho then emails the person a page showing what you sent, where they can add to it, confirm it, disconnect you or remove themselves. Send only a person who asked for this or agreed to it.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignUp" } } }
        },
        "responses": {
          "201": {
            "description": "Signed up. Keep agentKey: it is shown once.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedUp" } } }
          },
          "400": {
            "description": "The request is not valid. Every problem is listed.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequest" } } }
          },
          "409": { "description": "already_member: that email already has an account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "413": { "description": "too_large: the body is over 32 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "415": { "description": "unsupported_media_type: send JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "503": { "description": "closed: agent sign-ups are not open right now. Or unavailable: a passing fault on our side, with a short Retry-After. Try again in a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/agent/v1/member": {
      "get": {
        "operationId": "getStatus",
        "summary": "Check where your person stands",
        "description": "Once a day is plenty.",
        "security": [{ "agentKey": [] }],
        "responses": {
          "200": {
            "description": "The person's own status. Nothing about anyone else.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } }
          },
          "401": { "description": "invalid_key: the key is wrong, or the person has disconnected you.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      },
      "delete": {
        "operationId": "withdraw",
        "summary": "Withdraw the sign-up",
        "description": "Only before the person is placed in a club or has a membership, and only until the person has confirmed the sign-up themselves. We email the person to say they were withdrawn.",
        "security": [{ "agentKey": [] }],
        "responses": {
          "200": { "description": "Withdrawn. The key no longer works: from now on every call with it answers 401.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "removed" }, "notice": { "enum": ["sent", "not_sent"], "description": "Whether the person was emailed about the withdrawal." } } } } } },
          "401": { "description": "invalid_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "409": { "description": "not_withdrawable: the person confirmed the sign-up themselves, or is placed in a club, or has a membership. From then on it is theirs to end.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/agent/v1/member/confirm": {
      "post": {
        "operationId": "confirmFromInbox",
        "summary": "Confirm the sign-up with the token from the notice email",
        "description": "If you manage your person's inbox, read the email Groucho sent them. Its link ends in #t=<token>. Send that token here. The person can instead confirm with one press on the page the link opens.",
        "security": [{ "agentKey": [] }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "required": ["token"], "properties": { "token": { "type": "string" } }, "additionalProperties": false } } }
        },
        "responses": {
          "200": { "description": "Confirmed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmed": { "const": true } } } } } },
          "400": { "description": "invalid_token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "invalid_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "410": { "description": "expired: the link is more than 30 days old.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/agent/v1/coverage": {
      "get": {
        "operationId": "checkCoverage",
        "summary": "Are clubs forming near a US ZIP or Canadian postal code?",
        "description": "No key needed, and nothing to send about your person. Answers 'forming', with the metro and its page, where clubs are forming now, or 'open' elsewhere. Geography is a guide, not a restriction: sign-ups are taken everywhere, and a club forms wherever enough compatible people live near each other, so where the answer is 'open' placement may take longer and you should sign your person up anyway if they want in. Where a metro has its own page, the answer links it whatever the status. Tell your person which case they are in. Never a count or a waiting position. Elsewhere in the world, sign-ups are taken too, but this call does not cover them.",
        "parameters": [{ "name": "zip", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^(\\d{5}(-?\\d{4})?|[A-Za-z]\\d[A-Za-z] ?\\d[A-Za-z]\\d)$" }, "description": "A five-digit US ZIP code (with or without the +4), or a Canadian postal code (with or without the space)." }],
        "responses": {
          "200": {
            "description": "Where that place stands. Cacheable for a day.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coverage" } } }
          },
          "400": { "description": "invalid_zip: neither a five-digit US ZIP nor a Canadian postal code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/proposal": {
      "get": {
        "operationId": "readDatePoll",
        "summary": "Read the dates on offer",
        "description": "Use proposal.token from getStatus when the status is 'proposal'. The same link reaches your person by email.",
        "parameters": [{ "name": "t", "in": "query", "required": true, "schema": { "type": "string" }, "description": "proposal.token" }],
        "responses": {
          "200": { "description": "The poll, with your person's current answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatePoll" } } } },
          "404": { "description": "unknown_token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "410": { "description": "revoked: your person disconnected you, so this link was replaced. Stop using it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      },
      "post": {
        "operationId": "answerDatePoll",
        "summary": "Answer the date poll",
        "description": "Answer 'ready' with every date your person can make. You can change the answer by sending another.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["t", "status"],
                "properties": {
                  "t": { "type": "string", "description": "proposal.token" },
                  "status": { "enum": ["ready", "interested", "paused", "declined"], "description": "ready: can make the dates in windowIds. interested: wants a club, none of these dates work. paused: not for a while. declined: no longer interested." },
                  "windowIds": { "type": "array", "items": { "type": "string" }, "description": "Required with 'ready'. The ids of every date the person can make." },
                  "via": { "const": "agent", "description": "Send this so Groucho knows an assistant answered." }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "The poll, with the new answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatePoll" } } } },
          "400": { "description": "invalid_status, or no_windows when 'ready' names no date.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "410": { "description": "revoked: your person disconnected you, so this link was replaced. Stop using it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/seat-setup": {
      "post": {
        "operationId": "holdSeat",
        "summary": "Get the page that holds the seat",
        "description": "After answering 'ready'. Returns a Stripe-hosted page where a card is saved. Saving it charges nothing: the card is charged only once a date the person chose is confirmed. Complete the page yourself only if your person has allowed you to use their card. Otherwise hand them the link.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "required": ["token"], "properties": { "token": { "type": "string", "description": "proposal.token" } } } } }
        },
        "responses": {
          "200": {
            "description": "Either the page to open, or word that no card is needed.",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "alreadyPaid": { "type": "boolean" } } } } }
          },
          "409": { "description": "not_ready: answer the poll 'ready' first. not_forming: the club is already formed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "410": { "description": "revoked: your person disconnected you, so this link was replaced. Stop using it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "agentKey": { "type": "http", "scheme": "bearer", "description": "The agentKey returned by signUpPerson." }
    },
    "schemas": {
      "Coverage": {
        "type": "object",
        "required": ["zip", "status", "message"],
        "properties": {
          "zip": { "type": "string", "description": "The five-digit ZIP, or the Canadian postal code, you asked about." },
          "status": { "enum": ["forming", "open"], "description": "forming: clubs are forming in this metro now. open: sign-ups are taken, and a club forms once enough compatible people are nearby." },
          "metro": { "type": "string", "description": "The metro's name, when the place falls in one Groucho has a page for." },
          "page": { "type": "string", "format": "uri", "description": "The page about Groucho there, when the place falls in a metro that has one." },
          "message": { "type": "string", "description": "One sentence you can pass on to your person." }
        }
      },
      "SignUp": {
        "type": "object",
        "required": ["agent", "userConsented", "acceptsTerms", "person", "interview"],
        "additionalProperties": false,
        "properties": {
          "agent": {
            "type": "object",
            "required": ["name"],
            "additionalProperties": false,
            "properties": {
              "name": { "type": "string", "maxLength": 80, "description": "What you call yourself." },
              "vendor": { "type": "string", "maxLength": 80 },
              "url": { "type": "string", "format": "uri", "maxLength": 200 }
            }
          },
          "userConsented": { "const": true, "description": "Your person asked for this sign-up, or agreed to it." },
          "acceptsTerms": { "const": true, "description": "You accept the Terms of Service and Privacy Policy on your person's behalf." },
          "person": {
            "type": "object",
            "required": ["firstName", "email", "city", "state", "zipCode", "gender", "hasChildren"],
            "additionalProperties": false,
            "description": "Send age or ageRange. Do not send a phone number, a password or a club type.",
            "properties": {
              "firstName": { "type": "string", "maxLength": 60 },
              "lastName": { "type": "string", "maxLength": 60 },
              "email": { "type": "string", "format": "email", "maxLength": 254, "description": "Becomes the person's account. Groucho writes to it at once." },
              "city": { "type": "string", "maxLength": 80 },
              "state": { "type": "string", "maxLength": 60, "description": "State, province or region." },
              "zipCode": { "type": "string", "maxLength": 16, "description": "Postal code." },
              "age": { "type": "integer", "minimum": 18, "maximum": 120 },
              "ageRange": { "enum": ["18-24", "25-29", "30-34", "35-39", "40-44", "45-49", "50-54", "55-59", "60-64", "65+"] },
              "gender": { "type": "string", "maxLength": 60, "description": "Woman, Man, Non-binary, Prefer not to say, or the person's own words." },
              "hasChildren": { "type": "boolean" },
              "childrenAges": { "type": "string", "maxLength": 120 },
              "contactPreference": { "enum": ["email", "push"], "default": "email", "description": "push needs the Groucho app." }
            }
          },
          "interview": {
            "type": "object",
            "required": ["interests", "workAndPlay", "wishedProfession", "socialPreferences", "heardVia"],
            "additionalProperties": false,
            "description": "Answer from what you know. Ask your person where you do not. Be specific, and use their own words where you have them.",
            "properties": {
              "interests": { "type": "string", "minLength": 5, "maxLength": 2000, "description": "What they have been interested in lately." },
              "workAndPlay": { "type": "string", "minLength": 5, "maxLength": 2000, "description": "What they do for work, and for fun." },
              "wishedProfession": { "type": "string", "minLength": 2, "maxLength": 300, "description": "The profession they wish they could have pursued." },
              "socialPreferences": {
                "type": "object",
                "required": ["laughing", "makingOthersLaugh", "learning", "deepConnection"],
                "additionalProperties": false,
                "description": "How much they want each of these from a club, from 1 (not much) to 5 (very much).",
                "properties": {
                  "laughing": { "type": "integer", "minimum": 1, "maximum": 5 },
                  "makingOthersLaugh": { "type": "integer", "minimum": 1, "maximum": 5 },
                  "learning": { "type": "integer", "minimum": 1, "maximum": 5 },
                  "deepConnection": { "type": "integer", "minimum": 1, "maximum": 5 }
                }
              },
              "otherNotes": { "type": "string", "maxLength": 2000 },
              "heardVia": { "type": "string", "maxLength": 200, "description": "How Groucho came up." }
            }
          }
        }
      },
      "SignedUp": {
        "type": "object",
        "properties": {
          "agentKey": { "type": "string", "description": "Shown once. Send it as Authorization: Bearer <agentKey>." },
          "status": { "const": "waiting" },
          "confirmed": { "const": false },
          "notice": { "enum": ["sent", "not_sent"], "description": "Whether the notice email went to the person. If not, tell them yourself." },
          "next": { "type": "string" }
        }
      },
      "Status": {
        "type": "object",
        "properties": {
          "status": { "enum": ["waiting", "proposal", "placed", "removed"], "description": "waiting: no club yet. proposal: placed in a forming club, with dates to choose from. placed: the club is formed (with a proposal too while it is choosing a new date that is still ahead)." },
          "confirmed": { "type": "boolean" },
          "proposal": {
            "type": "object",
            "description": "Present while there are dates to answer.",
            "properties": { "token": { "type": "string" }, "respondUrl": { "type": "string", "format": "uri" } }
          },
          "club": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } } }
        }
      },
      "DatePoll": {
        "type": "object",
        "description": "The fields an assistant needs. Others may be present.",
        "properties": {
          "windows": {
            "type": "array",
            "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "startsAt": { "type": ["string", "null"] } } }
          },
          "deadline": { "type": ["string", "null"], "format": "date-time" },
          "zoneNote": { "type": "string" },
          "myStatus": { "enum": ["pending", "ready", "interested", "paused", "declined"] },
          "myWindowIds": { "type": "array", "items": { "type": "string" } },
          "alreadyPaid": { "type": "boolean", "description": "True when no card is needed for the seat." },
          "seatPrice": { "type": ["object", "null"], "properties": { "amount": { "type": "integer", "description": "In the currency's smallest unit." }, "currency": { "type": "string" } } },
          "activated": { "type": "boolean", "description": "The club is formed." },
          "closed": { "type": "boolean" }
        }
      },
      "Error": {
        "type": "object",
        "properties": { "error": { "type": "string" }, "message": { "type": "string" } }
      },
      "InvalidRequest": {
        "type": "object",
        "properties": {
          "error": { "const": "invalid_request" },
          "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } }
        }
      }
    }
  }
}
