Example requests and responses (v2 JSON API)

Updated on Apr 05, 2024

List Sites

URL

/api/v2/sites

Click to copy

Response

{ 
  "sites": [
    { 
      "id": 1, 
      "title" "My site"
    }
  ]
}

Click to copy

Show Site

URL

/api/v2/sites/:site_id

Click to copy

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"
          }
        ]
      }
    ]
  }
}

Click to copy

Search Site

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

Click to copy

Sorting

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

Query Parameter	Possible Values
`sort_by`	`title`, `last_edited_at`, `created_at`
`sort_order`	`desc`, `asc`

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

Request	Results
`/api/v2/sites/:site_id/search?text=accounting+invoice`	Searches for the text “accounting invoice"
`/api/v2/sites/:site_id/search?text=accounting+invoice&sort_by=created_at`	Searches for the text “accounting invoice" and sorts the results `desc` by the `created_at` date for each article.
`/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"
  }
}

Click to copy

Show Manual

URL

/api/v2/sites/:site_id/manuals/:manual_id

Click to copy

Response

{
  "manual": {
    "id": 1,
    "title": "My manual",
    "internal_title": "My manual",
    "published": true,
    "chapters": [
      {
        "id": 1,
        "title": "My chapter",
        "published": true,
        "position": 1
      }
    ]
  }
}

Click to copy

Show Chapter

URL

/api/v2/sites/:site_id/chapters/:chapter_id

Click to copy

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"]
      }
    ]
  }
}

Click to copy

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.

By default the links in the html_body will be relative links and are appropriate for storing articles locally. You can ask ScreenSteps to insert the full URL to your published knowledge base by adding the resolve_links=true query parameter. If the article HTML is being ingested by 3rd party service such as an AI chat bot then use this option.

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

Click to copy

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": []
  }
}

Click to copy

List Articles

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.

The Article List endpoint is only available to Admins and Editors.

URL

/api/v2/sites/:site_id/articles

Click to copy

Filtering

You can filter the response using the following query parameters.

Query Parameter	Possible Values
`published`	`true`, `false`
`searchable`	`true`, `false` If `true`, only articles where exclude_from_search is set to false will be returned. If `false` then only articles where exclude_from_search is set to true will be returned.

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
  }
}

Click to copy

Show File for Article

URL

/api/v2/sites/:site_id/articles/:article_id/files/:file_id

Click to copy

Response

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

Click to copy

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

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

Click to copy

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.

Query Parameter	Example Values
`start_date`	`2021-05-01T12:00:00-04:00`
`end_date`	`2021-06-01T12:00:00-04:00`

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
  }
}

Click to copy

0 Comments

Add your comment

Previous Article Overview and Authentication (v2 JSON API)

Next Article Resolving Internal Links in API

ScreenSteps

Example requests and responses (v2 JSON API)

URL

Response

URL

Response

URL

Sorting

Example Requests

Response

URL

Response

URL

Response

URL

Response

URL

Filtering

Sorting

Response

URL

Response

URL

Time range

Response

0 Comments

Add your comment

Integrations

Other Resources

Recently Updated Articles