> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcollate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Breaking Changes - Collaboration | Official Documentation

> Tasks, suggestions, announcements, and system activity all move out of thread_entity into purpose-built entities with their own APIs in Collate 2.0.

# Collaboration

2.0 retires the thread-backed collaboration model. Tasks, suggestions, announcements, and system
activity each move out of `thread_entity` into purpose-built entities with their own tables, APIs and
permissions. Human conversations stay on `/v1/feed`.

| Concern         | 1.13 storage                          | 2.0 storage                                            |
| --------------- | ------------------------------------- | ------------------------------------------------------ |
| Conversations   | `thread_entity`                       | `thread_entity` (unchanged)                            |
| Tasks           | `thread_entity` (`type=Task`)         | **`task_entity`**                                      |
| Suggestions     | `suggestions` table                   | **`task_entity`** (`type=Suggestion`)                  |
| Announcements   | `thread_entity` (`type=Announcement`) | **`announcement_entity`**                              |
| System activity | `thread_entity` generated rows        | **`activity_stream`** (partitioned, retention-bounded) |

## Tasks become a first-class entity

**Breaking.** Affects API clients, bots, and workflow integrations reading `/v1/feed/tasks/*`.

Tasks are now backed by `task_entity`, with full CRUD and versioning at `/v1/tasks` (22 new
endpoints: list/create/upsert, resolve/close lifecycle transitions, scoped lists like `/assigned` and
`/dataAccessRequests`, bulk operations, version history). Required fields are `id`, `name`,
`category`, `type`, `status`, `createdBy`, and typed payload schemas ship per task type
(`glossaryApprovalPayload`, `dataAccessRequestPayload`, and nine others).

`/v1/feed` still exposes `GET /v1/feed/tasks/{id}`, `PUT /v1/feed/tasks/{id}/resolve` and
`PUT /v1/feed/tasks/{id}/close`, but **creating** a task thread through `POST /v1/feed` now validates
the task type and rejects anything outside the supported legacy set (description, tag, approval,
test-case-failure-resolution), plus enforces that `about` is non-blank and `taskDetails` is present
only on task threads.

<Warning>
  Move task creation to `POST /v1/tasks`. If you must stay on `/v1/feed`, restrict yourself to the four
  supported legacy task types and supply well-formed `taskDetails`.
</Warning>

Five new policy operations gate this: `CreateTask`, `EditTask`, `ResolveTask`, `CloseTask` and
`ReassignTask` (**behavioural** — affects non-admin users and application bots). The migration
backfills them onto the seed `DataConsumerPolicy` and `ApplicationBotPolicy`, but **custom policies
that replaced those seeds are not backfilled** — non-admins get `403` creating or editing tasks until
you add the operations yourself. Task authorization is also self-approval guarded: a task's creator
cannot approve their own task, even where policy would otherwise allow it.

## Suggestions become Tasks

**Breaking.** Affects AI and automation bots, and SDK users calling `/v1/suggestions`.

The entire `/v1/suggestions` namespace is removed:

| 1.13                                            | 2.0                                                       |
| ----------------------------------------------- | --------------------------------------------------------- |
| `GET /v1/suggestions?entityFQN=…`               | `GET /v1/tasks?…` filtered on `type=Suggestion`           |
| `POST /v1/suggestions`                          | `POST /v1/tasks` with `type: Suggestion`                  |
| `PUT /v1/suggestions/{id}/accept`               | `PUT /v1/tasks/{id}/suggestion/apply`, then resolve       |
| `PUT /v1/suggestions/{id}/reject`               | `POST /v1/tasks/{id}/resolve` with a rejecting resolution |
| `PUT /v1/suggestions/accept-all` / `reject-all` | `POST /v1/tasks/bulk`                                     |

The suggestion field path also moves from an entity link to `payload.fieldPath` in dot notation
(`columns.col_name.description`). Existing suggestions are migrated into `task_entity` automatically.

## Announcements become a standalone entity

**Breaking.** Affects anything reading or writing announcements through the feed API.

`/v1/feed` now rejects announcements outright — list, get, patch, create, delete, posts, and reactions
on an announcement thread all return `400` with `Announcements are no longer served from /v1/feed.
Use /v1/announcements instead.` Announcements are full entities in 2.0 (versioned, soft-deletable,
restorable) at `/v1/announcements`, and the UI renders them in the entity header rather than only in
the feed widget.

## System activity moves to a retention-bounded Activity Stream

**Breaking**, with a **data-loss note**. Affects anything treating the feed as an audit trail.

System-generated activity (field changes, entity created/updated) no longer lives in `thread_entity`.
It moves to a time-partitioned `activity_stream` table at `/v1/activity/**`, and **events older than
30 days are deleted automatically by default** (`activityStreamConfig.retentionDays`, configurable
globally or per domain).

<Warning>
  Do not use the activity stream as an audit trail. For compliance history use entity version history
  (`/v1/{entityType}/{id}/versions`) and the audit log (`/v1/audit/logs`, which gains a searchable
  `search_text` column and an export endpoint in 2.0). Activity events are ephemeral by design.
</Warning>

`thread_entity` itself is renamed to `thread_entity_legacy` post-migration (**behavioural** — affects
anyone querying the database directly); the feed repository resolves the legacy table dynamically so
migrated threads stay readable, but BI dashboards, or retention jobs querying `thread_entity` directly
need updating.

## Alert filters are scoped and matched literally

**Behavioural.** Affects existing alert subscriptions.

In 1.13, the entity-FQN filter returned `true` unconditionally for thread change events — thread
activity bypassed the filter entirely. In 2.0 a thread event is matched against the fully qualified
name of the entity the thread is **about**. An alert scoped to `service.db.schema` that previously
fired for every conversation and task in the system now fires only for threads about entities under
that name; alerts that looked noisy will go quiet, and alerts you relied on for global thread
coverage will stop firing.

Filter functions also now match fully qualified names **literally**, not as regular expressions. An
alert whose filter used `.`, `*` or `|` to match a family of names no longer matches — enumerate the
names or rely on descendant matching instead.

<Tip>
  Audit every alert with an entity name filter after upgrading, and test with
  `POST /v1/events/subscriptions/testDestination`.
</Tip>

## A few smaller additive pieces round out the redesign

`/v1/taskFormSchemas` stores per-task-type form definitions, referenced from a Task via
`taskFormSchemaId` and `taskFormSchemaVersion` — this is what lets governance workflows render
custom task forms. `changeEventType` adds `taskCreated`, `taskUpdated`,
`entityLineageAdded`/`Deleted`/`Updated` for webhook and event-subscription consumers, and
`changeEvent` gains a `recursive` flag marking cascade deletes — a single event is recorded for the
deleted root, so consumers that previously counted per-child delete events must read `recursive`
instead. Both the feed list and task list APIs also accept `startTs`/`endTs` for server-side
time-range filtering, replacing client-side windowing.

## Full detail

For the full narrative walkthrough of Collaboration in Collate 2.0 — including screenshots and step-by-step context — see [Release 2.0: Collaboration](/release-2.0/collaboration).