Public API

This API allows you to automate article creation within the Canvasflow platform.

API endpoint: https://api.canvasflow.io/v1

HTTP method: POST

API method: /article

Parameters

Required:

secretKey - API access key which authorises posting content on behalf of an account, provided on request by the Canvasflow support team.

publicationId - Unique ID to identify the brand to which the article should be published. Users are free to assign any meaningful alpha-numerical ID.

issueId - Unique ID to identify the issue to which the article should be published. Users are free to assign any meaningful alpha-numerical ID.

articleId- Unique ID to identify the brand to which the article should be published. Users are free to assign any meaningful alpha-numerical ID. Republishing an article with the same ID will result in existing published article being overwritten.

content - An XML document provided as a plain text string which describes the article's content and meta data. See below for a more detailed description of its contents.

Optional:

styleId - The article style which should be applied to the article. If not supplied, it will default to the first available style for that brand.

publicationName - Publication name, defaults to publicationId if not provided. issueName - name of the individual issue, defaults to IssueId if not provided. articleName - Name of the individual article, defaults to articleId if not provided. assets - Zip file containing referenced assets (images, movies, audio, etc) from the article's content.

Article XML Content:

The article content can be broken down into two key structures, 'Article Content' and 'Article Meta'.

Article Content:

The article's content is described for quick reference.
The term "schema" in this context is used to refer to XML tags which specify each text element's type.
It is possible to use either Canvasflow's native schema, or your own tags which more closely mirror the existing schema in your XML data.

Example using Canvasflow's native schema:

<?xml version="1.0" encoding="UTF-8"?>
<article>
  <articlemeta/>
  <articlecontent>
    <byline>by David Jones | London</byline>
    <head>Airbus admits A380 delivery pressure</head>
    <image>airbus.jpg</image>
    <intro>Group finance chief admits that number of customer handovers could slip in 2017, but makes no comment on production</intro>
    <body><![CDATA[<p>Airbus Group is forecasting that deliveries of A380s could fall to 20 aircraft in 2017, although it has not formally disclosed any production rate changes.</p><p>Speaking during a recent first-quarter briefing, chief financial officer Harald Wilhelm said it would hand over around 20-25 of the double-deck type in 2017.</p><p>Wilhelm had estimated, at the end of October last year, that production for 2017 would reach 20-30 aircraft. At this point, the A380 backlog stood at 144. But in the subsequent five months, to the end of March 2016, the backlog has fallen to 135 and the superjumbo gained only two net orders.</p>]]></body>
    <image caption=”An image caption” credit=”Alex Walker”>trains.jpg</image> 
  </articlecontent>
</article>

Canvasflow's supported tags directly correspond to the 'Text Component' type names. Therefore the supported tag names are:

title, headline, subtitle, body, crosshead, blockquote, intro, byline, footer, image

The tag's contents should be written using plain text without html formatting, for example:

<title>New Yorkers love Pizza!</title>

The only exception to this is the body tag, which may have tags, for example:

<body>
<![CDATA[
    <p>paragraph 1</p>
    <p>paragraph 2</p>
]]>
</body>

Any unrecognised components will result in a special unmatched component, which is clearly indicated when viewing the article through the Canvasflow Editor.

Custom Schema & Content Ordering

It may be desirable to define your own custom schema that more closely mirrors your existing XML data, rather then converting it to Canvasflow's native schema.

By default, the data components are processed in the order in which they appear in the content XML. However, it is possible to control the ordering. The '<top-down-order>' tag instructs Canvasflow to give priority to the components listed, meaning component types on the left will always appear before any other type to its right or unlisted.

This makes it possible to enforce certain behaviours, such as that a title will always appears at the top of the article, irrespective of where it appears in the XML.

<articlemeta>
    <top-down-order>Intro_Heading,Sub_Title</top-down-order>
    <schema>
      <mapping native="Intro_Heading" component="title"/>
      <mapping native="Sub_Title" component="subtitle"/>
	  ... etc
    </schema>
</articlemeta>