Knock Schedules API

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: [email protected]
            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: [email protected]
          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: [email protected]
        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: [email protected]
        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