forums

14 endpoints.

GET/api/forums Bearer token

List forums

Lists the forums the caller may read, by organization and department, then by name — optionally narrowed to one organization or one department within it. A department's forums are read by everyone holding a role in it or in one nested beneath it, and by holders of forums:read, forums:write or forums:moderate over it. Archived forums are left out unless include_archived is true.

Parameters

Name	In	Type	Required	Description
org	query	string	no	Organization UUID id or slug to filter by (and to resolve slug refs in).
department	query	string	no	Department UUID id or slug, resolved within org (which is then required).
include_archived	query	string	no	Include archived rows. Defaults to false.

Responses

Status	Description	Body
200	The readable forums.	ForumList
400	The department filter was given without an org filter.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
404	No organization has that id or slug, or the department is not one of its own.	ErrorResponse
500	The database could not be read.	ErrorResponse

POST/api/forums Bearer token

Create a forum

Creates a forum in a department — a department may have several, each for its own kind of conversation. Its name is unique within the department, ignoring case. Requires forums:write over the department.

Request body

application/jsonrequiredCreateForumRequest

Field	Type	Required	Description
org	string	yes	Organization UUID id or slug the department belongs to. at least 1 character
department	string	yes	UUID id or slug, within the organization, of the department the forum belongs to. Requires forums:write over it. at least 1 character
name	string	yes	Unique within the department, ignoring case. 1–120 characters
description	string	no	Omit or send empty for no description. at most 1000 characters

Responses

Status	Description	Body
201	The new forum.	Forum
400	The request body failed validation.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller may read the department's forums but does not hold forums:write over it.	ErrorResponse
404	No live organization or department has that ref, or the caller cannot read its forums.	ErrorResponse
409	The department already has a forum of that name.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

GET/api/forums/{forum_id}/topics Bearer token

List a forum's discussions

Lists the discussions of one forum the caller may read, latest activity first, a page at a time.

Parameters

Name	In	Type	Required	Description
forum_id	path	string (uuid)	yes	UUID id of the forum.
cursor	query	string	no	Opaque cursor from a previous page's next_cursor.
limit	query	integer	no	Page size, 1-200. Defaults to 50.

Responses

Status	Description	Body
200	One page of the forum's discussions.	ForumTopicList
400	The cursor is invalid.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
404	No forum the caller may read has that id.	ErrorResponse
500	The database could not be read.	ErrorResponse

POST/api/forums/{forum_id}/topics Bearer token

Start a discussion in a forum

Starts a discussion in a forum, optionally linking up to ten of the organization's live job aids, courses, quizzes and events — each one the caller can open themselves. The caller must take part in the forum's department — hold a role in it or in one nested beneath it, or forums:moderate over it — and the forum must be open.

Parameters

Name	In	Type	Required	Description
forum_id	path	string (uuid)	yes	UUID id of the forum.

Request body

application/jsonrequiredCreateForumTopicRequest

Field	Type	Required	Description
title	string	yes	1–200 characters
body_markdown	string	yes	The opening post. Markdown (GitHub-flavoured: tables, task lists, strikethrough). Stored as written and rendered sanitized: raw HTML is dropped, links may only use http, https or mailto, and images show as links. 1–20000 characters
resources	array of ForumResourceRef	no	Up to 10 of the organization's live job aids, courses, quizzes and events to link, in order — each one the caller can open themselves. at most 10 items

Field

Type

Required

Description

title

string

yes

1–200 characters

body_markdown

string

yes

The opening post. Markdown (GitHub-flavoured: tables, task lists, strikethrough). Stored as written and rendered sanitized: raw HTML is dropped, links may only use http, https or mailto, and images show as links.

1–20000 characters

resources

array of ForumResourceRef

Up to 10 of the organization's live job aids, courses, quizzes and events to link, in order — each one the caller can open themselves.

at most 10 items

Responses

Status	Description	Body
201	The new discussion.	ForumTopic
400	The request body failed validation.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller may read the forum (forums:read or forums:write) but not take part in it.	ErrorResponse
404	No forum the caller may read has that id, or a linked resource is not one they can open.	ErrorResponse
409	The forum is archived.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

GET/api/forums/{forum_id} Bearer token

Read one forum

Reads a forum — its department, description, how many discussions it holds and when one last moved — and what the caller may do to it. Its discussions are listed through GET /forums/{forum_id}/topics.

Parameters

Name	In	Type	Required	Description
forum_id	path	string (uuid)	yes	UUID id of the forum.

Responses

Status	Description	Body
200	The forum.	Forum
401	The access token is missing or invalid.	ErrorResponse
404	No forum the caller may read has that id.	ErrorResponse
500	The database could not be read.	ErrorResponse

PATCH/api/forums/{forum_id} Bearer token

Rename, describe, archive or restore a forum

Changes a forum's name or description, or archives it — its discussions stay readable, but nobody posts, replies or edits until it is restored. Requires forums:write over its department.

Parameters

Name	In	Type	Required	Description
forum_id	path	string (uuid)	yes	UUID id of the forum.

Request body

application/jsonrequiredUpdateForumRequest

Field	Type	Required	Description
name	string	no	Unique within the department, ignoring case. 1–120 characters
description	string \| null	no	Send null or empty to clear the description. at most 1000 characters
archived	boolean	no	True archives the forum — its discussions stay readable, but nobody posts, replies or edits; false restores it.

Field

Type

Required

Description

name

string

Unique within the department, ignoring case.

1–120 characters

description

string | null

Send null or empty to clear the description.

at most 1000 characters

archived

boolean

True archives the forum — its discussions stay readable, but nobody posts, replies or edits; false restores it.

Responses

Status	Description	Body
200	The forum, as changed.	Forum
400	The request body failed validation.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller does not hold forums:write over the forum's department.	ErrorResponse
404	No forum the caller may read has that id.	ErrorResponse
409	The department already has a forum of that name.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

DELETE/api/forums/{forum_id} Bearer token

Delete a forum

Permanently deletes a forum with every discussion, reply and link in it. Archiving (PATCH) is the reversible way to close one. Requires forums:delete over its department.

Parameters

Name	In	Type	Required	Description
forum_id	path	string (uuid)	yes	UUID id of the forum.

Responses

Status	Description	Body
204	The forum and everything in it are gone.	—
401	The access token is missing or invalid.	ErrorResponse
403	The caller does not hold forums:delete over the forum's department.	ErrorResponse
404	No forum the caller may read has that id.	ErrorResponse
500	The database could not be reached, or the delete failed.	ErrorResponse

PATCH/api/forum-topics/{topic_id}/moderation Bearer token

Pin or lock a forum discussion

Pins a discussion to the top of its forum or unpins it, and locks it — only moderators may then reply, and nobody may edit — or unlocks it. Requires forums:moderate over the discussion's department.

Parameters

Name	In	Type	Required	Description
topic_id	path	string (uuid)	yes	UUID id of the discussion.

Request body

application/jsonrequiredForumTopicModerationRequest

Field	Type	Required	Description
pinned	boolean	no	True pins the discussion to the top of its board; false unpins it.
locked	boolean	no	True locks the discussion — only moderators may reply, nobody may edit; false unlocks it.

Responses

Status	Description	Body
200	The discussion, as moderated.	ForumTopic
400	The request body failed validation.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller does not hold forums:moderate over the forum's department.	ErrorResponse
404	No discussion the caller may read has that id.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

POST/api/forum-topics/{topic_id}/replies Bearer token

Reply to a forum discussion

Adds a reply to a discussion and moves it to the top of its forum. The caller must take part in the forum's department — a role in it or in one nested beneath it, or forums:moderate over it — and the forum must be open; only moderators may reply to a locked discussion.

Parameters

Name	In	Type	Required	Description
topic_id	path	string (uuid)	yes	UUID id of the discussion.

Request body

application/jsonrequiredCreateForumReplyRequest

Field	Type	Required	Description
body_markdown	string	yes	The reply. Markdown (GitHub-flavoured: tables, task lists, strikethrough). Stored as written and rendered sanitized: raw HTML is dropped, links may only use http, https or mailto, and images show as links. 1–10000 characters

Field

Type

Required

Description

body_markdown

string

yes

The reply. Markdown (GitHub-flavoured: tables, task lists, strikethrough). Stored as written and rendered sanitized: raw HTML is dropped, links may only use http, https or mailto, and images show as links.

1–10000 characters

Responses

Status	Description	Body
201	The new reply.	ForumReply
400	The request body failed validation.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller may read the forum (forums:read or forums:write) but not take part in it.	ErrorResponse
404	No discussion the caller may read has that id.	ErrorResponse
409	The forum is archived, or the discussion is locked and the caller does not moderate it.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

GET/api/forum-topics/{topic_id} Bearer token

Read one forum discussion

Reads a discussion with every reply, oldest first, the linked material the caller may open, and what the caller may do to the discussion and to each reply.

Parameters

Name	In	Type	Required	Description
topic_id	path	string (uuid)	yes	UUID id of the discussion.

Responses

Status	Description	Body
200	The discussion.	ForumTopic
401	The access token is missing or invalid.	ErrorResponse
404	No discussion the caller may read has that id.	ErrorResponse
500	The database could not be read.	ErrorResponse

PATCH/api/forum-topics/{topic_id} Bearer token

Edit a forum discussion

Changes a discussion's title, opening post or linked material, and marks it edited. Only its author may, while they take part in the forum's department and the discussion is unlocked; moderators cannot rewrite what someone else said. New links must be material the author can open; links they cannot open are kept.

Parameters

Name	In	Type	Required	Description
topic_id	path	string (uuid)	yes	UUID id of the discussion.

Request body

application/jsonrequiredUpdateForumTopicRequest

Field	Type	Required	Description
title	string	no	1–200 characters
body_markdown	string	no	The opening post. Markdown (GitHub-flavoured: tables, task lists, strikethrough). Stored as written and rendered sanitized: raw HTML is dropped, links may only use http, https or mailto, and images show as links. 1–20000 characters
resources	array of ForumResourceRef	no	The links, replacing the current ones. Links to material the caller cannot open themselves are kept whatever is sent, since they cannot see them to decide. at most 10 items

Field

Type

Required

Description

title

string

1–200 characters

body_markdown

string

1–20000 characters

resources

array of ForumResourceRef

The links, replacing the current ones. Links to material the caller cannot open themselves are kept whatever is sent, since they cannot see them to decide.

at most 10 items

Responses

Status	Description	Body
200	The edited discussion.	ForumTopic
400	The request body failed validation.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller is not the discussion's author, or no longer takes part in the forum's department.	ErrorResponse
404	No discussion the caller may read has that id, or a linked resource is not one they can open.	ErrorResponse
409	The discussion is locked, or the forum archived.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

DELETE/api/forum-topics/{topic_id} Bearer token

Delete a forum discussion

Permanently deletes a discussion with every reply and link. Holders of forums:delete over its department may delete any discussion; its author may delete it until someone else has replied.

Parameters

Name	In	Type	Required	Description
topic_id	path	string (uuid)	yes	UUID id of the discussion.

Responses

Status	Description	Body
204	The discussion and its replies are gone.	—
401	The access token is missing or invalid.	ErrorResponse
403	The caller is neither its author nor a holder of forums:delete over the forum's department.	ErrorResponse
404	No discussion the caller may read has that id.	ErrorResponse
409	The caller is its author, but other people have replied to it.	ErrorResponse
500	The database could not be reached, or the delete failed.	ErrorResponse

PATCH/api/forum-replies/{reply_id} Bearer token

Edit a forum reply

Replaces a reply's text and marks it edited. Only its author may, while they take part in the forum's department, the discussion is unlocked and the forum open.

Parameters

Name	In	Type	Required	Description
reply_id	path	string (uuid)	yes	UUID id of the reply.

Request body

application/jsonrequiredUpdateForumReplyRequest

Field	Type	Required	Description
body_markdown	string	yes	The reply. Markdown (GitHub-flavoured: tables, task lists, strikethrough). Stored as written and rendered sanitized: raw HTML is dropped, links may only use http, https or mailto, and images show as links. 1–10000 characters

Field

Type

Required

Description

body_markdown

string

yes

1–10000 characters

Responses

Status	Description	Body
200	The edited reply.	ForumReply
400	The request body failed validation.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller is not the reply's author, or no longer takes part in the forum's department.	ErrorResponse
404	No reply the caller may read has that id.	ErrorResponse
409	The discussion is locked, or the forum archived.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

DELETE/api/forum-replies/{reply_id} Bearer token

Delete a forum reply

Permanently deletes a reply. Its author may, and so may holders of forums:delete over the discussion's department.

Parameters

Name	In	Type	Required	Description
reply_id	path	string (uuid)	yes	UUID id of the reply.

Responses

Status	Description	Body
204	The reply is gone.	—
401	The access token is missing or invalid.	ErrorResponse
403	The caller is neither its author nor a holder of forums:delete over the forum's department.	ErrorResponse
404	No reply the caller may read has that id.	ErrorResponse
500	The database could not be reached, or the delete failed.	ErrorResponse