NAV

Storyly API

Welcome to the Storyly API! You can use Storyly API to manage your Storyly Apps, Story Groups, Stories, Sub Users and Audiences via HTTP requests.

Getting Started

To use the Storyly API, you will need to create a unique API Token from dashboard.

Login to dashboard, navigate to Settings > Account Settings page, where you can create or update your API token.

This token provides read and write access to your account, so do not share or distribute it. Grant access only to those who need it. Ensure it is kept out of any version control system you may be using.

Endpoints

curl \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    "https://api.storyly.io/external/story-group?token=your_token_here"

Make sure to replace your_token_here with your API token.

Storyly API base URL is: https://api.storyly.io/external

Currently available endpoints are: /app, /instance, /segment, /story_group, /story, /sub-user, /audience

Token should be provided on query string of each API request, such as: https://api.storyly.io/external/story-group?token=your_token_here

All post / patch request bodies should be in JSON format and Content-Type: applicaton/json should be added to request header.

Available filters and parameters (will be described in detail below) can be added to query string.

Storyly App

Your apps that will host Storyly is defined as Storyly App.

Storyly App Entity

{
    "id": 1,
    "account_id": 1,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ",
    "title": "My iOS App",
    "store_id": "1234567890",
    "store_type": "ios",
    "category": "",
    "detailed_info" : {
        "title": "My iOS App",
        "category": "",
        "icon":  "https://prod-storyly-media.s3-eu-west-1.amazonaws.com/html-templates/appIcon.png",
        "developer": "",
        "market_url": "",
        "store": "ios"
    },
    "settings": null,
    "ts_created": "2020-07-09 08:15:00",
    "ts_updated": "2020-07-09 08:15:00"
}
Field Type Description
id integer Internal ID of the app.
account_id integer Internal ID of the account the app belongs to.
token string Token of the app.
title integer Title of the app.
store_id string Apple or Android Store ID or Web URL of the app.
store_type string Apple, Android or Web Store Type of the app.
category string Category of the app.
detailed_info JSON Detailed info about the app.
icon string URL of the app icon.
settings JSON Settings of the app.
ts_created date Date app was created.
ts_updated date Date app was updated.

Storyly App Endpoint

https://api.storyly.io/external/app

Storyly App Endpoint allows to retrieve list of Storyly Apps.

List Storyly Apps

curl \
    --header 'Content-Type: application/json' \
    --request GET \
    'https://api.storyly.io/external/app?token=your_token_here'

The above command returns JSON structured like this:

{
    "status": "ok",
    "message": "success",
    "data": [
        {
            "id": 1,
            "account_id": 1,
            "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ",
            "title": "My iOS App",
            "store_id": "1234567890",
            "store_type": "ios",
            "category": "",
            "detailed_info" : {
                "title": "My iOS App",
                "category": "",
                "icon":  "https://prod-storyly-media.s3-eu-west-1.amazonaws.com/html-templates/appIcon.png",
                "developer": "",
                "market_url": "",
                "store": "ios"
            },
            "settings": null,
            "ts_created": "2020-07-09 08:15:00",
            "ts_updated": "2020-07-09 08:15:00"
        }
    ]
}

HTTP Request

GET https://api.storyly.io/external/app?token=your_token_here

Storyly Instance

Your app instances that will host story groups in the Storyly App.

Storyly Instance Entity

{
    "id": 1,
    "account_id": 1,
    "app_id": 1,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ",
    "title": "New Instance",
    "status": 1,
    "ts_created": "2020-07-09 08:15:00",
    "ts_updated": "2020-07-09 08:15:00",
    "is_sharable": true
}
Field Type Description
id integer Internal ID of the instance.
account_id integer Internal ID of the account the instance belongs to.
app_id integer Internal ID of the app the instance belongs to.
token string Token of the instance.
title integer Title of the instance.
status integer Status of the instance.
is_sharable boolean Sharable status of the instance.
ts_created date Date instance was created.
ts_updated date Date instance was updated.

Storyly Instance Endpoint

https://api.storyly.io/external/instance

Storyly Instance Endpoint allows to retrieve list of Storyly Instances.

List Storyly Instances

curl \
    --header 'Content-Type: application/json' \
    --request GET \
    'https://api.storyly.io/external/instance?token=your_token_here'

The above command returns JSON structured like this:

{
    "status": "ok",
    "message": "success",
    "data": [
        {
            "id": 1,
            "account_id": 1,
            "app_id": 1,
            "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ",
            "title": "New Instance",
            "status": 1,
            "ts_created": "2020-07-09 08:15:00",
            "ts_updated": "2020-07-09 08:15:00",
            "is_sharable": true
        }
    ]
}

HTTP Request

GET https://api.storyly.io/external/instance?token=your_token_here

Segment

Segments are used for targeting users to specific stories. It is a label containing strings.

Segment Entity

{
    "account_id": 1,
    "label": "label_example",
    "is_used": false
}
Field Type Description
account_id integer Account ID the label belongs to.
label string Label.
is_used boolean Label's usage status.

Segment Endpoints

https://api.storyly.io/external/segment

Segment Endpoint allows list, create and delete actions.

Create a Segment

Create a new segment.

curl \
    --header 'Content-Type: application/json' \
    --request POST \
    --data-raw '{
        "label": "label_example"
    }' \
    'https://api.storyly.io/external/segment?token=your_token_here'

HTTP Request

POST https://api.storyly.io/external/segment?token=your_token_here

Required Body Parameters: label.

List Segments

This endpoint lists segemnts of the given account.

curl \
    --header 'Content-Type: application/json' \
    --request GET \
    'https://api.storyly.io/external/segment?token=your_token_here'

The above command returns JSON structured like this:

{
    "status": "ok",
    "message": "success",
    "data": [
        {
            "account_id": 1,
            "label": "label_example",
            "is_used": false
        }
    ]
}

HTTP Request

GET https://api.storyly.io/external/segment?token=your_token_here

Delete a Specific Segment

curl \
    --header 'Content-Type: application/json' \
    --request DELETE \
    'https://api.storyly.io/external/segment?token=your_token_here&label=label_example'

This endpoint deletes a specific segment. Entities will be deleted permanently.

HTTP Request

DELETE 'https://api.storyly.io/external/segment?token=your_token_here&label=label_example'

URL Parameters

Parameter Description
label Label to be deleted.

Story Group

Story groups are used to categorize stories. A story group contains up to 100 stories.

Each story group has a unique identifier, a title, an icon (shown in Storyly bar), an index to position where it is in the Storyly bar, and the stories in it. Story groups in Storyly view are dynamically ordered, when a user watches all stories in a story group, that group is placed at the end of the bar unless it is pinned. Story Group Segments payload has AND & OR logic. Labels can use be used as exclude or include labels and should always be string (in quotes).
Examples:
1. include "label1" -> "segments": [ { "type": "include", "labels": ["label1"] } ]
2. include "label1 AND label2" -> "segments": [ { "type": "include", "labels": ["label1"] }, { "type": "include", "labels": ["label2"] } ]
3. include "label1 OR label2" -> "segments": [ { "type": "include", "labels": ["label1", "label2"] } ]
4. include "label1" AND ("label2" OR "label3") -> "segments": [ { "type": "include", "labels": ["label1"] }, { "type": "include", "labels": ["label2", "label3"] } ]
5. exclude "label1" -> "segments": [ { "type": "exclude", "labels": ["label1"] } ]
6. include ("label1" OR "label2") AND exclude label3 -> "segments": [ { "type": "include", "labels": ["label1", "label2"] }, { "type": "exclude", "labels": ["label3"] } ]

Story Group Entity

{
    "id": 1,
    "app_id": 1,
    "instance_id": 1,
    "account_id": 1,
    "user_id": 1,
    "title": "Test Story Group",
    "icon": "https://db62cod6cnasq.cloudfront.net/user-media/1044/a6b1932c53fedeb801cb7a0d6c038be4.jpg",
    "available_icons" : {
        "jpeg": "https://qa-storyly-media.s3.amazonaws.com/user-media/103/sg4930/1607272172.jpeg",
        "webp": "https://qa-storyly-media.s3.amazonaws.com/user-media/103/sg4930/1607272172.webp",
    },
    "target_cap": 1000,
    "clicked_target_cap": 1000,
    "pinned": 0,
    "sort_order": 1,
    "settings" : {
        "audience_id": 1,
        "audience_mapping": [
          {
              "placeholder": "{Text_1}",
              "value": "Area",
              "type": "sync"
          }
        ]
    },
    "segments": [{"type":"include", "labels": ["segment1","segment2"]}],
    "status": 1,
    "type": "audience",
    "views": 5003,
    "clicks": 5003,
    "settings" : {
    "audience_id": 1,
    "template": {
        "id": 1,
        "max_story_count": 10
    },
    "ts_start": "2020-07-09 08:15:00",
    "ts_end": null,
    "ts_created": "2020-07-09 08:15:00",
    "ts_updated": "2020-07-09 08:15:00"
}
Field Type Description
id integer Internal ID of the story group.
app_id integer Internal ID of the app this story group attached.
instance_id integer Internal ID of the instance this story group attached.
user_id integer Internal ID of the user this story group was created by.
title string Title of the story group.
icon string URL of the story group icon.
available_icons JSON JPEG and WEBP versions of the story group icon
target_cap integer Target view cap. Story group will be paused when view count reaches cap.
clicked_target_cap integer Clicked target view cap. Story group will be paused when view count reaches cap.
pinned boolean Pin status of the story group.
sort_order integer Order of the story group.
segments array An array of strings, your story groups will be segmented using these segments. Available in Storyly SDK 1.3.0 and later.
settings JSON Settings of the story group.
audience_mapping JSON Audience mapping of the story group with the "audience" type.
audience_id integer Internal ID of the audience used to create the "audience" story group.
status integer Status of the story group. Only ACTIVE story groups will be displayed by SDK.
Possible values:
ACTIVE = 1,
PASSIVE = 2,
CAP_REACHED = 3,
END_DATE_REACHED = 4,
ARCHIVED = 9
type string Type of the story group.
Possible values:
default,
audience
views integer View count of the story group.
Will be filled by system, do not post this field when creating / updating a story.
clicks integer Click count of the story group.
Will be filled by system, do not post this field when creating / updating a story.
template JSON Template information of the "audience" story group.
Will be filled by system, do not post this field when creating / updating a story.
ts_start date Start date of the story group. Story group will not be displayed by SDK if this date is not reached.
ts_end date End date of the story group. Story group will not be displayed by SDK after this date is reached. Set as null if you do not want to set an end date.
ts_created date Date story group was created.
Will be filled by system, do not post this field when creating / updating a story.
ts_updated date Date story group was updated.
Will be filled by system, do not post this field when creating / updating a story.
media_url string URL of the story image.
Required if file is empty

Story Group Endpoints

https://api.storyly.io/external/story-group

Story Group Endpoint allows list, create, update and delete actions.

Create a Story Group

Create a new story group on given storyly instance.

curl \
    --header 'Content-Type: multipart/form-data' \
    --request POST \
    --form 'file=@"path/to/image.jpeg"' \
    --form 'data="{
      \"title\": \"Test Story Group\",
      \"app_id\": 1,
      \"ts_start\": \"2020-07-09 08:15:00\",
      \"ts_end\": null,
      \"target_cap\": null,
      \"click_target_cap\": null,
      \"status\": 1,
      \"segments\": null,
      \"cta_macro\": null,
      \"instagram_import\": false
    }";type=application/json' \
    'https://api.storyly.io/external/story-group?token=your_token_here'

HTTP Request

POST https://api.storyly.io/external/story-group?token=your_token_here

Required Body Parameters: app_id, title, file.

Additional Body Parameters: type can be specified. By default all story groups are in type "default". In order to create a story group with type "audience", first, the audience should be created for the user through the audience endpoints. sub_user_id can be given to specify which sub user will see the story groups. Both data and file should be sent with multipart/form-data header, where data is a JSON-string with application/json content type. Instead of file it is possible to send media_url field inside the data.

Get a Specific Story Group

This endpoint retrieves a specific story group by story group id.

curl \
    --header 'Content-Type: application/json' \
    --request GET \
    'https://api.storyly.io/external/story-group?token=your_token_here&story_group_id=1'

The above command returns JSON structured like this:

{
  "id": 1,
  "app_id": 1,
  "instance_id": 1,
  "account_id": 1,
  "user_id": 1,
  "title": "Test Story Group",
  "icon": "https://db62cod6cnasq.cloudfront.net/user-media/1044/a6b1932c53fedeb801cb7a0d6c038be4.jpg",
  "available_icons" : {
      "jpeg": "https://qa-storyly-media.s3.amazonaws.com/user-media/103/sg4930/1607272172.jpeg",
      "webp": "https://qa-storyly-media.s3.amazonaws.com/user-media/103/sg4930/1607272172.webp",
  },
  "target_cap": 1000,
  "clicked_target_cap": 1000,
  "pinned": 0,
  "sort_order": 1,
  "settings" : {
      "audience_id": 1,
      "audience_mapping": [
        {
            "placeholder": "{Text_1}",
            "value": "Area",
            "type": "sync"
        }
      ]
  },
  "segments": [{"type":"include", "labels": ["segment1","segment2"]}],
  "status": 1,
  "type": "audience",
  "views": 5003,
  "clicks": 5003,
  "settings" : {
  "audience_id": 1,
  "template": {
      "id": 1,
      "max_story_count": 10
  },
  "ts_start": "2020-07-09 08:15:00",
  "ts_end": null,
  "ts_created": "2020-07-09 08:15:00",
  "ts_updated": "2020-07-09 08:15:00"
}

HTTP Request

GET https://api.storyly.io/external/story-group?token=your_token_here&story_group_id=1

URL Parameters

Parameter Description
story_group_id The ID of the story group to retrieve

List Story Groups

This endpoint lists story groups of the given sub user or the account.

curl \
    --header 'Content-Type: application/json' \
    --request GET \
    'https://api.storyly.io/external/story-group?token=your_token_here&sub_user_id=4'

The above command returns JSON structured like this:

{
    "status": "ok",
    "message": "success",
    "data": [
        {
            "id": 1,
            "app_id": 1,
            "instance_id": 1,
            "account_id": 1,
            "user_id": 1,
            "title": "Test Story Group",
            "icon": "https://db62cod6cnasq.cloudfront.net/user-media/1044/a6b1932c53fedeb801cb7a0d6c038be4.jpg",
            "available_icons" : {
                "jpeg": "https://qa-storyly-media.s3.amazonaws.com/user-media/103/sg4930/1607272172.jpeg",
                "webp": "https://qa-storyly-media.s3.amazonaws.com/user-media/103/sg4930/1607272172.webp",
            },
            "target_cap": 1000,
            "clicked_target_cap": 1000,
            "pinned": 0,
            "sort_order": 1,
            "settings" : {
                "audience_id": 1,
                "audience_mapping": [
                  {
                      "placeholder": "{Text_1}",
                      "value": "Area",
                      "type": "sync"
                  }
                ]
            },
            "segments": [{"type":"include", "labels": ["segment1","segment2"]}],
            "status": 1,
            "type": "audience",
            "views": 5003,
            "clicks": 5003,
            "settings" : {
            "audience_id": 1,
                "template": {
                    "id": 1,
                    "max_story_count": 10
                }
            },
            "ts_start": "2020-07-09 08:15:00",
            "ts_end": null,
            "ts_created": "2020-07-09 08:15:00",
            "ts_updated": "2020-07-09 08:15:00"
        },
        {
            "id": 1,
            "app_id": 1,
            "instance_id": 1,
            "account_id": 1,
            "user_id": 1,
            "title": "Test Story Group",
            "icon": "https://db62cod6cnasq.cloudfront.net/user-media/1044/a6b1932c53fedeb801cb7a0d6c038be4.jpg",
            "available_icons" : {
                "jpeg": "https://qa-storyly-media.s3.amazonaws.com/user-media/103/sg4930/1607272172.jpeg",
                "webp": "https://qa-storyly-media.s3.amazonaws.com/user-media/103/sg4930/1607272172.webp",
            },
            "target_cap": 1000,
            "clicked_target_cap": 1000,
            "pinned": 0,
            "sort_order": 1,
            "segments": [{"type":"include", "labels": ["segment1","segment2"]}],
            "status": 1,
            "type": "default",
            "views": 5003,
            "clicks": 5003,
            "settings" : {},
            "template": {},
            "ts_start": "2020-07-09 08:15:00",
            "ts_end": null,
            "ts_created": "2020-07-09 08:15:00",
            "ts_updated": "2020-07-09 08:15:00"
        }
    ]
}

HTTP Request

GET https://api.storyly.io/external/story-group?token=your_token_here&sub_user_id=4

URL Parameters

Parameter Description
sub_user_id Retrieve story groups of the specific sub user

Update a Specific Story Group

This endpoint updates a specific story group.

curl \
    --header 'Content-Type: multipart/form-data' \
    --request PATCH \
    --form 'file=@"path/to/image.jpeg"' \
    --form 'data="{
      \"title\": \"Test Story Group\",
      \"app_id\": 1,
      \"ts_start\": \"2020-07-09 08:15:00\",
      \"ts_end\": null,
      \"target_cap\": null,
      \"click_target_cap\": null,
      \"status\": 1,
      \"sort_order\": 1,
      \"segments\": null,
      \"cta_macro\": null
    }";type=application/json' \
    'https://api.storyly.io/external/story-group?token=your_token_here&story_group_id=1'

HTTP Request

PATCH https://api.storyly.io/external/story-group?token=your_token_here&story_group_id=1

URL Parameters

Parameter Description
story_group_id The ID of the story group to update (Required)

Delete a Specific Story Group

curl \
    --header 'Content-Type: application/json' \
    --request DELETE \
    'https://api.storyly.io/external/story-group?token=your_token_here&story_group_id=1&app_id=1'

This endpoint deletes a specific story group. Entities will be deleted permanently.

HTTP Request

DELETE 'https://api.storyly.io/external/story-group?token=your_token_here&story_group_id=1&app_id=1'

URL Parameters

Parameter Description
story_group_id The ID of the story group to delete (Required)
app_id The ID of app the story group is connected to

Story

Stories are full-screen media that can be images, GIFs or videos. Regular image and GIF stories are displayed for 7 seconds and videos are displayed for 15 seconds.

Each story has a unique identifier, a title (set to story group’s title by default), a media component, an index to position where it is in the story group, and seen/unseen information to enable end-users to continue viewing the story group where they left off.

Story Entity

{
    "id": 1,
    "account_id": 1,
    "story_group_id": 1,
    "type": 1,
    "title": "Test Story",
    "sort_order": 1,
    "media": "https://db62cod6cnasq.cloudfront.net/user-media/1044/a6b1932c53fedeb801cb7a0d6c038be4.jpg",
    "media_raw": "https://db62cod6cnasq.cloudfront.net/user-media/1044/a6b1932c53fedeb801cb7a0d6c038be4.jpg",
    "mime_type": "image/jpeg",
    "target_cap": 1000,
    "button_text": "Click Here",
    "outlink": "https://google.com",
    "deep_link": "app://s=1",
    "settings": {
      "mapping": [{
        "placeholder": "{text}",
        "value": "James"
      }],
      "template_id": 1
    },
    "status": 1,
    "studio": null,
    "studio_image": null,
    "views": 5000,
    "ts_start": "2020-07-09 08:15:00",
    "ts_end": null,
    "ts_created": "2020-07-09 08:15:00",
    "ts_updated": "2020-07-09 08:15:00"
}
Parameter Type Description
id integer Internal ID of the story.
account_id integer Internal ID of the account.
story_group_id integer Internal ID of the story group this story is attached.
type integer Media type of the story.
Possible values:
IMAGE = 1
VIDEO = 2
TEMPLATE = 3
Will be filled by system, do not post this field when creating / updating a story.
title string Title of the story.
sort_order integer Order of the story.
media string URL of the optimized media.
media_raw string URL of the original media.
studio JSON Studio parameter of the story.
studio_image string The image of the studio.
mime_type string Mime Type of the media. image/jpeg, video/mp4.
Will be filled by system, do not post this field when creating / updating a story.
target_cap integer Target view cap. Story will be paused when view count reaches cap.
button_text string CTA Button text.
outlink string CTA Button link.
deep_link string Deep link of the story.
Will be filled by system, do not post this field when creating / updating a story.
settings object Additonal story settings.
template_id integer This field can be used inside settings parameter. ID of the template to be used
mapping object This field can be used inside settings parameter. It should be used with template_id parameter. Mapping data for the template
placeholder string This field should be used inside mapping parameter. Placeholder key for the template mapping.
Should be identical to the template's keys.
value string This field should be used inside mapping parameter. Value for the template placeholder
status integer Status of the story. Only ACTIVE stories will be displayed by SDK.
Possible values:
ACTIVE = 1
PASSIVE = 2
PASSIVE_BY_STORY_GROUP = 3
END_DATE_REACHED = 4
CAP_REACHED = 5
WAITING_MEDIA_IMPORT = 6
FAILED_MEDIA_IMPORT = 7
ARCHIVED = 9
views integer View count of the story.
Will be filled by system as story recieves impressions, do not post this field when creating / updating a story.
ts_start date Start date of the story. Story will not be displayed by SDK if this date is not reached.
ts_end date End date of the story. Story will not be displayed by SDK after this date is reached. Set as null if you do not want to set an end date.
ts_created date Date story was created.
Will be filled by system, do not post this field when creating / updating a story.
ts_updated date Date story was updated.
Will be filled by system, do not post this field when creating / updating a story.
media_url string URL of the story image.
Required if file is empty

Story Endpoints

https://api.storyly.io/external/story

Story Endpoint allows list, create, update and delete actions.

Create a Story

curl \
    --header 'Content-Type: multipart/form-data' \
    --request POST \
    --form 'file=@"path/to/image.jpeg"' \
    --form 'data="{
      \"title\": \"Test Story Group\",
      \"story_group_id\": 1,
      \"type\": 1,
      \"sort_order\": 1,
      \"target_cap\": null,
      \"status\": 1,
      \"deeplink\": null,
      \"outlink\": \"\""
    }";type=application/json' \
    'https://api.storyly.io/external/story?token=your_token_here'

Create a new story on given story group.

HTTP Request

POST https://api.storyly.io/external/story?token=your_token_here

Required Body Parameters: story_group_id, title, file. The file and data should be sent with the content type multipart/form-data. data should be a JSON-string with type application/json

Get a Specific Story

This endpoint retrieves a specific story by story_id.

curl \
    --header 'Content-Type: application/json' \
    --request GET \
    'https://api.storyly.io/external/story?token=your_token_here&story_id=1'

The above command returns JSON structured like this:

{
    "status": "ok",
    "message": "success",
    "data": {
        "id": 1,
        "account_id": 1,
        "story_group_id": 1,
        "type": 1,
        "title": "Test Story",
        "sort_order": 1,
        "media": "https://db62cod6cnasq.cloudfront.net/user-media/1044/a6b1932c53fedeb801cb7a0d6c038be4.jpg",
        "media_raw": "https://db62cod6cnasq.cloudfront.net/user-media/1044/a6b1932c53fedeb801cb7a0d6c038be4.jpg",
        "mime_type": "image/jpeg",
        "target_cap": 1000,
        "button_text": "Click Here",
        "outlink": "https://google.com",
        "deep_link": "app://s=1",
        "settings": {},
        "status": 1,
        "studio": null,
        "studio_image": null,
        "views": 5000,
        "ts_start": "2020-07-09 08:15:00",
        "ts_end": null,
        "ts_created": "2020-07-09 08:15:00",
        "ts_updated": "2020-07-09 08:15:00"
    }
}

HTTP Request

GET https://api.storyly.io/external/story?token=your_token_here&story_id=150

URL Parameters

Parameter Description
story_id The ID of the story to be retrieved (Required)

List Stories

This endpoint lists stories of the given story group.

curl \
    --header 'Content-Type: application/json' \
    --request GET \
    'https://api.storyly.io/external/story?token=your_token_here&story_group_id=150'

The above command returns JSON structured like this:

{
    "status": "ok",
    "message": "success",
    "data": [
        {
            "id": 1000,
            "story_group_id": 150,
            "type": 1,
            "title": "Test Story",
            "sort_order": 1,
            "media": "https://db62cod6cnasq.cloudfront.net/user-media/1044/a6b1932c53fedeb801cb7a0d6c038be4.jpg",
            "media_raw": "https://db62cod6cnasq.cloudfront.net/user-media/1044/a6b1932c53fedeb801cb7a0d6c038be4.jpg",
            "mime_type": "image/jpeg",
            "target_cap": 1000,
            "button_text": "Click Here",
            "outlink": "https://google.com",
            "deep_link": "app://s=1",
            "settings": {},
            "status": 1,
            "views": 5000,
            "ts_start": "2020-07-09 08:15:00",
            "ts_end": null,
            "ts_created": "2020-07-09 08:15:00",
            "ts_updated": "2020-07-09 08:15:00"
        },
        {
            "id": 1001,
            "story_group_id": 150,
            "type": 1,
            "title": "Test Story",
            "sort_order": 1,
            "media": "https://db62cod6cnasq.cloudfront.net/user-media/1044/a6b1932c53fedeb801cb7a0d6c038be4.jpg",
            "media_raw": "https://db62cod6cnasq.cloudfront.net/user-media/1044/a6b1932c53fedeb801cb7a0d6c038be4.jpg",
            "mime_type": "image/jpeg",
            "target_cap": 1000,
            "button_text": "Click Here",
            "outlink": "https://google.com",
            "deep_link": "app://s=1",
            "settings": {},
            "status": 1,
            "views": 5000,
            "ts_start": "2020-07-09 08:15:00",
            "ts_end": null,
            "ts_created": "2020-07-09 08:15:00",
            "ts_updated": "2020-07-09 08:15:00"
        }, ...
    ]
}

HTTP Request

GET https://api.storyly.io/external/story?token=your_token_here&story_group_id=150

Update a Specific Story

This endpoint updates a specific story.

curl \
    --header 'Content-Type: application/json' \
    --request PATCH \
    --form 'file=@"path/to/image.jpeg"' \
    --form 'data="{
      \"title\": \"Test Story Group\",
      \"story_group_id\": 1,
      \"story_id\": 1,
      \"type\": 1,
      \"sort_order\": 1,
      \"target_cap\": null,
      \"status\": 1,
      \"deeplink\": null,
      \"outlink\": \"\""
    }";type=application/json' \
    'https://api.storyly.io/external/story?token=your_token_here&id=150'

HTTP Request

PATCH https://api.storyly.io/external/story?token=your_token_here

Required Body Parameters

Parameter Description
story_id The ID of the story to update (Required)
story_group_id The ID of the story group attached to the story to update (Required)

Delete a Specific Story

This endpoint deletes a specific story. Entities will be deleted permanently.

curl \
    --header 'Content-Type: application/json' \
    --request DELETE \
    'https://api.storyly.io/external/story?token=your_token_here&story_group_id=1&story_id=1'

HTTP Request

DELETE https://api.storyly.io/external/story?token=your_token_here&story_group_id=1&story_id=1

URL Parameters

Parameter Description
story_id The ID of the story to delete (Required)
story_group_id The ID of the story group attached to the story to delete (Required)

Sub User

Sub User is a user created by the account and has its own audience. Sub User can have its own story groups with the type "audience".

Each sub user has a unique identifier, an user identifier (could be an email) and the audience id (if specified).

Sub User Entity

{
    "id": "f27baf23-063d-49ba-ab68-17133fbf0e5a",
    "user_identifier": "subuser@appsamurai.com",
    "audience_id": 1
}
Parameter Type Description
id string Internal ID of the sub user.
user_identifier string Unique identifier of the sub user.
audience_id integer Internal ID of sub user's audience.

Sub User Endpoints

https://api.storyly.io/external/sub-user

Sub User Endpoint allows create and list actions.

Create a Sub User

curl \
    --header 'Content-Type: application/json' \
    --request POST \
    --data-raw '{
      "user_identifier": "subuser@appsamurai.com"
    }'' \
    'https://api.storyly.io/external/sub-user?token=your_token_here'

Create a new sub user.

HTTP Request

POST https://api.storyly.io/external/story?token=your_token_here

Required Body Parameters: user_identifier.

Get a Specific Sub User

This endpoint retrieves a specific sub user by user_identifier.

curl \
    --header 'Content-Type: application/json' \
    --request GET \
    'https://api.storyly.io/external/sub-user?token=your_token_here&user_identifier=subuser@appsamurai.com'

The above command returns JSON structured like this:

{
    "status": "ok",
    "message": "success",
    "data": {
        "id": "f27baf23-063d-49ba-ab68-17133fbf0e5a",
        "user_identifier": "subuser@appsamurai.com",
        "audience_id": 1
    }
}

HTTP Request

GET https://api.storyly.io/external/sub-user?token=your_token_here&user_identifier=subuser@appsamurai.com

URL Parameters

Parameter Description
user_identifier Unique identifier of the sub user (Required)

Audience

Audience is created with the csv file holding the audience information of the specific sub user. It can be created and attached to the sub user. It is used in the creation of the "audience" story groups.

Each audience has its ID, name, audience identifier and the csv file.

Audience Entity

{
    "id": 1,
    "audience_identifier": "username",
    "name": "audience"
}
Parameter Type Description
id integer Internal ID of the audience.
name string Name of the audience.
audience_identifier string Identifier for mapping the audience with the story group. It is a unique column name from the csv file attached to the audience.

Audience Endpoints

https://api.storyly.io/external/audience

Audience Endpoint allows create and update actions.

Create an Audience {#create-a-audience}

curl \
    --header 'Content-Type: multipart/form-data' \
    --request POST \
    --form 'file=@"path/to/image.jpeg"' \
    --form 'data="{
      \"sub_user_id\": \"f27baf23-063d-49ba-ab68-17133fbf0e5a\",
      \"name\": \"Test Audience\",
      \"audience_identifier\": \"username\"
    }";type=application/json' \
    'https://api.storyly.io/external/audience?token=your_token_here'

Create a new audience.

HTTP Request

POST https://api.storyly.io/external/audience?token=your_token_here

Required Body Parameters: sub_user_id, name, audience_identifier (inside data) and file. Both data and file should be sent with the multipart/form-data content type and data should be a JSON-string with the application/json type.

Update an Audience

This endpoint updates the audience of a specific sub user.

curl \
    --header 'Content-Type: application/json' \
    --request PATCH \
    --form 'file=@"path/to/image.jpeg"' \
    --form 'data="{
      \"sub_user_id\": \"f27baf23-063d-49ba-ab68-17133fbf0e5a\",
      \"name\": \"Test Audience\",
      \"audience_identifier\": \"username\"
    }";type=application/json' \
    'https://api.storyly.io/external/audience?token=your_token_here'

Update an audience.

HTTP Request

PATCH https://api.storyly.io/external/audience?token=your_token_here

Required Body Parameters: sub_user_id. The audience can be updated with name, audience_identifier (inside data) and file. Both data and file should be sent with the multipart/form-data content type and data should be a JSON-string with the application/json type.