Private Tags
List private tags in an organisation
Endpoint
GET v1/organisations/{id}/private-tags
Response Codes
| 200 OK | Successfully listed the private tags |
|---|---|
| 403 Not Authorised | You aren't allowed to list the private tags (not in that organisation) |
Response Body
An array of private tags. See "Get a private 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 private tag by ID.
Create a private tag in an organisation
Endpoint
POST v1/organisations/{id}/private-tags
Request Body
| field | required | type | description |
|---|---|---|---|
| name | yes | string | The tag name |
| description | no | string | The tag description |
Example Request Body
{
"name": "For Bob",
"description": "For Bob to complete"
}Response Codes
| 201 Created | The private tag was created successfully |
|---|---|
| 403 Not Authorised | You aren't allowed to create the private tag |
Response Body
The newly created private tag object. See "Get a private tag" for the fields.
Get a private tag
Endpoint
GET v1/private-tags/{id}
Response Codes
| 200 OK | Successful request |
|---|---|
| 403 Not Authorised | You aren't allowed to view that private tag (not in the organisation) |
Response Body
| field | type | description |
|---|---|---|
| id | string | The unique ID of the private tag |
| name | string | The private tag name |
| description | string | The private tag description |
Example Response Body
{
"id": "ho49uide",
"name": "Year 8 - please review",
"description": "For review of whoever is in charge of Year 8"
}Update a private tag
Endpoint
PUT v1/private-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 private tag name |
| description | no | string | The new private tag description |
Response Codes
| 200 OK | The private tag was updated successfully |
|---|---|
| 403 Not Authorised | You aren't allowed to update the private tag |
Response Body
The updated private tag object.
Delete a private tag
Endpoint
DELETE v1/private-tags/{id}
Response Codes
| 204 No Content | The private tag was deleted successfully |
|---|---|
| 403 Not Authorised | You aren't allowed to delete the private tag |
List articles in a private tag
Endpoint
GET v1/private-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 private tag |
Response Body
An array of articles. See the Articles documentation.
Count articles in a private tag
Endpoint
GET v1/private-tags/{id}/articles/count
Request Parameters
This endpoint accepts all the request parameters that listing articles in a private 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 private tag
Endpoint
GET v1/private-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 private tag
Endpoint
GET v1/private-tags/{id}/images/count
Request Parameters
This endpoint accepts all the request parameters that listing images in a private 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.