REST API Reference

Complete documentation of all REST API endpoints provided by Product Roadmap Pro. All endpoints use the roadmap/v1 namespace and follow WordPress REST API conventions.

Time to read: 15 minutes

Authentication

Some endpoints require authentication. The table below each endpoint shows the required capability.

Public — No authentication needed
edit_posts — Requires Editor role or higher
manage_options — Requires Administrator role

Authenticate using one of these methods:

Method	How to Use
Cookie + Nonce	Send the `X-WP-Nonce` header with a valid nonce and include your `wordpressloggedin_*` cookie
Application Password	Use HTTP Basic Auth with your WordPress username and an application password
OAuth / JWT	If you have an OAuth or JWT plugin installed, follow its authentication flow

Getting a Nonce

When logged into WordPress admin, use the browser console:

wpApiSettings.nonce

Or generate one in PHP:

wp_create_nonce( 'wp_rest' );

Products

List All Products

GET /wp-json/roadmap/v1/products

Auth: Public

Returns all registered roadmap products.

Response:

[
  {
    "id": 5,
    "name": "Mobile App",
    "slug": "mobile-app",
    "description": "iOS and Android application",
    "count": 24
  }
]

Get Single Product

GET /wp-json/roadmap/v1/products/{id}

Auth: Public

Parameter	Type	Description
`id`	int	Product term ID

Items

List Items

GET /wp-json/roadmap/v1/items

Auth: Public

Retrieve a paginated list of roadmap items. This is the main endpoint used by the frontend app.

Parameter	Type	Default	Description
`product`	string	—	Product slug to filter by (required)
`status`	string	(all)	Status taxonomy slug
`category`	string	(all)	Category taxonomy slug
`page`	int	1	Page number
`per_page`	int	100	Items per page

Response:

{
  "items": [
    {
      "id": 123,
      "title": "Dark Mode Support",
      "content": "<p>Full description...</p>",
      "excerpt": "Short summary...",
      "votes": 14,
      "comment_count": 3,
      "priority": "high",
      "progress": 60,
      "target_date": "2026-06-01",
      "status": [{ "id": 5, "name": "In Progress", "slug": "in-progress" }],
      "categories": [],
      "product": [{ "id": 3, "name": "Mobile App", "slug": "mobile-app" }],
      "user_voted": 1,
      "link": "https://yoursite.com/roadmap_item/dark-mode/"
    }
  ],
  "total": 42,
  "pages": 5,
  "current_page": 1
}

Each item includes: id, title, content, excerpt, author, date, modified, votes, commentcount, priority, progress, targetdate, completionnotes, externallink, startdate, enddate, effortestimate, githubissue, status, categories, product, user_voted, link.

Create Item

POST /wp-json/roadmap/v1/items

Auth: edit_posts

Create a new roadmap item.

Request body:

{
  "title": "New Feature Request",
  "content": "Detailed description of the feature",
  "status": "planned",
  "priority": "high",
  "product": "mobile-app"
}

Field	Type	Required	Description
`title`	string	Yes	Item title
`content`	string	Yes	Full description (HTML allowed)
`status`	string	No	Status slug (default: `planned`)
`category`	string	No	Category slug
`priority`	string	No	`low`, `medium`, `high`, or `critical` (default: `medium`)
`target_date`	string	No	Target date (YYYY-MM-DD)
`progress`	int	No	Progress percentage (0-100)
`product`	string	No	Product slug
`start_date`	string	No	Start date for timeline
`end_date`	string	No	End date for timeline
`external_link`	string	No	URL to external tracker
`effort_estimate`	string	No	Effort estimate value
`github_issue`	string	No	GitHub issue URL

Response: 201 with the full item object.

Update Item

PUT /wp-json/roadmap/v1/items/{id}

Auth: edit_posts

Update a roadmap item’s status, title, or meta fields. All fields are optional — only include what you want to change.

Parameter	Type	Description
`id`	int	Roadmap item post ID

Request body:

{
  "status": "in-progress",
  "title": "Updated title",
  "progress": 50
}

Accepts the same fields as Create Item, all optional.

Delete Item

DELETE /wp-json/roadmap/v1/items/{id}

Auth: edit_posts

Permanently delete a roadmap item.

Parameter	Type	Description
`id`	int	Roadmap item post ID

Response:

{
  "success": true
}

Reorder Items

POST /wp-json/roadmap/v1/items/reorder

Auth: edit_posts

Update an item’s status and position. Used by the drag-and-drop feature when moving items between columns.

Request body:

{
  "item_id": 123,
  "new_status": "in-progress",
  "new_position": 2
}

Merge Items

POST /wp-json/roadmap/v1/items/merge

Auth: edit_posts

Merge a duplicate item into a target item. Transfers votes (deduplicates votes from the same user or IP) and reassigns comments. The source item is trashed after merge.

Request body:

{
  "source_id": 456,
  "target_id": 123
}

Response:

{
  "success": true,
  "message": "Successfully merged \"Feature A\" into \"Feature B\".",
  "source_id": 456,
  "target_id": 123,
  "target": {
    "id": 123,
    "title": "Feature B",
    "vote_count": 22,
    "edit_link": "https://..."
  }
}

Voting

Submit Vote

POST /wp-json/roadmap/v1/vote

Auth: Voting must be enabled. Logged-in users can always vote. Guests can vote if guest voting is enabled in settings.

Submit or change a vote on a roadmap item. Each user (or guest IP) can have one vote per item.

Request body:

{
  "item_id": 123,
  "vote_value": 1
}

Field	Type	Required	Description
`item_id`	int	Yes	The roadmap item to vote on
`vote_value`	int	No	`1` (upvote), `-1` (downvote), or `0` (remove vote). Default: `1`

Response:

{
  "success": true,
  "vote_count": 14
}

Comments

Post Comment

POST /wp-json/roadmap/v1/comment

Auth: Must be logged in. Comments must be enabled in settings.

Request body:

{
  "item_id": 123,
  "content": "This would be a great addition!"
}

Response: 201

{
  "success": true,
  "comment_id": 55,
  "message": "Comment added successfully"
}

List Comments

GET /wp-json/roadmap/v1/items/{id}/comments

Auth: Public

Retrieve all comments for a roadmap item.

Parameter	Type	Description
`id`	int	Roadmap item post ID

Response:

[
  {
    "id": 55,
    "content": "This would be a great addition!",
    "author": 1,
    "author_name": "Jane Doe",
    "author_avatar": "https://...",
    "date": "2026-03-01 14:30:00",
    "formatted_date": "March 1, 2026"
  }
]

Suggestions

Submit Suggestion

POST /wp-json/roadmap/v1/suggest

Auth: Suggestions must be enabled. User must be logged in (for guest suggestions, use the guest-suggest endpoint instead).

Submit a new feature suggestion. The suggestion is saved as a pending roadmap item unless auto-approve is enabled in settings.

Request body:

{
  "title": "Add dark mode",
  "description": "A dark theme option for nighttime use",
  "category": "ui-improvements"
}

Field	Type	Required	Description
`title`	string	Yes	Suggestion title
`description`	string	Yes	Detailed description
`category`	string	No	Category taxonomy slug

Response:

{
  "success": true,
  "message": "Thank you for your suggestion!",
  "id": 101
}

Stats

Get Statistics

GET /wp-json/roadmap/v1/stats

Auth: Public

Retrieve aggregate statistics for the roadmap.

Response:

{
  "total_items": 87,
  "total_votes": 312,
  "total_comments": 54,
  "items_by_status": {
    "planned": { "name": "Planned", "count": 30 },
    "in-progress": { "name": "In Progress", "count": 12 },
    "completed": { "name": "Completed", "count": 45 }
  }
}

Settings

Get Settings

GET /wp-json/roadmap/v1/settings

Auth: Public

Retrieve public roadmap settings and the current user’s info (if logged in).

Response:

{
  "enable_voting": true,
  "allow_guest_voting": false,
  "enable_comments": true,
  "enable_suggestions": true,
  "items_per_page": 20,
  "statuses": [
    { "id": 5, "name": "Planned", "slug": "planned" }
  ],
  "categories": [],
  "products": [],
  "is_pro": true,
  "current_user": {
    "id": 1,
    "name": "Admin",
    "email": "admin@example.com",
    "capabilities": ["roadmap_vote", "roadmap_comment"]
  }
}

The current_user field is null when not logged in.

Update Settings

POST /wp-json/roadmap/v1/settings

Auth: manage_options

Update roadmap settings.

Request body:

{
  "enable_voting": true,
  "allow_guest_voting": true,
  "enable_comments": true,
  "enable_suggestions": true,
  "items_per_page": 20
}

All fields are optional — include only the settings you want to change.

Advanced Filtering

The Pro addon adds these filter parameters to the items endpoint. Append them as query strings to any items request.

Parameter	Type	Description
`priority`	string	Filter by priority level: `critical`, `high`, `medium`, `low`
`assignee`	int	Filter by assigned user ID
`min_progress`	int	Minimum progress percentage (0-100)
`max_progress`	int	Maximum progress percentage (0-100)
`date_from`	string	Target date on or after this date (YYYY-MM-DD)
`date_to`	string	Target date on or before this date (YYYY-MM-DD)
`has_dependencies`	boolean	`1` for items with dependencies, `0` for items without
`product`	string	Comma-separated product slugs for multi-product filtering

Sorting

`orderby` Value	Description
`votes`	Sort by vote count
`progress`	Sort by progress percentage
`priority`	Sort by priority (critical > high > medium > low)
`target_date`	Sort by target date

All support order=ASC or order=DESC.

Example:

GET /wp-json/roadmap/v1/items?priority=high&min_progress=25&orderby=votes&order=DESC

Filter Presets

Save named filter combinations for quick reuse. Presets are stored per-user in a dedicated database table.

Saveable filter keys: status, category, product, priority, assignee, search. Date range and dependency filters cannot be saved in presets at this time.

Timeline

Get Timeline Data

GET /wp-json/roadmap/v1/timeline

Auth: Public

Returns roadmap items formatted for the Gantt chart timeline view.

Parameter	Type	Default	Description
`product`	string	(all)	Filter by product slug
`status`	string	(all)	Filter by status slug

Response:

[
  {
    "id": 123,
    "title": "Dark Mode Support",
    "status": "in-progress",
    "start_date": "2026-01-01",
    "end_date": "2026-03-15",
    "progress": 60,
    "assignee": {
      "id": 1,
      "name": "Jane Doe",
      "avatar": "https://..."
    },
    "dependencies": [456]
  }
]

Analytics

Get Analytics Data

GET /wp-json/roadmap/v1/analytics

Auth: edit_posts

Returns analytics data for a specified metric and time period.

Parameter	Type	Default	Description
`metric`	string	—	Metric type: `votes`, `progress`, or `engagement`
`period`	string	`week`	Time period: `day`, `week`, `month`, `year`
`product`	string	(all)	Filter by product slug
`start_date`	string	—	Custom start date (YYYY-MM-DD)
`end_date`	string	—	Custom end date (YYYY-MM-DD)

Get Analytics Overview

GET /wp-json/roadmap/v1/analytics/overview

Auth: edit_posts

Returns the analytics dashboard overview with summary statistics.

Get Trends

GET /wp-json/roadmap/v1/analytics/trends

Auth: edit_posts

Returns trend data over time.

Parameter	Type	Default	Description
`period`	string	`30days`	Time period: `7days`, `30days`, `90days`, `1year`

Get Popular Items

GET /wp-json/roadmap/v1/analytics/popular-items

Auth: edit_posts

Returns the most popular roadmap items ranked by votes and engagement.

Get Recent Activity

GET /wp-json/roadmap/v1/analytics/recent-activity

Auth: edit_posts

Returns a feed of recent roadmap activity (votes, comments, status changes).

Get Charts Data

GET /wp-json/roadmap/v1/analytics/charts

Auth: edit_posts

Returns chart-ready data for the analytics dashboard visualizations.

Track Event

POST /wp-json/roadmap/v1/analytics/track

Auth: Public

Record a frontend analytics event (e.g., page view). This is the only public analytics endpoint — all other analytics endpoints require the edit_posts capability.

Request body:

{
  "event": "item_viewed",
  "item_id": 123,
  "metadata": {}
}

Custom Fields

List Field Definitions

GET /wp-json/roadmap/v1/custom-fields

Auth: Public

Returns all defined custom field configurations. Custom field values are also included in every item response under a custom_fields key.

Response:

[
  {
    "key": "effort",
    "label": "Effort Points",
    "type": "number",
    "required": false,
    "show_in_list": true
  }
]

Create Field

POST /wp-json/roadmap/v1/custom-fields

Auth: manage_options

Create a new custom field definition.

Request body:

{
  "key": "effort",
  "label": "Effort Points",
  "type": "number",
  "required": false,
  "show_in_list": true
}

Field	Type	Required	Description
`key`	string	Yes	Unique identifier (letters, numbers, underscores)
`label`	string	Yes	Display label in the admin
`type`	string	Yes	Field type: text, textarea, select, number, date, url
`options`	array	For select	Dropdown choices as strings
`required`	bool	No	Whether the field must be filled
`showinlist`	bool	No	Show in admin list table column

Update Field

PUT /wp-json/roadmap/v1/custom-fields/{key}

Auth: manage_options

Update an existing field definition. The key in the URL identifies which field to update.

Delete Field

DELETE /wp-json/roadmap/v1/custom-fields/{key}

Auth: manage_options

Remove a field definition. Existing field values on posts are not deleted — they remain as post meta but are no longer displayed.

Guest Suggestions

Submit Guest Suggestion

POST /wp-json/roadmap/v1/guest-suggest

Auth: None (public)

Submit a suggestion without logging in. Only works if guest suggestions are enabled in settings.

Request body:

{
  "title": "Dark mode support",
  "description": "Add a dark theme option",
  "name": "Jane Doe",
  "email": "jane@example.com"
}

List Guest Suggestions

GET /wp-json/roadmap/v1/guest-suggestions

Auth: edit_posts

Returns pending guest suggestions for admin review.

Approve Guest Suggestion

POST /wp-json/roadmap/v1/guest-suggestions/{id}/approve

Auth: edit_posts

Converts the guest suggestion into a published roadmap item.

Reject Guest Suggestion

POST /wp-json/roadmap/v1/guest-suggestions/{id}/reject

Auth: edit_posts

Rejects and trashes the guest suggestion.

Webhooks

List Webhooks

GET /wp-json/roadmap/v1/webhooks

Auth: manage_options

Returns all configured webhooks (secrets are masked) and the last 20 delivery log entries.

Create Webhook

POST /wp-json/roadmap/v1/webhooks

Auth: manage_options

Request body:

{
  "url": "https://example.com/webhook-receiver",
  "secret": "my-secure-secret",
  "events": ["status_changed", "vote_submitted"]
}

Field	Type	Required	Description
`url`	string	Yes	The endpoint URL to receive events
`secret`	string	Yes	Shared secret for HMAC-SHA256 signature verification
`events`	array	Yes	Event types to subscribe to

Available events: statuschanged, votesubmitted, commentsubmitted, suggestionsubmitted, guestsuggestionsubmitted

Delete Webhook

DELETE /wp-json/roadmap/v1/webhooks/{index}

Auth: manage_options

Remove the webhook at the specified array index.

Test Webhook

POST /wp-json/roadmap/v1/webhooks/test

Auth: manage_options

Send a test ping event to verify your endpoint.

Request body:

{
  "url": "https://example.com/webhook-receiver",
  "secret": "my-secure-secret"
}

Changelog

List Changelog Entries

GET /wp-json/roadmap/v1/changelog

Auth: Public

Parameter	Type	Default	Description
`product`	string	(all)	Filter by product slug
`per_page`	int	10	Entries per page
`page`	int	1	Page number

Response:

{
  "entries": [
    {
      "id": 123,
      "version": "2.0.0",
      "date": "2026-01-15",
      "product": "mobile-app",
      "items": [
        { "type": "new-feature", "description": "Added dark mode" },
        { "type": "fix", "description": "Fixed login redirect" }
      ]
    }
  ],
  "total": 12,
  "pages": 2
}

Get Single Entry

GET /wp-json/roadmap/v1/changelog/{id}

Auth: Public

Returns a single changelog entry by post ID.

Filter Presets

Filter presets let users save named filter combinations for quick reuse. Presets are stored per-user — each user can only see and manage their own presets.

List Filter Presets

GET /wp-json/roadmap/v1/filter-presets

Auth: Logged in (any role)

Returns the current user’s saved filter presets.

Response:

[
  {
    "id": 7,
    "name": "High Priority Active",
    "filters": {
      "status": "in-progress",
      "priority": "high"
    },
    "is_default": false,
    "created_at": "2026-02-15 10:30:00"
  }
]

Create Filter Preset

POST /wp-json/roadmap/v1/filter-presets

Auth: Logged in (any role)

Save a named filter configuration for reuse.

Request body:

{
  "name": "High Priority Active",
  "filters": {
    "status": "in-progress",
    "priority": "high",
    "assignee": "42"
  }
}

Saveable filter keys: status, category, product, priority, assignee, search. Date range and dependency filters cannot be saved in presets.

Response: 201

{
  "success": true,
  "id": 7
}

Delete Filter Preset

DELETE /wp-json/roadmap/v1/filter-presets/{id}

Auth: Logged in (any role)

Delete one of your saved filter presets. You can only delete presets you created.

Parameter	Type	Description
`id`	int	Filter preset ID

Response:

{
  "success": true
}

User Profiles

Get User Activity

GET /wp-json/roadmap/v1/users/{id}/activity

Auth: Public

Retrieve a user’s roadmap activity including votes cast, items submitted, and comments made.

Parameter	Type	Description
`id`	int	WordPress user ID
`per_page`	int	Items per page (default: 20, max: 100)
`page`	int	Page number (default: 1)

Response:

{
  "user": {
    "id": 5,
    "name": "Jane Doe",
    "avatar": "https://..."
  },
  "stats": {
    "votes_cast": 12,
    "items_submitted": 3,
    "comments_made": 7
  },
  "voted_items": [
    {
      "item_id": 10,
      "title": "Dark Mode",
      "vote_value": 1,
      "voted_at": "2026-02-15",
      "url": "https://..."
    }
  ],
  "submitted_items": [
    {
      "id": 11,
      "title": "API Improvements",
      "date": "2026-01-20",
      "url": "https://...",
      "votes": 5
    }
  ],
  "comments": [
    {
      "id": 22,
      "item_id": 10,
      "item_title": "Dark Mode",
      "excerpt": "This would be great for...",
      "date": "2026-02-10"
    }
  ]
}

Get Top Contributors

GET /wp-json/roadmap/v1/users/top-contributors

Auth: Public

Retrieve the most active contributors ranked by vote count.

Parameter	Type	Default	Description
`limit`	int	10	Number of users to return (max: 100)

Response:

[
  {
    "user_id": 5,
    "name": "Jane Doe",
    "avatar": "https://...",
    "vote_count": 42
  }
]

Export

Export Items

GET /wp-json/roadmap/v1/export

Auth: export (Administrator role)

Export roadmap items as a CSV file download.

Parameter	Type	Default	Description
`product`	string	(all)	Filter by product slug
`status`	string	(all)	Filter by status
`format`	string	`csv`	Export format (`csv` supported; `pdf` planned)

CSV columns: ID, Title, Description, Status, Category, Priority, Target Date, Votes, Comments, Progress, Assignee.

Changelog (Additional Endpoints)

The free plugin provides GET /changelog and GET /changelog/{id} (documented above). The Pro addon adds these additional endpoints.

List Changelog Products

GET /wp-json/roadmap/v1/changelog/products

Auth: Public

Returns all products that have at least one published changelog entry.

Response:

[
  {
    "id": 3,
    "name": "Mobile App",
    "slug": "mobile-app",
    "changelog_count": 8
  }
]

Get Changelog by Product

GET /wp-json/roadmap/v1/changelog/by-product/{product}

Auth: Public

Retrieve paginated changelog entries for a specific product.

Parameter	Type	Default	Description
`product`	string	—	Product slug (URL parameter)
`limit`	int	10	Entries per page
`page`	int	1	Page number

Response:

{
  "product": {
    "id": 3,
    "name": "Mobile App",
    "slug": "mobile-app"
  },
  "changelogs": [],
  "total": 25,
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 25,
    "total_pages": 3
  }
}

Error Responses

All endpoints return standard WordPress REST API error responses:

{
  "code": "rest_forbidden",
  "message": "Sorry, you are not allowed to do that.",
  "data": {
    "status": 403
  }
}

Status Code	Meaning
200	Success
201	Created
400	Bad request (missing or invalid parameters)
401	Not authenticated
403	Authenticated but not authorized
404	Resource not found
500	Server error

Next Steps

Hooks & Filters Reference — Extend behavior with WordPress hooks
Customization Guide — Common customization patterns
Webhooks & Integrations — External service connections

← Hooks & Filters Reference | Customization Guide →