Introduction OAuth Users Organisations Tags Private Tags Articles Images Videos Publications

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 boolean1 Filter to include only flagged articles
untagged no boolean1 Filter to include only untagged articles
start no2 date Date range start3 date to limit results on
end no2 date Date range end date3 to limit results on
updated_start no2 date Article updated date range start3 date to limit results on
updated_end no2 date Article updated date range end date3 to limit results on
limit no number How many records to return
offset no4 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

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

2Both 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.

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

4An 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 no1 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 no1 string The HTML text for the lead for the article. Allowed tags: b, i
body no1 string The HTML text for the body of the article. Allowed tags: b, i, p, a[href], h3, h4, blockquote, ul, li, br

2The 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 a curator/owner

Response Body

The updated article, see "Get an article" for the fields.

Flag an article

Endpoint

POST v1/articles/{id}/flag

Response Codes

204 No Content Flagged the article successfully
403 Not Authorised Not allowed to flag the article, probably because you aren't a member of the organisation

Unflag an article

Endpoint

DELETE v1/articles/{id}/flag

Response Codes

204 No Content Unflagged the article successfully
403 Not Authorised Not allowed to unflag the article, probably because you aren't a member of the organisation

Watch an article

Endpoint

POST v1/articles/{id}/watch

Response Codes

204 No Content Watched the article successfully
403 Not Authorised Not allowed to watch the article

Unwatch an article

Endpoint

DELETE v1/articles/{id}/watch

Response Codes

204 No Content Unwatched the article successfully
403 Not Authorised Not allowed to unflag the article

Delete an article

Endpoint

DELETE v1/articles/{id}

Response Codes

204 No Content Article deleted successfully
403 Not Authorised You don't own the article, or you aren't a curator/owner

Get an article's tags

Endpoint

GET v1/articles/{id}/tags

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 connection1
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 exception2
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, retrying3
last_successful_post string The date and time of when the article was last successfully posted to the connection

1 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).

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

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