Integration Checklist

Last updated: July 17, 2026

Use this checklist before moving an ImageGrid client from a local test into production traffic.

Hosts and credentials

• Send public site and docs traffic to imagegrid.dev.
• Send API traffic to api.imagegrid.dev.
• Keep API keys on the server side. Do not put igk_... keys in browser JavaScript, mobile apps, logs, screenshots, or client-visible config.
• Use Authorization: Bearer igk_... for API calls. In preview environments protected by Basic Auth, prefer X-API-Key: igk_... so Authorization can remain available for Basic Auth.
• Issue separate keys per environment or service. Rotate by creating a replacement key, moving traffic, then revoking the old key.

Request behavior

• Treat uploads as multipart requests and jobs as JSON requests.
• Keep JSON job bodies small and explicit. Unknown fields are rejected.
• Use client-side timeouts for every request.
• Retry network errors and 5xx responses with backoff.
• Do not retry 400, 401, 403, or 404 responses without changing the request or credentials.
• Honor 429 and the Retry-After header instead of hot-looping.
• Store returned asset IDs, job IDs, and artifact IDs in your own system so retries and support investigations have concrete references.

Async polling

Start polling slowly, then back off while the job is still running.

job_id="igj_..."
for delay in 1 2 3 5 8 13; do
  body="$(curl -fsS -H "Authorization: Bearer $IMAGEGRID_API_KEY" \
    "https://api.imagegrid.dev/v1/jobs/$job_id")"
  status="$(printf '%s' "$body" | jq -r '.status')"
  if [ "$status" = "succeeded" ] || [ "$status" = "failed" ]; then
    printf '%s\n' "$body"
    exit 0
  fi
  sleep "$delay"
done

Keep long-running production pollers bounded. A queue-backed image job should not make a client spin forever.

Artifact handling

• Fetch artifact metadata before using a download URL.
• Treat signed download URLs as short lived.
• Do not persist signed URLs as permanent asset references.
• Store artifact IDs and metadata instead, then request fresh metadata when you need a current signed URL.
• Download failures with 403 usually mean the signed URL expired or was modified.

Production readiness

• Exercise the same operation payloads you plan to use in production.
• Verify your source image sizes and output sizes fit the selected plan.
• Confirm your app handles validation errors, quota denials, rate limits, and failed jobs.
• Confirm logging records the X-Request-ID response header and relevant object IDs without storing API keys or signed URL query strings.
• Contact ImageGrid before launch if the workload depends on high-volume rebuilds, very large grids, large uploads, or long-term hosted delivery.