[Launched] Team-Sharing for Goals


Hey folks,

We’re relaunching a more focused change to how the API enables you to manipulate members of Work Graph resources.

In the Asana UI, you can now add a Team as a member of goals:

screenshot of text "add teams or people by name or email" in goal dialog

This is known as “Team-Sharing”. Over time, we will roll out the same functionality to other Work Graph resources, such as Projects, Portfolios, and Workspaces.

There will be an independent migration period for each Work Graph resource as it moves over to the Team-Sharing.

Here’s what the Goal Team-Sharing migration looks like:

Old Endpoints New Endpoints
POST /goals/:goal_gid/addFollowers POST /memberships
POST /goals/:goal_gid/removeFollowers DELETE /memberships
(previously unavailable functionality) GET /memberships

Goal Team-Sharing Migration Timeline

  • 2023-03-22: the migration period starts:
    • Asana-Change: name=new_goal_memberships;affected=true header will
      begin appearing for API clients of old Goal membership endpoints:
    • those API clients should begin migrating their calls to the new
      /memberships endpoint
  • 2023-04-19: the migration period ends:
    • API clients of the old Goal membership endpoints must be using the
      /memberships endpoint:
    • calls to the old Goal membership endpoints will fail with a 404
    • the /memberships endpoint will be available as a replacement

We will follow a similar migration timeline for the other Work Graph resources,
as they begin migrating.

/memberships endpoint


GET /api/1.0/memberships?parent=123456


HTTP/1.1 200 OK
Asana-Change: name=new_memberships;affected=true

    "data": [
            "goal": {
                "gid": "123456",
                "name": "Team-Sharing API Demo",
                "owner": {
                    "gid": "987643",
                    "name": "Sasha F",
                    "resource_type": "user"
                "resource_type": "goal"
            "is_commenter": false,
            "is_editor": true,
            "member": {
                "gid": "4678",
                "name": "Sasha F",
                "resource_type": "user"
            "resource_type": "goal_membership"


Will Teams support Teams as members

No. Only users can be added as members for Teams. Teams will not be recursive.

If I don’t use Goal memberships, do I currently have to do anything?

No, you don’t need to do anything yet. If you use any other memberships, you
will eventually need to migrate to the /memberships endpoint.

What happened to Standard Access Levels (standard_access_level) from the
original announcement?

Standard Access Levels are being deferred for two reasons:

  1. Standard Access Levels are only currently available for some Work Graph
  2. Adding Team-Sharing and Standard Access Levels significantly complicates
    this change for developers and makes this harder, especially as both
    Team-Sharing and Standard Access Levels are being incrementally rolled
    out, one Work Graph resource at a time.


Date Event
2022-10-21 Original announcement
2023-01-19 Timeline adjustment
2023-01-25 Spec adjustment[1]
2023-03-23 Opt-In available
2023-04-27 Goal follower endpoints no longer available

Yours in Developer Relations,
Sasha, on behalf of the Asana API Team

  1. added clarifying text about effective_access_level and removed
    GET /memberships/effective_access_level/parent. ↩︎




NodeJS client still doesn’t support the new /memberships endpoint - any expectation when it will be updated?

Do you know that it does not “matter” as you can use the internal dispatcher to call the API raw endpoint from the code?

Well, it is quite odd that the official client doesn’t provide new endpoints, right? Even worse, it will provide the unsupported endpoints.

That’s fine if the “official solution” is to use the internal dispatcher, just disappointed as an user. I would recommend putting a note on Client libraries that official libraries may not be up-to-date with API.

I might be naive but I am not surprised at all if you take into account that in most companies the API team is not the same as the client librairies team. So they try to keep up but can’t always do…

I am not sure it has unsupported endpoints but rather deprecated ones.

That being said, knowing @sasha_f , he probably does everything he can to make sure those clients are up to date as fast as possible!

1 Like

Echoing @Bastien_Siebman I know for a fact that client libraries - keeping them current and relevant moreso than has typically happened in the past - is an active topic for the Developer Relations team.

1 Like

Hey there, this is a good call out. I agree, this is a disappointing experience. We’re currently working on revamping our client libraries to provide much more timely updates, as well as to follow more best practices for their respective language platforms. You can find more about that preview here: Try an early preview of our new Node.js and Python SDKs

Our goal in the future will be for API launches to be fast-followed with client library updates, and part of the preview is working towards ironing out any issues with that.

In the meantime, @Bastien_Siebman was spot on: you can make arbitrary calls to any currently available endpoint in the client library, even without explicit support for the resources or endpoint in question.

Thanks for the feedback, please keep it coming!