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

# Scripting API

> The Nextedy PLANNINGBOARD scripting API is a server-side REST interface embedded in the `PlanningBoardApiServlet`.

## Endpoint Overview

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/zUlmOSLBIQ0HyaAX/planningboard/diagrams/reference/api/scripting-api/diagram-1.svg?fit=max&auto=format&n=zUlmOSLBIQ0HyaAX&q=85&s=bc2ed3779c8fb1df441d531d630c95ae" alt="Tree of the Planningboard REST Servlet endpoints: GET /api/data, POST /planningboard_license, POST /api/data, POST /capacity, POST /planservice/fetchNewPlanParams, and POST /planservice/createPlan" width="900" height="340" data-path="planningboard/diagrams/reference/api/scripting-api/diagram-1.svg" />
</Frame>

***

## Data Retrieval

### `GET /api/data`

Retrieves all Planningboard data for the current board context, including work items and Plan membership information.

| Parameter          | Type    | Required        | Description                                                   |
| ------------------ | ------- | --------------- | ------------------------------------------------------------- |
| (query parameters) | Various | See application | Parameters determine which project and Plan scope is queried. |

**Date format:** All date values in the response use the format `dd-MM-yyyy HH:mm`.

**Response structure:**

```json theme={null}
{
  "items": [
    {
      "id": "<taskId>",
      "<fieldName>": "<value>"
    }
  ]
}
```

The response contains a top-level `items` array. Each element represents a work item (card) with its field values. Field names and their exact keys depend on the board configuration.

<Info title="Verify in application">
  The complete set of query parameters accepted by `GET /api/data` and the full response schema (all field names, pagination, and filtering behavior) require verification against the live application. The above reflects the confirmed structure from source context only.
</Info>

***

## Work Item Updates

### `POST /api/data` — Bulk Update

Updates one or more work items in a single request. Items are identified by their task IDs, and each field to update is passed as a separate request parameter.

**Parameter naming convention:** `{taskId}_{fieldName}`

For example, to update the `status` field of work item `WI-42`, pass:

```text theme={null}
WI-42_status=inProgress
```

Multiple work items can be updated in the same request by including parameters for each item.

| Parameter                       | Type   | Description                                                         |
| ------------------------------- | ------ | ------------------------------------------------------------------- |
| `ids`                           | String | Comma-separated list of task IDs to update. Example: `WI-42,WI-43`  |
| `{taskId}_{fieldName}`          | String | Field value for the named field on the named task.                  |
| `{taskId}_!nativeeditor_status` | String | Control parameter. Set to `deleted` to delete the item (see below). |

**Example request parameters:**

```text theme={null}
ids=WI-42,WI-43
WI-42_status=inProgress
WI-43_priority=high
```

***

### Work Item Deletion via `_!nativeeditor_status`

To delete a work item, include its ID in the `ids` parameter and set the special control parameter `{taskId}_!nativeeditor_status` to `deleted`.

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

<Warning title="Deletion is permanent">
  Deleting a work item via `_!nativeeditor_status=deleted` permanently removes the item. This operation cannot be undone through the API.
</Warning>

***

## Capacity Management

### `POST /capacity`

Sets the capacity value for a specific Plan within a project. Capacity values appear in the [capacity bar](/planningboard/reference/widget-parameters/capacity-parameters) displayed per swimlane.

**Request body (JSON):**

```json theme={null}
{
  "project": "<projectId>",
  "plan": "<planId>/<planName>",
  "capacity": <numericValue>
}
```

| Field      | Type   | Required | Description                                                                    |
| ---------- | ------ | -------- | ------------------------------------------------------------------------------ |
| `project`  | String | Yes      | The Polarion project ID.                                                       |
| `plan`     | String | Yes      | Plan identifier in the format `planId/planName`. Both components are required. |
| `capacity` | Number | Yes      | The capacity value to set for this Plan.                                       |

**Response:**

Returns a success or error response. The exact structure of the response object requires verification against the live application.

<Info title="Verify in application">
  The success and error response field names for `POST /capacity` are not fully specified in the available context. Verify the exact response shape against the live application before building integrations.
</Info>

<Warning title="Whitespace sensitivity">
  Capacity configuration parameters are whitespace-sensitive. Ensure no leading or trailing spaces appear in the `project`, `plan`, or `capacity` field values.
</Warning>

***

## Plan Management

### `POST /planservice/fetchNewPlanParams`

Retrieves the parameters required to create new Plans. Call this endpoint first to obtain valid `planParams` values before calling `createPlan`.

**Request body:** A `parametersRequest` JSON object. The exact structure depends on your board and project configuration.

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

**Response:** Returns a plan parameters object for use in the `createPlan` request. The exact fields in the returned parameters depend on your Plan configuration.

<Info title="Verify in application">
  The fields within `parametersRequest` and the structure of the returned plan parameters object require verification against the live application. These depend on your project's Plan type configuration.
</Info>

***

### `POST /planservice/createPlan`

Creates one or more new Plans based on the parameters retrieved from `fetchNewPlanParams`. Bulk creation is supported by providing an array of plan parameter objects.

**Request body:**

```json theme={null}
{
  "planParams": [
    {
      "<paramKey>": "<paramValue>"
    }
  ]
}
```

| Field        | Type  | Required | Description                                                                                                                   |
| ------------ | ----- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `planParams` | Array | Yes      | Array of `PlanParameters` objects. Provide one element per Plan to create. Multiple Plans can be created in a single request. |

<Info title="Verify in application">
  The individual fields within each `PlanParameters` element depend on the response from `fetchNewPlanParams`. Do not hard-code parameter names without first calling that endpoint for your environment.
</Info>

***

## License Status

### `POST /planningboard_license`

Returns the current Planningboard license status. Useful for diagnostics or for conditionally enabling features in integrations.

**Response structure (`LicenseResponse`):**

```json theme={null}
{
  "isMaintenanceExpired": false,
  "status": "<licenseStatus>",
  "message": "<humanReadableMessage>",
  "email": "<registeredEmail>",
  "product": "<productName>"
}
```

| Field                  | Type    | Description                                                      |
| ---------------------- | ------- | ---------------------------------------------------------------- |
| `isMaintenanceExpired` | Boolean | `true` if the maintenance period has expired; `false` otherwise. |
| `status`               | String  | Machine-readable license status code.                            |
| `message`              | String  | Human-readable status description.                               |
| `email`                | String  | Email address associated with the license registration.          |
| `product`              | String  | Product name as recorded in the license.                         |

***

## Data Model

The following data model structures are returned or consumed by the API. Field names are as confirmed from source context.

### Item Object

Returned by `GET /api/data` and by the internal `updateItem` service method after a successful update.

| Field             | Type    | Description                                                                              |
| ----------------- | ------- | ---------------------------------------------------------------------------------------- |
| `id`              | String  | The work item identifier.                                                                |
| Additional fields | Various | Work item field values. Exact field names depend on the board and project configuration. |

### Data Object

Returned by `GET /api/data`.

| Field   | Type          | Description                                                      |
| ------- | ------------- | ---------------------------------------------------------------- |
| `items` | Array of Item | The list of work items (cards) matching the current board query. |

***

## Configuration Example

The following example illustrates a typical sequence of API calls to update work item planning assignments on the board:

**Step 1 — Retrieve board data**

```text theme={null}
GET /api/data?<boardQueryParameters>
```

**Step 2 — Move a card to a new Plan (bulk update)**

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

ids=WI-42
WI-42_planId=SPRINT-7
```

**Step 3 — Set capacity for the target Plan**

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

{
  "project": "MyProject",
  "plan": "SPRINT-7/Sprint 7",
  "capacity": 40
}
```

***

## Related Reference

* [Widget Parameters](/planningboard/reference/widget-parameters/index) — per-instance configuration options that control what the board queries and displays
* [Capacity Parameters](/planningboard/reference/widget-parameters/capacity-parameters) — widget parameters related to capacity bars and normalization
* [Scripting Properties](/planningboard/reference/configuration-properties/scripting-properties) — server-side configuration properties for scripting behavior
* [Item Script API](/planningboard/reference/api/item-script-api) — scripting API for individual work item operations
* [Config Script API](/planningboard/reference/api/config-script-api) — scripting API for board configuration
* [Data Script API](/planningboard/reference/api/data-script-api) — scripting API for data access and transformation
* [REST API](/planningboard/reference/api/rest-api) — full REST API reference

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

  * Planningboard: Customizable Statistics and Capacity Indicators

  **Source Code**

  * `PlanningBoardApiServlet.java`
</Accordion>