Create, list, update, and delete workflow Schedules. Schedules fire workflows at one-off or recurring times for specific recipients with timezone and repeat-rule support.
openapi: 3.0.3
info:
title: Knock Schedules API
version: '1.0'
description: Create, list, update, and delete workflow Schedules. Schedules let you fire workflows at one-off or recurring
times for specific recipients with timezone and repeat-rule support.
contact:
name: Knock
url: https://knock.app
license:
name: Proprietary
servers:
- url: https://api.knock.app
variables: {}
security:
- BearerAuth: []
paths:
/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/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
- Bulk operations
x-ratelimit-tier: 1
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: Knock API key as a Bearer token. Use a public key (pk_...) for client-side requests or a secret key (sk_...)
for server-side.
schemas:
ListSchedulesResponse:
description: A response containing a list of schedules.
example:
entries:
- __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
page_info:
__typename: PageInfo
after: null
before: null
page_size: 25
properties:
entries:
description: A list of schedules.
items:
$ref: '#/components/schemas/Schedule'
type: array
x-struct: null
x-validate: null
page_info:
$ref: '#/components/schemas/PageInfo'
required:
- entries
- page_info
title: ListSchedulesResponse
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.ListSchedulesResponse
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
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
ScheduleRepeatRule:
description: The repeat rule for the schedule.
example:
__typename: ScheduleRepeat
day_of_month: null
days:
- mon
- tue
- wed
- thu
- fri
- sat
- sun
frequency: daily
hours: null
interval: 1
minutes: null
properties:
__typename:
description: The typename of the schema.
example: ScheduleRepeat
type: string
x-struct: null
x-validate: null
day_of_month:
description: The day of the month to repeat the schedule.
example: 1
nullable: true
type: integer
x-struct: null
x-validate: null
days:
description: The days of the week to repeat the schedule.
example:
- mon
- tue
- wed
- thu
- fri
items:
description: An identifier for a day of the week.
enum:
- mon
- tue
- wed
- thu
- fri
- sat
- sun
type: string
x-struct: null
x-validate: null
nullable: true
type: array
x-struct: null
x-validate: null
frequency:
description: The frequency of the schedule.
enum:
- daily
- weekly
- monthly
- hourly
example: daily
type: string
x-struct: null
x-validate: null
hours:
description: The hour of the day to repeat the schedule.
example: 0
nullable: true
type: integer
x-struct: null
x-validate: null
interval:
default: 1
description: The interval of the schedule.
example: 1
type: integer
x-struct: null
x-validate: null
minutes:
description: The minute of the hour to repeat the schedule.
example: 0
nullable: true
type: integer
x-struct: null
x-validate: null
required:
- frequency
title: ScheduleRepeatRule
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.ScheduleRepeatRule
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
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
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
DeleteSchedulesRequest:
description: A request to delete a schedule.
example:
schedule_ids:
- 123e4567-e89b-12d3-a456-426614174000
properties:
schedule_ids:
description: A list of schedule IDs.
items:
description: Unique identifier for the schedule.
type: string
x-struct: null
x-validate: null
type: array
x-struct: null
x-validate: null
required:
- schedule_ids
title: DeleteSchedulesRequest
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.DeleteSchedulesRequest
x-validate: null
UpdateSchedulesRequest:
description: A request to update a schedule.
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
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/RecipientReference'
- 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
ending_at:
description: The ending date and time for the schedule.
format: date-time
nullable: true
type: string
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
schedule_ids:
description: A list of schedule IDs.
items:
description: Unique identifier for the schedule.
format: uuid
type: string
x-struct: null
x-validate: null
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
required:
- schedule_ids
title: UpdateSchedulesRequest
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.UpdateSchedulesRequest
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
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
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
- nullable: true
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'
- 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
# --- truncated at 32 KB (78 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/knock-app/refs/heads/main/openapi/knock-schedules-api-openapi.yml