API reference
Send Authorization: Bearer <project key> from your server. The JSON body limit is 1 MiB, with a 4 MiB allowance for /layout/paginate. Browsers can use the returned share links or a short-lived credential for embedded tables.
Text operations, hosted media uploads and replacements, and table creation and row writes accept Idempotency-Key. Retry with the original request under the same key. A changed request or a pending operation can return 409.
Currently free · API use within the limits costs nothing. Usage is recorded and limits are shared across your projects.
Text usage counts Unicode code points. Requests exceeding the monthly free allowance return 429 with developer_free_quota_exceeded. Error bodies include error.code and error.message.
Reflow an existing HTML design
Generate short and long editions of the same design. As copy changes length, the fields below it move with their original spacing. Each record gets its own editable HTML.
Reflow a batch of records
POST/api/developer/v1/layout/reflow- Request
- Supply the design
html, itsdesignWidthin pixels, androws. Each record has a uniqueidand acontentobject keyed by field ID. You can also supply a previously measuredtemplatein place of the HTML and width. - Response
- Each row returns its
id, continuous editablehtml, measuredheight, andlayoutfor printing. SupplypageHeightin pixels to get anoverflowflag.
Measure a reusable template (optional)
POST/api/developer/v1/layout/finalize-contract- Request
- Send the annotated
htmland itsdesignWidth. - Response
- Save the returned
templateto reuse its measurements across reflow requests.
Use inline styles for the position and width of each field. Mark editable fields with data-mp-field and pinned decorations with data-mp-fixed. Send 1–200 rows per batch. Embed PNG, JPEG, or WebP images in the template.
Paginate a reflowed document
Print a reflowed record with the Magic Press print engine. Add running headers, footers, and page numbers while the content continues across pages.
Print continuous HTML to PDF
POST/api/developer/v1/layout/paginate- Request
- Pass
htmlandlayoutfrom the same reflowed record. Setpage.heightMmfor the paper height andpage.marginsMmfor top, right, bottom, and left margins. Optionalpage.headerandpage.footeraccept text and the tokens{{pageNum}}and{{totalPages}}. - Response
- Decode
pdfBase64to save the PDF. The response includesmediaTypeandpageCount. Keep the original HTML to edit or print with your own engine.
Batch document generation
Use your HTML template for up to 200 records at once. Every result follows the same design, and you can update a single record.
Render rows with a template
POST/api/developer/v1/layout/template-batch- Request
- JSON. Required
template(version: 1,html,fields) androws. Each row needs a uniqueidandcontentmatching the template fields exactly, with plain-text values. Send 1–200 rows with up to 1,000,000 characters total. - Response
- Each item in
rowshasidandhtml, alongsidecharacterCountandoperationId. Find a rendered field through itsdata-mp-fieldattribute.
You can supply your own template. Put each {{MP:fieldName}} placeholder once in an HTML text node. The service applies the template directly to the rows submitted in the request.
Normalize copy by example
Show one raw note and its edited fields. The API applies that writing style to the other notes and returns fields ready for your template.
Turn raw notes into matching fields
POST/api/developer/v1/content/normalize-batch- Request
- Send
example.source(one raw note),example.content(1–20 edited text fields), and 1–50rows, each with a uniqueidand its ownsource. Optionalinstructionscan specify conventions such as 24-hour times. Up to 20,000 input characters total. - Response
- Returns
rowsin input order. Each carries the originalidand acontentobject with the example’s field names. Missing values are empty strings. The response includesoperationIdandcharacterCount.
The copy example sets the fields and writing style. To render the result, pass the returned rows to template batch with an HTML template using the same fields. Each step meters its own input characters. Send structured copy straight to template batch.
Paginate long-form text
Flow sections of different lengths across columns and pages in a single printable document.
Generate paginated HTML
POST/api/developer/v1/layout/publication- Request
- Send a document
titleand 1–200sections, each with a uniqueid, aheading, and an array of plain-textparagraphs. Optionallanguageacceptsenorzh-CN. Usetemplateto choose A4/A5, one or two columns, margins, column gap, type size, and accent color. Up to 100,000 input characters. - Response
- Returns complete print-ready
html,pageCount, apageslist with section IDs on each page,characterCount, andoperationId. Open the HTML in a browser to print it or save it as a PDF.
The default is A4 with two columns. The renderer measures text in the browser and continues it into the next column or page. Metering counts the document title, section headings, and paragraph text once.
AI design
When you need a new design, turn the first record and a brief into HTML and a reusable template.
Generate a design
POST/api/developer/v1/layout/ai-design- Request
- JSON. Required
contentaccepts a string or an object with 1–100 text fields. Optionalrequirementsdescribes the design and allows up to 10,000 UTF-16 code units. Content and requirements together must total 1–100,000 characters. - Response
html,template,characterCount, andoperationId. Pass the returnedtemplateto the batch endpoint to reuse the design.
Fixed layout
Fit text at the largest size the original frame can hold.
Render positioned frames
POST/api/developer/v1/layout/fixed- Request
- JSON. Required
page(width,height),frames(id,type,left,top,width,height), androws(idandvalueskeyed by frame ID). Send 1–100 frames and 1–200 rows with up to 1,000,000 characters. - Response
- Each row returns
id,html, and text-frame measurements (frameId,scale,fontSizes). Also returnsfonts,imageLoading,characterCount, andoperationId.
Use CSS pixels. Frames can specify rotation. Text styles cover font family, size, color, weight, italic, alignment, line height, runStyles, and ranges. Supply an HTTPS URL for image frames with fit: "cover" or "contain". The rendered page loads the images.
Word to HTML
Extract text, embedded images, tables, and supported Word equations into flowing HTML.
Upload a DOCX
POST/api/developer/v1/documents/docx-to-html- Request
multipart/form-data. Requiredfilemust be a non-empty.docxup to 10 MiB.- Response
html,assets,stylesheetUrl,warnings,characterCount,documentId,resultUrl, andpreviewUrl. Load the returned stylesheet to display equations when embedding the HTML.
Retrieve or delete a result
GETDELETE/api/developer/v1/documents/results/{id}- Request
- The owning project’s API key and the
documentIdin the path. - Response
GETreturns the same result shape as conversion.DELETEremoves the result and its assets, returns204, and invalidates the share links.
Open the web preview
GET/api/developer/v1/documents/public/{id}- Request
- Open the returned
previewUrl, which includes itstoken. - Response
- An HTML page ready to open in a browser.
Read an extracted image
GET/api/developer/v1/documents/public/{id}/assets/{assetId}- Request
- Use the full address in
assets[].urlwith itstoken. - Response
- The image file. Reads are metered by bytes transferred.
Columns, facing pages, and floating objects may change in the HTML. Check warnings. Preview and asset share links have no fixed expiry while retained. Anyone with the full link can open it. Retained results and assets accrue storage usage over time.
Media QR codes
Get a playback link and a QR code that can stay in use when you replace hosted media.
Upload a hosted file
POST/api/developer/v1/media- Request
multipart/form-data. Requiredfileaccepts MP3, M4A, WAV, OGG, MP4, or WebM up to 50 MiB.- Response
mediaId,kind,bytes,playbackUrl,qrCodeDataUrl, andhosted: true.
Generate a QR code for your own URL
POST/api/developer/v1/media- Request
- JSON. Required
playbackUrlmust be an HTTPS URL up to 1,024 characters, without a username or password. - Response
playbackUrl,qrCodeDataUrl, andhosted: false. The QR code points to your URL. Your service hosts and updates the content there.
Replace a hosted file
PATCH/api/developer/v1/media/{id}- Request
- The owning project key, the
mediaIdin the path, and a new multipartfileusing the upload formats and limit. - Response
- Updated media type and size. The media ID, playback URL, and QR code stay the same.
Delete a hosted file
DELETE/api/developer/v1/media/{id}- Request
- The owning project key and the
mediaIdin the path. - Response
- Returns
204. The original playback link and QR code stop working, and the file stops accruing storage usage.
Open the player
GET/api/developer/v1/media/{id}/play- Request
- Open the returned
playbackUrl, which includes itstoken. - Response
- A browser page with a media player.
Read media content
GETHEAD/api/developer/v1/media/{id}/content- Request
- Use the full media link and
tokenfrom the player page. A single byteRangeis supported. - Response
- The media byte stream or its headers.
GETis metered by bytes transferred.
Anyone with the full playback URL can open it. The link has no fixed expiry while the file is retained. Hosted media is metered by storage size and time and by bytes transferred. Insufficient credit can interrupt playback.
Embedded tables
Embed an editor where users can paste Word documents or text-based PDFs into cells, generate plain text or HTML with AI columns, and fill rows vertically.
Issue an embed credential
POST/api/developer/v1/tables/embed-credentials- Request
- JSON. Required
customerIdanduserIdcome from your system, up to 128 characters each. Derive both from the signed-in user’s session on your server. - Response
embedUrl,token,expiresAt,projectId, andcustomerId. Credentials last 5 minutes. UsemountTablein the browser and renew through your server.
Check an embed credential
GET/api/developer/v1/tables/embed-credentials- Request
- Use the short-lived embed credential in
Authorization: Bearer <token>. - Response
projectId,customerId,userId, andexpiresAt. Revoking the issuing project key also invalidates its credentials.
List a customer’s tables
GET/api/developer/v1/tables- Request
- Required query parameter
customerId. Optional cursorafter. - Response
tablesandnextCursor, up to 100 tables per page.
Create a table
POST/api/developer/v1/tables- Request
- Required query parameter
customerId. JSON requiresname(up to 160 characters) andcolumns(1–40 non-empty labels, up to 120 characters each). - Response
- Returns
201, withid,name, andcolumns. Columns start as text.
Read a worksheet
GET/api/developer/v1/tables/{id}- Request
- Required table
idand query parametercustomerId. Optionalsheetandoffsetstart at zero.limitis 1–100 and defaults to 50. - Response
sheets,columns,rows, andtotalRows, among other fields. Rowcellsare keyed by column ID.
Append or update rows
PATCH/api/developer/v1/tables/{id}- Request
- Required table
idand query parametercustomerId. JSON requiressheetIdand 1–30rows. Each row hascellskeyed by column ID with strings, numbers, booleans, ornull. Supply a rowidto update it or omit it to append. - Response
appendedRowIdsandedits.
Read a table attachment
GETHEAD/api/developer/v1/table-assets/{id}- Request
- Use the full attachment link and
tokenreturned by the embedded editor. - Response
- Attachment bytes or response headers.
GETis metered by bytes transferred.
Data is isolated by project and customer. Users within one customer share a workspace and use their existing account in your product. Pass locale: "en" or locale: "zh-CN" to the SDK’s mountTable helper. By default it follows the host page or browser language. The editor supports Word and PDF paste, HTML or plain-text AI output, and vertical fill. AI columns use the model key configured in the table. Storage and transfer are metered.
Resource management
List stored resources by project and delete what you no longer need.
List project resources
GET/api/developer/v1/resources- Request
- Project key and optional
aftercursor. - Response
resourcesandnextCursor. Each page has up to 100 entries, including media, documents, tables, and attachments.bytesis a string.
Delete a stored resource
DELETE/api/developer/v1/resources/{id}- Request
- The owning project’s key and the resource
idreturned by the list. - Response
- Returns
204. The deleted resource stops accruing storage usage.