Knock Feeds API
The Feeds API from Knock — 2 operation(s) for feeds.
OpenAPI Specification
openapi: 3.0.0
info:
title: Knock Audiences Feeds API
version: '1.0'
description: An Audience is a segment of users.
servers:
- url: https://api.knock.app
variables: {}
security:
- BearerAuth: []
tags:
- name: Feeds
paths:
/v1/users/{user_id}/feeds/{id}:
get:
callbacks: {}
description: 'Returns a paginated list of feed items for a user in reverse chronological order, including metadata about the feed. If the user has not yet been identified within Knock, an empty feed will be returned.
You can customize the response using [response filters](/integrations/in-app/knock#customizing-api-response-content) to exclude or only include specific properties on your resources.
**Notes:**
* When making this call from a client-side environment, use your publishable key along with a user token.
* This endpoint’s rate limit is always scoped per-user and per-environment. This is true even for requests made without a signed user token.
* Any [attachments](/integrations/email/attachments) present in trigger data are automatically excluded from both the `data` and `activities` fields of `UserInAppFeedResponse`.
'
operationId: listUserInAppFeedItems
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: id
required: true
schema:
format: uuid
type: string
x-struct: null
x-validate: null
- description: The status of the feed items.
example: unread
in: query
name: status
required: false
schema:
enum:
- unread
- read
- unseen
- seen
- all
type: string
x-struct: null
x-validate: null
- description: The workflow key associated with the message in the feed.
example: my_source
in: query
name: source
required: false
schema:
type: string
x-struct: null
x-validate: null
- description: The tenant associated with the feed items.
example: my_tenant
in: query
name: tenant
required: false
schema:
type: string
x-struct: null
x-validate: null
- description: Whether the feed items have a tenant.
example: true
in: query
name: has_tenant
required: false
schema:
type: boolean
x-struct: null
x-validate: null
- description: The workflow categories of the feed items.
example:
- my_workflow_category
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: The archived status of the feed items.
example: exclude
in: query
name: archived
required: false
schema:
enum:
- exclude
- include
- only
type: string
x-struct: null
x-validate: null
- description: The trigger data of the feed items (as a JSON string).
example: '{ "key": "value" }'
in: query
name: trigger_data
required: false
schema:
type: string
x-struct: null
x-validate: null
- description: The locale to render the feed items in. Must be in the IETF 5646 format (e.g. `en-US`). When not provided, will default to the locale that the feed items were rendered in. Only available for enterprise plan customers using custom translations.
example: en-US
in: query
name: locale
required: false
schema:
type: string
x-struct: null
x-validate: null
- description: Comma-separated list of field paths to exclude from the response. Use dot notation for nested fields (e.g., `entries.archived_at`). Limited to 3 levels deep.
example: entries.archived_at,entries.clicked_at
in: query
name: exclude
required: false
schema:
type: string
x-struct: null
x-validate: null
- description: The mode to render the feed items in. Can be `compact` or `rich`. Defaults to `rich`. When `mode` is `compact`, feed items will not have `activities` and `total_activities` fields; the `data` field will not include nested arrays and objects; and the `actors` field will only have up to one actor.
example: compact
in: query
name: mode
required: false
schema:
default: rich
enum:
- compact
- rich
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
- 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
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UserInAppFeedResponse'
description: OK
summary: List feed items
tags:
- Feeds
x-ratelimit-tier: 2
/v1/users/{user_id}/feeds/{id}/settings:
get:
callbacks: {}
description: Returns the feed settings for a user.
operationId: getUserInAppFeedSettings
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: id
required: true
schema:
format: uuid
type: string
x-struct: null
x-validate: null
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UserInAppFeedSettingsResponse'
description: OK
summary: Get feed settings
tags:
- Feeds
x-ratelimit-tier: 4
components:
schemas:
PageInfo:
description: Pagination information for a list of resources.
example:
__typename: PageInfo
after: null
before: null
page_size: 25
properties:
__typename:
description: The typename of the schema.
example: PageInfo
type: string
x-struct: null
x-validate: null
after:
description: The cursor to fetch entries after.
nullable: true
type: string
x-struct: null
x-validate: null
before:
description: The cursor to fetch entries before.
nullable: true
type: string
x-struct: null
x-validate: null
page_size:
description: The number of items per page (defaults to 50).
type: integer
x-struct: null
x-validate: null
required:
- __typename
- page_size
title: PageInfo
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.PageInfo
x-validate: null
Object:
description: A custom [Object](/concepts/objects) entity which belongs to a collection.
example:
__typename: Object
collection: assets
created_at: null
id: specimen_25
properties:
classification: Theropod
config:
biz: baz
foo: bar
name: Velociraptor
status: contained
updated_at: '2024-05-22T12:00:00Z'
properties:
__typename:
description: The typename of the schema.
example: Object
type: string
x-struct: null
x-validate: null
collection:
description: The collection this object belongs to.
type: string
x-struct: null
x-validate: null
created_at:
description: Timestamp when the resource was created.
format: date-time
nullable: true
type: string
x-struct: null
x-validate: null
id:
description: Unique identifier for the object.
type: string
x-struct: null
x-validate: null
properties:
additionalProperties: true
description: The custom properties associated with the object.
type: object
x-struct: null
x-validate: null
updated_at:
description: The timestamp when the resource was last updated.
format: date-time
type: string
x-struct: null
x-validate: null
required:
- __typename
- id
- collection
- updated_at
title: Object
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.Object
x-validate: null
InAppFeedItem:
description: An in-app feed message in a user's feed.
example:
__typename: FeedItem
activities:
- __typename: Activity
actor: null
data:
foo: bar
id: 2FVHPWxRqNuXQ9krvNP5A6Z4qXe
inserted_at: '2024-01-01T00:00:00Z'
recipient:
__typename: User
avatar: null
created_at: null
email: jane@ingen.net
id: jane
name: Jane Doe
phone_number: null
timezone: null
updated_at: '2024-05-22T12:00:00Z'
updated_at: '2024-01-01T00:00:00Z'
actors:
- __typename: User
avatar: null
created_at: null
email: jane@ingen.net
id: jane
name: Jane Doe
phone_number: null
timezone: null
updated_at: '2024-05-22T12:00:00Z'
blocks:
- content: This is a message in an app feed
name: body
rendered: <p>This is a message in an app feed</p>
type: markdown
data:
foo: bar
id: 2FVHPWxRqNuXQ9krvNP5A6Z4qXe
inserted_at: '2021-01-01T00:00:00Z'
source:
__typename: Workflow
categories:
- collaboration
key: my_source
version_id: 123e4567-e89b-12d3-a456-426614174000
tenant: acme_corp
total_activities: 10
total_actors: 5
updated_at: '2021-01-01T00:00:00Z'
properties:
__typename:
description: The typename of the schema.
example: FeedItem
type: string
x-struct: null
x-validate: null
activities:
description: List of activities associated with this feed item.
items:
$ref: '#/components/schemas/Activity'
type: array
x-struct: null
x-validate: null
actors:
description: List of actors associated with this feed item.
items:
$ref: '#/components/schemas/Recipient'
type: array
x-struct: null
x-validate: null
archived_at:
description: Timestamp when the feed item was archived.
nullable: true
type: string
x-struct: null
x-validate: null
blocks:
description: Content blocks that make up the feed item.
items:
description: A content block for the feed, can be content or a button set.
nullable: false
oneOf:
- $ref: '#/components/schemas/MessageInAppFeedContentBlock'
- $ref: '#/components/schemas/MessageInAppFeedButtonSetBlock'
type: object
x-struct: null
x-validate: null
type: array
x-struct: null
x-validate: null
clicked_at:
description: Timestamp when the feed item was clicked.
nullable: true
type: string
x-struct: null
x-validate: null
data:
additionalProperties: true
description: Additional data associated with the feed item.
nullable: true
type: object
x-struct: null
x-validate: null
id:
description: Unique identifier for the feed.
example: 2FVHPWxRqNuXQ9krvNP5A6Z4qXe
type: string
x-struct: null
x-validate: null
inserted_at:
description: Timestamp when the resource was created.
nullable: false
type: string
x-struct: null
x-validate: null
interacted_at:
description: Timestamp when the feed item was interacted with.
nullable: true
type: string
x-struct: null
x-validate: null
link_clicked_at:
description: Timestamp when a link within the feed item was clicked.
nullable: true
type: string
x-struct: null
x-validate: null
read_at:
description: Timestamp when the feed item was marked as read.
nullable: true
type: string
x-struct: null
x-validate: null
seen_at:
description: Timestamp when the feed item was marked as seen.
nullable: true
type: string
x-struct: null
x-validate: null
source:
description: Source information for the feed item.
nullable: false
properties:
__typename:
description: The typename of the schema.
example: Workflow
type: string
x-struct: null
x-validate: null
categories:
description: Categories this workflow belongs to.
items:
nullable: false
type: string
x-struct: null
x-validate: null
type: array
x-struct: null
x-validate: null
key:
description: The key of the workflow.
nullable: false
type: string
x-struct: null
x-validate: null
version_id:
description: The workflow version ID.
format: uuid
nullable: false
type: string
x-struct: null
x-validate: null
required:
- __typename
- key
- version_id
- categories
type: object
x-struct: null
x-validate: null
tenant:
description: Tenant ID that the feed item belongs to.
nullable: true
type: string
x-struct: null
x-validate: null
total_activities:
description: Total number of activities related to this feed item.
example: 10
type: integer
x-struct: null
x-validate: null
total_actors:
description: Total number of actors related to this feed item.
example: 5
type: integer
x-struct: null
x-validate: null
updated_at:
description: The timestamp when the resource was last updated.
nullable: false
type: string
x-struct: null
x-validate: null
required:
- __typename
- id
- inserted_at
- updated_at
- actors
- activities
- blocks
- source
- tenant
- total_activities
- total_actors
- data
title: InAppFeedItem
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.InAppFeedItem
x-validate: null
Recipient:
description: A recipient of a notification, which is either a user or an object.
example:
__typename: User
avatar: null
created_at: null
email: jane@ingen.net
id: jane
name: Jane Doe
phone_number: null
timezone: null
updated_at: '2024-05-22T12:00:00Z'
oneOf:
- $ref: '#/components/schemas/User'
- $ref: '#/components/schemas/Object'
title: Recipient
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.Recipient
x-validate: null
UserInAppFeedResponse:
description: A paginated list of feed items.
example:
entries:
- __typename: FeedItem
activities:
- __typename: Activity
actor: null
data:
foo: bar
id: 2FVHPWxRqNuXQ9krvNP5A6Z4qXe
inserted_at: '2024-01-01T00:00:00Z'
recipient:
__typename: User
avatar: null
created_at: null
email: jane@ingen.net
id: jane
name: Jane Doe
phone_number: null
timezone: null
updated_at: '2024-05-22T12:00:00Z'
updated_at: '2024-01-01T00:00:00Z'
actors:
- __typename: User
avatar: null
created_at: null
email: jane@ingen.net
id: jane
name: Jane Doe
phone_number: null
timezone: null
updated_at: '2024-05-22T12:00:00Z'
blocks:
- content: This is a message in an app feed
name: body
rendered: <p>This is a message in an app feed</p>
type: markdown
data:
foo: bar
id: 2FVHPWxRqNuXQ9krvNP5A6Z4qXe
inserted_at: '2021-01-01T00:00:00Z'
source:
__typename: Workflow
categories:
- collaboration
key: my_source
version_id: 123e4567-e89b-12d3-a456-426614174000
tenant: acme_corp
total_activities: 10
total_actors: 5
updated_at: '2021-01-01T00:00:00Z'
meta:
__typename: FeedMetadata
total_count: 100
unread_count: 10
unseen_count: 5
page_info:
__typename: PageInfo
after: null
before: null
page_size: 25
vars:
foo: bar
properties:
entries:
description: The list of feed items in the user's feed.
items:
$ref: '#/components/schemas/InAppFeedItem'
nullable: false
type: array
x-struct: null
x-validate: null
meta:
description: The metadata for the user's feed.
example:
__typename: FeedMetadata
total_count: 100
unread_count: 10
unseen_count: 5
properties:
__typename:
description: The typename of the schema.
example: FeedMetadata
type: string
x-struct: null
x-validate: null
total_count:
description: The total number of feed items in the user's feed.
example: 100
type: integer
x-struct: null
x-validate: null
unread_count:
description: The number of unread feed items in the user's feed.
example: 10
type: integer
x-struct: null
x-validate: null
unseen_count:
description: The number of unseen feed items in the user's feed.
example: 5
type: integer
x-struct: null
x-validate: null
required:
- __typename
- total_count
- unread_count
- unseen_count
type: object
x-struct: null
x-validate: null
page_info:
$ref: '#/components/schemas/PageInfo'
vars:
additionalProperties: true
description: Additional variables for the feed item.
type: object
x-struct: null
x-validate: null
required:
- entries
- page_info
- vars
- meta
title: UserInAppFeedResponse
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.UserInAppFeedResponse
x-validate: null
Activity:
description: An activity associated with a workflow trigger request. Messages produced after a [batch step](/designing-workflows/batch-function) can be associated with one or more activities. Non-batched messages will always be associated with a single activity.
example:
__typename: Activity
actor: null
data:
foo: bar
id: 2FVHPWxRqNuXQ9krvNP5A6Z4qXe
inserted_at: '2024-01-01T00:00:00Z'
recipient:
__typename: User
avatar: null
created_at: null
email: jane@ingen.net
id: jane
name: Jane Doe
phone_number: null
timezone: null
updated_at: '2024-05-22T12:00:00Z'
updated_at: '2024-01-01T00:00:00Z'
properties:
__typename:
description: The typename of the schema.
example: Activity
type: string
x-struct: null
x-validate: null
actor:
anyOf:
- $ref: '#/components/schemas/Recipient'
- nullable: true
x-struct: null
x-validate: null
description: The actor who performed the activity.
type: object
x-struct: null
x-validate: null
data:
additionalProperties: true
description: The workflow trigger `data` payload associated with the activity.
nullable: true
type: object
x-struct: null
x-validate: null
id:
description: Unique identifier for the activity.
example: 2FVHPWxRqNuXQ9krvNP5A6Z4qXe
type: string
x-struct: null
x-validate: null
inserted_at:
description: Timestamp when the activity was created.
format: date-time
type: string
x-struct: null
x-validate: null
recipient:
$ref: '#/components/schemas/Recipient'
updated_at:
description: Timestamp when the activity was last updated.
format: date-time
type: string
x-struct: null
x-validate: null
title: Activity
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.Activity
x-validate: null
MessageInAppFeedButtonSetBlock:
description: A button set block in a message in an app feed.
example:
buttons:
- action: action_1
label: Action 1
name: primary
name: actions
type: button_set
properties:
buttons:
description: A list of buttons in an in app feed message.
items:
description: A button in an in app feed message.
nullable: false
properties:
action:
description: The action to take when the button is clicked.
nullable: false
type: string
x-struct: null
x-validate: null
label:
description: The label of the button.
nullable: false
type: string
x-struct: null
x-validate: null
name:
description: The name of the button.
nullable: false
type: string
x-struct: null
x-validate: null
required:
- action
- label
- name
type: object
x-struct: null
x-validate: null
nullable: false
type: array
x-struct: null
x-validate: null
name:
description: The name of the button set in a message in an app feed.
nullable: false
type: string
x-struct: null
x-validate: null
type:
description: The type of block in a message in an app feed.
enum:
- button_set
nullable: false
type: string
x-struct: null
x-validate: null
required:
- type
- name
- buttons
title: MessageInAppFeedButtonSetBlock
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.MessageInAppFeedContent.ButtonSetBlock
x-validate: null
User:
additionalProperties: true
description: A [User](/concepts/users) represents an individual in your system who can receive notifications through Knock. Users are the most common recipients of notifications and are always referenced by your internal identifier.
example:
__typename: User
created_at: null
email: ian.malcolm@chaos.theory
id: user_id
name: Dr. Ian Malcolm
updated_at: '2024-05-22T12:00:00Z'
properties:
__typename:
description: The typename of the schema.
example: User
type: string
x-struct: null
x-validate: null
avatar:
description: A URL for the avatar of the user.
nullable: true
type: string
x-struct: null
x-validate: null
created_at:
description: The creation date of the user from your system.
format: date-time
nullable: true
type: string
x-struct: null
x-validate: null
email:
description: The primary email address for the user.
nullable: true
type: string
x-struct: null
x-validate: null
id:
description: The unique identifier of the user.
type: string
x-struct: null
x-validate: null
name:
description: Display name of the user.
nullable: true
type: string
x-struct: null
x-validate: null
phone_number:
description: The [E.164](https://www.twilio.com/docs/glossary/what-e164) phone number of the user (required for SMS channels).
nullable: true
type: string
x-struct: null
x-validate: null
timezone:
description: The timezone of the user. Must be a valid [tz database time zone string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Used for [recurring schedules](/concepts/schedules#scheduling-workflows-with-recurring-schedules-for-recipients).
nullable: true
type: string
x-struct: null
x-validate: null
updated_at:
description: The timestamp when the resource was last updated.
format: date-time
type: string
x-struct: null
x-validate: null
required:
- __typename
- id
- updated_at
title: User
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.User
x-validate: null
UserInAppFeedSettingsResponse:
description: The response for the user's feed settings.
example:
features:
branding_required: true
properties:
features:
description: Features configuration for the user's feed.
properties:
branding_required:
description: Whether branding is required for the user's feed.
type: boolean
x-struct: null
x-validate: null
required:
- branding_required
type: object
x-struct: null
x-validate: null
required:
- features
title: UserInAppFeedSettingsResponse
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.UserInAppFeedSettingsResponse
x-validate: null
MessageInAppFeedContentBlock:
description: A block in a message in an app feed.
example:
content: This is a message in an app feed
name: body
rendered: <p>This is a message in an app feed</p>
type: markdown
properties:
content:
description: The content of the block in a message in an app feed.
nullable: false
type: string
x-struct: null
x-validate: null
name:
description: The name of the block in a message in an app feed.
nullable: false
type: string
x-struct: null
x-validate: null
rendered:
description: The rendered HTML version of the content.
nullable: false
type: string
x-struct: null
x-validate: null
type:
description: The type of block in a message in an app feed.
enum:
- markdown
- text
nullable: false
type: string
x-struct: null
x-validate: null
required:
- type
- name
- rendered
- content
title: MessageInAppFeedContentBlock
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.MessageInAppFeedContent.ContentBlock
x-validate: null
securitySchemes:
BearerAuth:
bearerFormat: JWT
scheme: bearer
type: http