Plain integration: operations for AI agents
Plain connects to Type.com as an integration. This page lists the 603 operations documented for Claude and Codex in Type.com: 232 read, 281 write, 90 destructive.
About Plain
Plain is a collaborative support platform for B2B support teams, offering a modern, AI-powered interface to consolidate support channels and assist customers efficiently.
Categories: Customer Support
How to connect Plain to Type.com
- Access
- Organization connection: one shared account for the workspace.
To add the connection, follow the steps in Space connections.
Documented operations
603 operations. Your connection's permissions determine which operations are available. API references describe the vendor surface; they do not expand your connection's credentials or access.
603 operations listed.
Queries
- Read
myUserAccount
Returns the UserAccount for the currently authenticated user, or null if no account has been created yet. Useful during onboarding to check whether account setup is complete.
POST - Read
myUser
Returns the full User record for the currently authenticated human user within the current workspace. Returns null if the caller is not a human user or is not a member of a workspace. Not available to machine users.
POST - Read
myMachineUser
Returns the machine user that owns the current API key. Only callable with a machine user API key; returns a FORBIDDEN error when called with a human user session.
POST - Read
myWorkspace
Returns the Workspace associated with the current API key or session. Useful for confirming which workspace a request is scoped to. Returns null if no workspace is in context.
POST - Read
myPermissions
Returns the full list of permission strings granted to the currently authenticated user or machine user in this workspace. Useful for inspecting what actions the caller is authorized to perform.
POST - Read
myWorkspaces
Returns all workspaces the currently authenticated human user belongs to, paginated. Not available to machine users. Use this to let users switch between workspaces.
POST - Read
myWorkspaceInvites
Returns all pending workspace invites sent to the currently authenticated user's email address. Use this to let a user see and act on workspaces they have been invited to join.
POST - Read
mySlackIntegration
Returns the current user's personal Slack notifications integration, or null if none is connected.
POST - Read
mySlackInstallationInfo
Returns a Slack OAuth installation URL for the current user to connect their personal Slack notifications integration. Pass this URL to Slack's OAuth flow and exchange the resulting code with createMySlackIntegration.
POST - Read
myLinearIntegration
Returns the current user's Linear integration, or null if no integration has been set up.
POST - Read
myLinearInstallationInfo
Returns the OAuth installation URL to initiate the Linear authorization flow for the current user. Pass the returned installationUrl to your UI so the user can grant Plain access to their Linear account. The redirectUrl must match the redirect URI registered for the Linear OAuth app; the authorization code delivered there is then passed to createMyLinearIntegration.
POST - Read
myLinearIntegrationToken
Returns a short-lived Linear access token for the current user's integration, or null if no integration exists. The token is automatically refreshed when it is close to expiry, so callers always receive a usable credential. Use this token to make Linear API calls on behalf of the authenticated user.
POST - Read
linearAppIntegration
The workspace-level Linear app integration, if one has been authorised.
POST - Read
workspaceLinearInstallationInfo
Builds the Linear OAuth installation URL for the app actor flow (actor=app).
POST - Read
githubUserAuthIntegration
Returns the GitHub user authentication integration for the currently authenticated user, or null if no integration exists.
POST - Read
workspaceCursorIntegration
Returns the workspace's Cursor integration, or null if none has been configured.
POST - Read
cursorRepositories
Returns the list of GitHub repositories accessible via the given Cursor integration. Results are fetched live from the Cursor API and cached for up to 5 minutes. Requires the `workspaceCursorIntegration:read` permission.
POST - Read
myJiraIntegrationToken
Returns the current user's Jira OAuth access token, automatically refreshing it if it is near expiry. Returns null if the user has not connected their Jira account. Requires the `userJiraIntegration:read` permission.
POST - Read
myEmailSignature
Returns the email signature configured for the currently authenticated user, or null if none has been set.
POST - Read
myFavoritePages
Returns the favorite pages saved by the currently authenticated user, ordered by most recently created first. Each user's favorites are independent — this query only returns pages belonging to the caller.
POST - Read
billingPlans
Returns the available billing plans that can be selected for self-serve checkout. Supports standard forward and backward pagination.
POST - Read
myBillingSubscription
Returns the current workspace billing subscription, including plan, status, trial info, feature entitlements, and credit balances. Returns null if the workspace has no billing account.
POST - Read
myBillingRota
Returns the current billing rota for the workspace, listing which users are actively on-rota and which are off-rota. The rota is used to track which users currently consume an active eng-rota seat.
POST - Read
sidekickCreditUsageByDay
Credit usage for the workspace, bucketed by the UTC day each billable item resolved, over the given date range. Covers Sidekick sessions and work done by the workspace's own agents. Use it to show a per-day breakdown of credit consumption. Requires the `billing:read` permission.
POST - Read
sidekickCreditBalance
The workspace's current Sidekick (Plain) credit balance: the monthly allowance grant/used/remaining and when it resets, plus any purchased top-up remaining. Use it to answer how many credits are left. Requires the `billing:read` permission.
POST - Read
creditSpend
Every billable item the workspace has used credits on, newest first: Sidekick sessions, Sidekick actions a workflow ran, and work done by the workspace's own agents. Items with status FREE_BETA were not charged; their credits show what they would have cost. Use it to show the line-by-line breakdown behind a credit total. Supports standard forward and backward pagination. Requires the `billing:read` permission.
POST - Read
workOSConfiguration
Returns short-lived WorkOS admin portal URLs and an embeddable widget token so workspace admins can configure SSO, directory sync, and domain verification. Each URL is a single-use link generated on the fly by WorkOS; fetch this query immediately before redirecting the user. Requires the `workspace:edit` permission and an active SSO entitlement (Frontier plan or above). Returns null if the workspace has no WorkOS organization configured.
POST - Read
labelTypes
Returns a paginated list of label types in the workspace. By default includes both active and archived label types; pass `filters: { isArchived: false }` to exclude archived ones. Requires the `labelType:read` permission.
POST - Read
labelType
Returns a single label type by its ID. Returns null if no label type with that ID exists. Requires the `labelType:read` permission.
POST - Read
labelTypeByExternalId
Returns a label type by its external ID. Returns null if no match is found. External IDs are unique within a workspace and are set when creating or updating a label type. Requires the `labelType:read` permission.
POST - Read
suggestedLabelTypes
Returns the PENDING AI-suggested label types awaiting review, most recently created first. Requires the `suggestedLabelType:read` permission.
POST - Read
roles
Returns all roles available in the workspace, including both built-in roles (Owner, Admin, Support, Viewer, None) and any custom roles. Supports cursor-based pagination. Requires the `roles:read` permission.
POST - Read
customRoles
Returns all custom roles defined in the workspace. Use this to list the custom roles you have created and inspect their scope definitions. Supports cursor-based pagination. Requires the `roles:read` permission.
POST - Read
customRole
Returns a single custom role by its ID, or null if not found. Requires the `roles:read` permission.
POST - Read
timelineEntries
Returns a paginated list of all timeline entries for a customer, ordered from oldest to newest. Timeline entries include every event, message, note, and automated activity that has occurred across all of the customer's threads. Supports cursor-based pagination via `first`/`after` and `last`/`before` arguments.
POST - Read
timelineEntry
Fetches a single timeline entry by its ID within a customer's timeline. Returns null if the entry does not exist.
POST - Read
threadTimelineEntry
Fetches a single timeline entry from a thread. Returns null if the thread does not exist or is not visible to the caller, or if the entry does not exist or belongs to another thread.
POST - Read
workspace
Fetch a workspace by its ID. Returns null if the workspace does not exist or the caller does not have access to it.
POST - Read
user
Fetch a single workspace member by their ID. Returns null if no user with that ID exists. Requires the `user:read` permission.
POST - Read
userByEmail
Fetch a workspace member by their email address. Returns null if no match is found. Deleted users are also returned — check the `isDeleted`, `deletedAt`, and `deletedBy` fields to determine whether the user has been removed. Requires the `user:read` permission.
POST - Read
users
List all human members of the workspace, with optional filters to narrow results by role assignability. Supports cursor-based pagination. Requires the `user:read` permission.
POST - Read
workspaceInvites
Returns all pending invites for the current workspace. Use this to view outstanding invitations and their status from an admin perspective.
POST - Read
customer
Fetch a single customer by their Plain customer ID. Returns null if no customer with that ID exists. Requires the `customer:read` permission.
POST - Read
customers
Fetch a paginated list of all customers in the workspace. Supports filtering by group membership, company, spam status and more via `filters`, and ordering via `sortBy`. Use cursor-based pagination (`first`/`after` or `last`/`before`) to page through large result sets. Requires the `customer:read` permission.
POST - Read
customerByEmail
Fetch a customer by their email address. Returns null if no customer with that email exists. Requires the `customer:read` permission.
POST - Read
customerByExternalId
Get a customer by its external ID. A customer's external ID is unique within a workspace.
POST - Read
customerGroup
Fetch a single customer group by its ID. Returns null if no group with the given ID exists in the workspace.
POST - Read
customerGroups
Fetch a paginated list of all customer groups in the workspace. Optionally filter by external IDs using the `filters` argument. Uses cursor-based pagination.
POST - Read
threadFieldSchemas
Returns all thread field schemas defined in the workspace, paginated. Use this to discover which custom fields exist and their configuration before reading or writing thread field values. Selecting the `createdBy`/`updatedBy` actor down to its `user` additionally requires the `user:read` permission; a token without it can query an empty workspace but starts failing once a schema exists and that selection is present.
POST - Read
threadFieldSchema
Fetches a single thread field schema by its ID. Returns null if no schema with the given ID exists. Selecting the `createdBy`/`updatedBy` actor down to its `user` additionally requires the `user:read` permission.
POST - Read
customerCardInstances
Returns the current customer card instances for a customer, triggering a fresh load for any cards that are expired or in an error state. Cards that are cached and within their TTL are returned immediately as `CustomerCardInstanceLoaded`. Cards that need to be fetched are returned as `CustomerCardInstanceLoading`; subscribe to `customerCardInstanceChanges` to receive the result when loading completes. Pass `threadId` to provide thread context to your card API endpoint. A maximum of 25 card instances will be returned, due to only allowing 25 customer card configs.
POST - Read
searchCustomers
Search for customers using a case-insensitive partial match across name, short name, email, and external ID. Results are sorted by most recently active first. Best suited for human-driven lookups (e.g. a search box) rather than precise programmatic resolution — use `customerByEmail` or `customerByExternalId` for exact lookups. Optionally narrow the results with `filters` (group membership, company, tenant, Slack channel and more). Requires the `customer:read` permission.
POST - Read
snippets
Returns a paginated list of all snippets in the workspace. Use this to sync or display the full snippet library. Supports standard forward and backward cursor pagination. Requires the `snippet:read` permission.
POST - Read
snippet
Fetches a single snippet by its ID, or null if no snippet with that ID exists. Returns soft-deleted snippets (where `isDeleted` is true). Requires the `snippet:read` permission.
POST - Read
broadcasts
Returns a paginated list of the workspace's broadcasts, newest first. Soft-deleted broadcasts are excluded. Optionally narrow the results with `filters` (status). Supports standard forward and backward cursor pagination. Requires the `broadcast:read` permission.
POST - Read
searchBroadcasts
Searches broadcasts by name (case-insensitive partial match). Soft-deleted broadcasts are excluded. Optionally narrow the results with `filters` (status), which applies on top of the name match. Requires the `broadcast:read` permission.
POST - Read
broadcast
Fetches a single broadcast by its ID, or null if no broadcast with that ID exists. Returns soft-deleted broadcasts (where `isDeleted` is true). Requires the `broadcast:read` permission.
POST - Read
broadcastRecipientUnsubscribes
Returns a paginated list of Slack channels that have opted out of broadcasts, newest first. Requires the `broadcast:read` permission and the broadcasts feature flag.
POST - Read
broadcastAudiences
Returns a paginated list of the workspace's broadcast audiences, newest first. Soft-deleted audiences are excluded. Requires the `broadcastAudience:read` permission.
POST - Read
broadcastAudience
Fetches a single broadcast audience by its ID, or null if no audience with that ID exists. Requires the `broadcastAudience:read` permission.
POST - Read
broadcastSendTargetRecipients
Who a send target resolves to right now. Takes the target rather than an id, so it answers for a filter still being written — before an audience is saved, or before a broadcast's target is committed — as readily as for one about to be sent. Point-in-time: the number moves as tenants, tiers and tenant fields change, and as channels are connected or disabled. Resolved through the same path a send uses, so it is what would actually be delivered to rather than an estimate assembled another way. Resolves the target on every call. Requires the `broadcast:read` permission.
POST - Read
workspaceEmailSettings
Returns the workspace's email settings, including whether email is enabled, any custom domain configuration, and BCC addresses.
POST - Read
emailSuppression
Returns the suppression for a specific email address, or null when the address is not suppressed.
POST - Read
workspaceChatSettings
Returns the workspace-level chat settings, including whether the live-chat channel is enabled for this workspace.
POST - Read
workspaceSetup
Returns how far this workspace has progressed through setup: channels, teammates, label types, tiers, automation and Sidekick Agent tools. Backs both the Onboarding checklist and the Sidekick Agent onboarding skill, so the two can never disagree.
POST - Read
machineUser
Fetches a single machine user by ID. Returns null if no machine user with the given ID exists in the workspace.
POST - Read
machineUsers
Returns a paginated list of all machine users in the workspace. Use the optional `filters.type` argument to restrict results to a specific machine user type (e.g. API_USER or AI_AGENT).
POST - Read
oauthApp
Fetches a single OAuth app by ID. Returns null if no OAuth app with the given ID exists in the workspace. Requires the `oauthApp:read` permission.
POST - Read
oauthApps
Returns a paginated list of the workspace's OAuth apps, oldest first. Requires the `oauthApp:read` permission.
POST - Read
permissions
Returns the complete list of all permission strings defined in Plain, sorted alphabetically. Use this to discover valid permission values when building role or API key management UIs. Requires the `permission:read` permission.
POST - Read
workspaceMSTeamsInstallationInfo
Returns the Microsoft Teams admin-consent URL that a workspace administrator must visit to authorize Plain's bot for the workspace's Azure AD tenant. Pass the URL the user should be redirected to after consent as `redirectUrl`. If the workspace already has an integration, the URL is scoped to that tenant to prevent accidentally consenting in the wrong one.
POST - Read
workspaceMSTeamsIntegration
Returns the workspace-level Microsoft Teams integration, or null if none has been created yet.
POST - Read
myMSTeamsInstallationInfo
Returns the OAuth installation URL for the current user to connect their personal Microsoft Teams account to Plain. Returns null in `installationUrl` if the workspace does not have an MS Teams workspace integration configured.
POST - Read
myMSTeamsIntegration
Returns the Microsoft Teams integration for the currently authenticated user, or null if the user has not connected their account.
POST - Read
connectedMSTeamsChannels
Returns a paginated list of Microsoft Teams channels that are connected to this workspace. Supports forward and backward cursor pagination.
POST - Read
getMSTeamsMembersForChannel
Fetches the current members of a Microsoft Teams channel directly from the Teams API. Requires a workspace MS Teams integration and calls Microsoft Graph; use this to populate member lists when resolving customers for a channel.
POST - Read
threadByMSTeamsMessage
Resolves a Microsoft Teams message to the Plain thread its conversation is on. If the message's thread was closed and the conversation continued in a successor thread, returns the open successor; if there is no open successor, returns the closed thread, which has `lockedAt` set. Returns null if Plain has not ingested the message. For a channel post, pass the root post's ID. After `createThreadFromMSTeamsMessage` returns no thread, poll this query until it returns a thread whose `lockedAt` is null. While the first thread is being created it returns null; while a successor to a closed thread is being created it returns the closed thread. Requires the `thread:read` permission.
POST - Read
workspaceSlackInstallationInfo
Returns a Slack OAuth installation URL for connecting a workspace-level Slack notifications integration. Pass this URL to Slack's OAuth flow and exchange the resulting code with createWorkspaceSlackIntegration.
POST - Read
workspaceSlackIntegrations
Returns a paginated list of all workspace-level Slack notifications integrations for this workspace.
POST - Read
workspaceSlackIntegration
Returns a single workspace-level Slack notifications integration by ID, or null if not found.
POST - Read
workspaceSlackChannelInstallationInfo
Returns a Slack OAuth installation URL for connecting a workspace Slack channel integration. Pass this URL to Slack's OAuth flow and exchange the resulting code with createWorkspaceSlackChannelIntegration.
POST - Read
workspaceSlackChannelIntegration
Returns a single workspace Slack channel integration by ID, or null if not found.
POST - Read
workspaceSlackChannelIntegrations
Returns a paginated list of all workspace Slack channel integrations for this workspace.
POST - Read
workspaceSlackSidekickInstallationInfo
Returns the OAuth installation URL to begin installing Plain's Sidekick Agent into your Slack workspace. Pass the returned URL to your users to redirect them through Slack's OAuth flow; on completion, pass the resulting auth code to createWorkspaceSlackSidekickIntegration.
POST - Read
workspaceSlackSidekickIntegration
Returns the current workspace's Slack Sidekick Agent integration, or null if Sidekick Agent has not been installed. Requires the workspaceSlackSidekickIntegration:read permission.
POST - Read
workspaceDiscordChannelInstallationInfo
Returns the Discord OAuth installation URL needed to connect a Discord server (guild) to this workspace. Redirect the user to the returned URL to begin the OAuth flow; after authorization Discord will redirect back to the provided `redirectUrl` with an `authCode` you can pass to `createWorkspaceDiscordChannelIntegration`.
POST - Read
workspaceDiscordChannelIntegration
Fetches a single workspace Discord channel integration by its ID. Returns null if no integration with that ID exists.
POST - Read
workspaceDiscordChannelIntegrations
Returns a paginated list of all Discord server (guild) channel integrations connected to this workspace.
POST - Read
userAuthDiscordChannelIntegration
Returns the current user's personal Discord authentication for a specific guild, or null if the user has not connected their Discord account to that guild.
POST - Read
userAuthDiscordChannelIntegrations
Returns a paginated list of all personal Discord authentication integrations for the current user across all guilds.
POST - Read
userAuthDiscordChannelInstallationInfo
Returns the Discord OAuth URL for a user to personally authenticate with Discord. Individual users must complete this flow (in addition to the workspace-level integration) before they can send Discord messages on behalf of themselves. After authorization, Discord redirects back to `redirectUrl` with an `authCode` for `createUserAuthDiscordChannelIntegration`.
POST - Read
searchThreadSlackUsers
Searches for slack users in a thread based on a search term. The search term can be part of either the slack's handle or full name.
POST - Read
searchSlackUsers
Searches for slack users in a slack channel based on a search term. The search term can be part of either the slack's handle or full name.
POST - Read
suggestedSlackTeammates
Suggests teammates to invite to Plain, sourced from the members of the workspace's connected Slack discussion channels. Only members of the workspace's own Slack team are included (Slack Connect guests are excluded), and anyone (matched by email, case-insensitive) who is already a member of this workspace or has a pending invite to it is excluded. Returns an empty list when there are no connected, enabled discussion channels for the given slackTeamId (e.g. a Slack Connect channel integration).
POST - Read
connectedSlackChannels
Gets all slack channels for this workspace, which match the specified filters.
POST - Read
connectedSlackChannel
Returns a single connected Slack channel by its Plain ID, or null if not found.
POST - Read
testChannel
The Slack test channel for one workspace Slack integration, or null until the first Slack test thread creates it. There is one test channel per integration. Requires the `workspaceSlackIntegration:read` and `connectedSlackChannel:read` permissions.
POST - Read
slackAutoJoinRules
Gets the auto-join rules for a workspace slack channel integration. Rules that have not yet been saved through `setSlackAutoJoinRules` are read from the legacy prefix/suffix settings and have a null id.
POST - Read
threadSlackUser
Returns a Slack user associated with the given thread, looked up by their Slack user ID. Returns null if the user is not found in that thread's Slack context.
POST - Read
slackUser
Returns a Slack user within a specific channel, looked up by their Slack user ID. Returns null if the user is not found in that channel.
POST - Read
threadBySlackPermalink
Resolves a Slack message permalink to the Plain thread it belongs to. Returns null if no thread is associated with the given Slack message.
POST - Read
threadBySlackMessage
Resolves a Slack message to the Plain thread it belongs to, using the same channel ID and message timestamp as `createThreadFromSlackMessage`. Returns null if no thread is associated with the given Slack message. Requires the `thread:read` permission.
POST - Read
userSlackChannelMemberships
Returns the Slack channels the current user belongs to within the given Slack workspace. Useful for populating channel pickers in UI integrations.
POST - Read
userAuthSlackIntegration
Returns the current user's user-auth Slack integration for the given Slack workspace, or null if not connected. Used for integrations that send messages as the user rather than as a bot.
POST - Read
userAuthSlackIntegrationByThreadId
Returns the current user's user-auth Slack integration for the Slack workspace associated with the given thread, or null if not connected.
POST - Read
userAuthSlackInstallationInfo
Returns a Slack OAuth installation URL for the current user to connect their user-auth Slack integration. Optionally scoped to a specific Slack workspace. Pass the resulting code to createUserAuthSlackIntegration.
POST - Read
workspaceDiscordIntegrations
Returns a paginated list of all webhook-based Discord integrations configured for this workspace.
POST - Read
workspaceDiscordIntegration
Fetches a single webhook-based workspace Discord integration by its ID. Returns null if not found.
POST - Read
connectedDiscordChannels
Returns a paginated list of Discord channels synced from a specific guild. Use `refreshConnectedDiscordChannels` to pull the latest channel list from Discord before querying.
POST - Read
customerCardConfigs
Returns all customer card configs for the workspace, ordered by their `order` field.
POST - Read
customerCardConfig
Returns a single customer card config by ID. Returns null if no config with the given ID exists.
POST - Read
setting
Fetch the effective value of a named setting at the given scope. Returns null when the setting has no stored value at that scope and no default applies. Use this to read notification preferences, workflow flags, chat-app configuration, and similar per-scope options. The `code` identifies which setting to read (e.g. `workflow/unassign_thread_after_mark_thread_as_done`) and `scope` pins the context (workspace, user, chat app, Slack channel, etc.).
POST - Read
webhookVersions
List all available webhook schema versions. Use this to discover which versions you can pin a webhook target to, and to check whether a version you are already using has been deprecated. Requires the `webhookTarget:read` permission.
POST - Read
webhookTarget
Fetch a single webhook target by its ID. Returns null if no target with that ID exists in the workspace. Requires the `webhookTarget:read` permission.
POST - Read
webhookTargets
List all webhook targets registered in the workspace, paginated. Returns every endpoint Plain is configured to deliver events to. Requires the `webhookTarget:read` permission.
POST - Read
webhookDeliveryAttempts
List delivery attempts for a webhook target, newest first. Each attempt records the event that was delivered, when it was attempted, how long it took, and whether it succeeded or failed. Use the optional `filters` argument to narrow results by event type or result status — useful for surfacing recent failures in your own observability tooling. Requires the `webhookTarget:read` permission.
POST - Read
publicEventRequestBody
Fetch the full JSON request body that Plain sent (or would send) for a given public event. Returns null if the event has expired — events are retained for 30 days. Use this alongside `webhookDeliveryAttempts` to inspect the exact payload for a failed delivery attempt and replay or debug it. Requires the `webhookTarget:read` permission.
POST - Read
subscriptionEventTypes
List every event type that can be subscribed to on a webhook target. Each entry includes the event type identifier and a human-readable description. Use this to discover valid values for `eventSubscriptions` when creating or updating a webhook target. Requires the `subscriptionEventTypes:read` permission.
POST - Read
interpolationVariables
List the static variables that can be interpolated with `{{ key }}` in snippets, auto-responses, bulk replies and workflow actions, with a label and group for building a picker. Thread field variables are not included; derive them from `threadFieldSchemas` as `threadField.<key>`. Requires the `workspace:read` permission.
POST - Read
workflowRule
Get a workflow rule by id. Returns null if no rule with the given ID exists. Workflow rules are the older, condition-plus-action configuration model; see `workflow` for the newer step-based model.
POST - Read
workflowRules
List all workflow rules in the workspace, paginated. Rules are returned in their configured display order. Use `workflowRule` to fetch a single rule by ID.
POST - Read
workflow
Get a workflow by id. Returns null if no workflow with the given ID exists. Workflows are the step-based automation model that supports conditions, actions, and wait steps connected in a graph.
POST - Read
workflows
List workflows in the workspace, paginated. Use `filters` to narrow results by trigger type (MANUAL, EVENTS or SCHEDULE), published status, the events an `events` trigger listens for, or the entities their steps reference (e.g. every workflow applying a given SLA policy). Ordered by `position` ascending unless `sortBy` says otherwise.
POST - Read
workflowCapabilities
Returns which blocks (condition/action/wait steps) are available for a workflow of the given trigger type. The builder UI sources its palette from this so the allow-list lives in the backend, not hardcoded in the UI. E.g. SCHEDULE workflows have no thread, so they allow no conditions/waits and only a restricted set of action types.
POST - Read
workflowExecution
Get a single workflow execution by id. Returns null if no execution with the given ID exists. Use this to inspect the status, timing, and per-step results of a specific run.
POST - Read
workflowExecutions
List executions for a specific workflow, paginated. Use this to audit the run history of a workflow and check for failures.
POST - Read
workflowExecutionsForWorkspace
List executions across every workflow in the workspace, newest first, paginated. Use this for a workspace-wide view of what automation has been doing, or narrow it with `filters` — by workflow, by the entity a run fired against, or by state. Executions that have not started yet sort to the top.
POST - Read
workflowExecutionsByEntity
List workflow executions filtered by the entity they ran against (e.g. a specific thread), paginated. Useful for showing all automation that has fired on a given thread. Optionally narrow further by workflow ID or execution status.
POST - Read
workflowTemplateGallery
Published templates for the gallery, metadata only — deprecated ones are already absent because the templates repo omits them. Use `workflowTemplate` for one with its workflows. Needs an authenticated caller and nothing more: templates are one published document, identical for every workspace, so there is nothing to scope by permission.
POST - Read
workflowTemplate
Null if no template with that ID is published. Deprecated templates still resolve here, which is what keeps existing install links working. Needs an authenticated caller and nothing more.
POST - Read
chatApp
Fetch a single chat app by its ID. Returns null if no chat app with that ID exists in the workspace. Requires the `chatApp:read` permission.
POST - Read
chatApps
List all chat apps in the workspace. Supports cursor-based pagination. Requires the `chatApp:read` permission.
POST - Read
chatAppSecret
Check whether a signing secret exists for a chat app. Returns metadata about the secret (creation time, actor) but never the secret value itself — the raw secret is only returned once, at creation time via `createChatAppSecret`. Returns null if no secret has been created for the given chat app. Requires the `chatAppSecret:read` permission.
POST - Read
thread
Fetch a single thread by its Plain-assigned ID. Returns null if no thread with that ID exists. Requires the `thread:read` permission.
POST - Read
threadByRef
Fetch a thread by its human-readable ref (e.g. `T-1234`). Useful when the ref is more convenient to store than the internal ID. Returns null if no match. Requires the `thread:read` permission.
POST - Read
threadByExternalId
Fetch a thread by the external ID you assigned it, scoped to a specific customer. Because `externalId` is only unique per-customer, both `customerId` and `externalId` are required. Returns null if no match. Requires the `thread:read` permission.
POST - Read
threadsByExternalId
Fetch all threads that share the given external ID, returned as a paginated connection. Unlike `threadByExternalId`, this is not scoped to a customer: because `externalId` is only unique per-customer, the same external ID can appear on threads belonging to different customers, and this query returns all of them. Returns an empty connection if there are no matches. Requires the `thread:read` permission.
POST - Read
threads
List threads with optional filtering and sorting, returned as a paginated connection. Supports rich filters (status, assignee, customer, label, priority, date ranges, tenant, tier, thread fields, and more) and multiple sort orders. Use this query to build inbox-style views or to export threads in bulk. Requires the `thread:read` permission.
POST - Read
testThreads
The signed-in user's own test threads, oldest first. They are excluded from `threads`, so this is the only query that lists them. Requires the `thread:read` permission.
POST - Read
searchThreads
Full-text search across thread titles, message contents, and customer names/emails. Accepts optional `ThreadsFilter` to narrow results further. For exact lookups by ID, ref, or external ID use the dedicated queries instead. Requires the `thread:read` permission.
POST - Read
deletedThreads
Paginated list of threads that have been deleted. Only threads deleted after the deletion audit log was enabled for your workspace are included. Useful for auditing or syncing deletions to an external system. Requires the `thread:read` permission.
POST - Read
autoresponder
Fetch a single autoresponder by its ID. Returns null if no autoresponder with that ID exists.
POST - Read
autoresponders
List all autoresponders in the workspace, ordered by their configured priority order. Supports cursor-based pagination.
POST - Read
timeSeriesMetric (deprecated)
Fetch a named time-series metric for the workspace, returning data points bucketed over a time range. Pass a metric name such as `threads_created_count` or `threads_first_response_time__p50` and optional options to control the date range, grouping dimension, and interval. Requires the `metrics:read` permission; agent-specific metric names additionally require `metricsAgent:read` and the `team_reporting` billing feature. The available look-back window is determined by your plan's `insights_max_days` entitlement.
POST - Read
singleValueMetric (deprecated)
Fetch a named single-value (aggregate) metric for the workspace over a given time range. Use this for summary figures such as median first-response time or SLA compliance percentage. Supports the same `dimension` grouping as `timeSeriesMetric` so results can be broken down by company, label type, tier, and more. Requires `metrics:read`; agent metrics require `metricsAgent:read`.
POST - Read
heatmapMetric (deprecated)
Fetch a named heatmap metric for the workspace, distributing activity across a 7-day × 24-hour grid (Monday–Sunday, hour 0–23 UTC). Each cell reports the thread count, its share of total volume as a percentage, and the list of thread IDs. Use this to identify peak support hours during a date range. Requires `metrics:read`.
POST - Read
threadTimeSeriesMetric
Fetch a time-series metric for threads with rich filter and group-by support. Choose a `TimeSeriesMetricName` (e.g. `threads_created_count`, `threads_first_response_time__p50`), specify a mandatory date range and bucketing interval, and optionally group results by assignee, company, tier, label type, and more. This is the preferred reporting query when you need server-side filtering across thread attributes. Requires `metrics:read`; grouping by assignee or filtering `assignedToUser` to anyone other than the caller additionally requires `metricsAgent:read`.
POST - Read
threadSingleValueMetric
Fetch an aggregate (single-value) metric for threads with rich filter and group-by support. Returns one value per group bucket for the specified date range and `SingleValueMetricName`, making it suitable for summary dashboards or leaderboard-style breakdowns by assignee, tier, or label type. Requires `metrics:read`; grouping by assignee or filtering `assignedToUser` to anyone other than the caller additionally requires `metricsAgent:read`.
POST - Read
threadHeatmapMetric
Fetch a heatmap metric for threads with filter support, distributing thread activity across a 7-day × 24-hour grid. Unlike the legacy `heatmapMetric`, this query uses the unified `ThreadMetricFilters` input for consistent filtering by label, tier, assignee, and more. Requires `metrics:read`; filtering `assignedToUser` to anyone other than the caller additionally requires `metricsAgent:read`.
POST - Read
companies (deprecated)
Returns a paginated list of all companies in your workspace. Supports cursor-based pagination and optional filtering by ID or deletion status. Requires the `company:read` permission.
POST - Read
company (deprecated)
Fetches a single company by its ID. Returns null if no company with that ID exists. Requires the `company:read` permission.
POST - Read
searchCompanies (deprecated)
Searches companies by name or domain using a case-insensitive partial match. The search term must be at least 2 characters long. Supports cursor-based pagination and optional filtering. Each match is returned as a `CompanySearchResult` that wraps the matched company. Requires the `company:read` permission.
POST - Read
teamSettings
Fetch the settings for a team (label type of kind TEAM) identified by its label type ID. Returns null if no settings have been configured yet for the team.
POST - Read
tenants (deprecated)
Returns a paginated list of tenants in the workspace. Use the `filters` argument to narrow the results and `sortBy` to order them (by name ascending when omitted). Requires the `tenant:read` permission.
POST - Read
tenant (deprecated)
Fetches a single tenant by its Plain-assigned ID. Returns null if no matching tenant is found. Requires the `tenant:read` permission.
POST - Read
accounts
Returns a paginated list of accounts in the workspace. Use the `filters` argument to narrow the results and `sortBy` to order them (by name ascending when omitted). Requires the `tenant:read` permission.
POST - Read
account
Fetches a single account by its Plain-assigned ID. Returns null if no matching account is found. Requires the `tenant:read` permission.
POST - Read
task
Fetch a single task by its ID. Returns null if no task with that ID exists. Requires the `task:read` permission.
POST - Read
taskByRef
Fetch a single task by its short human-readable ref (e.g. `T-123`), as displayed in the Plain app. Returns null if no task matches. Requires the `task:read` permission.
POST - Read
tasks
Fetch a paginated list of tasks in the workspace. Use `filters` to narrow results by status, assignee, company, or tenant. Use `sortBy` to order by priority, status, or creation/update time. Requires the `task:read` permission.
POST - Read
tenantFieldSchemas (deprecated)
Returns the list of tenant field schemas defined in the workspace. Use the `source` and `isVisible` filters to narrow results. Supports cursor-based pagination.
POST - Read
accountFieldSchemas
Returns the list of account field schemas defined in the workspace. Use the `source` and `isVisible` filters to narrow results. Supports cursor-based pagination.
POST - Read
searchTenants (deprecated)
Searches tenants by name or domain (case-insensitive partial match), or by external ID (exact match). The search term must be at least 2 characters long. Returns a paginated list of results. Requires the `tenant:read` permission.
POST - Read
searchAccounts
Searches accounts by name or domain (case-insensitive partial match), or by external ID (exact match). The search term must be at least 2 characters long. Returns a paginated list of results. Requires the `tenant:read` permission.
POST - Read
threadDiscussion
Fetch a single discussion by its ID. Returns null if no discussion with the given ID exists.
POST - Read
discussion
Fetch a single discussion by its ID. Preferred over threadDiscussion for new integrations.
POST - Read
discussions
List discussions in the workspace, with optional filtering and sorting. Supports cursor-based pagination. Filter by thread, status, creator, last-activity timestamps, source entity, or discussion type.
POST - Read
serviceAuthorization
Fetch a single completed service authorization by its ID. Returns null if not found or if the authorization is still pending.
POST - Read
serviceAuthorizations
List all completed service authorizations for the workspace. Only authorizations with status CONNECTED or REINSTALL_REQUIRED are returned; pending authorizations are excluded. Optionally filter by serviceIntegrationKey. Supports cursor-based pagination. Requires the `serviceAuthorization:read` permission.
POST - Read
sidekickGithubAccessibleRepos
Returns every GitHub repository the Sidekick Agent integration (identified by serviceAuthorizationId) can currently see via its OAuth token. Use this list to let users pick which repos Sidekick Agent should focus on before calling updateSidekickGithubConfig.
POST - Read
sidekickGithubServiceConfig
Returns the Sidekick Agent GitHub configuration for a workspace: which repositories are selected for Sidekick Agent to use and any workspace-level or per-repo operating instructions. Returns null when no configuration has been saved yet.
POST - Read
sidekickServiceConfig
Returns the Sidekick Agent configuration for a connected service (Datadog, Sentry, Grafana, Linear, Notion, incident.io, Attio, HubSpot, Jira, Granola, LaunchDarkly, Grain or Cursor), identified by its serviceAuthorizationId. Includes any operating instructions that guide how Sidekick Agent uses the integration. Returns null when no configuration has been saved yet. GitHub and PostHog have their own configuration shapes — use sidekickGithubServiceConfig / sidekickPosthogServiceConfig instead.
POST - Read
sidekickPosthogServiceConfig
Returns the Sidekick Agent PostHog configuration for a workspace, including any operating instructions and the default project the agent queries. Returns null when no configuration has been saved yet.
POST - Read
sidekickSettings
Returns workspace-level Sidekick Agent settings, including the custom prompt that is appended to every Sidekick Agent session's system prompt and the tools selected during onboarding. Always returns an object. customPrompt is null when not configured. preferredIntegrations is empty when none are selected.
POST - Read
agentSandboxToolPolicies
The Sidekick Agent tool approval policies for the workspace: every catalog tool with its effective approval mode (per-workspace override merged over the factory default). Optionally filter to a single service (e.g. "plain").
POST - Read
sidekickSkills
Every skill available to Sidekick Agent in this workspace: Plain's system skills plus the workspace's custom skills, each with its effective enabled state.
POST - Read
sidekickCustomSkill
A single workspace custom skill, including its instructions, for editing.
POST - Read
sidekickMcpServers
The custom (customer-owned) MCP servers registered for Sidekick Agent in this workspace.
POST - Read
sidekickMcpServer
A single custom MCP server by id, or null if it does not exist in this workspace.
POST - Read
importerTenantLists (deprecated)
Fetch the available tenant lists (e.g. company lists or account views) from a connected external service such as Attio, HubSpot, or Salesforce. Use this to let users choose which list to sync when setting up an import. Requires a completed service authorization ID.
POST - Read
importerAccountLists
Fetch the available account lists (e.g. company lists or account views) from a connected external service such as Attio, HubSpot, or Salesforce. Use this to let users choose which list to sync when setting up an import. Requires a completed service authorization ID.
POST - Read
importJobDefinition
Fetch the import job definition for a connected service integration. Pass isEnabled: true to return only the currently active definition, or isEnabled: false to return any definition regardless of enabled state. Returns null if no matching definition exists.
POST - Read
importJobs
List import jobs, optionally filtered by service integration key or import job definition ID. Each job represents a single sync run triggered by an import job definition, and contains per-entity-type runs with their progress and status.
POST - Read
tiers
Returns all tiers in the workspace, sorted by creation date. Supports cursor-based pagination. Requires the `tier:read` permission.
POST - Read
tier
Returns a single tier by its Plain ID. Returns null if no tier with that ID exists. Requires the `tier:read` permission.
POST - Read
serviceLevelAgreementPolicies
Returns the SLA policies in the workspace, sorted by name. Pass `filters` to narrow by name or by the target types a policy holds. Supports cursor-based pagination. Requires the `serviceLevelAgreement:read` permission.
POST - Read
serviceLevelAgreementPolicy
Returns a single SLA policy by its Plain ID. Returns null if no policy with that ID exists. Requires the `serviceLevelAgreement:read` permission.
POST - Read
businessHours (deprecated)
Fetch the workspace's business hours configuration. Deprecated — use businessHoursSchedules instead, which supports multiple named, timezone-aware schedules.
POST - Read
businessHoursSlots (deprecated)
Return all active business hours slots for the workspace, merged across every schedule. Deprecated — use businessHoursSchedules instead, which returns each schedule's slots separately. Requires the `businessHours:read` permission.
POST - Read
businessHoursSchedule
Fetches a single business hours schedule by its ID, or null if no schedule with that ID exists. Requires the `businessHours:read` permission.
POST - Read
businessHoursSchedules
Returns a paginated list of the workspace's business hours schedules, sorted by name. Requires the `businessHours:read` permission.
POST - Read
businessHoursOverride
Fetches a single business hours override by its ID, or null if no override with that ID exists. Requires the `businessHours:read` permission.
POST - Read
workspaceHmac
Returns the workspace's HMAC configuration, including the secret used to sign outbound webhook and HTTP-request payloads. Returns null if no secret has been generated yet. Requires the `workspaceHmac:read` permission.
POST - Read
threadLinkGroups
Returns a paginated list of thread link groups, each representing a distinct external entity (e.g. a Linear issue or Jira ticket) that is linked to one or more threads. Use this to build views that aggregate threads by a shared linked issue. Supports filtering by status, specific group IDs, company, or tier.
POST - Read
searchKnowledgeSources
Perform a semantic (vector) search across your workspace's knowledge sources and help center articles. Matches up to `pageSize` chunks (default 10, max 50), then returns one result per source containing its full indexed text, ordered by each source's most relevant chunk. Use `options` to restrict results by label type, content type (indexed documents vs help center articles), or to include help center articles that are not publicly accessible.
POST - Read
searchPlainHelpCenter
Perform a semantic (vector) search across Plain's own public help center (help.plain.com). Available to every workspace's Sidekick Agent so it can answer questions about how Plain itself works. Read-only and hard-restricted to Plain's public product documentation; it never returns the caller's own data or any other workspace's content. Returns up to `pageSize` results (default 10, max 50) ranked by relevance.
POST - Read
sidekickAvailableTools
List the Sidekick Agent tools available to this workspace: Plain tools always, external tools only for connected integrations.
POST - Read
sidekickToolArgOptions
Browse choices for a configurable tool arg (from `SidekickAvailableTool.configurableArgs`). Pass the selected dependsOn argument as parent; clear after when changing source, parent or query.
POST - Read
threadClusters
Returns all AI-generated thread clusters for the current workspace, sorted by thread count descending. Clusters group semantically similar threads together so you can spot trends and recurring issues at a glance. The optional `variant` argument selects which clustering model run to return; omit it to receive the default variant. This API is in beta and may change without notice.
POST - Read
threadCluster
Fetches a single thread cluster by its ID. Returns null if no cluster with that ID exists in the current workspace. This API is in beta and may change without notice.
POST - Read
activeThreadCluster
Returns the cluster that the given thread currently belongs to, or null if the thread has not been assigned to any cluster. Use this to show a customer-support agent which broader topic group a specific thread falls into. This API is in beta and may change without notice.
POST - Read
threadClustersPaginated
Returns a paginated list of AI-generated thread clusters for the current workspace. Use `filters` to narrow results by company, tenant, or clustering variant. Supports standard cursor-based pagination via `first`/`after` and `last`/`before`. Requires the `thread:read` permission. This API is in beta and may change without notice.
POST - Read
generatedReplies
This API is in beta and may change without notice. Returns the current suggested reply candidates for a thread, scoped to the most recent inbound message from the customer or from a machine user. Suggestions submitted via `addGeneratedReply` are always included. Suggestions generated by Plain AI are excluded when suggested responses are disabled or not available for the workspace, or when an externally submitted suggestion exists for the same message. Returns an empty list if the thread has no such message or no suggestion is available. Requires the `generatedReply:read` permission.
POST - Read
indexedDocuments
List indexed documents across your workspace, newest first. Use the `knowledgeSourceId` filter to retrieve only the documents belonging to a specific knowledge source, and the `statuses` filter to retrieve only documents with a given ingestion status.
POST - Read
knowledgeSource
Fetch a single knowledge source by its ID. Returns null if no knowledge source with the given ID exists.
POST - Read
knowledgeSources
List all knowledge sources in the workspace. Use the `type` filter to retrieve only sitemap or single-URL sources.
POST - Read
knowledgeSourceCitationsByThread
Returns the knowledge sources cited by AI agent replies across a thread, each linked to the timeline entry it was cited in and carrying a snapshot title (and best-effort url) plus the live cited document when it still exists. Returns an empty list when the thread has no citations or is not visible to the caller. Requires the `thread:read` and `timeline:read` permissions.
POST - Read
aiToneRules
Returns the workspace's AI tone rules, which guide how Plain's AI features phrase replies. Use the optional `isEnabled` filter to retrieve only active rules. Pagination is supported via standard `first`/`after` and `last`/`before` cursor arguments, though in practice all rules are returned in a single page. Requires the `aiToneRule:read` permission.
POST - Read
enabledAiToneRulesText
Returns all currently enabled AI tone rules serialised as a plain-text instruction string that is suitable for injecting into AI prompts. Returns `null` when no rules are enabled or the feature flag is off. Requires the `aiToneRule:read` permission.
POST - Read
savedThreadsViews
Returns all saved threads views for the workspace, ordered by creation time. Use this to list the views available in your workspace. Supports forward and backward cursor pagination.
POST - Read
savedThreadsView
Fetches a single saved threads view by its ID. Returns null if no view with the given ID exists in the workspace.
POST - Read
searchThreadLinkCandidates
Searches for external entities (e.g. Jira issues) that can be linked to a thread. Filter by `sourceType` to scope the search to a specific issue tracker, and provide a free-text `searchQuery` to match against issue titles or identifiers. Returns candidates that can then be passed to `createThreadLink`. Requires a connected issue tracker integration for the specified source type.
POST - Read
helpCenters
List all help centers in the workspace. Supports cursor-based pagination and optional filtering.
POST - Read
helpCenter
Fetch a single help center by ID. Returns null if not found.
POST - Read
helpCenterAiConversations
Lists AI conversations customers have had across the workspace's help centers. Defaults to sorting by last message time in descending order. Requires the `helpCenter:read` permission. Not available to machine users.
POST - Read
helpCenterAiConversation
Fetches a help center AI conversation by its internal ID. Returns null when the conversation does not exist in the current workspace. Requires the `helpCenter:read` permission. Not available to machine users.
POST - Read
helpCenterArticle
Fetch a single help center article by ID. Returns null if not found.
POST - Read
helpCenterArticleGroup
Fetch a single article group by ID. Returns null if not found.
POST - Read
helpCenterIndex
Fetch the navigation index for a help center by its ID. Returns null if not found. Use the returned hash when calling updateHelpCenterIndex to avoid clobbering concurrent edits.
POST - Read
helpCenterArticleBySlug
Fetch an article by its URL slug within a specific help center. Slugs are unique per help center. Returns null if no article matches.
POST - Read
helpCenterArticleGroupBySlug
Fetch an article group by its URL slug within a specific help center. Returns null if no group matches.
POST - Read
issueTrackerFields
Fetch the configurable fields for a connected issue tracker (e.g. Shortcut, Rootly, incident.io, GitHub). Pass previously selected field values in `selectedFields` so that dependent fields (such as labels that depend on a chosen repository) are populated correctly. Returns the list of fields the caller must or may provide when calling `createIssueTrackerIssue`. Requires the `threadLinkCandidate:search` permission.
POST - Read
customerSurveys
Returns a paginated list of all customer surveys configured in the workspace, ordered by their display order. Use this to build management UIs or sync survey configurations.
POST - Read
customerSurvey
Fetches a single customer survey by its ID. Returns null if no survey with that ID exists.
POST - Read
escalationPaths
Returns a paginated list of all escalation paths configured in the workspace. Requires the `escalationPath:read` permission.
POST - Read
escalationPath
Fetches a single escalation path by its ID. Returns null if no escalation path with the given ID exists. Requires the `escalationPath:read` permission.
POST - Read
myInternalNotifications
Returns a paginated list of internal notifications for the currently authenticated user. Use the optional `filters` argument to narrow results by read status or creation time. Supports forward and backward cursor-based pagination via `first`/`after` and `last`/`before`. Only available to human users — machine users will receive a forbidden error.
POST - Read
knowledgeGap
Fetch a single knowledge gap by its ID. Returns null if no gap with that ID exists in the workspace. Requires the `knowledgeGap:read` permission.
POST - Read
knowledgeGaps
Paginated list of knowledge gaps detected in the workspace. Filter by status or by when gaps were last seen. Sort by signal count or recency. Defaults to descending signal count order. Requires the `knowledgeGap:read` permission.
POST - Read
aiFeedback
Paginated list of the feedback your team has submitted on Plain's AI features, such as a thumbs up or down on a Customer Agent reply, newest first. Use the optional `filters` argument to narrow results by feature, sentiment or submission time. Requires the `aiFeatureFeedback:read` permission.
POST
Mutations
- Write
createUserAccount
Creates or updates the user account for the currently authenticated user. Idempotent: calling this multiple times with the same identity will update the existing account rather than creating a duplicate. Used during the initial onboarding flow to set the user's display names.
POST - Write
changeUserStatus
Manually set a workspace member's availability status (ONLINE, OFFLINE, or AWAY). ONLINE and OFFLINE do not pause working-hours automation, so the next scheduled transition still fires while automation is enabled; setting AWAY pauses automation until the member leaves AWAY, which resumes it and recomputes the next transition. Requires the `userStatus:edit` permission.
POST - Write
updateMyUser
Updates profile fields (display name, short name, or avatar) for the currently authenticated human user. Only the fields provided are changed; omitted fields are left unchanged. Not available to machine users.
POST - Write
updateUserDefaultSavedThreadsView
Sets or clears the default saved threads view for a specific user. Pass null for savedViewId to remove the default. This controls which thread view the user sees when they first open the inbox.
POST - Write
createWorkspace
Create a new Plain workspace. The authenticated user becomes the owner of the new workspace. Requires a unique internal name and a public-facing display name.
POST - Write
updateWorkspace
Update workspace settings such as the display name, logo, or allowed email domain names. At least one field must be provided. Domain names are stored in lowercase.
POST - Write
inviteUserToWorkspace
Send a workspace invitation to a user by email. Specify either a built-in roleKey (e.g. SUPPORT, ADMIN) or a customRoleId to control the permissions they receive on joining. Sends an invitation email to the provided address.
POST - Write
acceptWorkspaceInvite
Accept a workspace invitation using its ID. The authenticated user joins the workspace and is assigned the role specified in the invite. The invite is marked as accepted and can no longer be used.
POST - Write
assignRolesToUser
Assigns a role to a user in the workspace. Supply exactly one of `roleKey` (for built-in roles) or `customRoleId` (for custom roles) — not both. You can also set `usingBillingRotaSeat` to control whether the user occupies a billable seat on the billing rota. Requires the `roles:assign` permission.
POST - Write
createCustomRole
Creates a new custom role in the workspace. Custom roles are created with the Support permissions preset by default and can be further configured using `upsertRoleScopes`. Requires the `roles:create` permission and the `custom_roles` billing entitlement.
POST - Write
updateCustomRole
Updates the name and/or description of an existing custom role. Only the fields provided in the input are changed. Requires the `roles:edit` permission.
POST - Write
updateRolePriorityOrder
Sets the order in which roles win when a user is given more than one through SSO or directory sync. Custom roles can be placed anywhere below the admin role and above the none role. Requires the `roles:edit` permission.
POST - Write
upsertRoleScopes
Sets the thread-visibility scopes for a custom role, replacing any previously configured scopes for the given resource. Each scope condition limits which threads users with this role can see, based on a primitive type (label, tier, channel, tenant, or company) and an access mode. Requires the `roles:edit` permission and the `custom_roles` billing entitlement.
POST - Write
createLabelType
Creates a new label type in the workspace. Label types define the labels available to apply to threads and users. Requires the `labelType:create` permission.
POST - Write
unarchiveLabelType
Restores an archived label type so it can be applied to threads again. Requires the `labelType:edit` permission.
POST - Write
updateLabelType
Updates properties of an existing label type. Uses field-level wrapper inputs: pass `{ value: ... }` to change a field, or omit the field entirely to leave it unchanged. At least one field besides `labelTypeId` must be provided. Requires the `labelType:edit` permission.
POST - Write
moveLabelType
Changes the position of a label type in the ordered list, or moves it to a different parent. Supply `afterLabelTypeId` or `beforeLabelTypeId` to place the label type relative to a sibling, and optionally `parentLabelTypeId` to nest it under a parent. Requires the `labelType:edit` permission.
POST - Write
acceptSuggestedLabelTypes
Accepts one or more pending suggested label types, creating a real label type for each and marking the suggestions as ACCEPTED. All ids must currently be PENDING. Fails the whole batch with error code `label_type_name_already_exists` if a suggestion's name matches an existing label type or another suggestion in the same batch. Requires the `labelType:create` and `labelType:read` permissions.
POST - Write
dismissSuggestedLabelTypes
Dismisses one or more pending suggested label types without creating label types. All ids must currently be PENDING. Requires the `labelType:create` permission.
POST - Write
addLabels
Add one or more labels to a thread. Labels that are already present on the thread are silently skipped. Archived label types are rejected with error code `cannot_add_label_using_archived_label_type`. Requires the `label:create` permission.
POST - Write
addLabelsToUser
Add one or more team labels to a Plain user (agent). Only label types with type `TEAM` may be applied to users. Label types already present on the user are silently skipped. Requires the `label:create` permission.
POST - Write
createThreadLink
Links a thread to an external entity such as a Linear issue, Jira ticket, another Plain thread, or a Plain task. Provide exactly one of `linearIssue`, `jiraIssue`, `plainThread`, `plainTask`, or `sourceId`/`sourceType` for generic issue trackers. If the thread is already linked to the entity with the same link type, the existing link is returned. Returns an error with code `thread_link_already_exists` if it is linked with a different link type.
POST - Write
bulkCreateThreadLinks
Links many threads to a single target entity (a Linear issue, Jira ticket, another Plain thread, a Plain task, or a generic issue tracker) in one request. Provide exactly one of `linearIssue`, `jiraIssue`, `plainThread`, `plainTask`, or `sourceId`/`sourceType`, plus the list of `threadIds` to link to it. Each thread is linked independently: the returned `results` carry a per-thread `threadLink` or `error`, and the top-level `error` is set to `bulk_partial_failure` if any thread failed. A thread already linked to the target with the same link type gets the existing link back. Requires the `threadLink:create` permission.
POST - Write
bulkDeleteThreadLinks
Deletes multiple thread links by their IDs. Non-existent IDs are silently ignored (idempotent). Requires the `threadLink:delete` permission.
POST - Write
createNote
Creates an internal note visible only to your team. Notes appear in the thread timeline alongside customer messages and are useful for sharing context, reminders, or annotations. Provide `threadId` to pin the note to a specific thread; omit it to attach the note to the customer so it appears across all of their threads. Requires the `note:create` permission.
POST - Write
updateNote
Updates the text, markdown, or attachments of an existing note. Requires the `note:edit` permission.
POST - Write
createSavedThreadsView
Creates a new saved threads view in the workspace. The view stores a named filter configuration (including sort order, grouping, layout, and display options) that can be applied when querying threads. Requires the savedThreadsView:create permission; depending on workspace settings, only admins or all members may be allowed to create views.
POST - Write
updateSavedThreadsView
Updates an existing saved threads view. All fields in the input are optional; only the fields you provide will be changed. Depending on workspace settings, only the view's creator or workspace admins may be allowed to edit a view they did not create.
POST - Write
createMyFavoritePage
Saves a page as a favorite for the currently authenticated user. If the caller has already favorited a page with the same key, the existing record is returned unchanged (idempotent). Requires the `favoritePage:create` permission.
POST - Write
createSnippet
Creates a new snippet in the workspace. The `name` is used to search for the snippet when composing a reply. Provide `markdown` in addition to `text` to supply a rich-text version used in channels that support markdown. The optional `path` (alphanumeric only) places the snippet in a folder in the Plain app. Requires the `snippet:create` permission.
POST - Write
updateSnippet
Updates one or more fields of an existing snippet. Each field uses a wrapper input — pass `{ value: "..." }` to set it or omit it entirely to leave it unchanged. To remove the snippet's `path` (un-group it) pass `{ value: null }`. Requires the `snippet:edit` permission.
POST - Write
createBroadcast
Creates a new broadcast in the workspace. The `content` is encoded as declared by `contentFormat` and authored against the rendering rules of the given `type`. Requires the `broadcast:create` permission.
POST - Write
duplicateBroadcast
Copies an existing broadcast into a new draft. Authoring fields (content, audience, sender, notification title, and related settings) are copied. Send history, schedule, recipients, and delivery stats are not. The copy is named `Copy of <original name>`. Requires the `broadcast:create` and `broadcast:read` permissions.
POST - Write
updateBroadcast
Updates one or more fields of an existing broadcast. Each field uses a wrapper input — pass `{ value: ... }` to set it or omit it entirely to leave it unchanged. `type` is not updatable. Requires the `broadcast:edit` permission.
POST - Write
unsubscribeBroadcastRecipient
Records that a broadcast recipient should not receive further broadcasts. Idempotent. Requires the `broadcast:edit` permission and the broadcasts feature flag.
POST - Write
resubscribeBroadcastRecipient
Removes an unsubscribe so the recipient can receive broadcasts again. Idempotent. Requires the `broadcast:edit` permission and the broadcasts feature flag.
POST - Write
importBroadcastRecipientUnsubscribes
Bulk-imports broadcast recipient unsubscribes by recipient identifier (Slack channel id/name today; email later). Idempotent. Requires `broadcast:edit` and the broadcasts feature flag.
POST - Write
createBroadcastAudience
Creates a reusable broadcast audience. `filters` is validated against `type`, so a filter naming a dimension that type cannot resolve is rejected here rather than resolving to nobody at send time. Requires the `broadcastAudience:create` permission.
POST - Write
updateBroadcastAudience
Updates a broadcast audience's name, filters, or both. Editing an audience changes who every broadcast using it will reach on its next send. Requires the `broadcastAudience:edit` permission.
POST - Write
importBroadcastAudienceChannels
Bulk-imports Slack channels into a broadcast audience's pinned `slackChannels` filter (by channel id or exact name). Idempotent. Requires `broadcastAudience:edit` and the broadcasts feature flag.
POST - Write
scheduleBroadcast
Queues a broadcast to be sent, moving it from `DRAFT` to `SCHEDULED`. Calling this again on a broadcast that has not started sending changes when it will go out; once the send has started it is rejected. The broadcast must have a sender and at least one channel. A null `scheduledAt` clears the schedule instead, returning the broadcast to `DRAFT`. Requires the `broadcast:send` and `broadcast:read` permissions.
POST - Write
sendTestBroadcast
Sends the broadcast to the Slack channels you name, up to 10, so you can see what recipients will get before the real audience does. It goes out through the same pipeline as a real send, under the broadcast's own sender, so what arrives is what any channel would have received — with a notice at the top marking it as a test, since everyone in the channels you choose will see it. Every channel must already be connected to this workspace. They are independent of the broadcast's own audience, which is left untouched: the broadcast needs a sender and a notification title, but it does **not** need any channels of its own, because testing is what you do before choosing them. Only available while the broadcast can still be edited: once its send has started, it can no longer be tested. A test send never changes the broadcast's `status`, and never unlocks or locks editing. Requires the `broadcast:send` permission.
POST - Write
upsertTeamSettings
Create or update the settings for a team (label type of kind TEAM). If settings do not yet exist for the given team, they are created with defaults (round-robin disabled, max capacity 5); otherwise the existing settings are updated with the supplied values. The labelTypeId must refer to a label type of type TEAM — passing any other label type ID returns a validation error. Requires the `labelType:edit` permission.
POST - Write
createTask
Create a new task. Only `title` is required; `description`, `status`, `priority`, assignee, and a parent `companyId` or `tenantId` are all optional. A task may be linked to either a company or a tenant, but not both. Requires the `task:create` permission.
POST - Write
updateTask
Update an existing task. Only the fields you include are changed — omitted fields are left as-is. Setting `companyId` clears any existing `tenantId` and vice versa, since a task may be linked to at most one. Requires the `task:edit` permission.
POST - Write
upsertCustomer
Creates or updates a customer identified by email address, external ID, or Plain customer ID. Supply `onCreate` fields for values to set when creating and `onUpdate` fields for values to apply when the customer already exists. The output's `result` field indicates whether the customer was `CREATED`, `UPDATED`, or `NOOP` (existed and no values changed). Requires the `customer:create` and `customer:edit` permissions.
POST - Write
updateCustomerCompany (deprecated)
Assigns a customer to a different company, or clears their company association. Requires the `customer:edit` permission.
POST - Write
markCustomerAsSpam
Flags a customer as spam, hiding their threads from the inbox and excluding them from metrics. The operation is idempotent — marking an already-spam customer leaves their `markedAsSpamAt` timestamp unchanged. Requires the `customer:edit` permission.
POST - Write
unmarkCustomerAsSpam
Clears the spam flag from a customer, restoring their threads to the inbox and metrics. The `markedAsSpamAt` timestamp is cleared. Requires the `customer:edit` permission.
POST - Write
upsertCustomerGroup
Create or update a customer group identified by `customerGroupId`, `customerGroupKey`, or `externalId`. If a matching group is found it is updated and the result is `UPDATED`; if data is unchanged the result is `NOOP`; otherwise a new group is created and the result is `CREATED`. Note: using `customerGroupId` as the identifier returns an error if the group does not exist. Requires `customerGroup:create` and `customerGroup:edit` permissions.
POST - Write
createCustomerGroup
Create a new customer group with a unique key, display name, and color. Use `upsertCustomerGroup` instead if you need idempotent create-or-update behaviour. Requires `customerGroup:create` permission.
POST - Write
updateCustomerGroup
Update the name, key, color, or external ID of an existing customer group. At least one field must be provided in the input. Requires `customerGroup:edit` permission.
POST - Write
addCustomerToCustomerGroups
Add a customer to one or more customer groups (up to 25 at once), identified by group ID, key, or external ID. Memberships that already exist are silently skipped, making this operation safe to call repeatedly. Returns only the newly created memberships. Requires `customerGroupMembership:create` permission.
POST - Write
createThreadFieldSchema
Creates a new thread field schema, defining a custom field that can be attached to threads. The `key` must be unique within the workspace and cannot be changed after creation. Requires the `threadFieldSchema:create` permission.
POST - Write
updateThreadFieldSchema
Updates an existing thread field schema. All fields except `key` and `type` are mutable. String fields use wrapper inputs (e.g. `{ value: "..." }`) to distinguish a deliberate null from an omitted value. Requires the `threadFieldSchema:edit` permission.
POST - Write
reorderThreadFieldSchemas
Updates the display order of thread field schemas. You only need to include schemas whose order is changing — omitted schemas are left unchanged.
POST - Write
upsertThreadField
Sets (or updates) a single thread field value on a thread, identified by thread ID and field key. Creates the field if it does not exist, or overwrites the existing value if it does. Requires the `threadField:create` and `threadField:update` permissions.
POST - Write
bulkUpsertThreadFields
Upserts up to 25 thread field values in a single call — useful when setting multiple fields on one or more threads at once. Each entry is independently created or updated; a validation error on the batch as a whole is returned if any entry is invalid. Requires the `threadField:create` and `threadField:update` permissions.
POST - Write
createEscalationPath
Creates a new escalation path with the given name, optional description, and an ordered list of steps (up to 20). Each step routes the thread to either a specific user or the owners of a label type. Steps must not contain duplicates. Requires the `escalationPath:create` permission and the escalation paths feature entitlement.
POST - Write
updateEscalationPath
Updates an existing escalation path. All fields are optional — only the fields provided will be changed. If `steps` is provided, it replaces the full list of steps; omit it to leave the current steps unchanged. Returns an error if the escalation path does not exist. Requires the `escalationPath:edit` permission.
POST - Write
createWorkflowRule
Create a new workflow rule. The rule starts unpublished; use `toggleWorkflowRulePublished` to activate it. The `payload` field must be a valid JSON-encoded rule definition.
POST - Write
updateWorkflowRule
Update the name, payload, or display order of an existing workflow rule.
POST - Write
toggleWorkflowRulePublished
Toggle the published state of a workflow rule. Published rules are active and will fire automatically; unpublished rules are drafts.
POST - Write
triggerWorkflowRule
Manually trigger a workflow rule against a specific thread, bypassing its automatic trigger conditions. Useful for testing rules or applying them on demand.
POST - Write
createWorkflow
Create a new workflow. The workflow starts unpublished with no steps; use `bulkUpsertWorkflowSteps` to add steps and `updateWorkflow` to publish it. The `trigger` field must be a valid JSON-encoded trigger configuration.
POST - Write
updateWorkflow
Update a workflow's name, trigger configuration, entry step, or published status. To change where a workflow sits in the list, use `moveWorkflow`.
POST - Write
moveWorkflow
Move a workflow so it sits directly after another, or to the front of the list when `afterWorkflowId` is null. Only the moved workflow changes.
POST - Write
triggerWorkflow
Manually trigger a workflow against a specific thread. Returns the resulting WorkflowExecution so you can track the run's status and step results.
POST - Write
exportWorkflowTemplate
Build the files for publishing a workflow as a template; writes nothing. Requires the `workflowRule:create` permission.
POST - Write
createWorkflowStep
Add a single step to a workflow. For bulk changes to a workflow's step graph, prefer `bulkUpsertWorkflowSteps`.
POST - Write
updateWorkflowStep
Update a single workflow step's configuration, transitions, or canvas position. Replacing `transitions` is a full replacement of the array.
POST - Write
sendChat
Send a chat message from a support agent (or machine user) to a customer on a CHAT-channel thread. Either `text` or at least one `attachmentIds` entry must be provided. If `threadId` is omitted a new thread is created; if supplied the message is appended to the existing thread. An optional `timestamp` (ISO 8601, must be in the past) allows backdating messages when backfilling historical data. Requires the `chat:create` permission and the live-chat billing entitlement.
POST - Write
sendCustomerChat
Send a chat message on behalf of a customer into an existing CHAT-channel thread. Use this in a headless portal integration to forward messages written by the customer in your own UI into Plain. Unlike `sendChat`, `threadId` is required and the caller must be authenticated as a machine user. An optional `timestamp` (ISO 8601, must be in the past) allows backdating messages when backfilling. Requires the `chat:create` permission and the headless-portal billing entitlement.
POST - Write
createChatApp
Create a new chat app, which represents a source of chat messages (e.g. a specific in-product widget or integration). Optionally supply a `logo` using a previously uploaded workspace file ID. The logo must be a public, image-type workspace file. Requires the `chatApp:create` permission and the live-chat billing entitlement.
POST - Write
updateChatApp
Update the name or logo of an existing chat app. Only the fields provided in the input are changed. Requires the `chatApp:edit` permission.
POST - Write
createChatAppSecret
Generate a signing secret for a chat app used to authenticate incoming webhook requests. If a secret already exists for the given chat app it is deleted and replaced — the new secret is the only time the raw value is returned. Store it securely immediately after creation. Requires the `chatAppSecret:create` permission and the live-chat billing entitlement.
POST - Write
sendMSTeamsMessage
Sends a Microsoft Teams message on a thread. The thread must be associated with a connected MS Teams channel and the workspace must have an active MS Teams integration.
POST - Write
createThreadFromMSTeamsMessage
Creates a thread from a message in a Microsoft Teams channel or chat that the Plain bot is a member of. This is the trigger for the `API_ONLY` value of the `ms_teams/ingestion_mode` workspace setting, and works in `AUTOMATIC` mode too. In a channel, the whole post the message belongs to becomes the thread. In a chat, the thread also includes the messages before and after this one, taken from the chat's 50 most recent messages. Thread creation runs asynchronously, so `thread` is only returned when the message was already on a thread. Requires the `thread:create` permission.
POST - Write
sendSlackMessage
Sends a Slack message on a thread. The message appears in the thread's associated Slack channel as a reply or new message.
POST - Write
sendDiscordMessage
Sends an outbound Discord message on a thread. Requires both a workspace-level Discord channel integration and a personal user auth integration for the sending user. The message is posted into the Discord thread associated with the Plain thread.
POST - Write
toggleSlackMessageReaction
Adds or removes a reaction from a slack message timeline entry.
POST - Write
forkThread
Create a new thread by forking from a specific timeline entry in an existing thread. The forked thread starts at the chosen message, allowing you to split a conversation into a separate support case. Requires the `thread:create` permission.
POST - Write
updateConnectedSlackChannel
Updates the settings of a connected Slack channel, such as its channel type (customer or discussion) or whether it is enabled.
POST - Write
bulkUpdateConnectedSlackChannels
Applies many connected-slack-channel updates in a single request. Each update is applied independently with the same semantics as `updateConnectedSlackChannel`; partial failures are reported per-item.
POST - Write
bulkJoinSlackChannels
Instructs the Plain Slack bot to join public Slack channels for the given workspace Slack channel integration. By default it joins every public channel matching an auto-join rule on the integration. Set `rule` to join only the public channels matching one rule, identified by its channel name prefix and suffix.
POST - Write
createThreadFromSlackMessage
Creates a thread from a top-level message in a connected customer Slack channel, along with the replies Plain has already received for it. This is the trigger for the `API_ONLY` ingestion mode, and works in every other mode too. Ingestion runs asynchronously, so `thread` is returned only when the message had already been ingested. Requires the `thread:create` permission. This is not a way to import historic conversations: only replies Plain saw over the Slack events API are included, so a message from before the Plain bot joined the channel becomes a thread missing everything that was said before then.
POST - Write
setSlackAutoJoinRules
Replaces all auto-join rules for a workspace slack channel integration. The provided rules become the complete set of rules for the integration.
POST - Write
createCustomerEvent
Creates a customer event that appears in the timeline of every thread belonging to the customer. Use this to surface important product activity (e.g. a failed payment, a deleted API key) so your team has full context when helping the customer. The event layout is defined using Plain UI components. Requires the `customerEvent:create` permission.
POST - Write
createThreadEvent
Creates a thread event that appears only in the timeline of the specified thread. Use this when an activity is specific to a single conversation rather than the customer as a whole. The event layout is defined using Plain UI components. Thread events are visible only to your team and are never shown to the customer. Requires the `threadEvent:create` and `threadEvent:read` permissions.
POST - Write
createWorkspaceEmailDomainSettings
Configures a custom email domain for the workspace using the provided support email address. After creation, complete setup by verifying email forwarding with verifyWorkspaceEmailForwardingSettings and DNS records with verifyWorkspaceEmailDnsSettings.
POST - Write
verifyWorkspaceEmailForwardingSettings
Marks whether email forwarding has been configured on the custom domain. Call this after setting up the forwarding rule in your DNS/email provider to update Plain's record of the forwarding status.
POST - Write
verifyWorkspaceEmailDnsSettings
Triggers Plain to re-check whether the DKIM and return-path DNS records are correctly configured for the workspace's custom email domain. Returns the updated domain settings with the latest verification status.
POST - Write
updateWorkspaceEmailSettings
Updates workspace-level email settings such as whether email is enabled and the list of BCC addresses that are copied on all outbound emails.
POST - Write
addWorkspaceAlternateSupportEmailAddress
Adds an alternate support email address to the workspace's custom domain configuration, allowing emails to be sent from and received at that address. A workspace can have up to 5 alternate addresses.
POST - Write
sendNewEmail
Sends a new outbound email to a customer, creating a new thread by default. Use threadId to attach the email to an existing thread instead. Supports CC and BCC recipients (up to 49 combined), file attachments, and an optional alternate from address. Requires the email:create and email:read permissions.
POST - Write
replyToEmail
Replies to an existing email in a thread, threading the response correctly in email clients. Use inReplyToEmailId to identify the email being replied to. Supports CC and BCC recipients (up to 49 combined) and file attachments. Requires the email:create and email:read permissions.
POST - Write
createEmailPreviewUrl
Generates a short-lived URL that can be used to preview the rendered HTML of an email. Useful for displaying email content in external tools or dashboards.
POST - Write
sendBulkEmail
Sends the same email body to multiple threads at once (up to 100 thread IDs per call). Useful for broadcasting updates to a set of customers, for example notifying affected users of an incident.
POST - Write
createAttachmentDownloadUrl
Generate a short-lived download URL for an existing attachment. The returned URL expires after 3 minutes. If your workspace has virus scanning enabled, the response also includes an `attachmentVirusScanResult` indicating whether the file is safe to download. Requires the `attachment:download` permission.
POST - Write
createAttachmentUploadUrl
Generate a presigned upload URL for an attachment. Use the returned `uploadFormUrl` and `uploadFormData` fields to POST the file as multipart/form-data directly to storage. The upload URL expires after 2 hours; the resulting `attachment.id` can then be referenced in mutations such as `createThread`, `replyToEmail`, or `createNote`. Requires the `attachment:create` permission. Attachments that are never referenced in a message are automatically deleted after 24 hours.
POST - Write
createMachineUser
Creates a new machine user in the workspace. Each machine user can hold multiple API keys and optionally has a public-facing name shown to customers. Only one machine user of type AI_AGENT is allowed per workspace. Requires the `machineUser:create` permission.
POST - Write
updateMachineUser
Updates the name, description, or avatar of an existing machine user. At least one of `fullName`, `publicName`, `description`, or `avatar` must be provided. Requires the `machineUser:edit` permission.
POST - Write
createApiKey
Create an API key for a machine user. The plaintext secret is returned only once in `apiKeySecret` and cannot be retrieved again — store it immediately. You can only grant permissions that you yourself hold; attempting to escalate privileges returns an error. Requires the `apiKey:create` permission.
POST - Write
updateApiKey
Update the description and/or permissions of an existing API key. Permissions are replaced in full — pass the complete desired set. You cannot assign permissions you do not hold. Requires the `apiKey:edit` permission.
POST - Write
createOAuthApp
Creates an OAuth app owned by the workspace. When `usesPkce` is false, the app also gets a client secret, which is returned only once in `clientSecret` and can't be retrieved again. Requires the `oauthApp:create` permission.
POST - Write
updateOAuthApp
Updates the name, description, redirect URLs or allowed origins of an OAuth app. Requires the `oauthApp:edit` permission.
POST - Write
enableOAuthApp
Turns an OAuth app on, so the Plain API accepts its tokens again. Requires the `oauthApp:edit` permission.
POST - Write
disableOAuthApp
Turns an OAuth app off. The Plain API rejects every token issued to it, including ones it already holds, until it's turned back on. Requires the `oauthApp:edit` permission.
POST - Write
createMySlackIntegration
Connects the current user's personal Slack notifications integration using an OAuth auth code obtained from the Slack OAuth flow. Get the installation URL from mySlackInstallationInfo.
POST - Write
createUserAuthSlackIntegration
Connects the current user's user-auth Slack integration using an OAuth auth code. This integration allows Plain to send Slack messages as the authenticated user rather than as a bot. Get the installation URL from userAuthSlackInstallationInfo.
POST - Write
createWorkspaceSlackIntegration
Connects a workspace-level Slack notifications integration using an OAuth auth code. This integration enables Plain to post notifications to a Slack channel on behalf of the workspace. Get the installation URL from workspaceSlackInstallationInfo.
POST - Write
createWorkspaceSlackIntegrationFromAuth
Connects a workspace-level Slack notifications integration reusing a Slack connection the workspace already has, with no second OAuth install. The new integration posts through the given workspace Slack channel integration's connection. Choose the notification channel afterwards with the notification/slack/channel_id setting.
POST - Write
createWorkspaceSlackChannelIntegration
Connects a workspace Slack channel integration using an OAuth auth code. This integration allows Plain to monitor Slack channels and create threads from messages. Get the installation URL from workspaceSlackChannelInstallationInfo.
POST - Write
refreshWorkspaceSlackChannelIntegration
Re-authorizes an existing workspace Slack channel integration with a new OAuth auth code. Use this when isReinstallRequired is true on the integration to restore access.
POST - Write
createWorkspaceSlackSidekickIntegration
Installs Plain's Sidekick Agent into the workspace's Slack. Exchanges the OAuth authorization code (obtained by sending the user through the URL from workspaceSlackSidekickInstallationInfo) for a bot token, creates the Sidekick Agent Slack channel, and persists the integration. The channel is normally #ask-plain; if that name is already taken in the Slack workspace the next free name is used instead, so read askSidekickSlackChannelName off the returned integration and show the user which channel was created rather than assuming #ask-plain. Fails only if every candidate name is taken. Only one Sidekick Agent integration is allowed per workspace and per Slack team; calling this when one already exists returns an error. Requires the workspaceSlackSidekickIntegration:create permission and the ai_agent billing entitlement.
POST - Write
refreshWorkspaceSlackSidekickIntegration
Re-authorizes an existing workspace Slack Sidekick Agent integration with a new OAuth auth code. Use this when isReinstallRequired is true on the integration to restore access. Requires the workspaceSlackSidekickIntegration:update permission.
POST - Write
updateSidekickSlackConfig
Updates configuration for the workspace's Slack Sidekick Agent integration. Currently supports setting custom operating instructions that guide Sidekick Agent's behavior. Omitting operatingInstructions is a no-op; passing null or an empty string clears any existing instructions. Requires the workspaceSlackSidekickIntegration:update permission.
POST - Write
createWorkspaceDiscordChannelIntegration
Connects a Discord server (guild) to this workspace using an OAuth authorization code. Complete the OAuth flow via `workspaceDiscordChannelInstallationInfo` first to obtain the `authCode`. Once connected, Plain can receive inbound Discord messages and users can send replies via `sendDiscordMessage`.
POST - Write
createUserAuthDiscordChannelIntegration
Links the current user's personal Discord account to a specific Discord guild. Users must complete this in addition to the workspace-level integration before they can send Discord messages. Obtain the `authCode` by directing the user through the URL returned by `userAuthDiscordChannelInstallationInfo`.
POST - Write
refreshConnectedDiscordChannels
Syncs the list of Discord channels for a guild from the Discord API into Plain. Call this after channels are added or renamed in Discord so that `connectedDiscordChannels` reflects the latest state.
POST - Write
updateConnectedDiscordChannel
Updates settings for a connected Discord channel, such as enabling or disabling it. Disabled channels will not receive new messages from Plain.
POST - Write
createWorkspaceDiscordIntegration
Creates a webhook-based Discord integration for this workspace using an incoming webhook URL from Discord. This is the simpler webhook integration (as opposed to the full OAuth channel integration) and is used to post notifications to a Discord channel. The `webhookUrl` must be a valid Discord incoming webhook URL.
POST - Write
createMyLinearIntegration
Connects the current user's Plain account to their Linear account by exchanging an OAuth authorization code. Obtain the authorization code by directing the user through the URL returned by myLinearInstallationInfo. The redirectUrl must match the one used when generating the installation URL. Each workspace can only be connected to one Linear organisation; attempting to connect a second organisation returns an error.
POST - Write
createLinearAppIntegration
mutation createLinearAppIntegration
POST - Write
createGithubUserAuthIntegration
Connects the currently authenticated user's Plain account to their GitHub account using a Nango OAuth session. Requires the 'githubUserAuthIntegration:create' permission.
POST - Write
createWorkspaceCursorIntegration
Creates a Cursor integration for the workspace using the provided API token. Only one integration can be active at a time; call `deleteWorkspaceCursorIntegration` before creating a new one. Requires the `workspaceCursorIntegration:create` permission.
POST - Write
createMyMSTeamsIntegration
Connects the current user's personal Microsoft Teams account to Plain using the OAuth authorization code obtained after completing the installation flow from `myMSTeamsInstallationInfo`.
POST - Write
createWorkspaceMSTeamsIntegration
Creates a workspace-level Microsoft Teams integration by linking Plain to an Azure AD tenant. Each workspace can only have one integration, and each tenant can only be connected to one workspace. Call `workspaceMSTeamsInstallationInfo` first to obtain the admin-consent URL, then pass the resulting tenant ID here.
POST - Write
updateSetting
Create or overwrite a named setting at the given scope. Provide exactly one value field in `SettingValueInput` (boolean, string, number, or stringArray) that matches the expected type for the setting code. Returns the stored setting on success. To clear a value and revert to the scope hierarchy default, use `deleteSetting` instead.
POST - Write
bulkUpdateSlackChannelSettings
Applies many Slack per-channel setting writes in a single request. Each update targets the `WORKSPACE_SLACK_CONNECTED_CHANNEL` scope and is written with the same semantics as `updateSetting`. The writes are attempted independently; partial failures are reported per-item.
POST - Write
createCustomerCardConfig
Creates a new customer card config. New configs are placed at the bottom of the list (order 100000) by default. A maximum of 25 card configs can be created per workspace. Returns a `too_many_customer_card_configs` error if the limit is reached. The `key` must be unique within the workspace and is used in the request payload sent to your API URL.
POST - Write
updateCustomerCardConfig
Partially updates a customer card config. Only fields that are provided in the input will be changed; omitted fields are left unchanged. Updating `apiUrl` or `apiHeaders` requires the `customerCardConfigApiDetails:edit` permission. Changing the `key` must still result in a unique key within the workspace.
POST - Write
reorderCustomerCardConfigs
Updates the display order of one or more customer card configs. Only the configs listed in the input are updated; other configs keep their current order. This allows you to swap two configs or move a single card without specifying the full list. Duplicate order values are permitted and ties are broken by ID.
POST - Write
reloadCustomerCardInstance
Forces a fresh load of a customer card instance, bypassing the cache. Use this when you know your external data has changed and you want to immediately fetch updated card content from your API URL. The response will be a `CustomerCardInstanceLoading`; subscribe to `customerCardInstanceChanges` to receive the loaded or errored result.
POST - Write
createWebhookTarget
Register a new HTTP endpoint to receive Plain webhook events. You must specify the URL, a human-readable description, the webhook schema version to pin to, whether deliveries should start immediately, and the list of event types to subscribe to. You can optionally supply custom HTTP headers (e.g. an `Authorization` header) to send with every delivery. Use `subscriptionEventTypes` to discover valid event type identifiers. Requires the `webhookTarget:create` permission.
POST - Write
updateWebhookTarget
Update an existing webhook target. You can change the URL, pause or resume deliveries via `isEnabled`, switch to a newer schema version, change which event types are subscribed to, or replace the custom HTTP headers. Scalar fields use a `{ value: ... }` wrapper so you can omit fields you do not want to change; `eventSubscriptions` and `headers` are full replacements of the previous lists, so include every entry the target should keep. At least one field must be provided. Requires the `webhookTarget:edit` permission.
POST - Write
createThread
Create a new thread for a customer. Commonly used when a customer submits a contact form or when you want to start a proactive support interaction from your own product. The thread is created in `TODO` status. You can optionally set a title, priority, assignee, labels, thread fields, tenant, and an `externalId` for later lookup. Requires the `thread:create` and `thread:read` permissions.
POST - Write
importThread
Import a thread from an external system using its historical creation timestamp. Unlike createThread, this mutation does not trigger SLAs or autoresponders, making it suitable for backfilling historical support data. The externalId is used for idempotency — re-importing the same ID returns NOOP. Requires the thread:import permission.
POST - Write
importThreadMessages
Backfill up to 25 historical messages onto an existing thread. Each message requires an externalId for idempotency — re-importing the same ID returns NOOP for that message. INBOUND messages must be authored by a customer; OUTBOUND and NOTE messages must be authored by a user. Requires the thread:import permission.
POST - Write
assignThread
Assign a thread to a specific user or machine user, replacing any existing primary assignee. Requires the `thread:assign` and `thread:read` permissions.
POST - Write
unassignThread
Remove the primary assignee from a thread, leaving it unassigned. Requires the `thread:unassign` and `thread:read` permissions.
POST - Write
addAdditionalAssignees
Add one or more users or machine users as additional (secondary) assignees on a thread. Additional assignees are looped in but are not the primary person responsible. Requires the `thread:assign` and `thread:read` permissions.
POST - Write
snoozeThread
Snooze a thread for a number of seconds or until the customer replies (set `statusDetail` to `WAITING_FOR_CUSTOMER`). A snoozed thread is automatically unsnoozed when new activity arrives or when the timer expires. Requires the `thread:edit` and `thread:read` permissions.
POST - Write
markThreadAsDone
Mark a thread as Done, indicating there is nothing left for the support team to do right now. The thread will automatically revert to Todo when new activity arrives. Requires the `thread:edit` and `thread:read` permissions.
POST - Write
markThreadAsTodo
Explicitly move a thread back to Todo status. Use this to unsnooze a thread early or to reopen a thread that was incorrectly marked as Done. Requires the `thread:edit` and `thread:read` permissions.
POST - Write
changeThreadCustomer
Reassign a thread to a different customer. The original customer retains all their other threads. Requires the `thread:edit` permission.
POST - Write
changeThreadPriority
Set the priority of a thread. Priority is an integer from 0 (urgent) to 3 (low). Requires the `thread:edit` permission.
POST - Write
updateThreadTitle
Update the title of a thread. Requires the `thread:edit` permission.
POST - Write
updateThreadExternalId
Update the external ID of a thread. Pass `externalId: null` to clear it. Requires the `thread:edit` permission.
POST - Write
updateThreadTenant (deprecated)
Move a thread to a different tenant, or pass `tenantIdentifier: null` to detach it from its current tenant. Requires the `thread:edit` permission.
POST - Write
updateThreadAccount
Move a thread to a different account, or pass `accountIdentifier: null` to detach it from its current account. Requires the `thread:edit` permission.
POST - Write
updateThreadTier
Assign a thread to a tier, which governs the SLAs applied to it. Pass `tierIdentifier: null` to detach the thread from its current tier. Requires the `thread:edit` permission.
POST - Write
updateThreadServiceLevelAgreementPolicy
Assign an SLA policy to a thread. A policy takes precedence over the thread's tier when selecting SLAs. Pass `serviceLevelAgreementPolicyId: null` to detach the policy and fall back to the tier's SLAs. Requires the `thread:edit` permission.
POST - Write
updateThreadEscalationPath
Attach a thread to a specific escalation path, or pass `escalationPathId: null` to detach it. An escalation path defines the sequence of users or teams the thread escalates through if nobody responds in time. Requires the `thread:edit` permission.
POST - Write
lockThread
Lock a thread to prevent further replies or changes by non-admin users. Use this when a resolution is final and you want to freeze the conversation. Requires the `thread:edit` permission.
POST - Write
updateThreadAgentStatus
Update the AI agent status of a thread (`IN_PROGRESS`, `HANDED_OFF`, or `HANDLED`). Use this to signal that an AI agent has taken over, handed off to a human, or fully resolved the thread. Requires the `thread:edit` permission.
POST - Write
updateThreadSuggestedActionStatus
Accept or dismiss a specific AI-suggested action on a thread's catchup summary. Pass the `suggestedActionId` from the thread's `catchupDetail` and the new `status`. Requires the `thread:edit` permission.
POST - Write
createTestThread
Create a test thread for the signed-in user. Test threads come from a test customer rather than a real one. The scenario is picked for you and fixes the thread's title; its opening message is written shortly after this returns. They are listed by `testThreads` rather than `threads`, and only for the user who created them. Pass `channel: SLACK` to have the conversation happen in the workspace's Slack test channel instead of chat, so the caller sees a thread arrive the way a customer's Slack message does. Requires the `thread:create` permission.
POST - Write
createAllTestThreads
Create one test thread per scenario for the signed-in user, so they get a populated inbox in a single call rather than one `createTestThread` per scenario. Each thread comes from that scenario's own test customer, and its opening message is written shortly after this returns. Scenarios the caller already has a test thread for are skipped, so calling this again tops the set up rather than duplicating it, and a scenario that fails does not stop the rest. Use `testThreads` for the caller's full set. Requires the `thread:create` permission.
POST - Write
createThreadDiscussion
Start a new discussion on a Plain thread. Supports Slack (posts a new thread in a connected Slack channel), Email (sends an outbound email chain), and Cursor workspace background agent discussions. The markdownContent field is sent as the opening message; for Slack discussions you may also supply slackBlocks (JSON-encoded Block Kit array) for rich Slack formatting while markdownContent serves as the Plain UI fallback. Prefer createDiscussion for new integrations.
POST - Write
importThreadDiscussion
Import an existing external conversation as a discussion on a Plain thread, backfilling all messages. Currently supports Slack threads via permalink — the entire thread (root message and all replies) is imported. If the Slack channel is not yet connected to Plain, the bot will automatically join and register it as a DISCUSSION channel (requires the connectedSlackChannel:edit permission). Private channels must have the Plain bot invited via /invite @Plain first. The call is idempotent: re-importing the same Slack thread onto the same Plain thread resumes from where the previous import left off; importing onto a different thread returns an error. Threads with more than 800 messages cannot be imported.
POST - Write
createDiscussion
Create a new discussion. Supersedes createThreadDiscussion and additionally supports Sidekick Agent AGENT_SESSION discussions (which can be started without a thread). For Slack, Email, and Cursor discussion types, a threadId is required. For AGENT_SESSION discussions, threadId is optional and the discussion may be associated with a source entity (company, tenant, etc.) or page instead.
POST - Write
sendThreadDiscussionMessage
Send a reply to an existing Slack or email discussion. The message is posted in the original channel (as a Slack thread reply or email reply) and recorded in Plain. For Slack discussions you may optionally provide slackBlocks, set unfurlLinks, or broadcast the reply into the parent channel via replyBroadcast (replyBroadcast cannot be combined with attachmentIds). Prefer sendDiscussionMessage for new integrations.
POST - Write
sendDiscussionMessage
Send a message in an existing discussion. Supersedes sendThreadDiscussionMessage and additionally supports Sidekick Agent AGENT_SESSION discussions. For Slack and email discussions, use attachmentIds for customer-scoped file attachments. For AGENT_SESSION discussions, use workspaceFileIds instead. The message is delivered to the underlying channel (Slack thread reply, email reply, or agent session).
POST - Write
updateDiscussionAgentStatus
Report what an agent the workspace built is doing on a discussion. Only that agent may call this: Plain runs no session for it, so without a report the discussion looks permanently idle. Plain sets agentStatus itself for Sidekick Agent discussions, which this mutation rejects.
POST - Write
upsertDiscussionToolCall
Report a tool call made by the discussion's custom agent, keyed by toolCallId. Repeat with the same id to update; SUCCESS and ERROR are final. Callable by the bound custom agent.
POST - Write
requestDiscussionToolCallApproval
Ask a human to approve a tool call the agent has reported as PENDING. One approval per call, ever, and several may be open on one discussion at once; asking again for the same toolCallId returns the existing approval unchanged. Moves the discussion to TOOL_CALL_APPROVAL_PENDING.
POST - Write
requestDiscussionQuestion
Ask the people on an in-app discussion driven by the calling connected agent to choose among a few options, shown as a card above the message box. Asking while a card is pending adds the new questions to it, skipping any with the same text as one already there. Moves the discussion to TOOL_CALL_APPROVAL_PENDING until a person answers or dismisses the card, which emits discussion.question_resolved. Callable by the agent the discussion is bound to.
POST - Write
resolveDiscussionApproval
Decide a custom agent's approval by its approvalId. Denying fails the tool call it gates, with reviewerNote as the error; approving leaves the call PENDING for the agent to run. Sidekick Agent's approvals are decided with resolveAgentApproval instead.
POST - Write
stopDiscussionTurn
Stop the in-flight turn of an in-app discussion answered by an agent the workspace built. Plain runs nothing for that agent, so it records the stop and emits discussion.turn_stop_requested for the agent to act on. Sidekick Agent turns are stopped with stopAgentSessionTurn instead.
POST - Write
changeThreadDiscussionStatus
Moves a discussion between OPEN and RESOLVED. Callable by a person, by the custom agent a discussion is bound to, or by the machine user that started a Sidekick Agent discussion.
POST - Write
markThreadDiscussionRead
Clear the unread flag on a discussion. Use this when the user has viewed a discussion so that the isUnread indicator is reset. Returns the updated discussion.
POST - Write
resolveAgentApproval
Approves or denies a pending Sidekick Agent tool-use approval request identified by its leaseId. When approved, the agent session automatically resumes and executes the approved tools. When denied, the agent is notified so it can explain the denial to the user. An optional reviewerNote is passed back to the agent in both cases. A machine user may resolve only approvals of a Sidekick Agent session it started.
POST - Write
answerSidekickQuestion
Records the person's answer to a question card and resumes the agent with those selections: Sidekick Agent directly, a connected agent through discussion.question_resolved. Only a human may answer. Answering the same card again with the same selections is a no-op; a different answer is rejected.
POST - Write
dismissSidekickQuestion
Dismisses a question card so the person can reply in the chat instead. A connected agent learns of it through discussion.question_resolved.
POST - Write
editQueuedAgentSessionMessage
Edits the text of a user message that is waiting in a Sidekick Agent AGENT_SESSION queue. Attachments are not editable in this flow — delete and re-send to change them. Rejects with `queued_agent_session_message_already_dispatched` if the agent has already picked the message up.
POST - Write
stopAgentSessionTurn
Stops the in-flight turn of an in-app Sidekick Agent session; the session and its queue survive, and the oldest queued message runs next. A machine user may stop only a session it started.
POST - Write
replyToThread
Send a reply to the customer on a thread using the most appropriate channel automatically. Supports threads where the last inbound message is an email, a Slack message, or a form submission. If the thread has no messages yet, an email is sent to the customer. Requires the `thread:reply` (or channel-specific send) permission.
POST - Write
mintEmbedToken
Issues a short-lived RS256-signed JWT (60-second TTL) that a Plain embed iframe passes to your backend so you can verify the calling user's identity and context. Verify the token by fetching the public keys from the JWKS endpoint returned in `EmbedToken.jwksUrl`. The token carries claims identifying the Plain user, the thread, and the customer, plus the `plain_embed_id` you supplied for audit logging. Each call produces a unique token; call this mutation immediately before your embed needs to make an authenticated request to your backend.
POST - Write
upsertMyEmailSignature
Creates or updates the email signature for the currently authenticated user. The signature is appended automatically to outbound emails sent by that user.
POST - Write
createAutoresponder
Create a new autoresponder that automatically sends a reply when a thread is created from a matching message source and satisfies all specified conditions. A workspace can have at most 25 autoresponders. Requires the `autoresponder:create` permission.
POST - Write
updateAutoresponder
Update one or more fields on an existing autoresponder. Only fields provided in the input are changed; omitted fields retain their current values. Requires the `autoresponder:edit` permission.
POST - Write
reorderAutoresponders
Set new order values for one or more autoresponders. You must pass a unique `order` integer and a unique autoresponder ID for each entry; duplicate IDs or duplicate order values are rejected. Only the autoresponders included in the input are repositioned — others are left unchanged. Requires the `autoresponder:edit` permission.
POST - Write
createTenant (deprecated)
Creates a new tenant. Fails with a validation error if a tenant already exists with the provided `externalId`. Use `upsertTenant` instead if you want to create or update a tenant idempotently. Requires the `tenant:create` permission.
POST - Write
createAccount
Creates a new account. Fails with a validation error if an account already exists with the provided `externalId`. Use `upsertAccount` instead if you want to create or update an account idempotently. Requires the `tenant:create` permission.
POST - Write
upsertTenant (deprecated)
Creates a new tenant or updates an existing one identified by `externalId` or `tenantId`. Use this to keep Plain's tenant records in sync with the groups or organisations in your own product. The `result` field on the output indicates whether a record was created or updated. Requires the `tenant:read` and `tenant:create` permissions.
POST - Write
upsertAccount
Creates a new account or updates an existing one identified by `externalId` or `accountId`. Use this to keep Plain's account records in sync with the groups or organisations in your own product. The `result` field on the output indicates whether a record was created or updated. Requires the `tenant:read` and `tenant:create` permissions.
POST - Write
addCustomerToTenants (deprecated)
Adds a customer to one or more tenants. The customer can be identified by their Plain ID, external ID, or email address. If the customer is already a member of a given tenant the operation is a no-op for that tenant. Requires the `customer:edit` and `customerTenantMembership:create` permissions.
POST - Write
addCustomerToAccounts
Adds a customer to one or more accounts. The customer can be identified by their Plain ID, external ID, or email address. If the customer is already a member of a given account the operation is a no-op for that account. Requires the `customer:edit` and `customerTenantMembership:create` permissions.
POST - Write
upsertTenantFieldSchema (deprecated)
Creates or updates one or more tenant field schemas in a single call. Each schema is identified by the combination of `source` and `externalFieldId` — if a schema with that pair already exists it is updated, otherwise a new one is created. Requires `tenantFieldSchema:create` or `tenantFieldSchema:edit` permission.
POST - Write
upsertAccountFieldSchema
Creates or updates one or more account field schemas in a single call. Each schema is identified by the combination of `source` and `externalFieldId` — if a schema with that pair already exists it is updated, otherwise a new one is created. Requires `tenantFieldSchema:create` or `tenantFieldSchema:edit` permission.
POST - Write
upsertTenantField (deprecated)
Sets or updates a field value for a specific tenant. Identify the target field using `tenantFieldIdentifier` (tenant ID + external field ID) and pass exactly one value argument matching the schema's `type` (e.g. `stringValue`, `numberValue`, `booleanValue`, `arrayValue`, `dateValue`, `userReferenceValues`, or `tenantReferenceValues`). Requires `tenant:edit` permission.
POST - Write
upsertAccountField
Sets or updates a field value for a specific account. Identify the target field using `accountFieldIdentifier` (account ID + external field ID) and pass exactly one value argument matching the schema's `type` (e.g. `stringValue`, `numberValue`, `booleanValue`, `arrayValue`, `dateValue`, `userReferenceValues`, or `accountReferenceValues`). Requires `tenant:edit` permission.
POST - Write
setupTenantFieldSchemaMapping (deprecated)
Maps a tenant field schema to a built-in Plain concept such as `TIER`, enabling automatic tier assignment based on the field's value. Only one schema can be mapped to a given concept at a time.
POST - Write
setupAccountFieldSchemaMapping
Maps an account field schema to a built-in Plain concept such as `TIER`, enabling automatic tier assignment based on the field's value. Only one schema can be mapped to a given concept at a time.
POST - Write
upsertCompany (deprecated)
Creates a new company or updates an existing one identified by `companyId` or `companyDomainName`. The output includes a `result` field of either `CREATED` or `UPDATED` so you can tell which happened. You can pass a bare domain (e.g. `plain.com`) or a full URL and Plain will extract the domain. Requires the `company:create` and `company:edit` permissions.
POST - Write
startServiceAuthorization
Begin the OAuth authorization flow for a third-party service integration. Returns connection details including a serviceAuthorizationId and an HMAC digest that must be passed to the authorization URL to securely link the callback back to this workspace. After the user completes the OAuth flow in the third-party service, call completeServiceAuthorization to finalize the connection.
POST - Write
completeServiceAuthorization
Finalize a service authorization after the user has completed the OAuth flow in the third-party service. For most services, pass the serviceAuthorizationId returned by startServiceAuthorization. For Jira, also provide the jira field with the refreshToken and siteId obtained from Atlassian's OAuth callback. On success, the authorization transitions to CONNECTED status and is ready for use.
POST - Write
updateSidekickGithubConfig
Updates which GitHub repositories Sidekick Agent has access to and the operating instructions (workspace-level and per-repo) that guide its behavior. Replaces the full repo selection — omitting a repo removes it. Requires the GitHub service authorization to exist first.
POST - Write
updateSidekickServiceConfig
Updates the operating instructions that guide how Sidekick Agent uses a connected service (Datadog, Sentry, Grafana, Linear, Notion, incident.io, Attio, HubSpot, Jira, Granola, LaunchDarkly, Grain or Cursor), identified by its serviceAuthorizationId. Pass null or an empty string to clear the instructions. GitHub and PostHog have their own configuration shapes — use updateSidekickGithubConfig / updateSidekickPosthogConfig instead.
POST - Write
updateSidekickPosthogConfig
Updates the operating instructions and default project that guide how Sidekick Agent uses the PostHog integration. Pass null or an empty string to clear either field.
POST - Write
updateSidekickSettings
Updates workspace-level Sidekick Agent settings, such as the custom prompt appended to every session's system prompt and the tools selected during onboarding. Pass null or an empty string for customPrompt to clear any existing value. Omit a field to leave it unchanged.
POST - Write
updateAgentSandboxToolPolicy
Set the approval mode for a single Sidekick Agent tool in this workspace. Persisted as a sparse override; setting a tool to its factory default clears the override.
POST - Write
createSidekickCustomSkill
Create a workspace custom skill. The name must be a unique URL-safe slug.
POST - Write
updateSidekickCustomSkill
Update a workspace custom skill. Only the provided fields are changed.
POST - Write
createSidekickMcpServer
Register a custom (customer-owned) MCP server for Sidekick Agent and mint a Nango Connect session for in-browser OAuth consent. The server is created in an unreachable state; call completeSidekickMcpServerConnection after consent to discover its tools and mark it connected.
POST - Write
completeSidekickMcpServerConnection
Complete a custom MCP server connection after the admin finishes the in-browser OAuth consent: stores the Nango connection, discovers the server's tools (tools/list), persists the snapshot, and marks the server connected.
POST - Write
updateSidekickMcpServer
Update a custom MCP server's name or operating instructions. The server URL and slug are immutable after creation.
POST - Write
refreshSidekickMcpServerTools
Re-discover a custom MCP server's tools (tools/list) and reconcile the cached snapshot: newly-appeared tools start in the "ask" (approval-required) state.
POST - Write
createImportSync
Create an import job definition that continuously syncs tenant field schemas, tenants, and customers from a connected external service (Attio, HubSpot, or Salesforce). Only one enabled import job definition can exist per service authorization at a time; calling this when one is already enabled returns an error. Use updateImportJobDefinition to disable an existing definition before creating a new one.
POST - Write
importTenantFieldSchemasFromService (deprecated)
Fetches tenant field schemas from a connected external service (identified by `serviceIntegrationKey`) and upserts them into Plain. The service must already be authorized and connected. Returns the full list of schemas that were imported.
POST - Write
importAccountFieldSchemasFromService
Fetches account field schemas from a connected external service (identified by `serviceIntegrationKey`) and upserts them into Plain. The service must already be authorized and connected. Returns the full list of schemas that were imported.
POST - Write
updateImportJobDefinition
Disable the active import job definition for a service integration. This is the only supported update — pass isEnabled: false to stop future sync runs. Returns an error if no enabled definition exists for the given service.
POST - Write
createTier
Creates a new tier. You can optionally add tenant and company members at creation time. Requires the `tier:create` permission.
POST - Write
updateTier
Updates the name, color, external ID, default priority, or default flag of an existing tier. Only the fields you provide are changed. Requires the `tier:update` permission.
POST - Write
createServiceLevelAgreement
Create a service level agreement (SLA) for a tier. Each SLA commits your team to a time target and can be scoped by thread priority and/or label type. Provide exactly one of `firstResponseTimeMinutes` (time from thread creation to first reply), `nextResponseTimeMinutes` (time from each customer message to the next reply), `firstResolutionTimeMinutes` (time from thread creation to first Done), or `totalResolutionTimeMinutes` (time from thread creation to Done, including after reopen). A `nextResponseTimeMinutes` SLA can only be created if a `firstResponseTimeMinutes` SLA already exists on the same tier. Requires the `serviceLevelAgreement:create` permission.
POST - Write
updateServiceLevelAgreement
Update an existing SLA's time target, priority or label filter, business-hours setting, or breach actions. You cannot change an SLA's type after creation. Use the field-level wrapper inputs (e.g. `{ "value": 60 }`) for the fields you want to change and omit the rest. Requires the `serviceLevelAgreement:edit` permission.
POST - Write
createServiceLevelAgreementPolicy
Create an SLA policy together with its targets. A policy holds at most one target per type, and any combination of types is valid. Business hours are configured on the policy and apply to every target in it. A policy only starts tracking once it is applied to a thread. Requires the `serviceLevelAgreement:create` permission.
POST - Write
updateServiceLevelAgreementPolicy
Update an SLA policy and its targets. Pass the full set of targets you want the policy to have: a target of an existing type is updated in place, so live SLA trackers are unaffected, a new type is added, and a type you leave out is removed along with its trackers. Requires the `serviceLevelAgreement:edit` permission.
POST - Write
addMembersToTier
Adds one or more tenants or companies to a tier (up to 25 per call). Because each tenant or company can belong to only one tier at a time, adding a member that already belongs to another tier will move it to this tier. Requires the `tierMembership:read` and `tierMembership:create` permissions.
POST - Write
updateCompanyTier (deprecated)
Sets the tier for a single company, identified by its Plain ID or domain name. Pass a null `tierIdentifier` to remove the company from its current tier. Use `addMembersToTier` when you need to move multiple companies at once. Requires the `tierMembership:read` and `tierMembership:create` permissions.
POST - Write
updateTenantTier (deprecated)
Sets the tier for a single tenant, identified by its Plain ID or external ID. Pass a null `tierIdentifier` to remove the tenant from its current tier. Use `addMembersToTier` when you need to move multiple tenants at once. Requires the `tierMembership:read` and `tierMembership:create` permissions.
POST - Write
updateAccountTier
Sets the tier for a single account, identified by its Plain ID or external ID. Pass a null `tierIdentifier` to remove the account from its current tier. Use `addMembersToTier` when you need to move multiple accounts at once. Requires the `tierMembership:read` and `tierMembership:create` permissions.
POST - Write
upsertBusinessHours (deprecated)
Create or update the workspace's business hours using a per-weekday schedule. Deprecated — use createBusinessHoursSchedule or updateBusinessHoursSchedule instead, which support multiple named, timezone-aware schedules.
POST - Write
syncBusinessHoursSlots (deprecated)
Replace the workspace's business hours with the provided set of slots. Deprecated — use createBusinessHoursSchedule or updateBusinessHoursSchedule instead, which support multiple named schedules. Only works while the workspace has exactly one business hours schedule; otherwise it returns an error. Requires the `businessHours:edit` permission.
POST - Write
createBusinessHoursSchedule
Create a new named business hours schedule, optionally with its opening slots. Overlapping and adjacent slots are merged on write. Requires the `businessHours:create` permission.
POST - Write
updateBusinessHoursSchedule
Update a business hours schedule's name, its slots, or both. Omitted fields are left unchanged; passing an empty `slots` array clears the schedule's business hours. Overlapping and adjacent slots are merged on write. Requires the `businessHours:edit` permission.
POST - Write
createBusinessHoursOverride
Create an override that replaces a schedule's weekly hours from `startsOn` to `endsOn`, e.g. a holiday. Can't overlap another override on the same schedule. Requires the `businessHours:create` permission.
POST - Write
updateBusinessHoursOverride
Update an override's name, dates or slots. Omitted fields are left unchanged. Requires the `businessHours:edit` permission.
POST - Write
syncUserWorkingHours
Replace a user's working hours schedule in full. When `isEnabled` is true, the user's status is automatically switched to ONLINE at the start of each slot and to OFFLINE or AWAY (depending on workspace settings) at the end. Omit `userId` to configure the currently authenticated user's own schedule.
POST - Write
createHyperlineCheckoutSession
Creates a Hyperline-hosted checkout session for upgrading to a paid plan. Returns a URL that you redirect the user to in order to complete payment. Requires the `billing:edit` permission.
POST - Write
createHyperlineBillingPortalSession
Creates a Hyperline billing portal session and returns a URL where the user can manage their subscription, invoices, and payment methods. Requires the `billing:edit` permission.
POST - Write
createHyperlineComponentsAuthToken
Creates a short-lived authentication token for embedding Hyperline billing UI components directly in your own interface. Requires the `billing:edit` permission.
POST - Write
calculateRoleChangeCost
Calculates the billing cost delta of changing a user's role or seat type, including prorated and full-period amounts. Use this before making a role change to show the user an accurate cost preview.
POST - Write
addUserToActiveBillingRota
Moves a user onto the active billing rota, marking them as currently consuming an eng-rota seat. The user must already hold a billing rota seat. Requires the `billingSeat:edit` permission.
POST - Write
updateActiveBillingRota
Atomically adds and removes multiple users from the active billing rota in a single call. At least one user must be added or removed; the same user cannot appear in both lists. Requires the `billingSeat:edit` permission.
POST - Write
changeBillingPlan
Switches the workspace to a different billing plan. Use `previewBillingPlanChange` first to show the user the cost impact before applying the change.
POST - Write
previewBillingPlanChange
Returns a cost preview for switching to a different billing plan, including the immediate charge and the earliest date the change can take effect. No changes are made to the subscription.
POST - Write
purchaseCredits
Purchases a top-up credit bundle for AI features. The count must match the unit count of a configured top-up bundle. Returns the updated top-up credit balance after purchase. Requires the `billing:edit` permission.
POST - Write
regenerateWorkspaceHmac
Generates a new HMAC secret for the workspace, replacing any existing secret. Plain includes this secret as a signature header on outbound HTTP requests (e.g. workflow rule HTTP steps) so your server can verify the request originated from Plain. Requires the `workspaceHmac:edit` permission.
POST - Write
createIndexedDocument
Manually add a single URL as an indexed document within an existing knowledge source. The document is fetched and queued for indexing asynchronously. Requires Plain AI to be enabled on the workspace.
POST - Write
updateGeneratedReply
Record teammate feedback (thumbs up / thumbs down and an optional comment) on a generated reply. Use this to signal whether a suggestion was helpful so Plain can improve future suggestions. Requires the `generatedReply:edit` permission.
POST - Write
createKnowledgeSource
Create a new knowledge source that Plain AI will index and use when generating replies. Use type `SITEMAP` to crawl all URLs listed in a sitemap XML file, or type `URL` to index a single page. Requires Plain AI to be enabled on the workspace.
POST - Write
reindexKnowledgeSource
Trigger an immediate re-index of a knowledge source. Use this when the source content has changed and you do not want to wait for the automatic weekly re-index. The knowledge source status is reset to pending and indexing is queued asynchronously. Requires Plain AI to be enabled on the workspace.
POST - Write
createThreadChannelAssociation
Associates a connected Slack channel with a company or tenant so that threads from that channel are automatically routed to the correct customer context. Requires either a company or tenant identifier (or both). Returns the existing association if the channel is already linked to the same target; returns an error if the channel is already linked to a different target. Requires the `threadChannelAssociation:create` permission.
POST - Write
updateThreadChannelAssociationTenantMembershipPolicy (deprecated)
Changes how tenants are assigned for an existing thread channel association. Requires the `threadChannelAssociation:edit` permission.
POST - Write
updateThreadChannelAssociationAccountMembershipPolicy
Changes how accounts are assigned for an existing thread channel association. Requires the `threadChannelAssociation:edit` permission.
POST - Write
createWorkspaceFileUploadUrl
Begin a two-step file upload. Returns a pre-signed S3 form URL and form data fields that you POST the raw file bytes to directly from the client. The upload URL expires in 2 hours. Files must be 50 MB or smaller; certain executable file extensions (e.g. .exe, .bat) are rejected. Requires the `workspaceFile:create` permission.
POST - Write
createWorkspaceFileDownloadUrl
Generate a fresh download URL for a workspace file. For PRIVATE files, returns a short-lived pre-signed URL (valid for 3 minutes); for PUBLIC files, returns a permanent CDN URL with no expiry. Call this whenever you need to give a user access to a file rather than caching URLs, as private URLs expire quickly.
POST - Write
resolveCustomerForSlackChannel
Finds or creates a Plain customer associated with a Slack channel, using the Slack users in that channel to identify the customer. Useful for bootstrapping threads from Slack channels.
POST - Write
resolveCustomerForMSTeamsChannel
Finds or creates a Plain customer associated with the Microsoft Teams users in the given channel, using the workspace's connected MS Teams integration. Useful for bootstrapping a support thread from a Teams channel conversation.
POST - Write
createHelpCenter
Create a new help center with a subdomain, branding, and access settings. Requires the helpCenter:edit permission.
POST - Write
updateHelpCenter
Update the settings, branding, or access configuration of an existing help center. Only fields that are provided are updated. Requires the helpCenter:edit permission.
POST - Write
updateHelpCenterCustomDomainName
Set or clear the custom domain name for a help center. After setting, use verifyHelpCenterCustomDomainName to confirm DNS propagation. Requires the helpCenter:edit permission.
POST - Write
verifyHelpCenterCustomDomainName
Trigger a DNS verification check for the custom domain configured on the help center. Returns an error if the expected TXT record is not yet visible. Requires the helpCenter:edit permission.
POST - Write
updateHelpCenterIndex
Replace the navigation index (sidebar order and hierarchy) of a help center in a single call. You must supply the hash returned by the helpCenterIndex query — if the index has changed since you read it, the call will fail so you can re-fetch and re-apply your changes. Requires the helpCenter:edit permission.
POST - Write
upsertHelpCenterArticle
Create or update a help center article. Omit helpCenterArticleId to create a new article; provide it to update an existing one. The slug is normalized to lowercase and must be unique within the help center. contentHtml is rendered directly in the help center. status defaults to DRAFT when not provided. Requires the helpCenter:edit permission.
POST - Write
generateHelpCenterArticle
Use AI to generate one or more draft help center articles from the content of a support thread. Returns the generated articles in DRAFT status for review before publishing. Requires the helpCenter:edit permission.
POST - Write
createHelpCenterArticleGroup
Create a new article group (folder) within a help center. Pass parentHelpCenterArticleGroupId to nest the group inside an existing group. Requires the helpCenter:edit permission.
POST - Write
updateHelpCenterArticleGroup
Update the name of an existing article group. Requires the helpCenter:edit permission.
POST - Write
createIssueTrackerIssue
Create a new issue in a connected issue tracker (Shortcut, Rootly, incident.io, or GitHub) and return a `ThreadLinkCandidate` that can immediately be used with `createThreadLink` to link it to a thread. The `fields` array must include all required fields for the chosen tracker (use `issueTrackerFields` to discover which fields are required and their allowed values). For GitHub, the acting user must have a personal GitHub user auth integration set up via `createGithubUserAuthIntegration`; the issue is created on their behalf. Requires the `threadLink:create` permission.
POST - Write
createCustomerSurvey
Creates a new customer survey (e.g. a CSAT survey) in the workspace. Requires the `customerSurvey:create` permission and a billing entitlement for customer surveys. You must supply a template (currently only `csatTemplate` is supported) and can optionally specify targeting conditions, an enabled state, a send delay, and a per-customer cooldown interval.
POST - Write
updateCustomerSurvey
Updates an existing customer survey. At least one field must be provided. Partial updates are supported — only the fields you include are changed. Requires the `customerSurvey:edit` permission.
POST - Write
reorderCustomerSurveys
Updates the display order of one or more customer surveys in a single call. Pass an array of survey ID / order-index pairs; only surveys whose order actually changes are updated. Duplicate survey IDs in the input are rejected. Requires the `customerSurvey:edit` permission.
POST - Write
addGeneratedReply
Programmatically add a suggested reply to a thread. The reply is surfaced to teammates in Plain so they can review, edit, and send it — the customer sees nothing until a teammate explicitly sends it. The `timelineEntryId` must reference an inbound message on the thread, from the customer or from a machine user. A message the workspace sent, including one your own machine user sent, is not a valid target. The `markdown` field is capped at 5,000 characters. Requires the `generatedReply:create` permission.
POST - Write
escalateThread
Advance a thread to the next step in its escalation path. The thread must already have an escalation path attached (via `updateThreadEscalationPath`) — if not, this call returns an error. Requires the `thread:edit` permission.
POST - Write
createAiFeatureFeedback (deprecated)
Submit feedback on an AI feature result (e.g. an AI agent reply or a thread catchup). Deprecated — use `createAiFeedback` instead.
POST - Write
createAiFeedback
Submit feedback on any Plain AI feature result. Pass a JSON-encoded object in the `feedback` field whose `type` discriminates the feature (`AI_AGENT`, `THREAD_CATCHUP`, `THREAD_CLUSTERS`, `TONE_RULE`, or `KNOWLEDGE_GAP`) and includes the relevant context fields and an optional `sentiment` (`POSITIVE`, `NEGATIVE`, or `NEUTRAL`).
POST - Write
createMcpFeedback
Report a problem or an idea about Plain's MCP tools to the Plain team. Call this when a tool fails unexpectedly, when you cannot do what the user asked with the available tools, or when you have a concrete idea that would make the tools more useful. Describe the problem in `comment` and name the tool in `toolName` if one was involved. Do not include customer data, personal information, or message content in `comment`. Requires the `aiFeatureFeedback:create` permission.
POST - Write
generateAiToneRulesFromDescription
Uses AI to generate a set of tone rules from a free-text description of the desired communication style (up to 5000 characters). The generated rules are saved to the workspace in a disabled state so you can review and selectively enable them. Returns the newly created rules. Requires the `aiToneRule:create` permission.
POST - Write
createAiToneRule
Creates a single AI tone rule with the given category and description. Rules are enabled by default; pass `isEnabled: false` to create the rule in a disabled state. A workspace may have at most 7 simultaneously enabled rules across all categories. Requires the `aiToneRule:create` permission.
POST - Write
updateAiToneRules
Updates up to 10 AI tone rules in a single call. Each update item must include the rule ID and at least one field to change (`description` or `isEnabled`). Enabling a rule that would push the total number of enabled rules above 7 returns an error. Returns the full updated rule objects. Requires the `aiToneRule:edit` permission.
POST - Write
updateInternalNotifications
Marks one or more internal notifications as read, unread, or archived. Pass the notification IDs to update along with the desired `readAt` and/or `archivedAt` timestamps. Set `readAt` to null to mark a notification as unread; set `archivedAt` to a timestamp to archive it. Returns the updated notifications. Requires the `user:read` permission.
POST - Write
updateAllMyInternalNotifications
Updates every internal notification belonging to the current user that matches `filters`. Archived notifications are excluded. Provide exactly one of `readAt` or `archivedAt`. Returns how many rows changed. Rows that already had the requested state are not counted. Requires the `user:read` permission.
POST - Write
importTenantFieldSchemas (deprecated)
Upsert up to 50 tenant field schemas from an external system using their externalFieldId for idempotency. Set isDeleted: true on a schema to mark it as deleted in Plain. Returns an ImportResult with added, updated, and skipped counts.
POST - Write
importAccountFieldSchemas
Upsert up to 50 account field schemas from an external system using their externalFieldId for idempotency. Set isDeleted: true on a schema to mark it as deleted in Plain. Returns an ImportResult with added, updated, and skipped counts.
POST - Write
importTenants (deprecated)
Upsert up to 25 tenants from an external system using their externalId for idempotency. Optionally include tenant field values to sync custom fields alongside the tenant record. Returns an ImportResult with added, updated, and skipped counts.
POST - Write
importAccounts
Upsert up to 25 accounts from an external system using their externalId for idempotency. Optionally include account field values to sync custom fields alongside the account record. Returns an ImportResult with added, updated, and skipped counts.
POST - Write
importCustomers
Upsert up to 25 customers from an external system using their externalId for idempotency. Each customer can include an optional list of tenants to associate with. Returns an ImportResult with added, updated, and skipped counts.
POST - Destructive
deleteWorkspaceInvite
Cancel and delete a pending workspace invite. The invited user will no longer be able to accept it. The deleted invite is returned.
POST - Destructive
deleteUser
Permanently remove a workspace member. The user's threads remain but are unassigned. Returns an error if the user is the only owner of the workspace — another owner must exist before deletion is allowed. Requires the `user:delete` permission.
POST - Destructive
deleteCustomRole
Permanently deletes a custom role by its ID. Returns the ID of the deleted role on success. Requires the `roles:edit` permission.
POST - Destructive
archiveLabelType
Archives a label type so it can no longer be applied to threads, while preserving it on threads that already have it. To apply an archived label type again, unarchive it first. Requires the `labelType:edit` permission.
POST - Destructive
removeLabels
Remove one or more labels from a thread by label ID. All provided label IDs must belong to the same thread; mixing labels from different threads returns an error. Requires the `label:delete` permission.
POST - Destructive
removeLabelsFromUser
Remove one or more labels from a Plain user (agent) by label ID. Returns the remaining labels still applied to the user after the removal. Requires the `label:delete` permission.
POST - Destructive
deleteThreadLink
Removes an existing thread link by its ID. If the link type was `MERGED_INTO`, the previously merged thread will be marked as done automatically.
POST - Destructive
deleteNote
Soft-deletes a note. The note is marked as deleted but its record is retained. Requires the `note:delete` permission.
POST - Destructive
deleteSavedThreadsView
Permanently deletes a saved threads view. Returns an error if the view does not exist. Depending on workspace settings, only the view's creator or workspace admins may be allowed to delete a view they did not create.
POST - Destructive
deleteMyFavoritePage
Removes a favorite page for the currently authenticated user. If the specified favorite page does not exist or belongs to a different user, the mutation succeeds silently with no error. Requires the `favoritePage:delete` permission.
POST - Destructive
deleteSnippet
Soft-deletes a snippet. Deleted snippets are hidden from the snippet picker but remain fetchable by ID with `isDeleted: true`, preserving the history of replies that referenced them. Requires the `snippet:delete` permission.
POST - Destructive
deleteBroadcast
Soft-deletes a broadcast. Deleted broadcasts are excluded from `broadcasts` and `searchBroadcasts` but remain fetchable by ID with `isDeleted: true`. Requires the `broadcast:delete` permission.
POST - Destructive
deleteBroadcastAudience
Soft-deletes a broadcast audience. Rejected with `cannot_delete_broadcast_audience` while a broadcast targeting it is scheduled or being sent, since past `SCHEDULED` its author can no longer edit the reference away. Requires the `broadcastAudience:delete` permission.
POST - Destructive
deleteTask
Soft-delete a task. The task is removed from the active task list but remains queryable by ID with `isDeleted: true`. All thread links attached to the task are also deleted. Requires the `task:delete` permission.
POST - Destructive
deleteCustomer
Permanently deletes a customer and all associated data (threads, timeline entries, etc.). Deletion is asynchronous and cannot be reversed. Requires the `customer:delete` permission.
POST - Destructive
deleteCustomerGroup
Permanently delete a customer group by ID. This will fail if the group still has members — remove all customers from the group first. Requires `customerGroup:delete` permission.
POST - Destructive
removeCustomerFromCustomerGroups
Remove a customer from one or more customer groups (up to 25 at once), identified by group ID, key, or external ID. Returns an error if the customer is not currently a member of any of the specified groups. Requires `customerGroupMembership:delete` permission.
POST - Destructive
deleteThreadFieldSchema
Permanently deletes a thread field schema and removes all field values stored against it on every thread. This action cannot be undone. Requires the `threadFieldSchema:delete` permission.
POST - Destructive
deleteThreadField
Removes a stored thread field value from a thread, identified by thread ID and field key. Has no effect if the field has no value. Requires the `threadField:delete` permission.
POST - Destructive
deleteEscalationPath
Permanently deletes an escalation path by ID. Returns an error if the escalation path does not exist. Threads that were attached to this escalation path will lose their escalation path association. Requires the `escalationPath:delete` permission.
POST - Destructive
deleteWorkflowRule
Permanently delete a workflow rule. This action cannot be undone.
POST - Destructive
deleteWorkflow
Permanently delete a workflow and all its steps. Existing executions are retained for audit purposes.
POST - Destructive
deleteWorkflowStep
Delete a single step from a workflow. You are responsible for updating any steps that reference this step in their transitions.
POST - Destructive
bulkUpsertWorkflowSteps
Atomically replace all steps in a workflow. Steps with a matching `stepId` are updated; steps without an ID (or with a new ID) are created; steps that existed before but are absent from the input are deleted. Optionally updates `startStepId` and the trigger configuration in the same call. Maximum 60 steps per workflow.
POST - Destructive
deleteChatApp
Permanently delete a chat app. This action cannot be undone. Requires the `chatApp:delete` permission.
POST - Destructive
deleteChatAppSecret
Delete the signing secret associated with a chat app. After deletion, webhook signature verification for that chat app will fail until a new secret is created. Requires the `chatAppSecret:delete` permission.
POST - Destructive
deleteWorkspaceEmailDomainSettings
Removes the workspace's custom email domain configuration. After deletion, email will no longer be routed through the custom domain.
POST - Destructive
deleteEmailSuppression
Removes a hard-bounce or manual suppression for one email address. Spam-complaint suppressions cannot be removed.
POST - Destructive
removeWorkspaceAlternateSupportEmailAddress
Removes an alternate support email address from the workspace's custom domain configuration.
POST - Destructive
deleteMachineUser
Deletes a machine user and all of its API keys. The deleted machine user is returned in the response. Requires the `machineUser:delete` permission.
POST - Destructive
deleteApiKey
Permanently revoke an API key. The deleted key is returned for confirmation. System-managed keys cannot be deleted. Requires the `apiKey:delete` permission.
POST - Destructive
deleteOAuthApp
Permanently deletes an OAuth app. Every token it holds is rejected straight away. Requires the `oauthApp:delete` permission.
POST - Destructive
deleteMySlackIntegration
Disconnects the current user's personal Slack notifications integration.
POST - Destructive
deleteUserAuthSlackIntegration
Disconnects the current user's user-auth Slack integration for the specified Slack workspace.
POST - Destructive
deleteWorkspaceSlackIntegration
Disconnects and removes a workspace-level Slack notifications integration.
POST - Destructive
deleteWorkspaceSlackChannelIntegration
Disconnects and removes a workspace Slack channel integration. Connected channels for this integration will no longer be monitored.
POST - Destructive
deleteWorkspaceSlackSidekickIntegration
Removes Plain's Sidekick Agent from the workspace's Slack. Returns the integration that was deleted. Returns an error if no Sidekick Agent integration exists. Requires the workspaceSlackSidekickIntegration:delete permission.
POST - Destructive
deleteWorkspaceDiscordChannelIntegration
Removes a workspace Discord channel integration, disconnecting the Discord guild from the workspace. Existing threads and messages are not deleted.
POST - Destructive
deleteUserAuthDiscordChannelIntegration
Removes the current user's personal Discord authentication for the specified integration, preventing them from sending Discord messages until they re-authenticate.
POST - Destructive
deleteWorkspaceDiscordIntegration
Removes a webhook-based workspace Discord integration by its ID.
POST - Destructive
deleteMyLinearIntegration
Disconnects the current user's Linear integration. If no integration exists this is a no-op and succeeds.
POST - Destructive
deleteLinearAppIntegration
mutation deleteLinearAppIntegration
POST - Destructive
deleteGithubUserAuthIntegration
Disconnects the currently authenticated user's GitHub integration, removing their stored credentials. Requires the 'githubUserAuthIntegration:delete' permission.
POST - Destructive
deleteWorkspaceCursorIntegration
Removes the workspace's Cursor integration. If no integration with the given ID exists, the operation succeeds and returns a null `id`. Requires the `workspaceCursorIntegration:delete` permission.
POST - Destructive
deleteMyMSTeamsIntegration
Disconnects the current user's personal Microsoft Teams integration from Plain.
POST - Destructive
deleteWorkspaceMSTeamsIntegration
Removes a workspace-level Microsoft Teams integration. Pass the integration's `id` as `integrationId`. Returns the deleted integration.
POST - Destructive
deleteSetting
Delete a stored setting value at the given scope, causing the effective value to revert to the next level in the scope hierarchy (for example, removing a per-channel override exposes the workspace-level default). Returns the value that was removed in `previousSetting`, or null if no explicit value was stored at that scope. This operation is idempotent — deleting a setting that does not exist returns null without an error.
POST - Destructive
deleteCustomerCardConfig
Permanently deletes a customer card config and stops loading that card for all customers.
POST - Destructive
deleteWebhookTarget
Delete a webhook target, stopping all future deliveries to that endpoint and removing it from the workspace. Existing delivery attempt history is retained until normal retention expiry. Requires the `webhookTarget:delete` permission.
POST - Destructive
removeAdditionalAssignees
Remove one or more additional assignees from a thread. Does not affect the primary assignee. Requires the `thread:unassign` and `thread:read` permissions.
POST - Destructive
deleteThread
Permanently delete a thread and all its associated data from Plain. This action is irreversible — use with caution. Requires the `thread:delete` permission.
POST - Destructive
deleteTestThread
Permanently delete one of the signed-in user's own test threads. Other threads are reported as not found.
POST - Destructive
deleteAllTestThreads
Permanently delete every test thread belonging to the signed-in user.
POST - Destructive
deleteThreadDiscussion
Permanently delete a discussion from Plain. Only Slack-channel discussions are currently supported. This removes the discussion record from Plain but does not delete the underlying Slack thread.
POST - Destructive
deleteQueuedAgentSessionMessage
Removes a user message that is waiting in a Sidekick Agent AGENT_SESSION queue. Rejects with `queued_agent_session_message_already_dispatched` if the agent has already picked the message up — the frontend should reload to reflect the new state.
POST - Destructive
deleteAutoresponder
Permanently delete an autoresponder. The deleted autoresponder is returned in the response. Requires the `autoresponder:delete` permission.
POST - Destructive
deleteTenant (deprecated)
Permanently deletes a tenant, unlinking it from all customers and removing its fields. Threads that were associated with the tenant retain a tombstone reference but are no longer routed through it. The tenant can be identified by either its Plain `tenantId` or its `externalId`. Requires the `tenant:delete` permission.
POST - Destructive
deleteAccount
Permanently deletes an account, unlinking it from all customers and removing its fields. Threads that were associated with the account retain a tombstone reference but are no longer routed through it. The account can be identified by either its Plain `accountId` or its `externalId`. Requires the `tenant:delete` permission.
POST - Destructive
removeCustomerFromTenants (deprecated)
Removes a customer from one or more tenants. The customer can be identified by their Plain ID, external ID, or email address. If the customer is not currently a member of a specified tenant the operation is a no-op for that tenant. Requires the `customer:edit` and `customerTenantMembership:delete` permissions.
POST - Destructive
removeCustomerFromAccounts
Removes a customer from one or more accounts. The customer can be identified by their Plain ID, external ID, or email address. If the customer is not currently a member of a specified account the operation is a no-op for that account. Requires the `customer:edit` and `customerTenantMembership:delete` permissions.
POST - Destructive
setCustomerTenants (deprecated)
Replaces the full set of tenant memberships for a customer in a single call. Any tenants not included in the input are removed; any new ones are added. Use this when syncing tenant membership from your own system rather than tracking individual add/remove changes. Requires the `customer:edit`, `customerTenantMembership:create`, and `customerTenantMembership:delete` permissions.
POST - Destructive
setCustomerAccounts
Replaces the full set of account memberships for a customer in a single call. Any accounts not included in the input are removed; any new ones are added. Use this when syncing account membership from your own system rather than tracking individual add/remove changes. Requires the `customer:edit`, `customerTenantMembership:create`, and `customerTenantMembership:delete` permissions.
POST - Destructive
deleteTenantFieldSchema (deprecated)
Permanently deletes a tenant field schema and all field values stored against it across all tenants. This action cannot be undone. Requires `tenantFieldSchema:delete` permission.
POST - Destructive
deleteAccountFieldSchema
Permanently deletes an account field schema and all field values stored against it across all accounts. This action cannot be undone. Requires `tenantFieldSchema:delete` permission.
POST - Destructive
deleteTenantField (deprecated)
Clears a tenant's value for a specific field without removing the field schema itself. Use this to unset a field value while keeping the schema available for other tenants. Requires `tenant:edit` permission.
POST - Destructive
deleteAccountField
Clears an account's value for a specific field without removing the field schema itself. Use this to unset a field value while keeping the schema available for other accounts. Requires `tenant:edit` permission.
POST - Destructive
removeTenantFieldSchemaMapping (deprecated)
Removes the mapping between a tenant field schema and a built-in Plain concept, disabling any automatic behaviour (such as tier assignment) driven by that field.
POST - Destructive
removeAccountFieldSchemaMapping
Removes the mapping between an account field schema and a built-in Plain concept, disabling any automatic behaviour (such as tier assignment) driven by that field.
POST - Destructive
deleteCompany (deprecated)
Deletes a company identified by `companyId` or `companyDomainName`. Deleting a company unlinks it from all of its customers — the customers themselves are not deleted. Requires the `company:delete` permission.
POST - Destructive
deleteServiceAuthorization
Delete a workspace-level service authorization and revoke the associated credentials. Any import job definitions linked to this authorization are also disabled. This operation is permanent; to reconnect the service, start a new authorization flow.
POST - Destructive
deleteMyServiceAuthorization
Delete the current user's personal service authorization credentials (currently supported for Jira only). This removes the user's personal OAuth token but leaves the workspace-level Jira authorization intact. The primary Jira token cannot be deleted; another user must first become the primary before this user's token can be removed.
POST - Destructive
deleteSidekickCustomSkill
Delete a workspace custom skill.
POST - Destructive
deleteSidekickMcpServer
Delete a custom MCP server and best-effort revoke its Nango connection. Idempotent: deleting an unknown server is a no-op success.
POST - Destructive
deleteTier
Deletes a tier permanently. All tenant and company memberships in that tier are also removed. Requires the `tier:delete` permission.
POST - Destructive
deleteServiceLevelAgreement
Delete an SLA from a tier. A first-response-time SLA cannot be deleted while a next-response-time SLA still exists on the same tier — delete the next-response SLA first. Returns the deleted SLA on success. Requires the `serviceLevelAgreement:delete` permission.
POST - Destructive
deleteServiceLevelAgreementPolicy
Delete an SLA policy. Its targets and their SLA trackers are deleted with it, and any thread the policy was applied to falls back to its tier's SLAs. Requires the `serviceLevelAgreement:delete` permission.
POST - Destructive
removeMembersFromTier
Removes one or more tenants or companies from their current tier (up to 25 per call). After removal the member has no tier. Requires the `tierMembership:read` and `tierMembership:delete` permissions.
POST - Destructive
deleteBusinessHours (deprecated)
Delete the workspace's business hours configuration. Deprecated — use deleteBusinessHoursSchedule instead.
POST - Destructive
deleteBusinessHoursSchedule
Delete a business hours schedule and the slots belonging to it. Requires the `businessHours:delete` permission.
POST - Destructive
deleteBusinessHoursOverride
Delete an override. The schedule's weekly hours apply to its dates again. Requires the `businessHours:delete` permission.
POST - Destructive
cancelHyperlineSubscription
Cancels the workspace's active Hyperline subscription. The subscription remains active until the end of the current billing period. Requires the `billing:edit` permission.
POST - Destructive
removeUserFromActiveBillingRota
Moves a user off the active billing rota, freeing their eng-rota seat for another team member. The user must already hold a billing rota seat. Requires the `billingSeat:edit` permission.
POST - Destructive
deleteKnowledgeSource
Delete a knowledge source and remove it from Plain AI's index. This is idempotent — deleting a knowledge source that does not exist returns no error.
POST - Destructive
deleteThreadChannelAssociation
Removes a thread channel association, unlinking the connected Slack channel from its associated company or tenant. Requires the `threadChannelAssociation:delete` permission.
POST - Destructive
deleteWorkspaceFile
Delete a workspace file by ID. Requires the `workspaceFile:create` permission.
POST - Destructive
deleteHelpCenter
Permanently delete a help center and all its articles and article groups. This action cannot be undone. Requires the helpCenter:edit permission.
POST - Destructive
deleteHelpCenterArticle
Permanently delete a help center article. Requires the helpCenter:edit permission.
POST - Destructive
deleteHelpCenterArticleGroup
Delete an article group. Articles that belonged to the group are not deleted — they become ungrouped. To remove articles entirely, use deleteHelpCenterArticle. Requires the helpCenter:edit permission.
POST - Destructive
deleteCustomerSurvey
Permanently deletes a customer survey. Returns an error if the survey does not exist. Requires the `customerSurvey:delete` permission.
POST - Destructive
deleteAiToneRules
Permanently deletes one or more AI tone rules by ID. If any supplied ID does not exist the entire operation fails and no rules are deleted. Requires the `aiToneRule:delete` permission.
POST
No operations match.
See How connections work for access and permissions, or browse all integrations.