> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update design.md

> Save an edited design.md

Save an edited design.md. Start from the `markdown` returned by [Get design.md](/api-reference/design-md/get), change what you want, and send the whole document back.

Only values that differ from the current document are saved:

* A frontmatter value you leave exactly as returned is not written, so it keeps working as it does now. Saving the document unchanged writes nothing.
* A changed `buttons.radius`, `cornerRadius` or `fonts.heading` is pinned, so layout defaults stop adjusting it.
* A changed `layout` token is written into the design direction ahead of your prose, so it wins over older wording.
* A changed `colors.primary` also becomes your brand primary color.
* A key or section you remove is left unchanged. An empty `## Voice` or `## Design direction` section clears it. An empty design direction returns to the defaults derived from your brand.
* Other `##` sections, and text before the first section, are kept as part of the design direction.
* Edits to `## Reference email` are not saved and come back as a warning.

If you have saved an email as your AI style, designed AI emails copy that email's look, so new colors, fonts and button values reach them only after you clear the style. The response warns you when this applies.

## Request

<ParamField body="markdown" type="string" required>
  The full design.md document, up to 100,000 characters.
</ParamField>

<ParamField body="expectedVersion" type="string">
  The `version` from your last read. When design.md changed since then, the save
  fails with `409` and nothing is written. Recommended.
</ParamField>

<ParamField body="dryRun" type="boolean">
  `true` validates the document and returns the changes and warnings a save
  would produce, without saving.
</ParamField>

```bash theme={null}
curl -X PUT "https://api.sequenzy.com/api/v1/design-md" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "---\ncolors:\n  primary: \"#1f4fff\"\n---\n\n## Voice\n\nPlain and direct. Setup steps first.\n",
    "expectedVersion": "3f9a2c1d8e7b6a50"
  }'
```

Requires the `company_profile:manage` scope, including for dry runs. Personal API keys also need an owner or admin role in the workspace.

## Response fields

<ResponseField name="saved" type="boolean">
  `true` when this request wrote changes.
</ResponseField>

<ResponseField name="dryRun" type="boolean">
  `true` when you asked for a dry run.
</ResponseField>

<ResponseField name="changes" type="string[]">
  What changed, in document terms: `logo`, `colors.<key>`, `fonts.body`,
  `fonts.heading`, `buttons.style`, `buttons.radius`, `cornerRadius`,
  `voice`, `designDirection`, or `layout.<token>`.
</ResponseField>

<ResponseField name="warnings" type="object[]">
  Notes that did not block the save, each with a `message` and, when it maps to
  one, a `line`: unknown keys that were ignored, edits to the read-only
  Reference email section, and theme values a saved AI style overrides.
</ResponseField>

<ResponseField name="markdown" type="string">
  The document as it reads after the save, or as it would read for a dry run.
</ResponseField>

<ResponseField name="version" type="string">
  The current version. It only changes when something was saved.
</ResponseField>

<ResponseField name="designSystem" type="object">
  The layout tokens in effect after the save.
</ResponseField>

## Errors and retries

* `400` with `code: DESIGN_MD_BAD_REQUEST`: the document has errors, listed in `issues` with line numbers. Typical causes are invalid YAML, an unquoted hex color (`#` starts a YAML comment), or an unknown layout value. Nothing is saved.
* `409` with `code: DESIGN_MD_CONFLICT`: design.md changed after the read your `expectedVersion` came from. Get it again, reapply your edits and save with the new version. Do not resend the stale document unchanged.
* `422`: the body is missing `markdown`, or it is longer than 100,000 characters.
* A save either applies every change or none, so retrying a failed request is safe.

## Responses

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "message": "Saved design.md: changed colors.primary, voice.",
    "saved": true,
    "dryRun": false,
    "changes": ["colors.primary", "voice"],
    "warnings": [],
    "markdown": "---\n...\n",
    "version": "9b1e04c7d2a35f68",
    "designSystem": {
      "version": 1,
      "designCode": {
        "version": 1,
        "kickerStyle": "letterspaced",
        "titleAlignment": "left",
        "buttonShape": "rounded",
        "dividerStyle": "line",
        "density": "airy",
        "openerTreatments": ["editorial-masthead", "title-led"]
      },
      "compositionSpine": "editorial",
      "source": "custom"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": "design.md has 1 error: line 3: colors.primary must be a hex color such as \"#1f4fff\". Quote it: # starts a YAML comment.",
    "code": "DESIGN_MD_BAD_REQUEST",
    "issues": [
      {
        "message": "colors.primary must be a hex color such as \"#1f4fff\". Quote it: # starts a YAML comment.",
        "line": 3
      }
    ]
  }
  ```

  ```json 401 theme={null}
  { "error": "Invalid API key format" }
  ```

  ```json 403 theme={null}
  {
    "success": false,
    "error": "API key is missing required scope: company_profile:manage"
  }
  ```

  ```json 404 theme={null}
  {
    "success": false,
    "error": "Company not found",
    "code": "DESIGN_MD_NOT_FOUND"
  }
  ```

  ```json 409 theme={null}
  {
    "success": false,
    "error": "design.md changed since you read it. Get the current design.md and reapply your edits.",
    "code": "DESIGN_MD_CONFLICT",
    "howToFix": "GET /api/v1/design-md, reapply your edits to the returned markdown, then retry with its version as expectedVersion. Do not retry the stale document unchanged."
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.