---
title: "Topic details"
method: GET
path: "/api/v1/topics/{ref}"
---

# Topic details

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

## Request

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

Returns a topic with members (roles), document metadata, and linked tasks. Unknown or invisible topics return 404 — visibility requires membership or a workspace-visible topic.

## Path parameters

- `ref` string, required

## Response `200`

Topic details.

- object: Topic with access, documents, and linked tasks.
  - `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).
  - `my_role` 'admin' | 'writer' | 'reader': The caller's effective role.
  - `members` object[]: People with explicit access.
    - `user_id` string: User ID.
    - `role` 'admin' | 'writer' | 'reader': Member role.
    - `display_name` string: Display name.
  - `documents` DocumentMeta[]: Document metadata (content via the document endpoint).
    - `id` string: Document ID.
    - `title` string: Title.
    - `source` string, nullable: Source.
    - `version` integer: Current version.
    - `size_chars` integer: Content length in characters.
    - `updated_by` string: Last author.
    - `updated_at` string: Last update (ISO 8601).
  - `linked_tasks` object[]: Tasks linked to this topic (visible to everyone with topic access).
    - `number` string: Task number, e.g. A-17.
    - `title` string: Task title.
    - `status` string: Task status.

## Other responses

- `401`: The access token is missing or invalid.
- `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)