Coming soon, suggestions and ticket proposals
The What's New modal separates published feature cards from the Coming soon roadmap. A roadmap item is curated platform content. A customer's suggestion stays private until a verified platform administrator approves it; approval publishes only the reviewed title and description, without the author's user or organization identity.
WHATS_NEW_ROADMAP_ENABLED defaults to true. With it disabled, roadmap routes are absent from served OpenAPI and roadmap tools are absent from remote and stdio MCP discovery. Existing feature cards and API-key resource catalogs keep their existing contracts. A cached tool call still meets the API's current flag and permission checks. Existing MCP documentation resource discovery follows its existing gates and is unchanged by the roadmap flag.
Human REST operations
All calls require authentication. Suggestions, voting and administration require a signed-in human session; API keys and user tokens cannot perform these actions.
| Operation | Route | Body or query |
|---|---|---|
| Read curated roadmap | GET /v1/roadmap | sort=votes or newest, optional status=coming_soon or shipped, limit 1–100, offset 0–10000 |
| Read my private suggestions | GET /v1/roadmap/suggestions/mine | None |
| Suggest an item | POST /v1/roadmap/suggestions | {orgId,title,description} |
| Add my vote | PUT /v1/roadmap/:id/vote | {orgId} |
| Remove my vote | DELETE /v1/roadmap/:id/vote | None |
| Read moderation queue | GET /v1/admin/roadmap | Item sort/status, limit, offset, optional suggestionStatus=pending, approved or rejected; pending suggestions are listed first |
| Add a curated item | POST /v1/admin/roadmap/items | {title,description,featureCardId?} |
| Edit a curated item | PATCH /v1/admin/roadmap/items/:id | Changed title, description or feature-card link |
| Ship an item | POST /v1/admin/roadmap/items/:id/ship | {featureCardId} |
| Review a suggestion | POST /v1/admin/roadmap/suggestions/:id/moderate | `{decision:"approve" |
Voting requires a current membership in the chosen organization. One account gets one vote per item across all organizations; repeat PUT/DELETE calls are idempotent. Only Coming soon items accept or release votes: a shipped item keeps the votes it shipped with, and DELETE returns 409. A vote counts, and shows as votedByMe, only while its voter still belongs to the organization recorded with it; a departed voter can vote again through a current organization, which moves the one vote there. Shipping links an item to a published feature card and preserves its accumulated vote count. Administrator operations use the existing verified platform-admin gate.
The curated feed returns {enabled:true,items,hasMore}. Each item has id, title, description, status, voteCount, votedByMe, featureCardId, publishedAt and createdAt. Aggregate counts are public to authenticated readers; author, organization and voter identities never appear in the feed. Agents receive votedByMe:false so their access does not disclose their owner's personal preferences.
Shipping and notifications
Creating or editing a Coming soon item can link it to a draft feature card through featureCardId. The card must have the everyone audience because the roadmap is global. Approving and publishing that linked draft automatically marks the roadmap item as shipped in the same transaction while the roadmap flag is enabled. The ordinary feature-card publication checks still apply. Discarding the draft clears its roadmap link and keeps the Coming soon item and its votes; an administrator can also clear the link with featureCardId:null.
For an already published feature card, use the explicit Ship operation instead of linking it through create or edit. The card must be published, have a publication sequence and use the everyone audience. An existing link must name that same card, and one card can belong to only one roadmap item. Shipping preserves the accumulated votes and closes further voting. Shipped items cannot be edited. Repeating Ship with the same card returns the existing result without sending another notification.
When an item first ships, eligible voters receive one in-app notification linking to What's New. This event sends no email, SMS, push or third-party message. It uses notification type user_reminder with data kind roadmap_item_shipped and honors either corresponding mute setting. People who opted out of feature cards receive no shipment notification. The voter must still belong to the organization recorded with their vote, and that organization must be active; voters who departed that organization or whose organization is suspended are excluded. Item state, audit event and notification rows commit together.
Agent REST and MCP access
An org API key must explicitly name the existing issues resource scope to read roadmap content or prepare a proposal. Legacy keys without resource families do not opt in. Reusing the scope keeps feature-off grant schemas unchanged. The enrolling member must still belong to the key's organization, and project proposals require their current issue:create permission within that organization, bounded by the key's role ceilings. Runner keys, user-scoped keys and user tokens are refused. Revocation, pauses and grant changes take effect on the next REST dispatch.
Both MCP servers register the same four tools only after the API accepts their own credential:
| Tool | Parameters | Result |
|---|---|---|
list_roadmap | Optional limit, offset, sort | Curated Coming soon and shipped feed |
get_top_voted_roadmap | Optional limit, offset | Coming soon items sorted by aggregate votes |
suggest_roadmap_item | orgId, title, description, requestedByUser:true | Private suggestion for the key owner with an explicit suggestion grant |
propose_roadmap_ticket | projectId, itemId | One human-reviewable ticket draft |
propose_roadmap_ticket calls POST /v1/projects/:projectId/roadmap/:itemId/ticket-proposal. The key also needs write, as this POST follows the existing API method-scope gate. It returns {roadmapItemId,projectId,reviewRequired:true,drafts:[TicketDraft]} using the existing ticket draft contract. The source must be a curated Coming soon item. Pending or rejected suggestions, missing items and shipped items cannot be used.
A proposal is deterministic and writes no state: it calls no AI provider, creates no issue, assigns nobody and schedules nothing. Repeating or concurrently requesting it creates no duplicates. A human reviews or edits the returned draft and may then use the existing session-only POST /v1/projects/:projectId/issues/bulk-create flow. Roadmap content and proposal text are untrusted data; MCP results label them accordingly.
Stdio profiles use their existing issues tool group. Each profile independently probes the API with its own key, and every tool call keeps that profile's credential. Discovery from one profile never authorizes another. The existing write-confirmation preference also applies to proposal calls because the route uses POST.
Suggestions requested from an agent
The suggest_roadmap_item MCP tool files a private pending suggestion when the key owner asks. Grant the organization key roadmap_suggestions, issues, and write. The REST route is POST /v1/roadmap/agent-suggestions with orgId, title, description (why), and requestedByUser: true. The submitting account is the key owner; the audit records the API key. Agents cannot vote or moderate, and cannot supply another user identity.
The default-on platform setting whatsNew.roadmapEnabled disables Coming Soon and its REST/MCP routes immediately when set false. The environment switch WHATS_NEW_ROADMAP_ENABLED=false also disables registration. Linked cards have status coming_soon, no publication sequence, and an authenticated screenshot; approving shipment moves them to published and allocates their sequence at that moment.
Shipment approval keeps linked state consistent even when Coming Soon is switched off. In that case it creates no roadmap voter notification.