---
title: "Set Work Channel Purpose"
method: PUT
path: "/work/channels/{channel_id}/purpose"
tags: ["Work"]
---

# Set Work Channel Purpose

`PUT /work/channels/{channel_id}/purpose`

## Request

- Base URL: `https://be.graph8.com/api/v1`
- URL: `https://be.graph8.com/api/v1/work/channels/{channel_id}/purpose`
- Auth: HTTP bearer

Give one channel a purpose, taking it from whichever channel held it.

``purpose`` is required but nullable: ``null`` clears it. An empty body is
refused rather than guessed, because this operation reassigns state on
channels the caller did not name and may not act on an ambiguity —
``reassignedChannelIds`` says which ones it moved.

## Path parameters

- `channel_id` string, required: Channel id or slug

## Headers

- `Idempotency-Key` string, nullable: Retry-safety key. Replaying one returns the ORIGINAL result with `duplicate: true` instead of writing twice. Omit it and the server mints a single-use key, which means a retried request writes again — send your own for anything you may retry.
- `Authorization` string, nullable
- `X-Target-Org-Id` string, nullable

## Request body

- WorkChannelPurposeRequest: The purpose one channel is being given, or `null` to clear it. Required-but-nullable on purpose: `{}` would be ambiguous between "clear it" and "I forgot the field", and this operation reassigns state on channels the caller did not name, so it may not act on an ambiguity.
  - `purpose` string, nullable, required

## Response `200`

Successful Response

- ApiResponseWorkChannelWriteResult
  - `data` WorkChannelWriteResult, required: The result of one channel write, with its idempotent-replay marker.
    - `channel` WorkChannel: One Work channel as the room stores it.
      - `id` string, nullable: Channel id (uuid5 of `{org}:{name}` — the room address)
      - `name` string, nullable: Slug, unique per organization. Renaming the display name never moves the room.
      - `displayName` string, nullable: Human-readable name shown in the sidebar
      - `description` string, nullable: Channel description
      - `visibility` string, nullable: `open` (self-serve joinable) or `private` (invite only)
      - `kind` string, nullable: `stream` or `forum`
      - `memberUserIds` string[], nullable: Seated member identities
      - `participantAgentIds` string[], nullable: Seated agent ids
      - `system` boolean, nullable: True for a built-in channel (`#work`, `#signals`)
      - `archivedAt` string, nullable: When the channel was archived, if it is
      - `createdBy` string, nullable: Identity that created the channel
      - `createdAt` string, nullable: Creation timestamp
    - `duplicate` boolean, nullable: True when an Idempotency-Key replay returned the original result
    - `canvasSeeded` boolean, nullable: Present when `templateId` seeded a Canvas
  - `pagination` PaginationMeta
    - `page` integer, required: Current page number (1-indexed)
    - `limit` integer, required: Items per page
    - `total` integer, required: Total number of items
    - `has_next` boolean, required: Whether there are more pages
    - `next_cursor` string, nullable: Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers.
    - `total_available` integer, nullable: Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search.
    - `total_is_lower_bound` boolean, nullable: Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search.
    - `notes` string[], nullable: Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/graph8/apis/graph8-developer-api.md) · [All operations](https://skmtc.dev/graph8/apis/graph8-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/graph8/apis/graph8-developer-api/revisions/89fc11143b70?raw)