Curated queries

A curated query is a supported Teamwork Graph traversal exposed as a typed GraphQL field. You don't send Cypher — you select a field and pass its declared arguments. The Cypher behind the field is fixed and maintained by Atlassian.

Curated queries are ideal for initial Teamwork Graph exploration. They offer:

• No registration step. The fields exist in the schema, so there's nothing to submit and no propagation delay before you can call them.
• Typed, hydrated results. You get the object back directly and can request its fields, instead of resolving ARIs yourself.
• Stability. The traversal is versioned and supported, so a change to the underlying graph schema won't silently break your app.

If no curated query covers what you need, register your own query instead. See Persisted Cypher queries.

Available curated queries

Every field also accepts first: Int and after: String for pagination.

The userId, id, teamAri, spaceAri, and goalId arguments take an ARI, for example ari:cloud:identity::user/712020:5fb4febcfacfd60076a1c699.

Arguments named since and window take an ISO-8601 duration, for example P7D for the last seven days, or PT12H for the last twelve hours. jiraWorkItemComments defaults since to P30D when you omit it.

Discovering the catalog

The schema is the catalog. There's no "list curated queries" endpoint, so to see the fields available right now along with their exact return types, either run standard GraphQL introspection on the Query type, browse the schema in the GraphiQL playground, or fetch the SDL:

1
2
GET https://yourinstancename.atlassian.net/gateway/api/graphql/twg/schema

Do this rather than relying on the table above if you need certainty. New curated queries are added over time.

Calling a curated query

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
query companyName_assignedWork($userId: ID!) {
  atlassianUserAssignedJiraWorkItems(userId: $userId, first: 25) {
    edges {
      node {
        ... on JiraWorkItem {
          id
          title
          status {
            name
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Query variables:

1
2
3
4
{
  "userId": "ari:cloud:identity::user/712020:5fb4febcfacfd60076a1c699"
}

Each field returns a Relay-style connection: edges, each with a node, plus a pageInfo carrying hasNextPage and endCursor.

Endpoint and authentication

Curated queries are fields on the root Query type of the Teamwork Graph GraphQL endpoint. Replace yourinstancename with your site's name:

1
2
3
POST https://yourinstancename.atlassian.net/gateway/api/graphql/twg
Content-Type: application/json

Requests need an OAuth token carrying a scope for every object type the field returns, as well as for the object type it starts from. In a Forge app, call the endpoint with api.asUser().requestTeamworkGraph(...) as described in Call the Teamwork Graph API.

Every row returned is permission-filtered for the authenticated user, so a curated query only ever returns what that user can already see. Two users calling the same field with the same arguments can legitimately get different results.

Reading the response

The node on each edge is a union, so you select the concrete type with an inline fragment. Most fields return a single member.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
query companyName_recentWork($userId: ID!) {
  atlassianUserRecentlyViewed(userId: $userId, since: "P7D", first: 25) {
    edges {
      node {
        __typename
        ... on JiraWorkItem {
          id
          title
        }
        ... on ConfluencePage {
          id
          title
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Selecting __typename is worth doing on the broad fields so your client can branch on the type it actually received.

Pagination and limits

Curated queries cap first at 25, and 25 is also the default if you omit it. Requesting more than 25 returns an error.

When a curated query is not enough

If a curated query almost fits but you need extra filtering, calling it and filtering in your own code is usually the better trade. You keep the stability guarantee, and the 25-result cap means the volume is small.

Register your own query when the traversal itself is different: a different starting object type, a different relationship, or a return shape the catalog doesn't cover. See Persisted Cypher queries.

If you already know the ARI of a single object and don't need a traversal at all, use direct object querying instead.

If you're moving an existing integration off ad-hoc Cypher, start with Migrate from raw Cypher queries.

Getting help

If you're unsure whether a curated query covers your use case, ask in the Atlassian developer community. To report a bug or request a new curated query, raise a ticket in the Atlassian Ecosystem Help Center.