> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API

> The Nextedy PLANNINGBOARD REST API exposes endpoints for retrieving board data, updating work items, managing capacity, and interacting with Plans programmatically.

<Info title="Verify in application">
  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.
</Info>

***

## 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.

```text theme={null}
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.

```json theme={null}
{
  "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 |

<Info title="Verify in application">
  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.
</Info>

***

### 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:

```text theme={null}
{taskId}_{fieldName}
```

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

```text theme={null}
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`:

```text theme={null}
WI-42_!nativeeditor_status=deleted
```

<Warning title="Deletion is permanent">
  When `{taskId}_!nativeeditor_status=deleted` is submitted, the item is permanently deleted from Polarion. This action cannot be undone from the board.
</Warning>

**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**

```json theme={null}
{
  "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**

```json theme={null}
{
  "project": "MyProject",
  "plan": "sprint-12/Sprint 12",
  "capacity": 40
}
```

**Response**

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

<Tip title="Plan format">
  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.
</Tip>

***

### 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.

```json theme={null}
{
  "parametersRequest": { ... }
}
```

**Response**

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

<Info title="Verify in application">
  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.
</Info>

***

### 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.

```json theme={null}
{
  "planParams": [
    { ... },
    { ... }
  ]
}
```

**Bulk creation**

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

<Info title="Verify in application">
  The `PlanParameters` field structure is determined by the server-side model. Retrieve the required fields first using [POST /planservice/fetchNewPlanParams](#post-planservicefetchnewplanparams), then submit the populated objects to this endpoint.
</Info>

***

## Data Flow Diagram

```text theme={null}
  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                          |

<Note title="Role assignment">
  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](/planningboard/getting-started/licensing) for the setup process.
</Note>

***

## 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**

```text theme={null}
GET /api/data?<board-query-params>
```

Response:

```json theme={null}
{
  "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**

```text theme={null}
POST /api/data
Content-Type: application/x-www-form-urlencoded

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

**Step 3 — delete a task**

```text theme={null}
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**

```text theme={null}
POST /capacity
Content-Type: application/json

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

***

## Related Reference

* [Scripting API](/planningboard/reference/api/scripting-api) — JavaScript scripting interface for board customization
* [Config Script API](/planningboard/reference/api/config-script-api) — Configuration-time scripting hooks
* [Data Script API](/planningboard/reference/api/data-script-api) — Data-layer scripting interface
* [Teams Service API](/planningboard/reference/api/teams-service-api) — Teams service integration endpoints
* [Widget Parameters](/planningboard/reference/widget-parameters/index) — Per-instance board configuration
* [Configuration Properties](/planningboard/reference/configuration-properties/index) — System-wide administration properties

<Accordion title="Sources">
  **KB Articles**

  * Planningboard: Customizable Statistics and Capacity Indicators

  **Source Code**

  * `PlanningBoardApiServlet.java`
  * `PlanningBoardViewServlet.java`
</Accordion>