attach_data_source
ChatGPTAttach a data source to a catalogue under a variable, or change the variable of one already attached. data.transform.js then reads it as files["<variable>"]. If the spreadsheet's cells hold image references, the library they point into is attached automatically and the result says so — without it every one of those images resolves to nothing and the catalogue prints without its pictures, silently.
attach_media_source
ChatGPTAttach a media source to a catalogue under a variable, or change the variable of one already attached. data.transform.js then reads it as mediaSources["<variable>"].
create_component
ChatGPTCreate one or more reusable components on this document. Prefer creating components first and then composing them in template.hbs. Creating a component does NOT put it on a page — the entry has to place a page layout for anything to render. Every component is created unlocked; locks are the user's to set. The whole batch is validated together, so a parent and the child it calls can be created in one call regardless of array order, and either everything commits or nothing does. Changes are saved to the catalogue and can queue a thumbnail render that fetches external assets referenced by its content.
create_data_source
ChatGPTCreate a data source from a CSV or spreadsheet you provide as base64. Best for data you have generated — a CSV you assembled from a transform, an export you built. The bytes travel through your own context, roughly four characters per three bytes, so keep it under about 256 KB; a spreadsheet that already exists on disk is far cheaper to upload in the app. Hard limit 4.0 MB. Creating it does not attach it — call attach_data_source next. NOTE: pictures embedded in spreadsheet cells are NOT extracted on this path; that only happens when a workbook is uploaded through the app.
create_document
ChatGPTCreate a new catalogue from the blank starter — the same four root files and starter components the dashboard's 'Add New' produces, which are a working tour of Paged.js rather than empty files. It is created in component mode with no data or media sources attached; use attach_data_source or attach_media_source, then edit the source with update_file and the component tools.
create_media_source
ChatGPTCreate an empty media source — a library that images are uploaded into and that a catalogue attaches under a variable. Upload into it with upload_media_file, then attach it with attach_media_source.
delete_component
ChatGPTDelete one component. Refused if anything still calls it — including a component the entry cannot reach — and refused if it is locked or protected. Remove the {{> name}} calls from its callers first, then delete. Nothing is ever cascade-deleted and no caller's source is edited on your behalf. Changes are saved to the catalogue and can queue a thumbnail render that fetches external assets referenced by its content.
detach_source
ChatGPTStop a catalogue reading a data source or media source. The source itself and its files are left alone — this only removes the attachment, so it is reversible with attach_data_source or attach_media_source. Anything in data.transform.js still reading that variable will get undefined, so check the transform first.
export_pdf
ChatGPTQueue a PDF render of a catalogue. Returns a job immediately — rendering a long catalogue takes minutes — so poll get_export with the returned jobId until status is 'done' or 'failed'. This consumes the workspace's monthly export quota. If an identical export is already running, you join it rather than starting a second. Rendering may fetch external assets referenced by the catalogue.
find_file_in_media_source
ChatGPTSearch for files by name (case-insensitive partial match) within a media source. Returns matching files with their full paths and URLs, one page at a time: at most 100 matches per call by default (500 max), with "totalMatches" reporting the full count and "nextOffset" continuing when "hasMore" is true. Narrow the query rather than paging through a broad one. Use this when you need to find a specific image by name across all folders.
find_folder_in_media_source
ChatGPTSearch for folders by name (case-insensitive partial match) within a media source. Returns matching folders with their paths, one page at a time: at most 100 matches per call by default (500 max), with "totalMatches" reporting the full count and "nextOffset" continuing when "hasMore" is true. Use this when you need to locate a specific folder.
get_catalogue_guide
ChatGPTThe full account of how catalogues work here — the same material the in-app assistant works from. Read the relevant topic BEFORE writing template.hbs, styles.css or a component: it covers the component model and locks, the Paged.js page-geometry traps that produce blank pages and white bands, the tagging contract the editor's Layers panel is built from, and how to resolve pictures stored inside spreadsheet cells. Ask for one topic rather than 'all' unless you are starting from nothing — 'all' is long.
get_document
ChatGPTEverything about one catalogue except its source: which of the four root files have content, the component registry as summaries (name, type, what calls what, locks and inherited protection), the attached data and media sources with the variable each resolves under, and the current contentRevision. Call this before editing — it is the cheapest way to see the shape of a catalogue, and the summaries tell you which definitions an edit will be refused on.
get_export
ChatGPTCheck a queued PDF export, or list a catalogue's recent exports. Give a jobId to poll one — status goes queued → running → done or failed, and pagesSoFar advances while it renders. Omit the jobId to see the ten most recent. A finished export comes back with a downloadUrl the user can open while signed in. In inline rendering mode, this also resumes the render queue; pending jobs may write export files and fetch external assets referenced by catalogues.
get_more_tools
ChatGPTCheck for additional tools whenever your task might benefit from specialized capabilities - even if existing tools could work as a fallback.
list_data_sources
ChatGPTList all data sources attached to this document, including their variable names, column headers, and row counts. A source whose spreadsheet had pictures embedded in its cells also reports "cellImages": those cells hold [cattalog-media-ref:...] tokens naming images in a media source, and the report says which media source variable resolves them — or that it is not attached yet.
list_documents
ChatGPTList the catalogues in this workspace, newest-edited first. Returns each one's id, name, tags, when it was last edited and its current contentRevision. Start here: every other document tool takes an id from this list. Archived catalogues are excluded unless you ask for them.
list_files_in_media_source
ChatGPTList files and folders at a specific path within a media source, one page at a time. Returns names, urls, mimeTypes, and whether each entry is a folder. Use path "/" for root level. Entries are paged folders-first under a single cursor: at most 100 per call by default (500 max), and when "hasMore" is true you call again with the returned "nextOffset". "totalFolders"/"totalFiles" always report the full counts at the path. Use this to browse the folder structure of a media source.
list_media_sources
ChatGPTList all media sources attached to this document, including their variable names, folder/file counts, and top-level structure. At most 50 top-level folder names are listed per source; use list_files_in_media_source on path "/" to browse the rest. Use this first to discover what media is available.
list_workspace_sources
ChatGPTEvery data source and media source in this workspace, whether or not it is attached to anything. This is what you call before attach_data_source or attach_media_source — list_data_sources and list_media_sources show only what one catalogue already has.
read_component
ChatGPTInspect this document's components. mode "list" returns summaries — name, type, what each calls and is called by, whether the entry can reach it, its explicit lock and any inherited protection — without any source. mode "read" returns one component's owned source. Read before editing: a summary is not the code, and protection decides whether an edit will be accepted at all.
read_data_source_full
ChatGPTRead rows from a data source, one page at a time. Returns at most 100 rows by default (500 max, and fewer when the rows are wide). When "hasMore" is true, call again with the returned "nextOffset" to continue. Only use this when the preview is insufficient — prefer read_data_source_preview, and prefer run_data_transform over paging through a whole sheet to inspect it.
read_data_source_preview
ChatGPTRead the first 10 rows of a specific data source by its variable name. Use this to understand the structure and sample data before writing code.
read_file
ChatGPTRead the current content of one of the four root files. Use this before making edits to ensure you have the latest user-updated content. The returned contentRevision is the token to pass back to update_file and to the component tools — it is how a write proves it was built from the source that is actually stored.
replace_data_source
ChatGPTReplace the file behind an existing data source, keeping its id. Every catalogue already reading it keeps its attachment and its variable, so a transform reading files['products'] goes on working — which is the whole reason to use this rather than creating a second source. Same base64 limits and the same cell-image caveat as create_data_source. The old stored file is deleted; previous cell-image bindings are cleared and their deletion locks are released.
run_data_transform
ChatGPTExecute a data.transform.js script server-side and return its output along with any console.log/warn/error messages. Use this to test and debug your data transform code before committing it with update_file. The code must use the same export default function dataTransform({ files, mediaSources }) { ... } signature. The output is a SHAPE CHECK, not the data: anything larger than a few thousand characters comes back summarised — arrays as a length plus the first few items, objects cut at 20 keys and 3 levels deep, long strings cut — with a "note" saying so. Console output is capped the same way. Use it to confirm the structure and spot errors, not to read a catalogue.
screenshot_pages
ChatGPTRender pages of a catalogue in headless Chromium and return them as images — the same layout pass the PDF export uses, so what you see is what prints. This is how you check your own work after an edit. Ask for up to 6 pages in ONE call: a call paginates once, up to the highest page requested, so capturing pages 55-58 together costs a quarter of what four separate calls do. Pages that do not exist are reported in "missing" rather than silently dropped. Screenshots come from what is STORED — make your edit with update_file or the component tools first. Rendering may fetch external assets referenced by the catalogue and writes render diagnostics.
update_component
ChatGPTChange the owned source or metadata of existing components. Every source part you provide is COMPLETE content, not a diff; an omitted part is left unchanged and an empty string clears it. Name, type and lock state cannot be changed. A protected component is refused with the name of what protects it — do not work around that by cloning it or overriding it from elsewhere; say so and let the user unlock it. Changes are saved to the catalogue and can queue a thumbnail render that fetches external assets referenced by its content.
update_file
ChatGPTUpdate one of the four root files. Always provide the COMPLETE file content, not a partial diff. The content is parsed before it is stored — if it has a syntax error, or if the composition is invalid, the file is NOT updated and the error is returned to you. Otherwise it is reformatted, committed, and applied to the live editor immediately, so you can screenshot the preview afterwards to check your work. Only these four names are accepted: a path like components/product-card/template.hbs is not a file and cannot be written here — use update_component. Changes are saved to the catalogue and can queue a thumbnail render that fetches external assets referenced by its content.
upload_media_file
ChatGPTUpload one image into a media source, as base64. Best for something you generated — an SVG you wrote, a small chart. The bytes travel through your own context, so keep it under about 256 KB; a folder of photographs is far cheaper to drop into the app, which uploads them in parallel without them passing through a model at all. Hard limit 4.0 MB. Any image type except GIF, which has no meaning in a print layout.
whoami
ChatGPTReport the account, workspace, role and permissions this access token resolves to. Takes no arguments. Use it to confirm the connection is working and to find out which workspace you are about to act on.
