You can retrieve the overhead screenshot of a saved design by using the Get Media by Category ID
endpoint. This screenshot is generated when a user saves a design in the Scanifly portal. For full technical details, you can visit the API Reference documentation
Endpoint
To get the media associated with the overhead image, make a GET request to the following endpoint:
GET /api/v1/media/{projectId}/{categoryId}
Parameters
Parameter | Type | In | Required | Description |
---|---|---|---|---|
projectId | string | path | Yes | The ID of the project containing the design. You can get this from the response when you create a project. |
categoryId | string | path | Yes | The specific category ID for overhead design images. Use the static value: 65397f90bb9b3d22a282b8b1 . |
Prerequisites & Important Notes
- A design must be saved by a user to generate the overhead image. If a design has not been saved, this call will not return an image.
- The image reflects the saved state of the design. The layers that are active and visible to the user at the moment they save the design will appear in the screenshot. For example, if the irradiance map is turned on, it will be in the image. Conversely, if the roof outline visibility is turned off, it will not be shown.
- The endpoint returns images for all designs in the project. This API call will return an array of overhead image objects for every design associated with the given
projectId
. - Match images to designs by filename. You will need to identify the specific image you need from the response array. The
filename
in the response object corresponds to the design name, with spaces replaced by underscores. For example, a design named 'Remote Design 1' would have a filename like "remote_design_1_0.jpg
". The _0 suffix is automatically appended and can be disregarded. - A new save replaces the previous image. Whenever a user saves the design, the existing overhead image is replaced with a new one reflecting the latest saved state. It is expected that there will only ever be one image per design in this category.
- URLs are temporary. The URLs provided in the API response (
imgUrl
andthumbnailUrl
) are valid for 24 hours. After this period, you will receive an authorization error if you try to access them. You will need to make a new API call to get fresh URLs.
Successful Response (200 OK)
A successful request will return a JSON array containing media objects. For an overhead image, this will typically be an array with a single object.
The response object contains several useful fields:
Field | Type | Description |
---|---|---|
id | string | The unique identifier for the media file. |
userId | string | The ID of the user who triggered the media creation (by saving the design). |
projectId | string | The ID of the project this media belongs to. |
filename | string | The name of the image file. This corresponds to the design name, with spaces replaced by underscores (e.g., a design named 'Remote Design 1' would have a filename like "remote_design_1_0.jpg" ). |
imgUrl | string | A link to the full-sized image file. This link is valid for 24 hours. |
thumbnailUrl | string | A link to a thumbnail version of the image. This link is also valid for 24 hours. |
createdAt | string | The timestamp indicating when the image was created. |
updatedAt | string | The timestamp indicating when the image was last updated |
Example Response Body
[
{
"id": "655e5130f146452f1e67xxxx",
"userId": "60d5e1f0e2b3f70068a0xxxx",
"projectId": "64b022998904535352c1xxxx",
"clientRefId": "some-client-reference-id",
"filename": "remote_design_1_0.jpg",
"mimeType": "image/jpeg",
"size": 524288,
"imgUrl": "https://<some-url>/remote_design_1_0.jpg?<query-params>",
"thumbnailUrl": "https://<some-url>/remote_design_1_0_thumb.jpg?<query-params>",
"geolocation": null,
"createdAt": "2023-11-22T17:30:56.549Z",
"updatedAt": "2023-11-22T17:30:56.549Z"
},
{
"id": "655e5130f146452f1e67yyyy",
"userId": "60d5e1f0e2b3f70068a0xxxx",
"projectId": "64b022998904535352c1xxxx",
"clientRefId": "some-other-client-ref-id",
"filename": "on-site_design_v2_0.jpg",
"mimeType": "image/jpeg",
"size": 612345,
"imgUrl": "https://<some-url>/on-site_design_v2_0.jpg?<query-params>",
"thumbnailUrl": "https://<some-url>/on-site_design_v2_0_thumb.jpg?<query-params>",
"geolocation": null,
"createdAt": "2023-11-23T11:05:12.123Z",
"updatedAt": "2023-11-23T11:05:12.123Z"
}
]