URL
/api/v2/sites
Response
{
"sites": [
{
"id": 1,
"title" "My site"
}
]
}
URL
/api/v2/sites/:site_id
Response
This response requires a bit of explanation.
Key | Value |
---|---|
manuals |
A list of all manuals in a site. Use this if you are only interested in extracting the manuals from your site. |
table_of_contents |
A list of top level manuals and dividers (categories) with additional manuals nested under their respective dividers. Use this to fully recreate the main table of contents in your site. |
For manuals | |
title vs internal _title
|
These will be the same unless you have set "Public Title" for your manual. In that case the title will be the "Public title" and the internal_title will be the original title of the manual. |
{
"site": {
"id": 1,
"title": "My site",
"manuals": [
{
"id": 1,
"title": "My manual",
"published": true,
"position": 1,
"internal_title": "My manual"
}
],
"table_of_contents": [
{
"id": 1,
"type": "Divider",
"position": 1,
"published": true,
"content":<p>Some text</p>",
"manuals": [
{
"id": 1,
"title": "My manual",
"published": true,
"position": 1,
"internal_title": "My manual"
}
]
}
]
}
}
This will search for articles in a site. Allowed query parameters are:
text | Text to search |
tags | Array of tag names |
title | Search on just the article title |
page | The page of results you want to retrieve. Defaults to 1. |
manual_ids | Array of manual_ids for limiting the search scope |
URL
All requests should be GET
requests.
/api/v2/sites/:site_id/search
Example Requests
Request | Results |
---|---|
/api/v2/sites/:site_id/search?text=accounting+invoice |
Searches for the text “accounting invoice" |
/api/v2/sites/:site_id/search?tags=Admin |
Searches for articles tagged with “Admin" |
/api/v2/sites/:site_id/search?tags[]=Admin&tags[]=Daily |
Searches for articles tagged with “Admin” or “Daily” |
/api/v2/sites/:site_id/search?title=Price |
Searches for articles with “Price” in the title |
/api/v2/sites/:site_id/search?title=Price&page=2 |
Get the 2nd page of results |
/api/v2/sites/:site_id/search?manual_ids=3 |
Restrict the search to a specifc manual |
/api/v2/sites/:site_id/search?manual_ids[]=3&manual_ids[]=10 |
Restrict the search to two manuals |
Pagination
40 results will be returned for each request. If you would like additional pages of search results you can add the page that you want to the query string. For example:
/api/v2/sites/:site_id/search?text=accounting&page=2
Response
{
"results": [
{
"id": 1,
"title": "My site",
"links": [
"published_url": "https://myaccount.screenstepslive.com/s/1/m1/l/1",
"api_url": "https://myaccount.screenstepslive.com/api/v2/sites/1/articles/1"
],
"meta_description": null,
"meta_title": null,
"meta_search": null,
}
],
"meta": {
"page": "1",
"per_page": "40"
}
}
URL
/api/v2/sites/:site_id/manuals/:manual_id
Response
{
"manual": {
"id": 1,
"title": "My manual",
"internal_title": "My manual",
"published": true,
"chapters": [
{
"id": 1,
"title": "My chapter",
"published": true,
"position": 1
}
]
}
}
URL
/api/v2/sites/:site_id/chapters/:chapter_id
Response
{
"chapter": {
"id": 1,
"title": "My chapter",
"position": 1,
"published": true,
"articles": [
{
"id": 1,
"title": "My manual",
"published": true,
"position": 1,
"tags": ["first tag", "second tag"]
}
]
}
}
The Article endpoint provides the HTML representation for an article as well as the individual content blocks that make up an article. In most cases the html_body
should be sufficient for what you need.
The image urls used in the html_body
point to the hosted images and the urls will expire. You will need to download the images and store them locally. You will then replace the hrefs for each image in html_body with a relative path to the local copy of the image file.
Certain attributes are only available to admin users. Others are available to editor or admin users. See the table below. all_published_urls
and sites
attributes will only show additional site information if the requesting user is an admin user.
Attribute | Definition | Type | Available to |
---|---|---|---|
sites |
All sites that an article belongs to | Array | Admin |
all_published_urls | All published urls across all sites | Array | Admin |
last_edited_by_id | ID of the last user to edit an article | Integer | Admin or Editor |
owner_id | ID of the current owner | Integer | Admin or Editor |
owner_name |
Name of the current owner | String | Admin or Editor |
status | Current article status | String | Admin or Editor |
is_alias | Whether or not the article is an alias of another article | Boolean | Admin or Editor |
parent_alias_id | If the article is an alias, the id of the parent article | Integer | Admin or Editor |
URL
/api/v2/sites/:site_id/articles/:article_id
Response
{
"article": {
"id": 1,
"alias_parent_id: null,
"is_alias": false,
"all_published_urls": [
"https://example.screenstepslive.com/a/1"
],
"attached_files": [],
"chapter_id": 1,
"content_blocks": [
{
"id": "4CA0D540-4516-0134-2AB5-22000B5A851D",
"alt_tag": null,
"anchor_name": null,
"asset_file_name": null,
"auto_numbered": false,
"body": "<p>Article content</p>",
"content_block_ids": [],
"depth": 0,
"file_asset_id": null,
"foldable": false,
"image_asset_id": null,
"sort_order": 1,
"style": "introduction",
"title": null,
"type": "TextContent"
}
],
"created_at": "2019-04-09T13:47:26.000-04:00",
"html_body": "<div class='\"step-instructions\"'>\n<p>Article Content</p>\n</div>",
"last_edited_at": "2019-04-09T13:47:26.000-04:00",
"last_edited_by": "John Doe",
"last_edited_by_id": 1,
"owner_name": "None",
"owner_id: null,
"status: "Approved",
"manual": {
"id": 1,
"title": "Published Manual"
},
"manual_id": 1,
"meta_description": null,
"meta_search": null,
"meta_title": null,
"next_article": {
"id": 2,
"title": "Article 1 for chapter 1",
"published": true
},
"next_published_article": {
"id": 2,
"title": "Article 1 for chapter 1",
"published": true
},
"previous_article": null,
"previous_published_article": null,
"published": true,
"published_url": "https://example.screenstepslive.com/a/1",
"sites": [
{
"id": 1,
"title": "Example Site"
}
],
"tags": [],
"title": "Example Article",
"images": []
}
}
The Article List endpoint will contain article attributes, but not HTML content. Use the Article Show endpoint to retrieve HTML content.
The Article List endpoint is only available to Admins and Editors.
URL
/api/v2/sites/:site_id/articles
Sorting
You can sort the response with the following query parameters.
Query Parameter | Possible Values |
---|---|
sort_by |
title , last_edited_at , created_at
|
sort_order |
desc , asc
|
Response
{
"articles": [
{
"id": 1,
"alias_parent_id": null,
"all_published_urls": [
"https://example.screenstepslive.com/a/1"
],
"chapter_id": 1,
"created_at": "2019-04-09T13:47:26.000-04:00",
"is_alias": false,
"last_edited_at": "2019-04-09T13:47:26.000-04:00",
"last_edited_by": null,
"last_edited_by_id": null,
"manual": {
"id": 1,
"title": "Example Manual"
},
"manual_id": 1,
"meta_description": null,
"meta_search": null,
"meta_title": null,
"owner_name": "None",
"owner_id": null,
"published": true,
"tags": [],
"published_url": "https://example.screenstepslive.com/a/1",
"status": "None",
"sites": [
{
"id": 1,
"title": "Test Space"
}
],
"title": "Article 0 for chapter 1"
},
],
"meta": {
"page_count": 1,
"total_entries": 1
}
}
URL
/api/v2/sites/:site_id/articles/:article_id/files/:file_id
Response
{
"file": {
"id": 1,
"type": "image",
"filename": "image.png",
"url": "https://s3.amazonaws.screensteps_live/images/image.png",
"width": 200,
"height": 100
}
}
Use this endpoint to retrieve a list of searches performed on your site.
The Search Queries List endpoint is only available to Admins and Editors.
URL
/api/v2/sites/:site_id/analytics/searches
Time range
You can specific the time range with the following query parameters. The default time range will be for the last 30 days.
Query Parameter | Example Values |
---|---|
start_date |
May 1 2019 |
end_date |
Same as above |
Response
{
"search_queries": [
{
"id": 1,
"query_term": "checklist",
"created_at": "2019-07-08T14:39:03.000-04:00",
"hit_count": 2,
"clicked_result": null
}
],
"meta": {
"page_count": 1,
"total_entries": 1
}
}
0 Comments
Add your comment