Log inSign upBook a demo
Tines Stories
  1. API
  2. Stories
  3. Change request
  1. API
  2. Stories
  3. Change request

Promote

Last updated Open markdown version

Description

Promote changes to the live story.

Request

HTTP Method: POST

Query Parameter Description
change_request_id The ID of the change request
bypass_approval Optional Boolean. Defaults to false. When true, a pending (not yet approved) change request is promoted straight to the live story, skipping the approval step. Requires permission to promote on the story's team (STORY_MANAGE).
bypass_approval_reason Optional String. A human-readable reason recorded in the audit trail. When bypass_approval is true and no reason is supplied, the recorded message defaults to "Approval bypassed via API".
delete_draft Optional Boolean. Defaults to false. When true, the draft used for the change request is deleted after promotion, matching the web app behavior. When false, the draft is left on the story.
Path Parameter Description
story_id The ID of the story.

Note: Bypassing approval is the supported way for a single API identity to push a change live when your tenant has "Require approval for all changes" enabled, since a user cannot approve their own change request under that setting. Bypassing uses the same permission gate as a normal promotion, so the calling user needs permission to promote on the story's team (STORY_MANAGE); there is no separate bypass permission. A bypass is recorded distinctly in the audit trail and triggers a notification, so it is logged separately from a normal promotion.

Sample request

curl -X POST \
  https://<tenant-domain>/api/v1/stories/<<story_id>>/change_request/promote  \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>' \
  -d '{
        "change_request_id": "<<change_request_id>>"
      }'

Response

A successful request will return a JSON object representing 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.
entry_agent_id The ID of the entry action for this story.
exit_agents An Array of objects describing exit actions for this story.
send_to_story_skill_use_requires_confirmation Boolean flag indicating whether workbench should ask for confirmation before running 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
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.
api_enabled Boolean flag indicating if Webhook API is enabled.
api_entry_actions Array of entry action ID for API enabled story.
api_exit_actions Array of exit action IDs for API enabled story.
api_name Name of API for API enabled story.
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.

Sample response

{
  "name": "Simple story",
  "user_id": 167,
  "description": "In the simple story we will create a fictional situation where a detection system is configured to send alerts to our Tines tenant",
  "keep_events_for": 604800,
  "disabled": false,
  "priority": false,
  "send_to_story_enabled": false,
  "send_to_story_access_source": "OFF",
  "send_to_story_access": null,
  "shared_team_slugs": [],
  "entry_agent_id": null,
  "exit_agents": [],
  "send_to_story_skill_use_requires_confirmation": true,
  "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",
  "monitor_failures": false,
  "actions_with_monitoring": [],
  "recipients": [
    {
      "address": "test@example.com"
    }
  ],
  "api_enabled": false,
  "api_entry_actions": [],
  "api_exit_actions": [],
  "api_name": null,
  "id": 7981,
  "folder_id": 1,
  "published": true,
  "change_control_enabled": false,
  "locked": false,
  "owners": [1]
}
Was this helpful?