REST API - Nextedy Documentation

The REST API surface described here is derived from source code analysis. Endpoint paths, parameter names, and response structures should be verified against the running Planningboard instance. Some details — particularly exact error codes and optional fields — may differ between versions.

Base URL

All Planningboard API endpoints are relative to the Polarion server base. The admin API base path (apiBase) is set dynamically by the servlet at runtime.

POST /planningboard_license
GET  /api/data
POST /api/data           (bulk task update)
POST /capacity
POST /planservice/fetchNewPlanParams
POST /planservice/createPlan

Endpoints

GET /api/data

Retrieves Planningboard data — the set of work items and Plans currently rendered on the board — as a JSON response. Request parameters

Name	Type	Required	Description
(board query parameters)	string	See application	Parameters controlling which Plans and work items are fetched. Derived from the board’s widget configuration at runtime.

Date format Dates in the response use the format dd-MM-yyyy HH:mm. Response Returns a JSON object containing an items array. Each item in the array represents a work item or Plan card.

{
  "items": [ ... ]
}

Item object fields

Field	Type	Description
`id`	string	Work item identifier
(additional fields)	See application	Field set depends on board configuration and Polarion field mapping

The full set of fields returned per item depends on the board’s widget parameter configuration. Verify the exact response schema against the live board.

POST /api/data — Bulk Task Update

Updates one or more work items in a single request. Task IDs and field values are submitted as form parameters using a specific naming convention. Parameter naming convention Each field update is submitted as a separate parameter following the pattern:

{taskId}_{fieldName}

For example, to update the status field of task WI-42:

WI-42_status=done

Special parameter: _!nativeeditor_status The _!nativeeditor_status parameter controls the operation type for each task:

Value	Behavior
`deleted`	Permanently deletes the task
(other / absent)	Updates field values for the task

Deletion example To delete task WI-42:

WI-42_!nativeeditor_status=deleted

When {taskId}_!nativeeditor_status=deleted is submitted, the item is permanently deleted from Polarion. This action cannot be undone from the board.

Bulk parameter format Multiple tasks can be updated in a single POST by providing parameters for each task. The ids parameter supplies a comma-separated list of task IDs to process:

Parameter	Type	Description
`ids`	string	Comma-separated list of task IDs to update (e.g. `WI-42,WI-43,WI-44`)
`{taskId}_{fieldName}`	string	Field value for the named field on the named task
`{taskId}_!nativeeditor_status`	string	Operation flag; set to `deleted` to delete the task

Response Returns the updated Item object for each processed task (update operations). Deletion operations return a confirmation. See application for exact response envelope.

POST /planningboard_license

Returns the current license status for the Planningboard installation. Request No request body parameters required. Response — LicenseResponse

Field	Type	Description
`isMaintenanceExpired`	boolean	`true` if the maintenance period has expired
`status`	string	License status identifier
`message`	string	Human-readable status message
`email`	string	License contact email address
`product`	string	Product identifier (value: `PLANNINGBOARD`)

Example response

{
  "isMaintenanceExpired": false,
  "status": "active",
  "message": "License is valid.",
  "email": "license@example.com",
  "product": "PLANNINGBOARD"
}

POST /capacity

Sets the capacity value for a specific Plan within a project. Request body (JSON)

Field	Type	Required	Description
`project`	string	Yes	Polarion project ID
`plan`	string	Yes	Plan reference in the format `planId/planName`
`capacity`	number	Yes	Capacity value to assign to the Plan

Example request body

{
  "project": "MyProject",
  "plan": "sprint-12/Sprint 12",
  "capacity": 40
}

Response Returns a success or error response. See application for exact response envelope structure.

The plan field uses the composite format planId/planName. Both parts are required. Verify the exact IDs against the Plans configured in your Polarion project.

POST /planservice/fetchNewPlanParams

Retrieves the parameters needed to create new Plans, based on a parameters request. Used to pre-populate the Plan creation form. Request body Submit a parametersRequest JSON object. The exact schema of parametersRequest depends on the Plan type and project configuration.

{
  "parametersRequest": { ... }
}

Response Returns a plan parameters object used to drive the createPlan endpoint. See application for exact field structure.

The parametersRequest schema and the returned plan parameters format are dependent on your Polarion project configuration and Plan types. Verify the exact structures in the running application.

POST /planservice/createPlan

Creates one or more new Plans based on provided plan parameters. Supports bulk creation in a single request. Request body Submit a planParams array, where each element is a PlanParameters object.

{
  "planParams": [
    { ... },
    { ... }
  ]
}

Bulk creation Provide multiple objects in the planParams array to create multiple Plans in one call.

The PlanParameters field structure is determined by the server-side model. Retrieve the required fields first using POST /planservice/fetchNewPlanParams, then submit the populated objects to this endpoint.

Data Flow Diagram

  Polarion Client / Browser
         |
         |  REST over HTTP
         v
  +----------------------------+
  |  PlanningBoardApiServlet   |
  |  (main entry point)        |
  +----------------------------+
         |
         +-----------> GET /api/data
         |               |
         |               v
         |         PlanningBoardDataService.getData()
         |               |
         |               v
         |         [ items[] JSON response ]
         |
         +-----------> POST /api/data (bulk update)
         |               |
         |               v
         |         PlanningBoardDataService.updateItem()
         |         PlanningBoardDataService.deleteItem()
         |
         +-----------> POST /capacity
         |               |
         |               v
         |         Sets capacity on Plan in project
         |
         +-----------> POST /planservice/fetchNewPlanParams
         |               |
         |               v
         |         Returns PlanParameters for new Plan form
         |
         +-----------> POST /planservice/createPlan
                         |
                         v
                   Creates Plan(s) in Polarion project

Admin Interface Properties

The following properties are set by the admin servlet and are relevant when integrating with or extending the Planningboard admin interface. These are not configurable by end users.

Property	Description
`productName`	Identifies the product as `PLANNINGBOARD` in all admin interfaces
`version`	Runtime version string; the `qualifier` segment is replaced with a timestamp for cache busting after updates
`apiBase`	Base URL path for all Planningboard admin API endpoints
`libBase`	Base URL path for Planningboard JavaScript and CSS library assets
`roleId`	Polarion role identifier required to access Planningboard features; must be granted to users during project setup
`docUrl`	External support documentation link displayed in the admin interface
`pricingUrl`	External pricing information link shown during license configuration
`versionUrl`	Remote endpoint the admin interface queries for the latest available Planningboard version
`changelogUrl`	External URL to the Planningboard release changelog, accessible from the admin interface

The roleId property defines which Polarion role grants access to Planningboard features. Administrators must assign this role to users during project setup. Refer to License Installation for the setup process.

Configuration Example

The following example shows a typical sequence for reading board data and updating a task via the REST API. Step 1 — fetch board data

GET /api/data?<board-query-params>

Response:

{
  "items": [
    { "id": "WI-100", "title": "Implement login screen", "status": "open" },
    { "id": "WI-101", "title": "Write unit tests", "status": "open" }
  ]
}

Step 2 — update a task field

POST /api/data
Content-Type: application/x-www-form-urlencoded

ids=WI-100&WI-100_status=in-progress

Step 3 — delete a task

POST /api/data
Content-Type: application/x-www-form-urlencoded

ids=WI-101&WI-101_!nativeeditor_status=deleted

Step 4 — set capacity for a Plan

POST /capacity
Content-Type: application/json

{
  "project": "MyProject",
  "plan": "sprint-12/Sprint 12",
  "capacity": 40
}

Scripting API — JavaScript scripting interface for board customization
Config Script API — Configuration-time scripting hooks
Data Script API — Data-layer scripting interface
Teams Service API — Teams service integration endpoints
Widget Parameters — Per-instance board configuration
Configuration Properties — System-wide administration properties

Sources

KB Articles

Planningboard: Customizable Statistics and Capacity Indicators

Source Code

PlanningBoardApiServlet.java
PlanningBoardViewServlet.java

​Base URL

​Endpoints

​GET /api/data

​POST /api/data — Bulk Task Update

​POST /planningboard_license

​POST /capacity

​POST /planservice/fetchNewPlanParams

​POST /planservice/createPlan

​Data Flow Diagram

​Admin Interface Properties

​Configuration Example

​Related Reference

Base URL

Endpoints

GET /api/data

POST /api/data — Bulk Task Update

POST /planningboard_license

POST /capacity

POST /planservice/fetchNewPlanParams

POST /planservice/createPlan

Data Flow Diagram

Admin Interface Properties

Configuration Example

Related Reference