{"openapi":"3.1.0","info":{"title":"Roommatefit API","version":"0.1.0","description":"An original roommate-compatibility questionnaire generator across cleanliness, guests, noise/schedule, shared expenses, communication style, shared spaces and lifestyle habits, plus a genuine compatibility-scoring calculator for two respondents' answers.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://roommatefit.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/roommatefit/docs"},"termsOfService":"https://connectorbay.com/roommatefit/terms"},"servers":[{"url":"https://roommatefit.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/roommatefit/docs"},"security":[{},{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/generate_questionnaire":{"post":{"operationId":"generate_questionnaire","summary":"Generates an original roommate-compatibility questionnaire from one or more categories, optionally capped","description":"Generates an original roommate-compatibility questionnaire from one or more categories, optionally capped\n    per category. Use for \"make a roommate questionnaire about cleanliness and expenses\", \"give me 3 questions per\n    topic for a roommate interview\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"categories":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Category names to include; omit for all.","examples":[["Cleanliness & Chores","Noise & Schedule"]],"title":"Categories"},"count_per_category":{"anyOf":[{"maximum":10,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Cap the number of questions per category (essentials kept first).","title":"Count Per Category"},"seed":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Optional seed for reproducible variety when capping per category.","title":"Seed"}},"title":"generate_questionnaireArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/full_questionnaire":{"post":{"operationId":"full_questionnaire","summary":"The entire original 30-question roommate-compatibility questionnaire, sectioned by category. Use for \"give","description":"The entire original 30-question roommate-compatibility questionnaire, sectioned by category. Use for \"give\n    me the full roommate compatibility questionnaire\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"full_questionnaireArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/categories_list":{"post":{"operationId":"categories_list","summary":"Every questionnaire category with how many questions are in it. Use for \"what topics does the roommate","description":"Every questionnaire category with how many questions are in it. Use for \"what topics does the roommate\n    questionnaire cover\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"categories_listArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/questions_by_category":{"post":{"operationId":"questions_by_category","summary":"Every question in one category. Use categories_list for valid names. Use for \"what questions cover shared","description":"Every question in one category. Use categories_list for valid names. Use for \"what questions cover shared\n    expenses\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category":{"description":"A category name.","examples":["Cleanliness & Chores","Shared Expenses & Bills"],"title":"Category","type":"string"}},"required":["category"],"title":"questions_by_categoryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/question_search":{"post":{"operationId":"question_search","summary":"Keyword search across every question's text, category, and rationale. Use for \"any questions about guests\",","description":"Keyword search across every question's text, category, and rationale. Use for \"any questions about guests\",\n    \"questions about pets\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Keyword to search for.","minLength":1,"title":"Query","type":"string"}},"required":["query"],"title":"question_searchArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/question_info":{"post":{"operationId":"question_info","summary":"Full detail for one question: its text, type, options, why it matters, and a deeper follow-up prompt where","description":"Full detail for one question: its text, type, options, why it matters, and a deeper follow-up prompt where\n    one exists. Use for \"why does the rent-split question matter\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"question":{"description":"A question id or a phrase from its text.","examples":["quiet_hours","overnight guest"],"minLength":1,"title":"Question","type":"string"}},"required":["question"],"title":"question_infoArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/essential_topics_checklist":{"post":{"operationId":"essential_topics_checklist","summary":"The shortlist of questions most worth not skipping when vetting a potential roommate. Use for \"what are the","description":"The shortlist of questions most worth not skipping when vetting a potential roommate. Use for \"what are the\n    most important things to ask a potential roommate\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"essential_topics_checklistArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/discussion_prompts":{"post":{"operationId":"discussion_prompts","summary":"Deeper, open-ended follow-up prompts (beyond the scripted questions) for one category or all of them. Use","description":"Deeper, open-ended follow-up prompts (beyond the scripted questions) for one category or all of them. Use\n    for \"give us some deeper discussion prompts about noise and schedules\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Limit to one category; omit for all.","title":"Category"}},"title":"discussion_promptsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/compare_answers":{"post":{"operationId":"compare_answers","summary":"A genuine compatibility calculator: compares two respondents' 1-5 ratings on shared scale-type questions","description":"A genuine compatibility calculator: compares two respondents' 1-5 ratings on shared scale-type questions\n    (see question ids from questions_by_category/full_questionnaire, e.g. tidiness_general, payment_timing), and\n    returns a 0-100 compatibility score with the biggest gaps flagged for discussion. Use for \"compare our\n    roommate questionnaire answers\", \"how compatible are we based on our ratings\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"respondent_a":{"description":"First respondent's name or label.","minLength":1,"title":"Respondent A","type":"string"},"answers_a":{"additionalProperties":{"type":"number"},"description":"Their answers: {question_id: 1-5 rating} for scale-type questions.","examples":[{"quiet_hours":5,"tidiness_general":4}],"title":"Answers A","type":"object"},"respondent_b":{"description":"Second respondent's name or label.","minLength":1,"title":"Respondent B","type":"string"},"answers_b":{"additionalProperties":{"type":"number"},"description":"Their answers to the same question ids.","examples":[{"quiet_hours":3,"tidiness_general":2}],"title":"Answers B","type":"object"}},"required":["respondent_a","answers_a","respondent_b","answers_b"],"title":"compare_answersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}