Skip to content
Changelog

Report a bug

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

    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

    relatedThreads

    Find threads that are semantically similar to the given thread, ranked by relevance. Each result includes the thread and a distance score (lower means more similar). Useful for surfacing related support history or finding duplicate issues. Requires the `thread:read` permission.

    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

    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

    shareThreadToUserInSlack

    Sends a direct Slack message to a Plain user sharing a link to the given thread. Useful for notifying a teammate about a thread directly in Slack.

    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

    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

See How connections work for access and permissions, or browse all integrations.