Example requests and responses (v2 JSON API)

Updated Jul 09, 2019

List Sites

URL

<p>/api/v2/sites</p>

Response

<p>{ 
  "sites": [
    { 
      "id": 1, 
      "title" "My site"
    }
  ]
}</p>
Show Site

URL

<p>/api/v2/sites/:site_id</p>

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.
<p>{
  "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>
<p>Some text</p>",
        "manuals": [
          {
            "id": 1,
            "title": "My manual",
            "published": true,
            "position": 1,
            "internal_title": "My manual"
          }
        ]
      }
    ]
  }
}
Show Manual

URL

<p>/api/v2/sites/:site_id/manuals/:manual_id</p>

Response

<p>{
  "manual": {
    "id": 1,
    "title": "My manual",
    "internal_title": "My manual",
    "published": true,
    "chapters": [
      {
        "id": 1,
        "title": "My chapter",
        "published": true,
        "position": 1
      }
    ]
  }
}</p>
Show Chapter

URL

<p>/api/v2/sites/:site_id/chapters/:chapter_id</p>

Response

<p>{
  "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"]
      }
    ]
  }
}</p>
Show Article

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

<p>/api/v2/sites/:site_id/articles/:article_id</p>

Response

<p>{
  "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>
<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": []
  }
}
List Articles

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

<p>/api/v2/sites/:site_id/articles</p>

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

<p>{
  "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
  }
}</p>
Show File for Article

URL

<p>/api/v2/sites/:site_id/articles/:article_id/files/:file_id</p>

Response

<p>{
  "file": {
    "id": 1,
    "type": "image",
    "filename": "image.png",
    "url": "https://s3.amazonaws.screensteps_live/images/image.png",
    "width": 200,
    "height": 100
  }
}</p>
List Search Queries

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

<p>/api/v2/sites/:site_id/analytics/searches</p>

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

<p>{
  "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
  }
}</p>

2 Comments

Andy Duckworth

Is there a wildcard that can be used for the search site API that will return all articles for a site? The content this API returns will be very helpful for a project I am working on at our agency.

Greg DeVore

@Andy -
There isn't. Can you describe exactly what you are trying to do and maybe we can suggest a workaround?

Add your comment

E-Mail me when someone replies to this comment

Still Need Help?

Contact Us