Favorite Artifacts

Favorite Artifacts

Favorite artifacts are a shortlist of the images, videos, or files you care most about across every site and campaign. Instead of searching through an entire capture every time, you can mark the shots that matter — inspection photos, evidence frames, progress images — and retrieve them through the API.

Common uses:

• Inspection reporting — collect problem photos from many flights into one list.
• Progress tracking — favorite the same vantage point across recurring campaigns.
• Stakeholder handoff — export a curated set of images for a report or external system.
• Automated archiving — periodically download favorites to your own storage.

Marking an artifact as a favorite is done in the Raad web app. The API lets you list and download those favorites.

Before You Start

Every API request needs a valid JWT token. If you do not have one, see the Authentication guide first. Set this variable at the top of your shell session so the snippets below just work:

export JWT_TOKEN="YOUR_JWT_TOKEN"

Mark Artifacts as Favorites

While viewing an artifact in the web app, click the favorite icon (heart) to add it to your list. The exact location depends on where you are browsing:

You can also add a short note to a favorite for context. Notes stay attached to the favorite and are returned in the note field of the favorites API response.

List Your Favorite Artifacts

Once you have marked artifacts as favorites, list them through the API:

curl "https://app.raad.com/api/v1/artifacts/favorites?per_page=25" \
  -H "Authorization: Bearer $JWT_TOKEN"

The favorites endpoint accepts these filters:

File type examples:

curl "https://app.raad.com/api/v1/artifacts/favorites?per_page=25&file_type=JPEG" \
  -H "Authorization: Bearer $JWT_TOKEN"

The response is a JSON:API list. Each item includes the artifact metadata plus a time-limited downloadUrl:

{
  "data": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-234567890abc",
      "type": "artifact",
      "attributes": {
        "title": "DJI_0042.JPG",
        "fileType": "JPEG",
        "latitude": 30.2672,
        "longitude": -97.7431,
        "photoTakenAt": "2024-03-15T14:32:10.000Z",
        "siteId": "site-uuid",
        "siteName": "Solar Farm Alpha",
        "captureName": "March Inspection",
        "downloadUrl": "https://s3.amazonaws.com/...",
        "downloadUrlExpiresAt": "2024-03-15T15:05:00.000Z",
        "imageUrl": "https://app.raad.com/api/v1/artifacts/artifact-uuid/download",
        "thumbnailUrl": "https://app.raad.com/api/v1/artifacts/artifact-uuid/thumbnail",
        "note": "Use this for the quarterly report."
      }
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 25,
      "total": 1,
      "total_pages": 1
    }
  }
}

Download a Favorite Artifact

Use the artifact UUID to download the original file. The endpoint returns a 302 redirect to a fresh presigned S3 URL, so include -L to follow it.

export ARTIFACT_UUID="YOUR_ARTIFACT_UUID"

curl -L "https://app.raad.com/api/v1/artifacts/$ARTIFACT_UUID/download" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  --output my_favorite_image.jpg

The presigned URL expires after 5 minutes. If a download fails with a URL expired error, call the /download endpoint again for a fresh link.

Download All Your Favorites

If you have jq installed, you can page through favorites and download them all:

mkdir -p raad_favorites

ids=$(curl -s "https://app.raad.com/api/v1/artifacts/favorites?per_page=100" \
  -H "Authorization: Bearer $JWT_TOKEN" | jq -r '.data[].id')

for id in $ids; do
  curl -L "https://app.raad.com/api/v1/artifacts/$id/download" \
    -H "Authorization: Bearer $JWT_TOKEN" \
    --output "raad_favorites/$id.jpg"
  echo "Downloaded $id"
done

The example above assumes all favorites are JPEG images. If you have mixed file types, use the artifact title field to derive the extension:

mkdir -p raad_favorites

items=$(curl -s "https://app.raad.com/api/v1/artifacts/favorites?per_page=100" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  | jq -r '.data[] | "\(.id)|\(.attributes.title)"')

while IFS='|' read -r id title; do
  ext="${title##*.}"
  [ "$ext" = "$title" ] && ext="bin"
  curl -L "https://app.raad.com/api/v1/artifacts/$id/download" \
    -H "Authorization: Bearer $JWT_TOKEN" \
    --output "raad_favorites/$id.$ext"
  echo "Downloaded $title"
done <<< "$items"

Pull Thumbnails

For a light-weight preview without downloading the full file:

export ARTIFACT_UUID="YOUR_ARTIFACT_UUID"

curl -L "https://app.raad.com/api/v1/artifacts/$ARTIFACT_UUID/thumbnail" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  --output preview.jpg

Thumbnails are 400×400 and skipped automatically if the artifact cannot be thumbnailed.

Next Steps

• Combine the artifacts list with page parameters to keep large collections synced automatically.
• Use the Artifacts API reference for full filtering options (site, capture, date range, bounding box).
• Export favorite coordinates to a CSV or feed them into a GIS workflow.