Understanding ARIs in Teamwork Graph

An Atlassian Resource Identifier (ARI) is a globally unique identifier for objects across Atlassian. ARIs are used throughout the Teamwork Graph API to identify specific objects when querying relationships and traversing the graph.

What is an ARI?

An ARI is similar to a URL—it's a standardized way to uniquely identify any resource in the Atlassian ecosystem. Just as a URL can point to any web resource, an ARI can point to any Atlassian resource: a Jira work item, a Confluence page, a user account, or any other object.

ARIs ensure that when you reference an object in your queries, you're referring to exactly the right object, even when similar objects exist across different sites or products.

ARI structure

ARIs follow a consistent pattern across all Atlassian resources:

1
2
ari:cloud:{app}:{siteId}:{objectType}/{objectId}

Components

Examples

Here are some examples of ARIs for different object types:

Jira work item:

1
2
ari:cloud:jira:a436116f-02ce-4520-8fbb-7301462a1674:issue/8843576

Jira space (project):

1
2
ari:cloud:jira:a436116f-02ce-4520-8fbb-7301462a1674:project/30867

Atlassian project:

1
2
ari:cloud:townsquare:a436116f-02ce-4520-8fbb-7301462a1674:project/ATLAS-103368

User:

1
2
ari:cloud:identity::user/5fb4febcfacfd60076a1c699

Team:

1
2
ari:cloud:identity::team/19441f6d-f53e-4e35-a89f-265a30db4e68

Notice that user and team ARIs use identity as the app and have a double colon (::) instead of a site ID, since user accounts and teams exist across all Atlassian sites.

Finding your site ID

Your site ID, also called the cloud ID, uniquely identifies your Atlassian instance. Most ARIs require a site ID to identify which instance the resource belongs to.

To find your site ID:

1. Make a GET request to the following endpoint, replacing yourinstancename with your Atlassian site's name:

   1
   2
   https://yourinstancename.atlassian.net/_edge/tenant_info
   

2. In the JSON response, find the cloudId field. This is your site ID.

Example response:

1
2
{
  "cloudId": "a436116f-02ce-4520-8fbb-7301462a1674",
  "tenantId": "a436116f-02ce-4520-8fbb-7301462a1674",
  "realm": "prod"
}

In this example, the site ID is a436116f-02ce-4520-8fbb-7301462a1674.

Using ARIs in the Teamwork Graph API

When querying the Teamwork Graph API, you'll use ARIs in several ways:

Querying specific objects

Use an ARI to retrieve a specific object:

1
2
query GetNode($nodeId: ID!) {
  node(id: $nodeId) {
    id
    ... on JiraWorkItem {
      key
      summary
    }
  }
}

With variables:

1
2
{
  "nodeId": "ari:cloud:jira:a436116f-02ce-4520-8fbb-7301462a1674:issue/8843576"
}

Filtering relationships

Use ARIs in relationship filters to narrow down results. For example, filtering work items by a specific assignee:

1
2
relationships(
  filter: {
    fromNode: {
      JiraIssue: {
        assigneeAri: "ari:cloud:identity::user/5fb4febcfacfd60076a1c699"
      }
    }
  }
)

Traversing the graph

When traversing relationships, ARIs identify the starting point and connected objects:

1
2
MATCH (user:UserAccount {ari: 'ari:cloud:identity::user/5fb4febcfacfd60076a1c699'})
      -[:UserAssignedIssue]->(issue:JiraIssue)
RETURN user, issue

Constructing ARIs for different object types

Each object type has its own ARI pattern and method for finding the necessary IDs. See the following reference pages for object-specific details:

• Jira work item - Learn how to construct ARIs for Jira issues
• Jira space - Learn how to construct ARIs for Jira projects
• Atlassian project - Learn how to construct ARIs for Atlas projects
• User - Learn how to construct ARIs for user accounts
• Team - Learn how to construct ARIs for teams
• Atlassian goal - Learn how to construct ARIs for Atlas goals

Common ARI patterns

While each object type has its own specific pattern, here are some common patterns you'll see:

Jira resources

Jira resources typically follow this pattern:

1
2
ari:cloud:jira:{siteId}:{objectType}/{objectId}

Examples:

• Issues: ari:cloud:jira:{siteId}:issue/{issueId}
• Projects: ari:cloud:jira:{siteId}:project/{projectId}

Atlassian resources

Atlassian-wide resources (like Atlas projects) typically use the townsquare namespace:

1
2
ari:cloud:townsquare:{siteId}:{objectType}/{objectId}

Identity resources

User accounts and identity-related resources use the identity namespace and omit the site ID:

1
2
ari:cloud:identity::{objectType}/{objectId}

Examples:

• Users: ari:cloud:identity::user/{userId}
• Teams: ari:cloud:identity::team/{teamId}

Related resources

• Object types in Teamwork Graph - Overview of all available object types
• Call the Teamwork Graph API - Learn how to query the API
• Relationships in Teamwork Graph - Learn about relationships between objects