diff --git a/data/specs/mapi/openapi.yml b/data/specs/mapi/openapi.yml index b7768ea14..b12417ffa 100644 --- a/data/specs/mapi/openapi.yml +++ b/data/specs/mapi/openapi.yml @@ -1,6 +1,88 @@ components: responses: {} schemas: + PreviewTemplateResponse: + description: A response to a template preview request. + example: + content_type: email + result: success + template: + html_body:

Welcome to Acme!

+ subject: Hello John + text_body: Welcome to Acme! + properties: + content_type: + description: The content type of the preview. + enum: + - email + - in_app_feed + - push + - chat + - sms + type: string + x-struct: null + x-validate: null + errors: + description: A list of errors encountered during rendering. Present when result is "error". + items: + description: A rendering error with optional location information. + example: + field: html_content + line: 1 + message: 'Reason: expected end of string, line: 1' + properties: + field: + description: The template field that caused the error, if available. + nullable: true + type: string + x-struct: null + x-validate: null + line: + description: The line number where the error occurred, if available. + nullable: true + type: integer + x-struct: null + x-validate: null + message: + description: A human-readable description of the error. + type: string + x-struct: null + x-validate: null + required: + - message + type: object + x-struct: null + x-validate: null + nullable: true + type: array + x-struct: null + x-validate: null + result: + description: The result of the preview. + enum: + - success + - error + type: string + x-struct: null + x-validate: null + template: + anyOf: + - $ref: '#/components/schemas/EmailTemplate' + - $ref: '#/components/schemas/InAppFeedTemplate' + - $ref: '#/components/schemas/PushTemplate' + - $ref: '#/components/schemas/ChatTemplate' + - $ref: '#/components/schemas/SmsTemplate' + description: The rendered template, ready to be previewed. + type: object + x-struct: null + x-validate: null + required: + - result + - content_type + title: PreviewTemplateResponse + type: object + x-struct: Elixir.ControlWeb.V1.Specs.PreviewTemplateResponse + x-validate: null RequestTemplateQueryParamsArray: description: A list of key-value pairs for the request query params. Each object should contain key and value fields with string values. example: @@ -1970,11 +2052,17 @@ components: x-struct: null x-validate: null html_layout: - description: The complete HTML content of the email layout. + description: The complete HTML or MJML content of the email layout. nullable: false type: string x-struct: null x-validate: null + is_mjml: + description: Whether this layout uses MJML format. When true, html_layout must contain tags. + nullable: true + type: boolean + x-struct: null + x-validate: null name: description: The friendly name of this email layout. nullable: false @@ -3108,12 +3196,18 @@ components: text_body: 'Hello, {{ recipient.name }}! Welcome to {{ vars.app_name }} Get started here: {{ data.sign_in_url }}.' properties: html_body: - description: An HTML template for the email body. **Required** if `visual_blocks` is not provided. Only one of `html_body` or `visual_blocks` should be set. Supports Liquid templating with variables like `{{ recipient.name }}`, `{{ actor.name }}`, `{{ vars.app_name }}`, `{{ data.custom_field }}`, and `{{ tenant.name }}`. See the [template variables reference](https://docs.knock.app/designing-workflows/template-editor/variables) for available variables. + description: An HTML or MJML template for the email body. **Required** if `visual_blocks` is not provided. Only one of `html_body` or `visual_blocks` should be set. When `is_mjml` is true, this must contain MJML components. Supports Liquid templating with variables like `{{ recipient.name }}`, `{{ actor.name }}`, `{{ vars.app_name }}`, `{{ data.custom_field }}`, and `{{ tenant.name }}`. See the [template variables reference](https://docs.knock.app/designing-workflows/template-editor/variables) for available variables. example:

Hello, world!

nullable: true type: string x-struct: null x-validate: null + is_mjml: + description: Whether this template uses MJML format. When true, the template content will be compiled from MJML to HTML. Only valid when the selected layout is also MJML or when no layout is selected. + nullable: true + type: boolean + x-struct: null + x-validate: null settings: description: The [settings](https://docs.knock.app/integrations/email/settings) for the email template. Must be supplied with at least `layout_key`. example: @@ -5826,10 +5920,15 @@ components: x-struct: null x-validate: null html_layout: - description: The complete HTML content of the email layout. + description: The complete HTML or MJML content of the email layout. type: string x-struct: null x-validate: null + is_mjml: + description: Whether this layout uses MJML format. When true, html_layout must contain tags. + type: boolean + x-struct: null + x-validate: null key: description: The unique key for this email layout. type: string @@ -7715,6 +7814,97 @@ components: type: object x-struct: Elixir.ControlWeb.V1.Specs.EmailChannelSettings x-validate: null + PreviewTemplateRequest: + description: A request to preview a template, without requiring a template to be persisted within Knock. + example: + channel_type: email + data: + order_id: 123 + recipient: user_123 + template: + html_body:

Welcome!

+ settings: + layout_key: default + subject: Hello {{ recipient.name }} + properties: + actor: + anyOf: + - $ref: '#/components/schemas/RecipientReference' + - nullable: true + x-struct: null + x-validate: null + description: The actor to reference in the preview. + x-struct: null + x-validate: null + channel_type: + description: The channel type of the template to preview. + enum: + - email + - sms + - push + - chat + - in_app_feed + type: string + x-struct: null + x-validate: null + data: + additionalProperties: true + description: The data to pass to the template for rendering. + type: object + x-struct: null + x-validate: null + layout: + description: Email layout configuration. Only applicable for email channel type. Falls back to environment default if not provided. + nullable: true + properties: + html_content: + description: Inline HTML content for the layout. Must include `{{ content }}` placeholder. + nullable: true + type: string + x-struct: null + x-validate: null + key: + description: The key of an existing email layout to use. + nullable: true + type: string + x-struct: null + x-validate: null + text_content: + description: Inline text content for the layout. + nullable: true + type: string + x-struct: null + x-validate: null + type: object + x-struct: null + x-validate: null + recipient: + $ref: '#/components/schemas/RecipientReference' + template: + anyOf: + - $ref: '#/components/schemas/EmailTemplate' + - $ref: '#/components/schemas/SmsTemplate' + - $ref: '#/components/schemas/PushTemplate' + - $ref: '#/components/schemas/ChatTemplate' + - $ref: '#/components/schemas/InAppFeedTemplate' + description: The template content to preview. Structure depends on channel_type. + type: object + x-struct: null + x-validate: null + tenant: + description: The tenant to associate with the preview. Must not contain whitespace. + nullable: true + type: string + x-struct: null + x-validate: null + required: + - channel_type + - template + - recipient + title: PreviewTemplateRequest + type: object + x-struct: Elixir.ControlWeb.V1.Specs.PreviewTemplateRequest + x-validate: null SendWindow: description: A send window time for a notification. Describes a single day. example: @@ -10206,6 +10396,14 @@ paths: type: boolean x-struct: null x-validate: null + - description: When set to true, forces the upsert to override existing content regardless of environment restrictions. This bypasses the development-only environment check and origin environment checks. + in: query + name: force + required: false + schema: + type: boolean + x-struct: null + x-validate: null - description: Whether to commit the resource at the same time as modifying it. in: query name: commit @@ -11270,6 +11468,51 @@ paths: } fmt.Printf("%+v\n", response.ContentType) } + /v1/templates/preview: + post: + callbacks: {} + description: | + Renders a template preview, without requiring a template to be persisted within Knock. + This is useful for previewing templates in isolation, without the need to use a workflow. + + For email templates, you can optionally specify a layout by key or provide inline layout content. + operationId: previewTemplate + parameters: + - description: The environment slug. + in: query + name: environment + required: true + schema: + example: development + type: string + x-struct: null + x-validate: null + - description: The slug of a branch to use. This option can only be used when `environment` is `"development"`. + in: query + name: branch + required: false + schema: + example: feature-branch + type: string + x-struct: null + x-validate: null + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PreviewTemplateRequest' + description: Params + required: false + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/PreviewTemplateResponse' + description: OK + summary: Preview a template + tags: + - Templates /v1/guides/{guide_key}/activate: put: callbacks: {} @@ -11732,6 +11975,14 @@ paths: type: boolean x-struct: null x-validate: null + - description: When set to true, forces the upsert to override existing content regardless of environment restrictions. This bypasses the development-only environment check and origin environment checks. + in: query + name: force + required: false + schema: + type: boolean + x-struct: null + x-validate: null - description: Whether to commit the resource at the same time as modifying it. in: query name: commit @@ -12305,6 +12556,14 @@ paths: type: boolean x-struct: null x-validate: null + - description: When set to true, forces the upsert to override existing content regardless of environment restrictions. This bypasses the development-only environment check and origin environment checks. + in: query + name: force + required: false + schema: + type: boolean + x-struct: null + x-validate: null - description: Whether to commit the resource at the same time as modifying it. in: query name: commit @@ -13386,6 +13645,14 @@ paths: type: boolean x-struct: null x-validate: null + - description: When set to true, forces the upsert to override existing content regardless of environment restrictions. This bypasses the development-only environment check and origin environment checks. + in: query + name: force + required: false + schema: + type: boolean + x-struct: null + x-validate: null - description: Whether to commit the resource at the same time as modifying it. in: query name: commit @@ -14643,6 +14910,14 @@ paths: type: boolean x-struct: null x-validate: null + - description: When set to true, forces the upsert to override existing content regardless of environment restrictions. This bypasses the development-only environment check and origin environment checks. + in: query + name: force + required: false + schema: + type: boolean + x-struct: null + x-validate: null - description: Whether to commit the resource at the same time as modifying it. in: query name: commit @@ -15758,6 +16033,14 @@ paths: type: boolean x-struct: null x-validate: null + - description: When set to true, forces the upsert to override existing content regardless of environment restrictions. This bypasses the development-only environment check and origin environment checks. + in: query + name: force + required: false + schema: + type: boolean + x-struct: null + x-validate: null - description: Whether to commit the resource at the same time as modifying it. in: query name: commit @@ -16071,6 +16354,14 @@ paths: type: boolean x-struct: null x-validate: null + - description: When set to true, forces the upsert to override existing content regardless of environment restrictions. This bypasses the development-only environment check and origin environment checks. + in: query + name: force + required: false + schema: + type: boolean + x-struct: null + x-validate: null - description: Whether to commit the resource at the same time as modifying it. in: query name: commit