> ## 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.

# update_collab

> Edit a collab's settings: name, start, end, time zone, location, region, RSVP target or landing page.

> [!WARNING]
>
> Writes to your heyBTW workspace: it changes only the settings you send on one of your own collabs (and its target spec, if you pass one). It sends nothing and never writes to the event on the event platform.

The same edit the dashboard's Edit details does. Reach for it when an event's details change: the time moves, the venue is added, the event is renamed, or create\_collab assumed an end.

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

## When to use it

* "The dinner moved to 7pm, same night."
* "Add the venue: Foreign Cinema, Mission St."
* "Our RSVP target for the summit is 150."
* "The end time was a guess. It actually ends at 10."

## Parameters

Send only the fields that change.

| Parameter | Type | Required | Notes |
| - | - | - | - |
| `channel_id` | string | Yes | The collab, from list\_events or create\_collab. |
| `client_request_id` | string | Yes | A fresh hyphenated UUID for this edit. |
| `name` | string | No | One line, at most 200 characters. |
| `event_start` | string | No | RFC 3339 with an offset, or a local time read in the `timezone` you send or the collab already holds. A time with neither is refused, never guessed. A local time a daylight-saving change skips or repeats is refused with the two times it could mean. |
| `event_end` | string | No | Same rule as `event_start`. To move an event past its stored end, send both together. |
| `timezone` | string | No | IANA zone name (`America/Chicago`), never an offset. Sets or changes the zone and never moves the start or end. A zone cannot be cleared. Send it only when the person told you or the event page states it. |
| `location` | string | No | One line, at most 120 characters. |
| `region` | string | No | One line, at most 120 characters. |
| `rsvp_target` | integer | No | A whole number. |
| `landing_page_url` | string | No | One https link, at most 2048 characters, no user name or password, no parameter named like a key, token, secret, password or credential. heyBTW never opens it. |
| `clear_fields` | string\[] | No | To empty `location`, `region` or `landing_page_url`. Never send a blank instead. |
| `target_spec` | object | No | The block save\_target\_spec takes at collab scope. Replaces this collab's spec whole and keeps the prior version. Can be sent alone. |
| `contract_version` | string | No | Omit for v1, the only version advertised. |

## Workflow

There is no preview step. One call applies the edit.

**1. Confirm the change with the user**

Send only the fields that change. Re-sending a value create\_collab assumed (an end it defaulted) confirms it: the field comes back `applied` and its origin becomes `user_stated`. So send only what you mean to state.

**2. Generate a fresh client\_request\_id**

On a transport error, retry with the SAME id: a committed edit is replayed (`idempotent_replay: true`), never repeated. Reusing the id for a different edit is refused. An edit that wrote nothing does not consume the key.

**3. Read fields back to the user**

Every field you sent comes back in `data[0].fields` with a status. Report each `refused` field and its reason.

### Platform-owned fields are refused

A collab tied to a Luma, Splash or Zuddl event, or imported from a provider's public page, has its name, dates, time zone, location and landing page owned by that platform, which rewrites them on its next import or sync. A different value for one of those is:

* returned in `fields` as `{"field": ..., "status": "refused", "reason": "provider_owned", "provider": "luma" | "splash" | "zuddl"}`,
* reported as a `partial_coverage` gap ("Collab fields owned by the event platform were not changed"), so `status` is `partial`,
* NOT saved. The fields the platform does not own (`region`, `rsvp_target`) are still saved.

Tell the user to make that change on the event platform itself.

## Response

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

| Field | Meaning |
| - | - |
| `channel_id` | The collab. |
| `event_name`, `event_date`, `event_end` | Name, start and end after the edit. |
| `event_tense` | `upcoming`, `live` or `past`, read exactly as list\_events reads it. |
| `timezone`, `location`, `region`, `rsvp_target`, `landing_page_url` | As stored after the edit. |
| `outcome` | `updated` or `no_change`. |
| `fields` | One entry per field you sent: `applied` (saved), `unchanged` (it already held that value) or `refused` (not saved, with `reason` and `provider`). |
| `sync_window` | `rederived` (the data-collection window was recalculated from the new dates) or `kept` (a window set by hand in heyBTW was kept and still covers the new dates). Null otherwise. |
| `idempotent_replay` | true when this answer replays an earlier committed edit. |
| `target_spec` | Present when you passed one: what was saved and any item left out. |
| `target_spec_geography` | After a `location` edit or a new spec: which city the spec serves, and `from: collab` (this collab's spec pinned it) or `from: default` (the collab's location). |

A time edit moves the start and end everywhere at once, so list\_events, get\_event\_details and the dashboard agree.

## Rules the agent must follow

* Change only these eight settings (plus the target spec). Briefs, drafts and event framing go to save\_event\_context; a new event goes to create\_collab.
* Never guess a time zone from an offset or a place.
* To move an event later than its stored end, send `event_start` and `event_end` together. A lone `event_start` after the stored end is refused, naming that end.
* Report every `refused` field to the user, with the platform named. Never say a refused change was saved.
* This tool never edits the description, authored context, cost, rep, data-collection window, sign-ups, roster, partners or Playbook, and never touches the event on the event platform.

## Errors and gaps

| Code | What to do |
| - | - |
| `invalid_parameter` | Fix the named parameter and retry. |
| `entity_not_found` | A partner's collab, the demo collab or an unknown id. Only the workspace's own collabs can be edited. |
| `partial_coverage` gap | Platform-owned fields were refused. The rest of the edit was saved. |
| `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": "update_collab",
  "status": "error",
  "data": null,
  "error": {
    "code": "invalid_parameter",
    "message": "A tool parameter is invalid",
    "what_failed": "A tool parameter (`channel_id`) is not valid for this tool.",
    "what_to_check": "The `channel_id` argument of this call.",
    "what_to_do": "Correct `channel_id` and retry.",
    "retryable": false
  }
}
```

## Related

* [create\_collab](https://heybtw.com/docs/tools/create-collab.md)
* [save\_event\_context](https://heybtw.com/docs/tools/save-event-context.md), for briefs and drafts
* [archive\_collab](https://heybtw.com/docs/tools/archive-collab.md), to remove a collab
* Playbook: [Invite sprint](https://heybtw.com/docs/playbooks/invite-sprint.md)


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