Images
List images in an organisation
Endpoint
GET v1/organisations/{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 |
| untagged | no | boolean1 | Filter to include only untagged images |
| start | no2 | string | Date range start3 date to limit results on |
| end | no2 | string | 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 Codes
| 200 OK | Listed images successfully |
|---|---|
| 403 Not Authorised | Not allowed to list images of the organisation |
Response Body
An array of images. See "Get an image" for the fields.
Count images in an organisation
This endpoint is useful when combined with limiting and offsetting restraints when listing images 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}/images/count
Request Parameters
The same as when listing images in an organisation, except there are no limit, offset and order fields.
Response Body
| field | type | description |
|---|---|---|
| count | number | The number of images matched by the query |
Example Response Body
{
"count": 482
}List images in an organisation belonging to a particular user
This method follows the same request and response detail as listing images in an organisation.
Endpoint
GET v1/organisations/{id}/members/{user_id}/images
Count images in an organisation belonging to a particular user
Exactly the same as counting images in an organisation, except this endpoint scopes the results to a particular member of the organisation.
Endpoint
GET v1/organisations/{id}/members/{user_id}/images/count
Create an image in an organisation
Endpoint
POST v1/organisations/{id}/images
Request Body
| field | required | type | description |
|---|---|---|---|
| image | yes | file | The source image |
| caption | no1 | string | The caption of the image |
| people | no1 | string | For photos, an HTML text description of the people in the photo. Allowed tags: b, i |
| location | no | string | For photos, the location of the event where the photo was taken |
| location_latitude2 | no | number | For photos, the decimal latitude component of the coordinates where the photo was taken |
| location_longitude2 | no | number | For photos, the decimal longitude component of the coordinates where the photo was taken |
| date2 | no | string | For photos, the date (in format YYYY-MM-DD HH:MM:SS) of the event where the photo was taken |
| photographer | no | string | The name of the photographer / creator of the image |
| camera2 | no | string | For photos, the camera the photo was taken on |
1These fields aren't required so that the image object can be persisted and these fields provided later. This method is used by our JavaScript app. For photos, good caption and people fields should be provided.
2If the image is a JPEG, the API will attempt to parse the EXIF data to auto-populate the date, camera, and GPS coordinates.
Response Codes
| 201 Created | The image was created successfully |
|---|---|
| 403 Not Authorised | Not allowed to create images in this organisation |
| 400 Bad Request | Validation failed, could be caused by corrupt EXIF data |
Response Body
See "Get an image" for the fields.
Get an image
Endpoint
GET v1/images/{id}
Response Codes
| 200 OK | Successfully retrieved the images |
|---|---|
| 403 Not Authorised | You aren't allowed to get the image |
Response Body
| field | type | description |
|---|---|---|
| id | string | The unique identifier of the image |
| caption | string | The caption of the image |
| people | string | For photos, a list or description of the people in the photo |
| location | string | For photos, the location of the event where the photo was taken |
| location_latitude | number | For photos, the decimal latitude component of the coordinates where the photo was taken |
| location_longitude | number | For photos, the decimal longitude component of the coordinates where the photo was taken |
| date | string | For photos, the date (in format YYYY-MM-DD HH:MM:SS) of the event where the photo was taken. If this date was automatically parsed from the photo's EXIF data, the date may be inaccurate by ±12 hours as timezone offset is not provided |
| photographer | string | The name of the photographer / creator of the image |
| camera | string | For photos, the camera the photo was taken on |
| status | string | The status of the image, in the set {pending, approved} |
| file_150_square_url | string | The URL to the 150 square version of the image |
| file_500_url | string | The URL to the 500 resize version of the image |
| file_500_square_url | string | The URL to the 500 square version of the image |
| file_1000_url | string | The URL to the 1000 resize version of the image |
| file_1000_square_url | string | The URL to the 1000 square version of the image |
| file_2000_url | string | The URL to the 2000 resize version of the image |
| file_original_url | string | The URL to the 2000 resize version of the image |
| original_width | number | The width in pixels of the original image |
| original_height | number | The height in pixels of the original image |
| focal_point | object | Will be the coordinates of the dominant face if one is detected, or the manually-set focal point of the image |
| colour_palette | object | The automatically-generated colour palette for the image |
| tags | array | Array of tags which have been used for the image. See the Tags documentation |
| private_tags | array | Array of private tags which have been used for the image. See the Private Tags documentation |
| user | object | The user who owns the image. See the Users documentation |
| created_date | string | The date the image was created / uploaded |
| average_rating | number | The average rating of the image, to the nearest 0.5 |
| flagged | boolean | Whether the requesting user has flagged the image or not |
Example Response Body
{
"id": "sg1ceha",
"caption": null,
"people": null,
"location": null,
"location_latitude": null,
"location_longitude": null,
"date": "2006-02-21 15:27:48",
"photographer": "Me",
"camera": "Canon EOS DIGITAL REBEL",
"status": "pending",
"file_150_square_url": "http:\/\/lorempixel.com\/500\/500\/",
"file_500_url": "http:\/\/lorempixel.com\/500\/500\/",
"file_500_square_url": "http:\/\/lorempixel.com\/500\/500\/",
"file_1000_url": "http:\/\/lorempixel.com\/500\/500\/",
"file_1000_square_url": "http:\/\/lorempixel.com\/500\/500\/",
"file_2000_url": "http:\/\/lorempixel.com\/500\/500\/",
"file_original_url": "http:\/\/lorempixel.com\/500\/500\/",
"original_width": 2148,
"original_height": 1024,
"focal_point": {
"x": 1000,
"y": 512
},
"colour_palette": {
"background": {
"rgb": {
"red": 255,
"green": 255,
"blue": 255
}
},
"primary": {
"rgb": {
"red": 255,
"green": 255,
"blue": 255
}
},
"secondary": {
"rgb": {
"red": 255,
"green": 255,
"blue": 255
}
},
"detail": {
"rgb": {
"red": 255,
"green": 255,
"blue": 255
}
},
},
"tags": [],
"private_tags": [],
"user": {
"id": "1234567",
"first_name": "Keyon",
"last_name": "Gusikowski",
"avatar_url": "http:\/\/lorempixel.com\/500\/500\/",
"last_active_date": "2014-05-11 22:53:20"
},
"created_date": "2014-05-11 22:05:42",
"average_rating": 1.5,
"flagged": false
}Edit an image
Note that you cannot edit the actual image file once the image has been created, as it's very centric to the image's existence. Only "metadata" can be edited.
Endpoint
PUT v1/images/{id}
Request Body
All the fields that can be provided when creating the image, except for the image field. The source image cannot be changed after the image is created.
Response Codes
| 200 OK | Image updated successfully |
|---|---|
| 403 Not Authorised | Not allowed to update the image |
| 400 Bad Request | Validation failed |
Response Body
The updated image object.
Set an image's focal point
Endpoint
PUT v1/images/{id}/focal-point
Request Body
| field | required | type | description |
|---|---|---|---|
| x | yes | number | The x-coordinate of the new focal point |
| y | yes | number | The y-coordinate of the new focal point |
Response Codes
| 200 OK | Updated the focal point successfully |
|---|---|
| 403 Not Authorised | Not allowed to modify the image |
Response Body
The updated image.
Clear an image's focal point
Endpoint
DELETE v1/images/{id}/focal-point
Response Codes
| 204 No Content | Cleared the focal point successfully |
|---|---|
| 403 Not Authorised | Not allowed to modify the image |
Flag an image
Endpoint
POST v1/images/{id}/flag
Response Codes
| 204 No Content | Flagged the image successfully |
|---|---|
| 403 Not Authorised | Not allowed to flag the image, probably because you aren't a member of the organisation |
Unflag an article
Endpoint
DELETE v1/images/{id}/flag
Response Codes
| 204 No Content | Unflagged the image successfully |
|---|---|
| 403 Not Authorised | Not allowed to unflag the image, probably because you aren't a member of the organisation |
Delete an image
Endpoint
DELETE v1/images/{id}
Response Codes
| 204 No Content | Image deleted successfully |
|---|---|
| 403 Not Authorised | You aren't allowed to delete the image |
Get an image's tags
Endpoint
GET v1/images/{id}/tags
Response Body
An array of tags. See the Tags documentation for more detail.
Tag an image
Endpoint
POST v1/images/{id}/tags
Request Body
| field | required | type | description |
|---|---|---|---|
| tag_id | yes | string | The ID of the tag to attach |
Example Request Body
{
"tag_id": "sg1ceha"
}Response Codes
| 204 No Content | Tag successfully attached |
|---|---|
| 403 Not Authorised | Not allowed to edit the image |
Untag an image
Endpoint
DELETE v1/images/{id}/tags/{tag_id}
Response Codes
| 204 No Content | Tag detached successfully |
|---|---|
| 403 Not Authorised | Not allowed to edit the image |
Get an image's private tags
Endpoint
GET v1/images/{id}/private-tags
Response Body
An array of tags. See the Private Tags documentation for more detail.
Private-tag an image
Endpoint
POST v1/images/{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": "sg1ceha"
}Response Codes
| 204 No Content | Privaet tag successfully attached |
|---|---|
| 403 Not Authorised | Not allowed to edit the image |
Un-private-tag an image
Endpoint
DELETE v1/images/{id}/private-tags/{tag_id}
Response Codes
| 204 No Content | Private tag detached successfully |
|---|---|
| 403 Not Authorised | Not allowed to edit the image |
Get the images attached to an article
Endpoint
GET v1/articles/{id}/images
Response Codes
| 200 OK | Successfully listed the article's images |
|---|---|
| 403 Not Authorised | Not allowed to view the article |
Response Body
An array of images.
Attach an image to an article
Endpoint
POST v1/articles/{id}/images
Request Body
| field | required | type | description |
|---|---|---|---|
| image_id | yes | string | The ID of the image to attach |
Example Request Body
{
"image_id": "03jx1uc"
}Response Codes
| 204 No Content | Attached the image successfully |
|---|---|
| 403 Not Authorised | Not allowed to attach the image |
Detach an image from an article
Endpoint
DELETE v1/articles/{id}/images/{id}
Response Codes
| 204 No Content | Image detached successfully |
|---|---|
| 403 Not Authorised | Not allowed to detach images from the article |
Set the images attached to an article
This method allows you to "sync" which images are attached to the article. All images provided to this endpoint will replace the images already attached.
Endpoint
PUT v1/articles/{id}/images
Request Body
| field | required | type | description |
|---|---|---|---|
| image_ids | yes | string | A list of image ids (comma-separated) to replace with |
Example Request Body
{
"image_ids": "7ywudns,3rdg65g,03jx1uc"
}Response Codes
| 204 No Content | Successfully processed |
|---|---|
| 403 Not Authorised | Not allowed to edit the article |
Note that the server will silently drop any images which the user is not allowed to attach, therefore the client should ensure the user has rights to the images before uploading, or the request could end up wiping all images from the article.
Set the hero image of an article
Endpoint
POST v1/articles/{id}/hero-image
Request Body
| field | required | type | description |
|---|---|---|---|
| image_id | yes | string | The ID of the image |
Example Request Body
{
"image_id": "7ywudns"
}Response Codes
| 204 No Content | Successfully set the hero image |
|---|---|
| 403 Not Authorised | Not allowed to edit the article |
Delete the hero image from an article
Endpoint
DELETE articles/{id}/hero-image
Response Codes
| 204 No Content | Successfully removed the hero image |
|---|---|
| 403 Not Authorised | Not allowed to edit the article |