This provides an API for storing and retrieving images and linking them to objects such as Pages, or Activity Feed items.

Any POST to this API is expected to have a Content-Type header of “multipart/form-data” and a body containing two files: the image file itself and a metadata object called “data”. This file should be JSON-encoded and contain the data outlined under Form data.

Image uploads are limited to files 4MB or less in size. Attempting to upload a larger image will return a 413 status.

Resource URIs

Collection URI: /v7.1/image/

Item URI: /v7.1/image/{id}/


Item methods

  • GET Retrieve an Image by id

Item properties

Name Description Type Units HTTP Support
uri An escaped string containing the URI clients should request this image from (i.e., its CDN URI). string   GET: Required
template An escaped string containing a URI clients may use to request a transformed version of this image. Currently only width and height are supported transformations. string   GET: Required

Note: the scheme of these URIs will match the scheme of the request made to this endpoint.

Example values

template The following is a URI containing width and height. Simply replace with the desired integer value.



Collection methods

  • POST Upload a new Image

Form data

The following is expected in the “files” part of the Image request

Name Description HTTP Support
data A file containing a JSON encoded object POST: Required
image The binary data of an image POST: Required


Name Description Type Units HTTP Support
href A string with the URI for the object this image should be associated with. string   POST: Required
rel A string representing the relationship this image has to the object referred to by href. string   POST: Required
index An integer indicating the position of this image in a series to be uploaded. This is zero-indexed. int   POST: Required
Example values


Association URI
Activity Story /v7.1/activity_story/{id}
[Page](/docs/v71_Page] /v7.1/page/{id}
Route /v7.1/route/{id}
Workout /v7.1/workout/{id}


Relationship Resource Description
attachments Activity Story For Adding an image as an attachment to an Activity Story.
cover_photo Page For updating the cover photo of a Page.
attachments Route For attaching an image to a Route.
attachments Workout For attaching an image to a Workout.


GET Image entity

Request GET: /v7.1/image/{pk}/

POST Image entity

Below is an example request using curl <>_ to create a new image::

curl -vv -H "Api-Key: REDACTED" \
-H "Authorization: Bearer REDACTED" \
-F "data=@page_json.json;type=application/json" \
-F "image=@example.jpg"

Notice that the -F argument is used, here, to attach “files” to the multi-part request. A request requires all items described in [Form data].

This command will generate a request with the following headers::

Content-Length: 67414
Connection: close
User-Agent: curl/7.30.0
Content-Type: multipart/form-data; boundary=----------------------------81f690afcaaa
X-Request-Id: 33397d78-9168-4846-9610-1c8a9dfb749d
Accept: */*
Authorization: Bearer REDACTED

And the following body:

Content-Disposition: form-data; name="data"; filename="page_json.json"
Content-Type: application/json

  "href": "/v7.1/page/1337/",
  "rel": "cover_photo",
  "index": 0
Content-Disposition: form-data; name="image"; filename="example.jpg"
Content-Type: image/jpeg

... binary data here ...
Request POST /v7.1/image/



  "href": "/v7.1/page/1337/",
  "rel": "cover_photo",
  "index": 0


< binary image data >

Response 201