---
title: "Manage a topic"
method: PATCH
path: "/api/v1/topics/{ref}"
---

# Manage a topic

`PATCH /api/v1/topics/{ref}`

## Request

- Base URL: `https://myagentda.com`
- URL: `https://myagentda.com/api/v1/topics/{ref}`
- Auth: API key in header `Authorization`

Topic admin: add writers/readers (notified by email), remove members, switch visibility, rename, change description, archive/reactivate, delete a document.

## Path parameters

- `ref` string, required

## Request body

- object: Changes to apply; all fields optional.
  - `add_writers` string[]: Grant read + write.
  - `add_readers` string[]: Grant read-only.
  - `remove_members` string[]: Revoke access.
  - `visibility` 'private' | 'workspace': New visibility.
  - `rename` string: New topic name.
  - `description` string, nullable: New description (null clears it).
  - `archive` boolean: true = archive (read-only), false = reactivate.
  - `delete_document` string: Document ID to delete (admin only).

## Response `200`

Applied changes.

- object: Result of the management call.
  - `topic` Topic: A knowledge topic.
    - `id` string: Topic UUID.
    - `number` string: Short reference, e.g. T-3.
    - `name` string: Unique name.
    - `description` string, nullable: What belongs in this topic.
    - `visibility` 'private' | 'workspace': private: only named people. workspace: everyone reads.
    - `status` 'active' | 'archived': Archived topics are read-only.
    - `created_at` string: Creation time (ISO 8601).
    - `updated_at` string: Last change (ISO 8601).
  - `applied` string[]: Changes applied.
  - `skipped` string[]: No-ops that were skipped.

## Other responses

- `400`: The request was invalid.
- `401`: The access token is missing or invalid.
- `403`: The caller's role does not allow this action.
- `404`: Not found — or not visible to the caller (no existence leak).

---

[API](https://skmtc.dev/myagentda/apis/agentda.md) · [All operations](https://skmtc.dev/myagentda/apis/agentda/llms.txt) · [OpenAPI document](https://skmtc.dev/myagentda/apis/agentda/revisions/66a449ab49dc?raw)