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.

{
  "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:

URL

All requests should be GET requests.

/api/v2/sites/:site_id/search

Sorting

By default results are sorted based on search term relevance. You can control sorting in the response with the following query parameters.

If sort_by is included, but sort_order is omitted, it defaults to asc when sort_by=title and desc when sort_by=last_edited_at or sort_by=created_at.

If sort_by has an unsupported value, results are sorted by updated_at.

Example Requests

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.

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 returns both published and unpublished articles in a site. The results will contain article attributes, but not HTML content. Use the Article Show endpoint to retrieve HTML content.

URL

/api/v2/sites/:site_id/articles

Filtering

You can filter the response using the following query parameters.

Sorting

You can sort the response with the following query parameters.

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.

URL

/api/v2/sites/:site_id/analytics/searches

Time range

You can specific the time range with the start_date and end_date parameters. Without these parameters, the request will default to the last 30 days.

Response

{
  "search_queries": [
    {
      "id": 1,
      "query_term": "checklist",
      "created_at": "2021-05-08T14:39:03.000-04:00",
      "hit_count": 2,
      "clicked_result": null
    }
  ],
  "meta": {
    "page_count": 1,
    "total_entries": 1
  }
}