SEMSTORM - Content Assitant

Content Assistant API

This document contains basic information how to use SEMSTORM Content Assistant API v3.

Documentation

Every functionality contains examples in curl. For curl -as any other than prepared sdk library- remember that SEMSTORM API guarantee compatibility only for JSON formatted data.

Article

Create article

Endpoint:
https://api.semstorm.com/api-v3/content-assistant/article/create [POST]

Parameters   PHP  CURL 
parameter method type required default  description
title POST string no - Title of article.
language POST string no Language of article in short format. Example values: "en", "pl".
content POST string no - Content of article, can be plain text or properly formatted HTML.
ai_words_limit POST int no - Limit for AI tokens usage per document.
user_custom_str_1 POST string no - Custom string to categorize (and filter) articles. Maximum length is 64 characters.
user_custom_str_2 POST string no - Custom string to categorize (and filter) articles. Maximum length is 64 characters.
user_custom_str_3 POST string no - Custom string to categorize (and filter) articles. Maximum length is 64 characters.
user_custom_str_4 POST string no - Custom string to categorize (and filter) articles. Maximum length is 64 characters.
user_custom_str_5 POST string no - Custom string to categorize (and filter) articles. Maximum length is 64 characters.
user_custom_int_1 POST integer no - Custom integer to categorize (and filter) articles.
user_custom_int_2 POST integer no - Custom integer to categorize (and filter) articles.
user_custom_int_3 POST integer no - Custom integer to categorize (and filter) articles.
user_custom_int_4 POST integer no - Custom integer to categorize (and filter) articles.
user_custom_int_5 POST integer no - Custom integer to categorize (and filter) articles.
primary_keywords POST array no - Primary keywords parameters to create for given article. For every element key should be keyword (string) to be added while value is array of parameters described below.
Primary keyword array
parameter type required default  description
competitor_analyse_engines array yes - List of engines to use to retrieve competitors list. Important: every engine creates distinct analyse. Currently possible values are "google", "google_blog", "google_news".
language string no * Language of keyword. Example value: "pl". * - defaults to article language.
country string no * Country code used when gathering competitors. Example value: "pl". * - defaults to country where given language is used.
location string no * Geolocation for precise location used when gathering competitors. Use this or city param to define location - using both might get unexpected results. Example value: "52.2296756|21.0122287". * - defaults to location of biggest city in given country.
city string no * City name for precise location used when gathering competitors. Use this or location param to define location - using both might get unexpected results. Example value: "Warsaw". * - defaults to biggest city in given country.
device string no desktop Device to simulate when gathering competitors. Possible values are "desktop", "mobile".
Output   RESULT 
data type description
result["id"] integer Id of newly created article.

Description:
Creates new article.

Error:
User do not have permission to access Content Assistant.

Curl:

curl -X POST -d '{ "title": "My new article", "content": "<p>Some text...", "services_token": __ACCESS_TOKEN__ }' https://api.semstorm.com/api-v3/content-assistant/article/create.json

Output:

{ "id": __ID__ }

Retrieve article data

Endpoint:
https://api.semstorm.com/api-v3/content-assistant/article/retrieve [POST]

Parameters   PHP  CURL 
parameter method type required default  description
id POST string yes - ID of article.
additional_data POST array no - What additional data to return.
Additional data array
parameter type required default  description
keywords string no null All analyses about Primary keywords.
share_url string no null Links to article in SEMSTORM by using access hashes.
Output   RESULT 
data type description
result["id"] integer Article id.
result["title"] string Article title.
result["language"] string Article language.
result["content"] string Article content.
result["readability_grade"] integer Article readibility score.
result["grammar_grade"] integer Article grammar score.
result["content_grade"] integer Article content score.
result["characters_count"] integer Article characters count.
result["words_count"] integer Article words count.
result["created"] integer Article created timestamp.
result["changed"] integer Article last change timestamp.
result["article_state"] integer Article state, possible values are: -1 as "deleted", 10 as "draft" and 100 as "published".
result["ai_words_limit"] integer Limit for AI tokens usage per document.
result["user_custom_str_1"] string Custom string to categorize (and filter) articles. Maximum length is 64 characters.
result["user_custom_str_2"] string Custom string to categorize (and filter) articles. Maximum length is 64 characters.
result["user_custom_str_3"] string Custom string to categorize (and filter) articles. Maximum length is 64 characters.
result["user_custom_str_4"] string Custom string to categorize (and filter) articles. Maximum length is 64 characters.
result["user_custom_str_5"] string Custom string to categorize (and filter) articles. Maximum length is 64 characters.
result["user_custom_int_1"] integer Custom integer to categorize (and filter) articles.
result["user_custom_int_2"] integer Custom integer to categorize (and filter) articles.
result["user_custom_int_3"] integer Custom integer to categorize (and filter) articles.
result["user_custom_int_4"] integer Custom integer to categorize (and filter) articles.
result["user_custom_int_5"] integer Custom integer to categorize (and filter) articles.
result["share_hash_read"] string Article readonly hash, used to access article via SEMSTORM.
result["share_hash_edit"] string Article editable hash, used to access article via SEMSTORM.
result["share_url"]* array Links to SEMSTORM panel with article in readonly mode (first link) and editable mode (second link).
* - returned only if specified in "additional_data"
result["keywords"]* array Analyses of Primary keywords.
* - returned only if specified in "additional_data"

Description:
Get article data.

Error:
User do not have permission to access Content Assistant.

Curl:

curl -X POST -d '{ "id": __ID__, "additional_data": ["keywords", "share_url"], "services_token": __ACCESS_TOKEN__ }' https://api.semstorm.com/api-v3/content-assistant/article/retrieve.json

Output:

{"results": { "id": __ID__, "title": "(...)", "language": "(...)", "content": "(...)" (...)}}

Update article

Endpoint:
https://api.semstorm.com/api-v3/content-assistant/article/update [POST]

Parameters   PHP  CURL 
parameter method type required default  description
id POST integer yes - Article id to update.
title POST string no Title of article. If parameter is not passed title wont change.
language POST string no New article language in short format. Example values: "en", "pl". If parameter is not passed language wont change.
content POST string no Content of article, can be plain text or properly formatted HTML. If parameter is not passed content wont change.
article_state POST integer no Article state, possible values are: -1 as "deleted", 0 as "draft" and 1 as "published". If parameter is not passed article state wont change.
user_custom_str_1 POST string no - Custom string to categorize (and filter) articles. Maximum length is 64 characters.
user_custom_str_2 POST string no - Custom string to categorize (and filter) articles. Maximum length is 64 characters.
user_custom_str_3 POST string no - Custom string to categorize (and filter) articles. Maximum length is 64 characters.
user_custom_str_4 POST string no - Custom string to categorize (and filter) articles. Maximum length is 64 characters.
user_custom_str_5 POST string no - Custom string to categorize (and filter) articles. Maximum length is 64 characters.
user_custom_int_1 POST integer no - Custom integer to categorize (and filter) articles.
user_custom_int_2 POST integer no - Custom integer to categorize (and filter) articles.
user_custom_int_3 POST integer no - Custom integer to categorize (and filter) articles.
user_custom_int_4 POST integer no - Custom integer to categorize (and filter) articles.
user_custom_int_5 POST integer no - Custom integer to categorize (and filter) articles.
Output   RESULT 
data type description
result["id"] integer Id of updated article.

Description:
Change article data.

Error:
User do not have permission to access Content Assistant.
User do not have editor access to given article.

Curl:

curl -X POST -d '{ "id": __ID__, "title": "new title", "content": "Updated content about something else", (...) }' https://api.semstorm.com/api-v3/content-assistant/article/update.json

Output:

{ results: { "id": __ID__ } }

Delete article

Endpoint:
https://api.semstorm.com/api-v3/content-assistant/article/delete [POST]

Parameters   PHP  CURL 
parameter method type required default  description
id POST integer yes - ID of article.
Output   RESULT 
method type description
result["id"] integer Id of article that was deleted.

Description:
Change article state to "deleted", so it is moved to trash. After 30 days without any activity it will be deleted permanently.

Error:
User do not have permission to access Content Assistant.
User do not have editor access to given article.

Curl:

curl -X POST -d '{ "id": __ID__, "services_token": __ACCESS_TOKEN__ }' https://api.semstorm.com/api-v3/content-assistant/article/delete.json

Output:

{ results: { "id": __ID__ } }

Get list of articles

Endpoint:
https://api.semstorm.com/api-v3/content-assistant/article/get-list [POST]

Parameters   PHP  CURL 
parameter method type required default  description
pager POST array no Pager settings. See below for structure details.
filters POST array no Filters. See below for structure details.
additional_data POST array no - Array with information about additional data to retrieve if necessary. Possible values are: "keywords" for primary keywords data.
Pager array
parameter type required default  description
items_per_page integer no 25 Page size (how many articles are in one page). Possible values are: 25, 50, 100, 500.
page integer no 0 Page number to retrieve, starting from 0.
Fitlers array
parameter type required default  description
article_state int no All Article state, possible values are: -1 as "deleted", 0 as "draft" and 1 as "published".
article_search string no String to filter by. Searching occurs in title, language, changed and created params.
Output   RESULT 
method type description
result["articles"] array Array with campaigns.
result["articles"][]["id"] int Article id.
result["articles"][]["title"] string Article title.
result["articles"][]["language"] string Article language.
result["articles"][]["readability_grade"] string Article readability grade.
result["articles"][]["grammar_grade"] string Article grammar grade.
result["articles"][]["content_grade"] string Article content grade.
result["articles"][]["characters_count"] string Article characters count.
result["articles"][]["words_count"] string Article words count.
result["articles"][]["created"] string Article created timestamp.
result["articles"][]["changed"] string Article changed timestamp.
result["articles"][]["article_state"] string Article state.
result["articles"][]["ai_words_limit"] integer Limit for AI tokens usage per document.
result["articles"][]["user_custom_str_1"] string Custom string to categorize (and filter) articles. Maximum length is 64 characters.
result["articles"][]["user_custom_str_2"] string Custom string to categorize (and filter) articles. Maximum length is 64 characters.
result["articles"][]["user_custom_str_3"] string Custom string to categorize (and filter) articles. Maximum length is 64 characters.
result["articles"][]["user_custom_str_4"] string Custom string to categorize (and filter) articles. Maximum length is 64 characters.
result["articles"][]["user_custom_str_5"] string Custom string to categorize (and filter) articles. Maximum length is 64 characters.
result["articles"][]["user_custom_int_1"] integer Custom integer to categorize (and filter) articles.
result["articles"][]["user_custom_int_2"] integer Custom integer to categorize (and filter) articles.
result["articles"][]["user_custom_int_3"] integer Custom integer to categorize (and filter) articles.
result["articles"][]["user_custom_int_4"] integer Custom integer to categorize (and filter) articles.
result["articles"][]["user_custom_int_5"] integer Custom integer to categorize (and filter) articles.
result["articles"][]["keywords"]* array Analyses of Primary keywords.
* - returned only if specified in "additional_data".

Description:
Get articles list.

Error:
User do not have permission to access Content Assistant.

Curl:

curl -X POST -d '{ "pager": { "items_per_page":10, "page":1 }, "services_token": __ACCESS_TOKEN__ }' https://api.semstorm.com/api-v3/content-assistant/article/get-list.json

Output:

{ "articles"[ (...) ], "count":27 }

Primary keywords

Create primary keywords

Endpoint:
https://api.semstorm.com/api-v3/content-assistant/primary-keywords/create [POST]

Parameters   PHP  CURL 
parameter method type required default  description
article_id POST integer no - ID of article.
primary_keywords POST array no Primary keywords parameters to create for given article.
Primary keyword array
parameter type required default  description
keywords array yes - List of keywords to create. Important: every keyword creates distinct analyse.
engines array yes - List of engines to use to retrieve competitors list. Important: every engine creates distinct analyse. Currently possible values are "google-seo", "google-blog", "google-news", "google-shopping", "amazon".
language string no * Language of keyword. Example value: "pl". * - defaults to article language.
country string no * Country code used when gathering competitors. Example value: "pl". * - defaults to country where given language is used.
location string no * Geolocation for precise location used when gathering competitors. Use this or city param to define location - using both might get unexpected results. Example value: "52.2296756|21.0122287". * - defaults to location of biggest city in given country.
city string no * City name for precise location used when gathering competitors. Use this or location param to define location - using both might get unexpected results. Example value: "Warsaw". * - defaults to biggest city in given country.
device string no desktop Device to simulate when gathering competitors. Possible values are "desktop", "mobile".
Output   RESULT 
data type description
result["tokens"]["left"] integer Amount of tokens left for creating primary keywords.
result["keywords_ids"] array Array of keywords IDs of given article.

Description:
Creates primary keywords for given article.

Error:
User do not have permission to access Content Assistant.
User do not have editor access to given article.

Curl:

curl -X POST -d '{ "title": "My new article", "content": "<p>Some text...", "services_token": __ACCESS_TOKEN__ }' https://api.semstorm.com/api-v3/content-assistant/article/create.json

Output:

{ "keywords_ids": [(...)] }

Retrieve primary keywords data

Endpoint:
https://api.semstorm.com/api-v3/content-assistant/primary-keywords/retrieve [POST]

Parameters   PHP  CURL 
parameter method type required default  description
article_id POST integer yes - ID of article.
keywords_ids POST array no - Array with keywords IDs.
Output   RESULT 
data type description
result["keywords"] array Array with keywords - keys are keyword ID.
result["keywords"][_KEYWORD_ID_]["params"] array Keyword parameters.
result["keywords"][_KEYWORD_ID_]["params"]["country"] string Keyword country.
result["keywords"][_KEYWORD_ID_]["params"]["device"] string Keyword country.
result["keywords"][_KEYWORD_ID_]["params"]["language"] string Keyword country.
result["keywords"][_KEYWORD_ID_]["params"]["location"] string Keyword country.
result["keywords"][_KEYWORD_ID_]["params"]["city"] string Keyword country.
result["keywords"][_KEYWORD_ID_]["params"]["status"] string Keyword status. Possible values are "wait" for keyword witing to be analysed, "inprogress" for keyword that is actually analysing, "ready" for finished keyword, "error" when error or timeout occured.
result["keywords"][_KEYWORD_ID_]["params"]["progress"] string Keyword progress in percents, for ready keyword it is "100".
result["keywords"][_KEYWORD_ID_]["competitors"] array List of competitors, keys are position in SERP.
result["keywords"][_KEYWORD_ID_]["competitors"][_POSITION_]["url"] string Competitor full URL.
result["keywords"][_KEYWORD_ID_]["competitors"][_POSITION_]["domain"] string Competitor domain.
result["keywords"][_KEYWORD_ID_]["competitors"][_POSITION_]["include"] bool Flag indicating if URL is included into analyse.
result["keywords"][_KEYWORD_ID_]["competitors"][_POSITION_]["keywordStats"] array Array with number of primary keywords occurences in HTML elements.
result["keywords"][_KEYWORD_ID_]["competitors"][_POSITION_]["keywordStats"] array Array with number of primary keywords occurences in HTML elements.
result["keywords"][_KEYWORD_ID_]["competitors"][_POSITION_][_HTML_ELEMENT_] array Number of HTML elements on site.
result["keywords"][_KEYWORD_ID_]["suggestedKeywords"] array Suggested keyword selected by primary keyword analyse. Keys are keyword (phrase).
result["keywords"][_KEYWORD_ID_]["suggestedKeywords"][_KEYWORD_]["attributes"] array Suggested keyword occurences in HTML elements in all competitors.
result["keywords"][_KEYWORD_ID_]["suggestedKeywords"][_KEYWORD_]["baseWords"] array Array of base words (lemma) in order of appearance in suggested keyword.
result["keywords"][_KEYWORD_ID_]["suggestedKeywords"][_KEYWORD_]["grammaticalClasses"] array Grammatical classes (part of speech) of each word in order of appearance in suggested keyword.
result["keywords"][_KEYWORD_ID_]["suggestedKeywords"][_KEYWORD_]["aiScale"] integer Grade of suggested keyword in terms of imporance. Scale from 0 (low) to 3 (high).

Description:
Get primary keywords data.

Error:
User do not have permission to access Content Assistant.
User do not have editor access to given article.

Curl:

curl -X POST -d '{article_id: __ARTICLE_ID__, "keywords_ids": [__KEYWORDS_ID_1__, (...)], "services_token": __ACCESS_TOKEN__ }' https://api.semstorm.com/api-v3/content-assistant/primary-keywords/retrieve.json

Output:

{"services_token": __ACCESS_TOKEN__, "keywords": {__KEYWORD_ID__: (...) }}

Update primary keywords

Endpoint:
https://api.semstorm.com/api-v3/content-assistant/primary-keywords/update [POST]

Parameters   PHP  CURL 
parameter method type required default  description
article_id POST integer yes - Article id to update.
keywords POST array no Primary keywords parameters to update for given article. For every element key should be keyword ID and value should be array of parameters described below.
Keywords array
parameter method type required default  description
alter_competitors POST array no - Array to change competitors status ("include" flag). For every element key should be competitor position and value should be boolean value indicating new state of competitor. Competitors not listed will remain unchanged.
Output   RESULT 
data type description
result[_KEYWORD_ID_]["alter_competitors"] array Array with information which competitors has been changed. Keys are competitors positions, values are true.

Description:
Change primary keywords data.

Error:
User do not have permission to access Content Assistant.
User do not have editor access to given article.

Curl:

curl -X POST -d '{article_id: __ARTICLE_ID__, "keywords": {__KEYWORD_ID_1__: {"alter_competitors": { "2": false, "3": true }}, (...)}, "services_token": __ACCESS_TOKEN__ }' https://api.semstorm.com/api-v3/content-assistant/primary-keywords/update.json

Output:

[ true ]

Delete primary keywords

Endpoint:
https://api.semstorm.com/api-v3/content-assistant/primary-keywords/delete [POST]

Parameters   PHP  CURL 
parameter method type required default  description
article_id POST integer yes - ID of article.
keywords_ids POST array yes - Array witd keywords IDs (integers).
Output   RESULT 
method type description
result[_KEYWORD_ID_] bool Boolean value indicating if removing of keyword was succesful.

Description:
Delete primary keywords with all their data. This action is irreversable, use with caution.

Error:
User do not have permission to access Content Assistant.
User do not have editor access to given article.

Curl:

curl -X POST -d '{ "article_id": __ARTICLE_ID__ "keywords_ids": [ __KEYWORD_ID_1__, __KEYWORD_ID_2__, (...) ], "services_token": __ACCESS_TOKEN__ }' https://api.semstorm.com/api-v3/content-assistant/primary-keywords/delete.json

Output:

{ __KEYWORD_ID_1__: true, __KEYWORD_ID_2__: true, (...) }

Get list of primary keywords

Endpoint:
https://api.semstorm.com/api-v3/content-assistant/primary-keywords/get-list [POST]

Parameters   PHP  CURL 
parameter method type required default  description
article_id POST integer yes - ID of article.
Output   RESULT 
method type description
result["keywords"][_KEYWORD_ID_]["id"] string Keyword ID, same as array key.
result["keywords"][_KEYWORD_ID_]["keyword"] string Keyword.
result["keywords"][_KEYWORD_ID_]["status"] string Keyword status. Possible values are "wait", "inprogress", "ready", "error".
result["keywords"][_KEYWORD_ID_]["progress"] string Keyword percentage progress.

Description:
Get primary keywords list.

Error:
User do not have permission to access Content Assistant.
User do not have editor access to given article.

Curl:

curl -X POST -d '{ "article_id": __ARTICLE_ID__, "services_token": __ACCESS_TOKEN__ }' https://api.semstorm.com/api-v3/content-assistant/primary-keywords/get-list.json

Output:

{ "keywords": { __KEYWORD_ID_1__: { (...) } } }

Article revisions

Get list of article revisions

Endpoint:
https://api.semstorm.com/api-v3/content-assistant/article-revisions/get-list [POST]

Parameters   PHP  CURL 
parameter method type required default  description
article_id POST integer yes - ID of article.
Output   RESULT 
method type description
result[__REVISION_ID__]["id"] string Revision ID, same as array key.
result[__REVISION_ID__]["uid"] string User ID which edited article.
result[__REVISION_ID__]["content_length"] string Full content length.
result[__REVISION_ID__]["title"] string Revision title.
result[__REVISION_ID__]["created"] string Timestamp of revision creation.

Description:
Get article revisions list.

Error:
User do not have permission to access Content Assistant.
User do not have editor access to given article.

Curl:

curl -X POST -d '{ "article_id": __ARTICLE_ID__, "services_token": __ACCESS_TOKEN__ }' https://api.semstorm.com/api-v3/content-assistant/article-revisions/get-list.json

Output:

{ "results": { __REVISION_ID_1__: { (...) } } }

Retrieve article revision

Endpoint:
https://api.semstorm.com/api-v3/content-assistant/article-revisions/retrieve [POST]

Parameters   PHP  CURL 
parameter method type required default  description
article_id POST integer yes - ID of article.
revision_id POST integer yes - ID of revision.
Output   RESULT 
method type description
result["id"] string Revision ID.
result["uid"] string User ID which edited article.
result["content"] string Revision content.
result["content_length"] string Full content length.
result["title"] string Revision title.
result["created"] string Timestamp of revision creation.
result["language"] string Revision language.
result["meta_description"] string Revision meta description.

Description:
Get article revision.

Error:
User do not have permission to access Content Assistant.
User do not have editor access to given article.

Curl:

curl -X POST -d '{ "article_id": __ARTICLE_ID__, "revision_id": __REVISION_ID__, "services_token": __ACCESS_TOKEN__ }' https://api.semstorm.com/api-v3/content-assistant/article-revisions/retrieve.json

Output:

{ "results": { (...) } }

Revert article to selected revision

Endpoint:
https://api.semstorm.com/api-v3/content-assistant/article-revisions/revert [POST]

Parameters   PHP  CURL 
parameter method type required default  description
article_id POST integer yes - ID of article.
revision_id POST integer yes - ID of revision.
Output   RESULT 
method type description
result["revert"] boolean Boolean value indicating if reverting revision was succesful.

Description:
Get article revisions list.

Error:
User do not have permission to access Content Assistant.
User do not have editor access to given article.

Curl:

curl -X POST -d '{ "article_id": __ARTICLE_ID__, "revision_id": __REVISION_ID__, "services_token": __ACCESS_TOKEN__ }' https://api.semstorm.com/api-v3/content-assistant/article-revisions/revert.json

Output:

{ "results": { "revert": true } }

API errors

Authorization errors

Passing invalid token (or not passing at all) in request will result in authorization error.

PHP example code:

examples/Monitoring/ErrorAuthorization.php

Curl:

curl https://api.semstorm.com/api-v3/content-assistant/article/create.json?services_token=this-is-wrong-access-token

Output:

[ "Unauthorised access." ]

Errors messages

When error occurs you can check "message" in "error" variable returned from server.

PHP example code:

examples/Monitoring/ErrorSimple.php

Curl:

curl https://api.semstorm.com/api-v3/monitoring/monitoring-campaign/123456.json?services_token=__ACCESS_TOKEN__

Output:

{"error": { "message": "(404) No entry for given id." }

Throttle prevention errors

Error with code 503 in most cases will concern throttle prevention. If error message will contain "Throttle prevention. Data may be incomplete(...)" that means system was overloaded and refused to sustain connection.
This is temporary problem, you can retry your request after few secons - just remember that very large request will require more time to wait.
If problem sustains it propably means you are requesting too big set of data at once. Try split it into few smaller requests.

PHP example code:

There is no example of this error, as it happens occasionaly for big set of data.

Curl:

There is no example of this error, as it happens occasionaly for big set of data.

Output:

{ "params": {(...)}, "error": { "message": "(503) Service unavailable. Throttle prevention. Data may be incomplete. Try again later.", "result": {(...)} } }