Skip to content

Asana: Create a story on a goal

Asana stories.createStoryForGoal: arguments, response, policy and SDK examples.

← Stories operations · Get started

Operation asana.createstoryforgoal

Provider route: POST /goals/{goal_gid}/stories. Alter supplies the connection’s credentials and routing.

Install @alter-ai/sdk @alter-ai/asana with npm, or alter-sdk-asana with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { AsanaIntegration } from "@alter-ai/asana";
async function execute(input: Parameters<AsanaIntegration["stories"]["createStoryForGoal"]>[0]) {
const app = new App({ apiKey: process.env.ALTER_API_KEY! });
try {
const provider = new AsanaIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
const call = await provider.stories.createStoryForGoal(input);
const result = await call.wait();
return result.bodyJson();
} finally {
await app.close();
}
}
import os
from alter_sdk import App
from alter_sdk_asana import AsanaIntegration
async def execute(arguments):
async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
provider = AsanaIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
call = await provider.stories.create_story_for_goal(arguments)
result = await call.wait()
return result.body_json()
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
pathobjectRequired within parentAdditional keys: not allowed
path.goal_gidstringRequired within parent
queryModelOptionalExpand Get a story — request body — query
bodyobjectRequired within parent
body.dataModelOptionalExpand Update a story — request body — body data

Referenced models: Update a story — request body — body data, Get a story — request body — query

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

FieldTypePresenceDescription and constraints
$JSONRoot
$ (allOf 1)objectAll variants apply
$ (allOf 1).dataModelOptionalExpand Get a story — response body — data data — Story Response
$ (allOf 2)ModelAll variants applyExpand Get a story — response body — data

Referenced models: Get a story — response body — data data — Story Response, Get a story — response body — data

23 more schemas are linked from the tables above, on the schema pages.

Get a story — response body — data
FieldTypePresenceDescription and constraints
$objectRoot
dataModelRequired within parentExpand Get a story — response body — data data — sdk__Story Response

Referenced models: Get a story — response body — data data — sdk__Story Response

Update a story — request body — body data
FieldTypePresenceDescription and constraints
$objectRootA story represents an activity associated with an object in the Asana system.
gidstringOptionalGlobally unique identifier of the resource, as a string.
Read only: true
resource_typestringOptionalThe base type of this resource.
Read only: true
created_atstringOptionalThe time at which this resource was created.
Format: date-time
Read only: true
resource_subtypestringOptionalThe subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.
Read only: true
textstringOptionalThe plain text of the comment to add. Cannot be used with html_text.
html_textstringOptional[Opt In](/docs/inputoutput-options). HTML formatted text for a comment. This will not include the name of the creator. See [rich text](/docs/rich-text).
is_pinnedbooleanOptional*Conditional*. Whether the story should be pinned on the resource.
sticker_namestringOptionalThe name of the sticker in this story. `null` if there is no sticker.
One of: 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
Get a story — request body — query
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
opt_prettybooleanOptional
opt_fieldsarrayOptional
opt_fields[]stringEach itemOne of: anchor_gid, assignee, assignee.name, comment_gid, created_at, created_by, created_by.name, custom_field, custom_field.date_value, custom_field.date_value.date, custom_field.date_value.date_time, custom_field.display_value, custom_field.enabled, custom_field.enum_options, custom_field.enum_options.color, custom_field.enum_options.enabled, custom_field.enum_options.name, custom_field.enum_value, custom_field.enum_value.color, custom_field.enum_value.enabled, custom_field.enum_value.name, custom_field.id_prefix, custom_field.input_restrictions, custom_field.is_formula_field, custom_field.is_lookup_field, custom_field.multi_enum_values, custom_field.multi_enum_values.color, custom_field.multi_enum_values.enabled, custom_field.multi_enum_values.name, custom_field.name, custom_field.number_value, custom_field.representation_type, custom_field.text_value, custom_field.type, dependency, dependency.created_by, dependency.name, dependency.resource_subtype, duplicate_of, duplicate_of.created_by, duplicate_of.name, duplicate_of.resource_subtype, duplicated_from, duplicated_from.created_by, duplicated_from.name, duplicated_from.resource_subtype, follower, follower.name, hearted, hearts, hearts.user, hearts.user.name, html_text, is_editable, is_edited, is_pinned, liked, likes, likes.user, likes.user.name, new_approval_status, new_date_value, new_dates, new_dates.due_at, new_dates.due_on, new_dates.start_on, new_enum_value, new_enum_value.color, new_enum_value.enabled, new_enum_value.name, new_multi_enum_values, new_multi_enum_values.color, new_multi_enum_values.enabled, new_multi_enum_values.name, new_name, new_number_value, new_people_value, new_people_value.name, new_resource_subtype, new_section, new_section.name, new_text_value, num_hearts, num_likes, old_approval_status, old_date_value, old_dates, old_dates.due_at, old_dates.due_on, old_dates.start_on, old_enum_value, old_enum_value.color, old_enum_value.enabled, old_enum_value.name, old_multi_enum_values, old_multi_enum_values.color, old_multi_enum_values.enabled, old_multi_enum_values.name, old_name, old_number_value, old_people_value, old_people_value.name, old_resource_subtype, old_section, old_section.name, old_text_value, previews, previews.fallback, previews.footer, previews.header, previews.header_link, previews.html_text, previews.text, previews.title, previews.title_link, project, project.name, project.resource_subtype, reaction_summary, reaction_summary.count, reaction_summary.emoji_base, reaction_summary.reacted, reaction_summary.variant, resource_subtype, source, sticker_name, story, story.anchor_gid, story.comment_gid, story.created_at, story.created_by, story.created_by.name, story.resource_subtype, story.text, tag, tag.name, target, target.created_by, target.name, target.resource_subtype, task, task.created_by, task.name, task.resource_subtype, text, type
Create an enum option — response body — data data — Enum Option
FieldTypePresenceDescription and constraints
$objectRootEnum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.

You can add enum options to a custom field by using the `POST /custom_fields/custom_field_gid/enum_options` endpoint.

**It is not possible to remove or delete an enum option**. Instead, enum options can be disabled by updating the `enabled` field to false with the `PUT /enum_options/enum_option_gid` endpoint. Other attributes can be updated similarly.

On creation of an enum option, `enabled` is always set to `true`, meaning the enum option is a selectable value for the custom field. Setting `enabled=false` is equivalent to “trashing” the enum option in the Asana web app within the “Edit Fields” dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.

Enum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using `insert_before` or `insert_after` to reference an existing enum option. Only one of `insert_before` and `insert_after` can be provided when creating a new enum option.

An enum options list can be reordered with the `POST /custom_fields/custom_field_gid/enum_options/insert` endpoint.
gidstringOptionalGlobally unique identifier of the resource, as a string.
Read only: true
resource_typestringOptionalThe base type of this resource.
Read only: true
namestringOptionalThe name of the enum option.
enabledbooleanOptionalWhether or not the enum option is a selectable value for the custom field.
colorstringOptionalThe color of the enum option. Defaults to `none`.
Get a story — response body — data / data / source: web, email, mobile, api, unknown, type: comment, system likes item
FieldTypePresenceDescription and constraints
$objectRootAn object to represent a user's like.
gidstringOptionalGlobally unique identifier of the object, as a string.
Read only: true
userModelOptionalExpand Get users in a team — response body — data data item

Referenced models: Get users in a team — response body — data data item

Get a story — response body — data / data / source: web, email, mobile, api, unknown, type: comment, system previews item
FieldTypePresenceDescription and constraints
$objectRootA collection of rich text that will be displayed as a preview to another app.

This is read-only except for a small group of whitelisted apps.
Read only: true
fallbackstringOptionalSome fallback text to display if unable to display the full preview.
footerstringOptionalText to display in the footer.
headerstringOptionalText to display in the header.
header_linkstringOptionalWhere the header will link to.
html_textstringOptionalHTML formatted text for the body of the preview. See [rich text](/docs/rich-text#reading-rich-text).
textstringOptionalText for the body of the preview.
titlestringOptionalText to display as the title.
title_linkstringOptionalWhere to title will link to.
Search projects in a workspace — response body — data data item
FieldTypePresenceDescription and constraints
$objectRootA *project* represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.
gidstringOptionalGlobally unique identifier of the resource, as a string.
Read only: true
resource_typestringOptionalThe base type of this resource.
Read only: true
namestringOptionalName of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.
resource_subtypestringOptionalThe subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.
Known values: default_project, custom
Get a story — response body — data / data / source: web, email, mobile, api, unknown, type: comment, system reaction summary item
FieldTypePresenceDescription and constraints
$objectRootA summary of an emoji reaction on an object.
emoji_basestringOptionalThe emoji base character used in the reaction.
variantstringOptionalThe full emoji string used in the reaction.
countJSONOptional
count (anyOf 1)numberAlternativeThe number of reactions with the emoji variant on the object.
count (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
reactedbooleanOptionalWhether the current user has reacted with the emoji variant on the object.
Get sections in a project — response body — data, next page data item
FieldTypePresenceDescription and constraints
$objectRootA *section* is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.
gidstringOptionalGlobally unique identifier of the resource, as a string.
Read only: true
resource_typestringOptionalThe base type of this resource.
Read only: true
namestringOptionalThe name of the section (i.e. the text displayed as the section header).

SDK function policy ID: asana.createstoryforgoal. Catalog operation: asana:createStoryForGoal. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Required provider scopes: ["stories:write"]

Official provider source

Report an issue with this page

Necessary

Required for sign-in, security, authorization, and remembering your choices.

Always active

Analytics

Helps us understand which product and documentation features are useful.

Performance diagnostics

Uses performance tracing and privacy-masked session replay to diagnose problems.

You can change these choices at any time from Cookie settings.