Preview: This section describes a preview feature. Preview features are deemed stable; however, they remain under active development and may be subject to shorter deprecation windows. Preview features are suitable for early adopters in production environments. We release preview features so partners and developers can study, test, and integrate them prior to General Availability (GA).
The Capacity Planning REST API exposes three resources. All endpoints are
served under https://api.atlassian.com/ex/capacity-planning/{cloudId}/v1.
For the full machine-readable specification, see the REST API reference.
A contribution represents a time allocation — how much capacity a person has on a piece of work during a specific period. For example: "Alex is allocated 40% to Project Alpha for the week starting on 2026-07-20."
Contributions are identified by a composite key:
(contributorDataId, workId, startDate, endDate).
| Endpoint | Method | Description |
|---|---|---|
/v1/contributions | GET | Get contributions for a contributor-work pair |
/v1/contributions | POST | Create or update contributions (bulk upsert) |
/v1/contributions:clear | POST | Clear contributions by composite key |
contributorDataId — ARI of the person who is a contributor to the work (e.g. ari:cloud:identity::user/{accountId})workId — ARI of the work item. Can be a Jira issue, Atlas project, or
non-project work item. The ARI namespace acts as the type discriminator.Contribution date ranges are bounded in the public REST API v1 contract:
| Operation | Constraint |
|---|---|
POST /v1/contributions | Each request can include at most 100 contributions. |
POST /v1/contributions | Each contribution must have startDate on or before endDate. |
POST /v1/contributions | A single contribution must not span more than 90 days. |
POST /v1/contributions | startDate must not be more than 2 years in the past. |
POST /v1/contributions | endDate must not be more than 2 years in the future. |
GET /v1/contributions | startDate must be on or before endDate. |
GET /v1/contributions | The query window must not exceed 2 years. |
GET /v1/contributions | Results are returned as contribution cells aligned to weekly time periods. |
POST /v1/contributions:clear | Each request can include at most 100 composite keys. |
POST /v1/contributions:clear | Each composite key must have startDate on or before endDate. |
A contributor work association is the assignment link between a person and a piece of work — for example, "Alex is assigned to Project Alpha." Associations exist independently of contributions; you can assign someone to work without immediately allocating time.
| Endpoint | Method | Description |
|---|---|---|
/v1/contributor-work-associations | POST | Create associations |
/v1/contributor-work-associations/by-contributor | GET | List work for a contributor |
/v1/contributor-work-associations/by-work | GET | List contributors for a work item |
/v1/contributor-work-associations:delete | POST | Delete associations |
GET /v1/contributor-work-associations/by-contributor?contributorDataId={ari}GET /v1/contributor-work-associations/by-work?workId={ari}A non-project work item is a custom work item that doesn't exist in Jira — for example, "Hiring", "On-call", or "Team ceremonies." These are created and managed entirely through Capacity Planning and can be used as work targets for contributions and associations.
Non-project work items are identified by a server-generated UUID in URLs and have a full ARI in the response body for cross-product linking.
| Endpoint | Method | Description |
|---|---|---|
/v1/non-project-work-items | GET | List all non-project work items |
/v1/non-project-work-items | POST | Create a new non-project work item |
/v1/non-project-work-items/{id} | GET | Get a non-project work item by ID |
/v1/non-project-work-items/{id} | PUT | Update a non-project work item |
List endpoints return paginated results using cursor-based pagination:
1 2 3 4 5 6{ "results": [...], "next": "eyJsYXN0SWQiOi...", "hasMore": true }
Pass the next value as the cursor query parameter to fetch the next page.
The API uses ARIs (Atlassian Resource Identifiers) in request and response
bodies. ARIs are self-describing and polymorphic — for example, workId can
be a Jira issue, an Atlas project, or a non-project work item, and the ARI
namespace acts as the type discriminator.
In URLs, non-project work items use a bare UUID ({id}) rather than an ARI
for cleaner path handling. The full ARI is always available in the response body.
Rate this page: