Skip to main content
POST
Suggest a roadmap item

Authorizations

Authorization
string
header
required

The session token of a signed-in Plazza account, sent as Authorization: Bearer <token>.

Path Parameters

board
enum<string>
required

The board: hire for employers, talents for job seekers.

Available options:
hire,
talents
Example:

"hire"

Query Parameters

requestId
string<uuid>

Makes a retry safe: a request with the same id and content returns the resource the first one created.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Example:

"0f5e8c1e-7a8b-4c2d-9e1f-2a3b4c5d6e7f"

Body

application/json

A suggestion for the roadmap.

title
string
required

The title, 3 to 180 characters.

Maximum string length: 1000
Example:

"Swap shifts between employees"

body
string
required

The description in Markdown, up to 20,000 characters.

Maximum string length: 100000
Example:

"Let employees trade shifts, with a manager approving the swap."

kind
enum<string>
default:FEATURE

What the item is: a new feature, an improvement, a fix, or a design change.

Available options:
FEATURE,
ENHANCEMENT,
FIX,
DESIGN
Example:

"FEATURE"

tags
string[]

Up to 8 topics, of 1 to 40 characters each.

Maximum array length: 50
Maximum string length: 200
Example:
plans
string[]

Up to 8 plans it concerns, of 1 to 40 characters each.

Maximum array length: 50
Maximum string length: 200
Example:
area
string | null

The part of the product it concerns, up to 60 characters. Blank or null clears it.

Maximum string length: 500
Example:

"Scheduling"

followLanguageCode
enum<string> | null

To follow the item from the start, the language to be written to in.

Available options:
en,
fr
Example:

"fr"

displayName
string

The name shown with what you post. Kept with your first post or comment, and ignored after that: rename through your roadmap persona.

Maximum string length: 200
Example:

"Camille Tremblay"

Response

A suggestion or a planned change on a roadmap board.

A suggestion or a planned change on a roadmap board.

name
string
required

The item's resource name.

Example:

"roadmapBoards/hire/items/019a7c2e-4b1d-7c3a-9d4e-5f6a7b8c9d0e"

source
enum<string>
required

PLAZZA for a member’s suggestion; LINEAR for an item the Plazza team curates in Linear, where its content and status are managed.

Available options:
PLAZZA,
LINEAR
Example:

"PLAZZA"

slug
string
required

A readable form of the title, for URLs.

Example:

"swap-shifts-between-employees"

title
string
required

The title, in the language its author wrote it. Empty once withdrawn.

Example:

"Swap shifts between employees"

body
string
required

The description, in Markdown. Empty once withdrawn.

Example:

"Let employees trade shifts, with a manager approving the swap."

kind
enum<string>
required

What the item is: a new feature, an improvement, a fix, or a design change.

Available options:
FEATURE,
ENHANCEMENT,
FIX,
DESIGN
Example:

"FEATURE"

tags
string[]
required

Up to 8 topics.

Example:
plans
string[]
required

Up to 8 plans the item concerns.

Example:
area
string | null
required

The part of the product it concerns, if any.

Example:

"Scheduling"

status
enum<string>
required

Where the item stands in the workflow.

Available options:
BACKLOG,
PLANNED,
IN_PROGRESS,
SHIPPED,
DECLINED,
ARCHIVED
Example:

"PLANNED"

shipTime
string<date-time> | null
required

When it shipped. Null unless status is SHIPPED.

Example:

"2026-11-04T14:32:08.512Z"

state
enum<string>
required

PUBLISHED items are listed. Staff can UNPUBLISH one, its author can withdraw it, which erases its text but keeps the discussion, and staff can merge a duplicate into another item. The Linear sync SUSPENDED one while its issue can’t be read or left the Roadmap team.

Available options:
PUBLISHED,
UNPUBLISHED,
SUSPENDED,
WITHDRAWN,
MERGED
Example:

"PUBLISHED"

mergedInto
string | null
required

The resource name of the item a duplicate was merged into.

Example:

null

author
object | null
required

Who suggested it. Null for a curated item and once withdrawn.

Example:
voteCount
integer
required

How many people back it.

Required range: -9007199254740991 <= x <= 9007199254740991
Example:

42

commentCount
integer
required

How many comments it has, removed ones aside.

Required range: -9007199254740991 <= x <= 9007199254740991
Example:

7

etag
string
required

AIP-154: send it back to change the item, so a concurrent change is refused.

Example:

"\"3\""

createTime
string<date-time>
required

When it was suggested.

Example:

"2026-11-04T14:32:08.512Z"

updateTime
string<date-time>
required

When its content, status or state last changed.

Example:

"2026-11-04T14:32:08.512Z"

deleteTime
string<date-time> | null
required

AIP-164: when its author withdrew it. Null otherwise.

Example:

"2026-11-04T14:32:08.512Z"