Pull file deliveries

Discover completed deliveries

List globally with GET /v1/file-exports?limit=25&after=..., or list one subscription at GET /v1/file-export-subscriptions/{id}/deliveries?limit=25.

Fetch the manifest

curl -H "x-api-key: $REALTY_API_KEY" \
  "$REALTY_API_BASE/v1/file-exports/$DELIVERY_ID/manifest"

A non-complete delivery returns 409 delivery_not_complete; an expired delivery returns 410 delivery_expired.

Download and verify every part

Request each unique positive parts[].number from the manifest individually; treat it as an identifier, not a zero-based array index. Numbers need not be contiguous or sorted. part=0 is reserved for a grant to the immutable manifest object itself. The normal workflow above already retrieves that manifest through the JSON manifest endpoint.

Production part grants have kind: "logical" and contain the exact relative redemption path plus an opaque, short-lived bearer token. Grant and redemption responses are Cache-Control: no-store.

grant="$(
  curl --fail --silent --show-error \
    -H "x-api-key: $REALTY_API_KEY" \
    "$REALTY_API_BASE/v1/file-exports/$DELIVERY_ID/download?part=$PART_NUMBER"
)"

redeem_path="$(printf '%s' "$grant" | jq -er '.data.url')"
[ "$(printf '%s' "$grant" | jq -er '.data.kind')" = "logical" ] || exit 1
[ "$redeem_path" = "/v1/file-downloads/redeem" ] || exit 1
bearer_token="$(printf '%s' "$grant" | jq -er '.data.bearer_token')"

curl --fail --silent --show-error --max-redirs 0 \
  -H "Authorization: Bearer $bearer_token" \
  -H "Accept: application/octet-stream" \
  --output "$STAGED_PART" \
  "$REALTY_API_BASE$redeem_path"
unset bearer_token grant

Bind the returned relative path to the same reviewed API origin. Reject an absolute URL, scheme-relative URL, different path, query string, fragment, or redirect; never send the bearer to another origin. Keep the token in memory only and never log it. Stream the bytes to local/object staging while computing SHA-256, then compare the result with that part's sha256 before parsing it.

A transitional non-production deployment can instead return kind: "direct_https" with an HTTPS URL and no bearer token. Production consumers should reject that variant.

Commit exactly once

Key your load ledger by (subscriptionId, generation, sequence, manifestSha256). Commit data and that ledger row atomically. A retry that sees the same key is already complete; a different hash for the same sequence is a hard conflict.

Acknowledge after commit

POST /v1/file-exports/{deliveryId}/acknowledge
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "generation": 1,
  "sequence": 14,
  "manifest_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "customer_reference": "snowflake-load-01K0P9..."
}