Description
Create a story recipient for a story. The recipients will receive story monitoring communications when enabled.
Request
HTTP Method: POST
| Query Parameter | Description |
|---|---|
| story_id | ID of the story in which the story recipient should be created. |
| address | The email or webhook URL that should receive story monitoring communications. |
| draft_id | Optional The ID of the draft to update. About drafts. |
Sample request
curl -X POST \
https://<<META.tenant.domain>>/api/v1/stories/<<story_id>>/recipients \
-H 'content-type: application/json' \
-H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>' \
-d '{
"address": "alice@example.com"
}'
## Response
A successful request will return a JSON object describing the story in which the recipient was created.
### 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`). |
| 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. |
| 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
<!-- cspell:disable -->
```json
{
"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,
"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],
"monitor_failures": false,
"actions_with_monitoring": [],
"recipients": [
{
"address": "test@example.com"
}
]
}