Overview of the Atlassian platform GraphQL API

The Atlassian platform GraphQL API allows you to access to all sorts of Atlassian data.

For example, you can use the GraphQL API to access Jira projects, Bitbucket repositories, Opsgenie teams, or cross-product work activities.

The Atlassian platform GraphQL API makes this data accessible using one common mechanism using the Atlassian GraphQL Gateway.

About GraphQL

GraphQL is a query language for APIs. This style of API allows access to linked data, which you can think of as a graph of entities. For example, you can request the work activity of a team of people and get the details for those people in the same request. With other types of APIs, such as REST APIs, this would require many requests, making GraphQL more efficient and flexible to use.

Because you must specify the data attributes you want back (called fields), the payloads can be smaller and hence faster over the network. In other words, you only get the data that you specified and no more.

GraphQL APIs are strongly typed, and the type system determines what data can be queried. You can use queries to request data and mutations to modify data. To learn more about GraphQL, we recommend reading Introduction to GraphQL and learning about the Core Concepts.

Explorer

The GraphQL API explorer is a browser-based, interactive IDE that you can use to run queries and mutations and see the results.

The explorer helps you discover what fields are valid and where they can be used. As you type, it suggests value fields that can be placed into the query. Press control+space for a prompt showing the valid fields that you can use.

Use the type system documentation on the left side to learn more about the GraphQL schema.

Authentication

There are multiple ways to authenticate with the GraphQL API, depending on the client being used:

• OAuth: OAuth clients use https://api.atlassian.com/graphql
• Browser sessions and API tokens: Browsers and API tokens use https://{your-subdomain}.atlassian.net/gateway/api/graphql for tenanted products - for example https://hello.atlassian.net/gateway/api/graphql. You must use the appropriate subdomain for your request as sessions are distributed on a per-site basis. For non-tenanted products use the product domain instead - for example https://bitbucket.org/gateway/api/graphql, https://team.atlassian.com/gateway/api/graphql, https://trello.com/gateway/api/graphql. Note that some products might have not registered this route, for instance OpsGenie.
• Anonymous access: Some fields provide support for anonymous access. If a query is made anonymously and anonymous access is not available, then some fields may return no data.

All calls use HTTPS, which helps keep the data secure.

Authorization

Some fields require specific OAuth 2.0 authorization code grants (3LO) to be present in the request.

You can find out what fields require that scopes via the field descriptions, which are visible in the GraphQL explorer.

Rate limiting and query retries

AGG supports cost based per-user rate limiting for Graphql query and mutation operation. Schema producers can use the @rateLimit directive to specify the cost for different GraphQL fields in the schema.

The current default is that every user is allowed to spend 10,000 points per currency per minute.

AGG calculates the cost of every query and keeps track of how many points every user spent in the last minute. Once a user goes over 10,000 points for any currency, their requests to AGG will start being rate limited

AGG will start responding with HTTP 429 Too Many Requests status code. The response will contain a header RETRY-AFTER: ${timestamp} (for example retry-after: 2021-05-10T11:00Z) indicating the time when the rate limit will be reset.

Note: the HTTP 429 status code is for the entire request, it will not appear as a GraphQL error.

Do not retry on >=500 errors, as this is likely a service level issue, and doing so will only cause more unnecessary load.

Examples

Queries

This example query returns the cloud ID of a Jira site, your-domain.atlassian.net:

1
2
query example {
  tenantContexts(hostNames:["your-domain.atlassian.net"]) {
    cloudId
  }
}

This example query returns two things:

• A paginated list of all Jira projects
• For each project, a paginated list of Opsgenie teams that can be linked to the specified project

1
2
query example {
  jira {
    allJiraProjects(cloudId: "a436116f-02ce-4520-8fbb-7301462a1674", filter: {types: [SOFTWARE]}) {
      pageInfo {
        hasNextPage
      }
      edges {
        node {
          key
          name
          opsgenieTeamsAvailableToLinkWith {
            pageInfo {
              hasNextPage
            }
            edges {
              node {
                id
                name
              }
            }
          }
        }
      }
    }
  }
}

This example query returns the current user's identity information:

1
2
query example {
  me {
    user {
      ... on AtlassianAccountUser {
        accountId
        accountStatus
        name
        picture
      }
    }
  }
}

This example query shows what happens when no data is present for a field:

1
2
query example_with_no_data {
  user(accountId: "notanid") {
    ... on AtlassianAccountUser {
      name
    }
  }
}

# returns

{
  "data": {
    "user": null
  }
}

Mutations

This example mutation creates an association between a Jira project and a Confluence space:

1
2
mutation example {
  devOps {
    ariGraph {
      createRelationships (input: {
        "from": "ari:cloud:jira:a436116f-02ce-4520-8fbb-7301462a1674:project/1001",
        "to": "ari:cloud:confluence:a436116f-02ce-4520-8fbb-7301462a1674:space/456",
        "type": "project-documentation-space",
        "updatedAt": "2022-12-22T00:03:12.239Z"
      } ) {
        success
        errors {
          message
        }
      }
    }
  }
}

Errors

This example shows the errors returned when an invalid query is made:

1
2
query example_with_no_data {
  user(accountId: "notandid") {
    ... on AtlassianAccountUser {
      name
      notAValidField
    }
  }
}

# returns

{
  "errors": [
    {
      "message": "Validation error of type FieldUndefined: Field 'notAValidField' in type 'AtlassianAccountUser' is undefined @ 'user/notAValidField'",
      "locations": [
        {
          "line": 5,
          "column": 7
        }
      ],
      "extensions": {
        "errorSource": "GRAPHQL_GATEWAY",
        "classification": "ValidationError"
      }
    }
  ],
  "extensions": {
    "gateway": {
      "request_id": "d8765c8a6d500a3f",
      "invokedServices": []
    }
  }
}

Schema changes

The Atlassian GraphQL API is not versioned in the same way that Atlassian product REST APIs are versioned. The GraphQL API has only one version that continuously evolves. Changes to the schema are introduced using beta and removed after they have been deprecated.

Beta

Fields marked with beta can change without notice. Beta is typically used in the early stages of API development. You can determine if a field is in beta by using the GraphQL Explorer and reading the field's description.

To ensure that clients are explicitly accepting a field in beta, we require that the request contains a special header, X-ExperimentalApi: <betaName>. For example, if a field is marked as belonging to the DevOpsBeta program, we would require a header to be set as shown below:

1
2
X-ExperimentalApi: DevOpsBeta

If you don't provide this header when using a field that is in beta, then the request will be denied with an error indicating that you need to set the header to a specific value, such as DevOpsBeta.

If you use fields from two or more named beta fields then you must set a header per beta program.

Deprecation and removal

Fields and inputs can be deprecated and then removed after a period of time. A deprecation is an indication that you should move away from this field or input.

Like beta, you can see which fields are deprecated by reading the field description in the GraphQL explorer.