Asana: Create a story on a record
Asana stories.createStoryForRecord: arguments, response, policy and SDK examples.
← Stories operations · Get started
Operation asana.createstoryforrecord
Provider route: POST /records/{record_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"]["createStoryForRecord"]>[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.createStoryForRecord(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_record(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.record_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 Update a story — request body — body data |
Referenced models: Update a story — 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
Update a story — request body — body data
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A story represents an activity associated with an object in the Asana system. |
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 |
created_at | string | Optional | The time at which this resource was created. Format: date-time Read only: true |
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. Read only: true |
text | string | Optional | The plain text of the comment to add. Cannot be used with html_text. |
html_text | string | Optional | [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_pinned | boolean | Optional | *Conditional*. Whether the story should be pinned on the resource. |
sticker_name | string | Optional | The 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
| 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). |
Policy, approvals and errors
Section titled “Policy, approvals and errors”SDK function policy ID: asana.createstoryforrecord. Catalog operation: asana:createStoryForRecord. 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"]