---
title: Update
url: https://www.tines.com/docs/api/stories/update/
updated: 2026-01-15T14:21:36+00:00
description: Update a story. Defaults to a draft called `test` if change control is enabled on the story and no draft_id is provided.
---
*[tines.com](https://www.tines.com/llms.txt) › [Docs](https://www.tines.com/llms.txt) › [Tines API](https://www.tines.com/llms.txt) › [Stories](https://www.tines.com/llm/docs/api/stories.md)*
# Update
*[View on tines.com](https://www.tines.com/docs/api/stories/update/)*
## Description
Update a story. Defaults to a draft called `test` if change control is enabled on the story and no draft_id is provided.
## Request
HTTP Method: **PUT**
| Query Parameter | Description |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| name | **Optional** The story name. |
| description | **Optional** A user-defined description of the story. |
| add_tag_names | **Optional** An array of tag names to add to the story. |
| remove_tag_names | **Optional** An array of tag names to remove from the story. |
| keep_events_for | **Optional** Event retention period in seconds:
1 hour: `3600`
6 hours: `21600`
1 day: `86400`
3 days: `259200`
7 days: `604800`
14 days: `1209600 `
30 days:`2592000`
60 days:`5184000`
90 days:`7776000`
180 days:`15552000`
365 days: `31536000` |
| disabled | **Optional** Boolean flag indicating whether the story is disabled from running. |
| locked | **Optional** Boolean flag indicating whether the story is locked, preventing edits. |
| priority | **Optional** Boolean flag indicating whether story runs with high priority. |
| webhook_api_enabled | **Optional** Boolean flag indicating if webhook API is enabled. If enabling, the `api_entry_action_id` and `api_exit_action_ids` parameters must also be specified. The `draft_id` can also be provided if the change is being made to a non-live story. |
| api_entry_action_id | **Optional** The ID of the entry action for this API enabled story (action must be of type webhook). `api_exit_action_ids` must also be provided and `webhook_api_enabled` must be set to true. |
| api_exit_action_ids | **Optional** An array of IDs describing exit actions for this API enabled story (actions must be message-only mode event transformation). `api_entry_action_id` must also be provided and `webhook_api_enabled` must be set to true. |
| send_to_story_access_source | **Optional** `STS`, `STS_AND_WORKBENCH`, `WORKBENCH` or `OFF` indicating if send to story is enabled and where the send to story can be used. If enabling send to story, the `entry_action_id` and `exit_action_ids` parameters must also be specified. |
| entry_action_id | **Optional** The ID of the entry action for this send to story enabled story (action must be of type webhook). `exit_action_ids` must also be provided and `send_to_story_access_source` must be set to `STS`, `STS_AND_WORKBENCH` or `WORKBENCH`. |
| exit_action_ids | **Optional** An array of IDs describing exit actions for this send to story enabled story (actions must be message-only mode event transformation). `entry_action_id` must also be provided and `send_to_story_access_source` must be set to `STS`, `STS_AND_WORKBENCH` or `WORKBENCH`. |
| send_to_story_access | **Optional** Controls who is allowed to send to this story (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). default to `TEAM`. If using `SPECIFIC_TEAMS` must also specify list of teams' slugs in `shared_team_slugs`. |
| shared_team_slugs | **Optional** List of teams' slugs that can send to this story. Required to set `send_to_story_access` to `SPECIFIC_TEAMS`. Defaults to `[]` (empty array). |
| send_to_story_skill_use_requires_confirmation | **Optional** Boolean flag indicating whether workbench should ask for confirmation before running this story. Story must be enabled for workbench or send to story and workbench. |
| team_id | **Optional** The ID of the team to move the story to. |
| folder_id | **Optional** The ID of the folder to move the story to, or an empty value to indicate the root folder. Note that this folder must exist within the team identified by `team_id`, or the story's current team if `team_id` isn't specified. |
| change_control_enabled | **Optional** Boolean flag indicating if change control is enabled. |
| draft_id | **Optional** The ID of the draft to update. [About drafts](https://www.tines.com/docs/stories/change-control/#api-endpoints). |
| monitor_failures | **Optional** Boolean flag indicating if monitor failures is enabled on the story. |
| Path Parameter | Description |
| -------------- | -------------------- |
| story_id | The ID of the story. |
### Sample request
```bash
curl -X PUT \
https:///api/v1/stories/<> \
-H 'content-type: application/json' \
-H 'Authorization: Bearer <>' \
-d '{
"name": "Updated Simple story",
"description": "Updates story description"
}'
```
## Response
A successful request will return a JSON object describing the updated story
### Field description
| Parameter | Description |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | The story name. |
| user_id | ID of story creator. |
| description | A user-defined description of the story. |
| keep_events_for | Defined event retention period in seconds. |
| disabled | Boolean flag indicating whether story is disabled. |
| priority | Boolean flag indicating whether story is high priority story. |
| send_to_story_enabled | Boolean flag indicating if send to story is enabled. |
| send_to_story_access_source | `STS`, `STS_AND_WORKBENCH`, `WORKBENCH` or `OFF` indicating where the send to story can be used. |
| send_to_story_access | Controls who is allowed to send to this story (`TEAM`,`GLOBAL`,`SPECIFIC_TEAMS`). |
| send_to_story_referring_story_ids | List of story ids that call this Send to Story enabled story. Only present when `send_to_story_enabled` is `true`. |
| shared_team_slugs | List of teams' slugs that can send to this story when `send_to_story_access` is `SPECIFIC_TEAMS`, otherwise empty. |
| send_to_story_skill_use_requires_confirmation | Boolean flag indicating whether workbench should ask for confirmation before running this story. |
| entry_agent_id | The ID of the entry action for this story. |
| exit_agents | An array of objects describing exit actions for this story. |
| team_id | ID of team to which the story belongs. |
| tags | An array of tags used to classify the story. |
| guid | Unique identifier of the story. |
| slug | An underscored representation of the story name. |
| created_at | ISO 8601 timestamp representing date and time the story was created. |
| updated_at | ISO 8601 timestamp representing date and time the story row was last updated. It is best to use edited_at to track any modifications made to the story itself. |
| edited_at | ISO 8601 timestamp representing date and time the story was last logically updated. |
| mode | The mode of the story. `LIVE` or `TEST` |
| id | The story ID. |
| folder_id | ID of folder to which the story belongs. |
| published | Boolean flag indicating whether the story is published. |
| change_control_enabled | Boolean flag indicating if change control is enabled. |
| locked | Boolean flag indicating whether the story is locked to changes. |
| owners | List of user IDs that are listed as owners on the story. |
| draft_id | ID of the updated draft. |
| draft_name | Name of the updated draft. |
| monitor_failures | Boolean flag indicating if monitor failures is enabled on all actions in the story. This will be false when only some actions have monitoring enabled. |
| actions_with_monitoring | List of action IDs with monitoring enabled. |
| recipients | List of monitoring recipients for the story. |
### Sample response
```json
{
"name": "Updated Simple story",
"user_id": 167,
"description": "Updates story description",
"keep_events_for": 604800,
"disabled": false,
"priority": false,
"send_to_story_enabled": false,
"send_to_story_access_source": "OFF",
"send_to_story_access": null,
"send_to_story_skill_use_requires_confirmation": true,
"shared_team_slugs": [],
"entry_agent_id": null,
"exit_agents": [],
"team_id": 1,
"tags": ["Tag 1", "Tag 2"],
"guid": "df1e838a18d20696120b41516497b017",
"slug": "simple_story",
"created_at": "2021-05-10T08:56:50Z",
"updated_at": "2021-05-10T08:56:50Z",
"edited_at": "2021-05-10T08:56:50Z",
"mode": "LIVE",
"id": 7981,
"folder_id": 1,
"published": true,
"change_control_enabled": false,
"locked": false,
"owners": [1],
"draft_id": 1234,
"draft_name": "Updated Draft",
"monitor_failures": false,
"actions_with_monitoring": [],
"recipients": [
{
"address": "test@example.com"
}
]
}
```
### Sample request to enable send to story
```bash
curl -X PUT \
https:///api/v1/stories/<> \
-H 'content-type: application/json' \
-H 'Authorization: Bearer <>' \
-d '{
"entry_action_id": "<>",
"exit_action_ids": ["<>"],
"send_to_story_access_source": "STS"
}'
```