Redirect Rules

Configure URL redirects and rewrites for your applications using regex patterns

Redirects in Dokploy allow you to configure URL rewriting and HTTP redirects using regular expressions. This is useful for handling URL changes, enforcing canonical URLs, or routing traffic based on patterns.

Create Redirect

cURL

curl -X POST https://your-dokploy-instance.com/api/trpc/redirects.create \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "regex": "^/old-path/(.*)",
    "replacement": "/new-path/$1",
    "permanent": true,
    "applicationId": "app_abc123"
  }'

Request Body

regex · string · required

Regular expression pattern to match against incoming URLs. Supports standard regex syntax including capture groups.

Examples:

• ^/old-path/(.*) - Match any path starting with /old-path/
• ^/api/v1/(.*) - Match API v1 endpoints
• ^/blog/(\d+)/(.*) - Match blog posts with numeric IDs

replacement · string · required

Replacement pattern for the redirect. Can reference capture groups from the regex using $1, $2, etc.

Examples:

• /new-path/$1 - Preserve the captured path
• /api/v2/$1 - Upgrade API version
• https://example.com/$1 - Redirect to external domain

permanent · boolean · required

Whether this is a permanent redirect (HTTP 301) or temporary (HTTP 302).

Show Redirect Types

• true - HTTP 301 (Permanent) - Tells browsers and search engines to update their bookmarks/indexes
• false - HTTP 302 (Temporary) - Indicates the redirect is temporary and the original URL should be preserved

applicationId · string · required

ID of the application this redirect rule applies to.

Response

redirectId · string

Unique identifier for the created redirect rule.

regex · string

The regex pattern.

replacement · string

The replacement pattern.

permanent · boolean

Whether this is a permanent redirect.

applicationId · string

Associated application ID.

uniqueConfigKey · number

Unique key used for Traefik configuration.

createdAt · string

ISO 8601 timestamp when the redirect was created.

Get Redirect

cURL

curl -X GET "https://your-dokploy-instance.com/api/trpc/redirects.one?redirectId=redirect_xyz789" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Query Parameters

redirectId · string · required

ID of the redirect rule to retrieve.

Response

Returns the redirect rule object with all configuration details.

Update Redirect

cURL

curl -X POST https://your-dokploy-instance.com/api/trpc/redirects.update \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "redirectId": "redirect_xyz789",
    "regex": "^/updated-path/(.*)",
    "replacement": "/new-location/$1",
    "permanent": false
  }'

Request Body

redirectId · string · required

ID of the redirect rule to update.

regex · string · required

Updated regex pattern.

replacement · string · required

Updated replacement pattern.

permanent · boolean · required

Whether this is a permanent redirect.

Delete Redirect

cURL

curl -X POST https://your-dokploy-instance.com/api/trpc/redirects.delete \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "redirectId": "redirect_xyz789"
  }'

Request Body

redirectId · string · required

ID of the redirect rule to delete.

Redirect Examples

Force HTTPS

Redirect all HTTP traffic to HTTPS:

{
  "regex": "^http://(.*)$",
  "replacement": "https://$1",
  "permanent": true
}

Add Trailing Slash

Ensure all URLs end with a trailing slash:

{
  "regex": "^(.*[^/])$",
  "replacement": "$1/",
  "permanent": false
}

Remove www Prefix

Redirect www subdomain to apex domain:

{
  "regex": "^https://www\\.example\\.com/(.*)$",
  "replacement": "https://example.com/$1",
  "permanent": true
}

API Versioning

Redirect old API version to new version:

{
  "regex": "^/api/v1/(.*)$",
  "replacement": "/api/v2/$1",
  "permanent": false
}

Language Routing

Redirect based on language paths:

{
  "regex": "^/en/(.*)$",
  "replacement": "/$1?lang=en",
  "permanent": false
}

Preserve Query Parameters

Query parameters are automatically preserved in redirects. For example, /old-path?foo=bar matching ^/old-path$ with replacement /new-path will redirect to /new-path?foo=bar.

Best Practices

Test your regex patterns before deploying to production. Use tools like regex101.com to validate your patterns.

Permanent vs Temporary Redirects

• Use permanent redirects (301) when:

  • You’ve permanently moved content
  • You want search engines to update their indexes
  • The old URL will never be used again

• Use temporary redirects (302) when:

  • The redirect is for maintenance or testing
  • You might revert the change
  • You want to preserve the original URL in search engines

Performance

• Keep regex patterns simple when possible
• Avoid complex lookaheads and lookbehinds
• Test redirect rules with realistic traffic patterns
• Monitor redirect chains (one redirect leading to another)

Order Matters

If multiple redirect rules match the same URL, the first matching rule is applied. Order your rules from most specific to least specific.