Introduction OAuth Users Organisations Tags Private Tags Articles Images Videos Publications

Tags

List tags in an organisation

Endpoint

GET v1/organisations/{id}/tags

Response Codes

200 OK Successfully listed the tags
403 Not Authorised You aren't allowed to list the tags (not in that organisation)

Response Body

An array of tags. See "Get a tag" for the fields. Note that there won't be a number_of_articles or number_of_images field, which is only available when getting a particular tag by ID.

Create a tag in an organisation

Endpoint

POST v1/organisations/{id}/tags

Request Body

field required type description
name yes string The tag name
description no string The tag description

Example Request Body

{
    "name": "Sport",
    "description": "All the sport at the College"
}

Response Codes

201 Created The tag was created successfully
403 Not Authorised You aren't allowed to create the tag

Response Body

The newly created tag object. See "Get a tag" for the fields.

Get a tag

Endpoint

GET v1/tags/{id}

Response Codes

200 OK Successful request
403 Not Authorised You aren't allowed to view that tag (not in the organisation)

Response Body

field type description
id string The unique ID of the tag
name string The tag name
description string The tag description

Example Response Body

{
    "id": "di4po87",
    "name": "Sport",
    "description": "All the sport at the College"
}

Update a tag

Endpoint

PUT v1/tags/{id}

Request Body

Note that only the subset of fields that are to be updated need to be provided.

field required type description
name no string The new tag name
description no string The new tag description

Response Codes

200 OK The tag was updated successfully
403 Not Authorised You aren't allowed to update the tag

Response Body

The updated tag object.

Delete a tag

Endpoint

DELETE v1/tags/{id}

Response Codes

204 No Content The tag was deleted successfully
403 Not Authorised You aren't allowed to delete the tag

List articles in a tag

Endpoint

GET v1/tags/{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
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 Articles listed successfully
403 Not Authorised Not allowed to list articles in the tag

Response Body

An array of articles. See the Articles documentation.

Count articles in a tag

Endpoint

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

Request Parameters

This endpoint accepts all the request parameters that listing articles in a tag does, except there are no limit, offset or order fields.

Response Body

The same as when counting articles in an organisation. See the Articles documentation.

List images in a tag

Endpoint

GET v1/tags/{id}/images

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 image (pending, approved)
flagged no boolean1 Filter to include only flagged images
start no2 date Date range start3 date to limit results on
end no2 date 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 caption, date and created_date. To specify with a direction, use a pipe e.g. ?order=created_date|desc

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

Same as for listing articles, except it will be an array of images. See the Images documentation.

Count articles in a tag

Endpoint

GET v1/tags/{id}/images/count

Request Parameters

This endpoint accepts all the request parameters that listing images in a tag does, except there are no limit, offset or order fields.

Response Body

The same as when counting images in an organisation. See the Images documentation.