{"openapi":"3.1.0","info":{"title":"VocabSpaced API","version":"0.1.0","description":"A stateless SM-2 spaced-repetition scheduler for any vocabulary or term/definition list — computed locally, nothing stored.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://vocabspaced.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/vocabspaced/docs"},"termsOfService":"https://connectorbay.com/vocabspaced/terms"},"servers":[{"url":"https://vocabspaced.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/vocabspaced/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/new_item":{"post":{"operationId":"new_item","summary":"The starting SM-2 scheduling state for a brand-new term/definition pair (no reviews yet).","description":"The starting SM-2 scheduling state for a brand-new term/definition pair (no reviews yet).\n    Use for \"add this word to my review deck\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"term":{"description":"The vocabulary term or word.","title":"Term","type":"string"},"definition":{"description":"Its definition or meaning.","title":"Definition","type":"string"}},"required":["term","definition"],"title":"new_itemArguments","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/schedule_review":{"post":{"operationId":"schedule_review","summary":"Grade one SM-2 review and return the updated ease factor, interval, repetition count and","description":"Grade one SM-2 review and return the updated ease factor, interval, repetition count and\n    next review date. Use for \"I got 'ephemeral' right just now, when should it come back\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"term":{"description":"The vocabulary term or word being reviewed.","title":"Term","type":"string"},"definition":{"description":"Its definition or meaning.","title":"Definition","type":"string"},"quality":{"description":"Recall quality: 0-2 = failed recall (blackout to unfamiliar-when-shown), 3-5 = correct recall (hesitant to immediate).","maximum":5,"minimum":0,"title":"Quality","type":"integer"},"ease_factor":{"default":2.5,"description":"The item's ease factor before this review (2.5 for a new item).","exclusiveMinimum":0,"title":"Ease Factor","type":"number"},"interval_days":{"default":0,"description":"The item's interval in days before this review (0 for a new item).","minimum":0,"title":"Interval Days","type":"integer"},"repetitions":{"default":0,"description":"Consecutive successful reviews before this one (0 for a new item).","minimum":0,"title":"Repetitions","type":"integer"},"correct_count":{"default":0,"description":"Running total of correct reviews so far, for reporting.","minimum":0,"title":"Correct Count","type":"integer"},"incorrect_count":{"default":0,"description":"Running total of incorrect reviews so far, for reporting.","minimum":0,"title":"Incorrect Count","type":"integer"},"review_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Date of this review, YYYY-MM-DD. Defaults to today (UTC).","title":"Review Date"}},"required":["term","definition","quality"],"title":"schedule_reviewArguments","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/review_batch":{"post":{"operationId":"review_batch","summary":"Grade a whole review session (a list of items) in one call. Use for \"here's how I did on","description":"Grade a whole review session (a list of items) in one call. Use for \"here's how I did on\n    today's 12 flashcards, reschedule all of them\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"items":{"description":"Each item: {term, definition, quality, ease_factor?, interval_days?, repetitions?, correct_count?, incorrect_count?, review_date?}.","examples":[[{"definition":"lasting a very short time","quality":4,"term":"ephemeral"}]],"items":{"additionalProperties":true,"type":"object"},"maxItems":100,"minItems":1,"title":"Items","type":"array"},"review_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Default review date (YYYY-MM-DD) for items that don't specify their own.","title":"Review Date"}},"required":["items"],"title":"review_batchArguments","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/due_items":{"post":{"operationId":"due_items","summary":"Split a list of scheduled items into due (ranked most-overdue first) and not-yet-due. Use","description":"Split a list of scheduled items into due (ranked most-overdue first) and not-yet-due. Use\n    for \"which of these flashcards are due today\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"items":{"description":"Items carrying a next_review_date field, as returned by schedule_review/review_batch.","items":{"additionalProperties":true,"type":"object"},"minItems":1,"title":"Items","type":"array"},"as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Date to check against, YYYY-MM-DD. Defaults to today (UTC).","title":"As Of"}},"required":["items"],"title":"due_itemsArguments","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/mastery_level":{"post":{"operationId":"mastery_level","summary":"Classify a card's maturity band (new/learning/young/mature) from its interval and repetition","description":"Classify a card's maturity band (new/learning/young/mature) from its interval and repetition\n    count. Use for \"is this word mastered yet\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"interval_days":{"description":"The item's current interval in days.","minimum":0,"title":"Interval Days","type":"integer"},"repetitions":{"description":"The item's current consecutive-success count.","minimum":0,"title":"Repetitions","type":"integer"}},"required":["interval_days","repetitions"],"title":"mastery_levelArguments","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/algorithm_explainer":{"post":{"operationId":"algorithm_explainer","summary":"Explain the SM-2 spaced-repetition algorithm this connector implements: the quality scale,","description":"Explain the SM-2 spaced-repetition algorithm this connector implements: the quality scale,\n    the ease-factor formula and the interval rule. Use for \"how does spaced repetition scheduling\n    actually work\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"algorithm_explainerArguments","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}}}}