{"openapi":"3.1.0","info":{"title":"Langexchange API","version":"0.1.0","description":"A fully local CEFR-calibrated (A1-C2) language-exchange conversation-prompt generator with a hand-authored topic bank across daily-life, opinion, and hypothetical categories, plus an honest CEFR can-do quick-reference.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://langexchange.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/langexchange/docs"},"termsOfService":"https://connectorbay.com/langexchange/terms"},"servers":[{"url":"https://langexchange.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/langexchange/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/list_levels":{"post":{"operationId":"list_levels","summary":"The six CEFR levels (A1-C2) with their typical grammar focus. Use for \"what CEFR levels do you cover\".","description":"The six CEFR levels (A1-C2) with their typical grammar focus. Use for \"what CEFR levels do you cover\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_levelsArguments","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/cefr_reference":{"post":{"operationId":"cefr_reference","summary":"The CEFR can-do quick-reference for one level, or all six — what a learner at that level can typically","description":"The CEFR can-do quick-reference for one level, or all six — what a learner at that level can typically\n    do, paraphrased from the Council of Europe's published CEFR global scale. Use for \"what can a B1 learner\n    actually do\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"level":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A1 | A2 | B1 | B2 | C1 | C2 (or a name like 'beginner'/'advanced'); omit to list all six.","title":"Level"}},"title":"cefr_referenceArguments","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/topic_bank":{"post":{"operationId":"topic_bank","summary":"Browses the hand-authored conversation-prompt bank by level and/or category, without picking one. Use","description":"Browses the hand-authored conversation-prompt bank by level and/or category, without picking one. Use\n    for \"show me all the B2 opinion prompts\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"level":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A1 | A2 | B1 | B2 | C1 | C2; omit for all levels.","title":"Level"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"daily_life | opinions | hypotheticals; omit for all categories.","title":"Category"}},"title":"topic_bankArguments","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/conversation_prompt":{"post":{"operationId":"conversation_prompt","summary":"One level-appropriate conversation-starter prompt, calibrated to that CEFR level's typical grammar and","description":"One level-appropriate conversation-starter prompt, calibrated to that CEFR level's typical grammar and\n    vocabulary complexity. Use for \"give me an A2 conversation starter\", \"opinion question for a B1 learner\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"level":{"description":"A1 | A2 | B1 | B2 | C1 | C2 (or a name like 'beginner'/'advanced').","title":"Level","type":"string"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"daily_life | opinions | hypotheticals; omit for a random category.","title":"Category"}},"required":["level"],"title":"conversation_promptArguments","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/practice_session":{"post":{"operationId":"practice_session","summary":"Several conversation prompts across mixed categories for one CEFR level, bundled as a practice set. Use","description":"Several conversation prompts across mixed categories for one CEFR level, bundled as a practice set. Use\n    for \"give me 5 conversation prompts for a C1 language exchange\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"level":{"description":"A1 | A2 | B1 | B2 | C1 | C2","title":"Level","type":"string"},"count":{"default":3,"maximum":12,"minimum":1,"title":"Count","type":"integer"}},"required":["level"],"title":"practice_sessionArguments","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}}}}