> ## Documentation Index
> Fetch the complete documentation index at: https://plain-docs-orca-916-agent-docs-restructure.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# API and webhook updates

> Updates to Plain's API, and new webhook schema versions.

<Update label="September 4, 2026" tags={["API"]}>
  **GraphQL schema**

  * Added `createBroadcast`, `updateBroadcast`, `deleteBroadcast`, and `scheduleBroadcast` mutations, plus `broadcast`, `broadcasts`, and `searchBroadcasts` queries, so you can manage [broadcasts](/product/broadcasts) programmatically.

  **Guides**

  * The Broadcasts guide now documents [using the API](/product/broadcasts#using-the-api), including the permissions your [API key](/graphql/authentication) needs to create, update, and send broadcasts.

  [Broadcasts](/product/broadcasts#using-the-api) · [Authentication](/graphql/authentication)
</Update>

<Update label="August 19, 2026" tags={["API"]}>
  Discussion `status` is now `OPEN` or `RESOLVED`. Agent activity moved to `agentStatus` (`UNKNOWN`, `IDLE`, and related values). If you filter or switch on the old discussion status values (`IDLE`, `IN_PROGRESS`, `APPROVAL_REQUESTED`), update those clients.

  [Discussions](/graphql/discussions)
</Update>

<Update label="August 18, 2026" tags={["API"]}>
  Added `isCustomAgent` on `MachineUser`. `true` when the machine user is an agent the workspace built itself, rather than an ordinary API integration.

  [Machine users](/agents/machine-users)
</Update>

<Update label="July 14, 2026" tags={["Webhooks"]} description="2026-07-14">
  * Added `thread.note_mention_created` when a note mentions a machine user (for example an [agent](/agents)). Payload includes `thread`, `note`, and `mentions` (an array of `machineUser`).
  * Added `attio` and `email_domain` to `tenant.source` on `thread.tenant_updated`.

  [Webhook versions](/webhooks/versions) · [JSON schema](https://core-api.uk.plain.com/webhooks/schema/2026-07-14.json)
</Update>

<Update label="July 9, 2026" tags={["API"]}>
  Added `createTenant`. It fails if a tenant already exists with the given `externalId`. Use [`upsertTenant`](/graphql/tenants/upsert) when you want create-or-update. Requires `tenant:create`.
</Update>

<Update label="July 2, 2026" tags={["API"]}>
  * Added `threadsByExternalId` to list every thread with a given `externalId`, across customers. `threadByExternalId` still returns a single thread for one customer.
  * Added `knowledgeSourceCitationsByThread` for the knowledge sources cited by AI replies on a thread.

  [Fetch threads](/graphql/threads/get) · [Searching knowledge](/agents/searching-knowledge)
</Update>

<Update label="June 23, 2026" tags={["API"]}>
  Added `updateThreadExternalId`. Pass `externalId: null` to clear it. Requires `thread:edit`.

  [Updating threads](/graphql/threads/update)
</Update>

<Update label="June 15, 2026" tags={["Webhooks"]} description="2026-06-15">
  * Added `WAITING_INDEFINITELY` to `statusDetail.type` on `thread` (snoozed with no duration). The same value is available on the thread type in the API.
  * `componentUser.user` may be a `machineUser` as well as a `user` when a [UI component](/ui-components) references a machine user.

  [Webhook versions](/webhooks/versions) · [JSON schema](https://core-api.uk.plain.com/webhooks/schema/2026-06-15.json)
</Update>

<Update label="May 22, 2026" tags={["API"]}>
  Added `importThread` and `importThreadMessages` for backfilling historical threads without firing SLAs or autoresponders. Each `externalId` is idempotent (`NOOP` on replay). Requires `thread:import`.

  [Importing threads](/graphql/threads/import)
</Update>

<Update label="May 6, 2026" tags={["Webhooks"]} description="2026-05-06">
  * Added `numberValue` on `threadField`.
  * Added `NUMBER` to `threadField.type`.

  [Webhook versions](/webhooks/versions) · [JSON schema](https://core-api.uk.plain.com/webhooks/schema/2026-05-06.json)
</Update>

<Update label="May 4, 2026" tags={["API"]}>
  Added a paginated `discussions` query with filters for user and discussion type.

  [Fetch discussions](/graphql/discussions/get)
</Update>

<Update label="April 5, 2026" tags={["API"]}>
  Added `webhookDeliveryAttempts` so you can inspect delivery attempts, including response status and body, without leaving the API.

  [Delivery attempts](/graphql/webhook-targets/delivery-attempts)
</Update>

<Update label="March 30, 2026" tags={["API"]}>
  Added `createDiscussion`, `sendDiscussionMessage`, and the single `discussion` query, so you can open a side-conversation on a thread and post into it programmatically.

  [Create a discussion](/graphql/discussions/create) · [Send a message](/graphql/discussions/send-message)
</Update>

<Update label="March 25, 2026" tags={["API"]}>
  Added `importCustomers`, `importTenants`, and `importTenantFieldSchemas` for bulk backfills from another system. Each is idempotent on `externalId` and returns added, updated, and skipped counts.
</Update>

<Update label="February 11, 2026" tags={["API"]}>
  Added `updateNote` for editing an existing note on a thread.

  [Notes](/graphql/notes)
</Update>

<Update label="February 10, 2026" tags={["API"]}>
  Added `lockThread` to freeze a thread so non-admin users cannot reply or make changes.
</Update>

<Update label="January 13, 2026" tags={["API"]}>
  Added `updateThreadAgentStatus` to set a thread's AI agent status to `IN_PROGRESS`, `HANDED_OFF`, or `HANDLED`.

  [Building agents](/agents)
</Update>

<Update label="December 19, 2025" tags={["API"]}>
  Tasks are now available over the API: `createTask`, `updateTask`, `deleteTask`, plus `task`, `taskByRef`, and a filterable `tasks` query.

  [Tasks](/graphql/tasks)
</Update>

<Update label="November 21, 2025" tags={["API"]}>
  Added `labelTypeByExternalId`, so you can look up a label type by the ID it has in your own system.

  [Label types](/graphql/labels/label-types)
</Update>

<Update label="October 8, 2025" tags={["API"]}>
  Added `deleteThread` for permanently deleting a thread.

  [Deleting threads](/graphql/threads/delete)
</Update>

<Update label="September 22, 2025" tags={["API"]}>
  Added `searchKnowledgeSources` to search the knowledge your agents draw on.

  [Searching knowledge](/agents/searching-knowledge)
</Update>

<Update label="September 8, 2025" tags={["API"]}>
  Added `upsertTenantField`, `deleteTenantField`, and `deleteTenantFieldSchema`, completing tenant field management over the API.

  [Tenant fields](/graphql/tenants/tenant-fields)
</Update>

<Update label="August 28, 2025" tags={["API"]}>
  Added the `tenantFieldSchemas` query and `upsertTenantFieldSchema` mutation, including field visibility.

  [Tenant fields](/graphql/tenants/tenant-fields)
</Update>

<Update label="August 11, 2025" tags={["API"]}>
  Added `deleteTenant`. Deleting a tenant unlinks it from all customers and removes its fields.

  [Deleting tenants](/graphql/tenants/delete)
</Update>

<Update label="August 8, 2025" tags={["API"]}>
  Added the `knowledgeSources` query and `deleteKnowledgeSource` mutation.

  [Searching knowledge](/agents/searching-knowledge)
</Update>

<Update label="August 6, 2025" tags={["Webhooks"]} description="2025-08-06">
  * Added `additionalAssignees` on `thread`.
  * Added `externalId` and `isExcludedFromAi` on `labelType`.

  [Webhook versions](/webhooks/versions) · [JSON schema](https://core-api.uk.plain.com/webhooks/schema/2025-08-06.json)
</Update>