Knock Objects API

openapi: 3.0.0
info:
  title: Knock Audiences Objects API
  version: '1.0'
  description: An Audience is a segment of users.
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}/{id}/schedules:
    get:
      callbacks: {}
      description: Returns a paginated list of schedules for an object.
      operationId: listObjectSchedules
      parameters:
      - description: The ID of the object to list schedules for.
        in: path
        name: id
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: The collection of the object to list schedules for.
        in: path
        name: collection
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: Filter schedules by tenant id.
        in: query
        name: tenant
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: Filter schedules by workflow id.
        in: query
        name: workflow
        required: false
        schema:
          type: string
          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 items per page (defaults to 50).
        in: query
        name: page_size
        required: false
        schema:
          type: integer
          x-struct: null
          x-validate: null
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSchedulesResponse'
          description: OK
      summary: List object schedules
      tags:
      - Objects
      x-ratelimit-tier: 4
  /v1/objects/{collection}/{id}/messages:
    get:
      callbacks: {}
      description: Returns a paginated list of messages for a specific object in the given collection. Allows filtering by message status and provides various sorting options.
      operationId: listMessagesForObject
      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: Limits the results to items with the corresponding tenant.
        example: tenant_123
        in: query
        name: tenant
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: Limits the results to items with the corresponding channel ID.
        example: 123e4567-e89b-12d3-a456-426614174000
        in: query
        name: channel_id
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: Limits the results to messages with the given delivery status.
        example:
        - delivered
        in: query
        name: status[]
        required: false
        schema:
          items:
            enum:
            - queued
            - sent
            - delivered
            - delivery_attempted
            - undelivered
            - not_sent
            - bounced
            type: string
            x-struct: null
            x-validate: null
          type: array
          x-struct: null
          x-validate: null
      - description: Limits the results to messages with the given engagement status.
        example:
        - unread
        in: query
        name: engagement_status[]
        required: false
        schema:
          items:
            enum:
            - seen
            - unseen
            - read
            - unread
            - archived
            - unarchived
            - link_clicked
            - interacted
            type: string
            x-struct: null
            x-validate: null
          type: array
          x-struct: null
          x-validate: null
      - description: 'Limits the results to only the message IDs given (max 50). Note: when using this option, the results will be subject to any other filters applied to the query.'
        example:
        - 1jNaXzB2RZX3LY8wVQnfCKyPnv7
        in: query
        name: message_ids[]
        required: false
        schema:
          items:
            type: string
            x-struct: null
            x-validate: null
          type: array
          x-struct: null
          x-validate: null
      - description: Limits the results to messages related to any of the provided categories.
        example:
        - workflow_123
        in: query
        name: workflow_categories[]
        required: false
        schema:
          items:
            type: string
            x-struct: null
            x-validate: null
          type: array
          x-struct: null
          x-validate: null
      - description: Limits the results to messages triggered by the given workflow key.
        example: comment-created
        in: query
        name: source
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: Limits the results to messages associated with the top-level workflow run ID returned by the workflow trigger request.
        example: 123e4567-e89b-12d3-a456-426614174000
        in: query
        name: workflow_run_id
        required: false
        schema:
          format: uuid
          type: string
          x-struct: null
          x-validate: null
      - description: Limits the results to messages for a specific recipient's workflow run.
        example: 123e4567-e89b-12d3-a456-426614174000
        in: query
        name: workflow_recipient_run_id
        required: false
        schema:
          format: uuid
          type: string
          x-struct: null
          x-validate: null
      - description: Limits the results to only messages that were generated with the given data. See [trigger data filtering](/api-reference/overview/trigger-data-filtering) for more information.
        example: '{"comment_id": "123"}'
        in: query
        name: trigger_data
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: Limits the results to items inserted after the given date.
        example: '2025-01-01T00:00:00Z'
        in: query
        name: inserted_at.gt
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: Limits the results to items inserted after or on the given date.
        example: '2025-01-01T00:00:00Z'
        in: query
        name: inserted_at.gte
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: Limits the results to items inserted before the given date.
        example: '2025-01-01T00:00:00Z'
        in: query
        name: inserted_at.lt
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: Limits the results to items inserted before or on the given date.
        example: '2025-01-01T00:00:00Z'
        in: query
        name: inserted_at.lte
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: The collection this object belongs to.
        example: projects
        in: path
        name: collection
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: Unique identifier for the object.
        example: project-123
        in: path
        name: id
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListMessagesResponse'
          description: OK
      summary: List messages
      tags:
      - Objects
      x-ratelimit-tier: 4
      x-retention-policy: true
  /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}/{object_id}/channel_data/{channel_id}:
    delete:
      callbacks: {}
      description: Unsets the channel data for the specified object and channel.
      operationId: unsetObjectChannelData
      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: The unique identifier for the channel.
        in: path
        name: channel_id
        required: true
        schema:
          format: uuid
          type: string
          x-struct: null
          x-validate: null
      responses:
        '204':
          description: No Content
      summary: Unset channel data
      tags:
      - Objects
      x-ratelimit-tier: 3
    get:
      callbacks: {}
      description: Returns the channel data for the specified object and channel.
      operationId: getObjectChannelData
      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: The unique identifier for the channel.
        in: path
        name: channel_id
        required: true
        schema:
          format: uuid
          type: string
          x-struct: null
          x-validate: null
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChannelData'
          description: OK
      summary: Get channel data
      tags:
      - Objects
      x-ratelimit-tier: 4
    put:
      callbacks: {}
      description: Sets the channel data for the specified object and channel. 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.
      operationId: setObjectChannelData
      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: The unique identifier for the channel.
        in: path
        name: channel_id
        required: true
        schema:
          format: uuid
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            example:
              data:
                tokens:
                - push_token_1
            schema:
              $ref: '#/components/schemas/ChannelDataRequest'
        description: Params
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChannelData'
          description: OK
      summary: Set channel data
      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: p

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