---
title: "Public API"
canonical: "https://support.appfire.com/space/DLP/297634424/Public%20API"
format: markdown
---
You can use the public API endpoints to set up integration between BigPicture and external tools. To get responses, you need to have admin permissions.
## Base URL
### How to determine the base URL (Jira Server, Jira Data Center)
To determine the base URL for the public API:
1. Navigate to **Jira Administration > System > General configuration**.
2. Under the **General Settings** section, find the **base URL**, for example, [https://yourcompanyname.com](https://yourcompanyname.com).
Use the following format for the base URL in the public API (replace **{Jira BaseURL} **with your base URL):
```plaintext
{Jira BaseURL}/rest/softwareplant-bigpicture/1.0
```
Example:
```plaintext
https://yourcompanyname.com/rest/softwareplant-bigpicture/1.0
```
### How to determine the base URL (Jira Cloud)
BigPicture can be located on different servers. For example, during a version update, BigPicture is moved to another server which causes the change of the base URL.
To determine the base URL of the server where BigPicture is located, you have to call our Cloud Manager with a token to the public API:
```plaintext
GET https://cloud.softwareplant.com/cloudmanager/bigpicture/where-am-i
Authorization: APIToken {your API token}
```
In response, you should get the location of BigPicture, for example:
```plaintext
{
"location": "https://cloud.softwareplant.com/bigpicture/jiracloud/101"
}
```
Use the following format for the base URL in the public API:
```plaintext
{location received from cloudmanager}/rest
```
#### What happens when BigPicture is moved to another server
When BigPicture changes location to another server, then a call to the public API of the old server returns a 401 error. After that, it is necessary to call our Cloud Manager again to determine the BigPicture location using the **["where-am-i" ](https://appfire.atlassian.net/wiki/spaces/DLPDRAFT/pages/297534728)**[endpoint](https://appfire.atlassian.net/wiki/spaces/DLPDRAFT/pages/297534728).
## Synchronize absences of your Resources
Provide API to synchronize the following absences of your Resources with data from other systems used by your organization, e.g., SAP.
- Regular work time
- Holiday
- Sick leave
Jira and BigPicture admins can perform queries on these endpoints:
> ⚠️ **Cookie: JSESSIONID=sessionId** is used for calls to the public API on Jira Server/ Jira Data Center. **It is not required on Jira Cloud**.
| **Operation** | **Request type: URL** | **Additional info** | **Example of response** |
| --- | --- | --- | --- |
| Get absence for a particular Resource | **GET baseUrl/public/ppm/resources/****{individualId}/****absences**
Accept: application/json
Authorization: APIToken
Cookie: JSESSIONID=sessionId | Replace **baseUrl **with your real URL, for example: [https://qa.softwareplant.com/prod/rest/softwareplant-bigpicture/1.0](https://qa.softwareplant.com/prod/rest/softwareplant-bigpicture/1.0)
For **{individualId}, **use a pattern: EXT_USER@@
Replace with an ID for an external platform you use data from. If your default external platform is Jira Server, enter 2. To check , go to App Configuration → Integrations → Connections. Click F12 to see a side window on the right. Go to "Network" → "Fetch/XHR". Refresh the page, click "extplatform" and navigate to the "Preview" section. The will be visible there, as presented below. Copy an ID for the platform you want to use.
Next, replace with a real ID of the user from the external platform you want to use (for Jira Server, enter a user ID in Jira, for another extplatform like Trello, provide a user ID in Trello).
If is an email address, double “@” and use the pattern EXT_USER@@@@, then provide a real email in .
You can generate an **APIToken** in BigPicture -> My settings -> API tokens. For more info, click [here](https://appfire.atlassian.net/wiki/spaces/DLP/pages/296849987). The token is valid for 1 year.
To catch your **sessionId,** you can:
Open BigPicture and click F12 to see a side window on the right. Go to "Network" -> "Fetch/XHR". Refresh the page and copy your JSESSIONID, as presented below.
 | Example of API response for Resource absence:
 |
| Create absence for a particular Resource | **POST baseUrl/public/ppm/resources/{individualId}/absences**
Content-Type: application/json
Authorization: APIToken
Cookie: JSESSIONID=sessionId
Request Body**:**
{ "startDate": "2022-12-02", "endDate": "2022-12-02", "absenceType": "HOLIDAY", "comment": "new comment content", "percentageUnavailability": 100 } | There are 5 different **absenceType** you can use:
- HOLIDAY
- LEAVE AT REQUEST
- SICK LEAVE
- MATERNITY LEAVE
- OTHER REASON
You can set **percentageUnavailability **to 50 or 100.
Other values are not supported. 50 means the Resource is absent half a day, while 100 informs that the Resource is absent all day.
To provide data, use the pattern: **YYYY-MM-dd**. |
| Update absence for a particular Resource | **PUT baseUrl/public/ppm/resources/{individualId}/absences?startDate={startDate}**
Content-Type: application/json
Authorization: APIToken
Cookie: JSESSIONID=sessionId
Request Body:
{ "startDate": "2024-07-21", "endDate": "2024-09-21", "absenceType": "OTHER REASON", "comment": "updated comment content", "percentageUnavailability": 50 } |
| Delete absence for a particular Resource | **DELETE baseUrl/public/ppm/resources/{individualId}/absences?startDate={startDate}**
Content-Type: application/json
Authorization: APIToken
Cookie: JSESSIONID=sessionId |
## Get all Teams in a given Box
Jira and BigPicture admins can use the following endpoint to get all Teams in a given Box.
> ⚠️ **Cookie: JSESSIONID=sessionId** is used for calls to the public API on Jira Server/ Jira Data Center. **It is not required on Jira Cloud**.
| **Operation** | **Request type: URL** | **Additional info** | **Example of response** |
| --- | --- | --- | --- |
| Get all Teams in a given Box | **GET baseURL/public/ppm/teams?boxIds={boxId1}&boxIds={boxId2}**
Accept: application/json
Authorization: APIToken
Cookie: JSESSIONID=sessionId | Replace **baseUrl **with your real URL, for example: [https://qa.softwareplant.com/prod/rest/softwareplant-bigpicture/1.0](https://qa.softwareplant.com/prod/rest/softwareplant-bigpicture/1.0)
Replace **{boxId1}, {boxId2} **with real IDs. You can enter as many **boxIds **as you want. You can find your **boxId **in the URL bar or next to the status of the Box, as presented below.
You can generate an **APIToken **in BigPicture -> My settings -> API tokens. For more info, click [here](https://appfire.atlassian.net/wiki/spaces/DLP/pages/296849987). The token is valid for 1 year.
To catch your **sessionId,** you can:
Open BigPicture and click F12 to see a side window on the right. Go to "Network" -> "Fetch/XHR". Refresh the page and copy your JSESSIONID, as presented below.
 | Example of GET Team response:
 |
## Get task assignment of your Resources
Jira and BigPicture admins can use the following endpoint to get assignments of tasks for Resources.
> ⚠️ **Cookie: JSESSIONID=sessionId** is used for calls to the public API on Jira Server/ Jira Data Center. **It is not required on Jira Cloud**.
| **Operation** | **Request type: URL** | **Additional info** | **Example of response** |
| --- | --- | --- | --- |
| Get assignments of tasks for Resources | **GET baseURL/public/ppm/boxarea/resourcetaskassignment/{boxId}/**
**resourcetaskassignment?startDate={startDate}&endDate={endDate}&taskEffortMode={taskEffortMode}**
Accept: application/json
Authorization: APIToken
Cookie: JSESSIONID=sessionId | Replace **baseUrl **with your real URL, for example: [https://qa.softwareplant.com/prod/rest/softwareplant-bigpicture/1.0](https://qa.softwareplant.com/prod/rest/softwareplant-bigpicture/1.0)
Replace **{boxId} **with real **boxId** of box you would like to retrieve data from. You can find your **boxId **in the URL bar or next to the status of the Box, as presented below.
To provide data, use the pattern: **YYYY-MM-dd**.
The following **taskEffortMode **can be applied:
- ORIGINAL_EFFORT_ESTIMATE,
- REMAINING_EFFORT_ESTIMATE,
- STORY_POINT_EFFORT_ESTIMATE
By default, ORIGINAL_EFFORT_ESTIMATE will be generated for **taskEffortMode **even If you do not replace **{taskEffortMode} **in the endpoint.
You can generate an **APIToken **in BigPicture -> My settings -> API tokens. For more info, click [here](https://appfire.atlassian.net/wiki/spaces/DLP/pages/296849987). The token is valid for 1 year.
To catch your **sessionId,** you can:
Open BigPicture and click F12 to see a side window on the right. Go to "Network" -> "Fetch/XHR". Refresh the page and copy your JSESSIONID, as presented below.
 | Example task assignment response:
 |
## Get all Box IDs associated with a selected task in the scope
Jira and BigPicture admins can use the following endpoint to get all Box IDs connected with a selected task in the scope.
> ⚠️ **Cookie: JSESSIONID=sessionId** is used for calls to the public API on Jira Server/ Jira Data Center. **It is not required on Jira Cloud**.
| **Operation** | **Request type: URL** | **Additional info** |
| --- | --- | --- |
| Get all Box IDs associated with a selected task in the scope | **GET ****{baseURL}/public/ppm/boxarea/task/{taskIdorExtPlatformTaskKey}/boxes**
Accept: application/json
Authorization: APIToken
Cookie: JSESSIONID=sessionId | Replace **baseUrl **with your real URL, for example: [https://qa.softwareplant.com/prod/rest/softwareplant-bigpicture/1.0](https://qa.softwareplant.com/prod/rest/softwareplant-bigpicture/1.0)
You can find **taskId** in BigPicture, for example, "108".
1. Click F12 to see a side window on the right.
2. Navigate to "Network" -> "Fetch/XHR".
3. Start editing a selected task inline in BigPicture.
4. Click the updateFieldValue parameter and go to the "Payload" section. The **taskId **is visible there.
For **ExtPlatformTaskKey**, use this pattern {extplatformId}@{extTaskType}@{extTaskId}, for example, "2@1@1034407".
1. Go to a Jira issue and click F12 to see a side window on the right.
2. Navigate to "Network" -> "Fetch/XHR".
3. Refresh the page.
4. Find the loadBoxStructure parameter (use the search box to find it faster).
5. Go to the "Payload" section.
Make sure that the [WBS widget](https://appfire.atlassian.net/wiki/spaces/DLP/pages/297603900) is enabled.
You can generate an **APIToken **in BigPicture -> My settings -> API tokens. For more info, click [here](https://appfire.atlassian.net/wiki/spaces/DLP/pages/296849987). The token is valid for 1 year.
To catch your **sessionId,** you can:
Open BigPicture and click F12 to see a side window on the right. Go to "Network" -> "Fetch/XHR". Refresh the page and copy your JSESSIONID, as presented below.
 |
## Get the field definition of a Box
Jira and BigPicture admins can use the following endpoint to get the field definition of a Box.
> ⚠️ **Cookie: JSESSIONID=sessionId** is used for calls to the public API on Jira Server/ Jira Data Center. **It is not required on Jira Cloud**.
| **Operation** | **Request type: URL** | **Additional info** |
| --- | --- | --- |
| Get the field definition of a Box | **GET {baseUrl}/public/ppm/box/field/definition**
Accept: application/json
Authorization: APIToken
Cookie: JSESSIONID=sessionId | Replace **baseUrl **with your real URL, for example: [https://qa.softwareplant.com/prod/rest/softwareplant-bigpicture/1.0](https://qa.softwareplant.com/prod/rest/softwareplant-bigpicture/1.0)
You can generate an **APIToken **in BigPicture -> My settings -> API tokens. For more info, click [here](https://appfire.atlassian.net/wiki/spaces/DLP/pages/296849987). The token is valid for 1 year.
To catch your **sessionId,** you can:
Open BigPicture and click F12 to see a side window on the right. Go to "Network" -> "Fetch/XHR". Refresh the page and copy your JSESSIONID, as presented below.
 |
**Example of response:**
##### **Example response**
```javascript
{
"boxFieldDefinitions":[
{
"boxFieldDefinitionId":13,
"boxFieldDefinitionLabel":"Actual Cost",
"dataType":"NUMBER",
"readOnly":true,
"removable":false,
"selectOptions":[
]
},
{
"boxFieldDefinitionId":111,
"boxFieldDefinitionLabel":"Actual Cost (Tasks)",
"dataType":"NUMBER",
"readOnly":true,
"removable":false,
"selectOptions":[
]
},
{
"boxFieldDefinitionId":10,
"boxFieldDefinitionLabel":"Archived",
"dataType":"LABELS",
"readOnly":true,
"removable":false,
"selectOptions":[
]
}
]
}
```
## Get selected fields of a Box
Jira and BigPicture admins can use the following endpoint to get selected fields of a Box.
> ⚠️ **Cookie: JSESSIONID=sessionId** is used for calls to the public API on Jira Server/ Jira Data Center. **It is not required on Jira Cloud**.
| **Operation** | **Request type: URL** | **Additional info** |
| --- | --- | --- |
| Get selected fields of a Box | **POST {baseUrl}/public/ppm/box/{boxId}/selectedFields**
Accept: application/json
Authorization: APIToken
Cookie: JSESSIONID=sessionId | Replace **baseUrl **with your real URL, for example: [https://qa.softwareplant.com/prod/rest/softwareplant-bigpicture/1.0](https://qa.softwareplant.com/prod/rest/softwareplant-bigpicture/1.0)
Replace **{boxId} **with a real ID. You can find your **boxId **in the URL bar or next to the status of the Box, as presented below.
You can generate an **APIToken **in BigPicture -> My settings -> API tokens. For more info, click [here](https://appfire.atlassian.net/wiki/spaces/DLP/pages/296849987). The token is valid for 1 year.
To catch your **sessionId,** you can:
Open BigPicture and click F12 to see a side window on the right. Go to "Network" -> "Fetch/XHR". Refresh the page and copy your JSESSIONID, as presented below.
 |
**Example of request body:**
##### **Example request**
```javascript
{
"boxIds":["PROG-1741", "ROOT"],
"fields":{
"1":["NONE"],
"2":["MAX"]
}
}
```
**Example of response:**
##### **Example response**
```javascript
{
"fields":{
"ROOT":{
"aggregations":{
"1":{
"NONE":{
"dataTypeId":"STRING",
"value":""
}
},
"2":{
"MAX":{
"dataTypeId":"DATE",
"value":"2069-12-31"
}
}
}
},
"PROG-1741":{
"aggregations":{
"1":{
"NONE":{
"dataTypeId":"STRING",
"value":""
}
},
"2":{
"MAX":{
"dataTypeId":"DATE",
"value":"2025-12-31"
}
}
}
}
}
}
```
## Get values of respective aggregation for a particular task
Jira and BigPicture admins can use the following endpoint to get values of respective aggregation by global task field names.
> ⚠️ **Cookie: JSESSIONID=sessionId** is used for calls to the public API on Jira Server/ Jira Data Center. **It is not required on Jira Cloud**.
| **Operation** | **Request type: URL** | **Additional info** |
| --- | --- | --- |
| Get values of respective aggregation for a particular task | **GET baseUrl/public/ppm/boxarea/task/{taskIdOrExtPlatformTaskKey}/field/aggregations**
Accept: application/json
Authorization: APIToken
Cookie: JSESSIONID=sessionId | Replace **baseUrl **with your real URL, for example: [https://qa.softwareplant.com/prod/rest/softwareplant-bigpicture/1.0](https://qa.softwareplant.com/prod/rest/softwareplant-bigpicture/1.0)
You can generate an **APIToken **in BigPicture -> My settings -> API tokens. For more info, click [here](https://appfire.atlassian.net/wiki/spaces/DLP/pages/296849987). The token is valid for 1 year.
To catch your **sessionId,** you can:
Open BigPicture and click F12 to see a side window on the right. Go to "Network" -> "Fetch/XHR". Refresh the page and copy your JSESSIONID, as presented below.
 |
Parameters:
| **Parameter** | **Location** | **Type** | **Description** |
| --- | --- | --- | --- |
| taskIdOrExtPlatformTaskKey | Path | String | Providing **taskId** or **ExtPlatformTaskKey **is mandatory.
You can find **taskId** in BigPicture, for example, "108".
1. Click F12 to see a side window on the right.
2. Navigate to "Network" -> "Fetch/XHR".
3. Start editing a selected task inline in BigPicture.
4. Click the updateFieldValue parameter and go to the "Payload" section. The **taskId **is visible there.
For **ExtPlatformTaskKey**, use this pattern {extplatformId}@{extTaskType}@{extTaskId}, for example, "2@1@1034407".
1. Go to a Jira issue and click F12 to see a side window on the right.
2. Navigate to "Network" -> "Fetch/XHR".
3. Refresh the page.
4. Find the loadBoxStructure parameter (use the search box to find it faster).
5. Go to the "Payload" section.
Make sure that the [WBS widget](https://appfire.atlassian.net/wiki/spaces/DLP/pages/297603900) is enabled.
 |
| fieldId | Query String | String or Integer | Providing **t****askFieldId **or **g****lobalFieldName** is mandatory.
Enter **taskFieldId** - TaskFieldId (integer) used to identify a field in BigPicture, for example, "518".
Enter **globalFieldName** - GlobalFieldName (String) used to identify global field names, for example, "Story Points". |
| aggregationType | Query String | String | Providing **aggregationType **is mandatory.
Possible values:
- MIN
- MAX
- SUM
- SUM_NO_PARENT
- AVG
- AVG_NO_PARENT |
| boxId | Query String | String | Providing **boxId **is optional. This parameter can be used as a context for aggregation.
You can find your **boxId **in the URL bar or next to the status of the Box, for example, "PROG-30".
 |
### **Example of query:**
Giving the structure for a task, where DEV-4 has taskId=4
##### **Request in curl**
```shell
curl --request GET 'https://qa.softwareplant.com/prod/rest/softwareplant-bigpicture/1.0/public/ppm/boxarea/task/4/field/aggregations?fieldId=Story Points&aggregationType=SUM_NO_PARENT' \
--header 'Authorization: APIToken eyJ0eXBlIjoiSldUIiwiYWxnIjoiSFM1MTIifQ.eyJpc3MiOiIwMDAwMDAwIiwic3ViIjoiSklSQVVTRVIxMDAwMCIsImV4cCI6MTY2OTk3ODQ2NSwiaWF0IjoxNjY5MzczNjY1fQ.nR2kvya9ngBXe5rMXqSnHttFskvBwKUZe3o-i5AXWNv9pVtehKdc0Vo7SvUCreZAAnTq2Bm1TtcBrp7hTXPkmQ' \
--header 'Cookie: JSESSIONID=DAEA639C9BB35602BA6DD6047AE28F91; atlassian.xsrf.token=BRV5-VZPW-OO88-0AGP_9ef14177ddf00af1495cb7818d5b29c83c1a899c_lin'
```
Parameters used in the query:
taskIdOrExtPlatformTaskKey - 4
fieldId - "Story Points"
aggregationType - SUM_NO_PARENT
### **Example of response:**
##### **Example response**
```javascript
{
"currentVersion": 1,
"latestVersion": 1,
"cargo": {
"value": {
"dataTypeId": "NUMBER",
"number": 6.0,
"histogram": false
}
}
}
```