Knock
Knock Partials API

Partials allow you to reuse content across templates.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.0.3
info:
  title: Knock Audiences Accounts Partials 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: Partials allow you to reuse content across templates.
  name: Partials
paths:
  /v1/partials:
    get:
      callbacks: {}
      description: List all partials for a given environment.
      operationId: listPartials
      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 Partial. Contains a list of entries and page information.
                example:
                  entries:
                  - content: <p>Hello, world!</p>
                    description: This is a test partial
                    environment: development
                    icon_name: icon-name
                    input_schema:
                    - 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
                    inserted_at: '2021-01-01T00:00:00Z'
                    key: my-partial
                    name: My Partial
                    type: html
                    updated_at: '2021-01-01T00:00:00Z'
                    valid: true
                    visual_block_enabled: true
                  page_info:
                    after: null
                    before: null
                    page_size: 25
                properties:
                  entries:
                    description: A list of entries.
                    items:
                      $ref: '#/components/schemas/Partial'
                    nullable: false
                    type: array
                    x-struct: null
                    x-validate: null
                  page_info:
                    $ref: '#/components/schemas/PageInfo'
                required:
                - entries
                - page_info
                title: PaginatedPartialResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
      summary: List partials
      tags:
      - Partials
  /v1/partials/{partial_key}:
    get:
      callbacks: {}
      description: Get a partial by its key.
      operationId: getPartial
      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: The key of the partial to retrieve.
        in: path
        name: partial_key
        required: true
        schema:
          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/Partial'
          description: OK
      summary: Get a partial
      tags:
      - Partials
    put:
      callbacks: {}
      description: 'Updates a partial of a given key, or creates a new one if it does not yet exist.


        Note: this endpoint only operates on partials in the “development” environment.

        '
      operationId: upsertPartial
      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: The key of the partial to upsert.
        in: path
        name: partial_key
        required: true
        schema:
          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 PartialRequest request under the partial key.
              example:
                partial:
                  content: <p>Hello, world!</p>
                  description: This is a test partial
                  input_schema:
                  - 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
                  name: My Partial
                  type: html
                  visual_block_enabled: true
              properties:
                partial:
                  $ref: '#/components/schemas/PartialRequest'
              required:
              - partial
              title: WrappedPartialRequestRequest
              type: object
              x-struct: null
              x-validate: null
        description: Params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: Wraps the Partial response under the `partial` key.
                example:
                  partial:
                    content: <p>Hello, world!</p>
                    description: This is a test partial
                    environment: development
                    icon_name: icon-name
                    input_schema:
                    - 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
                    inserted_at: '2021-01-01T00:00:00Z'
                    key: my-partial
                    name: My Partial
                    type: html
                    updated_at: '2021-01-01T00:00:00Z'
                    valid: true
                    visual_block_enabled: true
                properties:
                  partial:
                    $ref: '#/components/schemas/Partial'
                required:
                - partial
                title: WrappedPartialResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
      summary: Upsert a partial
      tags:
      - Partials
  /v1/partials/{partial_key}/validate:
    put:
      callbacks: {}
      description: 'Validates a partial payload without persisting it.


        Note: this endpoint only operates on partials in the “development” environment.

        '
      operationId: validatePartial
      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: The key of the partial to validate.
        in: path
        name: partial_key
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            schema:
              description: Wraps the PartialRequest request under the partial key.
              example:
                partial:
                  content: <p>Hello, world!</p>
                  description: This is a test partial
                  input_schema:
                  - 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
                  name: My Partial
                  type: html
                  visual_block_enabled: true
              properties:
                partial:
                  $ref: '#/components/schemas/PartialRequest'
              required:
              - partial
              title: WrappedPartialRequestRequest
              type: object
              x-struct: null
              x-validate: null
        description: Params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: Wraps the Partial response under the `partial` key.
                example:
                  partial:
                    content: <p>Hello, world!</p>
                    description: This is a test partial
                    environment: development
                    icon_name: icon-name
                    input_schema:
                    - 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
                    inserted_at: '2021-01-01T00:00:00Z'
                    key: my-partial
                    name: My Partial
                    type: html
                    updated_at: '2021-01-01T00:00:00Z'
                    valid: true
                    visual_block_enabled: true
                properties:
                  partial:
                    $ref: '#/components/schemas/Partial'
                required:
                - partial
                title: WrappedPartialResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
      summary: Validate a partial
      tags:
      - Partials
components:
  schemas:
    PartialRequest:
      description: A partial object with attributes to update or create a partial.
      example:
        content: <p>Hello, world!</p>
        description: This is a test partial
        input_schema:
        - 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
        name: My Partial
        type: html
        visual_block_enabled: true
      properties:
        content:
          description: The partial content.
          type: string
          x-struct: null
          x-validate: null
        description:
          description: An arbitrary string attached to a partial object. Useful for adding notes about the partial for internal purposes. Maximum of 280 characters allowed.
          type: string
          x-struct: null
          x-validate: null
        icon_name:
          description: The name of the icon to be used in the visual editor.
          type: string
          x-struct: null
          x-validate: null
        input_schema:
          description: The field types available for the partial.
          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
        name:
          description: A name for the partial. Must be at maximum 255 characters in length.
          type: string
          x-struct: null
          x-validate: null
        type:
          description: The partial type. One of 'html', 'json', 'markdown', 'text'.
          enum:
          - html
          - text
          - json
          - markdown
          type: string
          x-struct: null
          x-validate: null
        visual_block_enabled:
          description: Indicates whether the partial can be used in the visual editor. Only applies to HTML partials.
          type: boolean
          x-struct: null
          x-validate: null
      required:
      - type
      - name
      - content
      title: PartialRequest
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.PartialRequest
      x-validate: null
    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
    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
    MessageTypeBooleanField:
      description: A boolean field used in a message type.
      example:
        key: boolean_field
        label: Boolean Field
        settings:
          default: false
          description: A description of the boolean field
          required: true
        type: boolean
      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 boolean field.
          properties:
            default:
              description: The default value of the boolean field.
              example: true
              type: boolean
              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:
          - boolean
          example: boolean
          type: string
          x-struct: null
          x-validate: null
      required:
      - type
      - key
      - label
      title: MessageTypeBooleanField
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.MessageTypes.BooleanField
      x-validate: null
    MessageTypeTextField:
      description: A text field used in a message type.
      example:
        key: text_field
        label: Text Field
        settings:
          description: A description of the text field
          max_length: 100
          min_length: 10
          placeholder: A placeholder for the text field
          required: true
        type: text
      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 text field.
          properties:
            default:
              description: The default value of the text field.
              example: A placeholder
              nullable: true
              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
            max_length:
              example: 100
              type: integer
              x-struct: null
              x-validate: null
            min_length:
              example: 10
              type: integer
              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:
          - text
          example: text
          type: string
          x-struct: null
          x-validate: null
      required:
      - type
      - key
      - label
      title: MessageTypeTextField
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.MessageTypes.TextField
      x-validate: null
    Partial:
      description: A partial is a reusable piece of content that can be used in a template.
      example:
        content: <p>Hello, world!</p>
        description: This is a test partial
        environment: development
        icon_name: icon-name
        input_schema:
        - 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
        inserted_at: '2021-01-01T00:00:00Z'
        key: my-partial
        name: My Partial
        type: html
        updated_at: '2021-01-01T00:00:00Z'
        valid: true
        visual_block_enabled: true
      properties:
        content:
          description: The partial content.
          type: string
          x-struct: null
          x-validate: null
        description:
          description: An arbitrary string attached to a partial object. Useful for adding notes about the partial for internal purposes. Maximum of 280 characters allowed.
          type: string
          x-struct: null
          x-validate: null
        environment:
          description: The slug of the environment in which the partial exists.
          type: string
          x-struct: null
          x-validate: null
        icon_name:
          description: The name of the icon to be used in the visual editor.
          type: string
          x-struct: null
          x-validate: null
        input_schema:
          description: The field types available for the partial.
          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
        inserted_at:
          description: The timestamp of when the partial was created.
          format: date-time
          type: string
          x-struct: null
          x-validate: null
        key:
          description: The unique key string for the partial 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 partial. Must be at maximum 255 characters in length.
          type: string
          x-struct: null
          x-validate: null
        type:
          description: The partial type. One of 'html', 'json', 'markdown', 'text'.
          enum:
          - html
          - text
          - json
          - markdown
          type: string
          x-struct: null
          x-validate: null
        updated_at:
          description: The timestamp of when the partial was last updated.
          format: date-time
          type: string
          x-struct: null
          x-validate: null
        valid:
          description: Whether the partial and its content are in a valid state.
          type: boolean
          x-struct: null
          x-validate: null
        visual_block_enabled:
          description: Indicates whether the partial can be used in the visual editor. Only applies to HTML partials.
          type: boolean
          x-struct: null
          x-validate: null
      required:
      - key
      - type
      - name
      - content
      - inserted_at
      - updated_at
      - valid
      title: Partial
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.Partial
      x-validate: null
    Messag

# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/knock-app/refs/heads/main/openapi/knock-app-partials-api-openapi.yml
Knock Partials API

Documentation

Specifications

Schemas & Data

Other Resources

OpenAPI Specification
