Sequenzy Design.md API

openapi: 3.2.0
info:
  title: Sequenzy Design.md API
  description: Sequenzy API for managing subscribers, tags, events, sequences, and transactional emails
  version: 1.0.0
servers:
- url: https://api.sequenzy.com/api/v1
  description: Production server
- url: https://api.sequenzy.com/v1
  description: Legacy production server alias
security:
- bearerAuth: []
tags:
- name: design.md
paths:
  /design-md:
    get:
      operationId: getDesignMd
      summary: Get design.md
      description: Returns the company's design.md, its email design brief as one Markdown document. YAML frontmatter holds the exact values AI-generated emails use (logo, colors, fonts, buttons, cornerRadius, layout tokens), shown as the values emails actually get. The body holds the Voice and Design direction sections the AI writer follows, plus a read-only Reference email section naming the saved AI style. design.md is a view over existing company fields, not a separate store.
      tags:
      - design.md
      responses:
        '200':
          description: design.md returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  markdown:
                    type: string
                    description: The full design.md document.
                  version:
                    type: string
                    description: Content version. Pass it as expectedVersion when saving so a concurrent change fails instead of being overwritten.
                    example: 3f9a2c1d8e7b6a50
                  designSystem:
                    $ref: '#/components/schemas/EmailDesignSystem'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The API key lacks account:read, or the caller cannot access the company
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Company not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/TransientDatabaseUnavailable'
    put:
      operationId: updateDesignMd
      summary: Update design.md
      description: 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.
      tags:
      - design.md
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - markdown
              properties:
                markdown:
                  type: string
                  maxLength: 100000
                  description: The full design.md document, usually the markdown from GET /design-md with your edits.
                expectedVersion:
                  type: string
                  description: Version from GET /design-md. When it no longer matches, the save fails with 409 and nothing is written. Recommended.
                dryRun:
                  type: boolean
                  description: true validates the document and reports changes and warnings without saving.
            examples:
              change-voice-and-color:
                summary: Change the voice and pin a primary color
                value:
                  markdown: "---\ncolors:\n  primary: \"#1f4fff\"\n---\n\n# Acme email design\n\n## Voice\n\nPlain and direct. Setup steps first.\n"
                  expectedVersion: 3f9a2c1d8e7b6a50
              dry-run:
                summary: Preview what a save would change
                value:
                  markdown: '## Design direction


                    Editorial and calm. One idea per email.

                    '
                  dryRun: true
      responses:
        '200':
          description: design.md saved, unchanged, or validated (dry run)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: 'Saved design.md: changed colors.primary, voice.'
                  saved:
                    type: boolean
                    description: True when this request wrote changes.
                  dryRun:
                    type: boolean
                  changes:
                    type: array
                    items:
                      type: string
                    description: Changed fields in document terms, such as colors.primary, fonts.heading, buttons.radius, cornerRadius, logo, voice, designDirection or layout.spine.
                    example:
                    - colors.primary
                    - voice
                  warnings:
                    type: array
                    description: Non-blocking notes, such as ignored unknown keys, edits to the read-only Reference email section, or theme values a saved AI style overrides.
                    items:
                      $ref: '#/components/schemas/DesignMdIssue'
                  markdown:
                    type: string
                    description: The document as it reads after the save, or would read for a dry run.
                  version:
                    type: string
                    description: The current version. Unchanged for a dry run or when nothing changed.
                  designSystem:
                    $ref: '#/components/schemas/EmailDesignSystem'
        '400':
          description: The document has errors, such as invalid YAML, a color that is not a hex value, or an unknown layout token. Nothing is saved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: 'design.md has 1 error: line 3: colors.primary must be a hex color such as "#1f4fff". Quote it: # starts a YAML comment.'
                  code:
                    type: string
                    example: DESIGN_MD_BAD_REQUEST
                  issues:
                    type: array
                    items:
                      $ref: '#/components/schemas/DesignMdIssue'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The API key lacks company_profile:manage, or the caller's workspace role cannot change settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Company not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: design.md changed since expectedVersion was read. Get it again, reapply your edits, and retry with the new version.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                  code:
                    type: string
                    example: DESIGN_MD_CONFLICT
                  howToFix:
                    type: string
        '422':
          description: The request body is not an object with a markdown string of at most 100,000 characters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/TransientDatabaseUnavailable'
components:
  headers:
    RetryAfter:
      description: Number of seconds to wait before retrying the request.
      schema:
        type: integer
        minimum: 1
        example: 1
  responses:
    TransientDatabaseUnavailable:
      description: The database was temporarily unavailable. The request may be retried after the delay in Retry-After.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error: The service could not reach its database for a moment. Retry the request.
            code: SERVICE_UNAVAILABLE
  schemas:
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: Error message
        code:
          type: string
          description: Optional stable machine-readable error discriminator when available.
          example: COMPANY_CREATE_REQUIRES_PERSONAL_KEY
        retryable:
          type: boolean
          description: Whether retrying the request can recover from the error.
        issues:
          type: array
          description: Field-level problems with the request, when the endpoint reports them. Up to ten entries; `error` summarizes the first three.
          items:
            $ref: '#/components/schemas/InputIssue'
      required:
      - error
    InputIssue:
      type: object
      properties:
        path:
          type: string
          description: Dotted field path, such as `audience.subscriberIds[0]`. Empty when the problem is with the request body itself.
          example: kind
        message:
          type: string
          description: What is wrong with the field.
          example: must be "add_tags"
        allowedValues:
          type: array
          description: Accepted values when the field only takes a fixed set of values.
          items: {}
          example:
          - add_tags
      required:
      - path
      - message
    DesignMdIssue:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          example: Unknown key "shadows" was ignored.
        line:
          type: integer
          description: 1-based line in the document, when the issue maps to one.
          example: 2
    EmailDesignSystem:
      type: object
      description: The visual identity every AI-generated email renders inside, parsed from the company's design direction text.
      required:
      - version
      - designCode
      - compositionSpine
      - source
      properties:
        version:
          type: integer
          example: 1
        designCode:
          type: object
          description: The locked visual grammar applied to every generated email.
          required:
          - version
          - kickerStyle
          - titleAlignment
          - buttonShape
          - dividerStyle
          - density
          - openerTreatments
          properties:
            version:
              type: integer
              example: 1
            kickerStyle:
              type: string
              enum:
              - chip
              - letterspaced
              - none
            titleAlignment:
              type: string
              enum:
              - left
              - center
            buttonShape:
              type: string
              enum:
              - rounded
              - pill
            dividerStyle:
              type: string
              enum:
              - line
              - space
            density:
              type: string
              enum:
              - airy
              - compact
            openerTreatments:
              type: array
              items:
                type: string
                enum:
                - hero-image
                - hero-color
                - header-hero
                - editorial-masthead
                - title-led
        compositionSpine:
          type: string
          enum:
          - hero-led
          - editorial
          - product-spec
          description: Which worked-example skeleton anchors email composition.
        source:
          type: string
          enum:
          - derived
          - custom
          description: derived when every token comes from brand derivation; custom when the direction text carries the identity.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as Bearer token