Knock Partials API

openapi: 3.2.0
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'
                    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:
    MessageTypeJsonField:
      description: A JSON field used in a message type.
      example:
        key: json_field
        label: JSON Field
        settings:
          default:
            key: value
          description: A description of the JSON field
          placeholder: A placeholder for the JSON field
          required: true
          schema:
            properties:
              key:
                type: string
            required:
            - key
        type: json
      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
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        settings:
          description: Settings for the json field.
          properties:
            default:
              description: The default value of the JSON field.
              example:
                key: value
              type:
              - object
              - 'null'
              x-struct: null
              x-validate: null
            description:
              example: A description of the field, used in the UI as a hint text.
              type:
              - string
              - 'null'
              x-struct: null
              x-validate: null
            placeholder:
              example: A placeholder for the field.
              type:
              - string
              - 'null'
              x-struct: null
              x-validate: null
            required:
              description: Whether the field is required.
              example: true
              type: boolean
              x-struct: null
              x-validate: null
            schema:
              description: A JSON schema used to validate the structure of the JSON provided. Must be a valid JSON schema.
              example:
                properties:
                  key:
                    type: string
              type:
              - object
              - 'null'
              x-struct: null
              x-validate: null
          type: object
          x-struct: null
          x-validate: null
        type:
          description: The type of the field.
          enum:
          - json
          example: json
          type: string
          x-struct: null
          x-validate: null
      required:
      - type
      - key
      - label
      title: MessageTypeJsonField
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.MessageTypes.JsonField
      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
          type:
          - string
          - 'null'
          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.
              type:
              - string
              - 'null'
              x-struct: null
              x-validate: null
            placeholder:
              example: A placeholder for the field.
              type:
              - string
              - 'null'
              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
    MessageTypeButtonField:
      description: A button field used in a message type.
      example:
        action:
          key: action
          label: Button Action
          settings:
            description: A description of the text field in the button action
            required: true
          type: text
        key: button_field
        label: Button Field
        settings:
          description: A description of the button field
          required: true
        text:
          key: text
          label: Button Text
          settings:
            description: A description of the text field in the button
            required: true
          type: text
        type: button
      properties:
        action:
          $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
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        settings:
          description: Settings for the button field.
          properties:
            description:
              example: A description of the field, used in the UI as a hint text.
              type:
              - string
              - 'null'
              x-struct: null
              x-validate: null
            placeholder:
              example: A placeholder for the field.
              type:
              - string
              - 'null'
              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
        text:
          $ref: '#/components/schemas/MessageTypeTextField'
        type:
          description: The type of the field.
          enum:
          - button
          example: button
          type: string
          x-struct: null
          x-validate: null
      required:
      - type
      - key
      - label
      - text
      - action
      title: MessageTypeButtonField
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.MessageTypes.ButtonField
      x-validate: null
    MessageTypeUrlField:
      description: A URL field used in a message type.
      example:
        key: url_field
        label: URL Field
        settings:
          description: A description of the URL field
          placeholder: A placeholder for the URL field
          required: true
        type: url
      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
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        settings:
          description: Settings for the url field.
          properties:
            default:
              description: The default value of the URL field.
              example: https://example.com
              type:
              - string
              - 'null'
              x-struct: null
              x-validate: null
            description:
              example: A description of the field, used in the UI as a hint text.
              type:
              - string
              - 'null'
              x-struct: null
              x-validate: null
            placeholder:
              example: A placeholder for the field.
              type:
              - string
              - 'null'
              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:
          - url
          example: url
          type: string
          x-struct: null
          x-validate: null
      required:
      - type
      - key
      - label
      title: MessageTypeUrlField
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.MessageTypes.UrlField
      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
          type:
          - string
          - 'null'
          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
              type:
              - string
              - 'null'
              x-struct: null
              x-validate: null
            description:
              example: A description of the field, used in the UI as a hint text.
              type:
              - string
              - 'null'
              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.
              type:
              - string
              - 'null'
              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
    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
          type:
          - string
          - 'null'
          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.
              type:
              - string
              - 'null'
              x-struct: null
              x-validate: null
            placeholder:
              example: A placeholder for the field.
              type:
              - string
              - 'null'
              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
    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.
          type:
          - string
          - 'null'
          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.
          type:
          - string
          - 'null'
          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
    MessageTypeSelectField:
      description: A select field used in a message type.
      example:
        key: select_field
        label: Select Field
        settings:
          default: option1
          description: A description of the select field
          options:
          - label: Option 1
            value: option1
          - label: Option 2
            value: option2
          - label: Option 3
            value: option3
          required: true
        type: 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
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        settings:
          description: Settings for the select field.
          properties:
            default:
              description: The default value for the select field.
              example: option1
              type:
              - string
              - 'null'
              x-struct: null
              x-validate: null
            description:
              example: A description of the field, used in the UI as a hint text.
              type:
              - string
              - 'null'
              x-struct: null
              x-validate: null
            options:
              description: The available options for the 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.
              type:
              - string
              - 'null'
              x-struct: null
              x-validate: null
            required:
              description: Whether the field is required.
              example: true
              type: boolean


# --- 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