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

# archive_collab

> Archive one of your collabs, or restore an archived one. The reversible way to remove a collab.

> [!WARNING]
>
> Writes to your heyBTW workspace: it sets one collab archived or restored. Nothing is deleted. It sends nothing and changes nothing on the event platform.

The same archive the dashboard has. There is no delete over MCP. Reach for it when the user wants a test event, a cancelled event or a mistake out of their reports, or wants an archived one back.

Follows the [heyBTW MCP rules](https://heybtw.com/docs/mcp/rules.md).

## When to use it

* "Get rid of that test event I made."
* "The October dinner got cancelled, take it out of my reports."
* "Bring back the collab I archived last week."

## Parameters

| Parameter | Type | Required | Notes |
| - | - | - | - |
| `channel_id` | string | Yes | The collab, from list\_events or create\_collab. |
| `archived` | boolean | Yes | `true` archives, `false` restores. A call without a JSON boolean is refused and changes nothing. |
| `client_request_id` | string | Yes | A fresh hyphenated UUID for this call. |
| `contract_version` | string | No | Omit for v1, the only version advertised. |

## Workflow

**1. Read the collab first**

Before archiving a collab that holds sign-ups, Lists or activations, read it with get\_event\_details and confirm with the user.

**2. Call with a fresh client\_request\_id**

On a transport error, retry with the SAME id: a committed change is replayed (`idempotent_replay: true`), never repeated. Reusing the id with the other state is refused. A call that changed nothing does not consume the key.

**3. Describe it as reversible**

Tell the user the collab was archived and can be restored. Never say it was deleted.

### What archiving does and does not do

* The collab leaves list\_events, get\_event\_attribution and every MCP read of the program until restored. Its open Playbook tasks leave get\_due\_tasks' open and overdue queue.
* Nothing is deleted, completed or cascaded. Sign-ups, List links, activations, authored context, tasks and observations stay as they were. A restore returns it exactly as it was.
* Nothing changes on the event platform. The Luma, Splash or Zuddl event and the integration connection are untouched. Automatic sync of an archived collab pauses until it is restored.

## Response

The shape below is from the contract and the code (`tools/archive_collab.py`). A success was not captured live, because this tool archives a real collab.

| Field | Meaning |
| - | - |
| `channel_id` | The collab. |
| `outcome` | `archived`, `restored`, or `no_change` when the collab already held that state. |
| `archived` | The collab's state after the call. |
| `holdings.roster_count` | Its sign-ups, the count list\_events and get\_event\_details report. |
| `holdings.list_count` | Lists linked to it. |
| `holdings.activation_count` | Invite sends to its event. |
| `holdings.authored_context_count` | Entries saved with save\_event\_context. |
| `holdings.task_count` | Open Playbook tasks you can read (yours and ones shared with partners). |
| `holdings.observation_count` | Person observations recorded on it. |
| `holdings.source_platform` | Where the collab came from, or null. |
| `idempotent_replay` | true when this answer replays an earlier committed call. |

A replay of a call made before `task_count` and `observation_count` existed returns them as null, with a note. Null is unknown, not zero.

## Rules the agent must follow

* Read the collab and confirm with the user before archiving one that holds people, Lists or activations.
* Say "archived", never "deleted". It is reversible.
* Use `holdings` to tell the user what the collab still holds.
* Only the workspace's own collabs. A partner's collab, the demo collab or an unknown id returns `entity_not_found`.

## Errors and gaps

| Code | What to do |
| - | - |
| `invalid_parameter` | Validation reports one parameter at a time. Fix it and call again; another may follow. |
| `entity_not_found` | Not one of the workspace's own collabs. |
| `collab_limit_reached` | A restore would pass the plan's active-collab limit. Nothing changed. |
| `insufficient_scope` | The OAuth token lacks `mcp:tools:write`. Nothing changed. |
| `internal_error` | Retry once with the SAME `client_request_id`. |
| 429 | Honor `Retry-After`. 30 requests per 5 s, 60 per minute, 1000 per day per workspace. |

Trimmed from a real call with no arguments today:

```json theme={null}
{
  "tool": "archive_collab",
  "status": "error",
  "data": null,
  "error": {
    "code": "invalid_parameter",
    "what_failed": "A tool parameter (`channel_id`) is not valid for this tool.",
    "what_to_do": "Correct `channel_id` and retry.",
    "retryable": false
  }
}
```

## Related

* [get\_event\_details](https://heybtw.com/docs/tools/get-event-details.md), read before archiving
* [list\_events](https://heybtw.com/docs/tools/list-events.md)
* [update\_collab](https://heybtw.com/docs/tools/update-collab.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.