cancel_import
ChatGPTStops a book import for good: no further chapters are imported and the import cannot be resumed — re-importing means preparing it again from the source. Chapters already saved stay (never deleted). Single-document imports are accepted within seconds and cannot be cancelled (import_not_cancellable) — the document can be deleted in the app. import_busy means the book is being advanced at this instant; try again in a moment.
commit_import
ChatGPTSaves a prepared plan — or a prepared batch — into a space. The Save-to-Twinbook card calls this itself when the learner taps; from chat it is the learner's explicit request in words ("yes, save it to Algebra 1", "save them all to Thermo"). ONE item: planId. SEVERAL items: batch { batchId, items: [{ planId, position }] } — the planIds from that prepare_import, in the user's study order (position 1 = first); leave out what the user excluded; book-length items cannot be in a batch (save them with planId alone). Destination: spaceId (one of the learner's own spaces) or newSpace { title, productMode, cover } to create a space and save into it in one step; a plan prepared with a destination needs neither. Returns accepted within seconds; a batch uploads its items in order in the background (one importId for all; get_import_status lists them as parts). A plan is imported at most once: calling again (same key, or any key for the same plan) returns the same import and never charges or creates twice. On a timeout, call again with the SAME key.
create_space
ChatGPTCreates a new private, free study space for the learner. productMode is the subject area that shapes the notes — general, healthcare, technology (coding / IT), stem (science & math) — only values listed in get_upload_context.productModes (defaultProductMode is what the app would preselect): infer it from the material or ask, and say which you chose. A cover picture is generated automatically from the name and description unless coverPrompt (a short description of the picture) or coverImage (a picture the user attached) is given. Use only when the user asks for a new space or none is suitable. Reports the plan's space limit if reached.
get_cover_preview
ChatGPTStatus of a cover preview: generating, ready (with url) or failed. The card polls this after preview_cover. Not for the model to call.
get_import_status
ChatGPTReports an import's state: outcome (processing, materials_ready, saved_without_ai, partially_completed, failed, cancelled), stage (a book: mapping_chapters → importing_chapters → done), counts and per-part status, canRetry / canCancel, and a link to open it in Twinbook.
get_profile
ChatGPTReturns the connected Twinbook learner's stable opaque id, name and email. Use it to confirm which account is linked.
get_upload_context
ChatGPTReturns the learner's plan, remaining monthly allowance (pages, uploads, AI credits), per-import limits (perImport.maxQuickPages: a PDF up to that many pages becomes one chapter; perImport.maxImportPages: longer documents up to that are processed as several chapters; perImport.maxBookPages with booksEnabled: longer documents import as books — chapter map first, then chapter by chapter, each chapter one upload; urlsEnabled / officeEnabled / youtubeEnabled: which link and file kinds this server accepts), the content kinds and note styles the app offers, and whether AI terms are accepted. Call before planning an import.
list_spaces
ChatGPTLists the learner's study spaces, most recently opened first, with canUpload (only spaces the learner created accept imports), chapter count, subject area and learning mode. Optional query filters by title. Resolves a space the user named to its id for prepare_import.destination; when no space was named, the Save-to-Twinbook card lists the spaces for the learner, so no lookup is needed.
prepare_import
ChatGPTStages and inspects what the user wants saved and returns a plan per item: real page count, how it will be processed (processing: quick = one chapter; chapters = Twinbook detects chapters itself; book = chapter map first, then chapter-by-chapter import, each chapter one upload — estimatedUsage.uploadsEstimated; save_only = stored without AI), estimated usage, warnings, blockedBy, a planId, and destinations (the learner's own spaces + whether a new one may be created). ONE item: exactly one of text, url, file. SEVERAL items (a reading list, a course plan, all the attachments): sources[] in study order — one call, up to 20 items (get_upload_context.perImport.maxBatchItems) — which returns a batchId and items[] (position, planId, error for an item that could not be prepared, includedByDefault); the others still save. The result is shown on the Save-to-Twinbook card: the items with a checkbox each and their order (for a batch), the learner's own spaces, and a New space option (name + subject area); the learner's tap on the card performs the save (the card calls commit_import). destination.spaceId is for a space the user named (it is highlighted on the card). What the assistant has after this call is a summary to relay — the title(s), how each lands, which items are unavailable and why, which are saved on their own — while the learner completes the save on the card; commit_import from chat is for an explicit request in words. Links are sent as the url itself (web page, PDF/Word/PowerPoint link, YouTube) and fetched by Twinbook; a chat share link is refused, that conversation goes as text. A book-length document (over the chapter limit) is planned but excluded from a batch (blockedBy book_in_batch): it is saved on its own with its planId.
preview_cover
ChatGPTRenders a cover picture for a space that does not exist yet, from a short prompt, in the app's own cover style. The Save-to-Twinbook card calls this itself when the learner creates a new space and on Refresh; it answers at once with status generating and the card polls get_cover_preview. One image generation per call, capped per import and per day (cover_limit_reached). Not for the model to call.
retry_import
ChatGPTResumes a paused book import (failed chapters are re-queued, finished chapters are kept) or re-submits a single upload that failed for a transient reason (canRetry true). Idempotent while the import is running. Returns import_not_retryable when nothing can be retried — then a fresh prepare_import is needed.
