← All posts
Guides12 Nov 2026 · 3 min read

Automating redirect management with the RedirectDuck API

Use a scoped token to create a paused rule, review and enable it, then test its mapping through the API.

RedirectDuck team
RedirectDuck mascot

The RedirectDuck API is useful when a URL mapping already exists in a script or another system. The same source, destination and forwarding options used in the dashboard can be managed through JSON requests.

Begin with a small test mapping on a domain you own. Automation should make a reviewed change repeatable, not make an unreviewed change larger.

Prepare access and a source domain

Create a token in the selected workspace's settings. For this walkthrough, give it redirects:read and redirects:write scopes. The token's user also needs a role allowed to edit rules.

Add and verify the source domain before expecting live traffic to redirect. Replace the example domains below with your own. Keep the token in your script's environment or secret store.

Requests use the base URL https://redirectduck.com/v1 and the header:

Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

Create a paused rule

Send this JSON to POST /v1/redirects:

{
  "source": "old.example.com/campaign-qa",
  "destination": "https://example.com/current-offers",
  "code": 302,
  "keep_path": false,
  "keep_query": true,
  "enabled": false
}

A successful creation returns HTTP 201 and the rule's ID. Save that returned ID; the next request operates on it. The rule is paused because enabled is false.

Review the returned source, destination, code and forwarding settings before proceeding.

Enable or update the identified rule

Send a PATCH request to /v1/redirects/rd_123, replacing rd_123 with the actual ID:

{
  "destination": "https://example.com/current-offers",
  "enabled": true
}

PATCH changes the supplied fields while retaining the rule's other settings. Enabling the rule can affect live requests after the edge receives the configuration, so use a test source path while learning the workflow.

Test the configured result

Send a POST request to /v1/redirects/test:

{
  "url": "https://old.example.com/campaign-qa?utm_source=qa"
}

Inspect the returned match, status code and location. The tester evaluates enabled rules; a paused rule will not match. It does not make a live request to validate public DNS, the TLS certificate or the destination website.

Follow with a browser or HTTP check of the actual source URL.

Handle failures before retrying

Check both the HTTP status and the JSON error response. Invalid input, missing scopes, plan limits and rule conflicts need different fixes.

For HTTP 429, respect the Retry-After header. If a create request times out, inspect the existing rules before repeating it: a missing response does not prove that the first request failed to create the rule.

Keep the rule IDs and intended mappings in your automation's records. See the API reference for the full request fields, pagination and error format.

Point your old domain at us

One DNS record, HTTPS included. Free for your first domain.

Start for free