The Teamwork Graph API supports direct object queries — a set of top-level GraphQL query fields that let you fetch a specific object by its ARI (Atlassian Resource Identifier) without writing a Cypher query.

Direct object queries are useful when you already know the ARI of the resource you want to retrieve and you want a quick, simple way to look it up.

How it works

Each direct object query is a top-level field on the Query type that accepts a single id argument. The id must be a valid ARI for the corresponding object type. The query returns the object with all of its available fields, or null if the object is not found or you do not have permission to view it.

1
2
query {
  <queryField>(id: "<ARI>") {
    id
    # ... other fields
  }
}

Available direct object queries

The following table lists all object types that currently support direct object querying:

Query field	Object type	ARI format	Description
`jiraWorkItem`	JiraWorkItem	`ari:cloud:jira:{siteId}:issue/{issueId}`	A work item from Jira (issue, task, story, bug, etc.)
`atlassianGoal`	AtlassianGoal	`ari:cloud:townsquare:{cloudId}:goal/{goalId}`	A goal in Atlassian's goal-tracking platform
`atlassianProject`	AtlassianProject	`ari:cloud:townsquare:{cloudId}:project/{projectId}`	A project in Atlassian that groups related work and team activities

Not all object types support direct object queries. For object types not listed above, you can retrieve them using a Cypher query instead.

Examples

Querying a Jira work item

Fetch a specific Jira work item by its ARI to retrieve its key, summary, status, and assignee:

1
2
query getJiraWorkItem {
  jiraWorkItem(id: "ari:cloud:jira:abc123-def456:issue/10001") {
    id
    key
    summary
    description
    status {
      name
    }
    issueType {
      name
    }
    assignee {
      name
    }
    reporter {
      name
    }
    createdAt
    webUrl
  }
}

Querying an Atlassian goal

Fetch a specific Atlassian goal by its ARI to retrieve its name, description, owner, and status:

1
2
query getAtlassianGoal {
  atlassianGoal(id: "ari:cloud:townsquare:abc123-def456:goal/789") {
    id
    name
    key
    description
    url
    owner {
      name
    }
    createdAt
    startedAt
    dueDateStartedAt
    dueDateEndedAt
    updatedAt
    archived
    watching
    watcherCount
  }
}

Querying an Atlassian project

Fetch a specific Atlassian project by its ARI to retrieve its name, state, and descriptions:

1
2
query getAtlassianProject {
  atlassianProject(id: "ari:cloud:townsquare:abc123-def456:project/456") {
    id
    name
    key
    state
    url
    owner {
      name
    }
    descriptionWhat
    descriptionWhy
    descriptionMeasurement
    createdAt
    startedAt
    dueDateStartedAt
    dueDateEndedAt
    lastUpdatedAt
    archived
    watching
    watcherCount
    privateProject
  }
}

Direct object queries vs. Cypher queries

	Direct object queries	Cypher queries
Use case	Fetch a single known object by ARI	Traverse relationships, filter, and match patterns across the graph
Input	A single `id` (ARI)	A Cypher query string with optional parameters
Complexity	Simple — one field, one argument	Flexible — supports complex graph traversals
Supported types	Limited to specific object types (see table above)	All object types and relationships in the graph

Use direct object queries when you have an ARI and want to quickly retrieve a specific object. Use Cypher queries when you need to traverse relationships, search for objects by property, or perform more complex graph operations.

Finding an object's ARI

To use a direct object query, you need the ARI of the object you want to fetch. If you don't know the ARI, see Understanding ARIs for methods to discover it.