Articles

List articles in an organisation

Endpoint

GET v1/organisations/{id}/articles

Request Parameters

field	required	type	description
search	no	string	Filter results based on a search string
status	no	string	Filter on the status of the article (draft, ready, published). For example, to retrieve just draft and ready articles, this field should be `draft,ready`
flagged	no	boolean¹	Filter to include only flagged articles
untagged	no	boolean¹	Filter to include only untagged articles
start	no²	date	Date range start³ date to limit results on
end	no²	date	Date range end date³ to limit results on
updated_start	no²	date	Article updated date range start³ date to limit results on
updated_end	no²	date	Article updated date range end date³ to limit results on
limit	no	number	How many records to return
offset	no⁴	number	If limiting, how many records to offset by. Combined with `limit`, this is useful for pagination
order	no	string	The field and optional direction to order on. Fields that can be ordered on are `title`, `date` and `created_date`. To specify with a direction, use a pipe e.g. `?order=title\|asc`

¹As this is a GET method, the request data is presented as a query string. Therefore, booleans must be represented as 1 or 0.

²Both start date and end date are required to limit results by a date range. If one is provided and not the other, a 400 Bad Request will be returned.

³Dates are in the format YYYY-MM-DD HH:MM:SS.

⁴An offset can only be supplied with a limit.

Response Codes

200 OK	Listed articles successfully
403 Not Authorised	Not allowed to list the articles, probably not a member of the organisation

Response Body

An array of articles. See "Get an article" for the fields.

Example Response Body

[
    {
        "id": "p0o9i8u7",
        "title": "Peter Pan",
        "author": "Robin Hood",
        "lead": "Peter Pan is a character created by <em>Scottish novelist</em> and playwright J. M. Barrie.",
        "body": "<p>A <em>good<\/em> body.<\/p>",
        "date": "2013-01-01 00:00:00",
        "location": "Auckland, New Zealand",
        "status": "draft",
        "tags": [],
        "private_tags": [],
        "hero_image": null,
        "user": {
            "id": "i8u7y6t5",
            "first_name": "Dallas",
            "last_name": "Hauck",
            "avatar_url": "http:\/\/site.com\/i.png",
            "last_active_date": "2014-04-22 01:02:03"
        },
        "created_date": "2014-04-20 01:03:04",
        "updated_date": "2014-04-20 01:05:23",
        "average_rating": 3.5,
        "flagged": false
    },
    ...
]

Count articles in an organisation

This endpoint is useful when combined with limiting and offsetting restraints when listing articles in an organisation. This endpoint accepts the same query as the listing endpoint does, but returns the total count of entities matched, as it's not possible to count the total when paginating.

Endpoint

GET v1/organisations/{id}/articles/count

Request Parameters

The same as when listing articles in an organisation, except there are no limit, offset and order fields.

Response Body

field	type	description
count	number	The number of articles matched by the query

Example Response Body

{
    "count": 312
}

List articles in an organisation owned by a particular member

Same as listing articles in an organisation as above, but scoped to a particular member of the organisation.

Endpoint

GET v1/organisations/{id}/members/{user_id}/articles

Count articles in an organisation owned by a particular member

Endpoint

GET v1/organisations/{id}/members/{user_id}/articles/count

Request Parameters

Same as when listing articles in an organisation owned by a particular member, except there are no limit, offset, and order fields.

Response Body

Same as for counting articles in an organisation.

Create an article in an organisation

Articles must be created for an organisation.

Endpoint

POST v1/organisations/{id}/articles

Request Body

field	required	type	description
title	no¹	string	The title (or headline) for the article
author	yes	string	The author of the article
date	no	string	The date (in format `YYYY-MM-DD HH:MM:SS`) for the article
location	no	string	The location the event being described in the article took place
lead	no¹	string	The HTML text for the lead for the article. Allowed tags: `b, i`
body	no¹	string	The HTML text for the body of the article. Allowed tags: `b, i, p, a[href], h3, h4, blockquote, ul, li, br`

²The title, lead and body are not required for creating an article object as it allows the object to be persisted without providing the information up front. This technique is used for our JavaScript application. An article should have a good title, lead and body before it's published.

Example Request Body

{
    "title": "Mary had a Little Lamb",
    "author": "Sarah Josepha Hale",
    "date": "1830-05-24 00:00:00",
    "location": "Boston",
    "lead": "The article lead, which can be marked up with <b>bold<\/b> text and <i>italicised</i> text",
    "body": "<p>The body is allowed more <blockquote>complex<\/blockquote> HTML structures<\/p>"
}

Response Codes

201 Created	The article was created successfully
403 Not Authorised	Not allowed to create the article in the organisation, probably because you're not a member

Response Body

See "Get an article" for the fields

Get an article

Endpoint

GET v1/articles/{id}

Response Codes

200 OK	Successfully retrieved the article
403 Not Authorised	Not allowed to get the article, probably because you're not a member of the organisation, or the article belongs to somebody else and it's not ready

Response Body

field	type	description
id	string	The unique identifier for the article
title	string	The title of the article
author	string	The author of the article
lead	string	The lead of the article as HTML text
body	string	The body of the article as HTML text
date	string	The date (in format YYYY-MM-DD HH:MM:SS) of the event being discussed, if applicable
location	string	The location of the event being discussed, if applicable
status	string	The status of the article, in the set {`draft`, `ready`, `published`}
tags	array	An array of tags which the article has been tagged with. See the Tags documentation.
private_tags	array	An array of private tags which the article has been tagged with. See the Private Tags documentation.
hero_image	object	The hero image for the article. See the Images documentation.
user	object	The user who created the article. See the Users documentation.
created_date	string	The date (in format YYYY-MM-DD HH:MM:SS) the user created the article
average_rating	number	The average rating of the article, between 0 and 5 (0.5 increments)
flagged	boolean	Whether the requesting user has flagged the article. May be omitted in some contexts.
watch_status	string	The watch status of the requesting user, in the set {`watching`, `not_watching`, `unwatched`}
url	string	The URL to view the article once it's published

Example Response Body

{
    "id": 1,
    "title": "Peter Pan",
    "author": "Robin Hood",
    "lead": "A <em>good<\/em> lead",
    "body": "<p>A <em>good<\/em> body.<\/p>",
    "date": "2013-01-01 00:00:00",
    "location": "Auckland, New Zealand",
    "status": "draft",
    "tags": [],
    "private_tags": [],
    "hero_image": null,
    "user": {
        "id": "12345667",
        "first_name": "Dallas",
        "last_name": "Hauck",
        "avatar_url": "http:\/\/google.com\/i.png",
        "last_active_date": "2014-04-22 01:02:03"
     },
    "created_date": "2014-04-20 01:03:04",
    "average_rating": 3.5,
    "flagged": false,
    "watch_status": "not_watching",
    "url": "https:\/\/hail.to\/org\/article\/tukep50"
}

Edit an article

Endpoint

PUT api/v1/articles/{id}

Request Body

Same fields as when creating an article.

Response Codes

200 OK	Article updated successfully
403 Not Authorised	Not allowed to update the article, either the user doesn't own it or they aren't of a high enough permission role

Response Codes

200 OK	Listed the tags successfully
403 Not Authorised	Not allowed to access the article

Response Body

An array of tags, see the Tags documentation.

Tag an article

Endpoint

POST v1/articles/{id}/tags

Request Body

field	required	type	description
tag_id	yes	string	The ID of the tag to attach

Example Request Body

{
    "tag_id": "fq4iux2"
}

Response Codes

204 No Content	Tag successfully attached
403 Not Authorised	Not allowed to edit the article

Untag an article

Endpoint

DELETE v1/articles/{id}/tags/{tag_id}

Response Codes

204 No Content	Tag detached successfully
403 Not Authorised	Not allowed to edit the article

Get an article's private tags

Endpoint

GET v1/articles/{id}/private-tags

Response Codes

200 OK	Listed the private tags successfully
403 Not Authorised	Not allowed to access the article

Response Body

An array of private tags, see the Private Tags documentation.

Private-tag an article

Endpoint

POST v1/articles/{id}/private-tags

Request Body

field	required	type	description
private_tag_id	yes	string	The ID of the private tag to attach

Example Request Body

{
    "private_tag_id": "fq4iux2"
}

Response Codes

204 No Content	Private tag successfully attached
403 Not Authorised	Not allowed to edit the article

Un-private-tag an article

Endpoint

DELETE v1/articles/{id}/private-tags/{private_tag_id}

Response Codes

204 No Content	Private tag detached successfully
403 Not Authorised	Not allowed to edit the article

List a publication's articles

Endpoint

GET v1/publications/{id}/articles

Response Codes

200 OK	Listed the articles successfully
403 Not Authorised	Not allowed to access the publication

Response Body

The same as listing articles in an organisation, see above.

Attaching an article to a publication

Endpoint

POST v1/publications/{id}/articles

Request Body

field	required	type	description
article_id	yes	string	The ID of the article to attach

Example Request Body

{
    "article_id": "gxyf0qd"
}

Response Codes

201 Created	The article was successfully associated
403 Not Authorised	Not allowed to attach that article to this publication
400 Bad Request	The article is already attached to the publication

Response Body

The publication's articles, including the newly attached article.

Removing an article from a publication

Endpoint

DELETE v1/publications/{id}/articles/{article_id}

Response Codes

204 No Content	Article detached successfully
403 Not Authorised	Not allowed to detach the article from the publication

Set a featured article

Endpoint

POST v1/publications/{id}/featured-article

Request Body

field	required	type	description
article_id	yes	string	The ID of the article to make the featured article

Example Request Body

{
    "article_id": "gxpf0ed"
}

Response Codes

204 No Content	Featured article set successfully
403 Not Authorised	Not allowed to set the featured article for this publication

Remove the featured article from a publication

Endpoint

DELETE v1/publications/{id}/featured-article

Response Codes

204 No Content	Featured article cleared successfully
403 Not Authorised	Not allowed to change the featured article of the publication

Get an article's connections

Endpoint

GET v1/articles/{id}/connections

Response Body

An array of connections. Each connection consists of:

field	type	description
id	string	The ID of the connection
name	string	The name of the connection¹
authorised	boolean	Whether the connection has been authorised
authorised_name	string	The full name of the remote user who authorised the connection
exception	boolean	Whether the connection is in exception²
configured	boolean	Whether the connection has been configured
service	object	The service this connection is for
status	string	The status of the most recent post to the connection. One for `pending`, `posted`, `failed`, `retrying`³
last_successful_post	string	The date and time of when the article was last successfully posted to the connection

¹ The name of the connection is relative to the service, so for a Facebook page, the name would be the name of the Facebook page, for example 'Summer Heights High School'. For Twitter, it would be the username of the account, for example 'HailSays'. It's up to the client to determine how to render these in the context of the service (you might want to append 'Facebook page' to the end of the Facebook page name, or prepend a '@' for a Twitter account).

² A connection in exception is a connection that was once authorised and configured, but has encountered a problem since, most likely due to authorisation being revoked or something critical being deleted on the remote service. A connection in exception cannot be posted to, and must be reauthorised and configured by the user.

³ A pending post is queued up ready to post to the remote service, usually within a few seconds. A posted post was successfully posted. A failed post is when a hard-failure result is returned from the remote service, but can be rectified without the whole connection being reauthorised by fixing something and trying again later. A retrying post can occur when a rate limit has been reached at the remote service, or some other error which we can recover from automatically.

Push an article to a connection

Endpoint

POST v1/articles/{id}/connections

Request Body

field	required	type	description
connection_id	yes	string	The ID of the connection to post to
comment	no	string	For services that support it (e.g. Facebook and Twitter), an optional message to include with the post

Response Codes

202 Accepted	The post job was accepted on to the queue for processing
403 Not Authorised	Not allowed to change the featured article of the publication
400 Bad Request	The connection is in exception, isn't authorised or configured, or is already pending processing

Response Body

The updated connection reflecting its new status.

Login

API Documentation

Articles

List articles in an organisation

Endpoint

Request Parameters

Response Codes

Response Body

Example Response Body

Count articles in an organisation

Endpoint

Request Parameters

Response Body

Example Response Body

List articles in an organisation owned by a particular member

Endpoint

Count articles in an organisation owned by a particular member

Endpoint

Request Parameters

Response Body

Create an article in an organisation

Endpoint

Request Body

Example Request Body

Response Codes

Response Body

Get an article

Endpoint

Response Codes

Response Body

Example Response Body

Edit an article

Endpoint

Request Body

Response Codes

Response Body

Flag an article

Endpoint

Response Codes

Unflag an article

Endpoint

Response Codes

Watch an article

Endpoint

Response Codes

Unwatch an article

Endpoint

Response Codes

Delete an article

Endpoint

Response Codes

Get an article's tags

Endpoint

Response Codes

Response Body

Tag an article

Endpoint

Request Body

Example Request Body

Response Codes

Untag an article

Endpoint

Response Codes

Get an article's private tags

Endpoint

Response Codes

Response Body

Private-tag an article

Endpoint

Request Body

Example Request Body

Response Codes

Un-private-tag an article

Endpoint

Response Codes

List a publication's articles

Endpoint

Response Codes

Response Body

Attaching an article to a publication