Asana: Create a story on a task
Asana stories.createStoryForTask: arguments, response, policy and SDK examples.
← Stories operations · Get started
Operation asana.createstoryfortask
Provider route: POST /tasks/{task_gid}/stories. Alter supplies the connection’s credentials and routing.
Call through Alter
Section titled “Call through Alter”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"]["createStoryForTask"]>[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.createStoryForTask(input); const result = await call.wait(); return result.bodyJson(); } finally { await app.close(); }}import osfrom alter_sdk import Appfrom 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_task(arguments) result = await call.wait() return result.body_json()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
path | object | Required within parent | Additional keys: not allowed |
path.task_gid | string | Required within parent | |
query | Model | Optional | Expand Get a story — request body — query |
body | object | Required within parent | |
body.data | Model | Optional | Expand Create a story on a task — request body — body data |
Referenced models: Create a story on a task — request body — body data, Get a story — request body — query
Response
Section titled “Response”Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | |
$ (allOf 1) | object | All variants apply | |
$ (allOf 1).data | Model | Optional | Expand Get a story — response body — data data — Story Response |
$ (allOf 2) | Model | All variants apply | Expand Get a story — response body — data |
Referenced models: Get a story — response body — data data — Story Response, Get a story — response body — data
Schemas
Section titled “Schemas”23 more schemas are linked from the tables above, on the schema pages.
Get a story — response body — data
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
data | Model | Required within parent | Expand Get a story — response body — data data — sdk__Story Response |
Referenced models: Get a story — response body — data data — sdk__Story Response
Create a story on a task — request body — body data
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | |
$ (allOf 1) | Model | All variants apply | Expand Update a story — request body — body data |
$ (allOf 2) | object | All variants apply | |
$ (allOf 2).parent_comment | string | Optional | The GID of the top-level comment envelope to reply to, exposed as `comment_gid` on story reads. This is not the story `gid`. Retrieve it with `GET /stories/{story_gid}?opt_fields=comment_gid`. The parent must belong to the task in the request URL and must not itself be a reply. Works with either `text` or `html_text`. Omit this input to create a top-level comment. |
Referenced models: Update a story — request body — body data
Get a story — request body — query
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
opt_pretty | boolean | Optional | |
opt_fields | array | Optional | |
opt_fields[] | string | Each item | One 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
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Enum 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. |
gid | string | Optional | Globally unique identifier of the resource, as a string. Read only: true |
resource_type | string | Optional | The base type of this resource. Read only: true |
name | string | Optional | The name of the enum option. |
enabled | boolean | Optional | Whether or not the enum option is a selectable value for the custom field. |
color | string | Optional | The 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
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | An object to represent a user's like. |
gid | string | Optional | Globally unique identifier of the object, as a string. Read only: true |
user | Model | Optional | Expand 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
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A 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 |
fallback | string | Optional | Some fallback text to display if unable to display the full preview. |
footer | string | Optional | Text to display in the footer. |
header | string | Optional | Text to display in the header. |
header_link | string | Optional | Where the header will link to. |
html_text | string | Optional | HTML formatted text for the body of the preview. See [rich text](/docs/rich-text#reading-rich-text). |
text | string | Optional | Text for the body of the preview. |
title | string | Optional | Text to display as the title. |
title_link | string | Optional | Where to title will link to. |
Search projects in a workspace — response body — data data item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A *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. |
gid | string | Optional | Globally unique identifier of the resource, as a string. Read only: true |
resource_type | string | Optional | The base type of this resource. Read only: true |
name | string | Optional | Name 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_subtype | string | Optional | The 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
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A summary of an emoji reaction on an object. |
emoji_base | string | Optional | The emoji base character used in the reaction. |
variant | string | Optional | The full emoji string used in the reaction. |
count | JSON | Optional | |
count (anyOf 1) | number | Alternative | The number of reactions with the emoji variant on the object. |
count (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
reacted | boolean | Optional | Whether the current user has reacted with the emoji variant on the object. |
Get sections in a project — response body — data, next page data item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A *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. |
gid | string | Optional | Globally unique identifier of the resource, as a string. Read only: true |
resource_type | string | Optional | The base type of this resource. Read only: true |
name | string | Optional | The name of the section (i.e. the text displayed as the section header). |
Get a task's tags — response body — data, next page data item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A *tag* is a label that can be attached to any task in Asana. It exists in a single workspace or organization. |
gid | string | Optional | Globally unique identifier of the resource, as a string. Read only: true |
resource_type | string | Optional | The base type of this resource. Read only: true |
name | string | Optional | Name of the tag. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer. |
Policy, approvals and errors
Section titled “Policy, approvals and errors”SDK function policy ID: asana.createstoryfortask. Catalog operation: asana:createStoryForTask. 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"]