---
title: "Update design.md"
method: PUT
path: "/design-md"
tags: ["design.md"]
---

# Update design.md

`PUT /design-md`

## Request

- Base URL: `https://api.sequenzy.com/api/v1`
- URL: `https://api.sequenzy.com/api/v1/design-md`
- Auth: HTTP bearer

Saves an edited design.md. Only values that differ from the current document are written. A frontmatter value left exactly as returned is not written and keeps its current behavior; a changed buttons.radius, cornerRadius or fonts.heading is pinned so layout defaults no longer override it; a changed layout token is written into the design direction ahead of its prose. A key or section you remove is left unchanged, and an empty Voice or Design direction section clears that field (an empty direction returns to brand-derived defaults). Other level-2 sections are kept as part of the design direction. The Reference email section is read-only. Requires company_profile:manage, including for dry runs.

## Request body

- object
  - `markdown` string, required: The full design.md document, usually the markdown from GET /design-md with your edits.
  - `expectedVersion` string: Version from GET /design-md. When it no longer matches, the save fails with 409 and nothing is written. Recommended.
  - `dryRun` boolean: true validates the document and reports changes and warnings without saving.

## Response `200`

design.md saved, unchanged, or validated (dry run)

- object
  - `success` boolean
  - `message` string
  - `saved` boolean: True when this request wrote changes.
  - `dryRun` boolean
  - `changes` string[]: Changed fields in document terms, such as colors.primary, fonts.heading, buttons.radius, cornerRadius, logo, voice, designDirection or layout.spine.
  - `warnings` DesignMdIssue[]: Non-blocking notes, such as ignored unknown keys, edits to the read-only Reference email section, or theme values a saved AI style overrides.
    - `message` string, required
    - `line` integer: 1-based line in the document, when the issue maps to one.
  - `markdown` string: The document as it reads after the save, or would read for a dry run.
  - `version` string: The current version. Unchanged for a dry run or when nothing changed.
  - `designSystem` EmailDesignSystem: The visual identity every AI-generated email renders inside, parsed from the company's design direction text.
    - `version` integer, required
    - `designCode` object, required: The locked visual grammar applied to every generated email.
      - `version` integer, required
      - `kickerStyle` 'chip' | 'letterspaced' | 'none', required
      - `titleAlignment` 'left' | 'center', required
      - `buttonShape` 'rounded' | 'pill', required
      - `dividerStyle` 'line' | 'space', required
      - `density` 'airy' | 'compact', required
      - `openerTreatments` string[], required
    - `compositionSpine` 'hero-led' | 'editorial' | 'product-spec', required: Which worked-example skeleton anchors email composition.
    - `source` 'derived' | 'custom', required: derived when every token comes from brand derivation; custom when the direction text carries the identity.

## Other responses

- `400`: The document has errors, such as invalid YAML, a color that is not a hex value, or an unknown layout token. Nothing is saved.
- `401`: Unauthorized
- `403`: The API key lacks company_profile:manage, or the caller's workspace role cannot change settings
- `404`: Company not found
- `409`: design.md changed since expectedVersion was read. Get it again, reapply your edits, and retry with the new version.
- `422`: The request body is not an object with a markdown string of at most 100,000 characters
- `503`: The database was temporarily unavailable. The request may be retried after the delay in Retry-After.

## Changes

- **2026-10-16** `db3873ca3d4d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/sequenzy/apis/sequenzy-api/changes/design-md/put.md)

---

[API](https://skmtc.dev/sequenzy/apis/sequenzy-api.md) - [All operations](https://skmtc.dev/sequenzy/apis/sequenzy-api/llms.txt) - [OpenAPI document](https://skmtc.dev/sequenzy/apis/sequenzy-api/revisions/8156dc12d8b4?raw)