[New] Goals Now Support Privacy Settings, Default Access Levels, and Stories via API

English Forum Developers & API Changelog
1

[New] Goals Now Support Privacy Settings, Default Access Levels, and Stories via API

Summary

Goals now support privacy settings, default access levels, and stories via the Asana API.

You can now:

  • Control goal visibility with privacy_setting
  • Set a default member access level with default_access_level
  • Read and post goal comments programmatically using two new goal stories endpoints

These are additive changes with no breaking impact on existing integrations.

Who is affected

This update is relevant to developers building:

  • Goal management and OKR tools that need to reflect or enforce goal visibility configured by workspace admins — for example, restricting sensitive strategic goals to members only while keeping team-level goals visible across the workspace
  • Reporting and analytics integrations that surface goal data and need to respect privacy boundaries when displaying goals to different user segments
  • Collaboration tools that want to surface goal comments or post programmatic updates into a goal’s activity feed

What’s new

Privacy and access level fields

Two new optional fields are now available on goal create, read, and update endpoints:

Field Type Description
privacy_setting string Controls who can see the goal. Values: public_to_workspace, members_only
default_access_level string Default access role assigned when a new member joins the goal. Values: admin, editor, commenter, viewer

Affected endpoints:

  • GET /goals/{goal_gid} — Returns privacy_setting and default_access_level
  • GET /goals — Available via opt_fields
  • POST /goals — Accepts privacy_setting and default_access_level
  • PUT /goals/{goal_gid} — Accepts privacy_setting and default_access_level

Note: privacy_setting and default_access_level are opt-in fields and must be explicitly requested using the opt_fields parameter. For example:

GET /goals/{goal_gid}?opt_fields=custom_field_settings.custom_field.default_access_level,custom_field_settings.custom_field.privacy_setting

Goal stories endpoints

Two new endpoints let you read and create stories (comments and activity) on goals:

Endpoint Description
GET /goals/{goal_gid}/stories Returns all stories for a goal (paginated)
POST /goals/{goal_gid}/stories Creates a comment or sticker story on a goal

Goal stories follow the same structure as task stories. Comments are authored by the authenticated user and timestamped at the time of the server request.

Required OAuth scope: goals:write

Optional request fields for POST /goals/{goal_gid}/stories:

Field Type Description
text string The text content of the comment
html_text string HTML formatted text of the comment
is_pinned boolean Whether the story should be pinned on the goal
sticker_name string enum The sticker to attach to the story. Values: green_checkmark, people_dancing, dancing_unicorn, heart, party_popper, people_waving_flags, splashing_narwhal, trophy, yeti_riding_unicorn, celebrating_people, determined_climbers, phoenix_spreading_love

Usage

Creating a goal with privacy settings

// POST /goals
{
  "data": {
    "name": "Grow web traffic by 30%",
    "notes": "Start building brand awareness.",
    "due_on": "2019-09-15",
    "start_on": "2019-09-14",
    "is_workspace_level": true,
    "privacy_setting": "public_to_workspace",
    "default_access_level": "commenter",
    "workspace": "12345678901234",
    "time_period": "98765432109876",
    "owner": "11223344556677"
  }
}

Updating privacy settings on an existing goal

// PUT /goals/{goal_gid}
{
  "data": {
    "privacy_setting": "members_only",
    "default_access_level": "editor"
  }
}

Getting stories from a goal

// GET /goals/{goal_gid}/stories
{
  "data": [
    {
      "gid": "12345",
      "resource_type": "story",
      "type": "comment",
      "text": "Updated Q2 target based on revised forecast.",
      "created_by": {
        "gid": "98765",
        "resource_type": "user",
        "name": "Greg Sanchez"
      },
      "created_at": "2024-04-01T10:00:00.000Z"
    }
  ]
}

Creating a comment on a goal

// POST /goals/{goal_gid}/stories
{
  "data": {
    "text": "Updated Q2 target based on revised forecast."
  }
}

Creating a sticker story on a goal

// POST /goals/{goal_gid}/stories
{
  "data": {
    "sticker_name": "trophy",
    "is_pinned": true
  }
}

Timeline

These changes are available now.

Resources

1 Like