Public API
The redirection.io public API offers a way to interact with redirection.io organizations, projects and rules.
Please note that the redirection.io public API is only available in organizations that contain at least one project using a "Starter" or a "Pro" plan.
General considerations
API location and availability
The redirection.io public API is available at https://api.redirection.io: this page provides general information about how to use the API, the available endpoints, etc. It also features an OpenAPI specification that you can use to integrate the API with your own tools: https://api.redirection.io/docs.json.
In the sections below, all the API requests must be sent to the host api.redirection.io with the scheme https.
Security
Using the redirection.io API requires an API key, that can be created under the "API tokens" screen of your organization in the manager:
- Open the redirection.io manager with an organization administrator account
- head to the "Settings > API tokens" screen of your organization
-
Click the "Create a new token" button -
Give this token a name -
Save the generated token in a secure place.
Take care to store this token in a secure location, as it gives a complete control over your redirection.io organization.
Once created, an API token must be used in the Authorization header using the Bearer prefix, as below (of course, replace the string HERE_GOES_THE_TOKEN with the value of the token):
Authorization: Bearer HERE_GOES_THE_TOKENAvailable endpoints
Details of the organization
The API can be used to retrieve some information about the organization the API token belongs to, with the /organization endpoint:
curl \
-XGET https://api.redirection.io/organization \
-H "Authorization: Bearer HERE_GOES_THE_TOKEN"In return, you will get some basic information about the organization and its projects:
{
"id" : "859fb30e-5c02-11eb-b66c-fa163e4748ca",
"name" : "ACME agency",
"projects" : [
{
"id" : "060201ae-88ad-4043-bd02-4661be4fcbd0",
"metadata" : [],
"name" : "ACME project",
"plan" : "starter_1000",
"slug" : "acme-project"
}
],
"slug" : "acme-agency"
}
The id of a project is useful to list or create the rules of this project - we will use it in the newt paragraphs.
Listing the rules of a project
In order to get the list of currently published rules, use the /rules endpoint (of course, replace PROJECT_ID with the id of the project whose rules you want to fetch):
curl \
-XGET "https://api.redirection.io/rules?projectId=PROJECT_ID" \
-H "Authorization: Bearer HERE_GOES_THE_TOKEN"The response contains a list of Rule objects:
[
{
"id": "20fdf49e-85db-461f-bde9-033974870329",
"trigger": {
"source": "/blog/some-source-url",
"methods": [],
"requestHeaders": [],
"responseStatusCodes": [],
"ipAddress": null,
"sampling": null
},
"actions": [
{
"location": "/blog/blog-post-new-url",
"statusCode": 302,
"type": "redirection"
}
],
"markers": [],
"variables": [],
"examples": [],
"priority": 10,
"description": "This rule redirects an article of the blog to its new URL",
"metadata": [],
"enabled": true,
"tags": [
"CMS",
"blog",
"created with the API"
]
}
]
Creating a simple redirection rule
The redirection.io API is not meant as a full replacement of the manager, but as a convenient way to create rules programmatically. However, dealing with our complete API can be a bit complex if you have simple requirements.
This the reason why we offer the /redirections endpoint, which is a shortcut to create simple redirection rules, defined as the combination of:
- a source URL (absolute or relative) without any marker
- a redirect status code
- a target location (absolute or relative)
For example, imagine that you just changed the title of a blog post in your website CMS. There are chances, the URL of the article also changed, and you could want to automatically create a redirect rule from the old URL to the new one. The /redirections endpoint allows such a quick rule creation:
curl \
-XPOST https://api.redirection.io/redirections \
-H "Authorization: Bearer HERE_GOES_THE_TOKEN" \
-H "Content-Type: application/json" \
-d @- <<'EOF'
{
"project": "/projects/PROJECT_ID",
"source": "/blog/some-source-url",
"target": "/blog/blog-post-new-url",
"statusCode": 302
}
EOFProvided the submitted payload is valid, the response will contain a Draft object, which describes the newly draft created rule:
[
{
"id" : "0184097b-82dd-3cf6-1199-e39f730f2cce",
"status" : "add",
"rule" : {
"id" : "12b93f68-32b8-4efb-9484-241c8421bb8a",
"trigger" : {
"ipAddress" : null,
"methods" : [],
"requestHeaders" : [],
"responseStatusCodes" : [],
"sampling" : null,
"source" : "/blog/some-source-url"
},
"actions" : [
{
"location" : "/blog/blog-post-new-url",
"statusCode" : 302,
"type" : "redirection"
}
],
"description" : null,
"enabled" : true,
"examples" : [],
"markers" : [],
"metadata" : [],
"priority" : 0,
"tags" : [],
"variables" : []
}
}
]
As you can see, the resulting Draft contains the description of a complete redirection.io rule, along with the draft status (which can be add, update or delete, depending on the operation performed).
If you need to configure more specialized triggers or actions, then rather use the /rules endpoint (described in the next paragraph) for a complete control over rules. As a sidenote, the request payload for the /redirections endpoint supports some optional metadata:
-
enabled: should the rule be enabled, or not? -
description: should a description message be attached to the rule? -
priority: which priority value should be associated to the rule? -
tags: an optional array of strings to attach to the rules, which can be helpful when searching a specific rule
Here is an example of a complete payload:
{
"project": "/projects/PROJECT_ID",
"source": "/blog/some-source-url",
"target": "/blog/blog-post-new-url",
"statusCode": 302,
"enabled": false,
"description": "This rule redirects an article of the blog to its new URL",
"priority": 10,
"tags": ["CMS", "blog", "created with the API"]
}Once created, the associated rule appears as a "draft" in the rules list in the manager:
-
in the rules list -
it can be edited using the rules edition form
Please note that, when a rule is created, it is not applied to your website unless it is published. Also, it is not listed by the /rules endpoint, as this only lists published rules. However, you can retrieve this rule using the /drafts endpoint:
curl \
-XGET "https://api.redirection.io/drafts?projectId=PROJECT_ID" \
-H "Authorization: Bearer HERE_GOES_THE_TOKEN"This returns the list of the draft changes that are going to be applied when the rules will be published:
[
{
"id" : "01840988-96f5-f1df-9841-69af039d6aa6",
"rule" : {
"actions" : [
{
"location" : "/blog/blog-post-new-url",
"statusCode" : 302,
"type" : "redirection"
}
],
"description" : "This rule redirects an article of the blog to its new URL",
"enabled" : false,
"examples" : [],
"id" : "20fdf49e-85db-461f-bde9-033974870329",
"markers" : [],
"metadata" : [],
"priority" : 10,
"tags" : [
"CMS",
"blog",
"created with the API"
],
"trigger" : {
"ipAddress" : null,
"methods" : [],
"requestHeaders" : [],
"responseStatusCodes" : [],
"sampling" : null,
"source" : "/blog/some-source-url"
},
"variables" : []
},
"status" : "add"
}
]
Creating more complex traffic rules
The redirection.io public API also offers a full control over the trigger and actions. In many scenarios, you will want to create programmatically complex rules. All the redirection.io triggers and actions are available in the public API, as described in the Rule model.
Here is an example of a (quite complete) rule creation call:
curl \
-XPOST https://api.redirection.io/rules \
-H "Authorization: Bearer HERE_GOES_THE_TOKEN" \
-H "Content-Type: application/json" \
-d @- <<'EOF'
{
"project": "/projects/PROJECT_ID",
"trigger": {
"source": "/animals/@animalName",
"methods": [
"GET",
"POST"
],
"requestHeaders": [
{
"name": "User-Agent",
"operator": "contains",
"value": "bot"
}
],
"responseStatusCodes": [
418
],
"ipAddress": {
"type": "inRange",
"start": "1.2.3.4",
"end": "1.2.3.255"
},
"sampling": 23
},
"actions": [
{
"type": "customHtml",
"value": "",
"location": "headStart"
},
{
"type": "redirection",
"location": "https://example.com/pets/@animal",
"statusCode": 307
},
{
"type": "header",
"name": "X-Redirectionio-Method",
"value": "The method for this request was: @httpMethod",
"override": true
}
],
"markers": [
{
"name": "animalName",
"type": "enum",
"values": [
"dog",
"cat",
"fish"
],
"transformers": [
{
"type": "uppercase"
}
]
}
],
"variables": [
{
"type": "marker",
"name": "animal",
"marker": "animalName"
},
{
"type": "requestMethod",
"name": "httpMethod",
"transformers": [
{
"type": "lowercase"
}
]
}
],
"examples": [
{
"mustMatch": true,
"url": "https://example.com/animals/fish",
"method": "GET",
"responseStatusCode": 418,
"headers": [
{
"name": "User-Agent",
"value": "example-bot/1.0"
}
],
"ipAddress": "1.2.3.10"
},
{
"mustMatch": true,
"url": "https://example.com/animals/dog",
"method": "POST",
"responseStatusCode": 418,
"headers": [
{
"name": "User-Agent",
"value": "generic-bot"
}
],
"ipAddress": "1.2.3.118"
},
{
"mustMatch": false,
"url": "https://example.com/animals/cat",
"method": "DELETE"
}
],
"description": "Some quite complete rule example",
"enabled": true,
"tags": [
"animals",
"api created rule"
]
}
EOFThis will result in the following draft rule being created:
Publishing rules
Once a rule is created, modified or deleted using the public API, it is listed as a "draft" change in your ruleset. This means that, unless you publish the rules:
- the rule is not applied on your production website;
- the changes are not listed in the
/rulesendpoint; - the changes only appear in the
/draftsendpoint.
You can publish rules using the graphical interface, or using the API:
curl \
-XPOST https://api.redirection.io/projects/PROJECT_ID/publish \
-H "Authorization: Bearer HERE_GOES_THE_TOKEN"This call triggers the publication of all the changes performed in the ruleset, which will be shortly made available to your live website!