> For the complete documentation index, see [llms.txt](https://docs.ativo.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ativo.io/rest-api/rest-api-endpoints.md).

# REST API Endpoints

{% hint style="info" %}
Set up access first: [Cloud setup](/rest-api/cloud-api-setup.md) or [Data Center setup](/rest-api/data-center-api-setup.md).
{% endhint %}

## Base URL

The base Url is shown on the Ativo REST API admin page (**Jira settings → Marketplace Apps → Ativo Programs → REST API**).

| Platform         | Base URL structure                                                                                 |
| ---------------- | -------------------------------------------------------------------------------------------------- |
| Jira Cloud       | `https://<your-site>.atlassian.net/gateway/api/svc/jira/apps/<app-id>_<environment-id>/rest/api/1` |
| Jira Data Center | `https://<your-jira-url>/rest/ativo-programs/1.0/api/1`                                            |

All endpoints are `GET`, answer JSON, and carry the `X-API-Model-Version` header (see [Version](/rest-api/api-version.md)). Paths below are relative to the base URL. The scope column applies to Jira Cloud only: an OAuth 2.0 integration must hold that scope to call the endpoint, see [Cloud setup](/rest-api/cloud-api-setup.md).

## Teams

| Endpoint     | Returns                            | Cloud scope                 |
| ------------ | ---------------------------------- | --------------------------- |
| `/team`      | List of teams: `id`, `key`, `name` | `read:configuration:custom` |
| `/team/{id}` | One team configuration             | `read:configuration:custom` |
| `/teams`     | All team configurations            | `read:configuration:custom` |

## Programs (ARTs)

| Endpoint        | Returns                               | Cloud scope                 |
| --------------- | ------------------------------------- | --------------------------- |
| `/program`      | List of programs: `id`, `key`, `name` | `read:configuration:custom` |
| `/program/{id}` | One program configuration             | `read:configuration:custom` |
| `/programs`     | All program configurations            | `read:configuration:custom` |

## Periods (PIs)

| Endpoint       | Returns                              | Cloud scope                 |
| -------------- | ------------------------------------ | --------------------------- |
| `/period`      | List of periods: `id`, `key`, `name` | `read:configuration:custom` |
| `/period/{id}` | One period configuration             | `read:configuration:custom` |
| `/periods`     | All period configurations            | `read:configuration:custom` |

## Objectives

| Endpoint                             | Returns                                   | Cloud scope        |
| ------------------------------------ | ----------------------------------------- | ------------------ |
| `/objectives/{programId}/{periodId}` | The program and team objectives of one PI | `read:plan:custom` |

## Meta

| Endpoint              | Returns                                          | Cloud scope                 |
| --------------------- | ------------------------------------------------ | --------------------------- |
| `/meta/model/version` | The current data model version, `{"version": 9}` | `read:configuration:custom` |

## Rips

* Start with a list endpoint (`/team`, `/program`, `/period`) to get the `id`s, then fetch an object by id.
* Archived teams, programs and periods are included and carry `isArchived: true`.
* Ativo configuration changes slowly. Cache responses rather than fetching them on every request.
* Jira Cloud only: requests beyond Atlassian's platform limits answer `429` and can be retried with exponential backoff, see [Cloud setup](/rest-api/cloud-api-setup.md).