Designing documents

Themes, fonts, colours, cover pages with photos, columns, callouts and images: make documents that look like your brand.

Block templates are laid out by squiggli, so they can look as polished as anything from a design tool: a cover page with a photo fading into your colour, your fonts, coloured headings, label-and-value details, tinted callouts and both parties signing side by side. Everything here works the same from the editor, the API and your AI agent.

The fastest way: a starter

Start from a finished design and change what you need. GET /v1/templates/starters lists them with their full blocks and theme.

curl https://squiggli.billy-965.workers.dev/v1/templates \
  -H "Authorization: Bearer $SQUIGGLI_API_KEY" -H "Content-Type: application/json" \
  -d '{ "starter": "statement-of-work", "name": "Website build SOW", "theme": { "accent_color": "#0f766e", "heading_color": "#0f766e" } }'

Anything you send overrides the starter: theme merges with its theme, blocks replaces its blocks.

Themes

A theme sets the look of the whole document. Every setting is optional.

"theme": {
  "font": "roboto",
  "heading_font": "poppins",
  "heading_color": "#1e88e5",
  "text_color": "#141a2e",
  "accent_color": "#0a5ce0",
  "font_size": 10.5,
  "line_height": 1.6,
  "page_size": "A4",
  "margin": 52,
  "header_logo": true,
  "page_numbers": true
}

Fonts

helvetica, inter, roboto, poppins, montserrat, open-sans, lora, merriweather, playfair-display, instrument-sans, familjen-grotesk. Lora, Merriweather and Playfair Display are serifs. All but Helvetica are Google Fonts under the SIL Open Font Licence, embedded in the PDF so it looks the same everywhere. Custom fonts also cover accented and non-Latin characters that Helvetica can't.

Colours

Colours are hex: #1e88e5, 1e88e5 or the short #18e.

Cover page

A full page with a title, an optional photo across the top that fades into the background colour, text under the title, and your logo at the bottom. Put it first.

{
  "type": "cover",
  "title": "Statement of Work",
  "subtitle": "Website rebuild",
  "body": "**Prepared for:**\n{{client.name}}\n{{client.company}}",
  "image_url": "https://images.example.com/office.jpg",
  "image_height": 0.42,
  "background_color": "#0a5ce0",
  "text_color": "#ffffff",
  "logo": true
}

image_url takes an https link to a PNG or JPEG, or an uploaded image's id. logo is true for your business logo, false for none, or another image.

Rich text

Paragraphs, details, callouts, list items, table cells and the cover body understand **bold**, *italic* and line breaks (\n), along with {{variables}}. Put a backslash before a * to print it.

Details

Label and value lines, the clearest way to show the terms of a deal:

{ "type": "details", "items": [
  { "label": "Project fee", "value": "{{fees.amount}} plus GST" },
  { "label": "Target delivery", "value": "{{delivery.date}}" }
] }

Callouts

Text in a tinted box, for a note that must not be missed. The tint comes from the accent colour unless you set background_color.

{ "type": "callout", "text": "Only the work listed above is included." }

Columns

Two or three columns side by side. The classic use is the parties block: each party's details above their own signature.

{ "type": "columns", "columns": [
  [ { "type": "paragraph", "text": "**{{provider.company}}**\nABN: {{provider.abn}}" },
    { "type": "spacer", "height": 24 },
    { "type": "signature", "role": "provider" } ],
  [ { "type": "paragraph", "text": "**{{client.company}}**\nABN: {{client.abn}}" },
    { "type": "spacer", "height": 24 },
    { "type": "signature", "role": "client" } ]
] }

Columns can hold headings, paragraphs, details, callouts, lists, images, spacers, fields and signatures. A column group always stays on one page.

Images

An image block takes url (an https link, an uploaded image's id, or "logo"), an optional width in points and align. Upload images with POST /v1/assets, sending a base64 PNG or JPEG up to 4 MB; the response's id goes in url. If an image can't be fetched, previews show "Image not found" in its place.

Headings, tables and dividers

• Headings take level (1 to 3), align and their own color.
• Paragraphs take align, size and color.
• Tables take header (bold first row over an accent rule) and striped.
• Dividers take color and thickness.

Getting your agent to design it

Agents connected to the MCP server have squiggli_list_starter_templates, squiggli_create_template, squiggli_upload_image and squiggli_preview_template, which returns a link to the PDF for you to open. Ask for what you want in plain words:

Make a squiggli template for our website proposals, based on the statement-of-work starter.
Use our brand: headings in Montserrat, body in Open Sans, accent #0f766e. Put this photo on the cover: https://…/office.jpg
Add a details block for the price and timeline, and keep both parties signing side by side.
Then send me the preview link.

Seeing it

The editor (Templates in the app) shows the real PDF as you type, with a Design panel for the theme. From code, POST /v1/templates/{id}/preview returns the PDF, and POST /v1/templates/{id}/preview-link returns a link that works for an hour.