File Sync

Commit a redirectiq.json file to your repo and RedirectIQ keeps your edge redirects in sync automatically. No dashboard required — your redirect config lives with your code.

How it works

You serve a redirectiq.json file at a public HTTPS URL on your domain. RedirectIQ fetches that file on a schedule, diffs it against the rules currently live at the edge, and applies any changes — adds, updates, and removals.

If the file has not changed since the last fetch (detected by SHA-256 hash), nothing happens. Only real changes trigger a deploy.

Rules synced from the file appear in your dashboard with a JSON badge. They cannot be edited from the dashboard — edit the file instead.

File format

{
  "version": 1,
  "redirects": [
    { "from": "/old-page", "to": "/new-page", "type": "301" },
    { "from": "/blog/*", "to": "https://new-site.com/posts", "type": "301" },
    { "from": "/docs/v1/[slug]", "to": "/docs/v2/[slug]", "type": "301" },
    { "from": "/promo", "to": "https://campaign.example.com/", "type": "302" }
  ]
}

Field	Required	Description
from	Yes	Source path starting with /. Supports wildcards (/blog/*) and named parameters (/posts/[slug]).
to	Yes	Destination — a path on the same domain (/new-path) or an absolute https:// URL to any destination.
type	No	"301" (permanent, default) or "302" (temporary). Omit to use 301.

Relative paths in “to”

If to starts with /, it is resolved to an absolute URL on the same domain before the rule is written to the edge. /new-page becomes https://yourdomain.com/new-page.

Duplicate paths

If the same from path appears more than once, the first occurrence is used and the duplicates are skipped. The sync result will report a warning for each duplicate.

Setting it up

Add the file to your repo

Create redirectiq.json in your public assets directory (wherever static files are served at the root of your domain). Start with an empty redirects array and add rules as you go.

Deploy it

The file must be reachable at a public HTTPS URL on your domain — for example, https://yourdomain.com/redirectiq.json. Verify it loads in a browser before continuing.

Enable File Sync in the dashboard

Open your domain in the RedirectIQ dashboard. Scroll to the File Sync section. Enter the URL of your file and choose a sync mode. Click Save.

Trigger the first sync

Click "Sync now" to fetch the file immediately and write any rules to the edge. Subsequent syncs happen automatically based on your chosen mode.

Sync modes

Hourly polling

RedirectIQ checks your file once per hour. No changes to your CI/CD pipeline required. Good for teams that want zero-configuration sync.

Deploy webhook only

The file is only fetched when you call the deploy webhook — typically triggered by your CI/CD pipeline after a successful deploy. This ensures redirects go live as part of the same pipeline run that changes your URLs.

You can switch between modes at any time from the File Sync settings. You can also trigger an immediate sync using the Sync now button regardless of which mode is active.

Deploy webhook

When File Sync is enabled, a webhook URL is available in the dashboard. Call it via POST from your CI/CD pipeline after a successful deploy to trigger an immediate sync.

curl -X POST https://app.redirectiq.com/api/v1/domains/YOUR_DOMAIN_ID/sync-json \
  -H "Authorization: Bearer YOUR_API_KEY"

Response field	Description
added	Number of new rules written to the edge.
updated	Number of existing rules whose destination or type changed.
removed	Number of rules that were in the edge but no longer in the file.
total	Total number of active file-synced rules after this run.
errors	Array of per-entry validation warnings (duplicates, invalid paths, etc.).

The webhook URL and your domain ID are shown in the File Sync section of the dashboard. Use an API key from Settings → API Keys for the Authorization header.

Security

Domain ownership required

File Sync can only be enabled on domains that have completed DNS ownership verification (the TXT record step in DNS Setup). This confirms you control the domain before we fetch any file from it.

URL hostname pinning

The sync URL must be on the same hostname as the domain you registered. You cannot point RedirectIQ at a URL on a different domain — even one you also own. This prevents one account from writing rules using a file hosted by a different account.

HTTPS only

RedirectIQ will not fetch over plain HTTP. TLS certificate validation is enforced, ensuring the file is served by the entity that controls the domain and has not been intercepted in transit.

512 KB file size limit

The sync file is capped at 512 KB. Responses that exceed this limit are rejected entirely — no partial syncs.

Limits

Limit	Value
Max redirects per file	500
Max file size	512 KB
Fetch timeout	8 seconds
Rule limit (combined)	Shared with dashboard rules — subject to your plan limit
Poll interval (hourly mode)	Once per hour

File-synced rules and dashboard rules share the same plan limit. If your plan allows 100 rules and you have 30 dashboard rules, the file can add up to 70 more.

Have questions about File Sync?