{"openapi":"3.1.0","info":{"title":"VedaStudy SSB API","version":"1.0.0","description":"Read VedaStudy SSB's library of sacred texts — folders, documents in every language edition (always the CURRENT version), files, page text, Chant & Read line timings and line meanings — and act for signed-in members (Sign in with VedaStudy SSB).\n\nAuthenticate with `Authorization: Bearer <key or token>`:\n* `pk_live_…` publishable key — for web pages (works only from your app's allowed origins).\n* `sk_live_…` secret key — server-side only.\n* `vsat.…` OAuth access token — a member signed in with VedaStudy SSB (needed for content when your app is 'signed-in' only, and for /me).\n\nGuides: https://vedastudyssb.web.app/developers · MCP server: https://vedastudyssb.web.app/api/mcp"},"servers":[{"url":"https://vedastudyssb.web.app/api/v1"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"API key (pk_live_/sk_live_) or OAuth access token (vsat.)"},"oauth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://vedastudyssb.web.app/oauth/authorize","tokenUrl":"https://vedastudyssb.web.app/api/oauth/token","refreshUrl":"https://vedastudyssb.web.app/api/oauth/token","scopes":{"profile":"Name, email, country, preferred language","library":"Read and change the member's saved texts","meanings:write":"Write line meanings (super admins only)","classes":"Classes, homework, tutor feedback (tutors: run classes)","classes:submit":"Send a recording to the tutor (only when the member asks)","practice":"Practice progress","notes":"Own highlights, bookmarks and notes"}}}}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","bad_request","sign_in_required","origin_not_allowed","secret_key_in_browser","insufficient_scope","rate_limited","app_suspended","method_not_allowed","server_error"]},"message":{"type":"string"}}}}}}}}},"schemas":{"Folder":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"titles":{"type":"object","additionalProperties":{"type":"string"}},"description":{"type":"string"},"parentId":{"type":["string","null"]},"icon":{"type":"string"},"documentCount":{"type":"integer"},"links":{"type":"object"}}},"DocumentSummary":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"titles":{"type":"object","additionalProperties":{"type":"string"}},"description":{"type":"string"},"kind":{"type":"string","enum":["pdf","audio","video","slides","image","other"]},"languages":{"type":"array","items":{"type":"string"}},"folderId":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"meaningsCount":{"type":"integer"},"thumbnailUrl":{"type":["string","null"]},"links":{"type":"object","properties":{"web":{"type":"string"},"api":{"type":"string"},"embed":{"type":"string"}}}}}}},"paths":{"/languages":{"get":{"summary":"Content languages","responses":{"200":{"description":"Languages","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/folders":{"get":{"summary":"List folders (top level, or under ?parent=)","parameters":[{"name":"parent","in":"query","schema":{"type":"string"}},{"name":"locale","in":"query","required":false,"description":"Language for titles/descriptions in the response (falls back to English).","schema":{"type":"string"}}],"responses":{"200":{"description":"Folders","content":{"application/json":{"schema":{"type":"object","properties":{"folders":{"type":"array","items":{"$ref":"#/components/schemas/Folder"}}}}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/folders/{id}":{"get":{"summary":"A folder with its sub-folders, documents and breadcrumb","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"query","required":false,"description":"Language for titles/descriptions in the response (falls back to English).","schema":{"type":"string"}}],"responses":{"200":{"description":"Folder","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/documents":{"get":{"summary":"List / filter documents","parameters":[{"name":"folder","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","description":"Title/tag contains","schema":{"type":"string"}},{"name":"kind","in":"query","schema":{"type":"string"}},{"name":"lang","in":"query","description":"Has an edition in this language","schema":{"type":"string"}},{"name":"updated_since","in":"query","description":"ISO date — sync only what changed","schema":{"type":"string","format":"date-time"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["folder","updated"]}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":200}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"locale","in":"query","required":false,"description":"Language for titles/descriptions in the response (falls back to English).","schema":{"type":"string"}}],"responses":{"200":{"description":"Documents","content":{"application/json":{"schema":{"type":"object","properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/DocumentSummary"}},"total":{"type":"integer"},"nextCursor":{"type":["string","null"]}}}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/documents/{id}":{"get":{"summary":"A document with every language edition (current version) and its links","parameters":[{"name":"id","in":"path","required":true,"description":"Document id or slug.","schema":{"type":"string"}},{"name":"locale","in":"query","required":false,"description":"Language for titles/descriptions in the response (falls back to English).","schema":{"type":"string"}}],"responses":{"200":{"description":"Document","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/documents/{id}/thumbnail":{"get":{"summary":"Small preview image (accepts ?key=pk_live_… for <img src>)","parameters":[{"name":"id","in":"path","required":true,"description":"Document id or slug.","schema":{"type":"string"}}],"responses":{"200":{"description":"JPEG","content":{"image/jpeg":{}}}}}},"/documents/{id}/file":{"get":{"summary":"Signed link to the current file of an edition (JSON, or ?redirect=1 for a 302). Content access required.","parameters":[{"name":"id","in":"path","required":true,"description":"Document id or slug.","schema":{"type":"string"}},{"name":"lang","in":"query","required":false,"description":"Edition language code (e.g. en = IAST, hi, ta, te, kn, ru). Defaults to en, else the first edition.","schema":{"type":"string"}},{"name":"download","in":"query","schema":{"type":"string","enum":["1"]}},{"name":"redirect","in":"query","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"Signed URL","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/documents/{id}/video":{"get":{"summary":"Video player embed URL","parameters":[{"name":"id","in":"path","required":true,"description":"Document id or slug.","schema":{"type":"string"}},{"name":"lang","in":"query","required":false,"description":"Edition language code (e.g. en = IAST, hi, ta, te, kn, ru). Defaults to en, else the first edition.","schema":{"type":"string"}}],"responses":{"200":{"description":"Video","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/documents/{id}/text":{"get":{"summary":"Page-by-page text of a PDF edition","parameters":[{"name":"id","in":"path","required":true,"description":"Document id or slug.","schema":{"type":"string"}},{"name":"lang","in":"query","required":false,"description":"Edition language code (e.g. en = IAST, hi, ta, te, kn, ru). Defaults to en, else the first edition.","schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"integer"}},{"name":"to","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Pages","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/documents/{id}/chant":{"get":{"summary":"Chant & Read: recordings + every timed line with its boxes on this edition's pages","parameters":[{"name":"id","in":"path","required":true,"description":"Document id or slug.","schema":{"type":"string"}},{"name":"lang","in":"query","required":false,"description":"Edition language code (e.g. en = IAST, hi, ta, te, kn, ru). Defaults to en, else the first edition.","schema":{"type":"string"}}],"responses":{"200":{"description":"Chant timings","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/documents/{id}/meanings":{"get":{"summary":"Published line meanings, placed on this edition's pages","parameters":[{"name":"id","in":"path","required":true,"description":"Document id or slug.","schema":{"type":"string"}},{"name":"lang","in":"query","required":false,"description":"Edition language code (e.g. en = IAST, hi, ta, te, kn, ru). Defaults to en, else the first edition.","schema":{"type":"string"}}],"responses":{"200":{"description":"Meanings","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/documents/{id}/meanings/{key}":{"put":{"summary":"Write a line meaning (super admin token with meanings:write)","security":[{"oauth":["meanings:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Document id or slug.","schema":{"type":"string"}},{"name":"key","in":"path","required":true,"description":"Line key, e.g. 12:0","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"object","additionalProperties":{"type":"string"},"description":"Markdown per language code"},"status":{"type":"string","enum":["published","draft"]}}}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Delete a line meaning","security":[{"oauth":["meanings:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Document id or slug.","schema":{"type":"string"}},{"name":"key","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/documents/{id}/changes":{"get":{"summary":"Which pages changed in the current version vs the previous one","parameters":[{"name":"id","in":"path","required":true,"description":"Document id or slug.","schema":{"type":"string"}},{"name":"lang","in":"query","required":false,"description":"Edition language code (e.g. en = IAST, hi, ta, te, kn, ru). Defaults to en, else the first edition.","schema":{"type":"string"}}],"responses":{"200":{"description":"Changes","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/documents/{id}/embed":{"get":{"summary":"Ready-to-paste embed code (iframe + web component)","parameters":[{"name":"id","in":"path","required":true,"description":"Document id or slug.","schema":{"type":"string"}},{"name":"lang","in":"query","required":false,"description":"Edition language code (e.g. en = IAST, hi, ta, te, kn, ru). Defaults to en, else the first edition.","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer"}},{"name":"chant","in":"query","schema":{"type":"string","enum":["1"]}},{"name":"meanings","in":"query","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"Snippets","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/search":{"get":{"summary":"Search titles, folders and the text inside documents","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"text","in":"query","description":"0 to skip in-text search","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":50}},{"name":"locale","in":"query","required":false,"description":"Language for titles/descriptions in the response (falls back to English).","schema":{"type":"string"}}],"responses":{"200":{"description":"Results","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/me":{"get":{"summary":"The signed-in member (scope: profile)","security":[{"oauth":["profile"]}],"responses":{"200":{"description":"Member","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/me/library":{"get":{"summary":"The member's saved texts (scope: library)","security":[{"oauth":["library"]}],"responses":{"200":{"description":"Library","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/me/classes":{"get":{"summary":"The member's classes, homework, recordings sent + feedback (scope: classes)","security":[{"oauth":["classes"]}],"responses":{"200":{"description":"Classes","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/me/classes/join":{"post":{"summary":"Join a class with its code","security":[{"oauth":["classes"]}],"responses":{"200":{"description":"Joined","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/me/classes/{id}":{"delete":{"summary":"Leave a class","security":[{"oauth":["classes"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Left","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/classes":{"post":{"summary":"Start a class (tutors)","security":[{"oauth":["classes"]}],"responses":{"200":{"description":"Class","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/classes/{id}":{"get":{"summary":"A class (tutor: students, recordings, code; student: homework + own recordings)","security":[{"oauth":["classes"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Class","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/classes/{id}/homework":{"post":{"summary":"Set homework: verse range or line keys (tutors)","security":[{"oauth":["classes"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Homework","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/homework/{id}":{"delete":{"summary":"Remove homework (tutors)","security":[{"oauth":["classes"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/classes/{id}/recordings":{"post":{"summary":"Send a recording to the tutor (multipart audio + meta, or JSON audio_base64) — only when the member asks","security":[{"oauth":["classes:submit"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sent","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/submissions/{id}/recording":{"get":{"summary":"Signed link to a sent recording (sender or tutor)","security":[{"oauth":["classes"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Link","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/submissions/{id}/feedback":{"post":{"summary":"Tutor feedback on a recording (emails the student)","security":[{"oauth":["classes"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/me/practice":{"get":{"summary":"Practice progress (?doc= for per-line)","security":[{"oauth":["practice"]}],"responses":{"200":{"description":"Practice","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/me/notes":{"get":{"summary":"The member's notes on a text (?doc=)","security":[{"oauth":["notes"]}],"responses":{"200":{"description":"Notes","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/me/notes/{doc}/{key}":{"put":{"summary":"Save a highlight / bookmark / note on a line","security":[{"oauth":["notes"]}],"parameters":[{"name":"doc","in":"path","required":true,"schema":{"type":"string"}},{"name":"key","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/me/library/{id}":{"put":{"summary":"Save a text to the member's library","security":[{"oauth":["library"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Document id or slug.","schema":{"type":"string"}}],"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Remove a text from the member's library","security":[{"oauth":["library"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Document id or slug.","schema":{"type":"string"}}],"responses":{"200":{"description":"Removed","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}}}}