New GraphQL APIs are available for Atlassian Goals and Projects

[#1]

Hi everyone, I’m excited to share that we’ve released new GraphQL APIs for the Goals and Projects apps. These APIs simplify alignment and visibility by supporting integrations with your existing tools, workflows, and reporting setups.

Read on to learn more about the available APIs, authentication, and resources to get started!

Create and update Goals and Projects via the API

Use these capabilities to keep goals and projects in sync with your existing tools, automate routine updates, and streamline how work is managed at scale.

	Goals	Projects
Create and manage	Create, edit, and clone goals.	Create, edit, and clone projects.
Access, sharing, and visibility	Share goals, manage who’s following a goal.	Share projects, manage who’s following a project.
Connections with teams, goals, projects, and work	Link or unlink teams, projects, and work items from a goal.	Add or remove individual and team contributors, link or remove goals and related projects, manage links, and link or unlink work items.
Manage updates, comments, and sharing	Create, edit, delete, and share goal updates; create, edit, and delete comments.	Create, edit, delete, and share project updates; create, edit, and delete comments.
Custom fields	Edit or clear text, number, user, and dropdown custom fields on goals.	Edit or clear text, number, user, and dropdown custom fields on projects.
Learnings, decisions, and risks	Create, edit, and delete learnings, decisions, and risks for a goal.	Create, edit, and delete learnings, decisions, and risks for a project.
Manage metrics and progress (Goals only)	Create, edit, remove, and archive goal metrics and metric targets; configure roll‑up. Integrate third-party data sources to automatically update your goal metrics.	-
Configure goal types and success measures (Goals only)	Create and edit goal types / success measures.	-

Read Goals and Projects via the API

Use these capabilities to pull data into your existing tools for reporting, dashboards, and internal apps.

	Goals	Projects
Discover and browse	Search, filter, and sort goals across your organization.	Search, filter, and sort projects across your organization.
View details	View a goal’s details, including status, owners, hierarchy, and linked work, teams, and projects.	View a project’s details, including status, contributors, and linked work, goals, and dependencies.
Access, sharing, and visibility	See who owns a goal, and who’s following it.	See who owns a project, which teams are involved, and who’s following the project.
Connections with teams, goals, projects, and work	View teams, linked projects, and linked work items associated with a goal.	View contributors and teams, linked goals and dependencies, external links, and linked work items for a project.
Updates, comments, and sharing	View a goal’s latest update, historical updates, and comments.	View a project’s latest update, historical updates, and comments; fetch updates in bulk.
Custom fields	View all custom field values on a goal.	View all custom field values on a project.
Learnings, decisions, and risks	View learnings, decisions, and risks for a goal.	View learnings, decisions, and risks for a project.
Configuration and capabilities	Read app‑level settings that control the Goals experience.	Read app‑level settings and capabilities that control the Projects experience.
Metrics and progress (Goals only)	View goal metrics, targets, current values, history, and roll‑up progress.	-
Goal types/success measures (Goals only)	View goal types and success measure definitions used in your organization.	-

Authentication

Authentication is currently supported via API tokens. To call the APIs, you’ll need to:

• Create an API token for your Atlassian account

• Use it with basic auth when calling the GraphQL endpoint

You can learn how to create and manage tokens by following the details on Manage API tokens for your Atlassian account.

How to get started

1. Create an API token

2. Explore the GraphQL schemas and example queries/mutations in the docs:

   • Goals GraphQL API

   • Projects GraphQL API

3. Try simple flows like:

   • Listing all projects or goals for a workspace.

   • Updating a goal’s description and attaching metric targets.

   • Linking a goal to a project and posting an update.

We’d love your feedback

We’re still actively evolving these APIs and would love to hear:

• The use cases you’re solving (dashboards, internal tools, automations, etc.)

• Any gaps in the schema or API capabilities you’d like to see filled.

Please share feedback, questions, or examples of what you’re building in the comments, and we’ll keep iterating based on your input.

Helpful resources

• Goals Queries and Mutations

• Project Queries and Mutations

• Managing API tokens

• Integrating and updating third-party metrics with Atlassian Goals

[Matt Richards]

@Charlie Marriott - Is this content accessible by way of MCP?

[Birgit P]

Hi,

First off: Thanks ❤️
I will be one of the very early users and certainly commenting further on this.

There are 4 core use cases I will solve with this (I kind of hacked my own Goals API in advance  by reading out the DOM of the browser, so I understand them):

• Reporting: The goals reporting is very clumsy. I want an Excel page listing all goals with a specific tag, and then their status, progress and latest updates. It needs to be a snapshot for board level.
• Implementing a project methodology: I'm not a fan of it, but we define projects in stages and associate progress with that. So if you change a field, the progress metric changes. 
  (Have to check if this is supported btw. I mean those field that you get on the side of goals).
• Change requests: If a goals deadline slips by >3 months, this triggers an automatic change management request workflow with Jira. We'll likely attach that ticket to the Goal.
• Goal creation: We have an annual project approval process. At the end, it will create a goal.

As a first feedback: I'm not a sophisticated user of GraphQL. The documentation - and I understand that it's super new, feels very thin. It would be useful to have relevant examples.

So for those who also want to play with it, here's some calls that I made work with the help of chatGPT.

Hope that saves someone time.

Best,
Birgit

Read Goals

(You have to replace the ari:cloud IT with your own. I have no idea which call to use to get it, I just used DevTools in Chrome to read it out)

query GoalsSearch {

  goals_search(

    containerId: "ari:cloud:townsquare::site/bb135c9c-xxxx"

    searchString: ""

    first: 25

    after: "dHFsY29ubmVjdGlvbjoyNDoyNTow"

    sort: null

  ) {

    pageInfo {

      hasNextPage

      endCursor

    }

    edges {

      node {

        id

        key

        name

        url

        isArchived

        creationDate

        latestUpdateDate

        startDate

        description

      }

    }

  }

}

Read Goal Updates

Obviously the ID of the goal comes from above call.

query GoalUpdates {

  goals_byId(

    goalId: "ari:cloud:townsquare:bb135c9c-xxx"

  ) {

    id

    key

    name

    updates(first: 10) @optIn(to: "Townsquare") {

      pageInfo { hasNextPage endCursor }

      edges {

        cursor

        node {

          id

          url

          creationDate

          editDate

          updateType

          missedUpdate

          summary

          newScore

          oldScore

          newTargetDate

          oldTargetDate

          newTargetDateConfidence

          oldTargetDateConfidence

        }

      }

    }

  }

Update a Goal

What is noted here is:

• The text needs to be formatted in ADF (Atlassian Document Format)
• The targetDate formatting thing threw me off a bit, but it's actually visible in the UI as well. The confidence interval specifies if you're talking about quarters, months or days...
• In general, it's useful to retrieve the outputs of a few goals and just see what is inserted.

mutation CreateGoalUpdate  {

  goals_createUpdate(

    input: {

      goalId: "ari:cloud:townsquare:bb135c9c-7917-xyz"

      summary: "{\"version\":1,\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Programmatic update: upload pipeline live; first Call 7 dataset uploaded.\"}]}]}"

      status: "off_track"

      score: 75

      targetDate: { date: "2026-02-15", confidence: DAY }

    }

  ) @optIn(to: "Townsquare") {

    success

    errors { message }

    update {

      id

      url

      creationDate

      updateType

      summary

      newScore

      newTargetDate

      newTargetDateConfidence

    }

  }

}

[Tim Holme]

I made a token, but I get the error:
HTTP error occurred: 401 Client Error: Unauthorized for url: https://team.atlassian.com/gateway/api/graphql Response body: {"code":401,"message":"Unauthorized"}


How do I present the API token in my request? I have it in a header

headers = {

    "Authorization": f"Bearer {ATLASSIAN_API_KEY}",

    "Content-Type": "application/json"

}