ScreenStepsScreenSteps API v2 JSON APIExample requests and responses (v2 JSON API)

Example requests and responses (v2 JSON API)

List Sites

URL

/api/v2/sites

Response

{ 
  "sites": [
    { 
      "id": 1, 
      "title" "My site"
    }
  ]
}
Show 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 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"
          }
        ]
      }
    ]
  }
}
Show Manual

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
      }
    ]
  }
}
Show Chapter

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

URL

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

Response

"article": {
    "id": 1,
    "title": "My article",
    "html_body": "<div class=\"step-instructions\">\n<p>Article Content</p>\n</div>",
    "manual_id": 1,
    "chapter_id": 1,
    "last_edited_by": "John Doe",
    "last_edited_at": "2016-06-01T11:09:37-04:00",
    "meta_title": "My SEO title",
    "meta_description": "An article description",
    "meta_search": "Additional internal search terms",
    "created_at": "2016-04-04T15:44:50-04:00",
    "tags": ["my tag"],
    "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"
      }
    ],
    "attached_files": [],
    "images": [],
    "manual": {
      "id": 1,
      "title": "My manual"
    },
    "next_published_article": {
      "id": 8,
      "title": "Next article"
    },
    "next_article": {
      "id": 8,
      "title": "Next article"
    },
    "previous_published_article": {
      "id": 9,
      "title": "Next article"
    },
    "previous_article": {
      "id": 9,
      "title": "Next article"
    }
  }
}
Show File for Article

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

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