Knock Message types API

openapi: 3.0.3
info:
  title: Knock Audiences Accounts Message types API
  version: '1.0'
  description: Manage static Audiences and their members. Audiences power lifecycle messaging — when a user joins an audience, configured workflows fire automatically.
  contact:
    name: Knock
    url: https://knock.app
  license:
    name: Proprietary
servers:
- url: https://api.knock.app
  variables: {}
security:
- BearerAuth: []
tags:
- description: A message type allows you to specify an in-app schema that defines the fields available for your in-app notifications.
  name: Message types
paths:
  /v1/message_types/{message_type_key}/validate:
    put:
      callbacks: {}
      description: 'Validates a message type payload without persisting it.


        Note: this endpoint only operates on message types in the `development` environment.

        '
      operationId: validateMessageType
      parameters:
      - description: The key of the message type to validate.
        in: path
        name: message_type_key
        required: true
        schema:
          example: email
          type: string
          x-struct: null
          x-validate: null
      - 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:
              description: Wraps the MessageTypeRequest request under the message_type key.
              example:
                message_type:
                  description: This is a message type
                  name: My Message Type
                  preview: <div>Hello, world!</div>
                  variants:
                  - fields:
                    - key: text_field
                      label: My text field
                      settings:
                        description: A description of the text field
                        max_length: 100
                        min_length: 10
                        required: true
                      type: text
                    key: default
                    name: Default
              properties:
                message_type:
                  $ref: '#/components/schemas/MessageTypeRequest'
              required:
              - message_type
              title: WrappedMessageTypeRequestRequest
              type: object
              x-struct: null
              x-validate: null
        description: Params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: Wraps the MessageType response under the `message_type` key.
                example:
                  message_type:
                    archived_at: null
                    created_at: '2021-01-01T00:00:00Z'
                    deleted_at: null
                    description: Email message type
                    environment: development
                    icon_name: email
                    key: email
                    name: Email
                    owner: user
                    preview: <div>Hello, world!</div>
                    semver: 1.0.0
                    sha: '1234567890'
                    updated_at: '2021-01-01T00:00:00Z'
                    valid: true
                    variants:
                    - fields:
                      - key: text_field
                        label: My text field
                        settings:
                          description: A description of the text field
                          max_length: 100
                          min_length: 10
                          required: true
                        type: text
                      key: default
                      name: Default
                properties:
                  message_type:
                    $ref: '#/components/schemas/MessageType'
                required:
                - message_type
                title: WrappedMessageTypeResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
      summary: Validate message type
      tags:
      - Message types
  /v1/message_types/{message_type_key}:
    get:
      callbacks: {}
      description: Retrieve a message type by its key, in a given environment.
      operationId: getMessageType
      parameters:
      - description: The key of the message type to retrieve.
        in: path
        name: message_type_key
        required: true
        schema:
          example: email
          type: string
          x-struct: null
          x-validate: null
      - 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
      - description: Whether to annotate the resource. Only used in the Knock CLI.
        in: query
        name: annotate
        required: false
        schema:
          type: boolean
          x-struct: null
          x-validate: null
      - description: Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.
        in: query
        name: hide_uncommitted_changes
        required: false
        schema:
          type: boolean
          x-struct: null
          x-validate: null
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageType'
          description: OK
      summary: Get message type
      tags:
      - Message types
    put:
      callbacks: {}
      description: 'Updates a message type, or creates a new one if it does not yet exist.


        Note: this endpoint only operates in the `development` environment.

        '
      operationId: upsertMessageType
      parameters:
      - description: The key of the message type to upsert.
        in: path
        name: message_type_key
        required: true
        schema:
          example: email
          type: string
          x-struct: null
          x-validate: null
      - 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
      - description: Whether to annotate the resource. Only used in the Knock CLI.
        in: query
        name: annotate
        required: false
        schema:
          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
        required: false
        schema:
          type: boolean
          x-struct: null
          x-validate: null
      - description: The message to commit the resource with, only used if `commit` is `true`.
        in: query
        name: commit_message
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            schema:
              description: Wraps the MessageTypeRequest request under the message_type key.
              example:
                message_type:
                  description: This is a message type
                  name: My Message Type
                  preview: <div>Hello, world!</div>
                  variants:
                  - fields:
                    - key: text_field
                      label: My text field
                      settings:
                        description: A description of the text field
                        max_length: 100
                        min_length: 10
                        required: true
                      type: text
                    key: default
                    name: Default
              properties:
                message_type:
                  $ref: '#/components/schemas/MessageTypeRequest'
              required:
              - message_type
              title: WrappedMessageTypeRequestRequest
              type: object
              x-struct: null
              x-validate: null
        description: Params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: Wraps the MessageType response under the `message_type` key.
                example:
                  message_type:
                    archived_at: null
                    created_at: '2021-01-01T00:00:00Z'
                    deleted_at: null
                    description: Email message type
                    environment: development
                    icon_name: email
                    key: email
                    name: Email
                    owner: user
                    preview: <div>Hello, world!</div>
                    semver: 1.0.0
                    sha: '1234567890'
                    updated_at: '2021-01-01T00:00:00Z'
                    valid: true
                    variants:
                    - fields:
                      - key: text_field
                        label: My text field
                        settings:
                          description: A description of the text field
                          max_length: 100
                          min_length: 10
                          required: true
                        type: text
                      key: default
                      name: Default
                properties:
                  message_type:
                    $ref: '#/components/schemas/MessageType'
                required:
                - message_type
                title: WrappedMessageTypeResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
      summary: Upsert message type
      tags:
      - Message types
  /v1/message_types:
    get:
      callbacks: {}
      description: Returns a paginated list of message types available in a given environment.
      operationId: listMessageTypes
      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
      - description: Whether to annotate the resource. Only used in the Knock CLI.
        in: query
        name: annotate
        required: false
        schema:
          type: boolean
          x-struct: null
          x-validate: null
      - description: Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.
        in: query
        name: hide_uncommitted_changes
        required: false
        schema:
          type: boolean
          x-struct: null
          x-validate: null
      - description: The cursor to fetch entries after.
        in: query
        name: after
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: The cursor to fetch entries before.
        in: query
        name: before
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: The number of entries to fetch per-page.
        in: query
        name: limit
        required: false
        schema:
          type: integer
          x-struct: null
          x-validate: null
      responses:
        '200':
          content:
            application/json:
              schema:
                description: A paginated list of MessageType. Contains a list of entries and page information.
                example:
                  entries:
                  - archived_at: null
                    created_at: '2021-01-01T00:00:00Z'
                    deleted_at: null
                    description: Email message type
                    environment: development
                    icon_name: email
                    key: email
                    name: Email
                    owner: user
                    preview: <div>Hello, world!</div>
                    semver: 1.0.0
                    sha: '1234567890'
                    updated_at: '2021-01-01T00:00:00Z'
                    valid: true
                    variants:
                    - fields:
                      - key: text_field
                        label: My text field
                        settings:
                          description: A description of the text field
                          max_length: 100
                          min_length: 10
                          required: true
                        type: text
                      key: default
                      name: Default
                  page_info:
                    after: null
                    before: null
                    page_size: 25
                properties:
                  entries:
                    description: A list of entries.
                    items:
                      $ref: '#/components/schemas/MessageType'
                    nullable: false
                    type: array
                    x-struct: null
                    x-validate: null
                  page_info:
                    $ref: '#/components/schemas/PageInfo'
                required:
                - entries
                - page_info
                title: PaginatedMessageTypeResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
      summary: List message types
      tags:
      - Message types
components:
  schemas:
    MessageTypeMarkdownField:
      description: A markdown field used in a message type.
      example:
        key: markdown_field
        label: Markdown Field
        settings:
          default: '# Heading


            This is **bold** and this is *italic*.'
          description: A description of the markdown field
          placeholder: A placeholder for the markdown field
          required: true
        type: markdown
      properties:
        key:
          description: The unique key of the field.
          example: key
          type: string
          x-struct: null
          x-validate: null
        label:
          description: The label of the field.
          example: Label
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        settings:
          description: Settings for the markdown field.
          properties:
            default:
              description: The default value of the markdown field.
              example: '# Heading


                This is **bold** and this is *italic*.'
              type: string
              x-struct: null
              x-validate: null
            description:
              example: A description of the field, used in the UI as a hint text.
              nullable: true
              type: string
              x-struct: null
              x-validate: null
            placeholder:
              example: A placeholder for the field.
              nullable: true
              type: string
              x-struct: null
              x-validate: null
            required:
              description: Whether the field is required.
              example: true
              type: boolean
              x-struct: null
              x-validate: null
          type: object
          x-struct: null
          x-validate: null
        type:
          description: The type of the field.
          enum:
          - markdown
          example: markdown
          type: string
          x-struct: null
          x-validate: null
      required:
      - type
      - key
      - label
      title: MessageTypeMarkdownField
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.MessageTypes.MarkdownField
      x-validate: null
    MessageTypeImageField:
      description: An image field used in a message type.
      example:
        action:
          key: action
          label: Image Action
          settings:
            description: A link to open when the paywall image is clicked
            placeholder: A placeholder for the image action
            required: true
          type: text
        alt:
          key: alt
          label: Alt Text
          settings:
            description: A description of the paywall image
            placeholder: A placeholder for the alt text
            required: true
          type: text
        key: image_field
        label: Paywall Image
        settings:
          description: An image to display in the paywall
          required: true
        type: image
        url:
          key: url
          label: Image URL
          settings:
            description: The URL of the paywall image
            placeholder: A placeholder for the image URL
            required: true
          type: url
      properties:
        action:
          $ref: '#/components/schemas/MessageTypeTextField'
        alt:
          $ref: '#/components/schemas/MessageTypeTextField'
        key:
          description: The unique key of the field.
          example: key
          type: string
          x-struct: null
          x-validate: null
        label:
          description: The label of the field.
          example: Label
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        settings:
          description: Settings for the image field.
          properties:
            description:
              example: A description of the field, used in the UI as a hint text.
              nullable: true
              type: string
              x-struct: null
              x-validate: null
            placeholder:
              example: A placeholder for the field.
              nullable: true
              type: string
              x-struct: null
              x-validate: null
            required:
              description: Whether the field is required.
              example: true
              type: boolean
              x-struct: null
              x-validate: null
          type: object
          x-struct: null
          x-validate: null
        type:
          description: The type of the field.
          enum:
          - image
          example: image
          type: string
          x-struct: null
          x-validate: null
        url:
          $ref: '#/components/schemas/MessageTypeUrlField'
      required:
      - type
      - key
      - label
      - url
      - action
      - alt
      title: MessageTypeImageField
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.MessageTypes.ImageField
      x-validate: null
    MessageType:
      description: A message type is a schema for a message that maps to a UI component or element within your application.
      example:
        archived_at: null
        created_at: '2021-01-01T00:00:00Z'
        deleted_at: null
        description: Email message type
        environment: development
        icon_name: email
        key: email
        name: Email
        owner: user
        preview: <div>Hello, world!</div>
        semver: 1.0.0
        sha: '1234567890'
        updated_at: '2021-01-01T00:00:00Z'
        valid: true
        variants:
        - fields:
          - key: text_field
            label: My text field
            settings:
              description: A description of the text field
              max_length: 100
              min_length: 10
              required: true
            type: text
          key: default
          name: Default
      properties:
        archived_at:
          description: The timestamp of when the message type was deleted.
          format: date-time
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        created_at:
          description: The timestamp of when the message type was created.
          format: date-time
          type: string
          x-struct: null
          x-validate: null
        deleted_at:
          description: The timestamp of when the message type was deleted.
          format: date-time
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        description:
          description: An arbitrary string attached to a message type object. Useful for adding notes about the message type for internal purposes. Maximum of 280 characters allowed.
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        environment:
          description: The environment of the message type.
          type: string
          x-struct: null
          x-validate: null
        icon_name:
          description: The icon name of the message type.
          type: string
          x-struct: null
          x-validate: null
        key:
          description: The unique key string for the message type object. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.
          type: string
          x-struct: null
          x-validate: null
        name:
          description: A name for the message type. Must be at maximum 255 characters in length.
          type: string
          x-struct: null
          x-validate: null
        owner:
          description: The owner of the message type.
          enum:
          - system
          - user
          type: string
          x-struct: null
          x-validate: null
        preview:
          description: An HTML/liquid template for the message type preview.
          type: string
          x-struct: null
          x-validate: null
        semver:
          description: The semantic version of the message type.
          example: 1.0.0
          type: string
          x-struct: null
          x-validate: null
        sha:
          description: The SHA hash of the message type.
          type: string
          x-struct: null
          x-validate: null
        updated_at:
          description: The timestamp of when the message type was last updated.
          format: date-time
          type: string
          x-struct: null
          x-validate: null
        valid:
          description: Whether the message type is valid.
          type: boolean
          x-struct: null
          x-validate: null
        variants:
          description: The variants of the message type.
          items:
            $ref: '#/components/schemas/MessageTypeVariant'
          type: array
          x-struct: null
          x-validate: null
      required:
      - key
      - valid
      - owner
      - environment
      - created_at
      - name
      - variants
      - preview
      - semver
      - updated_at
      - sha
      title: MessageType
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.MessageType
      x-validate: null
    PageInfo:
      description: The information about a paginated result.
      example:
        after: null
        before: null
        page_size: 25
      properties:
        after:
          description: The cursor to fetch entries after. Will only be present if there are more entries to fetch.
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        before:
          description: The cursor to fetch entries before. Will only be present if there are more entries to fetch before the current page.
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        page_size:
          description: The number of entries to fetch per-page.
          type: integer
          x-struct: null
          x-validate: null
      required:
      - page_size
      title: PageInfo
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.PageInfo
      x-validate: null
    MessageTypeMultiSelectField:
      description: A multi-select field used in a message type.
      example:
        key: multi_select_field
        label: Multi-Select Field
        settings:
          default:
          - option1
          - option3
          description: A description of the multi-select field
          options:
          - label: Option 1
            value: option1
          - label: Option 2
            value: option2
          - label: Option 3
            value: option3
          required: true
        type: multi_select
      properties:
        key:
          description: The unique key of the field.
          example: key
          type: string
          x-struct: null
          x-validate: null
        label:
          description: The label of the field.
          example: Label
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        settings:
          description: Settings for the multi_select field.
          properties:
            default:
              description: The default values for the multi-select field.
              example:
              - option1
              - option3
              items:
                type: string
                x-struct: null
                x-validate: null
              nullable: true
              type: array
              x-struct: null
              x-validate: null
            description:
              example: A description of the field, used in the UI as a hint text.
              nullable: true
              type: string
              x-struct: null
              x-validate: null
            options:
              description: The available options for the multi-select field.
              items:
                properties:
                  label:
                    description: The display label for the option.
                    example: Option 1
                    type: string
                    x-struct: null
                    x-validate: null
                  value:
                    description: The value for the option.
                    example: option1
                    type: string
                    x-struct: null
                    x-validate: null
                required:
                - value
                type: object
                x-struct: null
                x-validate: null
              type: array
              x-struct: null
              x-validate: null
            placeholder:
              example: A placeholder for the field.
              nullable: true
              type: string
              x-struct: null
              x-validate: null
            required:
              description: Whether the field is required.
              example: true
              type: boolean
              x-struct: null
              x-validate: null
          type: object
          x-struct: null
          x-validate: null
        type:
          description: The type of the field.
          enum:
          - multi_select
          example: multi_select
          type: string
          x-struct: null
          x-validate: null
      required:
      - type
      - key
      - label
      - settings
      title: MessageTypeMultiSelectField
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.MessageTypes.MultiSelectField
      x-validate: null
    MessageTypeRequest:
      description: A request to create a message type.
      example:
        description: This is a message type
        name: My Message Type
        preview: <div>Hello, world!</div>
        variants:
        - fields:
          - key: text_field
            label: My text field
            settings:
              description: A description of the text field
              max_length: 100
              min_length: 10
              required: true
            type: text
          key: default
          name: Default
      properties:
        description:
          description: An arbitrary string attached to a message type object. Useful for adding notes about the message type for internal purposes. Maximum of 280 characters allowed.
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        icon_name:
          description: The icon name of the message type.
          type: string
          x-struct: null
          x-validate: null
        name:
          description: A name for the message type. Must be at maximum 255 characters in length.
          type: string
          x-struct: null
          x-validate: null
        preview:
          description: An HTML/liquid template for the message type preview.
          type: string
          x-struct: null
          x-validate: null
        semver:
          description: The semantic version of the message type.
          example: 1.0.0
          type: string
          x-struct: null
          x-validate: null
        variants:
          description: The variants of the message type.
          items:
            $ref: '#/components/schemas/MessageTypeVariant'
          type: array
          x-struct: null
          x-validate: null
      required:
      - name
      - description
      - preview
      title: MessageTypeRequest
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.MessageTypeRequest
      x-validate: null
    MessageTypeVariant:
      description: A variant of a message type.
      example:
        fields:
        - key: text_field
          label: My text field
          settings:
            description: A description of the text field
            max_length: 100
            min_length: 10
            required: true
          type: text
        key: default
        name: Default
      properties:
        fields:
          description: The field types available for the variant.
          items:
            anyOf:
            - $ref: '#/components/schemas/MessageTypeBooleanField'
            - $ref: '#/components/schemas/MessageTypeButtonField'
            - $ref: '#/components/schemas/MessageTypeImageField'
            - $ref: '#/components/schemas/MessageTypeJsonField'
            - $ref: '#/components/schemas/MessageTypeMarkdownField'
            - $ref: '#/components/schemas/MessageTypeMultiSelectField'
            - $ref: '#/components/schemas/MessageTypeSelectField'
            - $ref: '#/components/schemas/MessageTypeTextField'
            - $ref: '#/components/schemas/MessageTypeTextareaField'
            - $ref: '#/components/schemas/MessageTypeUrlField'
            type: object
            x-struct: null
            x-validate: null
          type: array
          x-struct: null
          x-validate: null
        key:
          description: The unique key string for the variant. Must be at minimum 3 characters and at maxim

# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/knock-app/refs/heads/main/openapi/knock-app-message-types-api-openapi.yml