Knock Schedules API
A schedule is a per-recipient, timezone-aware configuration for when to invoke a workflow.
OpenAPI Specification
openapi: 3.0.0
info:
title: Knock Audiences Schedules API
version: '1.0'
description: An Audience is a segment of users.
servers:
- url: https://api.knock.app
variables: {}
security:
- BearerAuth: []
tags:
- description: A schedule is a per-recipient, timezone-aware configuration for when to invoke a workflow.
name: Schedules
paths:
/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:
- Schedules
x-ratelimit-tier: 4
/v1/schedules:
delete:
callbacks: {}
description: Permanently deletes one or more schedules identified by the provided schedule IDs. This operation cannot be undone.
operationId: deleteSchedules
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteSchedulesRequest'
description: Params
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SchedulesResponse'
description: OK
summary: Delete schedules
tags:
- Schedules
x-ratelimit-tier: 3
get:
callbacks: {}
description: Returns a paginated list of schedules for the current environment, filtered by workflow and optionally by recipients and tenant.
operationId: listSchedules
parameters:
- description: Filter by workflow key.
in: query
name: workflow
required: true
schema:
type: string
x-struct: null
x-validate: null
- description: Filter by recipient references.
in: query
name: recipients[]
required: false
schema:
description: A list of recipient references to filter by.
items:
$ref: '#/components/schemas/RecipientReference'
type: array
x-struct: null
x-validate: null
- description: Filter by tenant ID.
in: query
name: tenant
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 schedules
tags:
- Schedules
x-ratelimit-tier: 4
post:
callbacks: {}
description: Creates one or more schedules for a workflow with the specified recipients, timing, and data. Schedules can be one-time or recurring. This endpoint also handles [inline identifications](/managing-recipients/identifying-recipients#inline-identifying-recipients) for the `actor`, `recipient`, and `tenant` fields.
operationId: createSchedules
parameters: []
requestBody:
content:
application/json:
example:
data:
key: value
ending_at: null
recipients:
- user_123
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/CreateSchedulesRequest'
description: Params
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SchedulesResponse'
description: OK
summary: Create schedules
tags:
- Schedules
x-ratelimit-tier: 3
put:
callbacks: {}
description: Updates one or more existing schedules with new timing, data, or other properties. All specified schedule IDs will be updated with the same values. This endpoint also handles [inline identifications](/managing-recipients/identifying-recipients#inline-identifying-recipients) for the `actor`, `recipient`, and `tenant` fields.
operationId: updateSchedules
parameters: []
requestBody:
content:
application/json:
example:
actor: null
data:
key: value
ending_at: null
repeats:
- __typename: ScheduleRepeat
day_of_month: null
days:
- mon
- tue
- wed
- thu
- fri
- sat
- sun
frequency: daily
hours: null
interval: 1
minutes: null
schedule_ids:
- 123e4567-e89b-12d3-a456-426614174000
scheduled_at: null
tenant: acme_corp
schema:
$ref: '#/components/schemas/UpdateSchedulesRequest'
description: Params
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SchedulesResponse'
description: OK
summary: Update schedules
tags:
- Schedules
x-ratelimit-tier: 3
/v1/users/{user_id}/schedules:
get:
callbacks: {}
description: Returns a paginated list of schedules for a specific user, in descending order.
operationId: listUserSchedules
parameters:
- description: The user ID to list schedules for.
in: path
name: user_id
required: true
schema:
type: string
x-struct: null
x-validate: null
- description: The workflow key to filter schedules for.
in: query
name: workflow
required: false
schema:
type: string
x-struct: null
x-validate: null
- description: The tenant ID to filter schedules for.
in: query
name: tenant
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 user schedules
tags:
- Schedules
x-ratelimit-tier: 4
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
TenantRequest:
additionalProperties: true
description: A tenant to be set in the system. You can supply any additional properties on the tenant object.
example:
id: tenant_123
name: ACME Corp, Inc.
settings:
branding:
icon_url: https://example.com/icon.png
logo_url: https://example.com/logo.png
primary_color: '#000000'
primary_color_contrast: '#FFFFFF'
properties:
channel_data:
description: The channel data for the tenant.
oneOf:
- nullable: true
x-struct: null
x-validate: null
- $ref: '#/components/schemas/InlineChannelDataRequest'
x-struct: null
x-validate: null
id:
description: The unique identifier for the tenant.
type: string
x-struct: null
x-validate: null
name:
description: An optional name for the tenant.
nullable: true
type: string
x-struct: null
x-validate: null
preferences:
description: The preferences for the tenant.
oneOf:
- nullable: true
x-struct: null
x-validate: null
- $ref: '#/components/schemas/InlinePreferenceSetRequest'
x-struct: null
x-validate: null
settings:
description: The settings for the tenant. Includes branding and preference set.
properties:
branding:
description: The branding for the tenant.
properties:
icon_url:
description: The icon URL for the tenant. Must point to a valid image with an image MIME type.
nullable: true
type: string
x-struct: null
x-validate: null
logo_url:
description: The logo URL for the tenant. Must point to a valid image with an image MIME type.
nullable: true
type: string
x-struct: null
x-validate: null
primary_color:
description: The primary color for the tenant, provided as a hex value.
nullable: true
type: string
x-struct: null
x-validate: null
primary_color_contrast:
description: The primary color contrast for the tenant, provided as a hex value.
nullable: true
type: string
x-struct: null
x-validate: null
type: object
x-struct: null
x-validate: null
preference_set:
description: The preference set for the tenant. Used to override the default preference set.
oneOf:
- nullable: true
x-struct: null
x-validate: null
- $ref: '#/components/schemas/PreferenceSetRequest'
x-struct: null
x-validate: null
type: object
x-struct: null
x-validate: null
required:
- id
title: TenantRequest
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.TenantRequest
x-validate: null
Schedule:
description: A schedule represents a recurring workflow execution.
example:
__typename: Schedule
actor: null
data: null
id: 123e4567-e89b-12d3-a456-426614174000
inserted_at: '2021-01-01T00:00:00Z'
last_occurrence_at: null
next_occurrence_at: null
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'
repeats:
- __typename: ScheduleRepeat
day_of_month: null
days:
- mon
- tue
- wed
- thu
- fri
- sat
- sun
frequency: daily
hours: null
interval: 1
minutes: null
tenant: null
updated_at: '2021-01-01T00:00:00Z'
workflow: workflow_123
properties:
__typename:
description: The typename of the schema.
example: Schedule
type: string
x-struct: null
x-validate: null
actor:
description: A map of properties describing a user or an object to identify in Knock and mark as who or what performed the action.
oneOf:
- $ref: '#/components/schemas/Recipient'
- nullable: true
x-struct: null
x-validate: null
x-struct: null
x-validate: null
data:
additionalProperties: true
description: An optional map of data to pass into the workflow execution. There is a 10MB limit on the size of the full `data` payload. Any individual string value greater than 1024 bytes in length will be [truncated](/developer-tools/api-logs#log-truncation) in your logs.
nullable: true
type: object
x-struct: null
x-validate: null
id:
description: Unique identifier for the schedule.
format: uuid
type: string
x-struct: null
x-validate: null
inserted_at:
description: Timestamp when the resource was created.
format: date-time
type: string
x-struct: null
x-validate: null
last_occurrence_at:
description: The last occurrence of the schedule.
format: date-time
nullable: true
type: string
x-struct: null
x-validate: null
next_occurrence_at:
description: The next occurrence of the schedule.
format: date-time
nullable: true
type: string
x-struct: null
x-validate: null
recipient:
$ref: '#/components/schemas/Recipient'
repeats:
description: The repeat rule for the schedule.
items:
$ref: '#/components/schemas/ScheduleRepeatRule'
type: array
x-struct: null
x-validate: null
tenant:
description: The tenant to trigger the workflow for. Triggering with a tenant will use any tenant-level overrides associated with the tenant object, and all messages produced from workflow runs will be tagged with the tenant.
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
workflow:
description: The workflow the schedule is applied to.
type: string
x-struct: null
x-validate: null
required:
- id
- workflow
- recipient
- repeats
- inserted_at
- updated_at
title: Schedule
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.Schedule
x-validate: null
RecipientReference:
description: A reference to a recipient, either a user identifier (string) or an object reference (ID, collection).
example: user_123
oneOf:
- description: The ID of the user which is used as the reference for the recipient.
example: user_123
nullable: false
title: UserReference
type: string
x-struct: null
x-validate: null
- description: A reference to a recipient object.
example:
collection: projects
id: project_123
properties:
collection:
description: The collection the recipient object belongs to.
example: projects
nullable: false
type: string
x-struct: null
x-validate: null
id:
description: An identifier for the recipient object.
example: project_123
nullable: false
type: string
x-struct: null
x-validate: null
title: ObjectReference
type: object
x-struct: null
x-validate: null
title: RecipientReference
x-struct: Elixir.SwitchboardWeb.V1.Specs.RecipientReference
x-validate: null
InlinePreferenceSetRequest:
additionalProperties:
$ref: '#/components/schemas/PreferenceSetRequest'
description: Inline set preferences for a recipient, where the key is the preference set id. Preferences that are set inline will be merged into any existing preferences rather than replacing them.
example:
default:
categories:
transactional:
channel_types:
email: false
channel_types:
email: true
title: InlinePreferenceSetRequest
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.InlinePreferenceSetRequest
x-validate: null
InlineTenantRequest:
description: An request to set a tenant inline.
example:
id: tenant_1
name: Acme Corp, Inc.
oneOf:
- description: The unique identifier for the tenant.
type: string
x-struct: null
x-validate: null
- $ref: '#/components/schemas/TenantRequest'
title: InlineTenantRequest
x-struct: Elixir.SwitchboardWeb.V1.Specs.InlineTenantRequest
x-validate: null
CreateSchedulesRequest:
description: A request to create a schedule.
example:
data:
key: value
ending_at: null
recipients:
- user_123
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
properties:
actor:
description: A map of properties describing a user or an object to identify in Knock and mark as who or what performed the action.
oneOf:
- $ref: '#/components/schemas/RecipientRequest'
- nullable: true
x-struct: null
x-validate: null
type: object
x-struct: null
x-validate: null
data:
additionalProperties: true
description: An optional map of data to pass into the workflow execution. There is a 10MB limit on the size of the full `data` payload. Any individual string value greater than 1024 bytes in length will be [truncated](/developer-tools/api-logs#log-truncation) in your logs.
nullable: true
type: object
x-struct: null
x-validate: null
ending_at:
description: The ending date and time for the schedule.
format: date-time
nullable: true
type: string
x-struct: null
x-validate: null
recipients:
description: The recipients to set the schedule for. Limited to 100 recipients per request.
items:
$ref: '#/components/schemas/RecipientRequest'
type: array
x-struct: null
x-validate: null
repeats:
description: The repeat rule for the schedule.
items:
$ref: '#/components/schemas/ScheduleRepeatRule'
type: array
x-struct: null
x-validate: null
scheduled_at:
description: The starting date and time for the schedule.
format: date-time
nullable: true
type: string
x-struct: null
x-validate: null
tenant:
anyOf:
- $ref: '#/components/schemas/InlineTenantRequest'
- nullable: true
x-struct: null
x-validate: null
description: The tenant to trigger the workflow for. Triggering with a tenant will use any tenant-level overrides associated with the tenant object, and all messages produced from workflow runs will be tagged with the tenant.
x-struct: null
x-validate: null
workflow:
description: The key of the workflow.
nullable: false
type: string
x-struct: null
x-validate: null
required:
- workflow
- recipients
title: CreateSchedulesRequest
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.CreateSchedulesRequest
x-validate: null
MsTeamsTokenConnection:
description: Microsoft Teams token connection.
example:
ms_teams_channel_id: 123e4567-e89b-12d3-a456-426614174000
ms_teams_team_id: 123e4567-e89b-12d3-a456-426614174000
ms_teams_tenant_id: null
ms_teams_user_id: null
properties:
ms_teams_channel_id:
description: Microsoft Teams channel ID.
format: uuid
nullable: true
type: string
x-struct: null
x-validate: null
ms_teams_team_id:
description: Microsoft Teams team ID.
format: uuid
nullable: true
type: string
x-struct: null
x-validate: null
ms_teams_tenant_id:
description: Microsoft Teams tenant ID.
format: uuid
nullable: true
type: string
x-struct: null
x-validate: null
ms_teams_user_id:
description: Microsoft Teams user ID.
format: uuid
nullable: true
type: string
x-struct: null
x-validate: null
title: MsTeamsTokenConnection
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.MsTeamsChannelData.TokenConnection
x-validate: null
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
MsTeamsIncomingWebhookConnection:
description: Microsoft Teams incoming webhook connection.
example:
incoming_webhook:
url: https://example.com/webhook
properties:
incoming_webhook:
description: Microsoft Teams incoming webhook.
properties:
url:
description: Microsoft Teams 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: MsTeamsIncomingWebhookConnection
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.MsTeamsChannelData.IncomingWebhookConnection
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
nullable: false
type: string
x-struct: null
x-validate: null
nullable: false
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
InlineIdentifyObjectRequest:
additionalProperties: true
description: A custom [Object](/concepts/objects) entity which belongs to a collection.
example:
collection: projects
id: project_1
name: My project
properties:
channel_data:
description: An optional set of [channel data](/managing-recipients/setting-channel-data) for the object. This is a list of `ChannelData` objects.
oneOf:
- $ref: '#/components/schemas/InlineChannelDataRequest'
- nullable: true
x-struct: null
x-validate: null
x-struct: null
x-validate: null
collection:
description: The collection this object belongs to.
nullable: false
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.
nullable: false
type: string
x-struct: null
x-validate: null
name:
description: An optional name for the object.
nullable: true
type: string
x-struct: null
x-validate: null
preferences:
description: An optional set of [preferences](/concepts/preferences) for the object.
oneOf:
- $ref: '#/components/schemas/InlinePreferenceSetRequest'
- nullable: true
x-struct: null
x-validate: null
x-struct: null
x-validate: null
required:
- id
- collection
title: InlineIdentifyObjectRequest
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.InlineIdentifyObjectRequest
x-validate: null
PreferenceSetWorkflowCategorySetting:
description: Workflow or category preferences within a preference set
example:
channel_types:
email: false
channels:
aef6e715-df82-4ab6-b61e-b743e249f7b6: true
oneOf:
- example: false
type: boolean
x-struct: null
x-validate: null
- description: The settings object for a workflow or category, where you can specify channel types or conditions.
example:
channel_types:
email: false
channels:
aef6e715-df82-4ab6-b61e-b743e249f7b6: true
conditions: null
properties:
channel_types:
anyOf:
- $ref: '#/components/schemas/PreferenceSetChannelTypes'
- nullable: true
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'
- nullable: true
x-struct: null
x-validate: null
description: An object where the key is the channel ID and the values are the preference settings for tha
# --- truncated at 32 KB (70 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/knock/refs/heads/main/openapi/knock-schedules-api-openapi.yml