Creating a Program Increment Objective in Jira Align via REST API

Quick answer

To add a Program Increment (PI) Objective in Jira Align, send a POST request to the PI Objectives endpoint with a JSON payload that includes the objective’s name, description, start date, and end date. The call requires a valid OAuth token, Program Manager (or higher) role, and the program’s ID. Once the request succeeds, the objective appears in the Objectives column of the corresponding PI on the Program Board after a brief UI refresh.

How the mechanism works

Jira Align organizes work around Programs, which are logical containers for multiple Jira projects. A PI is a time‑boxed interval (typically 8‑12 weeks) within a Program. PI Objectives are high‑level goals that teams commit to during PI Planning. The REST API exposes these objectives under the Program resource, allowing automation of objective creation.

Prerequisites

• OAuth 2.0 token with the program.objectives.write scope (or equivalent).
• User role of Program Manager, Solution Train Engineer, or higher.
• The Program ID (programId) of the target Program.
• All Jira projects that will contribute to the PI must be mapped to the Program; otherwise related backlog items will not surface on the Program Board.

Worked example

Replace the placeholders with your actual values before running the command. Execute it from a terminal where you have network access to your Jira Align instance.

curl -X POST "https://your-company.jiraalign.com/api/v1/Program/12345/Objectives" \
  -H "Authorization: Bearer YOUR_OAUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Improve checkout latency",
    "description": "Reduce average checkout time from 4s to under 2s for all customer segments.",
    "startDate": "2026-11-04",
    "endDate": "2026-12-30"
  }'

Important notes on the placeholders:

• your-company.jiraalign.com – base URL of your Jira Align tenant.
• 12345 – numeric ID of the Program (obtainable via the UI or a GET /api/v1/Programs call).
• YOUR_OAUTH_TOKEN – a token that has not expired and includes the required scope.
• Dates must be in ISO‑8601 format (YYYY-MM-DD) and fall within the PI’s start/end window defined in the Program Board.

Limits and common mistakes

Rate limiting

The API enforces a default throttle of 1,000 calls per minute per client. Responses include the header X-RateLimit-Remaining. Ignoring this header can result in HTTP 429 responses, causing scripts to fail silently if not checked.

Immutable PI dates

Once a PI Objective is created, its startDate and endDate cannot be modified via the API. Attempting to update these fields returns a 400 error. To change the dates you must delete the objective and recreate it.

Project‑program mapping mismatches

If a Jira project referenced in the objective’s related work is not mapped to the Program, the objective will still be created but any linked issues will not appear on the Program Board. Verify mappings in the Jira Align Admin > Programs > Project Mapping screen before creating objectives that rely on cross‑project data.

Missing permissions

Calling the endpoint without the program.objectives.write scope or with a role lower than Program Manager yields an HTTP 403 Forbidden. The response body may be minimal; always inspect the status code and any error message.

UI latency

The Program Board may take up to 30 seconds to reflect newly created objectives. If the objective does not appear immediately, refresh the board or wait a short interval before re‑checking.

Verification steps

1. Check the HTTP response: a successful creation returns 201 Created and includes a Location header pointing to the new objective (e.g., /api/v1/Program/12345/Objectives/67890).
2. Run a GET request to retrieve the objective and confirm the payload matches what you sent:

curl -X GET "https://your-company.jiraalign.com/api/v1/Program/12345/Objectives/67890" \
  -H "Authorization: Bearer YOUR_OAUTH_TOKEN"

Inspect the returned JSON for the fields name, description, startDate, and endDate.

1. Open the Program Board in the Jira Align UI, locate the PI that matches the dates you supplied, and verify that the objective appears in the Objectives column.
2. Optionally, review the audit log (Admin > Audit > API Calls) to ensure the request was recorded and to see the X-RateLimit-Remaining value returned.

Practical way to check the result

The most reliable confirmation is the GET request described above, because it directly queries the stored state. UI verification is useful for quick visual checks but should be supplemented with the API call to avoid being misled by UI refresh delays.