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.