API REFERENCE · v1

Redirects as JSON

A REST API over HTTPS. JSON in, JSON out, bearer token auth. Create scoped tokens in Settings & API, manage rules and domains, and retrieve analytics from your workspace.

Authentication Read the docs
Create a redirect
curl -X POST https://redirectduck.com/v1/redirects \
  -H "Authorization: Bearer rd_live_…" \
  -H "Content-Type: application/json" \
  -d '{"source":"oldbrand.com/*",
    "destination":"https://newbrand.io/$1",
    "code":301,"keep_query":true}'

Authentication

Create tokens in Settings & API. Each belongs to one workspace and has explicit scopes: redirects:read/write, domains:read/write and analytics:read. Writes also require an Editor or Owner membership. The secret is shown once. Send it on every request.

Authorization: Bearer rd_live_9f2c…
Base URL: https://redirectduck.com/v1
Requests over plain HTTP are refused, not redirected. Rotate a token from the same screen; the old one remains valid for up to one hour. Revoke it immediately when needed.

Endpoints

Collections are paginated with limit and cursor, in ascending ID order, 50 per page by default (maximum 100).

GET
/v1/redirects
List rules in ascending ID order.
POST
/v1/redirects
Create a validated redirect rule.
GET
/v1/redirects/{id}
Get a rule. Hit counts respect the plan retention window.
PATCH
/v1/redirects/{id}
Update only supplied fields.
DELETE
/v1/redirects/{id}
Delete a rule.
POST
/v1/redirects/test
Simulate matching and up to 12 redirects, including pending domains.
GET
/v1/domains
List domains.
POST
/v1/domains
Register a domain in the workspace.
GET
/v1/domains/{id}
Get DNS records and observed certificate state.
DELETE
/v1/domains/{id}
Remove a domain and its redirect rules.
POST
/v1/domains/{id}/verify
Check DNS configuration.
GET
/v1/analytics
Read retained traffic totals, daily series and paid breakdowns.
POST
/v1/imports
Validate and atomically import up to 5,000 rules / 2 MB.
POST
/v1/imports/{id}/commit
Commit an unexpired preview created by this token’s user.

The redirect object

Field Type
id string
Prefixed with rd_, stable for the life of the rule.
source string
Hostname with an optional path pattern or wildcard.
destination string
Absolute URL. Capture groups $1…$9 are substituted.
code integer
301, 302, 307 or 308.
keep_path boolean
Append the incoming path to the destination.
keep_query boolean
Merge the incoming query string into the destination.
status enum
pending_dns, live or paused.
zone enum
us or eu, inherited from the domain.
match_type enum
pattern or regex. Regex uses RE2 (Pro/Agency).
tags string[]
Up to 20 tags (Starter and above).
201 Created
{
  "id": "rd_7Kq2m",
  "source": "oldbrand.com/*",
  "destination": "https://newbrand.io/$1",
  "code": 301,
  "keep_path": true,
  "keep_query": true,
  "status": "live",
  "zone": "eu",
  "hits_30d": 12417,
  "created_at": "2026-09-18T09:14:02Z"
}

Rate limits

Limits apply per token, per minute. Every response carries X-RateLimit-Remaining and X-RateLimit-Reset. Redirect traffic itself is never rate limited.

FREE
60
requests / minute
Bulk: 1 import / day
STARTER
300
requests / minute
Bulk: 10 imports / day
PRO
1,200
requests / minute
Bulk: unlimited
AGENCY
3,000
requests / minute
Bulk: unlimited

Webhook verification

Create HTTPS endpoints in Settings & API (Pro and Agency). Each event has a stable delivery ID. Parse the X-RedirectDuck-Signature header as t=timestamp,v1=signature; compute HMAC-SHA256 with your signing secret over timestamp + "." + raw_request_body. Compare in constant time, reject timestamps older than five minutes and deduplicate event IDs. Failed requests retry up to eight times with exponential backoff; failed deliveries can be retried from Settings.

Errors

Errors return a machine-readable code, a human message and, for validation failures, the offending field.

HTTP code When it happens
400 invalid_request A field is missing or malformed. The field name is returned.
401 invalid_token Token missing, expired, revoked or issued to a removed member.
403 insufficient_scope Token scopes or current membership role do not permit the action.
409 rule_conflict An identical source already exists, or the rule creates a loop.
422 domain_not_verified The domain has no valid DNS record yet.
429 rate_limited Too many requests. Retry after the seconds given in the header.
404 not_found Resource not found in the token’s workspace.
OpenAPI specification
Download the OpenAPI schema for endpoints, scopes, request formats and error responses.
Download openapi.json