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 authorizes posting content on behalf of an account, provided on request by the Canvasflow team.

publicationId - Unique id to identify the publication to which the article should be published. Clients are free to assign any meaningful alpha-numerical id.

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

articleId- Unique id to identify the publication to which the article should be published. Clients are free to assign any meaningful alpha-numerical id. Republishing an article with the same id will result in overriding the existing article within Canvasflow.

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 publication.

publicationName - Publication name, defaults to publicationId if not provided.

issueName - Issue name, defaults to IssueId if not provided.

articleName - Article name, defaults to articleId if not provided.

assets - ZIP file containing referenced assets (images, movies, audio etc) from the article content.

Article XML Content

The article content can be broken down into 2 key structures, article content and article meta.

ArticleContent

The article content describes the article's content.

The term "schema" in this context is used for referring to the xml tags that are used for specifying each text element's type.

It is possible to use either Canvasflow's native schema, or use your own tags which more closely match 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 Canvasflow's text component type names. Therefore, supported tag names are:

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

The tag's contents should be plain text without html formatting, i.e:

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

The only exception to this is the body tag, which may have tags, i.e:

<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 matches 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, such that the component type on the left will always appear before any other type to its right or not listed.

This makes it possible to ensure that a title for example 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>