Knock Guides API

openapi: 3.0.3
info:
  title: Knock Audiences Accounts Guides 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: Guides let you define in-app guides that can be displayed to users based on priority and other conditions.
  name: Guides
paths:
  /v1/guides/{guide_key}:
    delete:
      callbacks: {}
      description: Archives a given guide across all environments.
      operationId: archiveGuide
      parameters:
      - description: The key of the guide to archive.
        in: path
        name: guide_key
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      responses:
        '200':
          content:
            application/json:
              schema:
                description: The response from archiving a guide.
                example:
                  result: success
                properties:
                  result:
                    description: The result of the promote operation.
                    example: success
                    type: string
                    x-struct: null
                    x-validate: null
                required:
                - result
                title: ArchiveGuideResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
      summary: Archive a guide
      tags:
      - Guides
    get:
      callbacks: {}
      description: Get a guide by its key.
      operationId: getGuide
      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 guide to retrieve.
        in: path
        name: guide_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/Guide'
          description: OK
      summary: Get a guide
      tags:
      - Guides
    put:
      callbacks: {}
      description: 'Updates a guide of a given key, or creates a new one if it does not yet exist.


        Note: this endpoint only operates on guides in the "development" environment.

        '
      operationId: upsertGuide
      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 guide to upsert.
        in: path
        name: guide_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 GuideRequest request under the guide key.
              example:
                guide:
                  activation_url_patterns:
                  - directive: allow
                    pathname: /dashboard/*
                  channel_key: in-app-guide
                  description: A guide to help users get started with the application
                  name: Getting Started Guide
                  steps:
                  - name: Welcome to the App
                    ref: welcome-step
                    schema_key: tooltip
                    schema_semver: 1.0.0
                    schema_variant_key: default
                    values:
                      text_field: value
                  target_audience_id: null
                  target_property_conditions:
                    all:
                    - argument: some_property
                      operator: equal_to
                      variable: recipient.property
              properties:
                guide:
                  $ref: '#/components/schemas/GuideRequest'
              required:
              - guide
              title: WrappedGuideRequestRequest
              type: object
              x-struct: null
              x-validate: null
        description: Params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: Wraps the Guide response under the `guide` key.
                example:
                  guide:
                    activation_url_patterns:
                    - directive: allow
                      pathname: /dashboard/*
                    active: true
                    archived_at: null
                    channel_key: in-app-guide
                    created_at: '2024-01-01T00:00:00Z'
                    description: A guide to help users get started with the application
                    environment: development
                    key: getting-started
                    name: Getting Started Guide
                    semver: 0.0.1
                    sha: '1234567890'
                    steps:
                    - name: Welcome to the App
                      ref: welcome-step
                      schema_key: tooltip
                      schema_semver: 1.0.0
                      schema_variant_key: default
                      values:
                        text_field: value
                    target_audience_id: null
                    target_property_conditions:
                      all:
                      - argument: some_property
                        operator: equal_to
                        variable: recipient.property
                    type: banner
                    updated_at: '2024-01-01T00:00:00Z'
                    valid: true
                properties:
                  guide:
                    $ref: '#/components/schemas/Guide'
                required:
                - guide
                title: WrappedGuideResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
      summary: Upsert a guide
      tags:
      - Guides
  /v1/guides:
    get:
      callbacks: {}
      description: Returns a paginated list of guides available in a given environment.
      operationId: listGuides
      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 Guide. Contains a list of entries and page information.
                example:
                  entries:
                  - activation_url_patterns:
                    - directive: allow
                      pathname: /dashboard/*
                    active: true
                    archived_at: null
                    channel_key: in-app-guide
                    created_at: '2024-01-01T00:00:00Z'
                    description: A guide to help users get started with the application
                    environment: development
                    key: getting-started
                    name: Getting Started Guide
                    semver: 0.0.1
                    sha: '1234567890'
                    steps:
                    - name: Welcome to the App
                      ref: welcome-step
                      schema_key: tooltip
                      schema_semver: 1.0.0
                      schema_variant_key: default
                      values:
                        text_field: value
                    target_audience_id: null
                    target_property_conditions:
                      all:
                      - argument: some_property
                        operator: equal_to
                        variable: recipient.property
                    type: banner
                    updated_at: '2024-01-01T00:00:00Z'
                    valid: true
                  page_info:
                    after: null
                    before: null
                    page_size: 25
                properties:
                  entries:
                    description: A list of entries.
                    items:
                      $ref: '#/components/schemas/Guide'
                    nullable: false
                    type: array
                    x-struct: null
                    x-validate: null
                  page_info:
                    $ref: '#/components/schemas/PageInfo'
                required:
                - entries
                - page_info
                title: PaginatedGuideResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
      summary: List guides
      tags:
      - Guides
  /v1/guides/{guide_key}/activate:
    put:
      callbacks: {}
      description: 'Activates (or deactivates) a guide in a given environment. You can either set the active status immediately or schedule it.


        Note: This immediately enables or disables a guide in a given environment without needing to go through environment promotion.

        '
      operationId: activateGuide
      parameters:
      - description: The key of the guide.
        in: path
        name: guide_key
        required: true
        schema:
          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:
              $ref: '#/components/schemas/GuideActivationParams'
        description: Params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: Wraps the Guide response under the `guide` key.
                example:
                  guide:
                    activation_url_patterns:
                    - directive: allow
                      pathname: /dashboard/*
                    active: true
                    archived_at: null
                    channel_key: in-app-guide
                    created_at: '2024-01-01T00:00:00Z'
                    description: A guide to help users get started with the application
                    environment: development
                    key: getting-started
                    name: Getting Started Guide
                    semver: 0.0.1
                    sha: '1234567890'
                    steps:
                    - name: Welcome to the App
                      ref: welcome-step
                      schema_key: tooltip
                      schema_semver: 1.0.0
                      schema_variant_key: default
                      values:
                        text_field: value
                    target_audience_id: null
                    target_property_conditions:
                      all:
                      - argument: some_property
                        operator: equal_to
                        variable: recipient.property
                    type: banner
                    updated_at: '2024-01-01T00:00:00Z'
                    valid: true
                properties:
                  guide:
                    $ref: '#/components/schemas/Guide'
                required:
                - guide
                title: WrappedGuideResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
      summary: Activate a guide
      tags:
      - Guides
  /v1/guides/{guide_key}/validate:
    put:
      callbacks: {}
      description: 'Validates a guide payload without persisting it.


        Note: Validating a guide is only done in the development environment context.

        '
      operationId: validateGuide
      parameters:
      - description: The key of the guide.
        in: path
        name: guide_key
        required: true
        schema:
          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 GuideRequest request under the guide key.
              example:
                guide:
                  activation_url_patterns:
                  - directive: allow
                    pathname: /dashboard/*
                  channel_key: in-app-guide
                  description: A guide to help users get started with the application
                  name: Getting Started Guide
                  steps:
                  - name: Welcome to the App
                    ref: welcome-step
                    schema_key: tooltip
                    schema_semver: 1.0.0
                    schema_variant_key: default
                    values:
                      text_field: value
                  target_audience_id: null
                  target_property_conditions:
                    all:
                    - argument: some_property
                      operator: equal_to
                      variable: recipient.property
              properties:
                guide:
                  $ref: '#/components/schemas/GuideRequest'
              required:
              - guide
              title: WrappedGuideRequestRequest
              type: object
              x-struct: null
              x-validate: null
        description: Params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: Wraps the Guide response under the `guide` key.
                example:
                  guide:
                    activation_url_patterns:
                    - directive: allow
                      pathname: /dashboard/*
                    active: true
                    archived_at: null
                    channel_key: in-app-guide
                    created_at: '2024-01-01T00:00:00Z'
                    description: A guide to help users get started with the application
                    environment: development
                    key: getting-started
                    name: Getting Started Guide
                    semver: 0.0.1
                    sha: '1234567890'
                    steps:
                    - name: Welcome to the App
                      ref: welcome-step
                      schema_key: tooltip
                      schema_semver: 1.0.0
                      schema_variant_key: default
                      values:
                        text_field: value
                    target_audience_id: null
                    target_property_conditions:
                      all:
                      - argument: some_property
                        operator: equal_to
                        variable: recipient.property
                    type: banner
                    updated_at: '2024-01-01T00:00:00Z'
                    valid: true
                properties:
                  guide:
                    $ref: '#/components/schemas/Guide'
                required:
                - guide
                title: WrappedGuideResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
      summary: Validate a guide
      tags:
      - Guides
  /v1/users/{user_id}/guides/messages/seen:
    put:
      callbacks: {}
      description: Records that a guide has been seen by a user, triggering any associated seen events.
      operationId: markUserGuideAsSeen (2)
      parameters:
      - description: The unique identifier of the user.
        in: path
        name: user_id
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            example:
              channel_id: 123e4567-e89b-12d3-a456-426614174000
              content:
                body: Limited spots available for today's behind-the-scenes DNA extraction demonstration.
                title: DNA Lab Tour Available
              data:
                next_time: '14:30'
                spots_left: 8
                tour_id: dna_lab_tour
              guide_id: 7e9dc78c-b3b1-4127-a54e-71f1899b831a
              guide_key: tour_notification
              guide_step_ref: lab_tours
              is_final: false
              metadata:
                cta: Reserve Spot
                theme: amber
                type: banner
              tenant: ingen_isla_nublar
            schema:
              $ref: '#/components/schemas/GuideActionRequest'
        description: Params
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GuideActionResponse'
          description: OK
      summary: Mark guide as seen
      tags:
      - Guides
      x-ratelimit-tier: 2
  /v1/users/{user_id}/guides/messages/{message_id}/seen:
    put:
      callbacks: {}
      description: Records that a guide has been seen by a user, triggering any associated seen events.
      operationId: markUserGuideAsSeen
      parameters:
      - description: The unique identifier of the user.
        in: path
        name: user_id
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            example:
              channel_id: 123e4567-e89b-12d3-a456-426614174000
              content:
                body: Limited spots available for today's behind-the-scenes DNA extraction demonstration.
                title: DNA Lab Tour Available
              data:
                next_time: '14:30'
                spots_left: 8
                tour_id: dna_lab_tour
              guide_id: 7e9dc78c-b3b1-4127-a54e-71f1899b831a
              guide_key: tour_notification
              guide_step_ref: lab_tours
              is_final: false
              metadata:
                cta: Reserve Spot
                theme: amber
                type: banner
              tenant: ingen_isla_nublar
            schema:
              $ref: '#/components/schemas/GuideActionRequest'
        description: Params
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GuideActionResponse'
          description: OK
      summary: Mark guide as seen
      tags:
      - Guides
      x-ratelimit-tier: 2
  /v1/users/{user_id}/guides/messages/archived:
    delete:
      callbacks: {}
      description: Records that a guide has been unarchived, triggering any associated unarchived events.
      operationId: markUserGuideAsUnarchived
      parameters:
      - description: The unique identifier of the user.
        in: path
        name: user_id
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GuideActionRequest'
        description: Params
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GuideActionResponse'
          description: OK
      summary: Mark guide as unarchived
      tags:
      - Guides
      x-ratelimit-tier: 2
    put:
      callbacks: {}
      description: Records that a guide has been archived by a user, triggering any associated archived events.
      operationId: markUserGuideAsArchived (2)
      parameters:
      - description: The unique identifier of the user.
        in: path
        name: user_id
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GuideActionRequest'
        description: Params
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GuideActionResponse'
          description: OK
      summary: Mark guide as archived
      tags:
      - Guides
      x-ratelimit-tier: 2
  /v1/users/{user_id}/guides/messages/interacted:
    put:
      callbacks: {}
      description: Records that a user has interacted with a guide, triggering any associated interacted events.
      operationId: markUserGuideAsInteracted (2)
      parameters:
      - description: The unique identifier of the user.
        in: path
        name: user_id
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GuideActionRequest'
        description: Params
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GuideActionResponse'
          description: OK
      summary: Mark guide as interacted
      tags:
      - Guides
      x-ratelimit-tier: 2
  /v1/users/{user_id}/guides/engagements/reset:
    put:
      callbacks: {}
      description: Resets the engagement state of a guide for a user, removing the guide's engagement log entry so the next interaction creates a fresh engagement.
      operationId: resetUserGuideEngagement
      parameters:
      - description: The unique identifier of the user.
        in: path
        name: user_id
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GuideActionRequest'
        description: Params
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GuideActionResponse'
          description: OK
      summary: Reset guide engagement
      tags:
      - Guides
      x-ratelimit-tier: 2
  /v1/users/{user_id}/guides/{channel_id}:
    get:
      callbacks: {}
      description: Returns a list of eligible in-app guides for a specific user and channel.
      operationId: listUserGuides
      parameters:
      - description: The unique identifier of the user.
        in: path
        name: user_id
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: The unique identifier for the channel.
        in: path
        name: channel_id
        required: true
        schema:
          format: uuid
          type: string
          x-struct: null
          x-validate: null
      - description: The tenant ID to use for targeting and rendering guides.
        in: query
        name: tenant
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: The data (JSON encoded object) to use for targeting and rendering guides.
        in: query
        name: data
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: The type of guides to filter by.
        in: query
        name: type
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GuidesResponse'
          description: OK
      summary: List guides
      tags:
      - Guides
      x-ratelimit-tier: 2
  /v1/users/{user_id}/guides/messages/{message_id}/interacted:
    put:
      callbacks: {}
      description: Records that a user has interacted with a guide, triggering any associated interacted events.
      operationId: markUserGuideAsInteracted
      parameters:
      - description: The unique identifier of the user.
        in: path
        name: user_id
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GuideActionRequest'
        description: Params
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GuideActionResponse'
          description: OK
      summary: Mark guide as interacted
      tags:
      - Guides
      x-ratelimit-tier: 2
  /v1/users/{user_id}/guides/messages/{message_id}/archived:
    put:
      callbacks: {}
      description: Records that a guide has been archived by a user, triggering any associated archived events.
      operationId: markUserGuideAsArchived
      parameters:
      - description: The unique identifier of the user.
        in: path
        name: user_id
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GuideActionRequest'
        description: Params
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GuideActionResponse'
          description: OK
      summary: Mark guide as archived
      tags:
      - Guides
      x-ratelimit-tier: 2
components:
  schemas:
    Guide:
      description: A guide defines an in-app guide that can be displayed to users based on priority and other conditions.
      example:
        activation_url_patterns:
        - directive: allow
          pathname: /dashboard/*
        active: true
        archived_at: null
        channel_key: in-app-guide
        created_at: '2024-01-01T00:00:00Z'
        description: A guide to help users get started with the application
        environment: development
        key: getting-started
        name: Getting Started Guide
        semver: 0.0.1
        sha: '1234567890'
        steps:
        - name: Welcome to the App
          ref: welcome-step
          schema_key: tooltip
          schema_semver: 1.0.0
          schema_variant_key: default
          values:
            text_field: value
        target_audience_id: null
        target_property_conditions:
          all:
          - argument: some_property
            operator: equal_to
            variable: recipient.property
        type: banner
        updated_at: '2024-01-01T00:00:00Z'
        valid: true
      properties:
        activation_url_patterns:
          description: A list of activation url patterns that describe when the guide should be shown.
          items:
            $ref: '#/components/schemas/GuideActivationUrlPattern'
          type: array
   

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