Skip to content

chore: update control openapi spec #1349

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cjbell merged 3 commits into from
Mar 18, 2026
Merged

chore: update control openapi spec #1349

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a89a59f
chore: update control openapi spec to v0.1.1273
knock-eng-bot Mar 12, 2026
3934832
chore: update control openapi spec to v0.1.1275
knock-eng-bot Mar 12, 2026
b30a36f
chore: update control openapi spec to v0.1.1286
knock-eng-bot Mar 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
297 changes: 294 additions & 3 deletions data/specs/mapi/openapi.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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: <p>Welcome to Acme!</p>
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:
Expand Down Expand Up @@ -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 <mjml> tags.
nullable: true
type: boolean
x-struct: null
x-validate: null
name:
description: The friendly name of this email layout.
nullable: false
Expand Down Expand Up @@ -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: <p>Hello, world!</p>
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:
Expand Down Expand Up @@ -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 <mjml> tags.
type: boolean
x-struct: null
x-validate: null
key:
description: The unique key for this email layout.
type: string
Expand Down Expand Up @@ -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: <p>Welcome!</p>
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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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: {}
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
Loading