Author a template with AI
Ask your assistant to turn a document description into a reusable ShipPDF template. The assistant creates a draft, defines the data fields, and adjusts the layout through MCP. Once published, the template can generate PDFs with different data through MCP or the REST API.
Before you start
Connect your client with templates:write. Supply a project ID or grant projects:read so the assistant can find a project. Add templates:read if you want it to inspect existing published templates as references.
To generate a PDF after publishing, also grant documents:create and documents:read and make sure the workspace has generation credits.
Describe the document
Give the assistant the paper size, orientation, content sections, branding, dynamic fields, and representative data. State whether you want a draft for review or a published template.
Create an A4 portrait invoice template in project proj_example. Include a logo, billing address, invoice number, date, item table, subtotal, tax, and total. Read ShipPDF’s authoring guide first. Define the data schema and use my example invoice as sample data. Give me a preview and leave it as a draft for review.
1. Read the authoring guide
The assistant should call get_authoring_guide before building a document. It returns the workflow, supported layout rules, and a worked example. Use describe_schema for the exact shape of a document or a specific definition.
Authoring accepts short input: nodes need their type, plus children for containers, while omitted settings receive editor defaults. Sizes need explicit units, such as pt, mm, or in. Use full data paths such as invoice.items.description when binding fields.
2. Create or resume a draft
Use create_template with project_id, name, and document. To resume an existing template, use get_draft_template with its template_id.
The response includes:
| Field | How to use it |
|---|---|
template_id | Identify the template in later calls. |
lock_version | Pass the latest value when editing or replacing the draft. |
pages | Check page size, margins, and content area. |
publishable | true means the publish check passed; false means problems remain; null means the check could not run. |
problems | Resolve reported issues, including affected nodes and locations where provided. |
mcp_preview_url | Open the saved draft with sample data for visual review. |
A draft can be saved with publish problems. Saving it does not make it available for generation.
3. Edit and preview
Use edit_template to change part of a draft. It accepts an ordered list of operations:
| Operation | Purpose |
|---|---|
add | Add a node under a parent. |
update | Change a node’s fields or settings. |
move | Move a node to a parent and position. |
remove | Remove a node. |
set_data_schema | Replace the template’s data schema. |
set_sample_data | Replace the sample data used for preview. |
Read existing node IDs from the draft and pass the latest lock_version. Operations are applied all or nothing: if one fails, none are saved. Use update_template when replacing the entire draft document or changing its name is simpler.
If another edit changes the draft first, ShipPDF returns a lock_version_conflict with the current draft. Review it, reapply the intended changes, and retry with the returned version.
Open mcp_preview_url to review the saved layout. The link lasts about 15 minutes; call get_draft_template to obtain another. If your client has browser tools, ask it to inspect the preview through its normal browser permission flow. Otherwise, open the link yourself and describe the changes you want.
The preview uses sample data and spends no generation credits. It helps review the layout but does not verify final PDF pagination. Test the finished PDF with representative data, including long tables and text.
Check accuracy with Claude in Chrome or ChatGPT in Chrome
Give your assistant browser access so it can open the preview, scroll through the document, and inspect the visible layout as it authors the template. This helps it catch clipped text, overlapping elements, incorrect spacing, and missing or incorrectly bound data that schema validation alone may not reveal.
- Claude in Chrome: install and enable the extension, then allow Claude to interact with the ShipPDF preview. Follow the Claude in Chrome setup guide.
- ChatGPT in Chrome: connect the ChatGPT browser extension to the desktop app, select Chrome with an
@-mention, and allow access to the preview site. Follow the ChatGPT browser extension guide.
Keep the ShipPDF MCP connection available in the same conversation. MCP provides the authoring tools; the browser extension lets the assistant see the result. Ask it to follow this review loop:
- Open the latest
mcp_preview_urland compare the layout and displayed values with your requirements and sample data. - Check alignment, margins, typography, images, table columns, and long text. Use the preview’s inspection controls to identify affected nodes.
- Correct issues with
edit_template, then reload the preview and check the saved changes. Repeat with representative data, including long tables and optional fields. - After publishing, generate a test PDF and inspect the finished file for page breaks, overflow, and data accuracy. Each new test generation uses a credit.
For example:
Use ShipPDF MCP to author the template and Chrome to check it visually. Open the draft preview, compare it with my reference and sample data, fix layout or binding errors, and check the preview again. Leave the draft for my review before publishing.
If browser access is unavailable, open the preview yourself and share screenshots or describe the issues. Visual review helps find mistakes; also verify the final PDF’s values against the source data.
Add images
Use import_asset with a public PNG, JPEG, or WebP URL, up to 10 MB. It returns an asset_id. Reference that image with an imageSource of type asset, using the returned ID as assetId. Private and loopback URLs are blocked.
4. Publish the template
After resolving the draft’s problems and reviewing its layout, call publish_template. It refuses drafts with outstanding publish problems and creates an immutable revision on success.
Publishing changes what future generations of this template produce. Later draft edits do not affect that revision until you publish again. If you requested a draft for review, have the assistant stop before publishing.
5. Generate a PDF
Use the published template ID with generate_document, then poll get_document. Follow Generate a PDF from an existing template for the full flow, including safe retries and download links.
See Limits and errors for validation problems and edit conflicts.