{ "components": { "responses": {}, "schemas": { "ListUsersResponse": { "description": "A paginated list of users.", "example": { "entries": [ { "__typename": "User", "created_at": null, "email": "ian.malcolm@chaos.theory", "id": "user_id", "name": "Dr. Ian Malcolm", "updated_at": "2024-05-22T12:00:00Z" } ], "page_info": { "__typename": "PageInfo", "after": null, "before": null, "page_size": 25 } }, "properties": { "entries": { "description": "A list of users.", "items": { "$ref": "#/components/schemas/User" }, "type": "array", "x-struct": null, "x-validate": null }, "page_info": { "$ref": "#/components/schemas/PageInfo" } }, "title": "ListUsersResponse", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.ListUsersResponse", "x-validate": null }, "ChannelData": { "description": "Channel data for a given channel type.", "example": { "__typename": "ChannelData", "channel_id": "123e4567-e89b-12d3-a456-426614174000", "data": { "devices": [ { "locale": null, "timezone": null, "token": "device_1" } ], "tokens": [ "push_token_1" ] } }, "properties": { "__typename": { "description": "The typename of the schema.", "example": "ChannelData", "type": "string", "x-struct": null, "x-validate": null }, "channel_id": { "description": "The unique identifier for the channel.", "format": "uuid", "type": "string", "x-struct": null, "x-validate": null }, "data": { "description": "Channel data for a given channel type.", "oneOf": [ { "$ref": "#/components/schemas/PushChannelDataFull" }, { "$ref": "#/components/schemas/AWSSNSPushChannelDataFull" }, { "$ref": "#/components/schemas/OneSignalChannelDataPlayerIdsOnly" }, { "$ref": "#/components/schemas/SlackChannelData" }, { "$ref": "#/components/schemas/MsTeamsChannelData" }, { "$ref": "#/components/schemas/DiscordChannelData" } ], "type": "object", "x-struct": null, "x-validate": null }, "provider": { "description": "The type of provider.", "enum": [ "push_fcm", "push_apns", "push_aws_sns", "push_expo", "push_one_signal", "chat_slack", "chat_ms_teams", "chat_discord", "http_knock_webhook" ], "example": "push_fcm", "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "channel_id", "data", "__typename" ], "title": "ChannelData", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.ChannelData", "x-validate": null }, "AddAudienceMembersRequest": { "description": "A request to add a list of audience members.", "example": { "members": [ { "tenant": "ingen_isla_nublar", "user": { "email": "ellie@ingen.net", "id": "dr_sattler", "name": "Dr. Ellie Sattler" } } ] }, "properties": { "members": { "description": "A list of audience members to add. You can add up to 1,000 members per request.", "items": { "$ref": "#/components/schemas/AudienceMemberRequest" }, "nullable": false, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "members" ], "title": "AddAudienceMembersRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.AddAudienceMembersRequest", "x-validate": null }, "TriggerWorkflowResponse": { "description": "The response from triggering a workflow.", "example": { "workflow_run_id": "123e4567-e89b-12d3-a456-426614174000" }, "properties": { "workflow_run_id": { "description": "This value allows you to track individual messages associated with this trigger request.", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid", "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "workflow_run_id" ], "title": "TriggerWorkflowResponse", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.TriggerWorkflowResponse", "x-validate": null }, "Subscription": { "description": "A subscription object.", "example": { "__typename": "Subscription", "inserted_at": "2021-01-01T00:00:00Z", "object": { "__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" }, "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": "2021-01-01T00:00:00Z" }, "properties": { "__typename": { "description": "The typename of the schema.", "example": "Subscription", "type": "string", "x-struct": null, "x-validate": null }, "inserted_at": { "description": "Timestamp when the resource was created.", "example": "2021-01-01T00:00:00Z", "format": "date-time", "type": "string", "x-struct": null, "x-validate": null }, "object": { "$ref": "#/components/schemas/Object" }, "properties": { "additionalProperties": true, "description": "The custom properties associated with the subscription relationship.", "nullable": true, "type": "object", "x-struct": null, "x-validate": null }, "recipient": { "$ref": "#/components/schemas/Recipient" }, "updated_at": { "description": "The timestamp when the resource was last updated.", "example": "2021-01-01T00:00:00Z", "format": "date-time", "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "__typename", "recipient", "object", "inserted_at", "updated_at" ], "title": "Subscription", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.Subscription", "x-validate": null }, "ListUserPreferenceSetsResponse": { "description": "A list of preference sets for the user.", "example": [ { "categories": { "marketing": false, "transactional": { "channel_types": { "email": false } } }, "channel_types": { "email": true, "push": false, "sms": { "conditions": [ { "argument": "US", "operator": "equal_to", "variable": "recipient.country_code" } ] } }, "commercial_subscribed": true, "id": "default", "workflows": null } ], "items": { "$ref": "#/components/schemas/PreferenceSet" }, "title": "ListUserPreferenceSetsResponse", "type": "array", "x-struct": null, "x-validate": null }, "ListWorkflowRecipientRunsResponse": { "description": "A paginated list of workflow recipient runs.", "example": { "items": [ { "__typename": "WorkflowRecipientRun", "actor": "user_456", "error_count": 0, "id": "550e8400-e29b-41d4-a716-446655440000", "inserted_at": "2025-01-01T00:00:00Z", "recipient": "user_123", "status": "completed", "tenant": "tenant_abc", "trigger_source": { "cancellation_key": "comment-123-user-456", "type": "api" }, "updated_at": "2025-01-01T00:05:00Z", "workflow": "comment-created", "workflow_run_id": "660e8400-e29b-41d4-a716-446655440000" } ], "page_info": { "__typename": "PageInfo", "after": null, "before": null, "page_size": 25 } }, "properties": { "items": { "description": "A list of workflow recipient runs.", "items": { "$ref": "#/components/schemas/WorkflowRecipientRun" }, "type": "array", "x-struct": null, "x-validate": null }, "page_info": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "items", "page_info" ], "title": "ListWorkflowRecipientRunsResponse", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.ListWorkflowRecipientRunsResponse", "x-validate": null }, "PreferenceSetWorkflowCategorySettingObject": { "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 that channel ID.", "x-struct": null, "x-validate": null }, "conditions": { "description": "A list of conditions to apply to a channel type.", "items": { "$ref": "#/components/schemas/Condition" }, "nullable": true, "type": "array", "x-struct": null, "x-validate": null } }, "title": "PreferenceSetWorkflowCategorySettingObject", "type": "object", "x-struct": null, "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 }, "TriggerWorkflowRequest": { "description": "A request to trigger a notification workflow.", "example": { "actor": "mr_dna", "cancellation_key": "isla_nublar_incident_1993", "data": { "affected_areas": [ "visitor_center", "raptor_pen", "trex_paddock" ], "attraction_id": "paddock_rex_01", "evacuation_protocol": "active", "message": "Life finds a way", "severity": "critical", "system_status": "fences_failing" }, "recipients": [ "dr_grant", "dr_sattler", "dr_malcolm" ], "tenant": "ingen_isla_nublar" }, "properties": { "actor": { "anyOf": [ { "$ref": "#/components/schemas/RecipientRequest" }, { "nullable": true, "x-struct": null, "x-validate": null } ], "description": "A map of properties describing a user or an object to identify in Knock and mark as who or what performed the action.", "x-struct": null, "x-validate": null }, "cancellation_key": { "description": "An optional key that is used to reference a specific workflow trigger request when issuing a [workflow cancellation](/send-notifications/canceling-workflows) request. Must be provided while triggering a workflow in order to enable subsequent cancellation. Should be unique across trigger requests to avoid unintentional cancellations.", "nullable": true, "type": "string", "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 }, "recipients": { "description": "The recipients to trigger the workflow for. Can inline identify users, objects, or use a list of user IDs. Limited to 1,000 recipients.", "items": { "$ref": "#/components/schemas/RecipientRequest" }, "type": "array", "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": [ "recipients" ], "title": "TriggerWorkflowRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.TriggerWorkflowRequest", "x-validate": null }, "BulkIdentifyUsersRequest": { "description": "A request to identify a list of users.", "example": { "users": [ { "email": "jane@ingen.net", "id": "user_1", "name": "Jane Doe", "timezone": "America/New_York" } ] }, "properties": { "users": { "description": "A list of users.", "items": { "$ref": "#/components/schemas/InlineIdentifyUserRequest" }, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "users" ], "title": "BulkIdentifyUsersRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.BulkIdentifyUsersRequest", "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 }, "MessageContents": { "description": "The content of a message.", "example": { "__typename": "MessageContent", "data": { "__typename": "MessageSmsContent", "body": "URGENT: Power failure detected in perimeter fencing. Backup generators failed to engage. Technical team dispatched. Maintain lockdown protocols.", "to": "+15553982647" }, "inserted_at": "1993-06-11T20:30:00Z", "message_id": "2w3YUpTTOxuDvZFji8OMsKrG176" }, "properties": { "__typename": { "description": "The typename of the schema.", "example": "MessageContent", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "data": { "description": "Content data specific to the channel type.", "nullable": false, "oneOf": [ { "$ref": "#/components/schemas/MessageEmailContent" }, { "$ref": "#/components/schemas/MessageSmsContent" }, { "$ref": "#/components/schemas/MessagePushContent" }, { "$ref": "#/components/schemas/MessageChatContent" }, { "$ref": "#/components/schemas/MessageInAppFeedContent" } ], "type": "object", "x-struct": null, "x-validate": null }, "inserted_at": { "description": "Timestamp when the message content was created.", "example": "2021-01-01T00:00:00Z", "format": "date-time", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "message_id": { "description": "The unique identifier for the message content.", "example": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "nullable": false, "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "__typename", "message_id", "data", "inserted_at" ], "title": "MessageContents", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.MessageContents", "x-validate": null }, "ListAudienceMembersResponse": { "description": "A paginated list of audience members.", "example": { "entries": [ { "__typename": "AudienceMember", "added_at": "1993-06-10T14:30:00Z", "tenant": "ingen_isla_nublar", "user": { "__typename": "User", "created_at": null, "email": "alan.grant@dig.site.mt", "id": "dr_grant", "name": "Dr. Alan Grant", "updated_at": "1993-06-09T08:15:00Z" }, "user_id": "dr_grant" } ], "page_info": { "__typename": "PageInfo", "after": null, "before": null, "page_size": 25 } }, "properties": { "entries": { "description": "A list of audience members.", "items": { "$ref": "#/components/schemas/AudienceMember" }, "type": "array", "x-struct": null, "x-validate": null }, "page_info": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "entries", "page_info" ], "title": "ListAudienceMembersResponse", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.ListAudienceMembersResponse", "x-validate": null }, "BulkDeleteSubscriptionsRequest": { "description": "A request to delete subscriptions for many groups of 1 subscribed-to object, N subscriber recipients.", "example": { "subscriptions": [ { "id": "subscribed-to-object-1", "recipients": [ { "collection": "projects", "id": "subscriber-project-1" }, "subscriber-user-1" ] }, { "id": "subscribed-to-object-2", "recipients": [ "subscriber-user-2" ] } ] }, "properties": { "subscriptions": { "description": "A nested list of subscriptions.", "items": { "description": "A list of subscriptions. 1 subscribed-to id, and N subscriber recipients.", "properties": { "id": { "description": "Unique identifier for the object.", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "recipients": { "description": "The recipients of the subscription. You can subscribe up to 100 recipients to an object at a time.", "items": { "$ref": "#/components/schemas/RecipientReference" }, "nullable": false, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "id", "recipients" ], "type": "object", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "subscriptions" ], "title": "BulkDeleteSubscriptionsRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.BulkDeleteSubscriptionsRequest", "x-validate": null }, "InlineChannelDataRequest": { "additionalProperties": { "description": "Channel data for a given channel type.", "nullable": false, "oneOf": [ { "$ref": "#/components/schemas/PushChannelDataTokensOnly" }, { "$ref": "#/components/schemas/PushChannelDataDevicesOnly" }, { "$ref": "#/components/schemas/AWSSNSPushChannelDataTargetARNsOnly" }, { "$ref": "#/components/schemas/AWSSNSPushChannelDataDevicesOnly" }, { "$ref": "#/components/schemas/OneSignalChannelDataPlayerIdsOnly" }, { "$ref": "#/components/schemas/SlackChannelData" }, { "$ref": "#/components/schemas/MsTeamsChannelData" }, { "$ref": "#/components/schemas/DiscordChannelData" } ], "x-struct": null, "x-validate": null }, "description": "A request to set channel data for a type of channel inline.", "example": { "97c5837d-c65c-4d54-aa39-080eeb81c69d": { "tokens": [ "push_token_xxx" ] } }, "title": "InlineChannelDataRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.InlineChannelDataRequest", "x-validate": null }, "MessageEmailContent": { "description": "The content of an email message.", "example": { "__typename": "MessageEmailContent", "bcc": "security@ingen.net", "cc": "operations@isla-nublar.com", "from": "welcome@isla-nublar.com", "html_body": "

Welcome to Isla Nublar

Dear visitor,

We're excited to confirm your upcoming tour of our biological preserve. Your safety is our primary concern.

Please review the safety protocols before arrival.

Remember: All specimens are accounted for and contained.

", "reply_to": "visitor.center@isla-nublar.com", "subject_line": "Tour Confirmation: Isla Nublar Biological Preserve", "text_body": "Welcome to Isla Nublar\n\nDear visitor,\n\nWe're excited to confirm your upcoming tour of our biological preserve. Your safety is our primary concern.\n\nPlease review the safety protocols before arrival: https://example.com/safety\n\nRemember: All specimens are accounted for and contained.", "to": "dr.grant@dig.site.mt" }, "properties": { "__typename": { "description": "The typename of the schema.", "example": "MessageEmailContent", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "bcc": { "description": "The BCC email addresses.", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "cc": { "description": "The CC email addresses.", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "from": { "description": "The sender's email address.", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "html_body": { "description": "The HTML body of the email message.", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "reply_to": { "description": "The reply-to email address.", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "subject_line": { "description": "The subject line of the email message.", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "text_body": { "description": "The text body of the email message.", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "to": { "description": "The recipient's email address.", "nullable": false, "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "__typename", "html_body", "text_body", "subject_line", "from", "to" ], "title": "MessageEmailContent", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.MessageEmailContent", "x-validate": null }, "Notify Response": { "description": "The response from triggering a workflow.", "example": { "result_id": "wf_1234567890abcdef" }, "properties": { "result_id": { "description": "This value allows you to track individual messages associated with this trigger request.", "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "result_id" ], "title": "Notify Response", "type": "object", "x-struct": "Elixir.SwitchboardWeb.Specs.Notify.Responses.NotifyResponse", "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 }, "PreferenceSetChannelTypes": { "description": "Channel type preferences.", "example": { "email": true, "sms": { "conditions": [ { "argument": "US", "operator": "equal_to", "variable": "recipient.country_code" } ] } }, "properties": { "chat": { "description": "Whether the channel type is enabled for the preference set.", "oneOf": [ { "type": "boolean", "x-struct": null, "x-validate": null }, { "$ref": "#/components/schemas/PreferenceSetChannelTypeSetting" } ], "x-struct": null, "x-validate": null }, "email": { "description": "Whether the channel type is enabled for the preference set.", "oneOf": [ { "type": "boolean", "x-struct": null, "x-validate": null }, { "$ref": "#/components/schemas/PreferenceSetChannelTypeSetting" } ], "x-struct": null, "x-validate": null }, "http": { "description": "Whether the channel type is enabled for the preference set.", "oneOf": [ { "type": "boolean", "x-struct": null, "x-validate": null }, { "$ref": "#/components/schemas/PreferenceSetChannelTypeSetting" } ], "x-struct": null, "x-validate": null }, "in_app_feed": { "description": "Whether the channel type is enabled for the preference set.", "oneOf": [ { "type": "boolean", "x-struct": null, "x-validate": null }, { "$ref": "#/components/schemas/PreferenceSetChannelTypeSetting" } ], "x-struct": null, "x-validate": null }, "push": { "description": "Whether the channel type is enabled for the preference set.", "oneOf": [ { "type": "boolean", "x-struct": null, "x-validate": null }, { "$ref": "#/components/schemas/PreferenceSetChannelTypeSetting" } ], "x-struct": null, "x-validate": null }, "sms": { "description": "Whether the channel type is enabled for the preference set.", "oneOf": [ { "type": "boolean", "x-struct": null, "x-validate": null }, { "$ref": "#/components/schemas/PreferenceSetChannelTypeSetting" } ], "x-struct": null, "x-validate": null } }, "title": "PreferenceSetChannelTypes", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.PreferenceSetChannelTypes", "x-validate": null }, "MessageEvent": { "description": "A message event. Occurs when a message [delivery or engagement status](/send-notifications/message-statuses) changes.", "example": { "__typename": "MessageEvent", "data": null, "id": "2FVHPWxRqNuXQ9krvNP5A6Z4qXe", "inserted_at": "2021-01-01T00:00:00Z", "recipient": "user_123", "type": "message.sent" }, "properties": { "__typename": { "description": "The typename of the schema.", "example": "MessageEvent", "type": "string", "x-struct": null, "x-validate": null }, "data": { "additionalProperties": true, "description": "The data associated with the message event. Only present for some event types.", "nullable": true, "type": "object", "x-struct": null, "x-validate": null }, "id": { "description": "The unique identifier for the message event.", "example": "2FVHPWxRqNuXQ9krvNP5A6Z4qXe", "type": "string", "x-struct": null, "x-validate": null }, "inserted_at": { "description": "Timestamp when the event was created.", "example": "2021-01-01T00:00:00Z", "format": "date-time", "type": "string", "x-struct": null, "x-validate": null }, "recipient": { "$ref": "#/components/schemas/RecipientReference" }, "type": { "description": "The type of event that occurred.", "enum": [ "message.archived", "message.bounced", "message.created", "message.delivered", "message.delivery_attempted", "message.interacted", "message.link_clicked", "message.not_sent", "message.queued", "message.read", "message.seen", "message.sent", "message.unarchived", "message.undelivered", "message.unread", "message.unseen" ], "example": "message.sent", "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "__typename", "id", "inserted_at", "recipient", "type" ], "title": "MessageEvent", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.MessageEvent", "x-validate": null }, "SuccessResponse": { "description": "A response indicating the operation was successful.", "example": { "ok": "ok" }, "properties": { "ok": { "description": "OK response.", "example": "ok", "type": "string", "x-struct": null, "x-validate": null } }, "title": "SuccessResponse", "type": "object", "x-struct": null, "x-validate": null }, "GuideActionRequest": { "description": "A request to trigger a guide action.", "example": { "channel_id": "123e4567-e89b-12d3-a456-426614174000", "content": { "body": "Limited spots available for today's behind-the-scenes DNA extraction demonstration.", "title": "DNA Lab Tour Available" }, "data": { "next_time": "14:30", "spots_left": 8, "tour_id": "dna_lab_tour" }, "guide_id": "7e9dc78c-b3b1-4127-a54e-71f1899b831a", "guide_key": "tour_notification", "guide_step_ref": "lab_tours", "is_final": false, "metadata": { "cta": "Reserve Spot", "theme": "amber", "type": "banner" }, "tenant": "ingen_isla_nublar" }, "properties": { "channel_id": { "description": "The unique identifier for the channel.", "format": "uuid", "type": "string", "x-struct": null, "x-validate": null }, "content": { "additionalProperties": true, "description": "The content of the guide.", "type": "object", "x-struct": null, "x-validate": null }, "data": { "additionalProperties": true, "description": "The data of the guide.", "type": "object", "x-struct": null, "x-validate": null }, "guide_id": { "description": "The unique identifier for the guide.", "format": "uuid", "type": "string", "x-struct": null, "x-validate": null }, "guide_key": { "description": "The key of the guide.", "type": "string", "x-struct": null, "x-validate": null }, "guide_step_ref": { "description": "The step reference of the guide.", "type": "string", "x-struct": null, "x-validate": null }, "is_final": { "description": "Whether the guide is final.", "type": "boolean", "x-struct": null, "x-validate": null }, "metadata": { "additionalProperties": true, "description": "The metadata of the guide.", "type": "object", "x-struct": null, "x-validate": null }, "tenant": { "description": "The tenant ID of the guide.", "nullable": true, "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "channel_id", "guide_id", "guide_key", "guide_step_ref" ], "title": "GuideActionRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.Guides.Requests.GuideActionRequest", "x-validate": null }, "BulkUpsertSubscriptionsRequest": { "description": "A request to upsert subscriptions for many groups of 1 subscribed-to object, N subscriber recipients.", "example": { "subscriptions": [ { "id": "project-1", "properties": null, "recipients": [ { "id": "user_1" } ] } ] }, "properties": { "subscriptions": { "description": "A nested list of subscriptions.", "items": { "description": "A list of subscriptions. 1 subscribed-to id, and N subscriber recipients.", "properties": { "id": { "description": "Unique identifier for the object.", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "properties": { "additionalProperties": true, "description": "The custom properties associated with the subscription relationship.", "nullable": true, "type": "object", "x-struct": null, "x-validate": null }, "recipients": { "description": "The recipients of the subscription. You can subscribe up to 100 recipients to an object at a time.", "items": { "$ref": "#/components/schemas/RecipientRequest" }, "nullable": false, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "id", "recipients" ], "type": "object", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "subscriptions" ], "title": "BulkUpsertSubscriptionsRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.BulkUpsertSubscriptionsRequest", "x-validate": null }, "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 }, "BatchMessagesStatusRequest": { "description": "Request to update the status of multiple messages in batch.", "example": { "message_ids": [ "2w3YUpTTOxuDvZFji8OMsKrG176", "2w3YVRbPXMIh8Zq6oBFcVDA5xes" ] }, "properties": { "message_ids": { "description": "The message IDs to update the status of.", "items": { "description": "The message ID to update the status of.", "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "message_ids" ], "title": "BatchMessagesStatusRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.BatchMessagesStatusRequest", "x-validate": null }, "MessageChatContent": { "description": "The content of a chat message.", "example": { "__typename": "MessageChatContent", "connection": { "access_token": null, "channel_id": "123e4567-e89b-12d3-a456-426614174000", "user_id": "dr_malcolm" }, "metadata": { "incident_id": "shutdown-june-1993", "initiated_by": "ray_arnold", "priority": "critical" }, "template": { "blocks": [ { "content": "*SYSTEM ALERT*: Multiple security systems offline", "name": "header", "type": "markdown" }, { "content": "The following systems are currently non-operational:\n- Main power grid\n- Perimeter fencing (sectors 3-12)\n- Automated tour vehicles\n- Phone systems", "name": "details", "type": "text" }, { "content": "Initiating full system shutdown and reboot sequence. Hold onto your butts.", "name": "action", "type": "text" } ], "json_content": null, "summary": "System Failure Alert" } }, "properties": { "__typename": { "description": "The typename of the schema.", "example": "MessageChatContent", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "connection": { "additionalProperties": true, "description": "The channel data connection from the recipient to the underlying provider.", "nullable": false, "type": "object", "x-struct": null, "x-validate": null }, "metadata": { "additionalProperties": true, "description": "Additional metadata associated with the chat message.", "example": { "foo": "bar" }, "nullable": true, "type": "object", "x-struct": null, "x-validate": null }, "template": { "description": "The template structure for the chat message.", "nullable": false, "properties": { "blocks": { "description": "The blocks of the message in a chat.", "items": { "$ref": "#/components/schemas/Block" }, "nullable": true, "type": "array", "x-struct": null, "x-validate": null }, "json_content": { "additionalProperties": true, "description": "The JSON content of the message.", "nullable": true, "type": "object", "x-struct": null, "x-validate": null }, "summary": { "description": "The summary of the chat message.", "nullable": true, "type": "string", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null } }, "required": [ "__typename", "template", "connection" ], "title": "MessageChatContent", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.MessageChatContent", "x-validate": null }, "PreferenceSetRequestCategories": { "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 }, "BatchGetMessageContentsResponse": { "description": "A list of `MessageContents`", "example": [ { "__typename": "MessageContent", "data": { "__typename": "MessageSmsContent", "body": "URGENT: Power failure detected in perimeter fencing. Backup generators failed to engage. Technical team dispatched. Maintain lockdown protocols.", "to": "+15553982647" }, "inserted_at": "1993-06-11T20:30:00Z", "message_id": "2w3YUpTTOxuDvZFji8OMsKrG176" } ], "items": { "$ref": "#/components/schemas/MessageContents" }, "title": "BatchGetMessageContentsResponse", "type": "array", "x-struct": null, "x-validate": null }, "DiscordChannelData": { "description": "Discord channel data.", "example": { "connections": [ { "channel_id": "123456789012345678" } ] }, "properties": { "connections": { "description": "List of Discord channel connections.", "items": { "description": "Discord channel connection, either a channel connection or an incoming webhook connection.", "oneOf": [ { "$ref": "#/components/schemas/DiscordChannelConnection" }, { "$ref": "#/components/schemas/DiscordIncomingWebhookConnection" } ], "type": "object", "x-struct": null, "x-validate": null }, "nullable": false, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "connections" ], "title": "DiscordChannelData", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.DiscordChannelData", "x-validate": null }, "WorkflowRecipientRunTriggerSource": { "description": "Describes how the workflow was triggered.", "example": { "cancellation_key": "comment-123-user-456", "type": "api" }, "properties": { "audience_key": { "description": "The key of the audience that triggered the workflow.", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "cancellation_key": { "description": "The cancellation key provided when the workflow was triggered via the API.", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "schedule_id": { "description": "The ID of the schedule that triggered the workflow.", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "type": { "description": "The type of trigger source. One of `api`, `audience`, `schedule`, `broadcast`, `workflow_step`, `integration`, or `rehearsal`.", "enum": [ "api", "audience", "schedule", "broadcast", "workflow_step", "integration", "rehearsal" ], "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "type" ], "title": "WorkflowRecipientRunTriggerSource", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.WorkflowRecipientRunTriggerSource", "x-validate": null }, "BulkDeleteUsersRequest": { "description": "A request to delete users in bulk.", "example": { "user_ids": [ "user_1", "user_2" ] }, "properties": { "user_ids": { "description": "A list of user IDs.", "items": { "description": "The unique identifier of the user.", "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "user_ids" ], "title": "BulkDeleteUsersRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.BulkDeleteUsersRequest", "x-validate": null }, "ListSubscriptionsResponse": { "description": "A response containing a list of subscriptions.", "example": { "entries": [ { "__typename": "Subscription", "inserted_at": "2021-01-01T00:00:00Z", "object": { "__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" }, "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": "2021-01-01T00:00:00Z" } ], "page_info": { "__typename": "PageInfo", "after": null, "before": null, "page_size": 25 } }, "properties": { "entries": { "description": "A list of subscriptions.", "items": { "$ref": "#/components/schemas/Subscription" }, "type": "array", "x-struct": null, "x-validate": null }, "page_info": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "entries", "page_info" ], "title": "ListSubscriptionsResponse", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.ListSubscriptionsResponse", "x-validate": null }, "MsTeamsAuthCheckResponse": { "description": "The response from a Microsoft Teams auth check request.", "example": { "connection": { "ok": true } }, "properties": { "connection": { "description": "A Microsoft Teams connection object.", "properties": { "ok": { "description": "Whether the Microsoft Teams connection is valid.", "nullable": false, "type": "boolean", "x-struct": null, "x-validate": null }, "reason": { "description": "The reason for the Microsoft Teams connection if it is not valid.", "nullable": true, "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "ok" ], "type": "object", "x-struct": null, "x-validate": null } }, "required": [ "connection" ], "title": "MsTeamsAuthCheckResponse", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.MsTeamsAuthCheckResponse", "x-validate": null }, "SlackAuthCheckResponse": { "description": "The response from a Slack auth check request.", "example": { "connection": { "ok": true } }, "properties": { "connection": { "description": "A Slack connection object.", "properties": { "ok": { "description": "Whether the Slack connection is valid.", "nullable": false, "type": "boolean", "x-struct": null, "x-validate": null }, "reason": { "description": "The reason for the Slack connection if it is not valid.", "nullable": true, "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "ok" ], "type": "object", "x-struct": null, "x-validate": null } }, "required": [ "connection" ], "title": "SlackAuthCheckResponse", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.SlackAuthCheckResponse", "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 }, "BatchMessagesInteractedRequest": { "description": "A request to batch mark messages as interacted with.", "example": { "message_ids": [ "1jNaXzB2RZX3LY8wVQnfCKyPnv7" ], "metadata": { "key": "value" } }, "properties": { "message_ids": { "description": "The message IDs to batch mark as interacted with.", "items": { "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null }, "metadata": { "additionalProperties": true, "description": "Metadata about the interaction.", "example": { "key": "value" }, "nullable": true, "type": "object", "x-struct": null, "x-validate": null } }, "required": [ "message_ids" ], "title": "BatchMessagesInteractedRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.BatchMessagesInteractedRequest", "x-validate": null }, "UserReference": { "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 }, "SetObjectRequest": { "additionalProperties": true, "description": "A set of parameters to set an object with. Does not include the object id or collection.", "example": { "channel_data": { "97c5837d-c65c-4d54-aa39-080eeb81c69d": { "tokens": [ "push_token_123" ] } }, "description": "My product description", "locale": "en-US", "name": "My product", "preferences": { "default": { "channel_types": { "email": true }, "workflows": { "dinosaurs-loose": { "channel_types": { "email": true } } } } }, "price": 100.0, "timezone": "America/New_York" }, "properties": { "channel_data": { "$ref": "#/components/schemas/InlineChannelDataRequest" }, "locale": { "description": "The locale of the object. Used for [message localization](/concepts/translations).", "nullable": true, "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": { "$ref": "#/components/schemas/InlinePreferenceSetRequest" }, "timezone": { "description": "The timezone of the object. 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 } }, "title": "SetObjectRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.SetObjectRequest", "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 }, "ListObjectPreferenceSetsResponse": { "description": "A list of preference sets for the object", "example": [ { "categories": { "marketing": false, "transactional": { "channel_types": { "email": false } } }, "channel_types": { "email": true, "push": false, "sms": { "conditions": [ { "argument": "US", "operator": "equal_to", "variable": "recipient.country_code" } ] } }, "commercial_subscribed": true, "id": "default", "workflows": null } ], "items": { "$ref": "#/components/schemas/PreferenceSet" }, "title": "ListObjectPreferenceSetsResponse", "type": "array", "x-struct": null, "x-validate": null }, "Tenant": { "additionalProperties": true, "description": "A tenant entity.", "example": { "__typename": "Tenant", "id": "tenant_jp123", "name": "Jurassic Park", "settings": { "branding": { "icon_url": "https://example.com/trex_silhouette_icon.png", "logo_url": "https://example.com/amber_fossil_logo.png", "primary_color": "#DF1A22", "primary_color_contrast": "#FFDE00" }, "preference_set": { "categories": { "safety": { "channel_types": { "email": true, "push": true } } }, "channel_types": { "email": true, "in_app_feed": true, "push": true }, "id": "default", "workflows": { "park_alert": { "channel_types": { "email": true, "push": true } } } } } }, "properties": { "__typename": { "description": "The typename of the schema.", "example": "Tenant", "type": "string", "x-struct": null, "x-validate": null }, "id": { "description": "The unique identifier for the tenant.", "nullable": false, "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 }, "settings": { "description": "The settings for the tenant. Includes branding and preference set.", "nullable": true, "properties": { "branding": { "description": "The branding for the tenant.", "nullable": true, "properties": { "icon_url": { "description": "The icon URL for the tenant. Must point to a valid image with an image MIME type.", "example": "https://example.com/trex_silhouette_icon.png", "format": "uri", "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.", "example": "https://example.com/amber_fossil_logo.png", "format": "uri", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "primary_color": { "description": "The primary color for the tenant, provided as a hex value.", "example": "#DF1A22", "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.", "example": "#FFDE00", "nullable": true, "type": "string", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null }, "preference_set": { "anyOf": [ { "$ref": "#/components/schemas/PreferenceSet" }, { "nullable": true, "x-struct": null, "x-validate": null } ], "description": "The preference set for the tenant. Used to override the default preference set.", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null } }, "required": [ "__typename", "id" ], "title": "Tenant", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.Tenant", "x-validate": null }, "BulkSetUserPreferencesRequest": { "description": "A request to set preferences for a set of users in bulk.", "example": { "preferences": { "__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 } } } }, "user_ids": [ "user_1", "user_2" ] }, "properties": { "preferences": { "$ref": "#/components/schemas/PreferenceSetRequest" }, "user_ids": { "description": "A list of user IDs.", "items": { "description": "The unique identifier of the user.", "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "preferences", "user_ids" ], "title": "BulkSetUserPreferencesRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.BulkSetUserPreferencesRequest", "x-validate": null }, "MessageInteractedRequest": { "description": "A request to mark a message as interacted with.", "example": { "metadata": { "key": "value" } }, "properties": { "metadata": { "additionalProperties": true, "description": "Metadata about the interaction.", "example": { "key": "value" }, "type": "object", "x-struct": null, "x-validate": null } }, "title": "MessageInteractedRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.MessageInteractedRequest", "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 }, "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 }, "GuideActionResponse": { "description": "A response for a guide action.", "example": { "status": "ok" }, "properties": { "status": { "description": "The status of a guide's action.", "example": "ok", "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "status" ], "title": "GuideActionResponse", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.Guides.Responses.GuideActionResponse", "x-validate": null }, "MessagePushContent": { "description": "Push channel data.", "example": { "__typename": "MessagePushContent", "body": "Multiple assets out of containment in Sector 5. Take shelter immediately!", "data": { "asset_type": "carnivore", "severity": "high" }, "title": "URGENT: Asset Containment Alert", "token": "ingen-security-1234567890" }, "properties": { "__typename": { "description": "The typename of the schema.", "example": "MessagePushContent", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "body": { "description": "The content body of the push notification.", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "data": { "additionalProperties": true, "description": "Additional data payload for the push notification.", "nullable": true, "type": "object", "x-struct": null, "x-validate": null }, "title": { "description": "The title of the push notification.", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "token": { "description": "The device token to send the push notification to.", "nullable": false, "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "__typename", "title", "body", "token" ], "title": "MessagePushContent", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.MessagePushContent", "x-validate": null }, "PreferenceSet": { "description": "A preference set represents a specific set of notification preferences for a recipient. A recipient can have multiple preference sets.", "example": { "categories": { "marketing": false, "transactional": { "channel_types": { "email": false } } }, "channel_types": { "email": true, "push": false, "sms": { "conditions": [ { "argument": "US", "operator": "equal_to", "variable": "recipient.country_code" } ] } }, "commercial_subscribed": true, "id": "default", "workflows": null }, "properties": { "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 } } }, "title": "PreferenceSetCategories", "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 }, "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 that channel ID.", "x-struct": null, "x-validate": null }, "commercial_subscribed": { "description": "Whether the recipient is subscribed to commercial communications. When false, the recipient will not receive commercial workflow notifications.", "nullable": true, "type": "boolean", "x-struct": null, "x-validate": null }, "id": { "description": "Unique identifier for the preference set.", "example": "default", "type": "string", "x-struct": null, "x-validate": null }, "workflows": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/PreferenceSetWorkflowCategorySetting" }, "description": "An object where the key is the workflow key and the values are the preference settings for that workflow.", "example": { "dinosaurs-loose": { "channel_types": { "email": false } } }, "title": "PreferenceSetWorkflows", "type": "object", "x-struct": null, "x-validate": null }, { "nullable": true, "x-struct": null, "x-validate": null } ], "description": "An object where the key is the workflow key and the values are the preference settings for that workflow.", "x-struct": null, "x-validate": null } }, "required": [ "id" ], "title": "PreferenceSet", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.PreferenceSet", "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 }, "WorkflowRecipientRunEvent": { "description": "An event that occurred during a workflow recipient run.", "example": { "__typename": "WorkflowRecipientRunEvent", "attempt": 1, "data": { "channel_type": "email", "message_id": "2FVHPWxRqNuXQ9krvNP5A6Z4qXe" }, "event": "message_enqueued", "id": "2FVHPWxRqNuXQ9krvNP5A6Z4qXe", "inserted_at": "2025-01-01T00:00:00Z", "status": "ok", "step_ref": "email_step_1", "step_type": "channel" }, "properties": { "__typename": { "description": "The typename of the schema.", "example": "WorkflowRecipientRunEvent", "type": "string", "x-struct": null, "x-validate": null }, "attempt": { "description": "The attempt number of the workflow recipient run event. Increments for each retry.", "example": 1, "type": "integer", "x-struct": null, "x-validate": null }, "data": { "additionalProperties": true, "description": "Event-specific data associated with the event.", "nullable": true, "type": "object", "x-struct": null, "x-validate": null }, "event": { "description": "The type of event that occurred.", "example": "message_enqueued", "type": "string", "x-struct": null, "x-validate": null }, "id": { "description": "The unique identifier for the event.", "example": "2FVHPWxRqNuXQ9krvNP5A6Z4qXe", "type": "string", "x-struct": null, "x-validate": null }, "inserted_at": { "description": "Timestamp when the resource was created.", "example": "2025-01-01T00:00:00Z", "format": "date-time", "type": "string", "x-struct": null, "x-validate": null }, "status": { "description": "Whether the event represents a successful or error state.", "enum": [ "ok", "error" ], "example": "ok", "type": "string", "x-struct": null, "x-validate": null }, "step_ref": { "description": "The reference of the workflow step associated with this event.", "example": "email_step_1", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "step_type": { "description": "The type of workflow step associated with this event.", "example": "channel", "nullable": true, "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "__typename", "id", "event", "status", "inserted_at" ], "title": "WorkflowRecipientRunEvent", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.WorkflowRecipientRunEvent", "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 }, "MessageDeliveryLog": { "description": "A message delivery log contains a `request` from Knock to a downstream provider and the `response` that was returned.", "example": { "__typename": "MessageDeliveryLog", "environment_id": "123e4567-e89b-12d3-a456-426614174000", "id": "2FVHPWxRqNuXQ9krvNP5A6Z4qXe", "inserted_at": "2021-01-01T00:00:00Z", "request": { "body": { "html_content": "" }, "headers": { "Content-Type": "application/json" }, "host": "localhost", "method": "GET", "path": "/", "query": "?foo=bar" }, "response": { "body": { "success": true }, "headers": { "Content-Type": "application/json" }, "status": 200 }, "service_name": "Postmark" }, "properties": { "__typename": { "description": "The typename of the schema.", "example": "MessageDeliveryLog", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "environment_id": { "description": "The ID of the environment in which the message delivery occurred.", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "id": { "description": "The unique identifier for the message delivery log.", "example": "2FVHPWxRqNuXQ9krvNP5A6Z4qXe", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "inserted_at": { "description": "Timestamp when the message delivery log was created.", "example": "2021-01-01T00:00:00Z", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "request": { "$ref": "#/components/schemas/MessageDeliveryLogRequest" }, "response": { "$ref": "#/components/schemas/MessageDeliveryLogResponse" }, "service_name": { "description": "The name of the service that processed the delivery.", "example": "Postmark", "nullable": false, "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "__typename", "id", "environment_id", "request", "response", "service_name", "inserted_at" ], "title": "MessageDeliveryLog", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.MessageDeliveryLog", "x-validate": null }, "ListObjectsResponse": { "description": "A paginated list of objects in a collection.", "example": { "entries": [ { "__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" } ], "page_info": { "__typename": "PageInfo", "after": null, "before": null, "page_size": 25 } }, "properties": { "entries": { "description": "A list of objects.", "items": { "$ref": "#/components/schemas/Object" }, "type": "array", "x-struct": null, "x-validate": null }, "page_info": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "entries", "page_info" ], "title": "ListObjectsResponse", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.ListObjectsResponse", "x-validate": null }, "ObjectReference": { "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 }, "PreferenceSetRequestWorkflows": { "additionalProperties": { "$ref": "#/components/schemas/PreferenceSetWorkflowCategorySetting" }, "description": "An object where the key is the workflow key and the values are the preference settings for that workflow.", "example": { "dinosaurs-loose": { "channel_types": { "email": false, "sms": true } }, "welcome-sequence": true }, "title": "PreferenceSetRequestWorkflows", "type": "object", "x-struct": null, "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 that channel ID.", "x-struct": null, "x-validate": null }, "conditions": { "description": "A list of conditions to apply to a channel type.", "items": { "$ref": "#/components/schemas/Condition" }, "nullable": true, "type": "array", "x-struct": null, "x-validate": null } }, "title": "PreferenceSetWorkflowCategorySettingObject", "type": "object", "x-struct": null, "x-validate": null } ], "title": "PreferenceSetWorkflowCategorySetting", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.PreferenceSetWorkflowCategorySetting", "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": "

This is a message in an app feed

", "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 }, "MessageDeliveryLogResponse": { "description": "A message delivery log response.", "example": { "body": { "success": true }, "headers": { "Content-Type": "application/json" }, "status": 200 }, "properties": { "body": { "description": "The body content that was received with the response.", "oneOf": [ { "type": "string", "x-struct": null, "x-validate": null }, { "additionalProperties": true, "type": "object", "x-struct": null, "x-validate": null } ], "type": "object", "x-struct": null, "x-validate": null }, "headers": { "additionalProperties": true, "description": "The headers that were received with the response.", "nullable": true, "type": "object", "x-struct": null, "x-validate": null }, "status": { "description": "The HTTP status code of the response.", "example": 200, "nullable": false, "type": "integer", "x-struct": null, "x-validate": null } }, "title": "MessageDeliveryLogResponse", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.MessageDeliveryLog.Response", "x-validate": null }, "Notify Request": { "description": "A request to trigger a notification workflow.", "example": { "actor": "user_123", "cancellation_key": "comment_123", "data": { "comment": "Great work on this feature!", "url": "https://example.com/projects/123/comments/456" }, "name": "new-comment", "recipients": [ "user_456", { "collection": "projects", "id": "project_789" } ] }, "properties": { "actor": { "$ref": "#/components/schemas/RecipientReference" }, "cancellation_key": { "description": "An optional key that is used to reference a specific workflow trigger request when issuing a [workflow cancellation](/send-notifications/canceling-workflows) request. Must be provided while triggering a workflow in order to enable subsequent cancellation. Should be unique across trigger requests to avoid unintentional cancellations.", "nullable": true, "type": "string", "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 }, "name": { "description": "The key of the workflow to trigger.", "type": "string", "x-struct": null, "x-validate": null }, "recipients": { "description": "A list of recipients.", "items": { "$ref": "#/components/schemas/RecipientReference" }, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "name", "actor", "recipients" ], "title": "Notify Request", "type": "object", "x-struct": "Elixir.SwitchboardWeb.Specs.Notify.Requests.TriggerRequest", "x-validate": null }, "ListMessageDeliveryLogsResponse": { "description": "A message delivery log response.", "example": { "items": [ { "__typename": "MessageDeliveryLog", "environment_id": "123e4567-e89b-12d3-a456-426614174000", "id": "2FVHPWxRqNuXQ9krvNP5A6Z4qXe", "inserted_at": "2021-01-01T00:00:00Z", "request": { "body": { "html_content": "" }, "headers": { "Content-Type": "application/json" }, "host": "localhost", "method": "GET", "path": "/", "query": "?foo=bar" }, "response": { "body": { "success": true }, "headers": { "Content-Type": "application/json" }, "status": 200 }, "service_name": "Postmark" } ], "page_info": { "__typename": "PageInfo", "after": null, "before": null, "page_size": 25 } }, "properties": { "items": { "description": "Returns a paginated list of delivery logs from the downstream provider for the specified message. For Knock in-app channels, the delivery logs will always be an empty list.", "items": { "$ref": "#/components/schemas/MessageDeliveryLog" }, "type": "array", "x-struct": null, "x-validate": null }, "page_info": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "items", "page_info" ], "title": "ListMessageDeliveryLogsResponse", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.ListMessageDeliveryLogsResponse", "x-validate": null }, "UserRecipient": { "description": "The ID of the user which is used as the reference for the recipient.", "example": "user_123", "title": "UserRecipient", "type": "string", "x-struct": null, "x-validate": null }, "ListTenantsResponse": { "description": "A response containing a list of tenants.", "example": { "entries": [ { "__typename": "Tenant", "id": "tenant_jp123", "name": "Jurassic Park", "settings": { "branding": { "icon_url": "https://example.com/trex_silhouette_icon.png", "logo_url": "https://example.com/amber_fossil_logo.png", "primary_color": "#DF1A22", "primary_color_contrast": "#FFDE00" }, "preference_set": { "categories": { "safety": { "channel_types": { "email": true, "push": true } } }, "channel_types": { "email": true, "in_app_feed": true, "push": true }, "id": "default", "workflows": { "park_alert": { "channel_types": { "email": true, "push": true } } } } } } ], "page_info": { "__typename": "PageInfo", "after": null, "before": null, "page_size": 25 } }, "properties": { "entries": { "description": "A list of tenants.", "items": { "$ref": "#/components/schemas/Tenant" }, "type": "array", "x-struct": null, "x-validate": null }, "page_info": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "entries", "page_info" ], "title": "ListTenantsResponse", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.ListTenantsResponse", "x-validate": null }, "ListActivitiesResponse": { "description": "Returns a paginated list of `activities` associated with a given message. For messages produced after a [batch step](/designing-workflows/batch-function), this will contain one or more activities. Non-batched messages will always return a single activity.", "example": { "items": [ { "__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" } ], "page_info": { "__typename": "PageInfo", "after": null, "before": null, "page_size": 25 } }, "properties": { "items": { "description": "A list of activities.", "items": { "$ref": "#/components/schemas/Activity" }, "type": "array", "x-struct": null, "x-validate": null }, "page_info": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "items", "page_info" ], "title": "ListActivitiesResponse", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.ListActivitiesResponse", "x-validate": null }, "SlackChannelDataTokenObject": { "description": "A Slack connection token.", "example": { "access_token": "xoxb-1234567890" }, "nullable": true, "properties": { "access_token": { "description": "A Slack access token.", "example": "xoxb-1234567890", "nullable": true, "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "access_token" ], "title": "SlackChannelDataTokenObject", "type": "object", "x-struct": null, "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 }, "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 }, "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 }, "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": "

This is a message in an app feed

", "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 }, "RecipientRequest": { "description": "Specifies a recipient in a request. This can either be a user identifier (string), an inline user request (object), or an inline object request, which is determined by the presence of a `collection` property.", "example": { "id": "user_1" }, "nullable": false, "oneOf": [ { "description": "The ID of the user which is used as the reference for the recipient.", "example": "user_123", "title": "UserRecipient", "type": "string", "x-struct": null, "x-validate": null }, { "$ref": "#/components/schemas/InlineIdentifyUserRequest" }, { "$ref": "#/components/schemas/InlineIdentifyObjectRequest" } ], "title": "RecipientRequest", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.RecipientRequest", "x-validate": null }, "AWSSNSPushChannelDataDevicesOnly": { "description": "AWS SNS push channel data.", "example": { "devices": [ { "locale": "en-US", "target_arn": "arn:aws:sns:us-west-2:123456789012:endpoint/GCM/gcmpushapp/5e3e9847-3183-3f18-a7e8-671c3a57d4b3", "timezone": "America/Los_Angeles" } ] }, "properties": { "devices": { "description": "A list of devices. Each device contains a target_arn, and optionally a locale and timezone.", "items": { "properties": { "locale": { "description": "The locale of the object. Used for [message localization](/concepts/translations).", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "target_arn": { "description": "The ARN of a platform endpoint associated with a platform application and a device token. See [Setting up an Amazon SNS platform endpoint for mobile notifications](https://docs.aws.amazon.com/sns/latest/dg/mobile-platform-endpoint.html).", "type": "string", "x-struct": null, "x-validate": null }, "timezone": { "description": "The timezone of the object. 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 } }, "required": [ "target_arn" ], "type": "object", "x-struct": null, "x-validate": null }, "nullable": false, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "devices" ], "title": "AWSSNSPushChannelDataDevicesOnly", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.AWSSNSPushChannelDataDevicesOnly", "x-validate": null }, "SlackTokenConnection": { "description": "A Slack connection token.", "example": { "access_token": "xoxb-1234567890", "channel_id": "C01234567890", "user_id": "U01234567890" }, "properties": { "access_token": { "description": "A Slack access token.", "example": "xoxb-1234567890", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "channel_id": { "description": "A Slack channel ID from the Slack provider.", "example": "C01234567890", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "user_id": { "description": "A Slack user ID from the Slack provider.", "example": "U01234567890", "nullable": true, "type": "string", "x-struct": null, "x-validate": null } }, "title": "SlackTokenConnection", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.SlackChannelData.TokenConnection", "x-validate": null }, "IdentifyUserRequest": { "additionalProperties": true, "description": "A set of parameters to identify a user with. Does not include the user ID, as that's specified elsewhere in the request. You can supply any additional properties you'd like to upsert for the user.", "example": { "channel_data": { "97c5837d-c65c-4d54-aa39-080eeb81c69d": { "tokens": [ "push_token_123" ] } }, "email": "ian.malcolm@chaos.theory", "name": "Dr. Ian Malcolm", "preferences": { "default": { "channel_types": { "email": true }, "workflows": { "dinosaurs-loose": { "channel_types": { "email": true } } } } }, "timezone": "America/New_York" }, "properties": { "avatar": { "description": "A URL for the avatar of the user.", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "channel_data": { "allOf": [ { "$ref": "#/components/schemas/InlineChannelDataRequest" } ], "description": "Channel-specific information that's needed to deliver a notification to an end provider.", "nullable": true, "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 }, "locale": { "description": "The locale of the user. Used for [message localization](/concepts/translations).", "nullable": true, "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 }, "preferences": { "allOf": [ { "$ref": "#/components/schemas/InlinePreferenceSetRequest" } ], "description": "A set of preferences for the user.", "nullable": true, "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 } }, "title": "IdentifyUserRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.IdentifyUserRequest", "x-validate": null }, "ChannelsForMsTeamsProviderResponse": { "description": "The response from a Microsoft Teams provider request, containing a list of channels.", "example": { "ms_teams_channels": [ { "displayName": "General", "id": "channel-id-1" } ] }, "properties": { "ms_teams_channels": { "description": "List of Microsoft Teams channels.", "items": { "properties": { "createdDateTime": { "description": "Microsoft Teams channel created date and time.", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "description": { "description": "Microsoft Teams channel description.", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "displayName": { "description": "Microsoft Teams channel name.", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "id": { "description": "Microsoft Teams channel ID.", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "isArchived": { "description": "Whether the Microsoft Teams channel is archived.", "nullable": false, "type": "boolean", "x-struct": null, "x-validate": null }, "membershipType": { "description": "Microsoft Teams channel membership type.", "nullable": false, "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "id", "displayName" ], "type": "object", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "ms_teams_channels" ], "title": "ChannelsForMsTeamsProviderResponse", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.ChannelsForMsTeamsProviderResponse", "x-validate": null }, "BulkSetObjectsRequest": { "description": "A request to set objects in bulk.", "example": { "objects": [ { "id": "project_1", "name": "My project" } ] }, "properties": { "objects": { "description": "A list of objects.", "items": { "$ref": "#/components/schemas/BulkSetObjectRequest" }, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "objects" ], "title": "BulkSetObjectsRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.BulkSetObjectsRequest", "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 }, "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 }, "GuidesResponse": { "description": "A response for a list of guides.", "example": { "entries": [ { "__typename": "Guide", "activation_url_patterns": [], "activation_url_rules": [ { "argument": "/workflows", "directive": "allow", "operator": "contains", "variable": "pathname" }, { "argument": "/guides", "directive": "allow", "operator": "equal_to", "variable": "pathname" } ], "active": true, "bypass_global_group_limit": false, "channel_id": "51b92f90-1504-4fda-95c1-495a3883bc4d", "dashboard_url": "https://dashboard.knock.app/~/guides/nps-survey", "id": "53595157-2fac-4a17-8dd7-e6603e32cb3a", "inserted_at": "2025-09-30T14:54:44.217756Z", "key": "nps-survey", "semver": "0.0.3", "steps": [ { "content": { "companyName": "Knock", "showFeedbackSection": true, "showThanksToast": true }, "message": { "archived_at": null, "id": "33hjnKRKNx9ISRlixVBjhpkh28J", "interacted_at": "2025-10-07T15:10:59.291Z", "link_clicked_at": null, "read_at": "2025-10-07T15:10:59.291Z", "seen_at": "2025-10-06T18:46:03.210Z" }, "ref": "step_1", "schema_key": "nps-survey", "schema_semver": "0.0.3", "schema_variant_key": "default" } ], "type": "nps-survey", "updated_at": "2025-10-03T17:46:53.653663Z" }, { "__typename": "Guide", "activation_url_patterns": [ { "directive": "allow", "pathname": "/dairy/*" }, { "directive": "allow", "pathname": "/produce", "search": "role=admin" }, { "directive": "allow", "pathname": "/" } ], "activation_url_rules": [], "active": true, "bypass_global_group_limit": false, "channel_id": "51b92f90-1504-4fda-95c1-495a3883bc4d", "dashboard_url": "https://dashboard.knock.app/~/guides/changelog-card", "id": "4fc4503e-ef8b-473a-ae07-14800639d30c", "inserted_at": "2025-10-07T19:41:06.215233Z", "key": "changelog-card", "semver": "0.0.3", "steps": [ { "content": { "body": "Lorem ipsum", "dismissible": false, "eyebrowText": "New in Knock", "image": { "action": "", "alt": "", "url": "https://bhoite.com/img/sculptures/2024/lander-r2/lander-r2.jpg" }, "link": "https://dashboard.knock.app/knock/development/guides/changelog-card/editor", "title": "Changelog card" }, "message": { "archived_at": null, "id": null, "interacted_at": null, "link_clicked_at": null, "read_at": null, "seen_at": null }, "ref": "step_1", "schema_key": "changelog-card", "schema_semver": "0.0.3", "schema_variant_key": "default" } ], "type": "changelog-card", "updated_at": "2025-10-07T20:39:52.410146Z" } ], "guide_group_display_logs": { "default": "2025-08-16T00:47:14.025Z" }, "guide_groups": [ { "__typename": "GuideGroup", "display_interval": 3600, "display_sequence": [ "nps-survey", "changelog-card" ], "inserted_at": "2025-07-24T21:06:27.394627Z", "key": "default", "updated_at": "2025-10-07T20:39:52.465400Z" } ], "ineligible_guides": [ { "key": "onboarding-tour", "message": "User has archived this guide already", "reason": "marked_as_archived" }, { "key": "premium-feature", "message": "User is not a member of the target audience", "reason": "not_in_target_audience" } ] }, "properties": { "entries": { "description": "A list of guides.", "items": { "properties": { "__typename": { "description": "The typename of the schema.", "type": "string", "x-struct": null, "x-validate": null }, "activation_url_patterns": { "description": "A list of URL Patterns to evaluate user's current location to activate the guide, if matched", "items": { "properties": { "directive": { "description": "The directive for the URL pattern ('allow' or 'block')", "type": "string", "x-struct": null, "x-validate": null }, "pathname": { "description": "The pathname pattern to match (supports wildcards like /*)", "type": "string", "x-struct": null, "x-validate": null }, "search": { "description": "The search query params to match", "type": "string", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null }, "activation_url_rules": { "description": "A list of URL rules to evaluate user's current location to activate the guide, if matched", "items": { "properties": { "argument": { "description": "The value to compare against", "type": "string", "x-struct": null, "x-validate": null }, "directive": { "description": "The directive for the URL rule ('allow' or 'block')", "type": "string", "x-struct": null, "x-validate": null }, "operator": { "description": "The comparison operator ('contains' or 'equal_to')", "type": "string", "x-struct": null, "x-validate": null }, "variable": { "description": "The variable to evaluate ('pathname')", "type": "string", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null }, "active": { "description": "Whether the guide is active.", "type": "boolean", "x-struct": null, "x-validate": null }, "bypass_global_group_limit": { "type": "boolean", "x-struct": null, "x-validate": null }, "channel_id": { "format": "uuid", "type": "string", "x-struct": null, "x-validate": null }, "dashboard_url": { "description": "URL to this guide in the Knock dashboard", "type": "string", "x-struct": null, "x-validate": null }, "id": { "description": "The unique identifier for the guide.", "format": "uuid", "type": "string", "x-struct": null, "x-validate": null }, "inserted_at": { "format": "date-time", "type": "string", "x-struct": null, "x-validate": null }, "key": { "description": "The key of the guide.", "type": "string", "x-struct": null, "x-validate": null }, "semver": { "type": "string", "x-struct": null, "x-validate": null }, "steps": { "items": { "properties": { "content": { "additionalProperties": true, "type": "object", "x-struct": null, "x-validate": null }, "message": { "properties": { "archived_at": { "format": "date-time", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "id": { "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "interacted_at": { "format": "date-time", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "link_clicked_at": { "format": "date-time", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "read_at": { "format": "date-time", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "seen_at": { "format": "date-time", "nullable": true, "type": "string", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null }, "ref": { "type": "string", "x-struct": null, "x-validate": null }, "schema_key": { "type": "string", "x-struct": null, "x-validate": null }, "schema_semver": { "type": "string", "x-struct": null, "x-validate": null }, "schema_variant_key": { "type": "string", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null }, "type": { "description": "The type of the guide.", "type": "string", "x-struct": null, "x-validate": null }, "updated_at": { "format": "date-time", "type": "string", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null }, "guide_group_display_logs": { "additionalProperties": { "format": "date-time", "type": "string", "x-struct": null, "x-validate": null }, "description": "A map of guide group keys to their last display timestamps.", "type": "object", "x-struct": null, "x-validate": null }, "guide_groups": { "description": "A list of guide groups with their display sequences and intervals.", "items": { "properties": { "__typename": { "type": "string", "x-struct": null, "x-validate": null }, "display_interval": { "type": "integer", "x-struct": null, "x-validate": null }, "display_sequence": { "items": { "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null }, "inserted_at": { "format": "date-time", "type": "string", "x-struct": null, "x-validate": null }, "key": { "type": "string", "x-struct": null, "x-validate": null }, "updated_at": { "format": "date-time", "type": "string", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null }, "ineligible_guides": { "description": "Markers for guides the user is not eligible to see.", "items": { "properties": { "key": { "description": "The guide's key identifier", "type": "string", "x-struct": null, "x-validate": null }, "message": { "description": "Human-readable explanation of ineligibility", "type": "string", "x-struct": null, "x-validate": null }, "reason": { "description": "Reason code for ineligibility", "enum": [ "guide_not_active", "marked_as_archived", "target_conditions_not_met", "not_in_target_audience" ], "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "key", "reason", "message" ], "type": "object", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "entries", "guide_groups", "guide_group_display_logs", "ineligible_guides" ], "title": "GuidesResponse", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.Guides.Responses.GuidesResponse", "x-validate": null }, "PushChannelDataFull": { "description": "Push channel data.", "example": { "devices": [ { "locale": "en-US", "timezone": null, "token": "push_token_1" } ], "tokens": [ "push_token_1", "push_token_2" ] }, "properties": { "devices": { "description": "A list of devices. Each device contains a token, and optionally a locale and timezone.", "items": { "properties": { "locale": { "description": "The locale of the object. Used for [message localization](/concepts/translations).", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "timezone": { "description": "The timezone of the object. 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 }, "token": { "description": "The device token to send the push notification to.", "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "token" ], "type": "object", "x-struct": null, "x-validate": null }, "nullable": false, "type": "array", "x-struct": null, "x-validate": null }, "tokens": { "description": "A list of push channel tokens.", "items": { "description": "The device token to send the push notification to.", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "nullable": false, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "tokens", "devices" ], "title": "PushChannelDataFull", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.PushChannelDataFull", "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": "

This is a message in an app feed

", "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 }, "ListMessagesResponse": { "description": "A paginated list of messages.", "example": { "items": [ { "__typename": "Message", "actors": [ "mr_arnold", "mr_muldoon" ], "archived_at": null, "channel_id": "123e4567-e89b-12d3-a456-426614174000", "clicked_at": null, "data": { "affected_areas": [ "visitor_center", "raptor_pen", "trex_paddock" ], "attraction_id": "paddock_rex_01", "evacuation_protocol": "active", "message": "Life finds a way", "severity": "critical", "system_status": "fences_failing" }, "engagement_statuses": [ "read", "seen" ], "id": "2w3YUpTTOxuDvZFji8OMsKrG176", "inserted_at": "1993-06-11T21:15:00Z", "interacted_at": null, "link_clicked_at": null, "metadata": { "external_id": "123e4567-e89b-12d3-a456-426614174000" }, "read_at": "1993-06-11T21:30:00Z", "recipient": "dr_grant", "scheduled_at": null, "seen_at": "1993-06-11T21:29:45Z", "source": { "__typename": "NotificationSource", "categories": [ "security", "emergency" ], "key": "security-breach-alert", "step_ref": "alert_step_1", "version_id": "123e4567-e89b-12d3-a456-426614174000", "workflow_recipient_run_id": "def01234-a56b-78c9-d012-345678901bcd", "workflow_run_id": "789e0123-f45a-67b8-c901-234567890abc" }, "status": "sent", "tenant": "ingen_isla_nublar", "updated_at": "1993-06-11T21:30:05Z", "workflow": "security-breach-alert" } ], "page_info": { "__typename": "PageInfo", "after": null, "before": null, "page_size": 25 } }, "properties": { "items": { "description": "A list of messages.", "items": { "$ref": "#/components/schemas/Message" }, "type": "array", "x-struct": null, "x-validate": null }, "page_info": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "items", "page_info" ], "title": "ListMessagesResponse", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.ListMessagesResponse", "x-validate": null }, "MergeUserRequest": { "description": "A set of parameters to merge one user into another.", "example": { "from_user_id": "user_1" }, "properties": { "from_user_id": { "description": "The user ID to merge from.", "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "from_user_id" ], "title": "MergeUserRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.MergeUserRequest", "x-validate": null }, "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 }, "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 }, "BulkSetObjectRequest": { "additionalProperties": true, "description": "A custom [Object](/concepts/objects) entity which belongs to a collection.", "example": { "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 }, "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" ], "title": "BulkSetObjectRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.BulkSetObjectRequest", "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 }, "AudienceMember": { "description": "An audience member.", "example": { "__typename": "AudienceMember", "added_at": "1993-06-10T14:30:00Z", "tenant": "ingen_isla_nublar", "user": { "__typename": "User", "created_at": null, "email": "alan.grant@dig.site.mt", "id": "dr_grant", "name": "Dr. Alan Grant", "updated_at": "1993-06-09T08:15:00Z" }, "user_id": "dr_grant" }, "properties": { "__typename": { "description": "The typename of the schema.", "example": "AudienceMember", "type": "string", "x-struct": null, "x-validate": null }, "added_at": { "description": "Timestamp when the resource was created.", "example": "2025-01-01T00:00:00Z", "format": "date-time", "type": "string", "x-struct": null, "x-validate": null }, "tenant": { "description": "The unique identifier for the tenant.", "example": "acme_corp", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "user": { "$ref": "#/components/schemas/User" }, "user_id": { "description": "The unique identifier of the user.", "example": "user_123", "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "__typename", "added_at", "user_id", "user" ], "title": "AudienceMember", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.AudienceMember", "x-validate": null }, "MessageSmsContent": { "description": "The content of an SMS message.", "example": { "__typename": "MessageSmsContent", "body": "ALERT: Security systems offline in Sector B. Evacuate immediately. Proceed to emergency bunker. DO NOT attempt to approach the paddocks. Response team dispatched.", "to": "+15553982647" }, "properties": { "__typename": { "description": "The typename of the schema.", "example": "MessageSmsContent", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "body": { "description": "The content body of the SMS message.", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "to": { "description": "The phone number the SMS was sent to.", "nullable": false, "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "__typename", "to", "body" ], "title": "MessageSmsContent", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.MessageSmsContent", "x-validate": null }, "PreferenceSetCategories": { "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 } } }, "title": "PreferenceSetCategories", "type": "object", "x-struct": null, "x-validate": null }, "PreferenceSetWorkflows": { "additionalProperties": { "$ref": "#/components/schemas/PreferenceSetWorkflowCategorySetting" }, "description": "An object where the key is the workflow key and the values are the preference settings for that workflow.", "example": { "dinosaurs-loose": { "channel_types": { "email": false } } }, "title": "PreferenceSetWorkflows", "type": "object", "x-struct": null, "x-validate": null }, "SlackChannelData": { "description": "Slack channel data.", "example": { "connections": [ { "access_token": "xoxb-1234567890", "channel_id": "C01234567890", "user_id": "U01234567890" } ], "token": { "access_token": "xoxb-1234567890" } }, "properties": { "connections": { "description": "List of Slack channel connections.", "items": { "description": "A Slack connection, either an access token or an incoming webhook", "nullable": false, "oneOf": [ { "$ref": "#/components/schemas/SlackTokenConnection" }, { "$ref": "#/components/schemas/SlackIncomingWebhookConnection" } ], "type": "object", "x-struct": null, "x-validate": null }, "nullable": false, "type": "array", "x-struct": null, "x-validate": null }, "token": { "description": "A Slack connection token.", "example": { "access_token": "xoxb-1234567890" }, "nullable": true, "properties": { "access_token": { "description": "A Slack access token.", "example": "xoxb-1234567890", "nullable": true, "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "access_token" ], "title": "SlackChannelDataTokenObject", "type": "object", "x-struct": null, "x-validate": null } }, "required": [ "connections" ], "title": "SlackChannelData", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.SlackChannelData", "x-validate": null }, "BulkUpdateMessagesForChannelRequest": { "description": "Updates message statuses in a specified channel. Use the `channel_id` parameter to target the channel and the `status` parameter to define what the status should be changed to (e.g. `archive`, `unarchive`). Apply to all messages or use filters to target a subset. For in-app channels, messages can be updated indefinitely via this operation. For all other channel types, messages outside the account's retention window will not be updated as part of this operation.", "example": { "archived": "include", "delivery_status": "delivered", "engagement_status": "seen", "has_tenant": true, "newer_than": "2024-01-01T00:00:00Z", "older_than": "2024-01-01T00:00:00Z", "recipient_ids": [ "recipient1", "recipient2" ], "tenants": [ "tenant1", "tenant2" ], "trigger_data": "{\"key\":\"value\"}", "workflows": [ "workflow1", "workflow2" ] }, "properties": { "archived": { "description": "Limits the results to messages with the given archived status.", "enum": [ "exclude", "include", "only" ], "type": "string", "x-struct": null, "x-validate": null }, "delivery_status": { "description": "Limits the results to messages with the given delivery status.", "enum": [ "queued", "sent", "delivered", "delivery_attempted", "undelivered", "not_sent", "bounced" ], "type": "string", "x-struct": null, "x-validate": null }, "engagement_status": { "description": "Limits the results to messages with the given engagement status.", "enum": [ "seen", "unseen", "read", "unread", "archived", "unarchived", "link_clicked", "interacted" ], "type": "string", "x-struct": null, "x-validate": null }, "has_tenant": { "description": "Limits the results to messages that have a tenant or not.", "type": "boolean", "x-struct": null, "x-validate": null }, "newer_than": { "description": "Limits the results to messages inserted after the given date.", "format": "date-time", "type": "string", "x-struct": null, "x-validate": null }, "older_than": { "description": "Limits the results to messages inserted before the given date.", "format": "date-time", "type": "string", "x-struct": null, "x-validate": null }, "recipient_ids": { "description": "Limits the results to messages with the given recipient IDs.", "items": { "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null }, "tenants": { "description": "Limits the results to messages with the given tenant IDs.", "items": { "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null }, "trigger_data": { "description": "Limits the results to only messages that were generated with the given data. See [trigger data filtering](/api-reference/overview/trigger-data-filtering) for more information.", "type": "string", "x-struct": null, "x-validate": null }, "workflows": { "description": "Limits the results to messages with the given workflow keys.", "items": { "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } }, "title": "BulkUpdateMessagesForChannelRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.BulkUpdateMessagesForChannelRequest", "x-validate": null }, "BatchListMessagesResponse": { "description": "The list of messages that were updated.", "example": [ { "__typename": "Message", "actors": [ "user_123" ], "archived_at": null, "channel_id": "123e4567-e89b-12d3-a456-426614174000", "clicked_at": null, "data": { "foo": "bar" }, "engagement_statuses": [ "seen" ], "id": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "inserted_at": "2021-01-01T00:00:00Z", "interacted_at": null, "link_clicked_at": null, "metadata": { "external_id": "123e4567-e89b-12d3-a456-426614174000" }, "read_at": null, "recipient": "user_123", "scheduled_at": null, "seen_at": "2025-01-01T00:01:00Z", "source": { "__typename": "NotificationSource", "categories": [ "collaboration" ], "key": "comment-created", "version_id": "123e4567-e89b-12d3-a456-426614174000" }, "status": "sent", "tenant": "tenant_123", "updated_at": "2021-01-01T00:00:00Z", "workflow": "comment-created" } ], "items": { "allOf": [ { "$ref": "#/components/schemas/Message" } ], "example": { "__typename": "Message", "actors": [ "user_123" ], "archived_at": null, "channel_id": "123e4567-e89b-12d3-a456-426614174000", "clicked_at": null, "data": { "foo": "bar" }, "engagement_statuses": [ "seen" ], "id": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "inserted_at": "2021-01-01T00:00:00Z", "interacted_at": null, "link_clicked_at": null, "metadata": { "external_id": "123e4567-e89b-12d3-a456-426614174000" }, "read_at": null, "recipient": "user_123", "scheduled_at": null, "seen_at": "2025-01-01T00:01:00Z", "source": { "__typename": "NotificationSource", "categories": [ "collaboration" ], "key": "comment-created", "version_id": "123e4567-e89b-12d3-a456-426614174000" }, "status": "sent", "tenant": "tenant_123", "updated_at": "2021-01-01T00:00:00Z", "workflow": "comment-created" }, "x-struct": null, "x-validate": null }, "title": "BatchListMessagesResponse", "type": "array", "x-struct": null, "x-validate": null }, "WorkflowRecipientRun": { "description": "A workflow recipient run represents an individual execution of a workflow for a specific recipient.", "example": { "__typename": "WorkflowRecipientRun", "actor": "user_456", "error_count": 0, "id": "550e8400-e29b-41d4-a716-446655440000", "inserted_at": "2025-01-01T00:00:00Z", "recipient": "user_123", "status": "completed", "tenant": "tenant_abc", "trigger_source": { "cancellation_key": "comment-123-user-456", "type": "api" }, "updated_at": "2025-01-01T00:05:00Z", "workflow": "comment-created", "workflow_run_id": "660e8400-e29b-41d4-a716-446655440000" }, "properties": { "__typename": { "description": "The typename of the schema.", "example": "WorkflowRecipientRun", "type": "string", "x-struct": null, "x-validate": null }, "actor": { "anyOf": [ { "$ref": "#/components/schemas/RecipientReference" }, { "nullable": true, "x-struct": null, "x-validate": null } ], "description": "The actor who triggered the workflow recipient run.", "x-struct": null, "x-validate": null }, "error_count": { "description": "The number of errors encountered during the workflow recipient run.", "example": 0, "type": "integer", "x-struct": null, "x-validate": null }, "id": { "description": "The unique identifier for the workflow recipient run (per-recipient).", "format": "uuid", "type": "string", "x-struct": null, "x-validate": null }, "inserted_at": { "description": "Timestamp when the resource was created.", "example": "2025-01-01T00:00:00Z", "format": "date-time", "type": "string", "x-struct": null, "x-validate": null }, "recipient": { "$ref": "#/components/schemas/RecipientReference" }, "status": { "description": "The current status of the workflow recipient run. One of `queued`, `processing`, `paused`, `completed`, or `cancelled`.", "enum": [ "queued", "processing", "paused", "completed", "cancelled" ], "example": "completed", "type": "string", "x-struct": null, "x-validate": null }, "tenant": { "description": "The tenant associated with the workflow recipient run.", "example": "tenant_abc", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "trigger_source": { "$ref": "#/components/schemas/WorkflowRecipientRunTriggerSource" }, "updated_at": { "description": "The timestamp when the resource was last updated.", "example": "2025-01-01T00:05:00Z", "format": "date-time", "type": "string", "x-struct": null, "x-validate": null }, "workflow": { "description": "The key of the workflow that was executed.", "example": "comment-created", "type": "string", "x-struct": null, "x-validate": null }, "workflow_run_id": { "description": "The identifier for the top-level workflow run shared across all recipients in a single trigger.", "format": "uuid", "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "__typename", "id", "workflow_run_id", "workflow", "status", "recipient", "trigger_source", "inserted_at", "updated_at" ], "title": "WorkflowRecipientRun", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.WorkflowRecipientRun", "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 }, "AWSSNSPushChannelDataFull": { "description": "AWS SNS push channel data.", "example": { "devices": [ { "locale": "en-US", "target_arn": "arn:aws:sns:us-west-2:123456789012:endpoint/GCM/gcmpushapp/5e3e9847-3183-3f18-a7e8-671c3a57d4b3", "timezone": "America/Los_Angeles" } ], "target_arns": [ "arn:aws:sns:us-west-2:123456789012:endpoint/GCM/gcmpushapp/5e3e9847-3183-3f18-a7e8-671c3a57d4b3" ] }, "properties": { "devices": { "description": "A list of devices. Each device contains a target_arn, and optionally a locale and timezone.", "items": { "properties": { "locale": { "description": "The locale of the object. Used for [message localization](/concepts/translations).", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "target_arn": { "description": "The ARN of a platform endpoint associated with a platform application and a device token. See [Setting up an Amazon SNS platform endpoint for mobile notifications](https://docs.aws.amazon.com/sns/latest/dg/mobile-platform-endpoint.html).", "type": "string", "x-struct": null, "x-validate": null }, "timezone": { "description": "The timezone of the object. 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 } }, "required": [ "target_arn" ], "type": "object", "x-struct": null, "x-validate": null }, "nullable": false, "type": "array", "x-struct": null, "x-validate": null }, "target_arns": { "description": "A list of platform endpoint ARNs. See [Setting up an Amazon SNS platform endpoint for mobile notifications](https://docs.aws.amazon.com/sns/latest/dg/mobile-platform-endpoint.html).", "items": { "description": "The ARN of a platform endpoint associated with a platform application and a device token. See [Setting up an Amazon SNS platform endpoint for mobile notifications](https://docs.aws.amazon.com/sns/latest/dg/mobile-platform-endpoint.html).", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "nullable": false, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "target_arns", "devices" ], "title": "AWSSNSPushChannelDataFull", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.AWSSNSPushChannelDataFull", "x-validate": null }, "InlineIdentifyUserRequest": { "additionalProperties": true, "description": "A set of parameters to inline-identify a user with. Inline identifying the user will ensure that the user is available before the request is executed in Knock. It will perform an upsert for the user you're supplying, replacing any properties specified.", "example": { "channel_data": { "97c5837d-c65c-4d54-aa39-080eeb81c69d": { "tokens": [ "push_token_123" ] } }, "email": "jane@ingen.net", "id": "user_1", "name": "Jane Doe", "preferences": { "default": { "channel_types": { "email": true }, "workflows": { "dinosaurs-loose": { "channel_types": { "email": true } } } } }, "timezone": "America/New_York" }, "properties": { "avatar": { "description": "A URL for the avatar of the user.", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "channel_data": { "allOf": [ { "$ref": "#/components/schemas/InlineChannelDataRequest" } ], "description": "Channel-specific information that's needed to deliver a notification to an end provider.", "nullable": true, "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.", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "locale": { "description": "The locale of the user. Used for [message localization](/concepts/translations).", "nullable": true, "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 }, "preferences": { "allOf": [ { "$ref": "#/components/schemas/InlinePreferenceSetRequest" } ], "description": "A set of preferences for the user.", "nullable": true, "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 } }, "required": [ "id" ], "title": "InlineIdentifyUserRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.InlineIdentifyUserRequest", "x-validate": null }, "MsTeamsChannelData": { "description": "Microsoft Teams channel data.", "example": { "connections": [ { "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 } ], "ms_teams_tenant_id": null }, "properties": { "connections": { "description": "List of Microsoft Teams connections.", "items": { "oneOf": [ { "$ref": "#/components/schemas/MsTeamsTokenConnection" }, { "$ref": "#/components/schemas/MsTeamsIncomingWebhookConnection" } ], "type": "object", "x-struct": null, "x-validate": null }, "nullable": false, "type": "array", "x-struct": null, "x-validate": null }, "ms_teams_tenant_id": { "description": "Microsoft Teams tenant ID.", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid", "nullable": true, "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "connections" ], "title": "MsTeamsChannelData", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.MsTeamsChannelData", "x-validate": null }, "SlackIncomingWebhookConnection": { "description": "A Slack connection incoming webhook.", "example": { "url": "https://hooks.slack.com/services/T01234567890/B01234567890/1234567890" }, "properties": { "url": { "description": "The URL of the incoming webhook for a Slack connection.", "example": "https://hooks.slack.com/services/T01234567890/B01234567890/1234567890", "nullable": false, "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "url" ], "title": "SlackIncomingWebhookConnection", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.SlackChannelData.IncomingWebhookConnection", "x-validate": null }, "PreferenceSetChannelTypeSetting": { "description": "A set of settings for a channel type. Currently, this can only be a list of conditions to apply.", "example": { "conditions": [ { "argument": "US", "operator": "equal_to", "variable": "recipient.country_code" } ] }, "properties": { "conditions": { "description": "A list of conditions to apply to a channel type.", "items": { "$ref": "#/components/schemas/Condition" }, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "conditions" ], "title": "PreferenceSetChannelTypeSetting", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.PreferenceSetChannelTypes.PreferenceSetChannelTypeSetting", "x-validate": null }, "UpsertSubscriptionsRequest": { "description": "A request to upsert subscriptions for a set of recipients.", "example": { "properties": { "key": "value" }, "recipients": [ "user_1", "user_2" ] }, "properties": { "properties": { "additionalProperties": true, "description": "The custom properties associated with the subscription relationship.", "nullable": true, "type": "object", "x-struct": null, "x-validate": null }, "recipients": { "description": "The recipients of the subscription. You can subscribe up to 100 recipients to an object at a time.", "items": { "$ref": "#/components/schemas/RecipientRequest" }, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "recipients" ], "title": "UpsertSubscriptionsRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.UpsertSubscriptionsRequest", "x-validate": null }, "Block": { "description": "A block in a message in a chat.", "example": { "content": "Hello, world!", "name": "greeting", "type": "text" }, "nullable": false, "properties": { "content": { "description": "The actual content of the block.", "example": "Hello, world!", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "name": { "description": "The name of the block for identification.", "example": "greeting", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "type": { "description": "The type of block in a message in a chat (text or markdown).", "enum": [ "text", "markdown" ], "example": "text", "nullable": false, "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "type", "name", "content" ], "title": "Block", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.MessageChatContent.Block", "x-validate": null }, "Cancel Request": { "description": "When invoked using a specific workflow key and cancellation key, will cancel any queued workflow runs associated with that key/cancellation key pair. Can optionally provide one or more recipients to scope the request to.", "example": { "cancellation_key": "comment_123", "name": "new-comment", "recipients": [ "user_456" ] }, "properties": { "cancellation_key": { "description": "An optional key that is used to reference a specific workflow trigger request when issuing a [workflow cancellation](/send-notifications/canceling-workflows) request. Must be provided while triggering a workflow in order to enable subsequent cancellation. Should be unique across trigger requests to avoid unintentional cancellations.", "type": "string", "x-struct": null, "x-validate": null }, "name": { "description": "The key of the workflow to cancel.", "type": "string", "x-struct": null, "x-validate": null }, "recipients": { "description": "A list of recipients to cancel the notification for. If omitted, cancels for all recipients associated with the cancellation key.", "items": { "$ref": "#/components/schemas/RecipientReference" }, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "name", "cancellation_key" ], "title": "Cancel Request", "type": "object", "x-struct": "Elixir.SwitchboardWeb.Specs.Notify.Requests.CancelRequest", "x-validate": null }, "PushChannelDataTokensOnly": { "description": "Push channel data.", "example": { "tokens": [ "push_token_1", "push_token_2" ] }, "properties": { "tokens": { "description": "A list of push channel tokens.", "items": { "description": "The device token to send the push notification to.", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "nullable": false, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "tokens" ], "title": "PushChannelDataTokensOnly", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.PushChannelDataTokensOnly", "x-validate": null }, "PreferenceSetChannels": { "additionalProperties": { "description": "Whether the specific channel (by channel_id) is enabled for the preference set, or a settings object with conditions.", "oneOf": [ { "type": "boolean", "x-struct": null, "x-validate": null }, { "$ref": "#/components/schemas/PreferenceSetChannelSetting" } ], "x-struct": null, "x-validate": null }, "description": "Channel preferences.", "example": { "2f641633-95d3-4555-9222-9f1eb7888a80": { "conditions": [ { "argument": "US", "operator": "equal_to", "variable": "recipient.country_code" } ] }, "aef6e715-df82-4ab6-b61e-b743e249f7b6": true }, "title": "PreferenceSetChannels", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.PreferenceSetChannels", "x-validate": null }, "BulkOperation": { "description": "A bulk operation entity.", "example": { "__typename": "BulkOperation", "completed_at": null, "error_count": 0, "error_items": [], "estimated_total_rows": 1000, "failed_at": null, "id": "123e4567-e89b-12d3-a456-426614174000", "inserted_at": "2024-05-22T12:00:00Z", "name": "Bulk operation name", "processed_rows": 0, "progress_path": "https://api.switchboard.com/v1/bulk_operations/123e4567-e89b-12d3-a456-426614174000", "started_at": null, "status": "processing", "success_count": 0, "updated_at": "2024-05-22T12:00:00Z" }, "properties": { "__typename": { "description": "The typename of the schema.", "example": "BulkOperation", "type": "string", "x-struct": null, "x-validate": null }, "completed_at": { "description": "Timestamp when the bulk operation was completed.", "format": "date-time", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "error_count": { "description": "The number of failed operations.", "example": 0, "type": "integer", "x-struct": null, "x-validate": null }, "error_items": { "description": "A list of items that failed to be processed.", "items": { "properties": { "collection": { "description": "The collection this object belongs to.", "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 } }, "required": [ "id" ], "type": "object", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null }, "estimated_total_rows": { "description": "The estimated total number of rows to process.", "example": 1000, "type": "integer", "x-struct": null, "x-validate": null }, "failed_at": { "description": "Timestamp when the bulk operation failed.", "format": "date-time", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "id": { "description": "Unique identifier for the bulk operation.", "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 }, "name": { "description": "The name of the bulk operation.", "example": "Bulk operation name", "type": "string", "x-struct": null, "x-validate": null }, "processed_rows": { "description": "The number of rows processed so far.", "example": 0, "type": "integer", "x-struct": null, "x-validate": null }, "progress_path": { "description": "The URI to the bulk operation's progress.", "format": "uri", "type": "string", "x-struct": null, "x-validate": null }, "started_at": { "description": "Timestamp when the bulk operation was started.", "format": "date-time", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "status": { "description": "The status of the bulk operation.", "enum": [ "queued", "processing", "completed", "failed" ], "example": "queued", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "success_count": { "description": "The number of successful operations.", "example": 0, "type": "integer", "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", "name", "status", "estimated_total_rows", "processed_rows", "success_count", "updated_at", "inserted_at" ], "title": "BulkOperation", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.BulkOperation", "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 }, "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 }, "WorkflowRecipientRunDetail": { "allOf": [ { "$ref": "#/components/schemas/WorkflowRecipientRun" }, { "properties": { "events": { "description": "A list of events that occurred during the workflow recipient run.", "items": { "$ref": "#/components/schemas/WorkflowRecipientRunEvent" }, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "events" ], "type": "object", "x-struct": null, "x-validate": null } ], "description": "A single workflow recipient run with its events.", "example": { "__typename": "WorkflowRecipientRun", "actor": "user_456", "error_count": 0, "events": [ { "__typename": "WorkflowRecipientRunEvent", "attempt": 1, "data": { "channel_type": "email", "message_id": "2FVHPWxRqNuXQ9krvNP5A6Z4qXe" }, "event": "message_enqueued", "id": "2FVHPWxRqNuXQ9krvNP5A6Z4qXe", "inserted_at": "2025-01-01T00:00:00Z", "status": "ok", "step_ref": "email_step_1", "step_type": "channel" } ], "id": "550e8400-e29b-41d4-a716-446655440000", "inserted_at": "2025-01-01T00:00:00Z", "recipient": "user_123", "status": "completed", "tenant": "tenant_abc", "trigger_source": { "cancellation_key": "comment-123-user-456", "type": "api" }, "updated_at": "2025-01-01T00:05:00Z", "workflow": "comment-created", "workflow_run_id": "660e8400-e29b-41d4-a716-446655440000" }, "title": "WorkflowRecipientRunDetail", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.WorkflowRecipientRunDetail", "x-validate": null }, "PushChannelDataDevicesOnly": { "description": "Push channel data.", "example": { "devices": [ { "locale": "en-US", "timezone": "America/Los_Angeles", "token": "push_token_1" } ] }, "properties": { "devices": { "description": "A list of devices. Each device contains a token, and optionally a locale and timezone.", "items": { "properties": { "locale": { "description": "The locale of the object. Used for [message localization](/concepts/translations).", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "timezone": { "description": "The timezone of the object. 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 }, "token": { "description": "The device token to send the push notification to.", "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "token" ], "type": "object", "x-struct": null, "x-validate": null }, "nullable": false, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "devices" ], "title": "PushChannelDataDevicesOnly", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.PushChannelDataDevicesOnly", "x-validate": null }, "Message": { "description": "Represents a single message that was generated by a workflow for a given channel.", "example": { "__typename": "Message", "actors": [ "mr_arnold", "mr_muldoon" ], "archived_at": null, "channel_id": "123e4567-e89b-12d3-a456-426614174000", "clicked_at": null, "data": { "affected_areas": [ "visitor_center", "raptor_pen", "trex_paddock" ], "attraction_id": "paddock_rex_01", "evacuation_protocol": "active", "message": "Life finds a way", "severity": "critical", "system_status": "fences_failing" }, "engagement_statuses": [ "read", "seen" ], "id": "2w3YUpTTOxuDvZFji8OMsKrG176", "inserted_at": "1993-06-11T21:15:00Z", "interacted_at": null, "link_clicked_at": null, "metadata": { "external_id": "123e4567-e89b-12d3-a456-426614174000" }, "read_at": "1993-06-11T21:30:00Z", "recipient": "dr_grant", "scheduled_at": null, "seen_at": "1993-06-11T21:29:45Z", "source": { "__typename": "NotificationSource", "categories": [ "security", "emergency" ], "key": "security-breach-alert", "step_ref": "alert_step_1", "version_id": "123e4567-e89b-12d3-a456-426614174000", "workflow_recipient_run_id": "def01234-a56b-78c9-d012-345678901bcd", "workflow_run_id": "789e0123-f45a-67b8-c901-234567890abc" }, "status": "sent", "tenant": "ingen_isla_nublar", "updated_at": "1993-06-11T21:30:05Z", "workflow": "security-breach-alert" }, "properties": { "__typename": { "description": "The typename of the schema.", "example": "Message", "type": "string", "x-struct": null, "x-validate": null }, "actors": { "description": "One or more actors that are associated with this message. Note: this is a list that can contain up to 10 actors if the message is produced from a [batch](/designing-workflows/batch-function).", "items": { "$ref": "#/components/schemas/RecipientReference" }, "type": "array", "x-struct": null, "x-validate": null }, "archived_at": { "description": "Timestamp when the message was archived.", "format": "date-time", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "channel": { "description": "A configured channel, which is a way to route messages to a provider.", "example": { "created_at": "2021-01-01T00:00:00Z", "id": "01234567-89ab-cdef-0123-456789abcdef", "key": "my-sendgrid-channel", "name": "My Sendgrid Channel", "provider": "sendgrid", "type": "email", "updated_at": "2021-01-01T00:00:00Z" }, "properties": { "created_at": { "description": "The timestamp of when the channel was created.", "format": "date-time", "type": "string", "x-struct": null, "x-validate": null }, "id": { "description": "The unique identifier for the channel.", "type": "string", "x-struct": null, "x-validate": null }, "key": { "description": "Unique identifier for the channel within a project (immutable once created).", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "name": { "description": "The human-readable name of the channel.", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "provider": { "description": "The ID of the provider that this channel uses to deliver messages.", "type": "string", "x-struct": null, "x-validate": null }, "type": { "description": "The type of channel, determining what kind of messages it can send.", "enum": [ "email", "in_app", "in_app_feed", "in_app_guide", "sms", "push", "chat", "http" ], "type": "string", "x-struct": null, "x-validate": null }, "updated_at": { "description": "The timestamp of when the channel was last updated.", "format": "date-time", "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "id", "type", "provider", "created_at", "updated_at" ], "type": "object", "x-struct": null, "x-validate": null }, "channel_id": { "deprecated": true, "description": "Deprecated, use channel.id instead.", "format": "uuid", "type": "string", "x-struct": null, "x-validate": null }, "clicked_at": { "description": "Timestamp when the message was clicked.", "format": "date-time", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "data": { "additionalProperties": true, "description": "Data associated with the message’s workflow run. Includes the workflow trigger request’s `data` payload merged with any additional data returned by a [fetch function](/designing-workflows/fetch-function). For messages produced after a [batch step](/designing-workflows/batch-function), includes the payload `data` from the most-recent trigger request (the final `activity` in the batch).", "nullable": true, "type": "object", "x-struct": null, "x-validate": null }, "engagement_statuses": { "description": "A list of engagement statuses.", "example": [ "read", "seen" ], "items": { "description": "An engagement status for a message. Can be one of: read, seen, interacted, link_clicked, archived.", "enum": [ "seen", "read", "interacted", "link_clicked", "archived" ], "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null }, "id": { "description": "The unique identifier for the message.", "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 }, "interacted_at": { "description": "Timestamp when the message was interacted with.", "format": "date-time", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "link_clicked_at": { "description": "Timestamp when a link in the message was clicked.", "format": "date-time", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "metadata": { "additionalProperties": true, "description": "The metadata associated with the message.", "example": { "external_id": "123e4567-e89b-12d3-a456-426614174000" }, "nullable": true, "type": "object", "x-struct": null, "x-validate": null }, "read_at": { "description": "Timestamp when the message was read.", "format": "date-time", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "recipient": { "$ref": "#/components/schemas/RecipientReference" }, "scheduled_at": { "description": "Timestamp when the message was scheduled to be sent.", "format": "date-time", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "seen_at": { "description": "Timestamp when the message was seen.", "format": "date-time", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "source": { "description": "The workflow or guide that triggered the message.", "example": { "__typename": "NotificationSource", "categories": [ "collaboration" ], "key": "comment-created", "step_ref": "email_step_1", "version_id": "123e4567-e89b-12d3-a456-426614174000", "workflow_recipient_run_id": "456e7890-a12b-34c5-d678-456789012345", "workflow_run_id": "987e6543-e21c-34b5-c678-987654321000" }, "properties": { "__typename": { "example": "NotificationSource", "type": "string", "x-struct": null, "x-validate": null }, "categories": { "description": "The categories associated with the message.", "items": { "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null }, "key": { "description": "The key of the workflow or guide that triggered the message.", "type": "string", "x-struct": null, "x-validate": null }, "step_ref": { "description": "The step reference for the step in the workflow that generated the message.", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "type": { "description": "Whether this message was generated from a workflow, broadcast, or guide.", "enum": [ "broadcast", "workflow", "guide" ], "type": "string", "x-struct": null, "x-validate": null }, "version_id": { "description": "The ID of the version of the workflow or guide that triggered the message.", "format": "uuid", "type": "string", "x-struct": null, "x-validate": null }, "workflow_recipient_run_id": { "description": "The unique identifier for the workflow recipient run that generated this message. Only present for workflow/broadcast messages.", "format": "uuid", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "workflow_run_id": { "description": "The unique identifier for the workflow run that generated this message. Only present for workflow/broadcast messages.", "format": "uuid", "nullable": true, "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "__typename", "key", "version_id", "categories" ], "type": "object", "x-struct": null, "x-validate": null }, "status": { "description": "The message delivery status.", "enum": [ "queued", "sent", "delivered", "delivery_attempted", "undelivered", "not_sent", "bounced" ], "example": "sent", "type": "string", "x-struct": null, "x-validate": null }, "tenant": { "description": "The ID of the `tenant` associated with the message. Only present when a `tenant` is provided on a workflow trigger request.", "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": { "deprecated": true, "description": "The key of the workflow that generated the message.", "nullable": true, "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "__typename", "id", "channel_id", "status", "inserted_at", "updated_at", "recipient", "engagement_statuses", "source" ], "title": "Message", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.Message", "x-validate": null }, "SetTenantResponse": { "description": "The response from setting a tenant.", "example": { "__typename": "Tenant", "created_at": "1993-05-24T08:30:00Z", "id": "ingen_isla_nublar", "name": "Jurassic Park", "settings": { "branding": { "icon_url": "https://example.com/trex_silhouette_icon.png", "logo_url": "https://example.com/amber_fossil_logo.png", "primary_color": "#DF1A22", "primary_color_contrast": "#FFDE00" } }, "updated_at": "1993-06-11T15:45:00Z" }, "oneOf": [ { "$ref": "#/components/schemas/Tenant" } ], "title": "SetTenantResponse", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.SetTenantResponse", "x-validate": null }, "BulkSetTenantsRequest": { "description": "A request to set tenants in bulk.", "example": { "tenants": [ { "id": "tenant_1", "name": "Acme Corp, Inc." } ] }, "properties": { "tenants": { "description": "The tenants to be upserted.", "items": { "$ref": "#/components/schemas/InlineTenantRequest" }, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "tenants" ], "title": "BulkSetTenantsRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.BulkSetTenantsRequest", "x-validate": null }, "AudienceMemberRequest": { "description": "An audience member.", "example": { "tenant": "ingen_isla_nublar", "user": { "email": "ellie@ingen.net", "id": "dr_sattler", "name": "Dr. Ellie Sattler" } }, "properties": { "tenant": { "description": "The unique identifier for the tenant.", "example": "ingen_isla_nublar", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "user": { "allOf": [ { "$ref": "#/components/schemas/InlineIdentifyUserRequest" } ], "description": "A user object. At minimum must contain an `id` property.", "x-struct": null, "x-validate": null } }, "required": [ "user" ], "title": "AudienceMemberRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.AudienceMemberRequest", "x-validate": null }, "RemoveAudienceMembersRequest": { "description": "A request to remove a list of audience members.", "example": { "members": [ { "tenant": "ingen_isla_nublar", "user": { "email": "ellie@ingen.net", "id": "dr_sattler", "name": "Dr. Ellie Sattler" } } ] }, "properties": { "members": { "description": "A list of audience members to remove. You can remove up to 1,000 members per request.", "items": { "$ref": "#/components/schemas/AudienceMemberRequest" }, "nullable": false, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "members" ], "title": "RemoveAudienceMembersRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.RemoveAudienceMembersRequest", "x-validate": null }, "SetTenantRequest": { "additionalProperties": true, "description": "A tenant to be set in the system. You can supply any additional properties on the tenant object.", "example": { "name": "Jurassic Park", "settings": { "branding": { "icon_url": "https://example.com/trex_silhouette_icon.png", "logo_url": "https://example.com/amber_fossil_logo.png", "primary_color": "#DF1A22", "primary_color_contrast": "#FFDE00" } } }, "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 }, "name": { "description": "An optional name for the tenant.", "nullable": true, "type": "string", "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 } }, "title": "SetTenantRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.SetTenantRequest", "x-validate": null }, "MessageInAppFeedContent": { "description": "The content of an in-app feed message.", "example": { "__typename": "MessageInAppFeedContent", "blocks": [ { "content": "## Welcome to Isla Nublar", "name": "header", "rendered": "

Welcome to Isla Nublar

", "type": "markdown" }, { "content": "Your tour will begin shortly. During your visit, please:\n\n* Stay in the vehicles at all times\n* Do not feed or provoke the animals\n* Follow all staff instructions", "name": "body", "rendered": "

Your tour will begin shortly. During your visit, please:

", "type": "markdown" }, { "buttons": [ { "action": "https://example.com/park-map", "label": "View Map", "name": "map" }, { "action": "https://example.com/safety", "label": "Safety Protocols", "name": "safety" } ], "name": "actions", "type": "button_set" } ] }, "nullable": false, "properties": { "__typename": { "description": "The typename of the schema.", "example": "MessageInAppFeedContent", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "blocks": { "description": "The blocks of the message in an app feed.", "items": { "description": "A block in a message in an app feed.", "nullable": false, "oneOf": [ { "$ref": "#/components/schemas/MessageInAppFeedContentBlock" }, { "$ref": "#/components/schemas/MessageInAppFeedButtonSetBlock" } ], "type": "object", "x-struct": null, "x-validate": null }, "nullable": false, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "__typename", "blocks" ], "title": "MessageInAppFeedContent", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.MessageInAppFeedContent", "x-validate": null }, "DiscordChannelConnection": { "description": "Discord channel connection.", "example": { "channel_id": "123456789012345678" }, "properties": { "channel_id": { "description": "Discord channel ID.", "example": "123456789012345678", "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "channel_id" ], "title": "DiscordChannelConnection", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.DiscordChannelData.ChannelConnection", "x-validate": null }, "AuthenticationError": { "description": "Authentication error response", "example": { "code": "authorization", "message": "Access token not set.", "status": 403, "type": "authentication_error" }, "properties": { "code": { "description": "The error code.", "example": "authorization", "type": "string", "x-struct": null, "x-validate": null }, "message": { "description": "The error message.", "example": "Access token not set.", "type": "string", "x-struct": null, "x-validate": null }, "status": { "description": "The HTTP status code.", "example": 403, "type": "integer", "x-struct": null, "x-validate": null }, "type": { "description": "The error type.", "example": "authentication_error", "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "code", "message", "status", "type" ], "title": "AuthenticationError", "type": "object", "x-struct": null, "x-validate": null }, "AWSSNSPushChannelDataTargetARNsOnly": { "description": "AWS SNS push channel data.", "example": { "target_arns": [ "arn:aws:sns:us-west-2:123456789012:endpoint/GCM/gcmpushapp/5e3e9847-3183-3f18-a7e8-671c3a57d4b3" ] }, "properties": { "target_arns": { "description": "A list of platform endpoint ARNs. See [Setting up an Amazon SNS platform endpoint for mobile notifications](https://docs.aws.amazon.com/sns/latest/dg/mobile-platform-endpoint.html).", "example": [ "arn:aws:sns:us-west-2:123456789012:endpoint/GCM/gcmpushapp/5e3e9847-3183-3f18-a7e8-671c3a57d4b3" ], "items": { "description": "The ARN of a platform endpoint associated with a platform application and a device token. See [Setting up an Amazon SNS platform endpoint for mobile notifications](https://docs.aws.amazon.com/sns/latest/dg/mobile-platform-endpoint.html).", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "nullable": false, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "target_arns" ], "title": "AWSSNSPushChannelDataTargetARNsOnly", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.AWSSNSPushChannelDataTargetARNsOnly", "x-validate": null }, "DeleteSubscriptionsRequest": { "description": "A request to delete subscriptions for a set of recipients.", "example": { "recipients": [ "user_123" ] }, "properties": { "recipients": { "description": "The recipients of the subscription. You can subscribe up to 100 recipients to an object at a time.", "items": { "$ref": "#/components/schemas/RecipientReference" }, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "recipients" ], "title": "DeleteSubscriptionsRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.DeleteSubscriptionsRequest", "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 }, "SchedulesResponse": { "description": "A list of schedules.", "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" } ], "items": { "$ref": "#/components/schemas/Schedule" }, "title": "SchedulesResponse", "type": "array", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.SchedulesResponse", "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 }, "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 that channel ID.", "x-struct": null, "x-validate": null }, "commercial_subscribed": { "description": "Whether the recipient is subscribed to commercial communications. When false, the recipient will not receive commercial workflow notifications.", "nullable": true, "type": "boolean", "x-struct": null, "x-validate": null }, "workflows": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/PreferenceSetWorkflowCategorySetting" }, "description": "An object where the key is the workflow key and the values are the preference settings for that workflow.", "example": { "dinosaurs-loose": { "channel_types": { "email": false, "sms": true } }, "welcome-sequence": true }, "title": "PreferenceSetRequestWorkflows", "type": "object", "x-struct": null, "x-validate": null }, { "nullable": true, "x-struct": null, "x-validate": null } ], "description": "An object where the key is the workflow key and the values are the preference settings for that workflow.", "x-struct": null, "x-validate": null } }, "title": "PreferenceSetRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.PreferenceSetRequest", "x-validate": null }, "BulkDeleteObjectsRequest": { "description": "Request body for bulk deleting objects.", "example": { "object_ids": [ "obj_123", "obj_456", "obj_789" ] }, "properties": { "object_ids": { "description": "List of object IDs to delete.", "items": { "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "object_ids" ], "title": "BulkDeleteObjectsRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.Objects.BulkDeleteObjectsRequest", "x-validate": null }, "TeamsForMsTeamsProviderResponse": { "description": "The response from a Microsoft Teams provider request, containing a list of teams.", "example": { "ms_teams_teams": [ { "displayName": "Engineering Team", "id": "team-id-1" } ], "skip_token": "token-for-next-page" }, "properties": { "ms_teams_teams": { "description": "List of Microsoft Teams teams.", "items": { "properties": { "description": { "description": "Microsoft Teams team description.", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "displayName": { "description": "Microsoft Teams team display name.", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "id": { "description": "Microsoft Teams team ID.", "nullable": false, "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "id", "displayName" ], "type": "object", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null }, "skip_token": { "description": "[OData param](https://learn.microsoft.com/en-us/graph/query-parameters) passed to the Microsoft Graph API to retrieve the next page of results.", "nullable": true, "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "ms_teams_teams", "skip_token" ], "title": "TeamsForMsTeamsProviderResponse", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.TeamsForMsTeamsProviderResponse", "x-validate": null }, "BulkCreateSchedulesRequest": { "description": "A request to bulk create schedules. Accepts a list of schedules to create. Each schedule must have a single recipient. The recipients do not have to be unique.", "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" } ] }, "properties": { "schedules": { "description": "A list of schedules.", "items": { "description": "A schedule represents a recurring workflow execution.", "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 }, "recipient": { "$ref": "#/components/schemas/RecipientRequest" }, "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" ], "type": "object", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "schedules" ], "title": "BulkCreateSchedulesRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.BulkCreateSchedulesRequest", "x-validate": null }, "ListMessageEventsResponse": { "description": "Returns a paginated list of [delivery and engagement](/send-notifications/message-statuses) events for the specified message.", "example": { "items": [ { "__typename": "MessageEvent", "data": null, "id": "2FVHPWxRqNuXQ9krvNP5A6Z4qXe", "inserted_at": "2021-01-01T00:00:00Z", "recipient": "user_123", "type": "message.sent" } ], "page_info": { "__typename": "PageInfo", "after": null, "before": null, "page_size": 25 } }, "properties": { "items": { "description": "A list of message events.", "items": { "$ref": "#/components/schemas/MessageEvent" }, "type": "array", "x-struct": null, "x-validate": null }, "page_info": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "items", "page_info" ], "title": "ListMessageEventsResponse", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.ListMessageEventsResponse", "x-validate": null }, "SubscriptionsResponse": { "description": "A response containing a list of subscriptions.", "example": [ { "__typename": "Subscription", "inserted_at": "2021-01-01T00:00:00Z", "object": { "__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" }, "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": "2021-01-01T00:00:00Z" } ], "items": { "$ref": "#/components/schemas/Subscription" }, "title": "SubscriptionsResponse", "type": "array", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.SubscriptionsResponse", "x-validate": null }, "ChannelsForSlackProviderResponse": { "description": "The response from a Slack provider request, containing a list of channels.", "example": { "next_cursor": null, "slack_channels": [ { "context_team_id": "T01234567890", "id": "C01234567890", "is_im": false, "is_private": false, "name": "general" } ] }, "properties": { "next_cursor": { "description": "Paginate through collections of data by setting the cursor parameter to a next_cursor attribute returned by a previous request's response_metadata. Default value fetches the first \"page\" of the collection.", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "slack_channels": { "description": "List of Slack channels.", "items": { "description": "A Slack channel.", "properties": { "context_team_id": { "description": "The team ID that the Slack channel belongs to.", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "id": { "description": "A Slack channel ID from the Slack provider.", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "is_im": { "description": "Whether the Slack channel is an IM channel.", "nullable": false, "type": "boolean", "x-struct": null, "x-validate": null }, "is_private": { "description": "Whether the Slack channel is private.", "nullable": false, "type": "boolean", "x-struct": null, "x-validate": null }, "name": { "description": "Slack channel name.", "nullable": false, "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "id", "name", "is_private", "is_im", "context_team_id" ], "type": "object", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "slack_channels", "next_cursor" ], "title": "ChannelsForSlackProviderResponse", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.ChannelsForSlackProviderResponse", "x-validate": null }, "Condition": { "description": "A condition to be evaluated.", "example": { "argument": "frog_genome", "operator": "contains", "variable": "specimen.dna_sequence" }, "properties": { "argument": { "description": "The argument value to compare against in the condition.", "example": "some_property", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "operator": { "description": "The operator to use in the condition evaluation.", "enum": [ "equal_to", "not_equal_to", "greater_than", "less_than", "greater_than_or_equal_to", "less_than_or_equal_to", "contains", "not_contains", "empty", "not_empty", "exists", "not_exists", "contains_all", "is_timestamp", "is_not_timestamp", "is_timestamp_on_or_after", "is_timestamp_before", "is_timestamp_on_or_after_date", "is_timestamp_before_date", "is_timestamp_between", "is_between", "is_audience_member", "is_not_audience_member" ], "example": "equal_to", "type": "string", "x-struct": null, "x-validate": null }, "variable": { "description": "The variable to be evaluated in the condition.", "example": "recipient.property", "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "variable", "operator", "argument" ], "title": "Condition", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.Condition", "x-validate": null }, "PreferenceSetChannelSetting": { "description": "A set of settings for a specific channel. Currently, this can only be a list of conditions to apply.", "example": { "conditions": [ { "argument": "US", "operator": "equal_to", "variable": "recipient.country_code" } ] }, "properties": { "conditions": { "description": "A list of conditions to apply to a specific channel.", "items": { "$ref": "#/components/schemas/Condition" }, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "conditions" ], "title": "PreferenceSetChannelSetting", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.PreferenceSetChannels.PreferenceSetChannelSetting", "x-validate": null }, "CancelWorkflowRequest": { "description": "When invoked using a specific workflow key and cancellation key, will cancel any queued workflow runs associated with that key/cancellation key pair. Can optionally provide one or more recipients to scope the request to.", "example": { "cancellation_key": "cancel-workflow-123", "recipients": [ "jhammond" ] }, "properties": { "cancellation_key": { "description": "An optional key that is used to reference a specific workflow trigger request when issuing a [workflow cancellation](/send-notifications/canceling-workflows) request. Must be provided while triggering a workflow in order to enable subsequent cancellation. Should be unique across trigger requests to avoid unintentional cancellations.", "type": "string", "x-struct": null, "x-validate": null }, "recipients": { "description": "A list of recipients to cancel the notification for. If omitted, cancels for all recipients associated with the cancellation key.", "items": { "$ref": "#/components/schemas/RecipientReference" }, "nullable": true, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "cancellation_key" ], "title": "CancelWorkflowRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.CancelWorkflowRequest", "x-validate": null }, "ChannelDataRequest": { "description": "A request to set channel data for a type of channel.", "example": { "data": { "tokens": [ "push_token_1" ] } }, "properties": { "data": { "description": "Channel data for a given channel type.", "nullable": false, "oneOf": [ { "$ref": "#/components/schemas/PushChannelDataTokensOnly" }, { "$ref": "#/components/schemas/PushChannelDataDevicesOnly" }, { "$ref": "#/components/schemas/AWSSNSPushChannelDataTargetARNsOnly" }, { "$ref": "#/components/schemas/AWSSNSPushChannelDataDevicesOnly" }, { "$ref": "#/components/schemas/OneSignalChannelDataPlayerIdsOnly" }, { "$ref": "#/components/schemas/SlackChannelData" }, { "$ref": "#/components/schemas/MsTeamsChannelData" }, { "$ref": "#/components/schemas/DiscordChannelData" } ], "type": "object", "x-struct": null, "x-validate": null } }, "required": [ "data" ], "title": "ChannelDataRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.ChannelDataRequest", "x-validate": null }, "MessageDeliveryLogRequest": { "description": "A message delivery log request.", "example": { "body": { "html_content": "" }, "headers": { "Content-Type": "application/json" }, "host": "localhost", "method": "GET", "path": "/", "query": "?foo=bar" }, "properties": { "body": { "description": "The body content that was sent with the request.", "oneOf": [ { "type": "string", "x-struct": null, "x-validate": null }, { "additionalProperties": true, "type": "object", "x-struct": null, "x-validate": null } ], "type": "object", "x-struct": null, "x-validate": null }, "headers": { "additionalProperties": true, "description": "The headers that were sent with the request.", "nullable": true, "type": "object", "x-struct": null, "x-validate": null }, "host": { "description": "The host to which the request was sent.", "example": "localhost", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "method": { "description": "The HTTP method used for the request.", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH" ], "example": "GET", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "path": { "description": "The path of the URL that was requested.", "example": "/", "nullable": false, "type": "string", "x-struct": null, "x-validate": null }, "query": { "description": "The query string of the URL that was requested.", "example": "?foo=bar", "nullable": true, "type": "string", "x-struct": null, "x-validate": null } }, "title": "MessageDeliveryLogRequest", "type": "object", "x-struct": "Elixir.SwitchboardWeb.V1.Specs.MessageDeliveryLog.Request", "x-validate": null } }, "securitySchemes": { "BearerAuth": { "bearerFormat": "JWT", "scheme": "bearer", "type": "http" } } }, "info": { "title": "Knock API", "version": "1.0" }, "openapi": "3.0.0", "paths": { "/v1/objects/{collection}/{object_id}/preferences/{id}/workflows": { "put": { "callbacks": {}, "deprecated": true, "description": "Updates the workflow preferences for an object's preference set.", "operationId": "updateObjectPreferenceWorkflows", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreferenceSet" } } }, "description": "OK" } }, "summary": "Update workflows in preference set", "tags": [ "Objects", "Preferences" ], "x-ratelimit-tier": 3 } }, "/v1/users/{user_id}/guides/messages/seen": { "put": { "callbacks": {}, "description": "Records that a guide has been seen by a user, triggering any associated seen events.", "operationId": "markUserGuideAsSeen (2)", "parameters": [ { "description": "The unique identifier of the user.", "in": "path", "name": "user_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "requestBody": { "content": { "application/json": { "example": { "channel_id": "123e4567-e89b-12d3-a456-426614174000", "content": { "body": "Limited spots available for today's behind-the-scenes DNA extraction demonstration.", "title": "DNA Lab Tour Available" }, "data": { "next_time": "14:30", "spots_left": 8, "tour_id": "dna_lab_tour" }, "guide_id": "7e9dc78c-b3b1-4127-a54e-71f1899b831a", "guide_key": "tour_notification", "guide_step_ref": "lab_tours", "is_final": false, "metadata": { "cta": "Reserve Spot", "theme": "amber", "type": "banner" }, "tenant": "ingen_isla_nublar" }, "schema": { "$ref": "#/components/schemas/GuideActionRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuideActionResponse" } } }, "description": "OK" } }, "summary": "Mark guide as seen", "tags": [ "Guides", "Users" ], "x-ratelimit-tier": 2 } }, "/v1/tenants/{id}": { "delete": { "callbacks": {}, "description": "Delete a tenant and all associated data. This operation cannot be undone.", "operationId": "deleteTenant", "parameters": [ { "description": "The unique identifier for the tenant.", "in": "path", "name": "id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "204": { "description": "No Content" } }, "summary": "Delete a tenant", "tags": [ "Tenants" ], "x-ratelimit-tier": 2 }, "get": { "callbacks": {}, "description": "Get a tenant by ID.", "operationId": "getTenant", "parameters": [ { "description": "The unique identifier for the tenant.", "in": "path", "name": "id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "When true, merges environment-level default preferences into the tenant's `settings.preference_set` field before returning the response. Defaults to false.", "in": "query", "name": "resolve_full_preference_settings", "required": false, "schema": { "type": "boolean", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } }, "description": "OK" } }, "summary": "Get a tenant", "tags": [ "Tenants" ], "x-ratelimit-tier": 4 }, "put": { "callbacks": {}, "description": "Sets a tenant within an environment, performing an upsert operation. Any existing properties will be merged with the incoming properties.", "operationId": "setTenant", "parameters": [ { "description": "The unique identifier for the tenant.", "in": "path", "name": "id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "When true, merges environment-level default preferences into the tenant's `settings.preference_set` field before returning the response. Defaults to false.", "in": "query", "name": "resolve_full_preference_settings", "required": false, "schema": { "type": "boolean", "x-struct": null, "x-validate": null } } ], "requestBody": { "content": { "application/json": { "example": { "name": "Jurassic Park", "settings": { "branding": { "icon_url": "https://example.com/trex_silhouette_icon.png", "logo_url": "https://example.com/amber_fossil_logo.png", "primary_color": "#DF1A22", "primary_color_contrast": "#FFDE00" } } }, "schema": { "$ref": "#/components/schemas/SetTenantRequest" } } }, "description": "Tenant", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetTenantResponse" } } }, "description": "OK" } }, "summary": "Set a tenant", "tags": [ "Tenants" ], "x-ratelimit-tier": 3 } }, "/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.\n\nYou 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.\n\n**Notes:**\n* When making this call from a client-side environment, use your publishable key along with a user token.\n* 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.\n* Any [attachments](/integrations/email/attachments) present in trigger data are automatically excluded from both the `data` and `activities` fields of `UserInAppFeedResponse`.\n", "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", "Users" ], "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", "Users" ], "x-ratelimit-tier": 4 } }, "/v1/objects/{collection}/{object_id}/preferences/{id}/channel_types/{type}": { "put": { "callbacks": {}, "deprecated": true, "description": "Updates a specific channel type preference for an object's preference set.", "operationId": "updateObjectPreferenceChannelType", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreferenceSet" } } }, "description": "OK" } }, "summary": "Update a channel type preference", "tags": [ "Objects", "Preferences" ], "x-ratelimit-tier": 3 } }, "/v1/integrations/census/custom-destination": { "post": { "callbacks": {}, "description": "Processes a Census custom destination RPC request.", "operationId": "processCensusRpcRequest", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "id": { "description": "The unique identifier for the RPC request.", "type": "string", "x-struct": null, "x-validate": null }, "jsonrpc": { "description": "The JSON-RPC version.", "type": "string", "x-struct": null, "x-validate": null }, "method": { "description": "The method name to execute.", "type": "string", "x-struct": null, "x-validate": null }, "params": { "additionalProperties": true, "description": "The parameters for the method.", "type": "object", "x-struct": null, "x-validate": null } }, "required": [ "id", "method", "jsonrpc" ], "type": "object", "x-struct": null, "x-validate": null } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "id": { "description": "The request ID.", "type": "string", "x-struct": null, "x-validate": null }, "result": { "additionalProperties": true, "description": "The result of the RPC call.", "type": "object", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null } } }, "description": "OK" } }, "summary": "Process a Census RPC request", "tags": [ "Integrations" ], "x-ratelimit-tier": 3 } }, "/v1/bulk_operations/{id}": { "get": { "callbacks": {}, "description": "Retrieves a bulk operation (if it exists) and displays the current state of it.", "operationId": "getBulkOperation", "parameters": [ { "description": "The ID of the bulk operation to retrieve.", "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/BulkOperation" } } }, "description": "OK" } }, "summary": "Get bulk operation", "tags": [ "Bulk operations" ], "x-ratelimit-tier": 4 } }, "/v1/users/{user_id}/subscriptions": { "get": { "callbacks": {}, "description": "Retrieves a paginated list of subscriptions for a specific user, in descending order.", "operationId": "listSubscriptionsForUser", "parameters": [ { "description": "The user ID to list subscriptions for.", "in": "path", "name": "user_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Associated resources to include in the response.", "in": "query", "name": "include[]", "required": false, "schema": { "items": { "enum": [ "preferences" ], "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } }, { "description": "Only returns subscriptions for the specified object references.", "in": "query", "name": "objects[]", "required": false, "schema": { "items": { "$ref": "#/components/schemas/RecipientReference" }, "type": "array", "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/ListSubscriptionsResponse" } } }, "description": "OK" } }, "summary": "List user subscriptions", "tags": [ "Subscriptions", "Users" ], "x-ratelimit-tier": 4 } }, "/v1/users/{user_id}": { "delete": { "callbacks": {}, "description": "Permanently delete a user and all associated data.", "operationId": "deleteUser", "parameters": [ { "description": "The ID of the user to delete.", "in": "path", "name": "user_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "204": { "description": "No Content" } }, "summary": "Delete user", "tags": [ "Users" ], "x-ratelimit-tier": 2 }, "get": { "callbacks": {}, "description": "Retrieve a specific user by their ID.", "operationId": "getUser", "parameters": [ { "description": "The ID of the user to retrieve.", "in": "path", "name": "user_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } }, "description": "OK" } }, "summary": "Get user", "tags": [ "Users" ], "x-ratelimit-tier": 4 }, "put": { "callbacks": {}, "description": "Create or update a user with the provided identification data. When you identify an existing user, the system merges the properties you specific with what is currently set on the user, updating only the fields included in your requests.", "operationId": "identifyUser", "parameters": [ { "description": "The unique identifier of the user.", "in": "path", "name": "user_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "requestBody": { "content": { "application/json": { "example": { "channel_data": { "97c5837d-c65c-4d54-aa39-080eeb81c69d": { "tokens": [ "push_token_123" ] } }, "email": "ian.malcolm@chaos.theory", "name": "Dr. Ian Malcolm", "preferences": { "default": { "channel_types": { "email": true }, "workflows": { "dinosaurs-loose": { "channel_types": { "email": true } } } } }, "timezone": "America/New_York" }, "schema": { "$ref": "#/components/schemas/IdentifyUserRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } }, "description": "OK" } }, "summary": "Identify user", "tags": [ "Users" ], "x-ratelimit-tier": 3 } }, "/v1/messages/{message_id}/delivery_logs": { "get": { "callbacks": {}, "description": "Returns a paginated list of delivery logs for the specified message.", "operationId": "listMessageDeliveryLogs", "parameters": [ { "description": "The ID of the message to fetch delivery logs for.", "in": "path", "name": "message_id", "required": true, "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/ListMessageDeliveryLogsResponse" } } }, "description": "OK" } }, "summary": "List delivery logs", "tags": [ "Messages" ], "x-ratelimit-tier": 3, "x-retention-policy": true } }, "/v1/messages": { "get": { "callbacks": {}, "description": "Returns a paginated list of messages for the current environment.", "operationId": "listMessages", "parameters": [ { "description": "The cursor to fetch entries after.", "in": "query", "name": "after", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The cursor to fetch entries before.", "in": "query", "name": "before", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The number of items per page (defaults to 50).", "in": "query", "name": "page_size", "required": false, "schema": { "type": "integer", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to items with the corresponding tenant.", "example": "tenant_123", "in": "query", "name": "tenant", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to items with the corresponding channel ID.", "example": "123e4567-e89b-12d3-a456-426614174000", "in": "query", "name": "channel_id", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to messages with the given delivery status.", "example": [ "delivered" ], "in": "query", "name": "status[]", "required": false, "schema": { "items": { "enum": [ "queued", "sent", "delivered", "delivery_attempted", "undelivered", "not_sent", "bounced" ], "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to messages with the given engagement status.", "example": [ "unread" ], "in": "query", "name": "engagement_status[]", "required": false, "schema": { "items": { "enum": [ "seen", "unseen", "read", "unread", "archived", "unarchived", "link_clicked", "interacted" ], "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to only the message IDs given (max 50). Note: when using this option, the results will be subject to any other filters applied to the query.", "example": [ "1jNaXzB2RZX3LY8wVQnfCKyPnv7" ], "in": "query", "name": "message_ids[]", "required": false, "schema": { "items": { "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to messages related to any of the provided categories.", "example": [ "workflow_123" ], "in": "query", "name": "workflow_categories[]", "required": false, "schema": { "items": { "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to messages triggered by the given workflow key.", "example": "comment-created", "in": "query", "name": "source", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to messages associated with the top-level workflow run ID returned by the workflow trigger request.", "example": "123e4567-e89b-12d3-a456-426614174000", "in": "query", "name": "workflow_run_id", "required": false, "schema": { "format": "uuid", "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to messages for a specific recipient's workflow run.", "example": "123e4567-e89b-12d3-a456-426614174000", "in": "query", "name": "workflow_recipient_run_id", "required": false, "schema": { "format": "uuid", "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to only messages that were generated with the given data. See [trigger data filtering](/api-reference/overview/trigger-data-filtering) for more information.", "example": "{\"comment_id\": \"123\"}", "in": "query", "name": "trigger_data", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to items inserted after the given date.", "example": "2025-01-01T00:00:00Z", "in": "query", "name": "inserted_at.gt", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to items inserted after or on the given date.", "example": "2025-01-01T00:00:00Z", "in": "query", "name": "inserted_at.gte", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to items inserted before the given date.", "example": "2025-01-01T00:00:00Z", "in": "query", "name": "inserted_at.lt", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to items inserted before or on the given date.", "example": "2025-01-01T00:00:00Z", "in": "query", "name": "inserted_at.lte", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMessagesResponse" } } }, "description": "OK" } }, "summary": "List messages", "tags": [ "Messages" ], "x-ratelimit-tier": 4, "x-retention-policy": true } }, "/v1/messages/{message_id}/unseen": { "delete": { "callbacks": {}, "description": "Marks a message as `unseen`. This reverses the `seen` state. Read more about message engagement statuses [here](/send-notifications/message-statuses#engagement-status).", "operationId": "markMessageUnseen (2)", "parameters": [ { "description": "The unique identifier for the message.", "example": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "in": "path", "name": "message_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Message" } ], "example": { "__typename": "Message", "actors": [ "user_123" ], "archived_at": null, "channel_id": "123e4567-e89b-12d3-a456-426614174000", "clicked_at": null, "data": { "foo": "bar" }, "engagement_statuses": [], "id": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "inserted_at": "2021-01-01T00:00:00Z", "interacted_at": null, "link_clicked_at": null, "metadata": { "external_id": "123e4567-e89b-12d3-a456-426614174000" }, "read_at": null, "recipient": "user_123", "scheduled_at": null, "seen_at": null, "source": { "__typename": "NotificationSource", "categories": [ "collaboration" ], "key": "comment-created", "step_ref": "email_step_1", "version_id": "123e4567-e89b-12d3-a456-426614174000" }, "status": "sent", "tenant": "tenant_123", "updated_at": "2021-01-01T00:00:00Z", "workflow": "comment-created" }, "x-struct": null, "x-validate": null } } }, "description": "OK" } }, "summary": "Mark message as unseen", "tags": [ "Messages" ], "x-ratelimit-tier": 2, "x-retention-policy": true } }, "/v1/users/{user_id}/preferences/{id}/categories/{key}": { "put": { "callbacks": {}, "deprecated": true, "description": "Updates a single category in a specific user preference set. This operation is deprecated.", "operationId": "updateUserPreferenceCategory", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreferenceSet" } } }, "description": "OK" } }, "summary": "Update category in user preference set", "tags": [ "Users", "Preferences" ], "x-ratelimit-tier": 3 } }, "/v1/users/{user_id}/guides/messages/{message_id}/seen": { "put": { "callbacks": {}, "description": "Records that a guide has been seen by a user, triggering any associated seen events.", "operationId": "markUserGuideAsSeen", "parameters": [ { "description": "The unique identifier of the user.", "in": "path", "name": "user_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "requestBody": { "content": { "application/json": { "example": { "channel_id": "123e4567-e89b-12d3-a456-426614174000", "content": { "body": "Limited spots available for today's behind-the-scenes DNA extraction demonstration.", "title": "DNA Lab Tour Available" }, "data": { "next_time": "14:30", "spots_left": 8, "tour_id": "dna_lab_tour" }, "guide_id": "7e9dc78c-b3b1-4127-a54e-71f1899b831a", "guide_key": "tour_notification", "guide_step_ref": "lab_tours", "is_final": false, "metadata": { "cta": "Reserve Spot", "theme": "amber", "type": "banner" }, "tenant": "ingen_isla_nublar" }, "schema": { "$ref": "#/components/schemas/GuideActionRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuideActionResponse" } } }, "description": "OK" } }, "summary": "Mark guide as seen", "tags": [ "Guides", "Users" ], "x-ratelimit-tier": 2 } }, "/v1/objects/{collection}/bulk/delete": { "post": { "callbacks": {}, "description": "Bulk deletes objects from the specified collection.", "operationId": "bulkDeleteObjects", "parameters": [ { "description": "The collection this object belongs to.", "in": "path", "name": "collection", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "requestBody": { "content": { "application/json": { "example": { "object_ids": [ "obj_123", "obj_456", "obj_789" ] }, "schema": { "$ref": "#/components/schemas/BulkDeleteObjectsRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOperation" } } }, "description": "OK" } }, "summary": "Bulk delete objects", "tags": [ "Objects", "Bulk operations" ], "x-ratelimit-tier": 1 } }, "/v1/providers/slack/{channel_id}/channels": { "get": { "callbacks": {}, "description": "List Slack channels for a Slack workspace.", "operationId": "listChannelsForSlackProvider", "parameters": [ { "description": "The ID of the Knock Slack channel to get channels for.", "in": "path", "name": "channel_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "A JSON encoded string containing the access token object reference.", "example": "{\"collection\":\"projects\",\"object_id\":\"project_123\"}", "in": "query", "name": "access_token_object", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Paginate through collections of data by setting the cursor parameter to a next_cursor attribute returned by a previous request's response_metadata. Default value fetches the first \"page\" of the collection.", "in": "query", "name": "query_options.cursor", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The maximum number of channels to return. Defaults to 200.", "in": "query", "name": "query_options.limit", "required": false, "schema": { "type": "integer", "x-struct": null, "x-validate": null } }, { "description": "Set to true to exclude archived channels from the list. Defaults to `true` when not explicitly provided.", "in": "query", "name": "query_options.exclude_archived", "required": false, "schema": { "type": "boolean", "x-struct": null, "x-validate": null } }, { "description": "Mix and match channel types by providing a comma-separated list of any combination of public_channel, private_channel, mpim, im. Defaults to `\"public_channel,private_channel\"`. If the user's Slack ID is unavailable, this option is ignored and only public channels are returned.", "in": "query", "name": "query_options.types", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Encoded team ID (T1234) to list channels in, required if org token is used.", "in": "query", "name": "query_options.team_id", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelsForSlackProviderResponse" } } }, "description": "OK" }, "403": { "content": { "application/json": { "schema": { "description": "Authentication error response", "example": { "code": "authorization", "message": "Access token not set.", "status": 403, "type": "authentication_error" }, "properties": { "code": { "description": "The error code.", "example": "authorization", "type": "string", "x-struct": null, "x-validate": null }, "message": { "description": "The error message.", "example": "Access token not set.", "type": "string", "x-struct": null, "x-validate": null }, "status": { "description": "The HTTP status code.", "example": 403, "type": "integer", "x-struct": null, "x-validate": null }, "type": { "description": "The error type.", "example": "authentication_error", "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "code", "message", "status", "type" ], "title": "AuthenticationError", "type": "object", "x-struct": null, "x-validate": null } } }, "description": "Forbidden" } }, "summary": "List channels", "tags": [ "Providers", "Slack" ], "x-ratelimit-tier": 2 } }, "/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", "Objects" ], "x-ratelimit-tier": 4 } }, "/v1/workflows/{key}/trigger": { "post": { "callbacks": {}, "description": "Trigger a workflow (specified by the key) to run for the given recipients, using the parameters provided. Returns an identifier for the workflow run request. All workflow runs are executed asynchronously. This endpoint also handles [inline identifications](/managing-recipients/identifying-recipients#inline-identifying-recipients) for the `actor`, `recipient`, and `tenant` fields.", "operationId": "triggerWorkflow (2)", "parameters": [ { "description": "Key of the workflow to trigger.", "in": "path", "name": "key", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "requestBody": { "content": { "application/json": { "example": { "actor": "mr_dna", "cancellation_key": "isla_nublar_incident_1993", "data": { "affected_areas": [ "visitor_center", "raptor_pen", "trex_paddock" ], "attraction_id": "paddock_rex_01", "evacuation_protocol": "active", "message": "Life finds a way", "severity": "critical", "system_status": "fences_failing" }, "recipients": [ "dr_grant", "dr_sattler", "dr_malcolm" ], "tenant": "ingen_isla_nublar" }, "schema": { "$ref": "#/components/schemas/TriggerWorkflowRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerWorkflowResponse" } } }, "description": "OK" } }, "summary": "Trigger workflow", "tags": [ "Workflows" ], "x-idempotent": true, "x-ratelimit-tier": 5 } }, "/v1/users/{user_id}/guides/messages/archived": { "delete": { "callbacks": {}, "description": "Records that a guide has been unarchived, triggering any associated unarchived events.", "operationId": "markUserGuideAsUnarchived", "parameters": [ { "description": "The unique identifier of the user.", "in": "path", "name": "user_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuideActionRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuideActionResponse" } } }, "description": "OK" } }, "summary": "Mark guide as unarchived", "tags": [ "Guides", "Users" ], "x-ratelimit-tier": 2 }, "put": { "callbacks": {}, "description": "Records that a guide has been archived by a user, triggering any associated archived events.", "operationId": "markUserGuideAsArchived (2)", "parameters": [ { "description": "The unique identifier of the user.", "in": "path", "name": "user_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuideActionRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuideActionResponse" } } }, "description": "OK" } }, "summary": "Mark guide as archived", "tags": [ "Guides", "Users" ], "x-ratelimit-tier": 2 } }, "/v1/messages/batch/unarchived": { "post": { "callbacks": {}, "description": "Marks the given messages as unarchived. This reverses the `archived` state. Archived messages are hidden from the default message list in the feed but can still be accessed and unarchived later.", "operationId": "batchMarkMessagesAsUnarchived", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "message_ids": [ "2w3YUpTTOxuDvZFji8OMsKrG176", "2w3YVRbPXMIh8Zq6oBFcVDA5xes" ] }, "schema": { "$ref": "#/components/schemas/BatchMessagesStatusRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "The list of messages that were updated.", "example": [ { "__typename": "Message", "actors": [ "user_123" ], "archived_at": null, "channel_id": "123e4567-e89b-12d3-a456-426614174000", "clicked_at": null, "data": { "foo": "bar" }, "engagement_statuses": [ "seen" ], "id": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "inserted_at": "2021-01-01T00:00:00Z", "interacted_at": null, "link_clicked_at": null, "metadata": { "external_id": "123e4567-e89b-12d3-a456-426614174000" }, "read_at": null, "recipient": "user_123", "scheduled_at": null, "seen_at": "2025-01-01T00:01:00Z", "source": { "__typename": "NotificationSource", "categories": [ "collaboration" ], "key": "comment-created", "version_id": "123e4567-e89b-12d3-a456-426614174000" }, "status": "sent", "tenant": "tenant_123", "updated_at": "2021-01-01T00:00:00Z", "workflow": "comment-created" } ], "items": { "allOf": [ { "$ref": "#/components/schemas/Message" } ], "example": { "__typename": "Message", "actors": [ "user_123" ], "archived_at": null, "channel_id": "123e4567-e89b-12d3-a456-426614174000", "clicked_at": null, "data": { "foo": "bar" }, "engagement_statuses": [ "seen" ], "id": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "inserted_at": "2021-01-01T00:00:00Z", "interacted_at": null, "link_clicked_at": null, "metadata": { "external_id": "123e4567-e89b-12d3-a456-426614174000" }, "read_at": null, "recipient": "user_123", "scheduled_at": null, "seen_at": "2025-01-01T00:01:00Z", "source": { "__typename": "NotificationSource", "categories": [ "collaboration" ], "key": "comment-created", "version_id": "123e4567-e89b-12d3-a456-426614174000" }, "status": "sent", "tenant": "tenant_123", "updated_at": "2021-01-01T00:00:00Z", "workflow": "comment-created" }, "x-struct": null, "x-validate": null }, "title": "BatchListMessagesResponse", "type": "array", "x-struct": null, "x-validate": null } } }, "description": "OK" } }, "summary": "Mark messages as unarchived", "tags": [ "Messages" ], "x-ratelimit-tier": 3, "x-retention-policy": true } }, "/v1/messages/{message_id}/unread": { "delete": { "callbacks": {}, "description": "Marks a message as `unread`. This reverses the `read` state. Read more about message engagement statuses [here](/send-notifications/message-statuses#engagement-status).", "operationId": "markMessageUnread (2)", "parameters": [ { "description": "The unique identifier for the message.", "example": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "in": "path", "name": "message_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Message" } ], "example": { "__typename": "Message", "actors": [ "user_123" ], "archived_at": null, "channel_id": "123e4567-e89b-12d3-a456-426614174000", "clicked_at": null, "data": { "foo": "bar" }, "engagement_statuses": [ "seen" ], "id": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "inserted_at": "2021-01-01T00:00:00Z", "interacted_at": null, "link_clicked_at": null, "metadata": { "external_id": "123e4567-e89b-12d3-a456-426614174000" }, "read_at": null, "recipient": "user_123", "scheduled_at": null, "seen_at": "2025-01-01T00:01:00Z", "source": { "__typename": "NotificationSource", "categories": [ "collaboration" ], "key": "comment-created", "step_ref": "email_step_1", "version_id": "123e4567-e89b-12d3-a456-426614174000" }, "status": "sent", "tenant": "tenant_123", "updated_at": "2021-01-01T00:00:00Z", "workflow": "comment-created" }, "x-struct": null, "x-validate": null } } }, "description": "OK" } }, "summary": "Mark message as unread", "tags": [ "Messages" ], "x-ratelimit-tier": 2, "x-retention-policy": true } }, "/v1/providers/ms-teams/{channel_id}/auth_check": { "get": { "callbacks": {}, "description": "Check if a connection to Microsoft Teams has been authorized for a given Microsoft Teams tenant object.", "operationId": "msTeamsProviderAuthCheck", "parameters": [ { "description": "The ID of the Knock Microsoft Teams channel to check.", "in": "path", "name": "channel_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "A JSON encoded string containing the Microsoft Teams tenant object reference.", "example": "{\"collection\":\"projects\",\"object_id\":\"project_123\"}", "in": "query", "name": "ms_teams_tenant_object", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MsTeamsAuthCheckResponse" } } }, "description": "OK" } }, "summary": "Check auth", "tags": [ "Providers", "Microsoft Teams" ], "x-ratelimit-tier": 2 } }, "/v1/messages/{message_id}/seen": { "delete": { "callbacks": {}, "description": "Marks a message as `unseen`. This reverses the `seen` state. Read more about message engagement statuses [here](/send-notifications/message-statuses#engagement-status).", "operationId": "markMessageUnseen", "parameters": [ { "description": "The unique identifier for the message.", "example": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "in": "path", "name": "message_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Message" } ], "example": { "__typename": "Message", "actors": [ "user_123" ], "archived_at": null, "channel_id": "123e4567-e89b-12d3-a456-426614174000", "clicked_at": null, "data": { "foo": "bar" }, "engagement_statuses": [], "id": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "inserted_at": "2021-01-01T00:00:00Z", "interacted_at": null, "link_clicked_at": null, "metadata": { "external_id": "123e4567-e89b-12d3-a456-426614174000" }, "read_at": null, "recipient": "user_123", "scheduled_at": null, "seen_at": null, "source": { "__typename": "NotificationSource", "categories": [ "collaboration" ], "key": "comment-created", "step_ref": "email_step_1", "version_id": "123e4567-e89b-12d3-a456-426614174000" }, "status": "sent", "tenant": "tenant_123", "updated_at": "2021-01-01T00:00:00Z", "workflow": "comment-created" }, "x-struct": null, "x-validate": null } } }, "description": "OK" } }, "summary": "Mark message as unseen", "tags": [ "Messages" ], "x-ratelimit-tier": 2, "x-retention-policy": true }, "put": { "callbacks": {}, "description": "Marks a message as `seen`. This indicates that the user has viewed the message in their feed or inbox. Read more about message engagement statuses [here](/send-notifications/message-statuses#engagement-status).", "operationId": "markMessageSeen", "parameters": [ { "description": "The unique identifier for the message.", "example": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "in": "path", "name": "message_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Message" } ], "example": { "__typename": "Message", "actors": [ "user_123" ], "archived_at": null, "channel_id": "123e4567-e89b-12d3-a456-426614174000", "clicked_at": null, "data": { "foo": "bar" }, "engagement_statuses": [ "seen" ], "id": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "inserted_at": "2021-01-01T00:00:00Z", "interacted_at": null, "link_clicked_at": null, "metadata": { "external_id": "123e4567-e89b-12d3-a456-426614174000" }, "read_at": null, "recipient": "user_123", "scheduled_at": null, "seen_at": "2025-01-01T00:01:00Z", "source": { "__typename": "NotificationSource", "categories": [ "collaboration" ], "key": "comment-created", "step_ref": "email_step_1", "version_id": "123e4567-e89b-12d3-a456-426614174000" }, "status": "sent", "tenant": "tenant_123", "updated_at": "2021-01-01T00:00:00Z", "workflow": "comment-created" }, "x-struct": null, "x-validate": null } } }, "description": "OK" } }, "summary": "Mark message as seen", "tags": [ "Messages" ], "x-ratelimit-tier": 2, "x-retention-policy": true } }, "/v1/users/{user_id}/channel_data/{channel_id}": { "delete": { "callbacks": {}, "description": "Deletes channel data for a specific user and channel ID.", "operationId": "unsetUserChannelData", "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": "channel_id", "required": true, "schema": { "format": "uuid", "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "204": { "description": "No Content" } }, "summary": "Unset channel data", "tags": [ "Channel data", "Users" ], "x-ratelimit-tier": 3 }, "get": { "callbacks": {}, "description": "Retrieves the channel data for a specific user and channel ID.", "operationId": "getUserChannelData", "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": "channel_id", "required": true, "schema": { "format": "uuid", "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelData" } } }, "description": "OK" } }, "summary": "Get channel data", "tags": [ "Channel data", "Users" ], "x-ratelimit-tier": 4 }, "put": { "callbacks": {}, "description": "Updates or creates channel data for a specific user and channel ID. If no user exists in the current environment for the given `user_id`, Knock will create the user entry as part of this request.", "operationId": "setUserChannelData", "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": "channel_id", "required": true, "schema": { "format": "uuid", "type": "string", "x-struct": null, "x-validate": null } } ], "requestBody": { "content": { "application/json": { "example": { "data": { "tokens": [ "push_token_1" ] } }, "schema": { "$ref": "#/components/schemas/ChannelDataRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelData" } } }, "description": "OK" } }, "summary": "Set channel data", "tags": [ "Channel data", "Users" ], "x-ratelimit-tier": 3 } }, "/v1/messages/{message_id}/events": { "get": { "callbacks": {}, "description": "Returns a paginated list of events for the specified message.", "operationId": "listMessageEvents", "parameters": [ { "description": "The ID of the message to fetch events for.", "in": "path", "name": "message_id", "required": true, "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/ListMessageEventsResponse" } } }, "description": "OK" } }, "summary": "List events", "tags": [ "Messages" ], "x-ratelimit-tier": 3, "x-retention-policy": true } }, "/v1/providers/slack/{channel_id}/auth_check": { "get": { "callbacks": {}, "description": "Check if a Slack channel is authenticated.", "operationId": "slackProviderAuthCheck", "parameters": [ { "description": "The ID of the Knock Slack channel to check.", "in": "path", "name": "channel_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "A JSON encoded string containing the access token object reference.", "example": "{\"collection\":\"projects\",\"object_id\":\"project_123\"}", "in": "query", "name": "access_token_object", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlackAuthCheckResponse" } } }, "description": "OK" } }, "summary": "Check auth", "tags": [ "Providers", "Slack" ], "x-ratelimit-tier": 2 } }, "/v1/tenants": { "get": { "callbacks": {}, "description": "List tenants for the current environment.", "operationId": "listTenants", "parameters": [ { "description": "Filter tenants by ID.", "in": "query", "name": "tenant_id", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Filter tenants by name.", "in": "query", "name": "name", "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/ListTenantsResponse" } } }, "description": "OK" } }, "summary": "List tenants", "tags": [ "Tenants" ], "x-ratelimit-tier": 4 } }, "/v1/messages/batch/seen": { "post": { "callbacks": {}, "description": "Marks the given messages as `seen`. This indicates that the user has viewed the message in their feed or inbox. Read more about message engagement statuses [here](/send-notifications/message-statuses#engagement-status).", "operationId": "batchMarkMessagesAsSeen", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "message_ids": [ "2w3YUpTTOxuDvZFji8OMsKrG176", "2w3YVRbPXMIh8Zq6oBFcVDA5xes" ] }, "schema": { "$ref": "#/components/schemas/BatchMessagesStatusRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "The list of messages that were updated.", "example": [ { "__typename": "Message", "actors": [ "user_123" ], "archived_at": null, "channel_id": "123e4567-e89b-12d3-a456-426614174000", "clicked_at": null, "data": { "foo": "bar" }, "engagement_statuses": [ "seen" ], "id": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "inserted_at": "2021-01-01T00:00:00Z", "interacted_at": null, "link_clicked_at": null, "metadata": { "external_id": "123e4567-e89b-12d3-a456-426614174000" }, "read_at": null, "recipient": "user_123", "scheduled_at": null, "seen_at": "2025-01-01T00:01:00Z", "source": { "__typename": "NotificationSource", "categories": [ "collaboration" ], "key": "comment-created", "version_id": "123e4567-e89b-12d3-a456-426614174000" }, "status": "sent", "tenant": "tenant_123", "updated_at": "2021-01-01T00:00:00Z", "workflow": "comment-created" } ], "items": { "allOf": [ { "$ref": "#/components/schemas/Message" } ], "example": { "__typename": "Message", "actors": [ "user_123" ], "archived_at": null, "channel_id": "123e4567-e89b-12d3-a456-426614174000", "clicked_at": null, "data": { "foo": "bar" }, "engagement_statuses": [ "seen" ], "id": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "inserted_at": "2021-01-01T00:00:00Z", "interacted_at": null, "link_clicked_at": null, "metadata": { "external_id": "123e4567-e89b-12d3-a456-426614174000" }, "read_at": null, "recipient": "user_123", "scheduled_at": null, "seen_at": "2025-01-01T00:01:00Z", "source": { "__typename": "NotificationSource", "categories": [ "collaboration" ], "key": "comment-created", "version_id": "123e4567-e89b-12d3-a456-426614174000" }, "status": "sent", "tenant": "tenant_123", "updated_at": "2021-01-01T00:00:00Z", "workflow": "comment-created" }, "x-struct": null, "x-validate": null }, "title": "BatchListMessagesResponse", "type": "array", "x-struct": null, "x-validate": null } } }, "description": "OK" } }, "summary": "Mark messages as seen", "tags": [ "Messages" ], "x-ratelimit-tier": 3, "x-retention-policy": true } }, "/v1/messages/batch/unseen": { "post": { "callbacks": {}, "description": "Marks the given messages as `unseen`. This reverses the `seen` state. Read more about message engagement statuses [here](/send-notifications/message-statuses#engagement-status).", "operationId": "batchMarkMessagesAsUnseen", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchMessagesStatusRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "The list of messages that were updated.", "example": [ { "__typename": "Message", "actors": [ "user_123" ], "archived_at": null, "channel_id": "123e4567-e89b-12d3-a456-426614174000", "clicked_at": null, "data": { "foo": "bar" }, "engagement_statuses": [], "id": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "inserted_at": "2021-01-01T00:00:00Z", "interacted_at": null, "link_clicked_at": null, "metadata": { "external_id": "123e4567-e89b-12d3-a456-426614174000" }, "read_at": null, "recipient": "user_123", "scheduled_at": null, "seen_at": null, "source": { "__typename": "NotificationSource", "categories": [ "collaboration" ], "key": "comment-created", "version_id": "123e4567-e89b-12d3-a456-426614174000" }, "status": "sent", "tenant": "tenant_123", "updated_at": "2021-01-01T00:00:00Z", "workflow": "comment-created" } ], "items": { "allOf": [ { "$ref": "#/components/schemas/Message" } ], "example": { "__typename": "Message", "actors": [ "user_123" ], "archived_at": null, "channel_id": "123e4567-e89b-12d3-a456-426614174000", "clicked_at": null, "data": { "foo": "bar" }, "engagement_statuses": [], "id": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "inserted_at": "2021-01-01T00:00:00Z", "interacted_at": null, "link_clicked_at": null, "metadata": { "external_id": "123e4567-e89b-12d3-a456-426614174000" }, "read_at": null, "recipient": "user_123", "scheduled_at": null, "seen_at": null, "source": { "__typename": "NotificationSource", "categories": [ "collaboration" ], "key": "comment-created", "version_id": "123e4567-e89b-12d3-a456-426614174000" }, "status": "sent", "tenant": "tenant_123", "updated_at": "2021-01-01T00:00:00Z", "workflow": "comment-created" }, "x-struct": null, "x-validate": null }, "title": "BatchListMessagesResponse", "type": "array", "x-struct": null, "x-validate": null } } }, "description": "OK" } }, "summary": "Mark messages as unseen", "tags": [ "Messages" ], "x-ratelimit-tier": 3, "x-retention-policy": true } }, "/v1/users/{user_id}/merge": { "post": { "callbacks": {}, "description": "Merge two users together, where the user specified with the `from_user_id` param will be merged into the user specified by `user_id`.", "operationId": "mergeUser", "parameters": [ { "description": "The id of the user to merge into.", "in": "path", "name": "user_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "requestBody": { "content": { "application/json": { "example": { "from_user_id": "user_1" }, "schema": { "$ref": "#/components/schemas/MergeUserRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } }, "description": "OK" } }, "summary": "Merge users", "tags": [ "Users" ], "x-ratelimit-tier": 2 } }, "/v1/objects/{collection}/{id}/messages": { "get": { "callbacks": {}, "description": "Returns a paginated list of messages for a specific object in the given collection. Allows filtering by message status and provides various sorting options.", "operationId": "listMessagesForObject", "parameters": [ { "description": "The cursor to fetch entries after.", "in": "query", "name": "after", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The cursor to fetch entries before.", "in": "query", "name": "before", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The number of items per page (defaults to 50).", "in": "query", "name": "page_size", "required": false, "schema": { "type": "integer", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to items with the corresponding tenant.", "example": "tenant_123", "in": "query", "name": "tenant", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to items with the corresponding channel ID.", "example": "123e4567-e89b-12d3-a456-426614174000", "in": "query", "name": "channel_id", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to messages with the given delivery status.", "example": [ "delivered" ], "in": "query", "name": "status[]", "required": false, "schema": { "items": { "enum": [ "queued", "sent", "delivered", "delivery_attempted", "undelivered", "not_sent", "bounced" ], "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to messages with the given engagement status.", "example": [ "unread" ], "in": "query", "name": "engagement_status[]", "required": false, "schema": { "items": { "enum": [ "seen", "unseen", "read", "unread", "archived", "unarchived", "link_clicked", "interacted" ], "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to only the message IDs given (max 50). Note: when using this option, the results will be subject to any other filters applied to the query.", "example": [ "1jNaXzB2RZX3LY8wVQnfCKyPnv7" ], "in": "query", "name": "message_ids[]", "required": false, "schema": { "items": { "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to messages related to any of the provided categories.", "example": [ "workflow_123" ], "in": "query", "name": "workflow_categories[]", "required": false, "schema": { "items": { "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to messages triggered by the given workflow key.", "example": "comment-created", "in": "query", "name": "source", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to messages associated with the top-level workflow run ID returned by the workflow trigger request.", "example": "123e4567-e89b-12d3-a456-426614174000", "in": "query", "name": "workflow_run_id", "required": false, "schema": { "format": "uuid", "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to messages for a specific recipient's workflow run.", "example": "123e4567-e89b-12d3-a456-426614174000", "in": "query", "name": "workflow_recipient_run_id", "required": false, "schema": { "format": "uuid", "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to only messages that were generated with the given data. See [trigger data filtering](/api-reference/overview/trigger-data-filtering) for more information.", "example": "{\"comment_id\": \"123\"}", "in": "query", "name": "trigger_data", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to items inserted after the given date.", "example": "2025-01-01T00:00:00Z", "in": "query", "name": "inserted_at.gt", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to items inserted after or on the given date.", "example": "2025-01-01T00:00:00Z", "in": "query", "name": "inserted_at.gte", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to items inserted before the given date.", "example": "2025-01-01T00:00:00Z", "in": "query", "name": "inserted_at.lt", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to items inserted before or on the given date.", "example": "2025-01-01T00:00:00Z", "in": "query", "name": "inserted_at.lte", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The collection this object belongs to.", "example": "projects", "in": "path", "name": "collection", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Unique identifier for the object.", "example": "project-123", "in": "path", "name": "id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMessagesResponse" } } }, "description": "OK" } }, "summary": "List messages", "tags": [ "Messages", "Objects" ], "x-ratelimit-tier": 4, "x-retention-policy": true } }, "/v1/objects/{collection}/{object_id}/preferences/{id}/categories/{key}": { "put": { "callbacks": {}, "deprecated": true, "description": "Updates a specific category preference for an object's preference set. Deprecated.", "operationId": "updateObjectPreferenceCategory", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreferenceSet" } } }, "description": "OK" } }, "summary": "Update a category preference", "tags": [ "Objects", "Preferences" ], "x-ratelimit-tier": 3 } }, "/v1/users/{user_id}/guides/messages/interacted": { "put": { "callbacks": {}, "description": "Records that a user has interacted with a guide, triggering any associated interacted events.", "operationId": "markUserGuideAsInteracted (2)", "parameters": [ { "description": "The unique identifier of the user.", "in": "path", "name": "user_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuideActionRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuideActionResponse" } } }, "description": "OK" } }, "summary": "Mark guide as interacted", "tags": [ "Guides", "Users" ], "x-ratelimit-tier": 2 } }, "/v1/users/{user_id}/guides/engagements/reset": { "put": { "callbacks": {}, "description": "Resets the engagement state of a guide for a user, removing the guide's engagement log entry so the next interaction creates a fresh engagement.", "operationId": "resetUserGuideEngagement", "parameters": [ { "description": "The unique identifier of the user.", "in": "path", "name": "user_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuideActionRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuideActionResponse" } } }, "description": "OK" } }, "summary": "Reset guide engagement", "tags": [ "Guides", "Users" ], "x-ratelimit-tier": 2 } }, "/v1/objects/{collection}/{object_id}/preferences": { "get": { "callbacks": {}, "description": "Returns a paginated list of preference sets for the specified object.", "operationId": "listObjectPreferenceSets", "parameters": [ { "description": "Unique identifier for the object.", "in": "path", "name": "object_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The collection this object belongs to.", "in": "path", "name": "collection", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "A list of preference sets for the object", "example": [ { "categories": { "marketing": false, "transactional": { "channel_types": { "email": false } } }, "channel_types": { "email": true, "push": false, "sms": { "conditions": [ { "argument": "US", "operator": "equal_to", "variable": "recipient.country_code" } ] } }, "commercial_subscribed": true, "id": "default", "workflows": null } ], "items": { "$ref": "#/components/schemas/PreferenceSet" }, "title": "ListObjectPreferenceSetsResponse", "type": "array", "x-struct": null, "x-validate": null } } }, "description": "OK" } }, "summary": "List preference sets", "tags": [ "Objects", "Preferences" ], "x-ratelimit-tier": 4 } }, "/v1/messages/{message_id}/read": { "delete": { "callbacks": {}, "description": "Marks a message as `unread`. This reverses the `read` state. Read more about message engagement statuses [here](/send-notifications/message-statuses#engagement-status).", "operationId": "markMessageUnread", "parameters": [ { "description": "The unique identifier for the message.", "example": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "in": "path", "name": "message_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Message" } ], "example": { "__typename": "Message", "actors": [ "user_123" ], "archived_at": null, "channel_id": "123e4567-e89b-12d3-a456-426614174000", "clicked_at": null, "data": { "foo": "bar" }, "engagement_statuses": [ "seen" ], "id": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "inserted_at": "2021-01-01T00:00:00Z", "interacted_at": null, "link_clicked_at": null, "metadata": { "external_id": "123e4567-e89b-12d3-a456-426614174000" }, "read_at": null, "recipient": "user_123", "scheduled_at": null, "seen_at": "2025-01-01T00:01:00Z", "source": { "__typename": "NotificationSource", "categories": [ "collaboration" ], "key": "comment-created", "step_ref": "email_step_1", "version_id": "123e4567-e89b-12d3-a456-426614174000" }, "status": "sent", "tenant": "tenant_123", "updated_at": "2021-01-01T00:00:00Z", "workflow": "comment-created" }, "x-struct": null, "x-validate": null } } }, "description": "OK" } }, "summary": "Mark message as unread", "tags": [ "Messages" ], "x-ratelimit-tier": 2, "x-retention-policy": true }, "put": { "callbacks": {}, "description": "Marks a message as `read`. This indicates that the user has read the message content. Read more about message engagement statuses [here](/send-notifications/message-statuses#engagement-status).", "operationId": "markMessageRead", "parameters": [ { "description": "The unique identifier for the message.", "example": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "in": "path", "name": "message_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Message" } ], "example": { "__typename": "Message", "actors": [ "user_123" ], "archived_at": null, "channel_id": "123e4567-e89b-12d3-a456-426614174000", "clicked_at": null, "data": { "foo": "bar" }, "engagement_statuses": [ "seen", "read" ], "id": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "inserted_at": "2021-01-01T00:00:00Z", "interacted_at": null, "link_clicked_at": null, "metadata": { "external_id": "123e4567-e89b-12d3-a456-426614174000" }, "read_at": "2025-01-01T00:02:00Z", "recipient": "user_123", "scheduled_at": null, "seen_at": "2025-01-01T00:01:00Z", "source": { "__typename": "NotificationSource", "categories": [ "collaboration" ], "key": "comment-created", "step_ref": "email_step_1", "version_id": "123e4567-e89b-12d3-a456-426614174000" }, "status": "sent", "tenant": "tenant_123", "updated_at": "2021-01-01T00:00:00Z", "workflow": "comment-created" }, "x-struct": null, "x-validate": null } } }, "description": "OK" } }, "summary": "Mark message as read", "tags": [ "Messages" ], "x-ratelimit-tier": 2, "x-retention-policy": true } }, "/v1/users/bulk/preferences": { "post": { "callbacks": {}, "description": "Bulk sets the preferences for up to 1,000 users at a time. The preference set `:id` can be either `default` or a `tenant.id`. Learn more about [per-tenant preferences](/preferences/tenant-preferences). Note that this is a destructive operation and will replace any existing users' preferences with the preferences sent.", "operationId": "bulkSetUserPreferences", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "preferences": { "__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 } } } }, "user_ids": [ "user_1", "user_2" ] }, "schema": { "$ref": "#/components/schemas/BulkSetUserPreferencesRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOperation" } } }, "description": "OK" } }, "summary": "Bulk set preferences", "tags": [ "Users", "Bulk operations" ], "x-ratelimit-tier": 1 } }, "/v1/objects/{collection}/{object_id}/preferences/{id}/workflows/{key}": { "put": { "callbacks": {}, "deprecated": true, "description": "Updates a specific workflow preference for an object's preference set.", "operationId": "updateObjectPreferenceWorkflow", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreferenceSet" } } }, "description": "OK" } }, "summary": "Update a workflow preference", "tags": [ "Objects", "Preferences" ], "x-ratelimit-tier": 3 } }, "/v1/users/{user_id}/guides/{channel_id}": { "get": { "callbacks": {}, "description": "Returns a list of eligible in-app guides for a specific user and channel.", "operationId": "listUserGuides", "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": "channel_id", "required": true, "schema": { "format": "uuid", "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The tenant ID to use for targeting and rendering guides.", "in": "query", "name": "tenant", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The data (JSON encoded object) to use for targeting and rendering guides.", "in": "query", "name": "data", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The type of guides to filter by.", "in": "query", "name": "type", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuidesResponse" } } }, "description": "OK" } }, "summary": "List guides", "tags": [ "Guides", "Users" ], "x-ratelimit-tier": 2 } }, "/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/objects/{collection}/bulk/subscriptions/add": { "post": { "callbacks": {}, "description": "Add subscriptions for all objects in a single collection. If a subscription for an object in the collection already exists, it will be updated. This endpoint also handles [inline identifications](/managing-recipients/identifying-recipients#inline-identifying-recipients) for the `recipient` field.", "operationId": "bulkAddSubscriptions", "parameters": [ { "description": "The collection this object belongs to.", "example": "projects", "in": "path", "name": "collection", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "requestBody": { "content": { "application/json": { "example": { "subscriptions": [ { "id": "project-1", "properties": null, "recipients": [ { "id": "user_1" } ] } ] }, "schema": { "$ref": "#/components/schemas/BulkUpsertSubscriptionsRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOperation" } } }, "description": "OK" } }, "summary": "Bulk add subscriptions", "tags": [ "Objects", "Subscriptions", "Bulk operations" ], "x-ratelimit-tier": 1 } }, "/v1/messages/batch/content": { "get": { "callbacks": {}, "description": "Get the contents of multiple messages in a single request.", "operationId": "batchGetMessageContents", "parameters": [ { "description": "The IDs of the messages to fetch contents of.", "in": "query", "name": "message_ids[]", "required": true, "schema": { "items": { "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "A list of `MessageContents`", "example": [ { "__typename": "MessageContent", "data": { "__typename": "MessageSmsContent", "body": "URGENT: Power failure detected in perimeter fencing. Backup generators failed to engage. Technical team dispatched. Maintain lockdown protocols.", "to": "+15553982647" }, "inserted_at": "1993-06-11T20:30:00Z", "message_id": "2w3YUpTTOxuDvZFji8OMsKrG176" } ], "items": { "$ref": "#/components/schemas/MessageContents" }, "title": "BatchGetMessageContentsResponse", "type": "array", "x-struct": null, "x-validate": null } } }, "description": "OK" } }, "summary": "Batch get message contents", "tags": [ "Messages" ], "x-ratelimit-tier": 4, "x-retention-policy": true } }, "/v1/users/bulk/identify": { "post": { "callbacks": {}, "description": "Identifies multiple users in a single operation. Allows creating or updating up to 1,000 users in a single batch with various properties, preferences, and channel data.", "operationId": "bulkIdentifyUsers", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "users": [ { "email": "jane@ingen.net", "id": "user_1", "name": "Jane Doe", "timezone": "America/New_York" } ] }, "schema": { "$ref": "#/components/schemas/BulkIdentifyUsersRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOperation" } } }, "description": "OK" } }, "summary": "Bulk identify users", "tags": [ "Users", "Bulk operations" ], "x-ratelimit-tier": 1 } }, "/v1/messages/{message_id}/content": { "get": { "callbacks": {}, "description": "Returns the fully rendered contents of a message, where the response depends on which channel the message was sent through.", "operationId": "getMessageContents", "parameters": [ { "description": "The ID of the message to fetch contents of.", "in": "path", "name": "message_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageContents" } } }, "description": "OK" } }, "summary": "Get message content", "tags": [ "Messages" ], "x-ratelimit-tier": 4, "x-retention-policy": true } }, "/v1/workflow_recipient_runs/{id}": { "get": { "callbacks": {}, "description": "Returns a single workflow recipient run with its associated events.", "operationId": "getWorkflowRecipientRun", "parameters": [ { "description": "The unique identifier for the workflow recipient run (per-recipient).", "in": "path", "name": "id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRecipientRunDetail" } } }, "description": "OK" } }, "summary": "Get a workflow recipient run", "tags": [ "Workflow recipient runs" ], "x-ratelimit-tier": 2, "x-retention-policy": true } }, "/v1/users/{user_id}/preferences/{id}/workflows": { "put": { "callbacks": {}, "deprecated": true, "description": "Updates the workflows in a specific user preference set. This operation is deprecated.", "operationId": "updateUserPreferenceWorkflows", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreferenceSet" } } }, "description": "OK" } }, "summary": "Update workflows in preference set", "tags": [ "Users", "Preferences" ], "x-ratelimit-tier": 3 } }, "/v1/objects/{collection}/{object_id}/preferences/{id}/categories": { "put": { "callbacks": {}, "deprecated": true, "description": "Updates the category preferences for an object's preference set.", "operationId": "updateObjectPreferenceCategories", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreferenceSet" } } }, "description": "OK" } }, "summary": "Update categories in preference set", "tags": [ "Objects", "Preferences" ], "x-ratelimit-tier": 3 } }, "/v1/notify/cancel": { "post": { "callbacks": {}, "description": "Cancels a previously triggered workflow using the provided cancellation key.", "operationId": "cancelWorkflow (2)", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cancel Request" } } }, "description": "Cancel Payload", "required": true }, "responses": { "204": { "description": "No Content" } }, "summary": "Cancel workflow", "tags": [ "Workflow Triggers" ], "x-ratelimit-tier": 3 } }, "/v1/objects/{collection}/{id}": { "delete": { "callbacks": {}, "description": "Permanently removes an object from the specified collection. This operation cannot be undone.", "operationId": "deleteObject", "parameters": [ { "description": "The collection this object belongs to.", "in": "path", "name": "collection", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Unique identifier for the object.", "in": "path", "name": "id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "204": { "description": "No Content" } }, "summary": "Delete an object", "tags": [ "Objects" ], "x-ratelimit-tier": 3 }, "get": { "callbacks": {}, "description": "Retrieves a specific object by its ID from the specified collection. Returns the object with all its properties.", "operationId": "getObject", "parameters": [ { "description": "The collection this object belongs to.", "in": "path", "name": "collection", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Unique identifier for the object.", "in": "path", "name": "id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Object" } } }, "description": "OK" } }, "summary": "Get an object", "tags": [ "Objects" ], "x-ratelimit-tier": 4 }, "put": { "callbacks": {}, "description": "Creates a new object or updates an existing one in the specified collection. This operation is used to identify objects with their properties, as well as optional preferences and channel data.", "operationId": "setObject", "parameters": [ { "description": "The collection this object belongs to.", "in": "path", "name": "collection", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Unique identifier for the object.", "in": "path", "name": "id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "requestBody": { "content": { "application/json": { "example": { "channel_data": { "97c5837d-c65c-4d54-aa39-080eeb81c69d": { "tokens": [ "push_token_123" ] } }, "description": "My product description", "locale": "en-US", "name": "My product", "preferences": { "default": { "channel_types": { "email": true }, "workflows": { "dinosaurs-loose": { "channel_types": { "email": true } } } } }, "price": 100.0, "timezone": "America/New_York" }, "schema": { "$ref": "#/components/schemas/SetObjectRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Object" } } }, "description": "OK" } }, "summary": "Set an object", "tags": [ "Objects" ], "x-ratelimit-tier": 3 } }, "/v1/tenants/bulk/delete": { "post": { "callbacks": {}, "description": "Delete up to 1,000 tenants at a time in a single operation. This operation cannot be undone.", "operationId": "bulkDeleteTenants", "parameters": [ { "description": "The IDs of the tenants to delete.", "in": "query", "name": "tenant_ids[]", "required": true, "schema": { "items": { "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOperation" } } }, "description": "OK" } }, "summary": "Bulk delete tenants", "tags": [ "Tenants", "Bulk operations" ], "x-ratelimit-tier": 1 } }, "/v1/workflow_recipient_runs": { "get": { "callbacks": {}, "description": "Returns a paginated list of workflow recipient runs for the current environment.", "operationId": "listWorkflowRecipientRuns", "parameters": [ { "description": "The cursor to fetch entries after.", "in": "query", "name": "after", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The cursor to fetch entries before.", "in": "query", "name": "before", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The number of items per page (defaults to 50).", "in": "query", "name": "page_size", "required": false, "schema": { "type": "integer", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to workflow recipient runs for the given workflow key.", "in": "query", "name": "workflow", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to workflow recipient runs with the given status.", "in": "query", "name": "status[]", "required": false, "schema": { "items": { "enum": [ "queued", "processing", "paused", "completed", "cancelled" ], "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to workflow recipient runs for the given tenant.", "in": "query", "name": "tenant", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to workflow recipient runs that have errors.", "in": "query", "name": "has_errors", "required": false, "schema": { "type": "boolean", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to workflow recipient runs for the given recipient. Accepts a user ID string or an object reference with `id` and `collection`.", "in": "query", "name": "recipient", "required": false, "schema": { "$ref": "#/components/schemas/RecipientReference" } }, { "description": "Limits the results to workflow recipient runs started after the given date.", "example": "2025-01-01T00:00:00Z", "in": "query", "name": "starting_at", "required": false, "schema": { "format": "date-time", "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to workflow recipient runs started before the given date.", "example": "2025-01-01T00:00:00Z", "in": "query", "name": "ending_at", "required": false, "schema": { "format": "date-time", "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWorkflowRecipientRunsResponse" } } }, "description": "OK" } }, "summary": "List workflow recipient runs", "tags": [ "Workflow recipient runs" ], "x-ratelimit-tier": 2, "x-retention-policy": true } }, "/v1/messages/{message_id}/activities": { "get": { "callbacks": {}, "description": "Returns a paginated list of activities for the specified message.", "operationId": "listMessageActivities", "parameters": [ { "description": "The ID of the message to fetch activities for.", "in": "path", "name": "message_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The trigger data to filter activities by.", "in": "query", "name": "trigger_data", "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/ListActivitiesResponse" } } }, "description": "OK" } }, "summary": "List activities", "tags": [ "Messages" ], "x-ratelimit-tier": 4, "x-retention-policy": true } }, "/v1/channels/{channel_id}/messages/bulk/{action}": { "post": { "callbacks": {}, "description": "Bulk update the status of messages for a specific channel. The channel is specified by the `channel_id` parameter. The action to perform is specified by the `action` parameter, where the action is a status change action (e.g. `archive`, `unarchive`).", "operationId": "bulkUpdateMessagesForChannel", "parameters": [ { "description": "The ID of the channel to update messages for.", "in": "path", "name": "channel_id", "required": true, "schema": { "format": "uuid", "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The target status to be applied to the messages.", "in": "path", "name": "action", "required": true, "schema": { "enum": [ "seen", "unseen", "read", "unread", "archived", "unarchived", "interacted", "archive", "unarchive", "delete" ], "type": "string", "x-struct": null, "x-validate": null } } ], "requestBody": { "content": { "application/json": { "example": { "archived": "include", "delivery_status": "delivered", "engagement_status": "seen", "has_tenant": true, "newer_than": "2024-01-01T00:00:00Z", "older_than": "2024-01-01T00:00:00Z", "recipient_ids": [ "recipient1", "recipient2" ], "tenants": [ "tenant1", "tenant2" ], "trigger_data": "{\"key\":\"value\"}", "workflows": [ "workflow1", "workflow2" ] }, "schema": { "$ref": "#/components/schemas/BulkUpdateMessagesForChannelRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOperation" } } }, "description": "OK" } }, "summary": "Bulk update message statuses for channel", "tags": [ "Messages", "Bulk operations" ], "x-ratelimit-tier": 2, "x-retention-policy": true } }, "/v1/users/{user_id}/preferences/{id}/categories": { "put": { "callbacks": {}, "deprecated": true, "description": "Updates the categories in a specific user preference set. This operation is deprecated.", "operationId": "updateUserPreferenceCategories", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreferenceSet" } } }, "description": "OK" } }, "summary": "Update categories in user preference set", "tags": [ "Users", "Preferences" ], "x-ratelimit-tier": 3 } }, "/v1/users/{user_id}/guides/messages/{message_id}/interacted": { "put": { "callbacks": {}, "description": "Records that a user has interacted with a guide, triggering any associated interacted events.", "operationId": "markUserGuideAsInteracted", "parameters": [ { "description": "The unique identifier of the user.", "in": "path", "name": "user_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuideActionRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuideActionResponse" } } }, "description": "OK" } }, "summary": "Mark guide as interacted", "tags": [ "Guides", "Users" ], "x-ratelimit-tier": 2 } }, "/v1/objects/{collection}/{object_id}/channel_data/{channel_id}": { "delete": { "callbacks": {}, "description": "Unsets the channel data for the specified object and channel.", "operationId": "unsetObjectChannelData", "parameters": [ { "description": "Unique identifier for the object.", "in": "path", "name": "object_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The collection this object belongs to.", "in": "path", "name": "collection", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The unique identifier for the channel.", "in": "path", "name": "channel_id", "required": true, "schema": { "format": "uuid", "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "204": { "description": "No Content" } }, "summary": "Unset channel data", "tags": [ "Channel data", "Objects" ], "x-ratelimit-tier": 3 }, "get": { "callbacks": {}, "description": "Returns the channel data for the specified object and channel.", "operationId": "getObjectChannelData", "parameters": [ { "description": "Unique identifier for the object.", "in": "path", "name": "object_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The collection this object belongs to.", "in": "path", "name": "collection", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The unique identifier for the channel.", "in": "path", "name": "channel_id", "required": true, "schema": { "format": "uuid", "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelData" } } }, "description": "OK" } }, "summary": "Get channel data", "tags": [ "Channel data", "Objects" ], "x-ratelimit-tier": 4 }, "put": { "callbacks": {}, "description": "Sets the channel data for the specified object and channel. If no object exists in the current environment for the given `collection` and `object_id`, Knock will create the object as part of this request.", "operationId": "setObjectChannelData", "parameters": [ { "description": "Unique identifier for the object.", "in": "path", "name": "object_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The collection this object belongs to.", "in": "path", "name": "collection", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The unique identifier for the channel.", "in": "path", "name": "channel_id", "required": true, "schema": { "format": "uuid", "type": "string", "x-struct": null, "x-validate": null } } ], "requestBody": { "content": { "application/json": { "example": { "data": { "tokens": [ "push_token_1" ] } }, "schema": { "$ref": "#/components/schemas/ChannelDataRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelData" } } }, "description": "OK" } }, "summary": "Set channel data", "tags": [ "Channel data", "Objects" ], "x-ratelimit-tier": 3 } }, "/v1/audiences/{key}/members": { "delete": { "callbacks": {}, "description": "Removes one or more members from the specified audience.", "operationId": "removeAudienceMembers", "parameters": [ { "description": "The key of the audience.", "in": "path", "name": "key", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveAudienceMembersRequest" } } }, "description": "Params", "required": true }, "responses": { "204": { "description": "No Content" } }, "summary": "Remove members", "tags": [ "Audiences" ], "x-ratelimit-tier": 3 }, "get": { "callbacks": {}, "description": "Returns a paginated list of members for the specified audience.", "operationId": "listAudienceMembers", "parameters": [ { "description": "The key of the audience.", "in": "path", "name": "key", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAudienceMembersResponse" } } }, "description": "OK" } }, "summary": "List members", "tags": [ "Audiences" ], "x-ratelimit-tier": 4 }, "post": { "callbacks": {}, "description": "Adds one or more members to the specified audience.", "operationId": "addAudienceMembers", "parameters": [ { "description": "The key of the audience.", "in": "path", "name": "key", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Create the audience if it does not exist.", "in": "query", "name": "create_audience", "required": false, "schema": { "type": "boolean", "x-struct": null, "x-validate": null } } ], "requestBody": { "content": { "application/json": { "example": { "members": [ { "tenant": "ingen_isla_nublar", "user": { "email": "ellie@ingen.net", "id": "dr_sattler", "name": "Dr. Ellie Sattler" } } ] }, "schema": { "$ref": "#/components/schemas/AddAudienceMembersRequest" } } }, "description": "Params", "required": true }, "responses": { "204": { "description": "No Content" } }, "summary": "Add members", "tags": [ "Audiences" ], "x-ratelimit-tier": 3 } }, "/v1/providers/ms-teams/{channel_id}/channels": { "get": { "callbacks": {}, "description": "List the Microsoft Teams channels within a team. By default, archived and private channels are excluded from the results.", "operationId": "listChannelsForMsTeamsProvider", "parameters": [ { "description": "The ID of the Knock Microsoft Teams channel to get channels for.", "in": "path", "name": "channel_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "A JSON encoded string containing the Microsoft Teams tenant object reference.", "example": "{\"collection\":\"projects\",\"object_id\":\"project_123\"}", "in": "query", "name": "ms_teams_tenant_object", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Microsoft Teams team ID.", "in": "query", "name": "team_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "[OData param](https://learn.microsoft.com/en-us/graph/query-parameters) passed to the Microsoft Graph API to filter channels.", "example": "displayName eq 'General'", "in": "query", "name": "query_options.$filter", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "[OData param](https://learn.microsoft.com/en-us/graph/query-parameters) passed to the Microsoft Graph API to select specific properties.", "example": "id,displayName,description", "in": "query", "name": "query_options.$select", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelsForMsTeamsProviderResponse" } } }, "description": "OK" } }, "summary": "List channels", "tags": [ "Providers", "Microsoft Teams" ], "x-ratelimit-tier": 2 } }, "/v1/users/bulk/delete": { "post": { "callbacks": {}, "description": "Permanently deletes up to 1,000 users at a time.", "operationId": "bulkDeleteUsers", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeleteUsersRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOperation" } } }, "description": "OK" } }, "summary": "Bulk delete users", "tags": [ "Users", "Bulk operations" ], "x-ratelimit-tier": 1 } }, "/v1/providers/slack/{channel_id}/revoke_access": { "put": { "callbacks": {}, "description": "Revoke access for a Slack channel.", "operationId": "slackProviderRevokeAccess", "parameters": [ { "description": "The ID of the Knock Slack channel to revoke access for.", "in": "path", "name": "channel_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "A JSON encoded string containing the access token object reference.", "example": "{\"collection\":\"projects\",\"object_id\":\"project_123\"}", "in": "query", "name": "access_token_object", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "A response indicating the operation was successful.", "example": { "ok": "ok" }, "properties": { "ok": { "description": "OK response.", "example": "ok", "type": "string", "x-struct": null, "x-validate": null } }, "title": "SuccessResponse", "type": "object", "x-struct": null, "x-validate": null } } }, "description": "OK" }, "403": { "content": { "application/json": { "schema": { "description": "Authentication error response", "example": { "code": "authorization", "message": "Access token not set.", "status": 403, "type": "authentication_error" }, "properties": { "code": { "description": "The error code.", "example": "authorization", "type": "string", "x-struct": null, "x-validate": null }, "message": { "description": "The error message.", "example": "Access token not set.", "type": "string", "x-struct": null, "x-validate": null }, "status": { "description": "The HTTP status code.", "example": 403, "type": "integer", "x-struct": null, "x-validate": null }, "type": { "description": "The error type.", "example": "authentication_error", "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "code", "message", "status", "type" ], "title": "AuthenticationError", "type": "object", "x-struct": null, "x-validate": null } } }, "description": "Forbidden" } }, "summary": "Revoke access", "tags": [ "Providers", "Slack" ], "x-ratelimit-tier": 2 } }, "/v1/messages/batch/unread": { "post": { "callbacks": {}, "description": "Marks the given messages as `unread`. This reverses the `read` state. Read more about message engagement statuses [here](/send-notifications/message-statuses#engagement-status).", "operationId": "batchMarkMessagesAsUnread", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "message_ids": [ "2w3YUpTTOxuDvZFji8OMsKrG176", "2w3YVRbPXMIh8Zq6oBFcVDA5xes" ] }, "schema": { "$ref": "#/components/schemas/BatchMessagesStatusRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "The list of messages that were updated.", "example": [ { "__typename": "Message", "actors": [ "user_123" ], "archived_at": null, "channel_id": "123e4567-e89b-12d3-a456-426614174000", "clicked_at": null, "data": { "foo": "bar" }, "engagement_statuses": [ "seen" ], "id": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "inserted_at": "2021-01-01T00:00:00Z", "interacted_at": null, "link_clicked_at": null, "metadata": { "external_id": "123e4567-e89b-12d3-a456-426614174000" }, "read_at": null, "recipient": "user_123", "scheduled_at": null, "seen_at": "2025-01-01T00:01:00Z", "source": { "__typename": "NotificationSource", "categories": [ "collaboration" ], "key": "comment-created", "version_id": "123e4567-e89b-12d3-a456-426614174000" }, "status": "sent", "tenant": "tenant_123", "updated_at": "2021-01-01T00:00:00Z", "workflow": "comment-created" } ], "items": { "allOf": [ { "$ref": "#/components/schemas/Message" } ], "example": { "__typename": "Message", "actors": [ "user_123" ], "archived_at": null, "channel_id": "123e4567-e89b-12d3-a456-426614174000", "clicked_at": null, "data": { "foo": "bar" }, "engagement_statuses": [ "seen" ], "id": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "inserted_at": "2021-01-01T00:00:00Z", "interacted_at": null, "link_clicked_at": null, "metadata": { "external_id": "123e4567-e89b-12d3-a456-426614174000" }, "read_at": null, "recipient": "user_123", "scheduled_at": null, "seen_at": "2025-01-01T00:01:00Z", "source": { "__typename": "NotificationSource", "categories": [ "collaboration" ], "key": "comment-created", "version_id": "123e4567-e89b-12d3-a456-426614174000" }, "status": "sent", "tenant": "tenant_123", "updated_at": "2021-01-01T00:00:00Z", "workflow": "comment-created" }, "x-struct": null, "x-validate": null }, "title": "BatchListMessagesResponse", "type": "array", "x-struct": null, "x-validate": null } } }, "description": "OK" } }, "summary": "Mark messages as unread", "tags": [ "Messages" ], "x-ratelimit-tier": 3, "x-retention-policy": true } }, "/v1/users/{user_id}/preferences/{id}/channel_types/{type}": { "put": { "callbacks": {}, "deprecated": true, "description": "Updates a single channel type in a specific user preference set. This operation is deprecated.", "operationId": "updateUserPreferenceChannelType", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreferenceSet" } } }, "description": "OK" } }, "summary": "Update channel type in preference set", "tags": [ "Users", "Preferences" ], "x-ratelimit-tier": 3 } }, "/v1/objects/{collection}": { "get": { "callbacks": {}, "description": "Returns a paginated list of objects from the specified collection. Optionally includes preference data for the objects.", "operationId": "listObjects", "parameters": [ { "description": "The cursor to fetch entries after.", "in": "query", "name": "after", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The cursor to fetch entries before.", "in": "query", "name": "before", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The number of items per page (defaults to 50).", "in": "query", "name": "page_size", "required": false, "schema": { "type": "integer", "x-struct": null, "x-validate": null } }, { "description": "The collection this object belongs to.", "in": "path", "name": "collection", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Includes preferences of the objects in the response.", "in": "query", "name": "include[]", "required": false, "schema": { "items": { "enum": [ "preferences" ], "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListObjectsResponse" } } }, "description": "OK" } }, "summary": "List objects in a collection", "tags": [ "Objects" ], "x-ratelimit-tier": 4 } }, "/v1/users/{user_id}/preferences": { "get": { "callbacks": {}, "description": "Retrieves a list of all preference sets for a specific user.", "operationId": "listUserPreferenceSets", "parameters": [ { "description": "The unique identifier of the user.", "in": "path", "name": "user_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "A list of preference sets for the user.", "example": [ { "categories": { "marketing": false, "transactional": { "channel_types": { "email": false } } }, "channel_types": { "email": true, "push": false, "sms": { "conditions": [ { "argument": "US", "operator": "equal_to", "variable": "recipient.country_code" } ] } }, "commercial_subscribed": true, "id": "default", "workflows": null } ], "items": { "$ref": "#/components/schemas/PreferenceSet" }, "title": "ListUserPreferenceSetsResponse", "type": "array", "x-struct": null, "x-validate": null } } }, "description": "OK" } }, "summary": "List user preference sets", "tags": [ "Users", "Preferences" ], "x-ratelimit-tier": 4 } }, "/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", "Users" ], "x-ratelimit-tier": 4 } }, "/v1/users/{user_id}/guides/messages/{message_id}/archived": { "put": { "callbacks": {}, "description": "Records that a guide has been archived by a user, triggering any associated archived events.", "operationId": "markUserGuideAsArchived", "parameters": [ { "description": "The unique identifier of the user.", "in": "path", "name": "user_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuideActionRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuideActionResponse" } } }, "description": "OK" } }, "summary": "Mark guide as archived", "tags": [ "Guides", "Users" ], "x-ratelimit-tier": 2 } }, "/v1/messages/{message_id}/archived": { "delete": { "callbacks": {}, "description": "Removes a message from the archived state, making it visible in the default message list in the feed again.", "operationId": "unarchiveMessage (2)", "parameters": [ { "description": "The unique identifier for the message.", "example": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "in": "path", "name": "message_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Message" } ], "example": { "__typename": "Message", "actors": [ "user_123" ], "archived_at": null, "channel_id": "123e4567-e89b-12d3-a456-426614174000", "clicked_at": null, "data": { "foo": "bar" }, "engagement_statuses": [ "seen" ], "id": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "inserted_at": "2021-01-01T00:00:00Z", "interacted_at": null, "link_clicked_at": null, "metadata": { "external_id": "123e4567-e89b-12d3-a456-426614174000" }, "read_at": null, "recipient": "user_123", "scheduled_at": null, "seen_at": "2025-01-01T00:01:00Z", "source": { "__typename": "NotificationSource", "categories": [ "collaboration" ], "key": "comment-created", "step_ref": "email_step_1", "version_id": "123e4567-e89b-12d3-a456-426614174000" }, "status": "sent", "tenant": "tenant_123", "updated_at": "2021-01-01T00:00:00Z", "workflow": "comment-created" }, "x-struct": null, "x-validate": null } } }, "description": "OK" } }, "summary": "Unarchive message", "tags": [ "Messages" ], "x-ratelimit-tier": 2, "x-retention-policy": true }, "put": { "callbacks": {}, "description": "Archives a message for the user. Archived messages are hidden from the default message list in the feed but can still be accessed and unarchived later.", "operationId": "archiveMessage", "parameters": [ { "description": "The unique identifier for the message.", "example": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "in": "path", "name": "message_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Message" } ], "example": { "__typename": "Message", "actors": [ "user_123" ], "archived_at": "2025-01-01T00:04:00Z", "channel_id": "123e4567-e89b-12d3-a456-426614174000", "clicked_at": null, "data": { "foo": "bar" }, "engagement_statuses": [ "seen", "archived" ], "id": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "inserted_at": "2021-01-01T00:00:00Z", "interacted_at": null, "link_clicked_at": null, "metadata": { "external_id": "123e4567-e89b-12d3-a456-426614174000" }, "read_at": null, "recipient": "user_123", "scheduled_at": null, "seen_at": "2025-01-01T00:01:00Z", "source": { "__typename": "NotificationSource", "categories": [ "collaboration" ], "key": "comment-created", "step_ref": "email_step_1", "version_id": "123e4567-e89b-12d3-a456-426614174000" }, "status": "sent", "tenant": "tenant_123", "updated_at": "2021-01-01T00:00:00Z", "workflow": "comment-created" }, "x-struct": null, "x-validate": null } } }, "description": "OK" } }, "summary": "Archive message", "tags": [ "Messages" ], "x-ratelimit-tier": 2, "x-retention-policy": true } }, "/v1/messages/batch/archived": { "post": { "callbacks": {}, "description": "Marks the given messages as archived. Archived messages are hidden from the default message list in the feed but can still be accessed and unarchived later.", "operationId": "batchMarkMessagesAsArchived", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "message_ids": [ "2w3YUpTTOxuDvZFji8OMsKrG176", "2w3YVRbPXMIh8Zq6oBFcVDA5xes" ] }, "schema": { "$ref": "#/components/schemas/BatchMessagesStatusRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "The list of messages that were updated.", "example": [ { "__typename": "Message", "actors": [ "user_123" ], "archived_at": "2025-01-01T00:04:00Z", "channel_id": "123e4567-e89b-12d3-a456-426614174000", "clicked_at": null, "data": { "foo": "bar" }, "engagement_statuses": [ "seen", "archived" ], "id": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "inserted_at": "2021-01-01T00:00:00Z", "interacted_at": null, "link_clicked_at": null, "metadata": { "external_id": "123e4567-e89b-12d3-a456-426614174000" }, "read_at": null, "recipient": "user_123", "scheduled_at": null, "seen_at": "2025-01-01T00:01:00Z", "source": { "__typename": "NotificationSource", "categories": [ "collaboration" ], "key": "comment-created", "version_id": "123e4567-e89b-12d3-a456-426614174000" }, "status": "sent", "tenant": "tenant_123", "updated_at": "2021-01-01T00:00:00Z", "workflow": "comment-created" } ], "items": { "allOf": [ { "$ref": "#/components/schemas/Message" } ], "example": { "__typename": "Message", "actors": [ "user_123" ], "archived_at": "2025-01-01T00:04:00Z", "channel_id": "123e4567-e89b-12d3-a456-426614174000", "clicked_at": null, "data": { "foo": "bar" }, "engagement_statuses": [ "seen", "archived" ], "id": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "inserted_at": "2021-01-01T00:00:00Z", "interacted_at": null, "link_clicked_at": null, "metadata": { "external_id": "123e4567-e89b-12d3-a456-426614174000" }, "read_at": null, "recipient": "user_123", "scheduled_at": null, "seen_at": "2025-01-01T00:01:00Z", "source": { "__typename": "NotificationSource", "categories": [ "collaboration" ], "key": "comment-created", "version_id": "123e4567-e89b-12d3-a456-426614174000" }, "status": "sent", "tenant": "tenant_123", "updated_at": "2021-01-01T00:00:00Z", "workflow": "comment-created" }, "x-struct": null, "x-validate": null }, "title": "BatchListMessagesResponse", "type": "array", "x-struct": null, "x-validate": null } } }, "description": "OK" } }, "summary": "Mark messages as archived", "tags": [ "Messages" ], "x-ratelimit-tier": 3, "x-retention-policy": true } }, "/v1/users/{user_id}/messages": { "get": { "callbacks": {}, "description": "Returns a paginated list of messages for a specific user. Messages are sorted with the most recent ones appearing first. Messages outside the account's retention window will not be included in the results.", "operationId": "listMessagesForUser", "parameters": [ { "description": "The cursor to fetch entries after.", "in": "query", "name": "after", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The cursor to fetch entries before.", "in": "query", "name": "before", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The number of items per page (defaults to 50).", "in": "query", "name": "page_size", "required": false, "schema": { "type": "integer", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to items with the corresponding tenant.", "example": "tenant_123", "in": "query", "name": "tenant", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to items with the corresponding channel ID.", "example": "123e4567-e89b-12d3-a456-426614174000", "in": "query", "name": "channel_id", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to messages with the given delivery status.", "example": [ "delivered" ], "in": "query", "name": "status[]", "required": false, "schema": { "items": { "enum": [ "queued", "sent", "delivered", "delivery_attempted", "undelivered", "not_sent", "bounced" ], "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to messages with the given engagement status.", "example": [ "unread" ], "in": "query", "name": "engagement_status[]", "required": false, "schema": { "items": { "enum": [ "seen", "unseen", "read", "unread", "archived", "unarchived", "link_clicked", "interacted" ], "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to only the message IDs given (max 50). Note: when using this option, the results will be subject to any other filters applied to the query.", "example": [ "1jNaXzB2RZX3LY8wVQnfCKyPnv7" ], "in": "query", "name": "message_ids[]", "required": false, "schema": { "items": { "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to messages related to any of the provided categories.", "example": [ "workflow_123" ], "in": "query", "name": "workflow_categories[]", "required": false, "schema": { "items": { "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to messages triggered by the given workflow key.", "example": "comment-created", "in": "query", "name": "source", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to messages associated with the top-level workflow run ID returned by the workflow trigger request.", "example": "123e4567-e89b-12d3-a456-426614174000", "in": "query", "name": "workflow_run_id", "required": false, "schema": { "format": "uuid", "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to messages for a specific recipient's workflow run.", "example": "123e4567-e89b-12d3-a456-426614174000", "in": "query", "name": "workflow_recipient_run_id", "required": false, "schema": { "format": "uuid", "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to only messages that were generated with the given data. See [trigger data filtering](/api-reference/overview/trigger-data-filtering) for more information.", "example": "{\"comment_id\": \"123\"}", "in": "query", "name": "trigger_data", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to items inserted after the given date.", "example": "2025-01-01T00:00:00Z", "in": "query", "name": "inserted_at.gt", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to items inserted after or on the given date.", "example": "2025-01-01T00:00:00Z", "in": "query", "name": "inserted_at.gte", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to items inserted before the given date.", "example": "2025-01-01T00:00:00Z", "in": "query", "name": "inserted_at.lt", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Limits the results to items inserted before or on the given date.", "example": "2025-01-01T00:00:00Z", "in": "query", "name": "inserted_at.lte", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The user ID to list messages for.", "example": "user-123", "in": "path", "name": "user_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMessagesResponse" } } }, "description": "OK" } }, "summary": "List user messages", "tags": [ "Messages", "Users" ], "x-ratelimit-tier": 4, "x-retention-policy": true } }, "/v1/integrations/hightouch/embedded-destination": { "post": { "callbacks": {}, "description": "Processes a Hightouch embedded destination RPC request.", "operationId": "processHightouchRpcRequest", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "id": { "description": "The unique identifier for the RPC request.", "type": "string", "x-struct": null, "x-validate": null }, "jsonrpc": { "description": "The JSON-RPC version.", "type": "string", "x-struct": null, "x-validate": null }, "method": { "description": "The method name to execute.", "type": "string", "x-struct": null, "x-validate": null }, "params": { "additionalProperties": true, "description": "The parameters for the method.", "type": "object", "x-struct": null, "x-validate": null } }, "required": [ "id", "method", "jsonrpc" ], "type": "object", "x-struct": null, "x-validate": null } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "id": { "description": "The request ID.", "type": "string", "x-struct": null, "x-validate": null }, "result": { "additionalProperties": true, "description": "The result of the RPC call.", "type": "object", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null } } }, "description": "OK" } }, "summary": "Process a Hightouch RPC request", "tags": [ "Integrations" ], "x-ratelimit-tier": 3 } }, "/v1/objects/{collection}/{object_id}/preferences/{id}/channel_types": { "put": { "callbacks": {}, "deprecated": true, "description": "Updates the channel type preferences for an object's preference set.", "operationId": "updateObjectPreferenceChannelTypes", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreferenceSet" } } }, "description": "OK" } }, "summary": "Update channel types in preference set", "tags": [ "Objects", "Preferences" ], "x-ratelimit-tier": 3 } }, "/v1/messages/{message_id}/interacted": { "put": { "callbacks": {}, "description": "Marks a message as `interacted` with by the user. This can include any user action on the message, with optional metadata about the specific interaction. Cannot include more than 5 key-value pairs, must not contain nested data. Read more about message engagement statuses [here](/send-notifications/message-statuses#engagement-status).", "operationId": "markMessageInteracted", "parameters": [ { "description": "The unique identifier for the message.", "example": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "in": "path", "name": "message_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageInteractedRequest" } } }, "description": "Params", "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Message" } ], "example": { "__typename": "Message", "actors": [ "user_123" ], "archived_at": null, "channel_id": "123e4567-e89b-12d3-a456-426614174000", "clicked_at": null, "data": { "foo": "bar" }, "engagement_statuses": [ "seen", "interacted" ], "id": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "inserted_at": "2021-01-01T00:00:00Z", "interacted_at": "2025-01-01T00:03:00Z", "link_clicked_at": null, "metadata": { "external_id": "123e4567-e89b-12d3-a456-426614174000" }, "read_at": null, "recipient": "user_123", "scheduled_at": null, "seen_at": "2025-01-01T00:01:00Z", "source": { "__typename": "NotificationSource", "categories": [ "collaboration" ], "key": "comment-created", "step_ref": "email_step_1", "version_id": "123e4567-e89b-12d3-a456-426614174000" }, "status": "sent", "tenant": "tenant_123", "updated_at": "2021-01-01T00:00:00Z", "workflow": "comment-created" }, "x-struct": null, "x-validate": null } } }, "description": "OK" } }, "summary": "Mark message as interacted", "tags": [ "Messages" ], "x-ratelimit-tier": 2, "x-retention-policy": true } }, "/v1/messages/{message_id}/unarchived": { "delete": { "callbacks": {}, "description": "Removes a message from the archived state, making it visible in the default message list in the feed again.", "operationId": "unarchiveMessage", "parameters": [ { "description": "The unique identifier for the message.", "example": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "in": "path", "name": "message_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Message" } ], "example": { "__typename": "Message", "actors": [ "user_123" ], "archived_at": null, "channel_id": "123e4567-e89b-12d3-a456-426614174000", "clicked_at": null, "data": { "foo": "bar" }, "engagement_statuses": [ "seen" ], "id": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "inserted_at": "2021-01-01T00:00:00Z", "interacted_at": null, "link_clicked_at": null, "metadata": { "external_id": "123e4567-e89b-12d3-a456-426614174000" }, "read_at": null, "recipient": "user_123", "scheduled_at": null, "seen_at": "2025-01-01T00:01:00Z", "source": { "__typename": "NotificationSource", "categories": [ "collaboration" ], "key": "comment-created", "step_ref": "email_step_1", "version_id": "123e4567-e89b-12d3-a456-426614174000" }, "status": "sent", "tenant": "tenant_123", "updated_at": "2021-01-01T00:00:00Z", "workflow": "comment-created" }, "x-struct": null, "x-validate": null } } }, "description": "OK" } }, "summary": "Unarchive message", "tags": [ "Messages" ], "x-ratelimit-tier": 2, "x-retention-policy": true } }, "/v1/users": { "get": { "callbacks": {}, "description": "Retrieve a paginated list of users in the environment. Defaults to 50 users per page.", "operationId": "listUsers", "parameters": [ { "description": "Associated resources to include in the response.", "in": "query", "name": "include[]", "required": false, "schema": { "items": { "enum": [ "preferences" ], "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } }, { "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/ListUsersResponse" } } }, "description": "OK" } }, "summary": "List users", "tags": [ "Users" ], "x-ratelimit-tier": 4 } }, "/v1/notify": { "post": { "callbacks": {}, "description": "Triggers a workflow with the given key, actor, recipients, and optional data.", "operationId": "triggerWorkflow", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Notify Request" } } }, "description": "Notify Payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Notify Response" } } }, "description": "OK" } }, "summary": "Trigger workflow", "tags": [ "Workflow Triggers" ], "x-ratelimit-tier": 3 } }, "/v1/providers/ms-teams/{channel_id}/teams": { "get": { "callbacks": {}, "description": "Get a list of teams belonging to the Microsoft Entra tenant. By default, archived and private channels are excluded from the results.", "operationId": "listTeamsForMsTeamsProvider", "parameters": [ { "description": "The ID of the Knock Microsoft Teams channel to get teams for.", "in": "path", "name": "channel_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "A JSON encoded string containing the Microsoft Teams tenant object reference.", "example": "{\"collection\":\"projects\",\"object_id\":\"project_123\"}", "in": "query", "name": "ms_teams_tenant_object", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "[OData param](https://learn.microsoft.com/en-us/graph/query-parameters) passed to the Microsoft Graph API to filter teams.", "example": "displayName eq 'My Team'", "in": "query", "name": "query_options.$filter", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "[OData param](https://learn.microsoft.com/en-us/graph/query-parameters) passed to the Microsoft Graph API to select fields on a team.", "example": "id,displayName,description", "in": "query", "name": "query_options.$select", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "[OData param](https://learn.microsoft.com/en-us/graph/query-parameters) passed to the Microsoft Graph API to limit the number of teams returned.", "example": 10, "in": "query", "name": "query_options.$top", "required": false, "schema": { "type": "integer", "x-struct": null, "x-validate": null } }, { "description": "[OData param](https://learn.microsoft.com/en-us/graph/query-parameters) passed to the Microsoft Graph API to retrieve the next page of results.", "in": "query", "name": "query_options.$skiptoken", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamsForMsTeamsProviderResponse" } } }, "description": "OK" } }, "summary": "List teams", "tags": [ "Providers", "Microsoft Teams" ], "x-ratelimit-tier": 2 } }, "/v1/messages/batch/read": { "post": { "callbacks": {}, "description": "Marks the given messages as `read`. Read more about message engagement statuses [here](/send-notifications/message-statuses#engagement-status).", "operationId": "batchMarkMessagesAsRead", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "message_ids": [ "2w3YUpTTOxuDvZFji8OMsKrG176", "2w3YVRbPXMIh8Zq6oBFcVDA5xes" ] }, "schema": { "$ref": "#/components/schemas/BatchMessagesStatusRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "The list of messages that were updated.", "example": [ { "__typename": "Message", "actors": [ "user_123" ], "archived_at": null, "channel_id": "123e4567-e89b-12d3-a456-426614174000", "clicked_at": null, "data": { "foo": "bar" }, "engagement_statuses": [ "seen", "read" ], "id": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "inserted_at": "2021-01-01T00:00:00Z", "interacted_at": null, "link_clicked_at": null, "metadata": { "external_id": "123e4567-e89b-12d3-a456-426614174000" }, "read_at": "2025-01-01T00:02:00Z", "recipient": "user_123", "scheduled_at": null, "seen_at": "2025-01-01T00:01:00Z", "source": { "__typename": "NotificationSource", "categories": [ "collaboration" ], "key": "comment-created", "version_id": "123e4567-e89b-12d3-a456-426614174000" }, "status": "sent", "tenant": "tenant_123", "updated_at": "2021-01-01T00:00:00Z", "workflow": "comment-created" } ], "items": { "allOf": [ { "$ref": "#/components/schemas/Message" } ], "example": { "__typename": "Message", "actors": [ "user_123" ], "archived_at": null, "channel_id": "123e4567-e89b-12d3-a456-426614174000", "clicked_at": null, "data": { "foo": "bar" }, "engagement_statuses": [ "seen", "read" ], "id": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "inserted_at": "2021-01-01T00:00:00Z", "interacted_at": null, "link_clicked_at": null, "metadata": { "external_id": "123e4567-e89b-12d3-a456-426614174000" }, "read_at": "2025-01-01T00:02:00Z", "recipient": "user_123", "scheduled_at": null, "seen_at": "2025-01-01T00:01:00Z", "source": { "__typename": "NotificationSource", "categories": [ "collaboration" ], "key": "comment-created", "version_id": "123e4567-e89b-12d3-a456-426614174000" }, "status": "sent", "tenant": "tenant_123", "updated_at": "2021-01-01T00:00:00Z", "workflow": "comment-created" }, "x-struct": null, "x-validate": null }, "title": "BatchListMessagesResponse", "type": "array", "x-struct": null, "x-validate": null } } }, "description": "OK" } }, "summary": "Mark messages as read", "tags": [ "Messages" ], "x-ratelimit-tier": 3, "x-retention-policy": true } }, "/v1/workflows/{key}/cancel": { "post": { "callbacks": {}, "description": "When invoked for a workflow using a specific workflow key and cancellation key, will cancel any queued workflow runs associated with that key/cancellation key pair. Can optionally be provided one or more recipients to scope the request to.", "operationId": "cancelWorkflow", "parameters": [ { "description": "The key of the workflow to cancel.", "in": "path", "name": "key", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "requestBody": { "content": { "application/json": { "example": { "cancellation_key": "cancel-workflow-123", "recipients": [ "jhammond" ] }, "schema": { "$ref": "#/components/schemas/CancelWorkflowRequest" } } }, "description": "Params", "required": true }, "responses": { "204": { "description": "No Content" } }, "summary": "Cancel workflow", "tags": [ "Workflows" ], "x-ratelimit-tier": 5 } }, "/v1/users/{user_id}/preferences/{id}/workflows/{key}": { "put": { "callbacks": {}, "deprecated": true, "description": "Updates a single workflow in a specific user preference set. This operation is deprecated.", "operationId": "updateUserPreferenceWorkflow", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreferenceSet" } } }, "description": "OK" } }, "summary": "Update workflow in user preference set", "tags": [ "Users", "Preferences" ], "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 } }, "/v1/tenants/bulk/set": { "post": { "callbacks": {}, "description": "Set or update up to 1,000 tenants in a single operation.", "operationId": "bulkSetTenants", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "tenants": [ { "id": "tenant_1", "name": "Acme Corp, Inc." } ] }, "schema": { "$ref": "#/components/schemas/BulkSetTenantsRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOperation" } } }, "description": "OK" } }, "summary": "Bulk set tenants", "tags": [ "Tenants", "Bulk operations" ], "x-ratelimit-tier": 1 } }, "/v1/objects/{collection}/bulk/subscriptions/delete": { "post": { "callbacks": {}, "description": "Delete subscriptions for many objects in a single collection type. If a subscription for an object in the collection doesn't exist, it will be skipped.", "operationId": "bulkDeleteSubscriptions", "parameters": [ { "description": "The collection this object belongs to.", "example": "projects", "in": "path", "name": "collection", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "requestBody": { "content": { "application/json": { "example": { "subscriptions": [ { "id": "subscribed-to-object-1", "recipients": [ { "collection": "projects", "id": "subscriber-project-1" }, "subscriber-user-1" ] }, { "id": "subscribed-to-object-2", "recipients": [ "subscriber-user-2" ] } ] }, "schema": { "$ref": "#/components/schemas/BulkDeleteSubscriptionsRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOperation" } } }, "description": "OK" } }, "summary": "Bulk delete subscriptions", "tags": [ "Objects", "Subscriptions", "Bulk operations" ], "x-ratelimit-tier": 1 } }, "/v1/objects/{collection}/{object_id}/preferences/{id}": { "delete": { "callbacks": {}, "description": "Unsets the preference set for the object, removing it entirely.", "operationId": "deleteObjectPreferenceSet", "parameters": [ { "description": "Unique identifier for the object.", "in": "path", "name": "object_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The collection this object belongs to.", "in": "path", "name": "collection", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Unique identifier for the preference set.", "in": "path", "name": "id", "required": true, "schema": { "default": "default", "example": "default", "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "204": { "description": "No Content" } }, "summary": "Delete object preference set", "tags": [ "Objects", "Preferences" ], "x-ratelimit-tier": 3 }, "get": { "callbacks": {}, "description": "Returns the preference set for the specified object and preference set `id`.", "operationId": "getObjectPreferenceSet", "parameters": [ { "description": "Unique identifier for the object.", "in": "path", "name": "object_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The collection this object belongs to.", "in": "path", "name": "collection", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Unique identifier for the preference set.", "in": "path", "name": "id", "required": true, "schema": { "default": "default", "example": "default", "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreferenceSet" } } }, "description": "OK" } }, "summary": "Get object preference set", "tags": [ "Objects", "Preferences" ], "x-ratelimit-tier": 4 }, "put": { "callbacks": {}, "description": "Sets preferences within the given preference set. By default, this is a destructive operation and will replace any existing preferences with the preferences given. Use '__persistence_strategy': 'merge' to merge with existing preferences instead. If no object exists in the current environment for the given `:collection` and `:object_id`, Knock will create the object as part of this request. The preference set `:id` can be either `default` or a `tenant.id`. Learn more about [per-tenant preferences](/preferences/tenant-preferences).", "operationId": "updateObjectPreferenceSet", "parameters": [ { "description": "Unique identifier for the object.", "in": "path", "name": "object_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The collection this object belongs to.", "in": "path", "name": "collection", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Unique identifier for the preference set.", "in": "path", "name": "id", "required": true, "schema": { "default": "default", "example": "default", "type": "string", "x-struct": null, "x-validate": null } } ], "requestBody": { "content": { "application/json": { "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 } } } }, "schema": { "$ref": "#/components/schemas/PreferenceSetRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreferenceSet" } } }, "description": "OK" } }, "summary": "Update a preference set", "tags": [ "Objects", "Preferences" ], "x-ratelimit-tier": 3 } }, "/v1/providers/ms-teams/{channel_id}/revoke_access": { "put": { "callbacks": {}, "description": "Remove a Microsoft Entra tenant ID from a Microsoft Teams tenant object.", "operationId": "msTeamsProviderRevokeAccess", "parameters": [ { "description": "The ID of the Knock Microsoft Teams channel to revoke access for.", "in": "path", "name": "channel_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "A JSON encoded string containing the Microsoft Teams tenant object reference.", "example": "{\"collection\":\"projects\",\"object_id\":\"project_123\"}", "in": "query", "name": "ms_teams_tenant_object", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "A response indicating the operation was successful.", "example": { "ok": "ok" }, "properties": { "ok": { "description": "OK response.", "example": "ok", "type": "string", "x-struct": null, "x-validate": null } }, "title": "SuccessResponse", "type": "object", "x-struct": null, "x-validate": null } } }, "description": "OK" }, "403": { "content": { "application/json": { "schema": { "description": "Authentication error response", "example": { "code": "authorization", "message": "Access token not set.", "status": 403, "type": "authentication_error" }, "properties": { "code": { "description": "The error code.", "example": "authorization", "type": "string", "x-struct": null, "x-validate": null }, "message": { "description": "The error message.", "example": "Access token not set.", "type": "string", "x-struct": null, "x-validate": null }, "status": { "description": "The HTTP status code.", "example": 403, "type": "integer", "x-struct": null, "x-validate": null }, "type": { "description": "The error type.", "example": "authentication_error", "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "code", "message", "status", "type" ], "title": "AuthenticationError", "type": "object", "x-struct": null, "x-validate": null } } }, "description": "Forbidden" } }, "summary": "Revoke access", "tags": [ "Providers", "Microsoft Teams" ], "x-ratelimit-tier": 2 } }, "/v1/messages/{message_id}": { "get": { "callbacks": {}, "description": "Retrieves a specific message by its ID.", "operationId": "getMessage", "parameters": [ { "description": "The unique identifier for the message.", "example": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "in": "path", "name": "message_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } }, "description": "OK" } }, "summary": "Get message", "tags": [ "Messages" ], "x-ratelimit-tier": 4, "x-retention-policy": true } }, "/v1/users/{user_id}/preferences/{id}": { "delete": { "callbacks": {}, "description": "Unsets the preference set for the user, removing it entirely.", "operationId": "deleteUserPreferenceSet", "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": "Unique identifier for the preference set.", "in": "path", "name": "id", "required": true, "schema": { "default": "default", "example": "default", "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "204": { "description": "No Content" } }, "summary": "Delete user preference set", "tags": [ "Users", "Preferences" ], "x-ratelimit-tier": 3 }, "get": { "callbacks": {}, "description": "Retrieves a specific preference set for a user identified by the preference set ID.", "operationId": "getUserPreferenceSet", "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": "Unique identifier for the preference set.", "in": "path", "name": "id", "required": true, "schema": { "default": "default", "example": "default", "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The unique identifier for the tenant.", "in": "query", "name": "tenant", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreferenceSet" } } }, "description": "OK" } }, "summary": "Get user preference set", "tags": [ "Users", "Preferences" ], "x-ratelimit-tier": 4 }, "put": { "callbacks": {}, "description": "Updates a complete preference set for a user. By default, this is a destructive operation and will replace any existing preferences with the preferences given. Use '__persistence_strategy__': 'merge' to merge with existing preferences instead.", "operationId": "updateUserPreferenceSet", "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": "Unique identifier for the preference set.", "in": "path", "name": "id", "required": true, "schema": { "default": "default", "example": "default", "type": "string", "x-struct": null, "x-validate": null } } ], "requestBody": { "content": { "application/json": { "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 } } } }, "schema": { "$ref": "#/components/schemas/PreferenceSetRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreferenceSet" } } }, "description": "OK" } }, "summary": "Update user preference set", "tags": [ "Users", "Preferences" ], "x-ratelimit-tier": 3 } }, "/v1/objects/{collection}/{object_id}/subscriptions": { "delete": { "callbacks": {}, "description": "Delete subscriptions for the specified recipients from an object. Returns the list of deleted subscriptions.", "operationId": "deleteSubscriptionsForObject", "parameters": [ { "description": "Unique identifier for the object.", "in": "path", "name": "object_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The collection this object belongs to.", "in": "path", "name": "collection", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSubscriptionsRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionsResponse" } } }, "description": "OK" } }, "summary": "Delete subscriptions", "tags": [ "Subscriptions", "Objects" ], "x-ratelimit-tier": 3 }, "get": { "callbacks": {}, "description": "List subscriptions for an object. Either list the recipients that subscribe to the provided object, or list the objects that the provided object is subscribed to. Determined by the `mode` query parameter.", "operationId": "listSubscriptionsForObject", "parameters": [ { "description": "Mode of the request. `recipient` to list the objects that the provided object is subscribed to, `object` to list the recipients that subscribe to the provided object.", "in": "query", "name": "mode", "required": false, "schema": { "default": "object", "enum": [ "recipient", "object" ], "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Additional fields to include in the response.", "in": "query", "name": "include[]", "required": false, "schema": { "items": { "enum": [ "preferences" ], "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } }, { "description": "Recipients to filter by (only used if mode is `object`).", "in": "query", "name": "recipients[]", "required": false, "schema": { "items": { "$ref": "#/components/schemas/RecipientReference" }, "type": "array", "x-struct": null, "x-validate": null } }, { "description": "Objects to filter by (only used if mode is `recipient`).", "in": "query", "name": "objects[]", "required": false, "schema": { "items": { "$ref": "#/components/schemas/ObjectReference" }, "type": "array", "x-struct": null, "x-validate": null } }, { "description": "Unique identifier for the object.", "in": "path", "name": "object_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The collection this object belongs to.", "in": "path", "name": "collection", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The 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/ListSubscriptionsResponse" } } }, "description": "OK" } }, "summary": "List subscriptions", "tags": [ "Subscriptions", "Objects" ], "x-ratelimit-tier": 4 }, "post": { "callbacks": {}, "description": "Add subscriptions for an object. If a subscription already exists, it will be updated. This endpoint also handles [inline identifications](/managing-recipients/identifying-recipients#inline-identifying-recipients) for the `recipient`.", "operationId": "addSubscriptionsForObject", "parameters": [ { "description": "Unique identifier for the object.", "in": "path", "name": "object_id", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "The collection this object belongs to.", "in": "path", "name": "collection", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "requestBody": { "content": { "application/json": { "example": { "properties": { "key": "value" }, "recipients": [ "user_1", "user_2" ] }, "schema": { "$ref": "#/components/schemas/UpsertSubscriptionsRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionsResponse" } } }, "description": "OK" } }, "summary": "Add subscriptions", "tags": [ "Subscriptions", "Objects" ], "x-ratelimit-tier": 3 } }, "/v1/messages/batch/interacted": { "post": { "callbacks": {}, "description": "Marks the given messages as interacted with by the user. This can include any user action on the message, with optional metadata about the specific interaction. Cannot include more than 5 key-value pairs, must not contain nested data. Read more about message engagement statuses [here](/send-notifications/message-statuses#engagement-status).", "operationId": "batchMarkMessagesAsInteracted", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "message_ids": [ "1jNaXzB2RZX3LY8wVQnfCKyPnv7" ], "metadata": { "key": "value" } }, "schema": { "$ref": "#/components/schemas/BatchMessagesInteractedRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "The list of messages that were updated.", "example": [ { "__typename": "Message", "actors": [ "user_123" ], "archived_at": null, "channel_id": "123e4567-e89b-12d3-a456-426614174000", "clicked_at": null, "data": { "foo": "bar" }, "engagement_statuses": [ "seen", "interacted" ], "id": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "inserted_at": "2021-01-01T00:00:00Z", "interacted_at": "2025-01-01T00:03:00Z", "link_clicked_at": null, "metadata": { "external_id": "123e4567-e89b-12d3-a456-426614174000" }, "read_at": null, "recipient": "user_123", "scheduled_at": null, "seen_at": "2025-01-01T00:01:00Z", "source": { "__typename": "NotificationSource", "categories": [ "collaboration" ], "key": "comment-created", "version_id": "123e4567-e89b-12d3-a456-426614174000" }, "status": "sent", "tenant": "tenant_123", "updated_at": "2021-01-01T00:00:00Z", "workflow": "comment-created" } ], "items": { "allOf": [ { "$ref": "#/components/schemas/Message" } ], "example": { "__typename": "Message", "actors": [ "user_123" ], "archived_at": null, "channel_id": "123e4567-e89b-12d3-a456-426614174000", "clicked_at": null, "data": { "foo": "bar" }, "engagement_statuses": [ "seen", "interacted" ], "id": "1jNaXzB2RZX3LY8wVQnfCKyPnv7", "inserted_at": "2021-01-01T00:00:00Z", "interacted_at": "2025-01-01T00:03:00Z", "link_clicked_at": null, "metadata": { "external_id": "123e4567-e89b-12d3-a456-426614174000" }, "read_at": null, "recipient": "user_123", "scheduled_at": null, "seen_at": "2025-01-01T00:01:00Z", "source": { "__typename": "NotificationSource", "categories": [ "collaboration" ], "key": "comment-created", "version_id": "123e4567-e89b-12d3-a456-426614174000" }, "status": "sent", "tenant": "tenant_123", "updated_at": "2021-01-01T00:00:00Z", "workflow": "comment-created" }, "x-struct": null, "x-validate": null }, "title": "BatchListMessagesResponse", "type": "array", "x-struct": null, "x-validate": null } } }, "description": "OK" } }, "summary": "Mark messages as interacted", "tags": [ "Messages" ], "x-ratelimit-tier": 3, "x-retention-policy": true } }, "/v1/users/{user_id}/preferences/{id}/channel_types": { "put": { "callbacks": {}, "deprecated": true, "description": "Updates the channel types in a specific user preference set. This operation is deprecated.", "operationId": "updateUserPreferenceChannelTypes", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreferenceSet" } } }, "description": "OK" } }, "summary": "Update channel types in preference set", "tags": [ "Users", "Preferences" ], "x-ratelimit-tier": 3 } }, "/v1/objects/{collection}/bulk/set": { "post": { "callbacks": {}, "description": "Bulk sets up to 1,000 objects at a time in the specified collection.", "operationId": "bulkSetObjects", "parameters": [ { "description": "The collection this object belongs to.", "in": "path", "name": "collection", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "requestBody": { "content": { "application/json": { "example": { "objects": [ { "id": "project_1", "name": "My project" } ] }, "schema": { "$ref": "#/components/schemas/BulkSetObjectsRequest" } } }, "description": "Params", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOperation" } } }, "description": "OK" } }, "summary": "Bulk set objects", "tags": [ "Objects", "Bulk operations" ], "x-ratelimit-tier": 1 } } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "https://api.knock.app", "variables": {} } ], "tags": [ { "description": "An Audience is a segment of users.", "name": "Audiences" }, { "description": "A bulk operation is a set of changes applied across zero or more records triggered via a call to the Knock API and performed asynchronously.", "name": "Bulk operations" }, { "description": "Channel data is data that is specific to a recipient and a channel, like push tokens, or one or more Slack connections.", "name": "Channel data" }, { "description": "A message sent to a single recipient on a channel.", "name": "Messages" }, { "description": "An object represents a resource in your system that you want to map into Knock.", "name": "Objects" }, { "description": "Preferences are a way to configure how notifications are sent to recipients. They are a set of configuration that determines whether a recipient should receive a notification for a given workflow on a specific channel.", "name": "Preferences" }, { "description": "A provider represents a third-party service that Knock integrates with and is configured via a channel.", "name": "Providers" }, { "description": "A schedule is a per-recipient, timezone-aware configuration for when to invoke a workflow.", "name": "Schedules" }, { "description": "A subscription represents a connection between a recipient and an object, used to represent a list.", "name": "Subscriptions" }, { "description": "A tenant represents a top-level entity from your system, like a company, organization, account, or workspace.", "name": "Tenants" }, { "description": "A user is an individual from your system, represented in Knock. They are most commonly a recipient of a notification.", "name": "Users" }, { "description": "A workflow run represents an individual execution of a workflow for a specific recipient.", "name": "Workflow recipient runs" }, { "description": "Operations for triggering and canceling workflow executions.", "name": "Workflow Triggers" }, { "description": "A workflow is a structured set of steps that is triggered to produce notifications sent over channels.", "name": "Workflows" } ] }