This is the reference for the Focus REST API. The REST API enables you to interact with Focus programmatically. Use this API for scripting interactions with Focus and sending data from external tools. This page documents the REST resources available in Focus, including the HTTP response codes and example requests and responses.

This documentation is for version 1 of the Focus REST API.

Focus REST API v1 resources are available through the following gateway paths:

• https://your-domain.atlassian.net/gateway/api/focus/v1/focus-areas
• https://api.atlassian.com/focus/cloud/{cloudId}/v1/focus-areas

Use the first path for site-domain access. Use the second path for cloud-id based access.

The Focus REST API supports the following authentication methods:

Atlassian API token (Basic auth)

Use this method when calling through your Atlassian site domain and gateway path:

1
2
3
4
5
curl --request GET \
  --url 'https://your-domain.atlassian.net/gateway/api/focus/v1/focus-areas' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

OAuth 2.0 bearer token

Use this method with an OAuth 2.0 access token in the Authorization header:

1
2
3
4
5
curl --request GET \
  --url 'https://api.atlassian.com/focus/cloud/<cloud_id>/v1/focus-areas' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Atlassian session authentication

Browser-based requests from authenticated Atlassian sessions are also supported on site-domain gateway paths. OAuth 2.0 scopes used by this API include:

• read:focus-areas:focus for Focus Area read operations
• write:focus-areas:focus for Focus Area write operations
• read:organizations:focus for Organizations read operations
• write:organizations:focus for Organizations write operations
• read:funds:focus for Funds read operations
• write:funds:focus for Funds write operations

Generate an API token (Basic auth method)

API token authentication uses HTTP Basic auth with your Atlassian account email and API token.

1. Generate an API token for your Atlassian account: https://id.atlassian.com/manage/api-tokens
2. Use email@example.com:<api_token> with Basic auth (for example via --user in cURL), or build the equivalent Authorization: Basic ... header.

Authorization is enforced based on the authenticated principal and granted scopes/permissions for the requested operation. For OAuth 2.0 and API token calls through api.atlassian.com, access is evaluated against the target cloud site (cloudId).

Most operations in this API require specific permissions. To use an operation, the calling user must have the required permissions. For OAuth 2.0 requests, the access token must also include a scope that permits the operation. See Authentication for details.

Focus permissions are granted through user groups. Some operations also require EDIT access to a specific organization or focus area. For more information, see Manage user group permissions.

Organization association permissions

Reading organization associations requires read access to Focus. It does not require connection actions or EDIT access.

Creating, updating, or removing organization associations requires write access to Focus, EDIT access to the organization, and the relevant action under Organizations > Connections in the Focus Group permissions settings:

• Link focus areas - required to connect an organization to a focus area as a contributor or sponsor, or to change its role
• Unlink focus areas - required to disconnect an organization from a focus area. Unlinking does not delete the organization or focus area

Creating, updating, or removing a sponsor association, including changing a sponsor to a contributor, also requires EDIT access to the focus area.

The Focus REST API uses the standard HTTP status codes.

Responses that return an error status code also return a response body, similar to this:

1
2
3
4
5
6
7
8
9
{
  "errors": [
    {
      "type": "FORMAT_INVALID",
      "message": "Field [name] is invalid."
    }
  ]
}