Knock Objects API

openapi: 3.2.0
info:
  title: Knock Objects API
  version: '1.0'
  description: An object represents a resource in your system that you want to map into Knock.
servers:
- url: https://api.knock.app
  variables: {}
security:
- BearerAuth: []
tags:
- description: An object represents a resource in your system that you want to map into Knock.
  name: Objects
paths:
  /v1/objects/{collection}/{object_id}/preferences/{id}/workflows:
    put:
      callbacks: {}
      deprecated: true
      description: Updates the workflow preferences for an object's preference set.
      operationId: updateObjectPreferenceWorkflows
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreferenceSet'
          description: OK
      summary: Update workflows in preference set
      tags:
      - Objects
      x-ratelimit-tier: 3
  /v1/objects/{collection}/{object_id}/preferences/{id}/channel_types/{type}:
    put:
      callbacks: {}
      deprecated: true
      description: Updates a specific channel type preference for an object's preference set.
      operationId: updateObjectPreferenceChannelType
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreferenceSet'
          description: OK
      summary: Update a channel type preference
      tags:
      - Objects
      x-ratelimit-tier: 3
  /v1/objects/{collection}/bulk/delete:
    post:
      callbacks: {}
      description: Bulk deletes objects from the specified collection.
      operationId: bulkDeleteObjects
      parameters:
      - description: The collection this object belongs to.
        in: path
        name: collection
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            example:
              object_ids:
              - obj_123
              - obj_456
              - obj_789
            schema:
              $ref: '#/components/schemas/BulkDeleteObjectsRequest'
        description: Params
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkOperation'
          description: OK
      summary: Bulk delete objects
      tags:
      - Objects
      x-ratelimit-tier: 1
  /v1/objects/{collection}/{object_id}/preferences/{id}/categories/{key}:
    put:
      callbacks: {}
      deprecated: true
      description: Updates a specific category preference for an object's preference set. Deprecated.
      operationId: updateObjectPreferenceCategory
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreferenceSet'
          description: OK
      summary: Update a category preference
      tags:
      - Objects
      x-ratelimit-tier: 3
  /v1/objects/{collection}/{object_id}/preferences:
    get:
      callbacks: {}
      description: Returns a paginated list of preference sets for the specified object.
      operationId: listObjectPreferenceSets
      parameters:
      - description: Unique identifier for the object.
        in: path
        name: object_id
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: The collection this object belongs to.
        in: path
        name: collection
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      responses:
        '200':
          content:
            application/json:
              schema:
                description: A list of preference sets for the object
                example:
                - categories:
                    marketing: false
                    transactional:
                      channel_types:
                        email: false
                  channel_types:
                    email: true
                    push: false
                    sms:
                      conditions:
                      - argument: US
                        operator: equal_to
                        variable: recipient.country_code
                  commercial_subscribed: true
                  id: default
                  workflows: null
                items:
                  $ref: '#/components/schemas/PreferenceSet'
                title: ListObjectPreferenceSetsResponse
                type: array
                x-struct: null
                x-validate: null
          description: OK
      summary: List preference sets
      tags:
      - Objects
      x-ratelimit-tier: 4
  /v1/objects/{collection}/{object_id}/preferences/{id}/workflows/{key}:
    put:
      callbacks: {}
      deprecated: true
      description: Updates a specific workflow preference for an object's preference set.
      operationId: updateObjectPreferenceWorkflow
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreferenceSet'
          description: OK
      summary: Update a workflow preference
      tags:
      - Objects
      x-ratelimit-tier: 3
  /v1/objects/{collection}/bulk/subscriptions/add:
    post:
      callbacks: {}
      description: Add subscriptions for all objects in a single collection. If a subscription for an object in the collection already exists, it will be updated. This endpoint also handles [inline identifications](/managing-recipients/identifying-recipients#inline-identifying-recipients) for the `recipient` field.
      operationId: bulkAddSubscriptions
      parameters:
      - description: The collection this object belongs to.
        example: projects
        in: path
        name: collection
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            example:
              subscriptions:
              - id: project-1
                properties: null
                recipients:
                - id: user_1
            schema:
              $ref: '#/components/schemas/BulkUpsertSubscriptionsRequest'
        description: Params
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkOperation'
          description: OK
      summary: Bulk add subscriptions
      tags:
      - Objects
      x-ratelimit-tier: 1
  /v1/objects/{collection}/{object_id}/preferences/{id}/categories:
    put:
      callbacks: {}
      deprecated: true
      description: Updates the category preferences for an object's preference set.
      operationId: updateObjectPreferenceCategories
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreferenceSet'
          description: OK
      summary: Update categories in preference set
      tags:
      - Objects
      x-ratelimit-tier: 3
  /v1/objects/{collection}/{id}:
    delete:
      callbacks: {}
      description: Permanently removes an object from the specified collection. This operation cannot be undone.
      operationId: deleteObject
      parameters:
      - description: The collection this object belongs to.
        in: path
        name: collection
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: Unique identifier for the object.
        in: path
        name: id
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      responses:
        '204':
          description: No Content
      summary: Delete an object
      tags:
      - Objects
      x-ratelimit-tier: 3
    get:
      callbacks: {}
      description: Retrieves a specific object by its ID from the specified collection. Returns the object with all its properties.
      operationId: getObject
      parameters:
      - description: The collection this object belongs to.
        in: path
        name: collection
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: Unique identifier for the object.
        in: path
        name: id
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Object'
          description: OK
      summary: Get an object
      tags:
      - Objects
      x-ratelimit-tier: 4
    put:
      callbacks: {}
      description: Creates a new object or updates an existing one in the specified collection. This operation is used to identify objects with their properties, as well as optional preferences and channel data.
      operationId: setObject
      parameters:
      - description: The collection this object belongs to.
        in: path
        name: collection
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: Unique identifier for the object.
        in: path
        name: id
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            example:
              channel_data:
                97c5837d-c65c-4d54-aa39-080eeb81c69d:
                  tokens:
                  - push_token_123
              description: My product description
              locale: en-US
              name: My product
              preferences:
                default:
                  channel_types:
                    email: true
                  workflows:
                    dinosaurs-loose:
                      channel_types:
                        email: true
              price: 100.0
              timezone: America/New_York
            schema:
              $ref: '#/components/schemas/SetObjectRequest'
        description: Params
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Object'
          description: OK
      summary: Set an object
      tags:
      - Objects
      x-ratelimit-tier: 3
  /v1/objects/{collection}:
    get:
      callbacks: {}
      description: Returns a paginated list of objects from the specified collection. Optionally includes preference data for the objects.
      operationId: listObjects
      parameters:
      - 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 items per page (defaults to 50).
        in: query
        name: page_size
        required: false
        schema:
          type: integer
          x-struct: null
          x-validate: null
      - description: The collection this object belongs to.
        in: path
        name: collection
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: Includes preferences of the objects in the response.
        in: query
        name: include[]
        required: false
        schema:
          items:
            enum:
            - preferences
            type: string
            x-struct: null
            x-validate: null
          type: array
          x-struct: null
          x-validate: null
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListObjectsResponse'
          description: OK
      summary: List objects in a collection
      tags:
      - Objects
      x-ratelimit-tier: 4
  /v1/objects/{collection}/{object_id}/preferences/{id}/channel_types:
    put:
      callbacks: {}
      deprecated: true
      description: Updates the channel type preferences for an object's preference set.
      operationId: updateObjectPreferenceChannelTypes
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreferenceSet'
          description: OK
      summary: Update channel types in preference set
      tags:
      - Objects
      x-ratelimit-tier: 3
  /v1/schedules/bulk/create:
    post:
      callbacks: {}
      description: Bulk creates up to 1,000 schedules at a time. This endpoint also handles [inline identifications](/managing-recipients/identifying-recipients#inline-identifying-recipients) for the `actor`, `recipient`, and `tenant` fields.
      operationId: bulkCreateSchedules
      parameters: []
      requestBody:
        content:
          application/json:
            example:
              schedules:
              - data:
                  key: value
                ending_at: null
                recipient: dnedry
                repeats:
                - __typename: ScheduleRepeat
                  day_of_month: null
                  days:
                  - mon
                  - tue
                  - wed
                  - thu
                  - fri
                  - sat
                  - sun
                  frequency: daily
                  hours: null
                  interval: 1
                  minutes: null
                scheduled_at: null
                tenant: acme_corp
                workflow: comment-created
              - data:
                  key: value
                ending_at: null
                recipient: esattler
                repeats:
                - __typename: ScheduleRepeat
                  day_of_month: null
                  days:
                  - mon
                  - tue
                  - wed
                  - thu
                  - fri
                  - sat
                  - sun
                  frequency: daily
                  hours: null
                  interval: 1
                  minutes: null
                scheduled_at: null
                tenant: acme_corp
                workflow: comment-created
            schema:
              $ref: '#/components/schemas/BulkCreateSchedulesRequest'
        description: Schedule bulk creation request
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkOperation'
          description: OK
      summary: Create schedules in bulk
      tags:
      - Objects
      x-ratelimit-tier: 1
  /v1/objects/{collection}/bulk/subscriptions/delete:
    post:
      callbacks: {}
      description: Delete subscriptions for many objects in a single collection type. If a subscription for an object in the collection doesn't exist, it will be skipped.
      operationId: bulkDeleteSubscriptions
      parameters:
      - description: The collection this object belongs to.
        example: projects
        in: path
        name: collection
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            example:
              subscriptions:
              - id: subscribed-to-object-1
                recipients:
                - collection: projects
                  id: subscriber-project-1
                - subscriber-user-1
              - id: subscribed-to-object-2
                recipients:
                - subscriber-user-2
            schema:
              $ref: '#/components/schemas/BulkDeleteSubscriptionsRequest'
        description: Params
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkOperation'
          description: OK
      summary: Bulk delete subscriptions
      tags:
      - Objects
      x-ratelimit-tier: 1
  /v1/objects/{collection}/{object_id}/preferences/{id}:
    delete:
      callbacks: {}
      description: Unsets the preference set for the object, removing it entirely.
      operationId: deleteObjectPreferenceSet
      parameters:
      - description: Unique identifier for the object.
        in: path
        name: object_id
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: The collection this object belongs to.
        in: path
        name: collection
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: Unique identifier for the preference set.
        in: path
        name: id
        required: true
        schema:
          default: default
          example: default
          type: string
          x-struct: null
          x-validate: null
      responses:
        '204':
          description: No Content
      summary: Delete object preference set
      tags:
      - Objects
      x-ratelimit-tier: 3
    get:
      callbacks: {}
      description: Returns the preference set for the specified object and preference set `id`.
      operationId: getObjectPreferenceSet
      parameters:
      - description: Unique identifier for the object.
        in: path
        name: object_id
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: The collection this object belongs to.
        in: path
        name: collection
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: Unique identifier for the preference set.
        in: path
        name: id
        required: true
        schema:
          default: default
          example: default
          type: string
          x-struct: null
          x-validate: null
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreferenceSet'
          description: OK
      summary: Get object preference set
      tags:
      - Objects
      x-ratelimit-tier: 4
    put:
      callbacks: {}
      description: 'Sets preferences within the given preference set. By default, this is a destructive operation and will replace any existing preferences with the preferences given. Use ''__persistence_strategy'': ''merge'' to merge with existing preferences instead. If no object exists in the current environment for the given `:collection` and `:object_id`, Knock will create the object as part of this request. The preference set `:id` can be either `default` or a `tenant.id`. Learn more about [per-tenant preferences](/preferences/tenant-preferences).'
      operationId: updateObjectPreferenceSet
      parameters:
      - description: Unique identifier for the object.
        in: path
        name: object_id
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: The collection this object belongs to.
        in: path
        name: collection
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: Unique identifier for the preference set.
        in: path
        name: id
        required: true
        schema:
          default: default
          example: default
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            example:
              __persistence_strategy__: merge
              categories:
                marketing: false
                transactional:
                  channel_types:
                    email: false
              channel_types:
                email: true
              channels:
                2f641633-95d3-4555-9222-9f1eb7888a80:
                  conditions:
                  - argument: US
                    operator: equal_to
                    variable: recipient.country_code
                aef6e715-df82-4ab6-b61e-b743e249f7b6: true
              commercial_subscribed: true
              workflows:
                dinosaurs-loose:
                  channel_types:
                    email: false
            schema:
              $ref: '#/components/schemas/PreferenceSetRequest'
        description: Params
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreferenceSet'
          description: OK
      summary: Update a preference set
      tags:
      - Objects
      x-ratelimit-tier: 3
  /v1/objects/{collection}/bulk/set:
    post:
      callbacks: {}
      description: Bulk sets up to 1,000 objects at a time in the specified collection.
      operationId: bulkSetObjects
      parameters:
      - description: The collection this object belongs to.
        in: path
        name: collection
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            example:
              objects:
              - id: project_1
                name: My project
            schema:
              $ref: '#/components/schemas/BulkSetObjectsRequest'
        description: Params
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkOperation'
          description: OK
      summary: Bulk set objects
      tags:
      - Objects
      x-ratelimit-tier: 1
components:
  schemas:
    DiscordIncomingWebhookConnection:
      description: Discord incoming webhook connection.
      example:
        incoming_webhook:
          url: https://example.com/webhook
      properties:
        incoming_webhook:
          description: Discord incoming webhook object.
          properties:
            url:
              description: Incoming webhook URL.
              example: https://example.com/webhook
              type: string
              x-struct: null
              x-validate: null
          required:
          - url
          type: object
          x-struct: null
          x-validate: null
      required:
      - incoming_webhook
      title: DiscordIncomingWebhookConnection
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.DiscordChannelData.IncomingWebhookConnection
      x-validate: null
    InlineChannelDataRequest:
      additionalProperties:
        description: Channel data for a given channel type.
        oneOf:
        - $ref: '#/components/schemas/PushChannelDataTokensOnly'
        - $ref: '#/components/schemas/PushChannelDataDevicesOnly'
        - $ref: '#/components/schemas/AWSSNSPushChannelDataTargetARNsOnly'
        - $ref: '#/components/schemas/AWSSNSPushChannelDataDevicesOnly'
        - $ref: '#/components/schemas/OneSignalChannelDataPlayerIdsOnly'
        - $ref: '#/components/schemas/SlackChannelData'
        - $ref: '#/components/schemas/MsTeamsChannelData'
        - $ref: '#/components/schemas/DiscordChannelData'
        x-struct: null
        x-validate: null
      description: A request to set channel data for a type of channel inline.
      example:
        97c5837d-c65c-4d54-aa39-080eeb81c69d:
          tokens:
          - push_token_xxx
      title: InlineChannelDataRequest
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.InlineChannelDataRequest
      x-validate: null
    PushChannelDataTokensOnly:
      description: Push channel data.
      example:
        tokens:
        - push_token_1
        - push_token_2
      properties:
        tokens:
          description: A list of push channel tokens.
          items:
            description: The device token to send the push notification to.
            type: string
            x-struct: null
            x-validate: null
          type: array
          x-struct: null
          x-validate: null
      required:
      - tokens
      title: PushChannelDataTokensOnly
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.PushChannelDataTokensOnly
      x-validate: null
    PreferenceSet:
      description: A preference set represents a specific set of notification preferences for a recipient. A recipient can have multiple preference sets.
      example:
        categories:
          marketing: false
          transactional:
            channel_types:
              email: false
        channel_types:
          email: true
          push: false
          sms:
            conditions:
            - argument: US
              operator: equal_to
              variable: recipient.country_code
        commercial_subscribed: true
        id: default
        workflows: null
      properties:
        categories:
          anyOf:
          - additionalProperties:
              $ref: '#/components/schemas/PreferenceSetWorkflowCategorySetting'
            description: An object where the key is the category and the values are the preference settings for that category.
            example:
              marketing:
                channel_types:
                  email: false
            title: PreferenceSetCategories
            type: object
            x-struct: null
            x-validate: null
          - x-struct: null
            x-validate: null
          description: An object where the key is the category and the values are the preference settings for that category.
          x-struct: null
          x-validate: null
        channel_types:
          anyOf:
          - $ref: '#/components/schemas/PreferenceSetChannelTypes'
          - x-struct: null
            x-validate: null
          description: An object where the key is the channel type and the values are the preference settings for that channel type.
          x-struct: null
          x-validate: null
        channels:
          anyOf:
          - $ref: '#/components/schemas/PreferenceSetChannels'
          - x-struct: null
            x-validate: null
          description: An object where the key is the channel ID and the values are the preference settings for that channel ID.
          x-struct: null
          x-validate: null
        commercial_subscribed:
          description: Whether the recipient is subscribed to commercial communications. When false, the recipient will not receive commercial workflow notifications.
          type:
          - boolean
          - 'null'
          x-struct: null
          x-validate: null
        id:
          description: Unique identifier for the preference set.
          example: default
          type: string
          x-struct: null
          x-validate: null
        workflows:
          anyOf:
          - additionalProperties:
              $ref: '#/components/schemas/PreferenceSetWorkflowCategorySetting'
            description: An object where the key is the workflow key and the values are the preference settings for that workflow.
            example:
              dinosaurs-loose:
                channel_types:
                  email: false
            title: PreferenceSetWorkflows
            type: object
            x-struct: null
            x-validate: null
          - x-struct: null
            x-validate: null
          description: An object where the key is the workflow key and the values are the preference settings for that workflow.
          x-struct: null
          x-validate: null
      required:
      - id
      title: PreferenceSet
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.PreferenceSet
      x-validate: null
    OneSignalChannelDataPlayerIdsOnly:
      description: OneSignal channel data.
      example:
        player_ids:
        - 123e4567-e89b-12d3-a456-426614174000
      properties:
        player_ids:
          description: A list of OneSignal player IDs.
          example:
          - 123e4567-e89b-12d3-a456-426614174000
          items:
            description: OneSignal player ID.
            format: uuid
            type: string
            x-struct: null
            x-validate: null
          type: array
          x-struct: null
          x-validate: null
      required:
      - player_ids
      title: OneSignalChannelDataPlayerIdsOnly
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.OneSignalChannelDataPlayerIdsOnly
      x-validate: null
    DiscordChannelConnection:
      description: Discord channel connection.
      example:
        channel_id: '123456789012345678'
      properties:
        channel_id:
          description: Discord channel ID.
          example: '123456789012345678'
          type: string
          x-struct: null
          x-validate: null
      required:
      - channel_id
      title: DiscordChannelConnection
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.DiscordChannelData.ChannelConnection
      x-validate: null
    PreferenceSetRequest:
      description: A request to set a preference set for a recipient.
      example:
        __persistence_strategy__: merge
        categories:
          marketing: false
          transactional:
            channel_types:
              email: false
        channel_types:
          email: true
        channels:
          2f641633-95d3-4555-9222-9f1eb7888a80:
            conditions:
            - argument: US
              operator: equal_to
              variable: recipient.country_code
          aef6e715-df82-4ab6-b61e-b743e249f7b6: true
        commercial_subscribed: true
        workflows:
          dinosaurs-loose:
            channel_types:
              email: false
      properties:
        __persistence_strategy__:
          description: Controls how the preference set is persisted. 'replace' will completely replace the preference set, 'merge' will merge with existing preferences.
          enum:
          - merge
          - replace
          type: string
          x-struct: null
          x-validate: null
        categories:
          anyOf:
          - additionalProperties:
              $ref: '#/components/schemas/PreferenceSetWorkflowCategorySetting'
            description: An object where the key is the category and the values are the preference settings for that category.
            example:
              marketing:
                channel_types:
                  email: false
              transactional: true
            title: PreferenceSetRequestCategories
            type: object
            x-struct: null
            x-validate: null
          - x-struct: null
            x-validate: null
          description: An object where the key is the category and the values are the preference settings for that category.
          x-struct: null
          x-validate: null
        channel_types:
          anyOf:
          - $ref: '#/components/schemas/PreferenceSetChannelTypes'
          - x-struct: null
            x-validate: null
          description: An object where the key is the channel type and the values are the preference settings for that channel type.
          x-struct: null
          x-validate: null
        channels:
          anyOf:
          - $ref: '#/components/schemas/PreferenceSetChannels'
          - x-struct: null
            x-validate: null
          description: An object where the key is the channel ID and the values are the preference settings for that channel ID.
          x-struct: null
          x-validate: null
        commercial_subscribed:
          description: Whether the recipient is subscribed to commercial communications. When false, the recipient will not receive commercial workflow notifications.
          type:
          - boolean
          - 'null'
          x-struct: null
      

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