URL redirects API for 301, 302 and 307 rules
Manage redirect rules (exact, prefix or regex) in one place and resolve any URL to its target with one call.
What it does
- The URL Redirects API keeps your redirect rules in one tenant-scoped list and answers the question "where should this URL go?". Create a rule, then ask the API to resolve a URL against all your active rules. It returns the first match and the final target, or says nothing matched.
- It solves the scattered-redirect problem. Redirects end up in web server configs, CMS plugins, marketing tools and old spreadsheets, and nobody knows which one wins. Here the rules, their order of matching, their expiry and their on/off state are in one list you can read and change by API.
- Three match types cover most cases. Exact matches one URL. Prefix matches everything that starts with a pattern, and can append the rest of the path to the target. Regex matches a pattern and can reuse captured groups (\1, \2) in the target. Pick 301 (permanent), 302 (found) or 307 (temporary, keeps the HTTP method). You can keep the query string, set an expiry date, switch a rule off without deleting it, and add a note.
- Rules are checked for duplicates inside your tenant, and an invalid regex is refused when you save it, not when a customer clicks. Create up to 100 rules in one bulk request. Partial success is supported, so one bad row does not stop the rest, and the response lists errors by row.
- How you use the answer is up to you. The API is the rules engine and resolver: your edge, proxy or app calls the test endpoint with a URL and acts on the target it gets back. It does not itself sit in front of your domain and serve redirects.
- Authenticate with an X-API-Key header or a Bearer token from Takelan SSO. Over the limit you get a 429 with a Retry-After header. Exact numbers vary by environment, so none are quoted.
- Affordable by design. Start free* inside platform limits. *Free within platform limits; usage beyond limits may be charged to maintain the platform. Connected ShadowCradle organizations can switch on Takelan SSO and these free* services with one switch. Airgap licences work without any Takelan connection.
Example use cases
Site migration
A small business moves to a new site. One prefix rule sends /blog/ to the new blog with the rest of the path kept, and a handful of exact rules cover renamed pages.
Short, memorable campaign links
Marketing creates /summer for a long landing-page URL, sets an end date, and the rule stops matching on its own after the campaign.
Product renames without broken bookmarks
A software team renames a product. A regex rule rewrites /old-name/(.*) to /new-name/\1 so deep links keep working.
Test before you ship
Before pointing live traffic at a rule set, a developer posts sample URLs to the test endpoint and checks the target each one would get.
Bulk import from an old config
An IT admin converts 80 legacy redirects to JSON and loads them in a single bulk request. Rows that fail come back with the row number and reason.
Temporary rules that clean up
A 307 rule sends users to a status page during maintenance. Switch it off in one call when the work is done, and the rule stays for next time.
Try it
Create a prefix rule
curl -X POST https://app.takelan.com/api/v1/utils/redirects \
-H "X-API-Key: $TAKELAN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"source_url": "https://example.com/blog/",
"target_url": "https://news.example.com",
"match_type": "prefix",
"redirect_type": "301",
"preserve_path": true,
"preserve_query": true,
"description": "Blog moved"
}'
# Response (abridged, fictional)
# { "id": "c1d2...7a", "match_type": "prefix", "redirect_type": "301",
# "is_active": true, "hit_count": 0 }Resolve a URL against your rules
curl -X POST https://app.takelan.com/api/v1/utils/redirects/test \
-H "X-API-Key: $TAKELAN_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "test_url": "https://example.com/blog/hello-world?utm=mail" }'
# Response (abridged, fictional)
# {
# "matched": true,
# "target_url": "https://news.example.com/hello-world?utm=mail",
# "reason": "Matched via prefix matching"
# }Expired and switched-off rules are skipped.
Endpoints
POST /api/v1/utils/redirectsCreate a redirect rule (exact, prefix or regex; 301, 302 or 307).GET /api/v1/utils/redirectsList your rules.GET /api/v1/utils/redirects/{redirect_id}One rule.PUT /api/v1/utils/redirects/{redirect_id}Change a rule, including switching it off.DELETE /api/v1/utils/redirects/{redirect_id}Delete a rule.POST /api/v1/utils/redirects/bulk/createCreate up to 100 rules at once. Partial success is allowed.POST /api/v1/utils/redirects/testResolve a URL: returns the first matching active rule and the final target.GET /api/v1/utils/redirects/statsSummary numbers for your rule set.POST /api/v1/quick-actions/create-redirectOne-call shortcut: source, target and match type.
MCP
Available as tools through /mcp/utils. Listing rules and resolving a URL work with a read-only key. Creating, changing or deleting rules are writes, so they are off by default and need the tenant's writes switch plus a key that is not read-only. About MCP
Common questions
how to manage 301 redirects with an API
Create each rule with POST /api/v1/utils/redirects, choose redirect_type 301 and a match type, and list or change them later by id. Use the bulk endpoint to load up to 100 at once.
what is the difference between exact, prefix and regex redirects
Exact matches one URL. Prefix matches anything that starts with your pattern, and can append the rest of the path to the target. Regex matches a pattern and can reuse captured groups in the target.
does the API serve the redirect to visitors
No. It stores your rules and resolves a URL to its target when you ask. Your edge, proxy or application calls the test endpoint and sends the visitor on. This keeps you in control of where redirects run.
how can I test a redirect before going live
Post a sample URL to /api/v1/utils/redirects/test. You get whether it matched, which rule won and the exact target, including any kept query string.
can a redirect expire automatically
Yes. Set expires_at on the rule. Expired rules are skipped when URLs are resolved. You can also switch a rule off without deleting it.
what if I send an invalid regex
It is refused at save time with a 400 and the regex error, so a bad pattern never reaches your live rules.
how do I bulk import redirects
POST up to 100 rules to /redirects/bulk/create. Valid rows are created and failed rows come back with their index and message.
is the redirect API free
It is affordable by design: start free* within platform limits. *Free within platform limits; usage beyond limits may be charged to maintain the platform.