Skip to main content

​
Overview

This page documents the request and response models for Download Original Photos: the JSON request body, the per-item presigned URL shapes (success and failure), and the top-level response envelope.

​
DownloadOriginalPhotosRequest

Sent in the JSON body of Download Original Photos. The shape of identifier depends on method. 
{
  "method": "selfie",
  "identifier": "ddc661a7-8861-4793-9437-af42a82d12f8"
}

{
  "method": "image_id",
  "identifier": "a4402318-0cf4-4e1e-b8e8-ac8e8f2fc244"
}

{
  "method": "image_ids",
  "identifier": [
    "a4402318-0cf4-4e1e-b8e8-ac8e8f2fc244",
    "f6cb3c08-2c7a-4ff7-8c1b-71b6f7d4d932"
  ]
}
FieldTypeDescription
methodstringDownload method: bib, selfie, image_id, or image_ids.
identifierstring | array of stringThe value to look up. A string when method is bib (BIB number), selfie (selfie request_id), or image_id (single image ID). A non-empty array of strings when method is image_ids.

​
PresignedUrlItem

Each entry inside presigned_urls[]. 
{
  "url": "https://...",
  "filename": "a4402318-0cf4-4e1e-b8e8-ac8e8f2fc244.jpg"
}
FieldTypeDescription
urlstringPresigned URL for downloading the image. Time-limited (~1 hour).
filenamestringSuggested filename for download.

​
FailedUrlItem

Each entry inside failed_urls[] when one or more URLs could not be generated. 
{
  "image_id": "a4402318-0cf4-4e1e-b8e8-ac8e8f2fc244",
  "error": "Failed to generate URL",
  "path": "imgs/456/large/a4402318-0cf4-4e1e-b8e8-ac8e8f2fc244.jpg"
}
FieldTypeDescription
image_idstringImage ID that failed.
errorstringHuman-readable error message.
pathstring | nullObject path if available.

​
DownloadOriginalPhotosResponse

Top-level response. It uses the standard envelope from Conventions; the download payload lives in data. When no images are available the API still returns 200 OK with empty arrays and a descriptive message (for example "No images found for selfie identifier ..."). data.identifier is the value echoed from the request:
  • For method = bib / selfie / image_id, it is the single string that was sent.
  • For method = image_ids, it is null (the request supplied a list).
If method is image_id and the image does not exist, or method is image_ids and every requested ID is invalid, the API instead responds with 400 Bad Request and the standard error envelope (data is null) — see Download Originals. 
{
  "responseType": "success",
  "message": "Generated 47 presigned URLs for download.",
  "data": {
    "presigned_urls": [
      {
        "url": "https://...",
        "filename": "a4402318-0cf4-4e1e-b8e8-ac8e8f2fc244.jpg"
      }
    ],
    "failed_urls": [],
    "total_images": 47,
    "successful_count": 47,
    "failed_count": 0,
    "identifier": "ddc661a7-8861-4793-9437-af42a82d12f8",
    "pagination": {
      "total": 47,
      "currentPage": 1,
      "totalPages": 2,
      "hasNextPage": true,
      "hasPreviousPage": false,
      "page_size": 30
    }
  }
}
FieldTypeDescription
responseTypestringAlways "success" for 2xx responses. See Conventions.
messagestringHuman-readable status message describing the result.
data.presigned_urlsarrayList of PresignedUrlItem download links.
data.failed_urlsarrayList of FailedUrlItem failures.
data.total_imagesnumberTotal number of images matched: for bib / selfie, the number of images that matched the identifier; for image_id, always 1; for image_ids, the size of the supplied list.
data.successful_countnumberNumber of successfully generated URLs in this page.
data.failed_countnumberNumber of failed URL generations in this page.
data.identifierstring | nullBIB number, selfie request_id, or single image_id echoed from the request. null when method is image_ids (since a list was supplied).
data.paginationobject | nullPaginationInfo metadata. null when there were no images to paginate.

​
Used By

Download Originals

Request body and response envelope for presigned downloads.