API reference

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, its designWidth in pixels, and rows. Each record has a unique id and a content object keyed by field ID. You can also supply a previously measured template in place of the HTML and width.
Response
Each row returns its id, continuous editable html, measured height, and layout for printing. Supply pageHeight in pixels to get an overflow flag.

Measure a reusable template (optional)

POST/api/developer/v1/layout/finalize-contract
Request
Send the annotated html and its designWidth.
Response
Save the returned template to 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 html and layout from the same reflowed record. Set page.heightMm for the paper height and page.marginsMm for top, right, bottom, and left margins. Optional page.header and page.footer accept text and the tokens {{pageNum}} and {{totalPages}}.
Response
Decode pdfBase64 to save the PDF. The response includes mediaType and pageCount. 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) and rows. Each row needs a unique id and content matching the template fields exactly, with plain-text values. Send 1–200 rows with up to 1,000,000 characters total.
Response
Each item in rows has id and html, alongside characterCount and operationId. Find a rendered field through its data-mp-field attribute.

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–50 rows, each with a unique id and its own source. Optional instructions can specify conventions such as 24-hour times. Up to 20,000 input characters total.
Response
Returns rows in input order. Each carries the original id and a content object with the example’s field names. Missing values are empty strings. The response includes operationId and characterCount.

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 title and 1–200 sections, each with a unique id, a heading, and an array of plain-text paragraphs. Optional language accepts en or zh-CN. Use template to 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, a pages list with section IDs on each page, characterCount, and operationId. 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 content accepts a string or an object with 1–100 text fields. Optional requirements describes 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, and operationId. Pass the returned template to 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), and rows (id and values keyed 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 returns fonts, imageLoading, characterCount, and operationId.

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. Required file must be a non-empty .docx up to 10 MiB.
Response
html, assets, stylesheetUrl, warnings, characterCount, documentId, resultUrl, and previewUrl. 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 documentId in the path.
Response
GET returns the same result shape as conversion. DELETE removes the result and its assets, returns 204, and invalidates the share links.

Open the web preview

GET/api/developer/v1/documents/public/{id}
Request
Open the returned previewUrl, which includes its token.
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[].url with its token.
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. Required file accepts MP3, M4A, WAV, OGG, MP4, or WebM up to 50 MiB.
Response
mediaId, kind, bytes, playbackUrl, qrCodeDataUrl, and hosted: true.

Generate a QR code for your own URL

POST/api/developer/v1/media
Request
JSON. Required playbackUrl must be an HTTPS URL up to 1,024 characters, without a username or password.
Response
playbackUrl, qrCodeDataUrl, and hosted: 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 mediaId in the path, and a new multipart file using 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 mediaId in 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 its token.
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 token from the player page. A single byte Range is supported.
Response
The media byte stream or its headers. GET is 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 customerId and userId come 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, and customerId. Credentials last 5 minutes. Use mountTable in 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, and expiresAt. 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 cursor after.
Response
tables and nextCursor, up to 100 tables per page.

Create a table

POST/api/developer/v1/tables
Request
Required query parameter customerId. JSON requires name (up to 160 characters) and columns (1–40 non-empty labels, up to 120 characters each).
Response
Returns 201, with id, name, and columns. Columns start as text.

Read a worksheet

GET/api/developer/v1/tables/{id}
Request
Required table id and query parameter customerId. Optional sheet and offset start at zero. limit is 1–100 and defaults to 50.
Response
sheets, columns, rows, and totalRows, among other fields. Row cells are keyed by column ID.

Append or update rows

PATCH/api/developer/v1/tables/{id}
Request
Required table id and query parameter customerId. JSON requires sheetId and 1–30 rows. Each row has cells keyed by column ID with strings, numbers, booleans, or null. Supply a row id to update it or omit it to append.
Response
appendedRowIds and edits.

Read a table attachment

GETHEAD/api/developer/v1/table-assets/{id}
Request
Use the full attachment link and token returned by the embedded editor.
Response
Attachment bytes or response headers. GET is 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 after cursor.
Response
resources and nextCursor. Each page has up to 100 entries, including media, documents, tables, and attachments. bytes is a string.

Delete a stored resource

DELETE/api/developer/v1/resources/{id}
Request
The owning project’s key and the resource id returned by the list.
Response
Returns 204. The deleted resource stops accruing storage usage.