Retrieve an Overhead Design Image

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 and thumbnailUrl) 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"
  }
]