openapi.json

{
  "openapi": "3.0.3",
  "info": {
    "title": "Notifuse API",
    "description": "API for Notifuse - a transactional email and newsletter management platform",
    "version": "1.0.0",
    "contact": {
      "name": "Notifuse Support",
      "url": "https://www.notifuse.com/support",
      "email": "hello@notifuse.com"
    },
    "license": {
      "name": "BUSL-1.1",
      "url": "https://github.com/Notifuse/notifuse/blob/main/LICENSE"
    }
  },
  "servers": [
    {
      "url": "https://{notifuseDomain}",
      "description": "Customer-specific Notifuse API server",
      "variables": {
        "notifuseDomain": {
          "description": "Your unique Notifuse domain",
          "default": "demo.notifuse.com"
        }
      }
    }
  ],
  "paths": {
    "/track": {
      "post": {
        "summary": "Ingest a web analytics beat",
        "description": "Public collect endpoint used by the Notifuse Analytics browser SDK. Each beat carries the full cumulative session state (all pageviews and goals), so the server can rebuild the session from any single payload. Beats are typically sent as text/plain to avoid CORS preflights; the body is JSON regardless of Content-Type. Silently-dropped traffic (disabled feature, disallowed origin, bot user agents) still receives success responses.\n\nThe endpoint is public and unauthenticated, so the identity fields (contact_email + contact_email_hmac, or identify_token) are claims until they verify against the workspace secret. One that does not verify is not an error: the beat is recorded anonymously. A single malformed action is dropped the same way, leaving the rest of the beat intact.\n\nVerifying the credential is the FIRST of three gates, not the only one. An address that clears all three is attached to the session; failing any of them costs the identity alone, silently — the beat is still stored and the response is still a 200 with no error. Success and every failure are therefore indistinguishable on the wire:\n\n1. Signature (or token decryption) must verify against the workspace secret. The recipe is in the contact_email_hmac schema; getting the domain-separation prefix wrong is the usual cause.\n\n2. Rate limits, applied to the IDENTIFIED path only (anonymous traffic is the normal firehose and stays unthrottled) and before the contact lookup, so an abusive caller cannot spend database reads: 120 identified beats per minute per workspace + address, and 600 per minute per client IP (that one counted across all workspaces, since an office shares one IP) — both sized around the SDK's 10-30s heartbeat. Exceeding either is deliberately never a 429, which the SDK would only queue for a retry that cannot fix it.\n\n3. The address must ALREADY be a contact in the workspace. A signature proves who the caller is, never that the address belongs to anyone, so without this gate a workspace's own signing key could store the email of people who are not contacts, and erasure would be unenforceable — a deleted contact's next beat would re-stamp the address. The answer is cached for 60 seconds, so a freshly created contact can stay unidentified and a deleted one keep resolving for about that long.\n\nThis is why a correctly-signed beat for an address that is not a contact is indistinguishable from a bad signature: both return 200 and record the session anonymously.\n",
        "operationId": "trackWebAnalyticsBeat",
        "tags": [
          "Web Analytics"
        ],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "text/plain": {
              "schema": {
                "$ref": "#/components/schemas/WebTrackPayload"
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebTrackPayload"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Beat accepted (or silently dropped)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Malformed payload. The full set of causes: an unparseable body; a missing or blank workspace_id; a session_id that is not a UUIDv7 or whose embedded timestamp falls outside [now-48h, now+24h]; an updated_at more than 24h from server time; a negative seq; more actions than the schema's maxItems; a custom_1..custom_10 dimension value over 256 characters; or more than 50 dimension entries. Row building re-derives the session date from session_id and surfaces any failure the same way, which today can only be that same session_id rule.\n\nNever returned for an unverifiable, throttled or unknown identity, and never for a single out-of-range ACTION — that one action is dropped and the beat is kept. An oversized actions ARRAY is a different rule and IS a 400: see maxItems on the actions property.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "Body over 1 MB. Distinguished from a 400 because it is the one failure the client can act on: actions[] only grows, so every later beat of that session fails too until it trims its oldest actions or rotates the session.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/workspaces.setWebAnalyticsSettings": {
      "post": {
        "summary": "Replace the workspace's web analytics settings",
        "description": "Gated by the web_analytics write permission (like blog settings, members manage the feature without workspace write access). The attribution filters version is recomputed server-side. Passing null settings clears the configuration.\n\nWriting an identified visitor's goals and navigation to their contact timeline is not configured here and has no setting: calling identify() with an HMAC is the opt-in, because minting that credential requires the workspace secret.\n",
        "operationId": "setWebAnalyticsSettings",
        "tags": [
          "Web Analytics"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "workspace_id"
                ],
                "properties": {
                  "workspace_id": {
                    "type": "string"
                  },
                  "settings": {
                    "$ref": "#/components/schemas/WebAnalyticsSettings"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Settings updated"
          },
          "400": {
            "description": "Validation failed"
          },
          "403": {
            "description": "The caller lacks web_analytics write, returned with the missing resource named in the error message."
          }
        }
      }
    },
    "/api/webAnalytics.backfillStart": {
      "post": {
        "summary": "Start an attribution backfill",
        "description": "Rewrites historical web_sessions and web_goals rows with the current attribution rules, one monthly partition per step. Fails while a run is already pending or running.\n",
        "operationId": "webAnalyticsBackfillStart",
        "tags": [
          "Web Analytics"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebAnalyticsBackfillRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Backfill task created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebAnalyticsBackfillResponse"
                }
              }
            }
          },
          "400": {
            "description": "A backfill is already in progress"
          },
          "403": {
            "description": "Missing web_analytics write permission"
          }
        }
      }
    },
    "/api/webAnalytics.backfillStatus": {
      "post": {
        "summary": "Get the latest backfill run",
        "operationId": "webAnalyticsBackfillStatus",
        "tags": [
          "Web Analytics"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebAnalyticsBackfillRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Latest run (null when none exists)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebAnalyticsBackfillResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/webAnalytics.backfillCancel": {
      "post": {
        "summary": "Cancel the in-flight backfill run",
        "operationId": "webAnalyticsBackfillCancel",
        "tags": [
          "Web Analytics"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebAnalyticsBackfillRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Run cancelled"
          },
          "400": {
            "description": "No backfill in progress"
          }
        }
      }
    },
    "/api/annotations.list": {
      "get": {
        "summary": "List annotations",
        "description": "Returns the workspace's annotations, most recent moment first. Every filter is optional; with none the most recent 100 rows come back.\n\nGated by the web_analytics read permission, like the rest of the web analytics surface.\n",
        "operationId": "listAnnotations",
        "tags": [
          "Web Analytics"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          {
            "name": "start",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Only annotations at or after this instant. Must be RFC3339; a malformed value is a 400 rather than a dropped filter.",
            "example": "2026-08-01T00:00:00Z"
          },
          {
            "name": "end",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Only annotations at or before this instant. Must be RFC3339.",
            "example": "2026-08-31T23:59:59Z"
          },
          {
            "name": "sources",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated list of sources to keep. Any value outside `manual`/`broadcast` is a 400.",
            "example": "manual,broadcast"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 1000
            },
            "description": "Maximum rows to return. Values above the maximum are clamped to it rather than refused.",
            "example": 100
          }
        ],
        "responses": {
          "200": {
            "description": "Annotations matching the filters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListAnnotationsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingWorkspaceId": {
                    "value": {
                      "error": "workspace_id is required"
                    }
                  },
                  "malformedStart": {
                    "value": {
                      "error": "start must be an RFC3339 timestamp"
                    }
                  },
                  "endBeforeStart": {
                    "value": {
                      "error": "invalid request: end must not be before start"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing required permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Insufficient permissions: read access to web analytics required"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to list annotations"
                }
              }
            }
          }
        }
      }
    },
    "/api/annotations.get": {
      "get": {
        "summary": "Get an annotation",
        "description": "Retrieves a single annotation by ID. Requires the web_analytics read permission.",
        "operationId": "getAnnotation",
        "tags": [
          "Web Analytics"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the annotation",
            "example": "3f2504e04f8911d39a0c0305e82c3301"
          }
        ],
        "responses": {
          "200": {
            "description": "The annotation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnnotationResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "id is required"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing required permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Insufficient permissions: read access to web analytics required"
                }
              }
            }
          },
          "404": {
            "description": "No annotation with that ID in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "annotation not found with ID: 3f2504e04f8911d39a0c0305e82c3301"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to get annotation"
                }
              }
            }
          }
        }
      }
    },
    "/api/annotations.create": {
      "post": {
        "summary": "Create an annotation",
        "description": "Creates a manual annotation. Requires the web_analytics write permission.\n\n`source` is always stored as `manual` and `source_id` is always empty: only the platform writes automatic rows, so there is no way to attach a caller-supplied key to one. **This endpoint is therefore not idempotent** — a retried call (a CI job re-running a deploy marker, for instance) writes a second annotation. De-duplicate on the caller's side, or delete the extra row.\n\nOmitted `color` and `timezone` are filled in server-side: the default colour, and the workspace timezone falling back to UTC.\n",
        "operationId": "createAnnotation",
        "tags": [
          "Web Analytics"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAnnotationRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Annotation created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnnotationResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - unparseable body, validation failed, or the instance runs in demo mode, where every mutating endpoint is closed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalidBody": {
                    "value": {
                      "error": "Invalid request body"
                    }
                  },
                  "missingTitle": {
                    "value": {
                      "error": "invalid request: title is required"
                    }
                  },
                  "invalidColor": {
                    "value": {
                      "error": "invalid request: color must be a hex color like #3b82f6"
                    }
                  },
                  "systemSource": {
                    "value": {
                      "error": "invalid request: source must be \"manual\""
                    }
                  },
                  "demoMode": {
                    "value": {
                      "error": "This operation is not allowed in demo mode"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing required permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Insufficient permissions: write access to web analytics required"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to create annotation"
                }
              }
            }
          }
        }
      }
    },
    "/api/annotations.update": {
      "post": {
        "summary": "Update an annotation",
        "description": "Edits an annotation's moment, timezone and presentation. Requires the web_analytics write permission.\n\nAutomatic annotations are editable — an operator may want to reword a broadcast's title — but their origin is not: `source` and `source_id` are reloaded from storage and carried forward, so an edit can neither promote a manual row to a system one nor take over another broadcast's slot.\n",
        "operationId": "updateAnnotation",
        "tags": [
          "Web Analytics"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateAnnotationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Annotation updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnnotationResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - unparseable body, validation failed, or the instance runs in demo mode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingId": {
                    "value": {
                      "error": "invalid request: id is required"
                    }
                  },
                  "missingAnnotatedAt": {
                    "value": {
                      "error": "invalid request: annotated_at is required"
                    }
                  },
                  "demoMode": {
                    "value": {
                      "error": "This operation is not allowed in demo mode"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing required permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Insufficient permissions: write access to web analytics required"
                }
              }
            }
          },
          "404": {
            "description": "No annotation with that ID in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "annotation not found with ID: 3f2504e04f8911d39a0c0305e82c3301"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to update annotation"
                }
              }
            }
          }
        }
      }
    },
    "/api/annotations.delete": {
      "post": {
        "summary": "Delete an annotation",
        "description": "Deletes an annotation, automatic ones included — a broadcast annotation cannot come back by accident, since its broadcast has already started. Requires the web_analytics write permission.\n",
        "operationId": "deleteAnnotation",
        "tags": [
          "Web Analytics"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeleteAnnotationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Annotation deleted. A body rather than a 204, so a delete is never indistinguishable from a proxy swallowing the response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeleteAnnotationResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - unparseable body, missing id, or the instance runs in demo mode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingId": {
                    "value": {
                      "error": "invalid request: id is required"
                    }
                  },
                  "demoMode": {
                    "value": {
                      "error": "This operation is not allowed in demo mode"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing required permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Insufficient permissions: write access to web analytics required"
                }
              }
            }
          },
          "404": {
            "description": "No annotation with that ID in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "annotation not found with ID: 3f2504e04f8911d39a0c0305e82c3301"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to delete annotation"
                }
              }
            }
          }
        }
      }
    },
    "/api/transactional.send": {
      "post": {
        "summary": "Send a transactional notification",
        "description": "Sends a transactional notification to a contact through specified channels.\nRequires authentication.\n",
        "operationId": "sendTransactionalNotification",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendTransactionalRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Notification sent successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message_id": {
                      "type": "string",
                      "description": "Unique identifier for the sent message",
                      "example": "msg_1234567890abcdef"
                    },
                    "success": {
                      "type": "boolean",
                      "description": "Whether the notification was sent successfully",
                      "example": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "notFoundExample": {
                    "value": {
                      "error": "Notification not found"
                    }
                  },
                  "inactiveExample": {
                    "value": {
                      "error": "Notification is not active"
                    }
                  },
                  "noChannelsExample": {
                    "value": {
                      "error": "No valid channels configured"
                    }
                  },
                  "validationExample": {
                    "value": {
                      "error": "notification.contact is required"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "The API key lacks a permission the send requires. `transactional:write` is\nalways required; `contacts:read` is required in addition when the request\nsets `cc` or `bcc`, because the subject is rendered against the contact.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Insufficient permissions: write access to transactional notifications required",
                  "resource": "transactional",
                  "permission": "write"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to send notification"
                }
              }
            }
          }
        }
      }
    },
    "/api/contacts.list": {
      "get": {
        "summary": "List contacts with filtering and pagination",
        "description": "Retrieves a paginated list of contacts with optional filtering. All contact fields are always returned.\n\n**Filtering**: Use filters to search for contacts. Text filters (email, external_id, first_name, last_name, full_name, phone, country, language) use case-insensitive partial matching (ILIKE).\n\n**List filtering**: Use `list_id` and/or `contact_list_status` to filter contacts by list membership.\n\n**Segment filtering**: Use `segments[]` to filter contacts that belong to specific segments.\n\n**Contact lists**: By default, `contact_lists` is not included in the response. Set `with_contact_lists=true` to include the contact's list subscriptions.\n\n**Pagination**: Uses cursor-based pagination. Use the `next_cursor` from the response to fetch the next page.\n",
        "operationId": "listContacts",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          {
            "name": "email",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by email (case-insensitive partial match)",
            "example": "user@example"
          },
          {
            "name": "external_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by external ID (case-insensitive partial match)",
            "example": "user_123"
          },
          {
            "name": "first_name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by first name (case-insensitive partial match)",
            "example": "John"
          },
          {
            "name": "last_name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by last name (case-insensitive partial match)",
            "example": "Doe"
          },
          {
            "name": "full_name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by full name (case-insensitive partial match)",
            "example": "John Doe"
          },
          {
            "name": "phone",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by phone number (case-insensitive partial match)",
            "example": "+1555"
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by country (case-insensitive partial match)",
            "example": "US"
          },
          {
            "name": "language",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by language (case-insensitive partial match)",
            "example": "en"
          },
          {
            "name": "list_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by list membership (contacts subscribed to this list)",
            "example": "newsletter"
          },
          {
            "name": "contact_list_status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "active",
                "pending",
                "unsubscribed",
                "bounced",
                "complained"
              ]
            },
            "description": "Filter by subscription status within the list",
            "example": "active"
          },
          {
            "name": "tracking_opens_consent",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "granted",
                "denied",
                "unknown"
              ]
            },
            "description": "Filter by the contact's open tracking choice; `unknown` matches contacts with none recorded",
            "example": "denied"
          },
          {
            "name": "tracking_clicks_consent",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "granted",
                "denied",
                "unknown"
              ]
            },
            "description": "Filter by the contact's click tracking choice; `unknown` matches contacts with none recorded",
            "example": "unknown"
          },
          {
            "name": "segments[]",
            "in": "query",
            "required": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "description": "Filter by segment membership (contacts in any of these segments)",
            "example": [
              "premium_users",
              "active_buyers"
            ]
          },
          {
            "name": "with_contact_lists",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Include contact list subscriptions in the response",
            "example": true
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "description": "Maximum number of contacts to return (1-100)",
            "example": 50
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Pagination cursor from previous response",
            "example": "MjAyMy0wMS0xNVQxMDozMDowMFp+dXNlckBleGFtcGxlLmNvbQ=="
          }
        ],
        "responses": {
          "200": {
            "description": "Contacts retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListContactsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingWorkspaceId": {
                    "value": {
                      "error": "workspace_id is required"
                    }
                  },
                  "invalidLimit": {
                    "value": {
                      "error": "limit must be between 1 and 100"
                    }
                  },
                  "invalidCursor": {
                    "value": {
                      "error": "invalid cursor encoding"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/contacts.count": {
      "get": {
        "summary": "Count contacts in a workspace",
        "description": "Returns the total number of contacts in a workspace.",
        "operationId": "countContacts",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          }
        ],
        "responses": {
          "200": {
            "description": "Contact count retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CountContactsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing workspace ID",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Missing workspace ID"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/contacts.upsert": {
      "post": {
        "summary": "Create or update a contact",
        "description": "Creates a new contact or updates an existing one. Contacts are matched **by email address only** — the email is the contact's unique identifier. `external_id` is stored but never used for matching, so sending an existing `external_id` with a new email address creates a second contact.\n\nTo change a contact's email address: upsert a contact with the new email and the full profile, re-create its list subscriptions (preserving unsubscribed/bounced/complained statuses — do not reset opt-outs), then delete the contact with the old email using `contacts.delete`. Message history and segment memberships are keyed to the email address and are not transferred.\n\nReturns information about whether the contact was created or updated.\n",
        "operationId": "upsertContact",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpsertContactRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Contact upserted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UpsertContactResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingWorkspaceId": {
                    "value": {
                      "error": "workspace_id is required"
                    }
                  },
                  "invalidEmail": {
                    "value": {
                      "error": "invalid email format"
                    }
                  },
                  "missingContact": {
                    "value": {
                      "error": "contact is required"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/contacts.getByEmail": {
      "get": {
        "summary": "Get a contact by email address",
        "description": "Retrieves a contact by their email address within a specific workspace. The response always includes the contact's list subscriptions with their status (active, pending, unsubscribed, bounced, complained).",
        "operationId": "getContactByEmail",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          {
            "name": "email",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "email"
            },
            "description": "The email address of the contact",
            "example": "user@example.com"
          }
        ],
        "responses": {
          "200": {
            "description": "Contact found successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "contact": {
                      "$ref": "#/components/schemas/Contact"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingWorkspaceId": {
                    "value": {
                      "error": "Missing workspace ID"
                    }
                  },
                  "missingEmail": {
                    "value": {
                      "error": "Missing email"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Contact not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Contact not found"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/contacts.getByExternalID": {
      "get": {
        "summary": "Get a contact by external ID",
        "description": "Retrieves a contact by their external ID within a specific workspace. The response always includes the contact's list subscriptions with their status (active, pending, unsubscribed, bounced, complained).\n\nNote that `external_id` is not unique — if several contacts share the same external ID, only one of them is returned (which one is not defined). Contacts are uniquely identified by email address.\n",
        "operationId": "getContactByExternalID",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          {
            "name": "external_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The external ID of the contact",
            "example": "user_12345"
          }
        ],
        "responses": {
          "200": {
            "description": "Contact found successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "contact": {
                      "$ref": "#/components/schemas/Contact"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingWorkspaceId": {
                    "value": {
                      "error": "Missing workspace ID"
                    }
                  },
                  "missingExternalId": {
                    "value": {
                      "error": "Missing external ID"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Contact not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Contact not found"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/contacts.import": {
      "post": {
        "summary": "Batch import contacts",
        "description": "Creates or updates multiple contacts in a single batch operation. This is significantly more efficient than individual upsert operations. Optionally subscribes all contacts to specified lists.",
        "operationId": "batchImportContacts",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchImportContactsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch import completed (may include partial failures)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchImportContactsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingWorkspaceId": {
                    "value": {
                      "error": "workspace_id is required"
                    }
                  },
                  "missingContacts": {
                    "value": {
                      "error": "contacts is required"
                    }
                  },
                  "emptyContacts": {
                    "value": {
                      "error": "contacts array cannot be empty"
                    }
                  },
                  "insufficientPermissions": {
                    "value": {
                      "error": "write access to lists required when subscribe_to_lists is provided"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/contacts.delete": {
      "post": {
        "summary": "Delete a contact",
        "description": "Deletes a contact from the workspace by email address. This action is permanent and cannot be undone.",
        "operationId": "deleteContact",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeleteContactRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Contact deleted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "description": "Whether the deletion was successful",
                      "example": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingWorkspaceId": {
                    "value": {
                      "error": "workspace_id is required"
                    }
                  },
                  "missingEmail": {
                    "value": {
                      "error": "email is required"
                    }
                  },
                  "invalidEmail": {
                    "value": {
                      "error": "invalid email format"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Contact not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Contact not found"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to delete contact"
                }
              }
            }
          }
        }
      }
    },
    "/api/contactLists.updateStatus": {
      "post": {
        "summary": "Update contact list subscription status",
        "description": "Updates the subscription status of a contact in a specific list. Can set status to active, pending, unsubscribed, bounced, or complained.\n\n**Note:** This endpoint only modifies **existing** list memberships. It does not add a contact to a list. To add a contact to a list, use the `/subscribe` endpoint (for public lists) or the `/api/contacts.import` endpoint (for any list, requires authentication).\n",
        "operationId": "updateContactListStatus",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateContactListStatusRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Status updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UpdateContactListStatusResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingWorkspaceId": {
                    "value": {
                      "error": "workspace_id is required"
                    }
                  },
                  "missingEmail": {
                    "value": {
                      "error": "email is required"
                    }
                  },
                  "missingListId": {
                    "value": {
                      "error": "list_id is required"
                    }
                  },
                  "invalidStatus": {
                    "value": {
                      "error": "invalid status value"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Contact list relationship not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "contact list not found"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/broadcasts.list": {
      "get": {
        "summary": "List broadcasts",
        "description": "Retrieves a list of broadcasts with pagination and optional filtering by status. Supports fetching template details for each variation.",
        "operationId": "listBroadcasts",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "draft",
                "scheduled",
                "sending",
                "paused",
                "sent",
                "cancelled",
                "failed",
                "testing",
                "test_completed",
                "winner_selected"
              ]
            },
            "description": "Filter broadcasts by status"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 50
            },
            "description": "Maximum number of broadcasts to return",
            "example": 50
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0
            },
            "description": "Number of broadcasts to skip for pagination",
            "example": 0
          },
          {
            "name": "with_templates",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Include full template details for each variation",
            "example": false
          }
        ],
        "responses": {
          "200": {
            "description": "List of broadcasts retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BroadcastListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "workspace_id is required"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to list broadcasts"
                }
              }
            }
          }
        }
      }
    },
    "/api/broadcasts.get": {
      "get": {
        "summary": "Get a broadcast",
        "description": "Retrieves a single broadcast by ID. Optionally includes template details for each variation.",
        "operationId": "getBroadcast",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the broadcast",
            "example": "broadcast_12345"
          },
          {
            "name": "with_templates",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Include full template details for each variation",
            "example": false
          }
        ],
        "responses": {
          "200": {
            "description": "Broadcast retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "broadcast": {
                      "$ref": "#/components/schemas/Broadcast"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Broadcast not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Broadcast not found"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/broadcasts.create": {
      "post": {
        "summary": "Create a broadcast",
        "description": "Creates a new broadcast campaign in draft status.\n\n**Important:** Creating a broadcast does not schedule or send it. After creating the broadcast,\nyou must call the `/api/broadcasts.schedule` endpoint to schedule or send it immediately.\n",
        "operationId": "createBroadcast",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateBroadcastRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Broadcast created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "broadcast": {
                      "$ref": "#/components/schemas/Broadcast"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingName": {
                    "value": {
                      "error": "name is required"
                    }
                  },
                  "missingList": {
                    "value": {
                      "error": "list is required"
                    }
                  },
                  "invalidTestSettings": {
                    "value": {
                      "error": "at least 2 variations are required for A/B testing"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to create broadcast"
                }
              }
            }
          }
        }
      }
    },
    "/api/broadcasts.update": {
      "post": {
        "summary": "Update a broadcast",
        "description": "Updates an existing broadcast. Only broadcasts in draft, scheduled, or paused status can be updated.",
        "operationId": "updateBroadcast",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateBroadcastRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Broadcast updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "broadcast": {
                      "$ref": "#/components/schemas/Broadcast"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalidStatus": {
                    "value": {
                      "error": "cannot update broadcast with status: sending"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Broadcast not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Broadcast not found"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/broadcasts.schedule": {
      "post": {
        "summary": "Schedule a broadcast",
        "description": "Schedules a broadcast for sending either immediately or at a specified time. This endpoint is restricted in demo mode.",
        "operationId": "scheduleBroadcast",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ScheduleBroadcastRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Broadcast scheduled successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingDateTime": {
                    "value": {
                      "error": "scheduled_date and scheduled_time are required when not sending immediately"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Broadcast not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/broadcasts.pause": {
      "post": {
        "summary": "Pause a broadcast",
        "description": "Pauses a broadcast that is currently sending.",
        "operationId": "pauseBroadcast",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PauseBroadcastRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Broadcast paused successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Broadcast not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/broadcasts.resume": {
      "post": {
        "summary": "Resume a broadcast",
        "description": "Resumes a paused broadcast.",
        "operationId": "resumeBroadcast",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResumeBroadcastRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Broadcast resumed successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Broadcast not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/broadcasts.cancel": {
      "post": {
        "summary": "Cancel a broadcast",
        "description": "Cancels a scheduled broadcast.",
        "operationId": "cancelBroadcast",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CancelBroadcastRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Broadcast cancelled successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Broadcast not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/broadcasts.retryFailed": {
      "post": {
        "summary": "Retry the recipients a broadcast failed to reach",
        "description": "Requeues the recipients whose delivery attempts were all refused by the email provider, so the same message is sent to them again. Only accepted once the broadcast has finished sending: a broadcast still working through its queue, or one that is paused, is refused. Failed recipients are kept for seven days, after which they can no longer be retried. Fix whatever the provider objected to before calling this, or the recipients will simply fail again.\n",
        "operationId": "retryFailedBroadcastRecipients",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RetryFailedBroadcastRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Recipients requeued",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "success"
                    },
                    "requeued": {
                      "type": "integer",
                      "description": "How many recipients were put back in the queue. Zero when there were none to retry.",
                      "example": 23
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - the broadcast has not finished sending, is paused, the workspace has no marketing email provider, or the body failed validation\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - write access to broadcasts required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Broadcast not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/broadcasts.sendToIndividual": {
      "post": {
        "summary": "Send broadcast to individual",
        "description": "Sends a broadcast to a single recipient for testing purposes. Optionally specify which template variation to send.",
        "operationId": "sendBroadcastToIndividual",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendToIndividualRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Broadcast sent to individual successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Broadcast not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/broadcasts.delete": {
      "post": {
        "summary": "Delete a broadcast",
        "description": "Deletes a broadcast. This action is permanent and cannot be undone.",
        "operationId": "deleteBroadcast",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeleteBroadcastRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Broadcast deleted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Broadcast not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/broadcasts.getTestResults": {
      "get": {
        "summary": "Get A/B test results",
        "description": "Retrieves the performance metrics for all variations in an A/B test broadcast.",
        "operationId": "getBroadcastTestResults",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the broadcast",
            "example": "broadcast_12345"
          }
        ],
        "responses": {
          "200": {
            "description": "Test results retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TestResultsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to get test results"
                }
              }
            }
          }
        }
      }
    },
    "/api/broadcasts.selectWinner": {
      "post": {
        "summary": "Select winning A/B test variation",
        "description": "Manually selects the winning variation for an A/B test broadcast. The winning variation will be sent to the remaining audience. This endpoint is restricted in demo mode.",
        "operationId": "selectBroadcastWinner",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SelectWinnerRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Winner selected successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to select winner"
                }
              }
            }
          }
        }
      }
    },
    "/api/broadcasts.refreshGlobalFeed": {
      "post": {
        "summary": "Refresh global feed data",
        "description": "Fetches fresh data from the configured global feed URL and stores it in the broadcast.\nThe global feed must be enabled for the broadcast before calling this endpoint.\n",
        "operationId": "refreshGlobalFeed",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RefreshGlobalFeedRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Global feed data refreshed successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RefreshGlobalFeedResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - global feed not enabled or validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "notEnabled": {
                    "value": {
                      "error": "global feed is not enabled for this broadcast"
                    }
                  },
                  "validation": {
                    "value": {
                      "error": "workspace_id is required"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Broadcast not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Broadcast not found"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to refresh global feed"
                }
              }
            }
          }
        }
      }
    },
    "/api/broadcasts.testRecipientFeed": {
      "post": {
        "summary": "Test recipient feed configuration",
        "description": "Tests the per-recipient feed configuration by fetching data for a specific contact or a random contact from the broadcast audience.\nThe recipient feed must be enabled for the broadcast before calling this endpoint.\n",
        "operationId": "testRecipientFeed",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TestRecipientFeedRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Recipient feed test completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TestRecipientFeedResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - recipient feed not enabled or validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "notEnabled": {
                    "value": {
                      "error": "recipient feed is not enabled for this broadcast"
                    }
                  },
                  "validation": {
                    "value": {
                      "error": "workspace_id is required"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Broadcast or contact not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "broadcastNotFound": {
                    "value": {
                      "error": "Broadcast not found"
                    }
                  },
                  "contactNotFound": {
                    "value": {
                      "error": "Contact not found"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to test recipient feed"
                }
              }
            }
          }
        }
      }
    },
    "/api/templates.list": {
      "get": {
        "summary": "List templates",
        "description": "Retrieves a list of all templates in the workspace. Supports optional filtering by category and channel.",
        "operationId": "listTemplates",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "marketing",
                "transactional",
                "welcome",
                "opt_in",
                "unsubscribe",
                "bounce",
                "blocklist",
                "blog",
                "other"
              ]
            },
            "description": "Filter templates by category"
          },
          {
            "name": "channel",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "email",
                "web"
              ]
            },
            "description": "Filter templates by channel"
          }
        ],
        "responses": {
          "200": {
            "description": "List of templates retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "templates": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Template"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "workspace_id is required"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to get templates"
                }
              }
            }
          }
        }
      }
    },
    "/api/templates.get": {
      "get": {
        "summary": "Get a template",
        "description": "Retrieves a single template by ID. Optionally specify a version number to retrieve a specific version.",
        "operationId": "getTemplate",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the template",
            "example": "welcome_email"
          },
          {
            "name": "version",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int64"
            },
            "description": "Specific version number (defaults to latest)",
            "example": 1
          }
        ],
        "responses": {
          "200": {
            "description": "Template retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "template": {
                      "$ref": "#/components/schemas/Template"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Template not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Template not found"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/templates.create": {
      "post": {
        "summary": "Create a template",
        "description": "Creates a new template. Each template must have a channel (email or web) with corresponding channel-specific content.",
        "operationId": "createTemplate",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateTemplateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Template created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "template": {
                      "$ref": "#/components/schemas/Template"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "duplicateId": {
                    "value": {
                      "error": "Template id already exists"
                    }
                  },
                  "deletedTemplateId": {
                    "summary": "The id belongs to a deleted template",
                    "value": {
                      "error": "Template id belongs to a deleted template and cannot be reused: deleted templates are kept so messages already sent with them can still be displayed. Choose another id"
                    }
                  },
                  "missingEmail": {
                    "value": {
                      "error": "email is required for channel 'email'"
                    }
                  },
                  "invalidId": {
                    "value": {
                      "error": "id must contain only letters, numbers, underscores, and hyphens"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to create template"
                }
              }
            }
          }
        }
      }
    },
    "/api/templates.update": {
      "post": {
        "summary": "Update a template",
        "description": "Updates an existing template. Creates a new version of the template. The email's `editor_mode` must stay the one the template was created with; to switch between the visual editor and MJML code, create a new template. A deleted template cannot be updated.",
        "operationId": "updateTemplate",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateTemplateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Template updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "template": {
                      "$ref": "#/components/schemas/Template"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "editorModeChange": {
                    "summary": "The update is in the other editor mode",
                    "value": {
                      "error": "cannot change editor mode: template was created in 'code' mode and its mode can't be changed; create a new template in 'visual' mode and copy the content with Import or Export MJML"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Template not found, or deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Template not found"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to update template"
                }
              }
            }
          }
        }
      }
    },
    "/api/templates.delete": {
      "post": {
        "summary": "Delete a template",
        "description": "Soft-deletes a template: it disappears from `templates.list` and can no longer be updated, but every version is kept, because messages already sent (message history, broadcast reports) are rendered from them. `templates.get` still returns it, with `deleted_at` set. Its id stays reserved: creating a template with the same id is refused.",
        "operationId": "deleteTemplate",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeleteTemplateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Template deleted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Template not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Template not found"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to delete template"
                }
              }
            }
          }
        }
      }
    },
    "/api/templates.compile": {
      "post": {
        "summary": "Compile template",
        "description": "Compiles an MJML template with provided data, returning the rendered HTML.\nWhen `subject` and/or `subject_preview` are provided, they are rendered\nthrough the same Liquid engine used at send time and returned alongside\nthe HTML so callers do not need to run a separate Liquid pass to preview\nthe subject line. Useful for previewing templates before saving.\n",
        "operationId": "compileTemplate",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompileTemplateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Template compiled successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompileTemplateResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - compilation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Compilation failed: Invalid MJML syntax"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/blogCategories.list": {
      "get": {
        "summary": "List blog categories",
        "description": "Returns every category of the workspace's blog, newest first. Not paginated. Requires the blog read permission.",
        "operationId": "listBlogCategories",
        "tags": [
          "Blog"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          }
        ],
        "responses": {
          "200": {
            "description": "The workspace's categories",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListBlogCategoriesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing workspace_id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "workspace_id is required"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing the blog read permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PermissionErrorResponse"
                },
                "example": {
                  "error": "Insufficient permissions: read access to blog required",
                  "resource": "blog",
                  "permission": "read"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to list categories"
                }
              }
            }
          }
        }
      }
    },
    "/api/blogCategories.get": {
      "get": {
        "summary": "Get a blog category",
        "description": "Retrieves a category by `id` or by `slug`; when both are given, `id` wins. Requires the blog read permission.",
        "operationId": "getBlogCategory",
        "tags": [
          "Blog"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The category ID. Either `id` or `slug` is required.",
            "example": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
          },
          {
            "name": "slug",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The category slug. Either `id` or `slug` is required.",
            "example": "product"
          }
        ],
        "responses": {
          "200": {
            "description": "The category",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BlogCategoryResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "either id or slug is required"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing the blog read permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PermissionErrorResponse"
                },
                "example": {
                  "error": "Insufficient permissions: read access to blog required",
                  "resource": "blog",
                  "permission": "read"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error. Also returned when no category matches the id or slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to get category"
                }
              }
            }
          }
        }
      }
    },
    "/api/blogCategories.create": {
      "post": {
        "summary": "Create a blog category",
        "description": "Creates a category. Posts always belong to one, so a blog needs at least one category before its first post. Requires the blog write permission.",
        "operationId": "createBlogCategory",
        "tags": [
          "Blog"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace. Passed in the query string, not the body.",
            "example": "ws_1234567890"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateBlogCategoryRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Category created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BlogCategoryResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed or the slug is taken",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "slugTaken": {
                    "value": {
                      "error": "category with slug 'product' already exists"
                    }
                  },
                  "invalidSlug": {
                    "value": {
                      "error": "slug must contain only lowercase letters, numbers, and hyphens"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing the blog write permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PermissionErrorResponse"
                },
                "example": {
                  "error": "Insufficient permissions: write access to blog required",
                  "resource": "blog",
                  "permission": "write"
                }
              }
            }
          }
        }
      }
    },
    "/api/blogCategories.update": {
      "post": {
        "summary": "Update a blog category",
        "description": "Replaces a category's name, slug, description and SEO settings. This is not a patch: optional fields left out are cleared. Public pages are cached for up to 5 minutes, so a rename can take that long to show on the blog. Requires the blog write permission.",
        "operationId": "updateBlogCategory",
        "tags": [
          "Blog"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace. Passed in the query string, not the body.",
            "example": "ws_1234567890"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateBlogCategoryRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Category updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BlogCategoryResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed, slug taken or category not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "category not found: blog category not found"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing the blog write permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PermissionErrorResponse"
                },
                "example": {
                  "error": "Insufficient permissions: write access to blog required",
                  "resource": "blog",
                  "permission": "write"
                }
              }
            }
          }
        }
      }
    },
    "/api/blogCategories.delete": {
      "post": {
        "summary": "Delete a blog category",
        "description": "Deletes a category **and every post in it**, in one transaction. Both are soft-deleted, which frees their slugs for reuse. Public pages are cached for up to 5 minutes, so the category can take that long to disappear from the blog. Requires the blog write permission.",
        "operationId": "deleteBlogCategory",
        "tags": [
          "Blog"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace. Passed in the query string, not the body.",
            "example": "ws_1234567890"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "id"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "example": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Category and its posts deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing id or category not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "failed to delete category: blog category not found"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing the blog write permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PermissionErrorResponse"
                },
                "example": {
                  "error": "Insufficient permissions: write access to blog required",
                  "resource": "blog",
                  "permission": "write"
                }
              }
            }
          }
        }
      }
    },
    "/api/blogPosts.list": {
      "get": {
        "summary": "List blog posts",
        "description": "Returns posts page by page, drafts included unless filtered out. Posts come newest-created first; with `status=published`, most recently published first. Page through with `page` and `limit` until you have `total_count` posts. Requires the blog read permission.",
        "operationId": "listBlogPosts",
        "tags": [
          "Blog"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          {
            "name": "category_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Only posts in this category.",
            "example": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "draft",
                "published"
              ],
              "default": "all"
            },
            "description": "`draft` is posts never published or since unpublished; `published` is every post with a publication date, including one dated in the future.",
            "example": "published"
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            },
            "description": "1-indexed page number.",
            "example": 2
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 100
            },
            "description": "Posts per page. Values above the maximum are clamped to it rather than refused.",
            "example": 50
          }
        ],
        "responses": {
          "200": {
            "description": "One page of posts",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListBlogPostsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingWorkspaceId": {
                    "value": {
                      "error": "workspace_id is required"
                    }
                  },
                  "invalidPage": {
                    "value": {
                      "error": "page must be a valid integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing the blog read permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PermissionErrorResponse"
                },
                "example": {
                  "error": "Insufficient permissions: read access to blog required",
                  "resource": "blog",
                  "permission": "read"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error. Also returned for a `status` outside the enum.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to list posts"
                }
              }
            }
          }
        }
      }
    },
    "/api/blogPosts.get": {
      "get": {
        "summary": "Get a blog post",
        "description": "Retrieves a post by `id` or by `slug`; when both are given, `id` wins. Drafts are returned too. Requires the blog read permission.",
        "operationId": "getBlogPost",
        "tags": [
          "Blog"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The post ID. Either `id` or `slug` is required.",
            "example": "1b4e28ba-2fa1-11d2-883f-0016d3cca427"
          },
          {
            "name": "slug",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The post slug. Either `id` or `slug` is required. Post slugs are unique across the workspace, so the slug alone identifies the post.",
            "example": "october-release"
          },
          {
            "name": "category_slug",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "With `slug`, only match the post if it is in this category — the lookup a `/{category_slug}/{post_slug}` URL maps to.",
            "example": "product"
          }
        ],
        "responses": {
          "200": {
            "description": "The post",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BlogPostResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "either id or slug is required"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing the blog read permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PermissionErrorResponse"
                },
                "example": {
                  "error": "Insufficient permissions: read access to blog required",
                  "resource": "blog",
                  "permission": "read"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error. Also returned when no post matches.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to get post"
                }
              }
            }
          }
        }
      }
    },
    "/api/blogPosts.create": {
      "post": {
        "summary": "Create a blog post",
        "description": "Creates a post as a draft. The post holds the metadata; its body lives in a web template, so publishing a post over the API takes three calls:\n\n1. `templates.create` with `channel: \"web\"`, `category: \"blog\"` and a `web` object. `web.html` is the body readers see, rendered as-is. `web.content` is required and is the Tiptap document the console editor opens; if you only have HTML, send `{\"type\": \"doc\", \"content\": []}`, and do not edit that post in the console afterwards, because saving there regenerates `web.html` from `web.content`.\n2. `blogPosts.create` with that template's `id` as `template_id`.\n3. `blogPosts.publish`.\n\nRequires the blog write permission, plus the templates write permission for step 1.\n",
        "operationId": "createBlogPost",
        "tags": [
          "Blog"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace. Passed in the query string, not the body.",
            "example": "ws_1234567890"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateBlogPostRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Post created as a draft",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BlogPostResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed, slug taken or category not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "slugTaken": {
                    "value": {
                      "error": "post with slug 'october-release' already exists"
                    }
                  },
                  "unknownCategory": {
                    "value": {
                      "error": "category not found: blog category not found"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing the blog write permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PermissionErrorResponse"
                },
                "example": {
                  "error": "Insufficient permissions: write access to blog required",
                  "resource": "blog",
                  "permission": "write"
                }
              }
            }
          }
        }
      }
    },
    "/api/blogPosts.update": {
      "post": {
        "summary": "Update a blog post",
        "description": "Replaces a post's metadata. This is not a patch: optional fields left out are cleared, so send the post back with your changes applied.\n\nTo change the body, update the template with `templates.update`, which saves a new template version. A post pinned to a `template_version` keeps rendering the old one until you update the post with the new version; a post at version `0` follows the latest version on its own, within the 5-minute page cache.\n\nRequires the blog write permission.\n",
        "operationId": "updateBlogPost",
        "tags": [
          "Blog"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace. Passed in the query string, not the body.",
            "example": "ws_1234567890"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateBlogPostRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Post updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BlogPostResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed, slug taken, or post or category not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "post not found: blog post not found"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing the blog write permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PermissionErrorResponse"
                },
                "example": {
                  "error": "Insufficient permissions: write access to blog required",
                  "resource": "blog",
                  "permission": "write"
                }
              }
            }
          }
        }
      }
    },
    "/api/blogPosts.delete": {
      "post": {
        "summary": "Delete a blog post",
        "description": "Soft-deletes a post, which takes it off the blog and frees its slug. Its template is left in place. Requires the blog write permission.",
        "operationId": "deleteBlogPost",
        "tags": [
          "Blog"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace. Passed in the query string, not the body.",
            "example": "ws_1234567890"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BlogPostIdRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Post deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing id or post not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "post not found: blog post not found"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing the blog write permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PermissionErrorResponse"
                },
                "example": {
                  "error": "Insufficient permissions: write access to blog required",
                  "resource": "blog",
                  "permission": "write"
                }
              }
            }
          }
        }
      }
    },
    "/api/blogPosts.publish": {
      "post": {
        "summary": "Publish a blog post",
        "description": "Publishes a draft: it appears on the blog's home and category pages, at its own URL, and in the RSS and JSON feeds. Publishing a post that is already published is refused; unpublish it first to change its date. Requires the blog write permission.",
        "operationId": "publishBlogPost",
        "tags": [
          "Blog"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace. Passed in the query string, not the body.",
            "example": "ws_1234567890"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublishBlogPostRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Post published",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing id, post not found or already published",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "failed to publish post: blog post not found or already published"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing the blog write permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PermissionErrorResponse"
                },
                "example": {
                  "error": "Insufficient permissions: write access to blog required",
                  "resource": "blog",
                  "permission": "write"
                }
              }
            }
          }
        }
      }
    },
    "/api/blogPosts.unpublish": {
      "post": {
        "summary": "Unpublish a blog post",
        "description": "Turns a published post back into a draft and clears its publication date. Requires the blog write permission.",
        "operationId": "unpublishBlogPost",
        "tags": [
          "Blog"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace. Passed in the query string, not the body.",
            "example": "ws_1234567890"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BlogPostIdRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Post unpublished",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing id, post not found or not published",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "failed to unpublish post: blog post not found or not published"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing the blog write permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PermissionErrorResponse"
                },
                "example": {
                  "error": "Insufficient permissions: write access to blog required",
                  "resource": "blog",
                  "permission": "write"
                }
              }
            }
          }
        }
      }
    },
    "/api/blogThemes.list": {
      "get": {
        "summary": "List blog theme versions",
        "description": "Returns the workspace's theme versions, newest first, files included. Requires the blog read permission.",
        "operationId": "listBlogThemes",
        "tags": [
          "Blog"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 100
            },
            "description": "Versions per page. Values above the maximum are clamped to it rather than refused.",
            "example": 50
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "description": "Versions to skip.",
            "example": 0
          }
        ],
        "responses": {
          "200": {
            "description": "One page of theme versions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListBlogThemesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "limit must be a valid integer"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing the blog read permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PermissionErrorResponse"
                },
                "example": {
                  "error": "Insufficient permissions: read access to blog required",
                  "resource": "blog",
                  "permission": "read"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/blogThemes.get": {
      "get": {
        "summary": "Get a blog theme version",
        "description": "Retrieves one theme version with its files. Requires the blog read permission.",
        "operationId": "getBlogTheme",
        "tags": [
          "Blog"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          {
            "name": "version",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "The theme version",
            "example": 4
          }
        ],
        "responses": {
          "200": {
            "description": "The theme version",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BlogThemeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing or non-integer version",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "version parameter is required"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing the blog read permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PermissionErrorResponse"
                },
                "example": {
                  "error": "Insufficient permissions: read access to blog required",
                  "resource": "blog",
                  "permission": "read"
                }
              }
            }
          },
          "404": {
            "description": "No theme with this version",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/blogThemes.getPublished": {
      "get": {
        "summary": "Get the published blog theme",
        "description": "Retrieves the theme version currently live on the blog. Requires the blog read permission.",
        "operationId": "getPublishedBlogTheme",
        "tags": [
          "Blog"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          }
        ],
        "responses": {
          "200": {
            "description": "The published theme",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BlogThemeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing workspace_id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "workspace_id is required"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing the blog read permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PermissionErrorResponse"
                },
                "example": {
                  "error": "Insufficient permissions: read access to blog required",
                  "resource": "blog",
                  "permission": "read"
                }
              }
            }
          },
          "404": {
            "description": "No theme is published",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/blogThemes.create": {
      "post": {
        "summary": "Create a blog theme version",
        "description": "Saves a new, unpublished theme version, numbered one above the highest existing version. Files left out are stored empty. Nothing changes on the blog until the version is published. Requires the blog write permission.",
        "operationId": "createBlogTheme",
        "tags": [
          "Blog"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace. Passed in the query string, not the body.",
            "example": "ws_1234567890"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateBlogThemeRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Theme version created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BlogThemeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - malformed body",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Invalid request body"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing the blog write permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PermissionErrorResponse"
                },
                "example": {
                  "error": "Insufficient permissions: write access to blog required",
                  "resource": "blog",
                  "permission": "write"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/blogThemes.update": {
      "post": {
        "summary": "Update a blog theme version",
        "description": "Edits an unpublished theme version in place. Only the files named in `files` are replaced. The published version cannot be edited: create a new version, or edit an older one, and publish that instead. Requires the blog write permission.",
        "operationId": "updateBlogTheme",
        "tags": [
          "Blog"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace. Passed in the query string, not the body.",
            "example": "ws_1234567890"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateBlogThemeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Theme version updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BlogThemeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - version missing, not found or published",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "cannot update published theme"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing the blog write permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PermissionErrorResponse"
                },
                "example": {
                  "error": "Insufficient permissions: write access to blog required",
                  "resource": "blog",
                  "permission": "write"
                }
              }
            }
          }
        }
      }
    },
    "/api/blogThemes.publish": {
      "post": {
        "summary": "Publish a blog theme version",
        "description": "Makes a theme version the one the blog renders, and unpublishes the previous one in the same transaction. Any version can be published, so rolling back is publishing an older one. Requires the blog write permission.",
        "operationId": "publishBlogTheme",
        "tags": [
          "Blog"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace. Passed in the query string, not the body.",
            "example": "ws_1234567890"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublishBlogThemeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Theme version published",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Theme published successfully"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - version missing or not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "version must be positive"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing the blog write permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PermissionErrorResponse"
                },
                "example": {
                  "error": "Insufficient permissions: write access to blog required",
                  "resource": "blog",
                  "permission": "write"
                }
              }
            }
          }
        }
      }
    },
    "/api/customEvents.import": {
      "post": {
        "summary": "Import custom events",
        "description": "Imports multiple custom events in a single batch operation. Maximum 50 events per request. Auto-creates contacts if they don't exist.",
        "operationId": "importCustomEvents",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ImportCustomEventsRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Custom events imported successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ImportCustomEventsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingWorkspaceId": {
                    "value": {
                      "error": "workspace_id is required"
                    }
                  },
                  "emptyEvents": {
                    "value": {
                      "error": "events array cannot be empty"
                    }
                  },
                  "tooManyEvents": {
                    "value": {
                      "error": "maximum 50 events allowed per batch"
                    }
                  },
                  "invalidEventName": {
                    "value": {
                      "error": "invalid event name: must contain only lowercase letters, numbers, underscores, dots, and slashes"
                    }
                  },
                  "missingRequiredFields": {
                    "value": {
                      "error": "event_name, external_id, and email are required for each event"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing required permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "contacts:write permission required"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to create custom events"
                }
              }
            }
          }
        }
      }
    },
    "/api/webhookSubscriptions.create": {
      "post": {
        "summary": "Create a webhook subscription",
        "description": "Creates a new webhook subscription to receive HTTP callbacks when specified events occur in the workspace.",
        "operationId": "createWebhookSubscription",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateWebhookSubscriptionRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Webhook subscription created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateWebhookSubscriptionResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingWorkspaceId": {
                    "value": {
                      "error": "workspace_id is required"
                    }
                  },
                  "invalidUrl": {
                    "value": {
                      "error": "url must be a valid HTTPS URL"
                    }
                  },
                  "emptyEventTypes": {
                    "value": {
                      "error": "at least one event type is required"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/webhookSubscriptions.list": {
      "get": {
        "summary": "List webhook subscriptions",
        "description": "Returns all webhook subscriptions for the specified workspace.",
        "operationId": "listWebhookSubscriptions",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          }
        ],
        "responses": {
          "200": {
            "description": "List of webhook subscriptions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListWebhookSubscriptionsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing workspace_id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "workspace_id is required"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/webhookSubscriptions.get": {
      "get": {
        "summary": "Get a webhook subscription",
        "description": "Retrieves a specific webhook subscription by ID.",
        "operationId": "getWebhookSubscription",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the webhook subscription",
            "example": "whsub_a1b2c3d4e5f6"
          }
        ],
        "responses": {
          "200": {
            "description": "Webhook subscription found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetWebhookSubscriptionResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingWorkspaceId": {
                    "value": {
                      "error": "workspace_id is required"
                    }
                  },
                  "missingId": {
                    "value": {
                      "error": "id is required"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Webhook subscription not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Webhook subscription not found"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/webhookSubscriptions.update": {
      "post": {
        "summary": "Update a webhook subscription",
        "description": "Updates an existing webhook subscription with new configuration.",
        "operationId": "updateWebhookSubscription",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateWebhookSubscriptionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook subscription updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UpdateWebhookSubscriptionResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingWorkspaceId": {
                    "value": {
                      "error": "workspace_id is required"
                    }
                  },
                  "missingId": {
                    "value": {
                      "error": "id is required"
                    }
                  },
                  "invalidUrl": {
                    "value": {
                      "error": "url must be a valid HTTPS URL"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Webhook subscription not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/webhookSubscriptions.delete": {
      "post": {
        "summary": "Delete a webhook subscription",
        "description": "Permanently deletes a webhook subscription. This action cannot be undone.",
        "operationId": "deleteWebhookSubscription",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeleteWebhookSubscriptionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook subscription deleted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingWorkspaceId": {
                    "value": {
                      "error": "workspace_id is required"
                    }
                  },
                  "missingId": {
                    "value": {
                      "error": "id is required"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/webhookSubscriptions.toggle": {
      "post": {
        "summary": "Toggle webhook subscription enabled state",
        "description": "Enables or disables a webhook subscription. Disabled subscriptions will not receive events.",
        "operationId": "toggleWebhookSubscription",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ToggleWebhookSubscriptionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook subscription toggled successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ToggleWebhookSubscriptionResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingWorkspaceId": {
                    "value": {
                      "error": "workspace_id is required"
                    }
                  },
                  "missingId": {
                    "value": {
                      "error": "id is required"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/webhookSubscriptions.regenerateSecret": {
      "post": {
        "summary": "Regenerate webhook secret",
        "description": "Generates a new signing secret for the webhook subscription. The old secret will immediately become invalid.",
        "operationId": "regenerateWebhookSecret",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RegenerateWebhookSecretRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook secret regenerated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RegenerateWebhookSecretResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingWorkspaceId": {
                    "value": {
                      "error": "workspace_id is required"
                    }
                  },
                  "missingId": {
                    "value": {
                      "error": "id is required"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/webhookSubscriptions.deliveries": {
      "get": {
        "summary": "Get webhook delivery history",
        "description": "Returns the delivery history for a webhook subscription, including status and response information.",
        "operationId": "getWebhookDeliveries",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          {
            "name": "subscription_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the webhook subscription (optional - if not provided, returns all deliveries for the workspace)",
            "example": "whsub_a1b2c3d4e5f6"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "description": "Number of deliveries to return (1-100)",
            "example": 20
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "description": "Offset for pagination",
            "example": 0
          }
        ],
        "responses": {
          "200": {
            "description": "List of webhook deliveries",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListWebhookDeliveriesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "workspace_id is required"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/webhookSubscriptions.test": {
      "post": {
        "summary": "Send a test webhook",
        "description": "Sends a test webhook to the subscription's URL to verify connectivity and configuration.",
        "operationId": "testWebhookSubscription",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TestWebhookRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Test webhook sent (check response for success/failure)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TestWebhookResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingWorkspaceId": {
                    "value": {
                      "error": "workspace_id is required"
                    }
                  },
                  "missingId": {
                    "value": {
                      "error": "id is required"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Webhook subscription not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Webhook subscription not found"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/webhookSubscriptions.eventTypes": {
      "get": {
        "summary": "List available event types",
        "description": "Returns a list of all available webhook event types that can be subscribed to.",
        "operationId": "listWebhookEventTypes",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "List of available event types",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListWebhookEventTypesResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/auditLogs.list": {
      "get": {
        "summary": "List audit logs",
        "description": "Returns one page of audit entries, newest first. With scope=workspace (the default) workspace_id is required and the caller must be an owner of that workspace or hold the audit_logs read permission; with scope=deployment the caller must be a root user and every entry is returned, optionally narrowed to one workspace.\n\nNever refused for licence reasons: the page works in every licence state on whatever was recorded while a key covered audit logs.\n",
        "operationId": "listAuditLogs",
        "tags": [
          "Audit logs"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "scope",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "workspace",
                "deployment"
              ],
              "default": "workspace"
            }
          },
          {
            "name": "workspace_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Required in workspace scope; optional narrowing in deployment scope.",
            "example": "ws_1234567890"
          },
          {
            "name": "actions",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated action names, e.g. templates.update,lists.create."
          },
          {
            "name": "categories",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated categories."
          },
          {
            "name": "actor_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "actor_email",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Substring match, case-insensitive."
          },
          {
            "name": "actor_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "user",
                "api_key",
                "system",
                "anonymous"
              ]
            }
          },
          {
            "name": "outcome",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "success",
                "failure",
                "denied"
              ]
            }
          },
          {
            "name": "target_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "target_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ip_address",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Only entries at or after this instant (RFC3339). A malformed value is a 400."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The next_cursor of the previous page."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 100
            },
            "description": "Clamped to 100."
          }
        ],
        "responses": {
          "200": {
            "description": "One page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditLogListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Malformed filter",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Not an owner, no audit_logs read permission, or not root for the deployment scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/auditLogs.get": {
      "get": {
        "summary": "Get an audit log entry",
        "description": "Returns one entry by id. In workspace scope an entry of another workspace is a 404, never a leak.\n",
        "operationId": "getAuditLog",
        "tags": [
          "Audit logs"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "scope",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "workspace",
                "deployment"
              ],
              "default": "workspace"
            }
          },
          {
            "name": "workspace_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Required in workspace scope."
          }
        ],
        "responses": {
          "200": {
            "description": "The entry",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "log": {
                      "$ref": "#/components/schemas/AuditLog"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "No such entry in this scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/auditLogs.actions": {
      "get": {
        "summary": "List audit actions",
        "description": "The catalogue of every action the log can contain, sorted by name, with its category. The console builds its action filter from it.\n",
        "operationId": "listAuditActions",
        "tags": [
          "Audit logs"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "The catalogue",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "actions": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AuditActionDescriptor"
                      }
                    },
                    "categories": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or expired credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/auditLogs.export": {
      "post": {
        "summary": "Export audit logs",
        "description": "Streams the entries the filter selects, newest first, as a CSV or NDJSON file download, up to 100 000 rows. When the cap is reached the response ends with an export.truncated marker row; narrow the date range for the rest. The same authorisation as auditLogs.list applies, before the first byte is written. The export is itself recorded as auditLogs.export.\n",
        "operationId": "exportAuditLogs",
        "tags": [
          "Audit logs"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "scope": {
                    "type": "string",
                    "enum": [
                      "workspace",
                      "deployment"
                    ],
                    "default": "workspace"
                  },
                  "workspace_id": {
                    "type": "string"
                  },
                  "format": {
                    "type": "string",
                    "enum": [
                      "csv",
                      "ndjson"
                    ],
                    "default": "csv"
                  },
                  "actions": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "categories": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "actor_id": {
                    "type": "string"
                  },
                  "actor_email": {
                    "type": "string"
                  },
                  "actor_type": {
                    "type": "string"
                  },
                  "outcome": {
                    "type": "string",
                    "enum": [
                      "success",
                      "failure",
                      "denied"
                    ]
                  },
                  "target_type": {
                    "type": "string"
                  },
                  "target_id": {
                    "type": "string"
                  },
                  "ip_address": {
                    "type": "string"
                  },
                  "from": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "to": {
                    "type": "string",
                    "format": "date-time"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The file, as text/csv or application/x-ndjson with a Content-Disposition attachment header",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              },
              "application/x-ndjson": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Malformed filter or unknown format",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/workspaces.setAuditLogSettings": {
      "post": {
        "summary": "Set the workspace audit log retention",
        "description": "Owners only. retention_days absent means the deployment default; 0 keeps every entry forever; otherwise 30 to 3650. Works in every licence state.\n",
        "operationId": "setAuditLogSettings",
        "tags": [
          "Audit logs"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "workspace_id",
                  "settings"
                ],
                "properties": {
                  "workspace_id": {
                    "type": "string"
                  },
                  "settings": {
                    "$ref": "#/components/schemas/AuditLogSettings"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "success"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid retention",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Not an owner",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/subscribe": {
      "post": {
        "summary": "Subscribe to email lists",
        "description": "Subscribe a contact to one or more email lists. This is a public endpoint that doesn't require authentication.\n\n**Important:** This endpoint subscribes contacts to **public lists** only. To add a contact to a private list, use the authenticated `/api/lists.subscribe` endpoint with a bearer token. A valid `email_hmac` in the contact object only lets the contact confirm a pending double opt-in on a private list: it never adds them to one, nor back to one they left.\n\nIf the list has double opt-in enabled, a confirmation email will be sent.\n",
        "operationId": "subscribeToLists",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubscribeToListsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Subscription successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "description": "Whether the subscription was successful",
                      "example": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingWorkspaceId": {
                    "value": {
                      "error": "workspace_id is required"
                    }
                  },
                  "invalidEmail": {
                    "value": {
                      "error": "invalid contact: invalid email format"
                    }
                  },
                  "missingListIds": {
                    "value": {
                      "error": "list_ids is required"
                    }
                  },
                  "listNotPublic": {
                    "value": {
                      "error": "list is not public"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to subscribe to lists"
                }
              }
            }
          }
        }
      }
    },
    "/api/lists.subscribe": {
      "post": {
        "summary": "Subscribe to email lists (authenticated)",
        "description": "Subscribe a contact to one or more email lists. This is an authenticated endpoint that requires a bearer token.\n\nUnlike the public `/subscribe` endpoint, this endpoint can subscribe contacts to **any list** (public or private) as long as the authenticated user has write permission on lists.\n\n**Note:** Double opt-in is bypassed for authenticated requests. Contacts are immediately set to `active` status regardless of the list's double opt-in setting. This allows administrators to manually add contacts without requiring email confirmation.\n",
        "operationId": "subscribeToListsAuthenticated",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubscribeToListsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Subscription successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "description": "Whether the subscription was successful",
                      "example": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingWorkspaceId": {
                    "value": {
                      "error": "workspace_id is required"
                    }
                  },
                  "invalidEmail": {
                    "value": {
                      "error": "invalid contact: invalid email format"
                    }
                  },
                  "missingListIds": {
                    "value": {
                      "error": "list_ids is required"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to subscribe to lists"
                }
              }
            }
          }
        }
      }
    },
    "/api/user.rootSignin": {
      "post": {
        "summary": "Root user programmatic signin",
        "security": [],
        "description": "Authenticates the root user using HMAC signature for programmatic access.\nThis endpoint is designed for automation scenarios like Infrastructure-as-Code\ndeployments, CI/CD pipelines, and automated testing where magic link\nauthentication is impractical.\n\n**Security Features:**\n- HMAC-SHA256 signature verification using the application's secret key\n- 60-second timestamp window to prevent replay attacks\n- Rate limited to 5 attempts per 5 minutes per email\n- Only works for a configured root email address (ROOT_EMAIL may list several, comma/semicolon-separated)\n\n**How to generate the signature:**\n```bash\nSECRET_KEY=\"your-notifuse-secret-key\"  # the first key when SECRET_KEY lists several\nROOT_EMAIL=\"admin@example.com\"\nTIMESTAMP=$(date +%s)\nMESSAGE=\"${ROOT_EMAIL}:${TIMESTAMP}\"\nSIGNATURE=$(echo -n \"$MESSAGE\" | openssl dgst -sha256 -hmac \"$SECRET_KEY\" | awk '{print $2}')\n```\n",
        "operationId": "rootSignin",
        "tags": [
          "Authentication"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RootSigninRequest"
              },
              "example": {
                "email": "admin@example.com",
                "timestamp": 1735600000,
                "signature": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Authentication successful",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RootSigninResponse"
                },
                "example": {
                  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoidXNyXzEyMzQ1Njc4OTAiLCJzZXNzaW9uX2lkIjoic2VzXzEyMzQ1Njc4OTAiLCJleHAiOjE3MzU2ODY0MDB9.signature",
                  "user": {
                    "id": "usr_1234567890",
                    "email": "admin@example.com",
                    "name": "Admin User",
                    "created_at": "2025-01-01T00:00:00Z",
                    "updated_at": "2025-01-01T00:00:00Z"
                  },
                  "expires_at": "2025-01-01T12:00:00Z"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing required fields",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingFields": {
                    "summary": "Missing required fields",
                    "value": {
                      "error": "Missing required fields: email, timestamp, signature"
                    }
                  },
                  "invalidBody": {
                    "summary": "Invalid JSON body",
                    "value": {
                      "error": "Invalid request body"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid credentials",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalidCredentials": {
                    "summary": "Invalid email, timestamp, or signature",
                    "value": {
                      "error": "Invalid credentials"
                    }
                  },
                  "rateLimited": {
                    "summary": "Too many failed attempts",
                    "value": {
                      "error": "Invalid credentials"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Method not allowed"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API token for authentication"
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message"
          }
        },
        "required": [
          "error"
        ]
      },
      "PermissionErrorResponse": {
        "type": "object",
        "description": "Returned with a 403 when the user or API key lacks the permission the endpoint requires.",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message"
          },
          "resource": {
            "type": "string",
            "description": "The permission resource the endpoint requires.",
            "example": "blog"
          },
          "permission": {
            "type": "string",
            "enum": [
              "read",
              "write"
            ],
            "description": "The access level the endpoint requires on that resource."
          }
        },
        "required": [
          "error",
          "resource",
          "permission"
        ]
      },
      "AuditLog": {
        "type": "object",
        "description": "One recorded control-plane action. workspace_id is absent for deployment-level entries (sign-ins, the licence, the system settings).",
        "properties": {
          "id": {
            "type": "string",
            "example": "8b8dd285f6874c17b5edcb39ef3e0b8b"
          },
          "occurred_at": {
            "type": "string",
            "format": "date-time"
          },
          "workspace_id": {
            "type": "string",
            "example": "ws_1234567890"
          },
          "action": {
            "type": "string",
            "description": "The RPC route that performed the action, verbatim.",
            "example": "workspaces.inviteMember"
          },
          "category": {
            "type": "string",
            "example": "members"
          },
          "outcome": {
            "type": "string",
            "enum": [
              "success",
              "failure",
              "denied"
            ]
          },
          "status_code": {
            "type": "integer",
            "example": 200
          },
          "actor_type": {
            "type": "string",
            "enum": [
              "user",
              "api_key",
              "system",
              "anonymous"
            ]
          },
          "actor_id": {
            "type": "string"
          },
          "actor_email": {
            "type": "string"
          },
          "actor_name": {
            "type": "string"
          },
          "actor_role": {
            "type": "string",
            "enum": [
              "owner",
              "member",
              "root"
            ]
          },
          "auth_method": {
            "type": "string",
            "enum": [
              "session",
              "api_key",
              "magic_code",
              "sso",
              "root_password"
            ]
          },
          "target_type": {
            "type": "string",
            "example": "invitation"
          },
          "target_id": {
            "type": "string"
          },
          "target_name": {
            "type": "string",
            "example": "bob@example.com"
          },
          "ip_address": {
            "type": "string",
            "example": "203.0.113.9"
          },
          "user_agent": {
            "type": "string"
          },
          "request_id": {
            "type": "string",
            "description": "Echoed on every API response as X-Request-ID."
          },
          "changes": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/AuditChange"
            }
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "AuditChange": {
        "type": "object",
        "description": "One field's before and after. Secrets are replaced by \"[redacted]\" on both sides.",
        "properties": {
          "old": {
            "description": "The value before the action"
          },
          "new": {
            "description": "The value after the action"
          }
        }
      },
      "AuditLogListResponse": {
        "type": "object",
        "properties": {
          "logs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AuditLog"
            }
          },
          "next_cursor": {
            "type": "string",
            "description": "Present when has_more is true; pass it back as cursor."
          },
          "has_more": {
            "type": "boolean"
          }
        }
      },
      "AuditActionDescriptor": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "example": "templates.update"
          },
          "category": {
            "type": "string",
            "example": "templates"
          },
          "target_type": {
            "type": "string",
            "example": "template"
          }
        }
      },
      "AuditLogSettings": {
        "type": "object",
        "description": "The workspace's retention. retention_days absent means the deployment default (365 days unless a root user changed it); 0 keeps every entry forever.",
        "properties": {
          "retention_days": {
            "type": "integer",
            "minimum": 0,
            "maximum": 3650,
            "description": "0, or a value between 30 and 3650.",
            "example": 365
          }
        }
      },
      "SendTransactionalRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "notification"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          "notification": {
            "$ref": "#/components/schemas/TransactionalNotificationSendParams"
          }
        }
      },
      "TransactionalNotificationSendParams": {
        "type": "object",
        "required": [
          "id",
          "contact",
          "channels"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "ID of the notification to send",
            "example": "welcome_email"
          },
          "external_id": {
            "type": "string",
            "nullable": true,
            "description": "External ID for idempotency checks",
            "example": "txn_12345"
          },
          "contact": {
            "$ref": "#/components/schemas/Contact"
          },
          "channels": {
            "type": "array",
            "description": "Channels to send through (at least one required)",
            "minItems": 1,
            "items": {
              "type": "string",
              "enum": [
                "email"
              ]
            },
            "example": [
              "email"
            ]
          },
          "data": {
            "type": "object",
            "additionalProperties": true,
            "description": "Data to populate the template with",
            "example": {
              "user_name": "John Doe",
              "activation_link": "https://example.com/activate/abc123"
            }
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true,
            "description": "Additional metadata for tracking",
            "example": {
              "campaign_id": "spring_promo_2023",
              "source": "user_signup"
            }
          },
          "email_options": {
            "type": "object",
            "description": "Email-specific options",
            "properties": {
              "from_name": {
                "type": "string",
                "nullable": true,
                "description": "Override default sender from name",
                "example": "Support Team"
              },
              "subject": {
                "type": "string",
                "nullable": true,
                "description": "Override template subject line. Supports Liquid templating variables.",
                "maxLength": 255,
                "example": "Welcome, {{ name }}!"
              },
              "subject_preview": {
                "type": "string",
                "nullable": true,
                "description": "Override template preheader/preview text. Supports Liquid templating variables.",
                "maxLength": 255,
                "example": "Your order has been confirmed"
              },
              "cc": {
                "type": "array",
                "description": "CC email addresses",
                "items": {
                  "type": "string",
                  "format": "email"
                },
                "example": [
                  "manager@example.com"
                ]
              },
              "bcc": {
                "type": "array",
                "description": "BCC email addresses",
                "items": {
                  "type": "string",
                  "format": "email"
                },
                "example": [
                  "archive@example.com"
                ]
              },
              "reply_to": {
                "type": "string",
                "format": "email",
                "description": "Reply-To email address",
                "example": "support@example.com"
              },
              "attachments": {
                "type": "array",
                "description": "Email attachments (max 20 files, 3MB per file, 10MB total)",
                "items": {
                  "$ref": "#/components/schemas/EmailAttachment"
                },
                "maxItems": 20,
                "example": [
                  {
                    "filename": "invoice.pdf",
                    "content": "JVBERi0xLjQKJeLjz9MKMy4uLg==",
                    "content_type": "application/pdf",
                    "disposition": "attachment"
                  }
                ]
              }
            }
          }
        }
      },
      "Contact": {
        "type": "object",
        "required": [
          "email"
        ],
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "description": "Email address of the contact. This is the contact's unique identifier.",
            "example": "user@example.com"
          },
          "external_id": {
            "type": "string",
            "nullable": true,
            "description": "Identifier for the contact in your own system. Not unique — several contacts may share the same external_id.",
            "example": "user_12345"
          },
          "timezone": {
            "type": "string",
            "nullable": true,
            "description": "Timezone of the contact",
            "example": "America/New_York"
          },
          "language": {
            "type": "string",
            "nullable": true,
            "description": "Preferred language of the contact",
            "example": "en-US"
          },
          "first_name": {
            "type": "string",
            "nullable": true,
            "description": "First name of the contact",
            "example": "John"
          },
          "last_name": {
            "type": "string",
            "nullable": true,
            "description": "Last name of the contact",
            "example": "Doe"
          },
          "full_name": {
            "type": "string",
            "nullable": true,
            "description": "Full name of the contact (for systems that don't have separate first/last names)",
            "example": "John Doe"
          },
          "phone": {
            "type": "string",
            "nullable": true,
            "description": "Phone number of the contact",
            "example": "+15551234567"
          },
          "address_line_1": {
            "type": "string",
            "nullable": true,
            "description": "First line of address",
            "example": "123 Main St"
          },
          "address_line_2": {
            "type": "string",
            "nullable": true,
            "description": "Second line of address",
            "example": "Apt 4B"
          },
          "country": {
            "type": "string",
            "nullable": true,
            "description": "Country of the contact",
            "example": "US"
          },
          "postcode": {
            "type": "string",
            "nullable": true,
            "description": "Postal code",
            "example": "10001"
          },
          "state": {
            "type": "string",
            "nullable": true,
            "description": "State or province",
            "example": "NY"
          },
          "job_title": {
            "type": "string",
            "nullable": true,
            "description": "Job title of the contact",
            "example": "Software Engineer"
          },
          "tracking_opens_consent": {
            "type": "string",
            "nullable": true,
            "enum": [
              "granted",
              "denied",
              null
            ],
            "description": "The contact's own choice about open tracking; `null` means unknown."
          },
          "tracking_clicks_consent": {
            "type": "string",
            "nullable": true,
            "enum": [
              "granted",
              "denied",
              null
            ],
            "description": "The contact's own choice about click tracking; `null` means unknown."
          },
          "tracking_consent_updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When a tracking choice last changed."
          },
          "tracking_consent_source": {
            "type": "string",
            "nullable": true,
            "description": "Where the last tracking choice came from (api, console, import, notification_center, email_link, subscribe_form)."
          },
          "custom_string_1": {
            "type": "string",
            "nullable": true,
            "description": "Custom string field 1",
            "example": "Premium tier"
          },
          "custom_string_2": {
            "type": "string",
            "nullable": true,
            "description": "Custom string field 2"
          },
          "custom_string_3": {
            "type": "string",
            "nullable": true,
            "description": "Custom string field 3"
          },
          "custom_string_4": {
            "type": "string",
            "nullable": true,
            "description": "Custom string field 4"
          },
          "custom_string_5": {
            "type": "string",
            "nullable": true,
            "description": "Custom string field 5"
          },
          "custom_number_1": {
            "type": "number",
            "format": "float",
            "nullable": true,
            "description": "Custom number field 1",
            "example": 42
          },
          "custom_number_2": {
            "type": "number",
            "format": "float",
            "nullable": true,
            "description": "Custom number field 2"
          },
          "custom_number_3": {
            "type": "number",
            "format": "float",
            "nullable": true,
            "description": "Custom number field 3"
          },
          "custom_number_4": {
            "type": "number",
            "format": "float",
            "nullable": true,
            "description": "Custom number field 4"
          },
          "custom_number_5": {
            "type": "number",
            "format": "float",
            "nullable": true,
            "description": "Custom number field 5"
          },
          "custom_datetime_1": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Custom datetime field 1",
            "example": "2023-06-01T09:00:00Z"
          },
          "custom_datetime_2": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Custom datetime field 2"
          },
          "custom_datetime_3": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Custom datetime field 3"
          },
          "custom_datetime_4": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Custom datetime field 4"
          },
          "custom_datetime_5": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Custom datetime field 5"
          },
          "custom_json_1": {
            "description": "Custom JSON field 1. Any JSON value, or null.",
            "example": {
              "preferences": {
                "theme": "dark",
                "notifications": true
              }
            }
          },
          "custom_json_2": {
            "description": "Custom JSON field 2. Any JSON value, or null."
          },
          "custom_json_3": {
            "description": "Custom JSON field 3. Any JSON value, or null."
          },
          "custom_json_4": {
            "description": "Custom JSON field 4. Any JSON value, or null."
          },
          "custom_json_5": {
            "description": "Custom JSON field 5. Any JSON value, or null."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "When the contact was created (read-only, set by server)",
            "example": "2023-01-15T10:30:00Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "When the contact was last updated (read-only, set by server)",
            "example": "2023-04-22T15:45:00Z"
          },
          "contact_lists": {
            "type": "array",
            "readOnly": true,
            "description": "Lists the contact is subscribed to (read-only, included in GET responses only)",
            "items": {
              "$ref": "#/components/schemas/ContactList"
            },
            "example": [
              {
                "email": "user@example.com",
                "list_id": "newsletter",
                "list_name": "Newsletter",
                "status": "active",
                "created_at": "2023-01-15T10:30:00Z",
                "updated_at": "2023-01-15T10:30:00Z",
                "deleted_at": null
              }
            ]
          },
          "contact_segments": {
            "type": "array",
            "readOnly": true,
            "description": "Segments the contact belongs to (read-only, included in GET responses only)",
            "items": {
              "$ref": "#/components/schemas/ContactSegment"
            }
          }
        }
      },
      "ContactInput": {
        "type": "object",
        "required": [
          "email"
        ],
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "description": "Email address of the contact. This is the contact's unique identifier — upserts always match contacts by email address.",
            "example": "user@example.com"
          },
          "external_id": {
            "type": "string",
            "nullable": true,
            "description": "Optional identifier for the contact in your own system (e.g. your user ID). Stored and searchable, but not unique and never used to match contacts during upserts — sending an existing external_id with a new email address creates a second contact.",
            "example": "user_12345"
          },
          "timezone": {
            "type": "string",
            "nullable": true,
            "description": "Timezone of the contact",
            "example": "America/New_York"
          },
          "language": {
            "type": "string",
            "nullable": true,
            "description": "Preferred language of the contact",
            "example": "en-US"
          },
          "first_name": {
            "type": "string",
            "nullable": true,
            "description": "First name of the contact",
            "example": "John"
          },
          "last_name": {
            "type": "string",
            "nullable": true,
            "description": "Last name of the contact",
            "example": "Doe"
          },
          "full_name": {
            "type": "string",
            "nullable": true,
            "description": "Full name of the contact (for systems that don't have separate first/last names)",
            "example": "John Doe"
          },
          "phone": {
            "type": "string",
            "nullable": true,
            "description": "Phone number of the contact",
            "example": "+15551234567"
          },
          "address_line_1": {
            "type": "string",
            "nullable": true,
            "description": "First line of address",
            "example": "123 Main St"
          },
          "address_line_2": {
            "type": "string",
            "nullable": true,
            "description": "Second line of address",
            "example": "Apt 4B"
          },
          "country": {
            "type": "string",
            "nullable": true,
            "description": "Country of the contact",
            "example": "US"
          },
          "postcode": {
            "type": "string",
            "nullable": true,
            "description": "Postal code",
            "example": "10001"
          },
          "state": {
            "type": "string",
            "nullable": true,
            "description": "State or province",
            "example": "NY"
          },
          "job_title": {
            "type": "string",
            "nullable": true,
            "description": "Job title of the contact",
            "example": "Software Engineer"
          },
          "tracking_opens_consent": {
            "type": "string",
            "nullable": true,
            "enum": [
              "granted",
              "denied",
              null
            ],
            "description": "The contact's own choice about open tracking. `granted` or `denied` override the\nworkspace's rule for contacts without a recorded choice; `null` (or absent on\ncreate) means unknown. Opens are tracked only when the workspace tracks them and\nthis choice allows it.\n",
            "example": "denied"
          },
          "tracking_clicks_consent": {
            "type": "string",
            "nullable": true,
            "enum": [
              "granted",
              "denied",
              null
            ],
            "description": "The contact's own choice about click tracking, with the same rules as `tracking_opens_consent`.",
            "example": "granted"
          },
          "tracking_consent_updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the tracking choice changed. Set by the server when a consent value changes and\nthis field is not given.\n"
          },
          "tracking_consent_source": {
            "type": "string",
            "nullable": true,
            "maxLength": 50,
            "description": "Where the change came from. Defaults to `api` for an API key and `console` for a\nconsole user; an import uses `import`. Known values: api, console, import,\nnotification_center, email_link, subscribe_form.\n",
            "example": "api"
          },
          "custom_string_1": {
            "type": "string",
            "nullable": true,
            "description": "Custom string field 1",
            "example": "Premium tier"
          },
          "custom_string_2": {
            "type": "string",
            "nullable": true,
            "description": "Custom string field 2"
          },
          "custom_string_3": {
            "type": "string",
            "nullable": true,
            "description": "Custom string field 3"
          },
          "custom_string_4": {
            "type": "string",
            "nullable": true,
            "description": "Custom string field 4"
          },
          "custom_string_5": {
            "type": "string",
            "nullable": true,
            "description": "Custom string field 5"
          },
          "custom_number_1": {
            "type": "number",
            "format": "float",
            "nullable": true,
            "description": "Custom number field 1",
            "example": 42
          },
          "custom_number_2": {
            "type": "number",
            "format": "float",
            "nullable": true,
            "description": "Custom number field 2"
          },
          "custom_number_3": {
            "type": "number",
            "format": "float",
            "nullable": true,
            "description": "Custom number field 3"
          },
          "custom_number_4": {
            "type": "number",
            "format": "float",
            "nullable": true,
            "description": "Custom number field 4"
          },
          "custom_number_5": {
            "type": "number",
            "format": "float",
            "nullable": true,
            "description": "Custom number field 5"
          },
          "custom_datetime_1": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Custom datetime field 1",
            "example": "2023-06-01T09:00:00Z"
          },
          "custom_datetime_2": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Custom datetime field 2"
          },
          "custom_datetime_3": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Custom datetime field 3"
          },
          "custom_datetime_4": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Custom datetime field 4"
          },
          "custom_datetime_5": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Custom datetime field 5"
          },
          "custom_json_1": {
            "description": "Custom JSON field 1. Any JSON value the jsonb column can hold — an object, an array, a string, a number, a boolean, or null to clear it.",
            "example": {
              "preferences": {
                "theme": "dark",
                "notifications": true
              }
            }
          },
          "custom_json_2": {
            "description": "Custom JSON field 2. Any JSON value the jsonb column can hold."
          },
          "custom_json_3": {
            "description": "Custom JSON field 3. Any JSON value the jsonb column can hold."
          },
          "custom_json_4": {
            "description": "Custom JSON field 4. Any JSON value the jsonb column can hold."
          },
          "custom_json_5": {
            "description": "Custom JSON field 5. Any JSON value the jsonb column can hold."
          }
        }
      },
      "ContactList": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "description": "Email address of the contact",
            "example": "user@example.com"
          },
          "list_id": {
            "type": "string",
            "description": "ID of the list",
            "example": "newsletter"
          },
          "list_name": {
            "type": "string",
            "description": "Name of the list",
            "example": "Newsletter"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "pending",
              "unsubscribed",
              "bounced",
              "complained"
            ],
            "description": "Subscription status",
            "example": "active"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the contact was subscribed to this list",
            "example": "2023-01-15T10:30:00Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the subscription was last updated",
            "example": "2023-01-15T10:30:00Z"
          },
          "deleted_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the subscription was deleted (null if active)",
            "example": null
          }
        }
      },
      "ContactSegment": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "description": "Email address of the contact",
            "example": "user@example.com"
          },
          "segment_id": {
            "type": "string",
            "description": "ID of the segment",
            "example": "premium_users"
          },
          "version": {
            "type": "integer",
            "format": "int64",
            "description": "Version of the segment computation",
            "example": 1
          },
          "matched_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the contact was matched to this segment",
            "example": "2023-01-15T10:30:00Z"
          },
          "computed_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the segment was last computed",
            "example": "2023-01-15T10:30:00Z"
          }
        }
      },
      "SubscribeToListsRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "contact",
          "list_ids"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          "contact": {
            "$ref": "#/components/schemas/SubscriptionContact"
          },
          "list_ids": {
            "type": "array",
            "description": "Array of list IDs to subscribe the contact to",
            "items": {
              "type": "string"
            },
            "example": [
              "newsletter",
              "product_updates"
            ],
            "minItems": 1
          }
        }
      },
      "SubscriptionContact": {
        "type": "object",
        "required": [
          "email"
        ],
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "description": "Email address of the contact",
            "example": "user@example.com"
          },
          "email_hmac": {
            "type": "string",
            "description": "HMAC of the email for authenticated subscription (optional)",
            "example": "a1b2c3d4e5f6..."
          },
          "external_id": {
            "type": "string",
            "nullable": true,
            "description": "Optional identifier for the contact in your own system. Not unique — contacts are identified by email address.",
            "example": "user_12345"
          },
          "timezone": {
            "type": "string",
            "nullable": true,
            "description": "Timezone of the contact",
            "example": "America/New_York"
          },
          "language": {
            "type": "string",
            "nullable": true,
            "description": "Preferred language of the contact",
            "example": "en-US"
          },
          "first_name": {
            "type": "string",
            "nullable": true,
            "description": "First name of the contact",
            "example": "John"
          },
          "last_name": {
            "type": "string",
            "nullable": true,
            "description": "Last name of the contact",
            "example": "Doe"
          },
          "full_name": {
            "type": "string",
            "nullable": true,
            "description": "Full name of the contact (for systems that don't have separate first/last names)",
            "example": "John Doe"
          },
          "phone": {
            "type": "string",
            "nullable": true,
            "description": "Phone number of the contact",
            "example": "+15551234567"
          },
          "address_line_1": {
            "type": "string",
            "nullable": true,
            "description": "First line of address",
            "example": "123 Main St"
          },
          "address_line_2": {
            "type": "string",
            "nullable": true,
            "description": "Second line of address",
            "example": "Apt 4B"
          },
          "country": {
            "type": "string",
            "nullable": true,
            "description": "Country of the contact",
            "example": "US"
          },
          "postcode": {
            "type": "string",
            "nullable": true,
            "description": "Postal code",
            "example": "10001"
          },
          "state": {
            "type": "string",
            "nullable": true,
            "description": "State or province",
            "example": "NY"
          },
          "job_title": {
            "type": "string",
            "nullable": true,
            "description": "Job title of the contact",
            "example": "Software Engineer"
          },
          "tracking_opens_consent": {
            "type": "string",
            "enum": [
              "granted",
              "denied"
            ],
            "description": "The visitor's choice about open tracking, for example from a checkbox on your form.\nRecorded with source `subscribe_form` on a public request.\n"
          },
          "tracking_clicks_consent": {
            "type": "string",
            "enum": [
              "granted",
              "denied"
            ],
            "description": "The visitor's choice about click tracking, recorded like `tracking_opens_consent`."
          },
          "custom_string_1": {
            "type": "string",
            "nullable": true,
            "description": "Custom string field 1",
            "example": "Premium tier"
          },
          "custom_string_2": {
            "type": "string",
            "nullable": true,
            "description": "Custom string field 2"
          },
          "custom_string_3": {
            "type": "string",
            "nullable": true,
            "description": "Custom string field 3"
          },
          "custom_string_4": {
            "type": "string",
            "nullable": true,
            "description": "Custom string field 4"
          },
          "custom_string_5": {
            "type": "string",
            "nullable": true,
            "description": "Custom string field 5"
          },
          "custom_number_1": {
            "type": "number",
            "format": "float",
            "nullable": true,
            "description": "Custom number field 1",
            "example": 42
          },
          "custom_number_2": {
            "type": "number",
            "format": "float",
            "nullable": true,
            "description": "Custom number field 2"
          },
          "custom_number_3": {
            "type": "number",
            "format": "float",
            "nullable": true,
            "description": "Custom number field 3"
          },
          "custom_number_4": {
            "type": "number",
            "format": "float",
            "nullable": true,
            "description": "Custom number field 4"
          },
          "custom_number_5": {
            "type": "number",
            "format": "float",
            "nullable": true,
            "description": "Custom number field 5"
          },
          "custom_datetime_1": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Custom datetime field 1",
            "example": "2023-06-01T09:00:00Z"
          },
          "custom_datetime_2": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Custom datetime field 2"
          },
          "custom_datetime_3": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Custom datetime field 3"
          },
          "custom_datetime_4": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Custom datetime field 4"
          },
          "custom_datetime_5": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Custom datetime field 5"
          },
          "custom_json_1": {
            "type": "object",
            "nullable": true,
            "description": "Custom JSON field 1",
            "example": {
              "preferences": {
                "theme": "dark",
                "notifications": true
              }
            }
          },
          "custom_json_2": {
            "type": "object",
            "nullable": true,
            "description": "Custom JSON field 2"
          },
          "custom_json_3": {
            "type": "object",
            "nullable": true,
            "description": "Custom JSON field 3"
          },
          "custom_json_4": {
            "type": "object",
            "nullable": true,
            "description": "Custom JSON field 4"
          },
          "custom_json_5": {
            "type": "object",
            "nullable": true,
            "description": "Custom JSON field 5"
          }
        }
      },
      "UpsertContactRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "contact"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          "contact": {
            "$ref": "#/components/schemas/ContactInput"
          }
        }
      },
      "UpsertContactResponse": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "description": "Email address of the contact",
            "example": "user@example.com"
          },
          "action": {
            "type": "string",
            "enum": [
              "create",
              "update",
              "error"
            ],
            "description": "The action that was performed: 'create' for new contacts, 'update' for existing contacts, 'error' if validation failed",
            "example": "create"
          },
          "error": {
            "type": "string",
            "nullable": true,
            "description": "Error message if the operation failed",
            "example": null
          }
        }
      },
      "DeleteContactRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "email"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Email address of the contact to delete",
            "example": "user@example.com"
          }
        }
      },
      "BatchImportContactsRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "contacts"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          "contacts": {
            "type": "array",
            "description": "Array of contacts to import (create or update)",
            "items": {
              "$ref": "#/components/schemas/ContactInput"
            },
            "minItems": 1,
            "example": [
              {
                "email": "user1@example.com",
                "first_name": "John",
                "last_name": "Doe"
              },
              {
                "email": "user2@example.com",
                "first_name": "Jane",
                "last_name": "Smith"
              }
            ]
          },
          "subscribe_to_lists": {
            "type": "array",
            "description": "Optional array of list IDs to subscribe all contacts to",
            "items": {
              "type": "string"
            },
            "example": [
              "newsletter",
              "product_updates"
            ]
          }
        }
      },
      "BatchImportContactsResponse": {
        "type": "object",
        "properties": {
          "operations": {
            "type": "array",
            "description": "Array of operation results, one for each contact in the request",
            "items": {
              "$ref": "#/components/schemas/UpsertContactOperation"
            }
          },
          "error": {
            "type": "string",
            "nullable": true,
            "description": "Global error message if the entire operation failed",
            "example": null
          }
        }
      },
      "UpsertContactOperation": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "description": "Email address of the contact",
            "example": "user@example.com"
          },
          "action": {
            "type": "string",
            "enum": [
              "create",
              "update",
              "error"
            ],
            "description": "The action that was performed: 'create' for new contacts, 'update' for existing contacts, 'error' for failed operations",
            "example": "create"
          },
          "error": {
            "type": "string",
            "nullable": true,
            "description": "Error message if this specific contact operation failed",
            "example": null
          }
        }
      },
      "UpdateContactListStatusRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "email",
          "list_id",
          "status"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Email address of the contact",
            "example": "user@example.com"
          },
          "list_id": {
            "type": "string",
            "description": "ID of the list",
            "example": "newsletter"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "pending",
              "unsubscribed",
              "bounced",
              "complained"
            ],
            "description": "New subscription status",
            "example": "active"
          }
        }
      },
      "UpdateContactListStatusResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "Whether the operation was successful",
            "example": true
          },
          "message": {
            "type": "string",
            "description": "Status message",
            "example": "status updated successfully"
          },
          "found": {
            "type": "boolean",
            "description": "Whether the contact was found in the list",
            "example": true
          }
        }
      },
      "ListContactsResponse": {
        "type": "object",
        "properties": {
          "contacts": {
            "type": "array",
            "description": "Array of contacts matching the query",
            "items": {
              "$ref": "#/components/schemas/Contact"
            }
          },
          "next_cursor": {
            "type": "string",
            "nullable": true,
            "description": "Cursor for fetching the next page of results. Null if no more results.",
            "example": "MjAyMy0wMS0xNVQxMDozMDowMFp+dXNlckBleGFtcGxlLmNvbQ=="
          }
        }
      },
      "CountContactsResponse": {
        "type": "object",
        "properties": {
          "total_contacts": {
            "type": "integer",
            "description": "Total number of contacts in the workspace",
            "example": 1523
          }
        }
      },
      "EmailAttachment": {
        "type": "object",
        "required": [
          "filename",
          "content"
        ],
        "properties": {
          "filename": {
            "type": "string",
            "description": "Name of the file (max 255 characters, no path separators)",
            "example": "invoice.pdf",
            "maxLength": 255
          },
          "content": {
            "type": "string",
            "format": "byte",
            "description": "Base64-encoded file content (max 3MB per file)",
            "example": "JVBERi0xLjQKJeLjz9MKMy4uLg=="
          },
          "content_type": {
            "type": "string",
            "description": "MIME type of the file (auto-detected if not provided)",
            "example": "application/pdf"
          },
          "disposition": {
            "type": "string",
            "enum": [
              "attachment",
              "inline"
            ],
            "description": "How the attachment should be displayed (defaults to 'attachment')",
            "example": "attachment",
            "default": "attachment"
          },
          "content_id": {
            "type": "string",
            "description": "Content-ID for inline attachments, referenced from the HTML body as <img src=\"cid:...\"> . Only allowed when disposition is 'inline'. May only contain letters, digits, and the characters . _ - @ (max 255 characters). Defaults to the filename when omitted.",
            "example": "checkInQr",
            "maxLength": 255
          }
        }
      },
      "Broadcast": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the broadcast",
            "example": "broadcast_12345"
          },
          "workspace_id": {
            "type": "string",
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          "name": {
            "type": "string",
            "description": "Name of the broadcast",
            "example": "Spring Newsletter 2024",
            "maxLength": 255
          },
          "channel_type": {
            "type": "string",
            "description": "Communication channel type",
            "example": "email"
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "scheduled",
              "processing",
              "paused",
              "processed",
              "cancelled",
              "failed",
              "testing",
              "test_completed",
              "winner_selected"
            ],
            "description": "Current status of the broadcast",
            "example": "draft"
          },
          "audience": {
            "$ref": "#/components/schemas/AudienceSettings"
          },
          "schedule": {
            "$ref": "#/components/schemas/ScheduleSettings"
          },
          "test_settings": {
            "$ref": "#/components/schemas/BroadcastTestSettings"
          },
          "utm_parameters": {
            "$ref": "#/components/schemas/UTMParameters"
          },
          "data_feed": {
            "$ref": "#/components/schemas/DataFeedSettings"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true,
            "description": "Custom metadata for the broadcast"
          },
          "winning_template": {
            "type": "string",
            "nullable": true,
            "description": "ID of the winning template variation",
            "example": "template_winner"
          },
          "test_sent_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the A/B test was sent"
          },
          "winner_sent_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the winning variation was sent"
          },
          "enqueued_count": {
            "type": "integer",
            "description": "Number of emails added to the queue by orchestrator",
            "example": 1000
          },
          "test_phase_recipient_count": {
            "type": "integer",
            "description": "Number of recipients in test phase"
          },
          "winner_phase_recipient_count": {
            "type": "integer",
            "description": "Number of recipients in winner phase"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the broadcast was created"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the broadcast was last updated"
          },
          "started_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the broadcast started sending"
          },
          "completed_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the broadcast completed sending"
          },
          "cancelled_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the broadcast was cancelled"
          },
          "paused_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the broadcast was paused"
          },
          "pause_reason": {
            "type": "string",
            "nullable": true,
            "description": "Reason for pausing the broadcast"
          },
          "tracking_mode": {
            "type": "string",
            "enum": [
              "inherit",
              "no_tracking"
            ],
            "description": "Absent or `inherit` follows the workspace tracking settings and each recipient's\ntracking consent (stored as absent). `no_tracking` sends every email without the\nopen pixel and the click-tracking redirect, keeping the UTM parameters; it cannot be\ncombined with an A/B test whose winner is sent automatically.\n"
          }
        }
      },
      "BroadcastTestSettings": {
        "type": "object",
        "properties": {
          "enabled": {
            "type": "boolean",
            "description": "Whether A/B testing is enabled",
            "example": true
          },
          "sample_percentage": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "description": "Percentage of audience to use for testing",
            "example": 20
          },
          "auto_send_winner": {
            "type": "boolean",
            "description": "Automatically send winning variation to remaining audience",
            "example": true
          },
          "auto_send_winner_metric": {
            "type": "string",
            "enum": [
              "open_rate",
              "click_rate"
            ],
            "description": "Metric used to determine the winner",
            "example": "open_rate"
          },
          "test_duration_hours": {
            "type": "integer",
            "minimum": 1,
            "maximum": 168,
            "description": "Duration of the test in hours (max 7 days)",
            "example": 24
          },
          "variations": {
            "type": "array",
            "description": "Test variations (2-8 variations allowed)",
            "minItems": 2,
            "maxItems": 8,
            "items": {
              "$ref": "#/components/schemas/BroadcastVariation"
            }
          }
        }
      },
      "BroadcastVariation": {
        "type": "object",
        "required": [
          "template_id"
        ],
        "properties": {
          "variation_name": {
            "type": "string",
            "description": "Name of this variation",
            "example": "Variation A"
          },
          "template_id": {
            "type": "string",
            "description": "Template ID for this variation",
            "example": "template_variant_a"
          },
          "metrics": {
            "$ref": "#/components/schemas/VariationMetrics"
          },
          "template": {
            "type": "object",
            "nullable": true,
            "description": "Full template object (populated when with_templates=true)"
          }
        }
      },
      "VariationMetrics": {
        "type": "object",
        "properties": {
          "recipients": {
            "type": "integer",
            "description": "Number of recipients"
          },
          "delivered": {
            "type": "integer",
            "description": "Number of delivered messages"
          },
          "opens": {
            "type": "integer",
            "description": "Number of opens"
          },
          "clicks": {
            "type": "integer",
            "description": "Number of clicks"
          },
          "bounced": {
            "type": "integer",
            "description": "Number of bounces"
          },
          "complained": {
            "type": "integer",
            "description": "Number of complaints"
          },
          "unsubscribed": {
            "type": "integer",
            "description": "Number of unsubscribes"
          }
        }
      },
      "AudienceSettings": {
        "type": "object",
        "required": [
          "list"
        ],
        "properties": {
          "list": {
            "type": "string",
            "description": "List ID to send to",
            "example": "newsletter"
          },
          "segments": {
            "type": "array",
            "description": "Optional segment IDs to filter recipients",
            "items": {
              "type": "string"
            },
            "example": [
              "premium_users"
            ]
          },
          "exclude_unsubscribed": {
            "type": "boolean",
            "default": true,
            "description": "Whether to exclude the list's unsubscribed contacts. Omitting the key excludes them; send false to mail them too, e.g. for a legal notice. With false the emails carry no List-Unsubscribe and List-Unsubscribe-Post headers. Bounced and complained contacts are never mailed, whatever this value.",
            "example": true
          }
        }
      },
      "AudienceSettingsPatch": {
        "type": "object",
        "description": "The audience keys a broadcasts.update body carries. Same fields as AudienceSettings, but none of them is required: each key the body names replaces the stored value and each key it leaves out keeps it.",
        "properties": {
          "list": {
            "type": "string",
            "description": "List ID to send to. Omit to keep the stored list.",
            "example": "newsletter"
          },
          "segments": {
            "type": "array",
            "description": "Segment IDs to filter recipients. Omit to keep the stored segments; send an empty array to remove segment targeting and send to the whole list.",
            "items": {
              "type": "string"
            },
            "example": [
              "premium_users"
            ]
          },
          "exclude_unsubscribed": {
            "type": "boolean",
            "description": "Whether to exclude the list's unsubscribed contacts. Omit to keep the stored value; send false to mail them too, in emails without the List-Unsubscribe and List-Unsubscribe-Post headers. Bounced and complained contacts are never mailed, whatever this value.",
            "example": true
          }
        }
      },
      "ScheduleSettings": {
        "type": "object",
        "description": "Schedule settings for a broadcast. Note: When a broadcast is first created,\nthese fields are empty/false. Use the /api/broadcasts.schedule endpoint to\nconfigure scheduling.\n",
        "properties": {
          "is_scheduled": {
            "type": "boolean",
            "description": "Whether the broadcast is scheduled (false after creation, set via broadcasts.schedule)",
            "example": false
          },
          "scheduled_date": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "description": "Scheduled date in YYYY-MM-DD format",
            "example": "2024-03-15"
          },
          "scheduled_time": {
            "type": "string",
            "pattern": "^\\d{2}:\\d{2}$",
            "description": "Scheduled time in HH:MM format",
            "example": "10:30"
          },
          "timezone": {
            "type": "string",
            "description": "IANA timezone",
            "example": "America/New_York"
          },
          "use_recipient_timezone": {
            "type": "boolean",
            "description": "Send at scheduled time in each recipient's timezone",
            "example": false
          }
        }
      },
      "UTMParameters": {
        "type": "object",
        "properties": {
          "source": {
            "type": "string",
            "description": "UTM source parameter",
            "example": "newsletter"
          },
          "medium": {
            "type": "string",
            "description": "UTM medium parameter",
            "example": "email"
          },
          "campaign": {
            "type": "string",
            "description": "UTM campaign parameter",
            "example": "spring_2024"
          },
          "term": {
            "type": "string",
            "description": "UTM term parameter"
          },
          "content": {
            "type": "string",
            "description": "UTM content parameter"
          }
        }
      },
      "CreateBroadcastRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "name",
          "audience"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          "name": {
            "type": "string",
            "description": "Name of the broadcast",
            "example": "Spring Newsletter 2024",
            "maxLength": 255
          },
          "audience": {
            "$ref": "#/components/schemas/AudienceSettings"
          },
          "test_settings": {
            "$ref": "#/components/schemas/BroadcastTestSettings"
          },
          "utm_parameters": {
            "$ref": "#/components/schemas/UTMParameters"
          },
          "data_feed": {
            "$ref": "#/components/schemas/DataFeedSettings"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true,
            "description": "Custom metadata for the broadcast"
          },
          "tracking_mode": {
            "type": "string",
            "enum": [
              "inherit",
              "no_tracking"
            ],
            "description": "See `Broadcast.tracking_mode`."
          }
        }
      },
      "UpdateBroadcastRequest": {
        "type": "object",
        "description": "Partial update of a broadcast. workspace_id, id and name are always applied; audience is merged one key at a time, and schedule, test_settings, utm_parameters, metadata, data_feed and tracking_mode keep their stored value when the key is left out of the body. Send the key to change it — including an explicitly empty object to clear it.",
        "required": [
          "workspace_id",
          "id",
          "name"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          "id": {
            "type": "string",
            "description": "ID of the broadcast to update",
            "example": "broadcast_12345"
          },
          "name": {
            "type": "string",
            "description": "Name of the broadcast",
            "example": "Spring Newsletter 2024",
            "maxLength": 255
          },
          "audience": {
            "allOf": [
              {
                "$ref": "#/components/schemas/AudienceSettingsPatch"
              }
            ],
            "description": "Merged into the stored audience one key at a time, so a body naming only list retargets the broadcast without dropping its segments or its exclusion of unsubscribed contacts. Omit the whole object to leave the audience untouched."
          },
          "schedule": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ScheduleSettings"
              }
            ],
            "description": "Omit to keep the stored schedule. Sending it replaces the schedule wholesale, so a body carrying an empty or partial object clears is_scheduled — which a later resume reads to decide between restoring the schedule and sending now."
          },
          "test_settings": {
            "allOf": [
              {
                "$ref": "#/components/schemas/BroadcastTestSettings"
              }
            ],
            "description": "Omit to keep the stored test settings. These hold the broadcast's template variations, so sending a partial object detaches its templates."
          },
          "utm_parameters": {
            "allOf": [
              {
                "$ref": "#/components/schemas/UTMParameters"
              }
            ],
            "description": "Omit to keep the stored UTM parameters; send an empty object to clear them."
          },
          "data_feed": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DataFeedSettings"
              }
            ],
            "description": "Omit to keep the stored data feed settings and their last fetched data."
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true,
            "description": "Custom metadata for the broadcast. Omit to keep the stored metadata; send an empty object to clear it."
          },
          "tracking_mode": {
            "type": "string",
            "enum": [
              "inherit",
              "no_tracking"
            ],
            "description": "Omit to keep the stored mode. Can be changed only while the broadcast is a draft or scheduled. See `Broadcast.tracking_mode`."
          }
        }
      },
      "ScheduleBroadcastRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "id"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          "id": {
            "type": "string",
            "description": "ID of the broadcast to schedule",
            "example": "broadcast_12345"
          },
          "send_now": {
            "type": "boolean",
            "description": "Send immediately instead of scheduling",
            "example": false
          },
          "scheduled_date": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "description": "Scheduled date in YYYY-MM-DD format (required if send_now=false)",
            "example": "2024-03-15"
          },
          "scheduled_time": {
            "type": "string",
            "pattern": "^\\d{2}:\\d{2}$",
            "description": "Scheduled time in HH:MM format (required if send_now=false)",
            "example": "10:30"
          },
          "timezone": {
            "type": "string",
            "description": "IANA timezone",
            "example": "America/New_York"
          },
          "use_recipient_timezone": {
            "type": "boolean",
            "description": "Send at scheduled time in each recipient's timezone",
            "example": false
          }
        }
      },
      "PauseBroadcastRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "id"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          "id": {
            "type": "string",
            "description": "ID of the broadcast to pause",
            "example": "broadcast_12345"
          }
        }
      },
      "ResumeBroadcastRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "id"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          "id": {
            "type": "string",
            "description": "ID of the broadcast to resume",
            "example": "broadcast_12345"
          }
        }
      },
      "CancelBroadcastRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "id"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          "id": {
            "type": "string",
            "description": "ID of the broadcast to cancel",
            "example": "broadcast_12345"
          }
        }
      },
      "DeleteBroadcastRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "id"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          "id": {
            "type": "string",
            "description": "ID of the broadcast to delete",
            "example": "broadcast_12345"
          }
        }
      },
      "SendToIndividualRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "broadcast_id",
          "recipient_email"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          "broadcast_id": {
            "type": "string",
            "description": "ID of the broadcast",
            "example": "broadcast_12345"
          },
          "recipient_email": {
            "type": "string",
            "format": "email",
            "description": "Email address to send test to",
            "example": "test@example.com"
          },
          "template_id": {
            "type": "string",
            "description": "Optional specific template variation to send",
            "example": "template_variant_a"
          }
        }
      },
      "SelectWinnerRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "id",
          "template_id"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          "id": {
            "type": "string",
            "description": "ID of the broadcast",
            "example": "broadcast_12345"
          },
          "template_id": {
            "type": "string",
            "description": "Template ID of the winning variation",
            "example": "template_variant_a"
          }
        }
      },
      "BroadcastListResponse": {
        "type": "object",
        "properties": {
          "broadcasts": {
            "type": "array",
            "description": "List of broadcasts",
            "items": {
              "$ref": "#/components/schemas/Broadcast"
            }
          },
          "total_count": {
            "type": "integer",
            "description": "Total number of broadcasts matching the query",
            "example": 45
          }
        }
      },
      "VariationResult": {
        "type": "object",
        "properties": {
          "template_id": {
            "type": "string",
            "description": "Template ID for this variation",
            "example": "template_variant_a"
          },
          "template_name": {
            "type": "string",
            "description": "Template name",
            "example": "Variation A"
          },
          "recipients": {
            "type": "integer",
            "description": "Total sent emails",
            "example": 1000
          },
          "delivered": {
            "type": "integer",
            "description": "Total delivered emails",
            "example": 980
          },
          "opens": {
            "type": "integer",
            "description": "Number of opens",
            "example": 450
          },
          "clicks": {
            "type": "integer",
            "description": "Number of clicks",
            "example": 120
          },
          "opens_tracked": {
            "type": "integer",
            "description": "Sent emails of this variation that carried the open pixel",
            "example": 1000
          },
          "clicks_tracked": {
            "type": "integer",
            "description": "Sent emails of this variation whose links were tracked",
            "example": 1000
          },
          "open_rate": {
            "type": "number",
            "format": "float",
            "description": "Open rate (opens / opens_tracked); 0 when no email was tracked",
            "example": 0.45
          },
          "click_rate": {
            "type": "number",
            "format": "float",
            "description": "Click rate (clicks / clicks_tracked); 0 when no email was tracked",
            "example": 0.12
          }
        }
      },
      "TestResultsResponse": {
        "type": "object",
        "properties": {
          "broadcast_id": {
            "type": "string",
            "description": "ID of the broadcast",
            "example": "broadcast_12345"
          },
          "status": {
            "type": "string",
            "description": "Current broadcast status",
            "example": "testing"
          },
          "test_started_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the test started"
          },
          "test_completed_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the test completed"
          },
          "variation_results": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/VariationResult"
            },
            "description": "Results for each variation, keyed by template_id"
          },
          "recommended_winner": {
            "type": "string",
            "nullable": true,
            "description": "Recommended winning template ID based on metrics",
            "example": "template_variant_a"
          },
          "winning_template": {
            "type": "string",
            "nullable": true,
            "description": "Selected winning template ID",
            "example": "template_variant_a"
          },
          "is_auto_send_winner": {
            "type": "boolean",
            "description": "Whether winner will be automatically sent",
            "example": true
          }
        }
      },
      "DataFeedHeader": {
        "type": "object",
        "required": [
          "name",
          "value"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "HTTP header name",
            "example": "Authorization"
          },
          "value": {
            "type": "string",
            "description": "HTTP header value",
            "example": "Bearer token123"
          }
        }
      },
      "GlobalFeedSettings": {
        "type": "object",
        "properties": {
          "enabled": {
            "type": "boolean",
            "description": "Whether the global data feed is enabled",
            "example": true
          },
          "url": {
            "type": "string",
            "description": "URL endpoint to fetch global data from (must be HTTPS)",
            "example": "https://api.example.com/broadcast-data"
          },
          "headers": {
            "type": "array",
            "description": "Custom HTTP headers to include in the request",
            "items": {
              "$ref": "#/components/schemas/DataFeedHeader"
            }
          }
        }
      },
      "RecipientFeedSettings": {
        "type": "object",
        "properties": {
          "enabled": {
            "type": "boolean",
            "description": "Whether the per-recipient data feed is enabled",
            "example": true
          },
          "url": {
            "type": "string",
            "description": "URL endpoint to fetch per-recipient data from (must be HTTPS)",
            "example": "https://api.example.com/recipient-data"
          },
          "headers": {
            "type": "array",
            "description": "Custom HTTP headers to include in the request",
            "items": {
              "$ref": "#/components/schemas/DataFeedHeader"
            }
          }
        }
      },
      "DataFeedSettings": {
        "type": "object",
        "description": "Configuration for external data feeds",
        "properties": {
          "global_feed": {
            "$ref": "#/components/schemas/GlobalFeedSettings"
          },
          "global_feed_data": {
            "type": "object",
            "additionalProperties": true,
            "description": "Cached data from the global feed (populated after fetch)"
          },
          "global_feed_fetched_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the global feed was last fetched"
          },
          "recipient_feed": {
            "$ref": "#/components/schemas/RecipientFeedSettings"
          }
        }
      },
      "RefreshGlobalFeedRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "broadcast_id",
          "url"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          "broadcast_id": {
            "type": "string",
            "description": "ID of the broadcast",
            "example": "broadcast_12345"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "The feed URL to fetch data from",
            "example": "https://api.example.com/feed/global"
          },
          "headers": {
            "type": "array",
            "description": "Optional custom headers to send with the request",
            "items": {
              "$ref": "#/components/schemas/DataFeedHeader"
            }
          }
        }
      },
      "RefreshGlobalFeedResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "Whether the refresh was successful",
            "example": true
          },
          "data": {
            "type": "object",
            "additionalProperties": true,
            "description": "The fetched data from the global feed"
          },
          "fetched_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the data was fetched"
          },
          "error": {
            "type": "string",
            "description": "Error message if the refresh failed",
            "example": null
          }
        }
      },
      "TestRecipientFeedRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "broadcast_id",
          "url"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          "broadcast_id": {
            "type": "string",
            "description": "ID of the broadcast",
            "example": "broadcast_12345"
          },
          "contact_email": {
            "type": "string",
            "format": "email",
            "description": "Optional email of a specific contact to test with. If not provided, uses a random contact from the audience.",
            "example": "john@example.com"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "The feed URL to fetch data from (must use HTTPS)",
            "example": "https://api.example.com/feed/recipient"
          },
          "headers": {
            "type": "array",
            "description": "Optional custom headers to send with the request",
            "items": {
              "$ref": "#/components/schemas/DataFeedHeader"
            }
          }
        }
      },
      "TestRecipientFeedResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "Whether the test was successful",
            "example": true
          },
          "data": {
            "type": "object",
            "additionalProperties": true,
            "description": "The fetched data from the recipient feed"
          },
          "fetched_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the data was fetched"
          },
          "error": {
            "type": "string",
            "description": "Error message if the test failed",
            "example": null
          },
          "contact_email": {
            "type": "string",
            "format": "email",
            "description": "Email of the contact used for the test",
            "example": "john@example.com"
          }
        }
      },
      "Template": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the template (alphanumeric, underscores, and hyphens only)",
            "example": "welcome_email",
            "maxLength": 32,
            "pattern": "^[a-zA-Z0-9_-]+$"
          },
          "name": {
            "type": "string",
            "description": "Name of the template",
            "example": "Welcome Email",
            "maxLength": 255
          },
          "version": {
            "type": "integer",
            "format": "int64",
            "description": "Version number of the template",
            "example": 1
          },
          "channel": {
            "type": "string",
            "enum": [
              "email",
              "web"
            ],
            "description": "Communication channel",
            "example": "email"
          },
          "email": {
            "$ref": "#/components/schemas/EmailTemplate"
          },
          "web": {
            "$ref": "#/components/schemas/WebTemplate"
          },
          "category": {
            "type": "string",
            "enum": [
              "marketing",
              "transactional",
              "welcome",
              "opt_in",
              "unsubscribe",
              "bounce",
              "blocklist",
              "blog",
              "other"
            ],
            "description": "Template category",
            "example": "transactional",
            "maxLength": 20
          },
          "template_macro_id": {
            "type": "string",
            "nullable": true,
            "description": "ID of the template macro (layout) to use"
          },
          "integration_id": {
            "type": "string",
            "nullable": true,
            "readOnly": true,
            "description": "ID of the integration managing this template (e.g., Supabase). Server-owned: it is set when the integration creates the template and cannot be set or changed through the API."
          },
          "test_data": {
            "type": "object",
            "additionalProperties": true,
            "description": "Test data for template preview",
            "example": {
              "user_name": "John Doe",
              "action_url": "https://example.com/action"
            }
          },
          "settings": {
            "type": "object",
            "additionalProperties": true,
            "description": "Channel-specific third-party settings"
          },
          "translations": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/TemplateTranslation"
            },
            "description": "Per-language content variants, keyed by language code",
            "example": {
              "fr": {
                "email": {
                  "subject": "Bienvenue"
                }
              }
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the template was created"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the template was last updated"
          },
          "deleted_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the template was deleted, null while it is active. Deleted templates no longer appear in `templates.list`, but `templates.get` still returns them, because messages already sent are rendered from them."
          }
        },
        "required": [
          "id",
          "name",
          "channel",
          "category"
        ]
      },
      "EmailTemplate": {
        "type": "object",
        "properties": {
          "editor_mode": {
            "type": "string",
            "enum": [
              "visual",
              "code"
            ],
            "default": "visual",
            "description": "Which editor the email is written in. `visual` stores the drag-and-drop block tree in `visual_editor_tree`; `code` stores raw MJML in `mjml_source`. The mode is set when the template is created and cannot be changed afterwards: an update in the other mode is refused with a 400. To switch, create a new template in the other mode."
          },
          "mjml_source": {
            "type": "string",
            "description": "Raw MJML source (supports Liquid templating). Required when `editor_mode` is `code`, ignored otherwise.",
            "example": "<mjml><mj-body><mj-section><mj-column><mj-text>Hello {{ contact.first_name }}</mj-text></mj-column></mj-section></mj-body></mjml>"
          },
          "sender_id": {
            "type": "string",
            "description": "ID of the sender configuration to use",
            "example": "sender_123"
          },
          "reply_to": {
            "type": "string",
            "format": "email",
            "description": "Reply-To email address",
            "example": "support@example.com"
          },
          "subject": {
            "type": "string",
            "description": "Email subject line (supports Liquid templating)",
            "example": "Welcome, {{user_name}}!"
          },
          "subject_preview": {
            "type": "string",
            "nullable": true,
            "description": "Preview text shown in email clients",
            "example": "Get started with your account"
          },
          "compiled_preview": {
            "type": "string",
            "description": "Compiled HTML preview of the email"
          },
          "visual_editor_tree": {
            "type": "object",
            "description": "MJML visual editor tree structure. Required when `editor_mode` is `visual` (the default), ignored in `code` mode.",
            "example": {
              "type": "mjml",
              "children": []
            }
          },
          "text": {
            "type": "string",
            "nullable": true,
            "description": "Plain text version of the email"
          }
        },
        "required": [
          "subject",
          "compiled_preview"
        ]
      },
      "WebTemplate": {
        "type": "object",
        "properties": {
          "content": {
            "type": "object",
            "additionalProperties": true,
            "description": "Tiptap JSON content (source of truth for web templates)"
          },
          "html": {
            "type": "string",
            "description": "Pre-rendered HTML for display"
          },
          "plain_text": {
            "type": "string",
            "description": "Extracted text for search indexing"
          }
        },
        "required": [
          "content"
        ]
      },
      "CreateTemplateRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "id",
          "name",
          "channel",
          "category"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          "id": {
            "type": "string",
            "description": "Unique identifier for the template (alphanumeric, underscores, and hyphens only)",
            "example": "welcome_email",
            "maxLength": 32,
            "pattern": "^[a-zA-Z0-9_-]+$"
          },
          "name": {
            "type": "string",
            "description": "Name of the template",
            "example": "Welcome Email",
            "maxLength": 255
          },
          "channel": {
            "type": "string",
            "enum": [
              "email",
              "web"
            ],
            "description": "Communication channel",
            "example": "email"
          },
          "email": {
            "$ref": "#/components/schemas/EmailTemplate"
          },
          "web": {
            "$ref": "#/components/schemas/WebTemplate"
          },
          "category": {
            "type": "string",
            "enum": [
              "marketing",
              "transactional",
              "welcome",
              "opt_in",
              "unsubscribe",
              "bounce",
              "blocklist",
              "blog",
              "other"
            ],
            "description": "Template category",
            "example": "transactional"
          },
          "template_macro_id": {
            "type": "string",
            "nullable": true,
            "description": "ID of the template macro (layout) to use"
          },
          "test_data": {
            "type": "object",
            "additionalProperties": true,
            "description": "Test data for template preview"
          },
          "settings": {
            "type": "object",
            "additionalProperties": true,
            "description": "Channel-specific settings"
          },
          "translations": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/TemplateTranslation"
            },
            "description": "Per-language content variants, keyed by language code. Every key must be one of the workspace's configured languages."
          }
        }
      },
      "UpdateTemplateRequest": {
        "type": "object",
        "description": "Replaces the template's content, creating a new version. Fields the body omits are not cleared: translations are carried over from the stored template, and integration_id is server-owned and always preserved.",
        "required": [
          "workspace_id",
          "id",
          "name",
          "channel",
          "category"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          "id": {
            "type": "string",
            "description": "ID of the template to update",
            "example": "welcome_email",
            "maxLength": 32
          },
          "name": {
            "type": "string",
            "description": "Name of the template",
            "example": "Welcome Email",
            "maxLength": 255
          },
          "channel": {
            "type": "string",
            "enum": [
              "email",
              "web"
            ],
            "description": "Communication channel",
            "example": "email"
          },
          "email": {
            "$ref": "#/components/schemas/EmailTemplate"
          },
          "web": {
            "$ref": "#/components/schemas/WebTemplate"
          },
          "category": {
            "type": "string",
            "enum": [
              "marketing",
              "transactional",
              "welcome",
              "opt_in",
              "unsubscribe",
              "bounce",
              "blocklist",
              "blog",
              "other"
            ],
            "description": "Template category",
            "example": "transactional"
          },
          "template_macro_id": {
            "type": "string",
            "nullable": true,
            "description": "ID of the template macro (layout) to use"
          },
          "test_data": {
            "type": "object",
            "additionalProperties": true,
            "description": "Test data for template preview"
          },
          "settings": {
            "type": "object",
            "additionalProperties": true,
            "description": "Channel-specific settings"
          },
          "translations": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/TemplateTranslation"
            },
            "description": "Per-language content variants, keyed by language code. Every key must be one of the workspace's configured languages. Omit the property to keep the stored translations untouched; send an empty object to delete all of them."
          }
        }
      },
      "DeleteTemplateRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "id"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          "id": {
            "type": "string",
            "description": "ID of the template to delete",
            "example": "welcome_email"
          }
        }
      },
      "CompileTemplateRequest": {
        "type": "object",
        "description": "Provide `visual_editor_tree` for a visual-mode template, or `mjml_source` for a code-mode one.",
        "required": [
          "workspace_id",
          "message_id"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          "message_id": {
            "type": "string",
            "description": "Unique message ID for tracking",
            "example": "msg_abc123"
          },
          "visual_editor_tree": {
            "type": "object",
            "description": "MJML visual editor tree structure (must have type 'mjml')",
            "additionalProperties": true
          },
          "mjml_source": {
            "type": "string",
            "description": "Raw MJML source of a code-mode template. When set, it is compiled instead of `visual_editor_tree`."
          },
          "subject": {
            "type": "string",
            "description": "Optional email subject. When provided, it is rendered through the same\nLiquid engine the send path uses (with `test_data`) and the rendered\nresult is returned as `subject` in the response. Liquid processing is\nskipped when `preserve_liquid` is true, `channel` is `web`, or\n`test_data` is empty.\n",
            "example": "Hi {{ contact.first_name }}"
          },
          "subject_preview": {
            "type": "string",
            "description": "Optional inbox preview text (the snippet shown after the subject in\nmost clients). Rendered through Liquid like `subject` and returned as\n`subject_preview` in the response.\n",
            "example": "Welcome {{ contact.first_name }}"
          },
          "test_data": {
            "type": "object",
            "description": "Data to use for Liquid templating",
            "additionalProperties": true,
            "example": {
              "user_name": "John Doe",
              "action_url": "https://example.com/action"
            }
          },
          "tracking_settings": {
            "$ref": "#/components/schemas/TrackingSettings"
          },
          "channel": {
            "type": "string",
            "enum": [
              "email",
              "web"
            ],
            "description": "Which channel this template targets. It selects the content object the template must carry: an `email` template supplies `email` and omits `web`, and a `web` template does the reverse."
          }
        }
      },
      "CompileTemplateResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "Whether compilation was successful"
          },
          "mjml": {
            "type": "string",
            "description": "Generated MJML markup"
          },
          "html": {
            "type": "string",
            "description": "Compiled HTML output"
          },
          "subject": {
            "type": "string",
            "description": "Rendered email subject. Present only when the request included a\nnon-empty `subject`. Returned on both success and error paths so the\ncaller can display the rendered subject alongside any compilation\nerror.\n",
            "example": "Hi Pierre"
          },
          "subject_preview": {
            "type": "string",
            "description": "Rendered inbox preview text. Present only when the request included a\nnon-empty `subject_preview`. Returned on both success and error paths.\n",
            "example": "Welcome Pierre"
          },
          "error": {
            "type": "object",
            "description": "MJML compilation error details, if any",
            "properties": {
              "message": {
                "type": "string"
              }
            }
          }
        }
      },
      "TrackingSettings": {
        "type": "object",
        "properties": {
          "enable_tracking": {
            "type": "boolean",
            "description": "Whether to enable click/open tracking"
          },
          "tracking_mode": {
            "type": "string",
            "enum": [
              "inherit",
              "no_tracking",
              "disabled"
            ],
            "description": "Per-notification tracking preference. Absent or \"inherit\" follows the\nworkspace tracking settings and each recipient's tracking consent (the\nworkspace settings always act as a kill-switch and cannot be\noverridden). \"no_tracking\" leaves out the open pixel and the\nclick-tracking redirect but keeps the UTM parameters. \"disabled\" suppresses all\nrewriting for this notification — no click-tracking redirect, no open\npixel, and no UTM parameters — used for auth emails (e.g. Supabase\nmagic links) whose single-use URLs must never be modified. Update\nsemantics: an ABSENT tracking_mode field keeps the stored value (so\npartial edits cannot wipe an opt-out; an empty string is treated as\nabsent); an explicit \"inherit\" resets the notification to follow the\nworkspace flag; an explicit \"disabled\" opts it out. Note that the\nother tracking_settings fields (utm_*) are replaced wholesale on\nupdate — only tracking_mode has keep-when-absent semantics.\n"
          },
          "endpoint": {
            "type": "string",
            "description": "API endpoint for tracking redirects"
          },
          "utm_source": {
            "type": "string",
            "description": "UTM source parameter"
          },
          "utm_medium": {
            "type": "string",
            "description": "UTM medium parameter"
          },
          "utm_campaign": {
            "type": "string",
            "description": "UTM campaign parameter"
          },
          "utm_content": {
            "type": "string",
            "description": "UTM content parameter"
          },
          "utm_term": {
            "type": "string",
            "description": "UTM term parameter"
          },
          "workspace_id": {
            "type": "string",
            "description": "Workspace ID for tracking"
          },
          "message_id": {
            "type": "string",
            "description": "Message ID for tracking"
          }
        }
      },
      "SEOSettings": {
        "type": "object",
        "description": "Search and social metadata for the page, exposed to the blog theme.",
        "properties": {
          "meta_title": {
            "type": "string",
            "example": "Release notes for October"
          },
          "meta_description": {
            "type": "string",
            "example": "Everything that shipped this month."
          },
          "og_title": {
            "type": "string",
            "description": "Open Graph title"
          },
          "og_description": {
            "type": "string",
            "description": "Open Graph description"
          },
          "og_image": {
            "type": "string",
            "description": "Open Graph image URL",
            "example": "https://cdn.example.com/og/october.png"
          },
          "canonical_url": {
            "type": "string",
            "example": "https://blog.example.com/product/october-release"
          },
          "keywords": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "release",
              "changelog"
            ]
          },
          "meta_robots": {
            "type": "string",
            "description": "Content of the robots meta tag.",
            "example": "index,follow"
          }
        }
      },
      "BlogAuthor": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "example": "Jane Doe"
          },
          "avatar_url": {
            "type": "string",
            "example": "https://cdn.example.com/avatars/jane.png"
          }
        }
      },
      "BlogCategory": {
        "type": "object",
        "required": [
          "id",
          "slug",
          "settings",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Server-generated UUID.",
            "example": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
          },
          "slug": {
            "type": "string",
            "description": "The category's path segment on the blog (`/{category_slug}`).",
            "example": "product"
          },
          "settings": {
            "type": "object",
            "required": [
              "name"
            ],
            "properties": {
              "name": {
                "type": "string",
                "example": "Product"
              },
              "description": {
                "type": "string",
                "example": "Release notes and product announcements."
              },
              "seo": {
                "$ref": "#/components/schemas/SEOSettings"
              }
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CreateBlogCategoryRequest": {
        "type": "object",
        "required": [
          "name",
          "slug"
        ],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 255,
            "example": "Product"
          },
          "slug": {
            "type": "string",
            "maxLength": 100,
            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
            "description": "Lowercase letters, digits and single hyphens. Must be unique among the workspace's categories.",
            "example": "product"
          },
          "description": {
            "type": "string",
            "example": "Release notes and product announcements."
          },
          "seo": {
            "$ref": "#/components/schemas/SEOSettings"
          }
        }
      },
      "UpdateBlogCategoryRequest": {
        "type": "object",
        "required": [
          "id",
          "name",
          "slug"
        ],
        "description": "A full replacement, not a patch: `description` and `seo` are cleared when omitted. Send the category back with your changes applied.",
        "properties": {
          "id": {
            "type": "string",
            "example": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
          },
          "name": {
            "type": "string",
            "maxLength": 255,
            "example": "Product"
          },
          "slug": {
            "type": "string",
            "maxLength": 100,
            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
            "description": "Changing it changes the URL of the category page and of every post in it. No redirect is created from the old URLs.",
            "example": "product"
          },
          "description": {
            "type": "string"
          },
          "seo": {
            "$ref": "#/components/schemas/SEOSettings"
          }
        }
      },
      "BlogCategoryResponse": {
        "type": "object",
        "required": [
          "category"
        ],
        "properties": {
          "category": {
            "$ref": "#/components/schemas/BlogCategory"
          }
        }
      },
      "ListBlogCategoriesResponse": {
        "type": "object",
        "required": [
          "categories",
          "total_count"
        ],
        "properties": {
          "categories": {
            "type": "array",
            "nullable": true,
            "description": "Every category, newest first. `null` rather than `[]` when there are none.",
            "items": {
              "$ref": "#/components/schemas/BlogCategory"
            }
          },
          "total_count": {
            "type": "integer",
            "example": 3
          }
        }
      },
      "BlogPost": {
        "type": "object",
        "required": [
          "id",
          "category_id",
          "slug",
          "settings",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Server-generated UUID.",
            "example": "1b4e28ba-2fa1-11d2-883f-0016d3cca427"
          },
          "category_id": {
            "type": "string",
            "example": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
          },
          "slug": {
            "type": "string",
            "description": "The post's path segment on the blog (`/{category_slug}/{post_slug}`).",
            "example": "october-release"
          },
          "settings": {
            "type": "object",
            "required": [
              "title",
              "template",
              "reading_time_minutes"
            ],
            "properties": {
              "title": {
                "type": "string",
                "description": "The post's H1.",
                "example": "What shipped in October"
              },
              "template": {
                "type": "object",
                "required": [
                  "template_id",
                  "template_version"
                ],
                "description": "The web template holding the post body.",
                "properties": {
                  "template_id": {
                    "type": "string",
                    "example": "blog_october_release"
                  },
                  "template_version": {
                    "type": "integer",
                    "description": "The template version the post renders. `0` means the latest version, whatever it is at render time.",
                    "example": 3
                  }
                }
              },
              "excerpt": {
                "type": "string",
                "example": "A faster editor, scheduled broadcasts and a new API."
              },
              "featured_image_url": {
                "type": "string",
                "example": "https://cdn.example.com/blog/october.png"
              },
              "authors": {
                "type": "array",
                "nullable": true,
                "items": {
                  "$ref": "#/components/schemas/BlogAuthor"
                }
              },
              "reading_time_minutes": {
                "type": "integer",
                "description": "Displayed as given; not computed from the body.",
                "example": 4
              },
              "seo": {
                "$ref": "#/components/schemas/SEOSettings"
              }
            }
          },
          "published_at": {
            "type": "string",
            "format": "date-time",
            "description": "Absent while the post is a draft.",
            "example": "2026-10-01T09:00:00Z"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CreateBlogPostRequest": {
        "type": "object",
        "required": [
          "category_id",
          "slug",
          "title",
          "template_id"
        ],
        "properties": {
          "category_id": {
            "type": "string",
            "description": "An existing category.",
            "example": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
          },
          "slug": {
            "type": "string",
            "maxLength": 100,
            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
            "description": "Lowercase letters, digits and single hyphens. Must be unique across the whole workspace, not just within the category.",
            "example": "october-release"
          },
          "title": {
            "type": "string",
            "maxLength": 500,
            "example": "What shipped in October"
          },
          "template_id": {
            "type": "string",
            "description": "A web template (`channel: web`) holding the post body — create it first with `templates.create`. Its existence is not checked here: a post pointing at a missing template is saved and renders with an empty body.",
            "example": "blog_october_release"
          },
          "template_version": {
            "type": "integer",
            "default": 0,
            "description": "The template version to render. Omit it (or send `0`) to always render the template's latest version; pin a version to control exactly when a template edit reaches readers.",
            "example": 1
          },
          "excerpt": {
            "type": "string",
            "example": "A faster editor, scheduled broadcasts and a new API."
          },
          "featured_image_url": {
            "type": "string",
            "example": "https://cdn.example.com/blog/october.png"
          },
          "authors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BlogAuthor"
            }
          },
          "reading_time_minutes": {
            "type": "integer",
            "example": 4
          },
          "seo": {
            "$ref": "#/components/schemas/SEOSettings"
          }
        }
      },
      "UpdateBlogPostRequest": {
        "allOf": [
          {
            "type": "object",
            "required": [
              "id"
            ],
            "description": "A full replacement, not a patch: every optional field omitted here is cleared, including `template_version`, which falls back to `0` (latest version). Send the post back with your changes applied.",
            "properties": {
              "id": {
                "type": "string",
                "example": "1b4e28ba-2fa1-11d2-883f-0016d3cca427"
              }
            }
          },
          {
            "$ref": "#/components/schemas/CreateBlogPostRequest"
          }
        ]
      },
      "BlogPostResponse": {
        "type": "object",
        "required": [
          "post"
        ],
        "properties": {
          "post": {
            "$ref": "#/components/schemas/BlogPost"
          }
        }
      },
      "ListBlogPostsResponse": {
        "type": "object",
        "required": [
          "posts",
          "total_count"
        ],
        "properties": {
          "posts": {
            "type": "array",
            "nullable": true,
            "description": "The requested page. `null` rather than `[]` when the page is empty.",
            "items": {
              "$ref": "#/components/schemas/BlogPost"
            }
          },
          "total_count": {
            "type": "integer",
            "description": "Posts matching the filters across all pages.",
            "example": 128
          }
        }
      },
      "PublishBlogPostRequest": {
        "type": "object",
        "required": [
          "id"
        ],
        "properties": {
          "id": {
            "type": "string",
            "example": "1b4e28ba-2fa1-11d2-883f-0016d3cca427"
          },
          "published_at": {
            "type": "string",
            "format": "date-time",
            "description": "The publication date to record, defaulting to now. Use it to backdate posts you import. A future date does not schedule the post: it goes live on the blog immediately, and only its appearance in the RSS and JSON feeds waits for the date.",
            "example": "2024-03-12T08:00:00Z"
          }
        }
      },
      "BlogPostIdRequest": {
        "type": "object",
        "required": [
          "id"
        ],
        "properties": {
          "id": {
            "type": "string",
            "example": "1b4e28ba-2fa1-11d2-883f-0016d3cca427"
          }
        }
      },
      "BlogThemeFiles": {
        "type": "object",
        "description": "The theme's source files. Liquid files render the blog's pages; see the blog theme guide for the variables each one receives.",
        "properties": {
          "home.liquid": {
            "type": "string",
            "description": "The blog home page."
          },
          "category.liquid": {
            "type": "string",
            "description": "A category page."
          },
          "post.liquid": {
            "type": "string",
            "description": "A post page."
          },
          "header.liquid": {
            "type": "string"
          },
          "footer.liquid": {
            "type": "string"
          },
          "shared.liquid": {
            "type": "string",
            "description": "Snippets shared by the other templates."
          },
          "styles.css": {
            "type": "string"
          },
          "scripts.js": {
            "type": "string"
          }
        }
      },
      "BlogTheme": {
        "type": "object",
        "required": [
          "version",
          "files",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "version": {
            "type": "integer",
            "description": "Assigned on creation, one above the highest existing version.",
            "example": 4
          },
          "published_at": {
            "type": "string",
            "format": "date-time",
            "description": "Present only on the theme currently live on the blog."
          },
          "published_by_user_id": {
            "type": "string",
            "description": "The user or API key that published it. Present only on the live theme."
          },
          "files": {
            "$ref": "#/components/schemas/BlogThemeFiles"
          },
          "notes": {
            "type": "string",
            "example": "Darker header, larger body text."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CreateBlogThemeRequest": {
        "type": "object",
        "properties": {
          "files": {
            "$ref": "#/components/schemas/BlogThemeFiles"
          },
          "notes": {
            "type": "string",
            "example": "Darker header, larger body text."
          }
        }
      },
      "UpdateBlogThemeRequest": {
        "type": "object",
        "required": [
          "version"
        ],
        "properties": {
          "version": {
            "type": "integer",
            "description": "An unpublished theme version.",
            "example": 4
          },
          "files": {
            "allOf": [
              {
                "$ref": "#/components/schemas/BlogThemeFiles"
              }
            ],
            "description": "Only the files named here are replaced; the others keep their stored content. Send a file as `\"\"` to empty it."
          },
          "notes": {
            "type": "string",
            "description": "Kept as stored when omitted."
          }
        }
      },
      "PublishBlogThemeRequest": {
        "type": "object",
        "required": [
          "version"
        ],
        "properties": {
          "version": {
            "type": "integer",
            "example": 4
          }
        }
      },
      "BlogThemeResponse": {
        "type": "object",
        "required": [
          "theme"
        ],
        "properties": {
          "theme": {
            "$ref": "#/components/schemas/BlogTheme"
          }
        }
      },
      "ListBlogThemesResponse": {
        "type": "object",
        "required": [
          "themes",
          "total_count"
        ],
        "properties": {
          "themes": {
            "type": "array",
            "nullable": true,
            "description": "Newest version first. `null` rather than `[]` when the page is empty.",
            "items": {
              "$ref": "#/components/schemas/BlogTheme"
            }
          },
          "total_count": {
            "type": "integer",
            "description": "Theme versions in the workspace across all pages.",
            "example": 4
          }
        }
      },
      "CustomEvent": {
        "type": "object",
        "description": "The current state of an external resource, identified by the (event_name, external_id) pair rather than by a server-generated id. Writing the same pair again updates the stored resource instead of appending a new event.",
        "required": [
          "event_name",
          "external_id",
          "email"
        ],
        "properties": {
          "event_name": {
            "type": "string",
            "description": "Event type name (lowercase letters, numbers, underscores, dots, and slashes only)",
            "example": "orders/fulfilled",
            "maxLength": 100,
            "pattern": "^[a-z0-9_./-]+$"
          },
          "external_id": {
            "type": "string",
            "description": "External system identifier for this event",
            "example": "shopify_order_12345",
            "maxLength": 255
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Contact email address",
            "example": "customer@example.com"
          },
          "properties": {
            "type": "object",
            "additionalProperties": true,
            "description": "The complete current state of the resource, as arbitrary JSON. Replaced wholesale by any write that includes it, so send every property you want kept, not only the ones that changed. Omit the field to leave the stored properties untouched; send an empty object to clear them all. Always an object on the way back, never null: a write answers with the properties the row holds afterwards, not with the ones the request carried.",
            "example": {
              "order_total": 129.99,
              "product_name": "Premium Subscription",
              "quantity": 1
            }
          },
          "occurred_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When this version of the resource was produced (allows backdating). Also acts as the ordering guard on an existing resource: unless deleted_at also changes, a write whose occurred_at is not strictly newer than the stored one is discarded in full — including its goal fields — and still answers success. Omitting the field defaults it to the time of the request, which always passes the guard.",
            "example": "2023-05-15T14:30:00Z"
          },
          "source": {
            "type": "string",
            "enum": [
              "api",
              "integration",
              "import",
              "web_analytics"
            ],
            "description": "Origin of the event, set by the server on the write that creates it and never moved afterwards, so a later write from another channel cannot relabel where a resource came from. Read-only.",
            "example": "api",
            "default": "api"
          },
          "integration_id": {
            "type": "string",
            "nullable": true,
            "description": "Optional reference to the integration that created the event. Preserved when a later write omits it, so an API call cannot accidentally unlink a resource from the integration that owns it.",
            "example": "shopify_integration_123"
          },
          "goal_type": {
            "type": "string",
            "enum": [
              "purchase",
              "subscription",
              "lead",
              "signup",
              "booking",
              "trial",
              "other"
            ],
            "nullable": true,
            "description": "Type of goal for conversion tracking. Required for goal_value to have meaning. Kept when a later write omits it, so a resource can be promoted to a goal after the fact; once set it can be changed but not cleared.",
            "example": "purchase"
          },
          "goal_name": {
            "type": "string",
            "nullable": true,
            "maxLength": 100,
            "description": "Optional goal name for categorization (e.g., 'first_purchase', 'monthly_subscription'). Kept when a later write omits it; once set it can be changed but not cleared.",
            "example": "first_purchase"
          },
          "goal_value": {
            "type": "number",
            "format": "double",
            "nullable": true,
            "description": "Monetary value of the goal. Required for 'purchase' and 'subscription' goal types. Can be negative for refunds/chargebacks. Kept when a later write omits it; once set it can be changed but not cleared.",
            "example": 99.99
          },
          "deleted_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Soft delete timestamp. Set to delete an event, set to null to restore.",
            "example": null
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the event was created in the system",
            "example": "2023-05-15T14:30:00Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the event was last updated",
            "example": "2023-05-15T14:30:00Z"
          }
        }
      },
      "ImportCustomEventsRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "events"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          "events": {
            "type": "array",
            "description": "Array of custom events to import (1-50 events)",
            "minItems": 1,
            "maxItems": 50,
            "items": {
              "type": "object",
              "description": "Each entry is an upsert on the (event_name, external_id) pair, not an append: an entry naming a resource that already exists updates it. Fields the entry leaves out keep the value already stored, so a partial entry is a safe way to correct one attribute. The exception is properties, which is replaced wholesale whenever the entry includes it.",
              "required": [
                "event_name",
                "external_id",
                "email"
              ],
              "properties": {
                "event_name": {
                  "type": "string",
                  "description": "Event type name",
                  "example": "orders/fulfilled",
                  "maxLength": 100,
                  "pattern": "^[a-z0-9_./-]+$"
                },
                "external_id": {
                  "type": "string",
                  "description": "External system identifier",
                  "example": "shopify_order_12345",
                  "maxLength": 255
                },
                "email": {
                  "type": "string",
                  "format": "email",
                  "description": "Contact email address",
                  "example": "customer@example.com"
                },
                "properties": {
                  "type": "object",
                  "additionalProperties": true,
                  "description": "The complete state of the resource. Omit the field to leave the stored properties untouched; send an empty object to clear them all. Including it replaces the stored set rather than merging into it, so restate every property you want kept.",
                  "example": {
                    "order_total": 129.99,
                    "product_name": "Premium Subscription"
                  }
                },
                "occurred_at": {
                  "type": "string",
                  "format": "date-time",
                  "description": "When this version of the resource was produced. On an entry naming an existing resource it is also the ordering guard: unless deleted_at also changes, an entry whose occurred_at is not strictly newer than the stored one is discarded in full and still counted as imported. Defaults to the time of the request.",
                  "example": "2023-05-15T14:30:00Z"
                },
                "source": {
                  "type": "string",
                  "enum": [
                    "api",
                    "integration",
                    "import"
                  ],
                  "description": "Origin to record, defaulting to 'api' when the entry omits it. It applies only where the entry creates the resource: an entry naming one that already exists leaves the stored origin alone, so re-importing cannot relabel a resource an integration created.",
                  "example": "api"
                },
                "integration_id": {
                  "type": "string",
                  "description": "Integration reference. Preserved when the entry omits it, so re-importing does not unlink a resource from the integration that owns it.",
                  "example": "shopify_integration_123"
                },
                "goal_type": {
                  "type": "string",
                  "enum": [
                    "purchase",
                    "subscription",
                    "lead",
                    "signup",
                    "booking",
                    "trial",
                    "other"
                  ],
                  "description": "Type of goal for conversion tracking. Kept when the entry omits it; once set it can be changed but not cleared.",
                  "example": "purchase"
                },
                "goal_name": {
                  "type": "string",
                  "maxLength": 100,
                  "description": "Optional goal name for categorization. Kept when the entry omits it; once set it can be changed but not cleared.",
                  "example": "first_purchase"
                },
                "goal_value": {
                  "type": "number",
                  "format": "double",
                  "description": "Monetary value (required for purchase/subscription, can be negative for refunds). Kept when the entry omits it; once set it can be changed but not cleared.",
                  "example": 99.99
                },
                "deleted_at": {
                  "type": "string",
                  "format": "date-time",
                  "description": "Soft delete timestamp",
                  "example": null
                }
              }
            },
            "example": [
              {
                "event_name": "orders/fulfilled",
                "external_id": "shopify_order_12345",
                "email": "customer@example.com",
                "properties": {
                  "order_total": 129.99,
                  "product_name": "Premium Subscription"
                },
                "occurred_at": "2023-05-15T14:30:00Z"
              },
              {
                "event_name": "payment/succeeded",
                "external_id": "stripe_payment_67890",
                "email": "customer@example.com",
                "properties": {
                  "amount": 129.99,
                  "currency": "USD"
                },
                "occurred_at": "2023-05-15T14:29:00Z"
              }
            ]
          }
        }
      },
      "ImportCustomEventsResponse": {
        "type": "object",
        "properties": {
          "event_ids": {
            "type": "array",
            "description": "External IDs of successfully imported events",
            "items": {
              "type": "string"
            },
            "example": [
              "shopify_order_12345",
              "stripe_payment_67890"
            ]
          },
          "count": {
            "type": "integer",
            "description": "Number of events created",
            "example": 2
          }
        }
      },
      "WebhookSubscription": {
        "type": "object",
        "description": "A webhook subscription that receives HTTP callbacks when events occur",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the subscription",
            "example": "whsub_a1b2c3d4e5f6"
          },
          "name": {
            "type": "string",
            "description": "Human-readable name for the subscription",
            "example": "Production Webhook"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "The HTTPS URL to receive webhook events",
            "example": "https://api.example.com/webhooks/notifuse"
          },
          "secret": {
            "type": "string",
            "description": "Secret key for signing webhook payloads (Standard Webhooks spec)",
            "example": "whsec_a1b2c3d4e5f6g7h8i9j0"
          },
          "settings": {
            "$ref": "#/components/schemas/WebhookSubscriptionSettings"
          },
          "event_types": {
            "type": "array",
            "description": "List of event types this subscription is subscribed to (flattened from settings for convenience)",
            "items": {
              "type": "string"
            },
            "example": [
              "contact.created",
              "contact.updated",
              "email.sent"
            ]
          },
          "custom_event_filters": {
            "$ref": "#/components/schemas/CustomEventFilters",
            "description": "Optional filters for custom_event.* event types (flattened from settings for convenience)"
          },
          "list_ids": {
            "type": "array",
            "description": "Lists the list.* events are narrowed to (flattened from settings for convenience). Absent or empty means every list.",
            "items": {
              "type": "string"
            },
            "example": [
              "newsletter",
              "product_updates"
            ]
          },
          "segment_ids": {
            "type": "array",
            "description": "Segments the segment.* events are narrowed to (flattened from settings for convenience). Absent or empty means every segment.",
            "items": {
              "type": "string"
            },
            "example": [
              "vip_customers"
            ]
          },
          "enabled": {
            "type": "boolean",
            "description": "Whether the subscription is currently active",
            "example": true
          },
          "last_delivery_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Timestamp of the last delivery attempt",
            "example": "2024-01-15T10:30:00Z"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the subscription was created",
            "example": "2024-01-01T00:00:00Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the subscription was last updated",
            "example": "2024-01-15T10:30:00Z"
          }
        }
      },
      "WebhookDelivery": {
        "type": "object",
        "description": "A record of a webhook delivery attempt",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the delivery",
            "example": "whdel_x1y2z3"
          },
          "subscription_id": {
            "type": "string",
            "description": "ID of the subscription this delivery belongs to",
            "example": "whsub_a1b2c3d4e5f6"
          },
          "event_type": {
            "type": "string",
            "description": "Type of event that triggered the delivery",
            "example": "contact.created"
          },
          "payload": {
            "type": "object",
            "description": "The JSON payload sent in the webhook",
            "additionalProperties": true
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "delivering",
              "delivered",
              "failed"
            ],
            "description": "Current status of the delivery",
            "example": "delivered"
          },
          "attempts": {
            "type": "integer",
            "description": "Number of delivery attempts made",
            "example": 1
          },
          "max_attempts": {
            "type": "integer",
            "description": "Maximum number of retry attempts",
            "example": 10
          },
          "next_attempt_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the next retry will be attempted",
            "example": "2024-01-15T10:35:00Z"
          },
          "last_attempt_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the last attempt was made",
            "example": "2024-01-15T10:30:00Z"
          },
          "delivered_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the delivery was successfully completed",
            "example": "2024-01-15T10:30:00Z"
          },
          "last_response_status": {
            "type": "integer",
            "nullable": true,
            "description": "HTTP status code from the last attempt",
            "example": 200
          },
          "last_response_body": {
            "type": "string",
            "nullable": true,
            "description": "Response body from the last attempt (truncated)",
            "example": "{\"received\": true}"
          },
          "last_error": {
            "type": "string",
            "nullable": true,
            "description": "Error message from the last failed attempt",
            "example": null
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the delivery was created",
            "example": "2024-01-15T10:30:00Z"
          }
        }
      },
      "WebhookEventType": {
        "type": "string",
        "description": "Available webhook event types",
        "enum": [
          "contact.created",
          "contact.updated",
          "contact.deleted",
          "list.subscribed",
          "list.unsubscribed",
          "list.confirmed",
          "list.resubscribed",
          "list.bounced",
          "list.complained",
          "list.pending",
          "list.removed",
          "segment.joined",
          "segment.left",
          "email.sent",
          "email.delivered",
          "email.opened",
          "email.clicked",
          "email.bounced",
          "email.complained",
          "email.unsubscribed",
          "custom_event.created",
          "custom_event.updated",
          "custom_event.deleted"
        ]
      },
      "CustomEventFilters": {
        "type": "object",
        "nullable": true,
        "description": "Optional filters for custom_event.* event types",
        "properties": {
          "goal_types": {
            "type": "array",
            "nullable": true,
            "description": "Filter by goal type (e.g., purchase, subscription, lead)",
            "items": {
              "type": "string"
            },
            "example": [
              "purchase",
              "subscription"
            ]
          },
          "event_names": {
            "type": "array",
            "nullable": true,
            "description": "Filter by event name (e.g., orders/fulfilled, payment.succeeded)",
            "items": {
              "type": "string"
            },
            "example": [
              "orders/fulfilled",
              "payment.succeeded"
            ]
          }
        }
      },
      "WebhookSubscriptionSettings": {
        "type": "object",
        "description": "Settings for webhook subscription",
        "properties": {
          "event_types": {
            "type": "array",
            "description": "List of event types this subscription is subscribed to",
            "items": {
              "type": "string"
            },
            "example": [
              "contact.created",
              "contact.updated",
              "email.sent"
            ]
          },
          "custom_event_filters": {
            "$ref": "#/components/schemas/CustomEventFilters"
          },
          "list_ids": {
            "type": "array",
            "description": "Lists the list.* events are narrowed to. Absent or empty means every list.",
            "items": {
              "type": "string"
            },
            "example": [
              "newsletter",
              "product_updates"
            ]
          },
          "segment_ids": {
            "type": "array",
            "description": "Segments the segment.* events are narrowed to. Absent or empty means every segment.",
            "items": {
              "type": "string"
            },
            "example": [
              "vip_customers"
            ]
          }
        }
      },
      "CreateWebhookSubscriptionRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "name",
          "url",
          "event_types"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          "name": {
            "type": "string",
            "description": "Human-readable name for the subscription",
            "example": "Production Webhook",
            "minLength": 1,
            "maxLength": 255
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "The HTTPS URL to receive webhook events",
            "example": "https://api.example.com/webhooks/notifuse"
          },
          "event_types": {
            "type": "array",
            "description": "List of event types to subscribe to",
            "items": {
              "type": "string"
            },
            "minItems": 1,
            "example": [
              "contact.created",
              "contact.updated"
            ]
          },
          "custom_event_filters": {
            "$ref": "#/components/schemas/CustomEventFilters"
          },
          "list_ids": {
            "type": "array",
            "description": "Narrow the list.* events to these lists. Omit it, or send an empty array, to receive an event for every list in the workspace.",
            "items": {
              "type": "string"
            },
            "example": [
              "newsletter",
              "product_updates"
            ]
          },
          "segment_ids": {
            "type": "array",
            "description": "Narrow the segment.* events to these segments. Omit it, or send an empty array, to receive an event for every segment in the workspace.",
            "items": {
              "type": "string"
            },
            "example": [
              "vip_customers"
            ]
          }
        }
      },
      "CreateWebhookSubscriptionResponse": {
        "type": "object",
        "properties": {
          "subscription": {
            "$ref": "#/components/schemas/WebhookSubscription"
          }
        }
      },
      "UpdateWebhookSubscriptionRequest": {
        "type": "object",
        "description": "A replace for what identifies the subscription — name, url and event_types are required and are written as sent — and a patch for everything that narrows it. Omitting enabled, custom_event_filters, list_ids or segment_ids leaves the stored value alone; a JSON null reads the same way. Send an explicitly empty array or object to remove a filter.",
        "required": [
          "workspace_id",
          "id",
          "name",
          "url",
          "event_types"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          "id": {
            "type": "string",
            "description": "The ID of the subscription to update",
            "example": "whsub_a1b2c3d4e5f6"
          },
          "name": {
            "type": "string",
            "description": "Updated name",
            "example": "Production Webhook Updated"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Updated URL",
            "example": "https://api.example.com/webhooks/notifuse/v2"
          },
          "event_types": {
            "type": "array",
            "description": "Updated list of event types",
            "items": {
              "type": "string"
            },
            "example": [
              "contact.created",
              "contact.updated",
              "contact.deleted"
            ]
          },
          "custom_event_filters": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CustomEventFilters"
              }
            ],
            "description": "Filters for the custom_event.* events. Omit it to leave the stored filters unchanged; send an empty object to stop filtering custom events."
          },
          "list_ids": {
            "type": "array",
            "nullable": true,
            "description": "Lists the list.* events are narrowed to. Omit it to leave the stored filter unchanged — a body that never mentions it cannot widen the subscription — and send an empty array to remove the narrowing.",
            "items": {
              "type": "string"
            },
            "example": [
              "newsletter",
              "product_updates"
            ]
          },
          "segment_ids": {
            "type": "array",
            "nullable": true,
            "description": "Segments the segment.* events are narrowed to. Omit it to leave the stored filter unchanged; send an empty array to remove the narrowing.",
            "items": {
              "type": "string"
            },
            "example": [
              "vip_customers"
            ]
          },
          "enabled": {
            "type": "boolean",
            "description": "Whether the subscription is enabled. Omit it to leave the stored value unchanged; send it only to switch the subscription on or off.",
            "example": true
          }
        }
      },
      "UpdateWebhookSubscriptionResponse": {
        "type": "object",
        "properties": {
          "subscription": {
            "$ref": "#/components/schemas/WebhookSubscription"
          }
        }
      },
      "DeleteWebhookSubscriptionRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "id"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          "id": {
            "type": "string",
            "description": "The ID of the subscription to delete",
            "example": "whsub_a1b2c3d4e5f6"
          }
        }
      },
      "ToggleWebhookSubscriptionRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "id",
          "enabled"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          "id": {
            "type": "string",
            "description": "The ID of the subscription",
            "example": "whsub_a1b2c3d4e5f6"
          },
          "enabled": {
            "type": "boolean",
            "description": "Whether to enable or disable the subscription",
            "example": true
          }
        }
      },
      "ToggleWebhookSubscriptionResponse": {
        "type": "object",
        "properties": {
          "subscription": {
            "$ref": "#/components/schemas/WebhookSubscription"
          }
        }
      },
      "RegenerateWebhookSecretRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "id"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          "id": {
            "type": "string",
            "description": "The ID of the subscription",
            "example": "whsub_a1b2c3d4e5f6"
          }
        }
      },
      "RegenerateWebhookSecretResponse": {
        "type": "object",
        "properties": {
          "subscription": {
            "$ref": "#/components/schemas/WebhookSubscription"
          }
        }
      },
      "ListWebhookSubscriptionsResponse": {
        "type": "object",
        "properties": {
          "subscriptions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookSubscription"
            }
          }
        }
      },
      "GetWebhookSubscriptionResponse": {
        "type": "object",
        "properties": {
          "subscription": {
            "$ref": "#/components/schemas/WebhookSubscription"
          }
        }
      },
      "ListWebhookDeliveriesResponse": {
        "type": "object",
        "properties": {
          "deliveries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookDelivery"
            }
          },
          "total": {
            "type": "integer",
            "description": "Total number of deliveries",
            "example": 150
          },
          "limit": {
            "type": "integer",
            "description": "Number of deliveries per page",
            "example": 20
          },
          "offset": {
            "type": "integer",
            "description": "Offset for pagination",
            "example": 0
          }
        }
      },
      "TestWebhookRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "id"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          "id": {
            "type": "string",
            "description": "The ID of the subscription to test",
            "example": "whsub_a1b2c3d4e5f6"
          },
          "event_type": {
            "type": "string",
            "description": "Optional event type to use for the test webhook payload",
            "example": "contact.created"
          }
        }
      },
      "TestWebhookResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "Whether the test webhook was delivered successfully",
            "example": true
          },
          "status_code": {
            "type": "integer",
            "description": "HTTP status code returned by the webhook endpoint",
            "example": 200
          },
          "response_body": {
            "type": "string",
            "description": "Response body from the webhook endpoint",
            "example": "{\"received\": true}"
          },
          "error": {
            "type": "string",
            "nullable": true,
            "description": "Error message if the test failed",
            "example": null
          }
        }
      },
      "ListWebhookEventTypesResponse": {
        "type": "object",
        "properties": {
          "event_types": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "contact.created",
              "contact.updated",
              "contact.deleted",
              "list.subscribed",
              "list.unsubscribed",
              "email.sent",
              "email.delivered"
            ]
          }
        }
      },
      "RootSigninRequest": {
        "type": "object",
        "description": "Request payload for root user programmatic signin using HMAC signature",
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "description": "The root user's email address (must match one of the configured ROOT_EMAIL addresses)",
            "example": "admin@example.com"
          },
          "timestamp": {
            "type": "integer",
            "format": "int64",
            "description": "Unix timestamp (seconds since epoch). Must be within 60 seconds of server time.",
            "example": 1735600000
          },
          "signature": {
            "type": "string",
            "description": "HMAC-SHA256 signature computed as: HMAC-SHA256(email + \":\" + timestamp, SECRET_KEY), with the first key when SECRET_KEY lists several.\nThe signature should be hex-encoded.\n",
            "example": "a1b2c3d4e5f6..."
          }
        },
        "required": [
          "email",
          "timestamp",
          "signature"
        ]
      },
      "RootSigninResponse": {
        "type": "object",
        "description": "Successful authentication response containing JWT token and user details",
        "properties": {
          "token": {
            "type": "string",
            "description": "JWT authentication token for subsequent API requests",
            "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
          },
          "user": {
            "$ref": "#/components/schemas/User"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Token expiration timestamp",
            "example": "2025-01-01T12:00:00Z"
          }
        },
        "required": [
          "token",
          "user",
          "expires_at"
        ]
      },
      "User": {
        "type": "object",
        "description": "User account information",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique user identifier",
            "example": "usr_1234567890"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "User's email address",
            "example": "admin@example.com"
          },
          "name": {
            "type": "string",
            "description": "User's display name",
            "example": "Admin User"
          },
          "language": {
            "type": "string",
            "description": "User's preferred locale for the console UI and system emails",
            "example": "en"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Account creation timestamp",
            "example": "2025-01-01T00:00:00Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Last update timestamp",
            "example": "2025-01-01T00:00:00Z"
          }
        },
        "required": [
          "id",
          "email"
        ]
      },
      "WebPageviewAction": {
        "type": "object",
        "description": "One pageview of the cumulative action list. Breaking any bound below drops this action alone; the rest of the beat is still accepted.",
        "required": [
          "type",
          "path",
          "page_number"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "pageview"
            ]
          },
          "path": {
            "type": "string",
            "maxLength": 2048
          },
          "page_number": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000
          },
          "duration": {
            "type": "integer",
            "format": "int64",
            "minimum": 0,
            "maximum": 86400000,
            "description": "Engaged (visible and focused) time on the page, ms. Capped at a day, which is more engaged time than one page can plausibly collect."
          },
          "scroll": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "entered_at": {
            "type": "integer",
            "format": "int64",
            "minimum": 0,
            "maximum": 100000000000000,
            "description": "Epoch ms, bounded to what a timestamp column can hold rather than to a window: a replayed offline beat legitimately carries an old timestamp."
          },
          "exited_at": {
            "type": "integer",
            "format": "int64",
            "minimum": 0,
            "maximum": 100000000000000,
            "description": "Epoch ms; when both are set, must be >= entered_at."
          }
        }
      },
      "WebGoalAction": {
        "type": "object",
        "description": "One conversion of the cumulative action list. Breaking any bound below drops this action alone; the rest of the beat is still accepted.",
        "required": [
          "type",
          "name",
          "path",
          "page_number",
          "timestamp"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "goal"
            ]
          },
          "name": {
            "type": "string",
            "maxLength": 100
          },
          "path": {
            "type": "string",
            "maxLength": 2048
          },
          "page_number": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000
          },
          "timestamp": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "maximum": 100000000000000,
            "description": "Original client timestamp in epoch ms; part of the goal's dedup key, so a retried beat lands on the same row. Bounded to what a timestamp column can hold, not to a window."
          },
          "value": {
            "type": "number",
            "minimum": 0,
            "maximum": 1000000000000
          },
          "properties": {
            "type": "object",
            "maxProperties": 50,
            "additionalProperties": {
              "type": "string",
              "maxLength": 1024
            },
            "description": "At most 50 keys, 1024 characters per value and 8 KB in total: the action list is cumulative, so an unbounded map is re-sent forever and would eventually push the body past the 1 MB limit."
          }
        }
      },
      "WebSessionAttributes": {
        "type": "object",
        "required": [
          "landing_page"
        ],
        "properties": {
          "referrer": {
            "type": "string"
          },
          "landing_page": {
            "type": "string"
          },
          "utm_source": {
            "type": "string"
          },
          "utm_medium": {
            "type": "string"
          },
          "utm_campaign": {
            "type": "string"
          },
          "utm_term": {
            "type": "string"
          },
          "utm_content": {
            "type": "string"
          },
          "utm_id": {
            "type": "string"
          },
          "utm_id_from": {
            "type": "string"
          },
          "screen_width": {
            "type": "integer"
          },
          "screen_height": {
            "type": "integer"
          },
          "viewport_width": {
            "type": "integer"
          },
          "viewport_height": {
            "type": "integer"
          },
          "device": {
            "type": "string",
            "description": "Device class, one of desktop, mobile or tablet. Detected IN THE BROWSER by the SDK, not re-parsed from user_agent server-side: modern browsers freeze the UA string and expose the real device, OS and version only through the Client Hints API, which never reaches the server. Client input, so it is trimmed to 200 characters and stored as sent. Defaults to \"desktop\" when absent or blank."
          },
          "browser": {
            "type": "string",
            "description": "Browser name from the same in-browser detection (\"Chrome\", \"Safari\", …). Defaults to \"Unknown\" when absent or blank."
          },
          "browser_type": {
            "type": "string",
            "description": "Qualifier for non-ordinary clients the SDK recognises — crawler, inapp, email, fetcher, cli — and empty for a normal browser. Note the server's own bot filtering works off the request User-Agent header, not this field, which is client input like the rest."
          },
          "os": {
            "type": "string",
            "description": "Operating system from the same in-browser detection (\"macOS\", \"Windows\", \"iPadOS\", …). Defaults to \"Unknown\" when absent or blank."
          },
          "user_agent": {
            "type": "string",
            "description": "Raw user agent, usable as an attribution filter dimension. Stored as sent, except that NUL characters are removed, bytes that are not valid UTF-8 become U+FFFD (written as %XX when the value comes from the User-Agent header), and the result is cut to at most 1024 bytes, between characters. It is NOT parsed into device/browser/os — those arrive already resolved in the fields above. Falls back to the request's User-Agent header when the attribute is absent."
          },
          "connection_type": {
            "type": "string"
          },
          "language": {
            "type": "string"
          },
          "timezone": {
            "type": "string"
          }
        }
      },
      "WebTrackPayload": {
        "type": "object",
        "required": [
          "workspace_id",
          "session_id",
          "actions",
          "updated_at"
        ],
        "properties": {
          "workspace_id": {
            "type": "string"
          },
          "session_id": {
            "type": "string",
            "description": "Client-generated UUIDv7. Its embedded timestamp is the single source of truth for the session start and for the partition the rows land in, and must fall within [now-48h, now+24h]. The past bound is the wider one because a session can keep beating for 24h after it started and the SDK offline queue holds beats for another 24h; the future bound is the same 24h as the other timestamps, since the id is minted from the device clock and a visitor whose clock runs fast inherits the whole skew."
          },
          "actions": {
            "type": "array",
            "maxItems": 1000,
            "description": "The FULL cumulative list of session actions (re-sent on every beat).\n\nTwo rules apply here and they are easy to conflate. One ACTION that breaks its own bounds is DROPPED on its own and the rest of the beat is still recorded — never a 400, because the list is cumulative and rejecting the beat would reject every later beat of that session too, permanently. The LIST exceeding maxItems is the opposite: it is a 400 for the whole beat, and because actions[] only ever grows, every later beat fails the same way until the client trims its oldest actions or rotates the session — the same remedy as the 413.",
            "items": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/WebPageviewAction"
                },
                {
                  "$ref": "#/components/schemas/WebGoalAction"
                }
              ]
            }
          },
          "attributes": {
            "$ref": "#/components/schemas/WebSessionAttributes"
          },
          "created_at": {
            "type": "integer",
            "format": "int64",
            "description": "Session creation, epoch ms. Optional, and never read: the session start comes from the UUIDv7 session_id instead, so a stored session start can never disagree with the partition its rows landed in. Accepted for wire compatibility with SDKs that still send it, discarded on arrival — not listed as required, so a generated client is not forced to invent a value the server throws away."
          },
          "updated_at": {
            "type": "integer",
            "format": "int64",
            "description": "Beat timestamp, epoch ms; must be within 24h of server time."
          },
          "sdk_version": {
            "type": "string"
          },
          "tab_id": {
            "type": "integer",
            "format": "int64",
            "description": "The writing tab. Tabs share a session id but keep their own cumulative actions and their own seq, so they are disjoint writers. Absent (or 0) from an older SDK."
          },
          "sent_at": {
            "type": "integer",
            "format": "int64",
            "description": "Stamped at each HTTP attempt; drives clock-skew correction beyond 5s."
          },
          "contact_email": {
            "type": "string",
            "maxLength": 255,
            "description": "Contact address claimed for this session, signed by contact_email_hmac. /track is public and unauthenticated, so no identity field is believed until it verifies against the workspace secret. Send either this pair or identify_token, never both.\n\nA valid signature is necessary but NOT sufficient: the identified path is rate limited, and the address must already be a contact in the workspace. Both extra gates are described under the /track operation. Every rejection along the way — bad signature, throttled, unknown address — costs the identity only: the beat is still recorded, just anonymously, and the response is the same 200 with no error. There is nothing on the wire distinguishing a working integration from a broken one, so verify against a contact that exists and check that the session actually shows up identified."
          },
          "contact_email_hmac": {
            "type": "string",
            "maxLength": 64,
            "description": "HMAC-SHA-256 of a DOMAIN-SEPARATED string, minted on the customer's server (never in the browser, which would hand the workspace secret to every visitor). The exact recipe, which must be followed literally:\n\nsignature = lowercase_hex( HMAC_SHA256( key = workspace secret key, message = \"wa_identify:\" + contact_email ) )\n\nThe message is the ASCII prefix \"wa_identify:\" concatenated with the address — signing bare \"alice@example.com\" instead of \"wa_identify:alice@example.com\" is the failure mode to check first. The result is the 64 lowercase hex characters of the digest, compared as bytes, so uppercase hex or base64 will not match.\n\nThe prefix exists to keep this credential from being interchangeable with the email HMAC that authorizes subscription changes (notification center, unsubscribe, one-click), which is computed over the bare address with the same workspace secret and is printed into every email Notifuse sends. Without the prefix, an unsubscribe HMAC scraped from a forwarded email would silently identify a visitor, and this analytics credential lifted out of page JS by any third-party script would let its holder change that contact's subscriptions.\n\nSigned and verified over the RAW address exactly as it appears in contact_email, before any normalization: sign the same bytes you send. Normalization (trim, lowercase) happens only after the signature checks out, to match the stored contact."
          },
          "identify_token": {
            "type": "string",
            "maxLength": 3174,
            "description": "Opaque encrypted credential carried by an email-click link (the nf_id parameter), and the alternative to the contact_email / contact_email_hmac pair rather than a companion to it. Expired or undecryptable tokens cost the identity only, not the beat. Once decrypted, the address it carries passes through the same two further gates as a signed contact_email (rate limit, then contact-must-exist).\n\nThe length limit is a ceiling on what the server will look at, not a size to aim for: it is derived from the longest address contacts can store, so that no token Notifuse mints can ever exceed it. Send the nf_id value back exactly as it arrived — a longer one is discarded before decryption, which costs the identity silently."
          },
          "dimensions": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Custom dimensions custom_1..custom_10."
          },
          "seq": {
            "type": "integer",
            "format": "int64",
            "minimum": 0,
            "description": "Monotonic per-session beat counter; the server only applies strictly newer beats."
          }
        }
      },
      "WebFilterCondition": {
        "type": "object",
        "required": [
          "field",
          "operator"
        ],
        "properties": {
          "field": {
            "type": "string"
          },
          "operator": {
            "type": "string",
            "enum": [
              "equals",
              "not_equals",
              "contains",
              "not_contains",
              "is_empty",
              "is_not_empty",
              "regex"
            ]
          },
          "value": {
            "type": "string"
          }
        }
      },
      "WebFilterOperation": {
        "type": "object",
        "required": [
          "dimension",
          "action"
        ],
        "properties": {
          "dimension": {
            "type": "string"
          },
          "action": {
            "type": "string",
            "enum": [
              "set_value",
              "unset_value",
              "set_default_value"
            ]
          },
          "value": {
            "type": "string"
          }
        }
      },
      "WebFilter": {
        "type": "object",
        "required": [
          "id",
          "name",
          "priority",
          "conditions",
          "operations",
          "enabled"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "priority": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000
          },
          "order": {
            "type": "integer"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "conditions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebFilterCondition"
            }
          },
          "operations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebFilterOperation"
            }
          },
          "enabled": {
            "type": "boolean"
          },
          "version": {
            "type": "string"
          }
        }
      },
      "WebAnalyticsSettings": {
        "type": "object",
        "nullable": true,
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "allowed_domains": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Origins allowed to send beats (\"example.com\", \"*.example.com\"); empty allows all."
          },
          "bounce_threshold_seconds": {
            "type": "integer",
            "description": "Sessions with less engaged time count as bounces (default 10)."
          },
          "filters": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebFilter"
            }
          },
          "filters_version": {
            "type": "string",
            "readOnly": true
          },
          "custom_dimension_labels": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "identify_from_email_links": {
            "type": "boolean",
            "description": "Adds a signed identity to the links of tracked emails, so a recipient who clicks one is recognised on landing without any code on the customer's site, and their visit is tied to their contact record. Off by default: unlike identify(), which the customer's own server calls with their own secret, this credential is minted by Notifuse for every recipient of every tracked send, so it is theirs to ask for."
          },
          "geo_enabled": {
            "type": "boolean"
          },
          "geo_store_city": {
            "type": "boolean"
          },
          "geo_store_region": {
            "type": "boolean"
          },
          "geo_coordinates_precision": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2
          }
        }
      },
      "WebAnalyticsBackfillRequest": {
        "type": "object",
        "required": [
          "workspace_id"
        ],
        "properties": {
          "workspace_id": {
            "type": "string"
          }
        }
      },
      "WebAnalyticsBackfillResponse": {
        "type": "object",
        "properties": {
          "backfill": {
            "type": "object",
            "nullable": true,
            "properties": {
              "task_id": {
                "type": "string"
              },
              "status": {
                "type": "string",
                "enum": [
                  "pending",
                  "running",
                  "completed",
                  "failed",
                  "paused"
                ]
              },
              "progress": {
                "type": "number"
              },
              "state": {
                "type": "object",
                "properties": {
                  "filters_version": {
                    "type": "string"
                  },
                  "partition_index": {
                    "type": "integer"
                  },
                  "rows_updated": {
                    "type": "integer",
                    "format": "int64"
                  }
                }
              },
              "error_message": {
                "type": "string"
              }
            }
          }
        }
      },
      "Annotation": {
        "type": "object",
        "required": [
          "id",
          "annotated_at",
          "timezone",
          "title",
          "color",
          "source",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Server-generated identifier (a UUID with its dashes removed).",
            "example": "3f2504e04f8911d39a0c0305e82c3301"
          },
          "annotated_at": {
            "type": "string",
            "format": "date-time",
            "description": "The moment the annotation marks, as a real instant.",
            "example": "2026-08-15T09:00:00Z"
          },
          "timezone": {
            "type": "string",
            "description": "IANA timezone the moment was entered in. This is display intent only — annotated_at already fixes the instant, and filtering never uses this field. It is what lets \"9am in Tokyo\" render back as 9am instead of the reader's local equivalent.",
            "example": "Asia/Tokyo"
          },
          "title": {
            "type": "string",
            "maxLength": 100,
            "description": "Counted in characters, not bytes.",
            "example": "Pricing page redesign"
          },
          "description": {
            "type": "string",
            "maxLength": 500,
            "description": "Optional longer note. Counted in characters, not bytes.",
            "example": "Rolled out to all visitors after the A/B test."
          },
          "color": {
            "type": "string",
            "pattern": "^#[0-9A-Fa-f]{6}$",
            "description": "Six-digit hex colour used for the marker on the charts.",
            "example": "#3b82f6"
          },
          "source": {
            "type": "string",
            "enum": [
              "manual",
              "broadcast"
            ],
            "description": "Who wrote the row. `manual` is anything typed by an operator or posted to this API; `broadcast` rows are written automatically when a broadcast starts sending. There is deliberately no API source — see the note on annotations.create.",
            "example": "manual"
          },
          "source_id": {
            "type": "string",
            "description": "The entity that caused an automatic annotation (a broadcast id today). Always absent on manual rows, and never settable through the API. An annotation outlives the entity it points at: deleting a broadcast leaves its annotation, because the send did happen.",
            "example": "bcast_1234567890"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ListAnnotationsResponse": {
        "type": "object",
        "properties": {
          "annotations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Annotation"
            }
          }
        }
      },
      "AnnotationResponse": {
        "type": "object",
        "properties": {
          "annotation": {
            "$ref": "#/components/schemas/Annotation"
          }
        }
      },
      "CreateAnnotationRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "annotated_at",
          "title"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "example": "ws_1234567890"
          },
          "annotated_at": {
            "type": "string",
            "format": "date-time",
            "description": "The moment to mark, as an RFC3339 instant.",
            "example": "2026-08-15T09:00:00Z"
          },
          "timezone": {
            "type": "string",
            "description": "IANA timezone the moment was entered in, kept for display. Defaults to the workspace timezone, then to UTC.",
            "example": "Asia/Tokyo"
          },
          "title": {
            "type": "string",
            "maxLength": 100,
            "example": "Pricing page redesign"
          },
          "description": {
            "type": "string",
            "maxLength": 500,
            "example": "Rolled out to all visitors after the A/B test."
          },
          "color": {
            "type": "string",
            "pattern": "^#[0-9A-Fa-f]{6}$",
            "default": "#3b82f6",
            "example": "#3b82f6"
          },
          "source": {
            "type": "string",
            "enum": [
              "manual"
            ],
            "description": "Only `manual` is accepted. Sending `broadcast` is rejected rather than quietly downgraded: it would be claiming the slot of an automatic row.",
            "default": "manual"
          }
        }
      },
      "UpdateAnnotationRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "id",
          "annotated_at",
          "title"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "example": "ws_1234567890"
          },
          "id": {
            "type": "string",
            "example": "3f2504e04f8911d39a0c0305e82c3301"
          },
          "annotated_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-08-15T09:00:00Z"
          },
          "timezone": {
            "type": "string",
            "description": "Falls back to the annotation's stored timezone when omitted.",
            "example": "Asia/Tokyo"
          },
          "title": {
            "type": "string",
            "maxLength": 100,
            "example": "Pricing page redesign"
          },
          "description": {
            "type": "string",
            "maxLength": 500
          },
          "color": {
            "type": "string",
            "pattern": "^#[0-9A-Fa-f]{6}$",
            "description": "Falls back to the annotation's stored colour when omitted.",
            "example": "#3b82f6"
          }
        }
      },
      "DeleteAnnotationRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "id"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "example": "ws_1234567890"
          },
          "id": {
            "type": "string",
            "example": "3f2504e04f8911d39a0c0305e82c3301"
          }
        }
      },
      "DeleteAnnotationResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          }
        }
      },
      "RetryFailedBroadcastRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "id"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The ID of the workspace",
            "example": "ws_1234567890"
          },
          "id": {
            "type": "string",
            "description": "ID of the broadcast whose failed recipients should be retried",
            "example": "broadcast_12345"
          }
        }
      },
      "TemplateTranslation": {
        "type": "object",
        "description": "Content for one language. Carries the field matching the template's channel: email for an email template, web for a web template.",
        "properties": {
          "email": {
            "$ref": "#/components/schemas/EmailTemplate"
          },
          "web": {
            "$ref": "#/components/schemas/WebTemplate"
          }
        }
      }
    }
  }
}