Download OpenAPI specification:Download
© 2021 EasyRedir Inc. All rights reserved.
The EasyRedir API is organized around REST. Our API has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
The EasyRedir API uses an API key and API secret to authenticate requests. You can view and manage your API keys in the EasyRedir Dashboard.
Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.
Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value and API secret as the password.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
$ curl https://api.easyredir.com/v1/rules \
-u SIXN63GMVQCBHA59WZ8F:9DNrIRAhVoOBMqlA09kNrdb67vz4fbAgmka+UurgF/4SoLzBFz9ISP1T
EasyRedir uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx
range indicate success. Codes in the 4xx
range indicate an error that failed given the information provided (e.g., a required parameter was omitted or was invalid). Codes in the 5xx
range indicate an error with our servers.
Some 4xx
errors will include a list of errors with additional attributes. This
may be useful to programatically handle the error or display an error message in
your own UI.
{
"type": "invalid_request_error",
"message": "Invalid Request",
"errors": [
{
"resource": "rule",
"param": "forward_params",
"code": "invalid_option",
"message": "Must be true or false"
}
]
}
The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. For example, if a request to create a Rule does not respond due to a network connection error, you can retry the request with the same idempotency key to guarantee that no more than one Rule is created.
To perform an idempotent request, provide an additional Idempotency-Key
header element with the request.
EasyRedir's idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, only when it succeeds. Subsequent requests with the same key return the same result.
An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions.
Keys are eligible to be removed from the system automatically after they're at least 24 hours old, and a new request is generated if a key is reused after the original has been pruned. The idempotency layer compares incoming parameters to those of the original request.
Results are only saved if an API endpoint executed successfully. If incoming parameters failed validation, or the request conflicted with another that was executing concurrently, no idempotent result is saved. It is safe to retry these requests.
All POST
, PUT
, PATCH
requests accept idempotency keys. Sending idempotency keys in GET
and DELETE
requests has no effect and should be avoided, as these requests are idempotent by definition.
EasyRedir utilizes cursor-based pagination via the starting_after
and ending_before
parameters. Both parameters take an existing object ID value and return objects in reverse chronological order based on the date created. The ending_before
parameter returns objects listed before the named object. The starting_after
parameter returns objects listed after the named object. These parameters are mutually exclusive -- only one of starting_after
or ending_before
may be used.
The limit
defaults to 25 records. You may provide a limit
query parameter of any value up to 100, changing the number of records returned for each page.
Fetch next 50 rules after rule id:
https://api.easyredir.com/v1/rules?limit=50&starting_after=96b30ce8-6331-4c18-ae49-4155c3a2136c
EasyRedir limits API requests on a per account basis to a reasonable amount - a daily limit of 250,000 requests and a burst limit of 100 requests per 10 seconds.
If your client reaches our rate limiting, you will receive a 429 Too Many Requests
error with additional rate limiting information in the headers of the response.
x-ratelimit-limit 100
x-ratelimit-remaining 0
x-ratelimit-reset 1612465680
The number of requests that may originate from your client during the set period.
The number of requests remaining until the reset cycle.
The epoch timestamp when the request limit will be reset.
You can use the headers from the response programatically to throttle your own requests. These headers are only returned if you have reached the request limit.
When fetching Host details, the returned certificate_status
will be one of the following:
The Host is protected by a valid SSL certificate. It will automatically renew with no additional cost.
Your SSL certificate is being provisioned. This process can take up to an hour. You may experience a security warning in your browser until this is complete.
The DNS settings for this Host are not set up. We are unable to automatically manage SSL certificates for this Host until the DNS set up process is complete.
Your plan does not support automatic HTTPS. Visitors using redirects on this Host may experience a security warning in their browser. You can upgrade your plan to enable automatic SSL certificate management.
The Host contains an underscore character (i.e. "_") which is not allowed by RFC 952 and RFC 1123. Our certificate providers will not issue a certificate for Host containing an underscore.
The CAA record for this Host is not configured correctly. Having a CAA record is not required, you can either remove your CAA record or your CAA record must include an entry for Let's Encrypt, 0 issue "letsencrypt.org"
so that we can automatically manage SSL certificates for you.
We have detected IPv6 AAAA DNS records on this Host. You must remove these AAAA records so that we can automatically manage SSL certificates for you.
DNS status for a Host will be one of:
DNS has been configured correctly for this Host.
DNS settings are not correct, see the recommended and alternative dns sections within the get Host response for correct settings.
Source URLs are the URLs that you want EasyRedir to redirect on your behalf. You must be able to modify the DNS for all Source URL hostnames you want EasyRedir to redirect for you. You can submit a list of source URLs to redirect. You can also include paths and query params after the domain name.
The Target URL is where we'll redirect anyone who accesses the Source URLs you configured in your EasyRedir dashboard. For your Target URLs you can include paths and add query parameters if you want to track conversions using analytics services (e.g. Google Analytics).
You can fine tune how our systems process your Rules. Choose between Moved Permanently (HTTP 301) or Found (HTTP 302). We recommend moved permanently Rules in most cases (best for SEO).
Get a list of Rules configured for your organization.
sq |
string
Optional query parameter to filter results by source URL. If both |
tq |
string
Optional query parameter to filter results by target URL. |
limit |
integer
Default: 25
Optional number of results per page |
Array of objects (Rule)
|
|
object (Pagination Metadata)
|
|
object (Pagination Links)
|
curl --request GET \ --url 'https://api.easyredir.com/v1/rules?starting_after=fce8da91-f1ce-40be-a517-70242d68790a' \ --header 'Authorization: Basic U0lYTjYzR01WUUNCSEE1OVdaOEY6OUROcklSQWhWb09CTXFsQTA5a05yZGI2N3Z6NGZiQWdta2ErVXVyZ0YvNFNvTHpCRno5SVNQMVQ='
{
-
"data": [
-
{
-
"id": "abc-def",
-
"type": "rule",
-
"attributes": {
-
"forward_params": true,
-
"forward_path": true,
-
"response_type": "moved_permanently",
-
"source_urls": [
-
"abc.com",
- "abc.com/123"
],
-
"target_url": "otherdomain.com"
}
}
],
-
"meta": {
-
"has_more": true
},
-
"links": {
-
"next": "/v1/rules?starting_after=abc-def",
-
"prev": "/v1/rules?ending_before=abc-def"
}
}
Create a new Rule for your organization
include[]=relationship |
string
Example: include[]=source_hosts
Optional list of relationship details to include in the response. For large number of related objects, consider using the relationship link to support paging and querying results. |
forward_params required
|
boolean
Whether requested URL params should be forwarded to the target URL. Can only be applied when the source_url does not have any query parameters defined on it. |
forward_path required
|
boolean
Whether the path should be forwarded to the target URL. Can only be applied on Rules on the root path of a Host. |
response_type required
|
string
Enum: "moved_permanently" "found" The type of response to use |
source_urls required
|
Array of strings
List of source URLs to redirect to the target URL |
target_url required
|
string
URL to redirect visitors to |
object (Rule)
|
|
object (Relationships)
|
{
-
"forward_params": true,
-
"forward_path": true,
-
"response_type": "moved_permanently",
-
"source_urls": [
-
"abc.com",
- "abc.com/123"
],
-
"target_url": "otherdomain.com"
}
{
-
"data": {
-
"id": "abc-def",
-
"type": "rule",
-
"attributes": {
-
"forward_params": true,
-
"forward_path": true,
-
"response_type": "moved_permanently",
-
"source_urls": [
-
"abc.com",
- "abc.com/123"
],
-
"target_url": "otherdomain.com"
}
},
-
"relationships": {
-
"[relationship type]": {
-
"data": [
-
{
-
"id": "abc-123",
-
"type": "host"
}
],
-
"links": {
-
"related": "/api/v1/rules/e819dbbb-892c-487f-a2e0-7b60b0362b6c/hosts"
}
}
}
}
Partial updates of Rules are supported. Only provide attributes you wish to update.
Id required
|
string
Id of the Rule to update |
include[]=relationship |
string
Example: include[]=source_hosts
Optional list of relationship details to include in the response. |
forward_params |
boolean
Whether requested URL params should be forwarded to the target URL. Can only be applied when the source_url does not have any query parameters defined on it. |
forward_path |
boolean
Whether the path should be forwarded to the target URL. Can only be applied on Rules on the root path of a hostname. |
response_type |
string
Enum: "moved_permanently" "found" The type of redirect to use |
source_urls |
Array of strings
List of source URLs to redirect to the target URL |
target_url |
string
URL to redirect visitors to |
object (Rule)
|
|
object (Relationships)
|
{
-
"forward_params": true,
-
"forward_path": true,
-
"response_type": "moved_permanently",
-
"source_urls": [
-
"abc.com",
- "abc.com/123"
],
-
"target_url": "otherdomain.com"
}
{
-
"data": {
-
"id": "abc-def",
-
"type": "rule",
-
"attributes": {
-
"forward_params": true,
-
"forward_path": true,
-
"response_type": "moved_permanently",
-
"source_urls": [
-
"abc.com",
- "abc.com/123"
],
-
"target_url": "otherdomain.com"
}
},
-
"relationships": {
-
"[relationship type]": {
-
"data": [
-
{
-
"id": "abc-123",
-
"type": "host"
}
],
-
"links": {
-
"related": "/api/v1/rules/e819dbbb-892c-487f-a2e0-7b60b0362b6c/hosts"
}
}
}
}
curl --request DELETE \ --url https://api.easyredir.com/v1/rules/5d29f819-302f-40c0-8b5a-6d670267615b \ --header 'Authorization: Basic U0lYTjYzR01WUUNCSEE1OVdaOEY6OUROcklSQWhWb09CTXFsQTA5a05yZGI2N3Z6NGZiQWdta2ErVXVyZ0YvNFNvTHpCRno5SVNQMVQ=' \ --header 'Content-Type: application/json'
Hosts are domains used within your source URLs. The Host endpoints allow you to get the list of all source Hosts for your Rules and fetch details about the dns and certificate configuration for each.
Get a list of source Hosts
limit |
integer
Default: 25
Optional number of results per page |
Array of objects (Host)
|
|
object (Pagination Metadata)
|
|
object (Pagination Links)
|
curl --request GET \ --url https://api.easyredir.com/v1/hosts \ --header 'Authorization: Basic U0lYTjYzR01WUUNCSEE1OVdaOEY6OUROcklSQWhWb09CTXFsQTA5a05yZGI2N3Z6NGZiQWdta2ErVXVyZ0YvNFNvTHpCRno5SVNQMVQ='
{
-
"data": [
-
{
-
"id": "abc-def",
-
"type": "host",
-
"attributes": {
-
"name": "easyredir.com",
-
"dns_status": "active",
-
"certificate_status": "active"
},
-
"links": {
-
"self": "/v1/hosts/abc-def"
}
}
],
-
"meta": {
-
"has_more": true
},
-
"links": {
-
"next": "/v1/rules?starting_after=abc-def",
-
"prev": "/v1/rules?ending_before=abc-def"
}
}
Get a source Host by id
Id required
|
string <uuid>
Id of the Host to fetch |
object (Host)
|
curl --request GET \ --url https://api.easyredir.com/v1/hosts/3aaedc9e-4f7b-49ba-9c88-b7048f9ab423 \ --header 'Authorization: Basic U0lYTjYzR01WUUNCSEE1OVdaOEY6OUROcklSQWhWb09CTXFsQTA5a05yZGI2N3Z6NGZiQWdta2ErVXVyZ0YvNFNvTHpCRno5SVNQMVQ='
{-
"data": {
-
"id": "abc-def",
-
"type": "host",
-
"attributes": {
-
"name": "easyredir.com",
-
"dns_status": "active",
-
"dns_tested_at": "2020-11-24T22:33:35Z",
-
"certificate_status": "active",
-
"acme_enabled": true,
-
"match_options": {
-
"case_insensitive": true,
-
"slash_insensitive": true
},
-
"not_found_action": {
-
"forward_params": true,
-
"forward_path": true,
-
"custom_404_body_present": "true",
-
"response_code": 302,
},
-
"security": {
-
"https_upgrade": true,
-
"prevent_foreign_embedding": true,
-
"hsts_include_sub_domains": true,
-
"hsts_max_age": 31536000,
-
"hsts_preload": true
},
-
"required_dns_entries": {
-
"recommended": {
-
"type": "A",
-
"values": [
-
"34.213.106.51",
- "54.68.182.72"
]
},
-
"alternatives": [
-
{
-
"type": "A",
-
"values": [
-
"34.213.106.51",
- "54.68.182.72"
]
}
]
},
-
"detected_dns_entries": [
-
{
-
"type": "A",
-
"values": [
-
"34.213.106.51",
- "54.68.182.72"
]
}
]
},
-
"links": {
-
"self": "/v1/hosts/abc-def"
}
}
}
Update a source Host by id. Partial updates are supported. Only provide attributes you wish to update.
Id required
|
string <uuid>
Id of the Host to update |
object (Match Options)
|
|
object (Not found configuration)
|
|
object (Security Settings)
|
object (Host)
|
{
-
"match_options": {
-
"case_insensitive": true,
-
"slash_insensitive": true
},
-
"not_found_action": {
-
"forward_params": true,
-
"forward_path": true,
-
"custom_404_body": "<html><body>My Custom 404 content.</body></html>",
-
"response_code": 302,
},
-
"security": {
-
"https_upgrade": true,
-
"prevent_foreign_embedding": true,
-
"hsts_include_sub_domains": true,
-
"hsts_max_age": 31536000,
-
"hsts_preload": true
}
}
{-
"data": {
-
"id": "abc-def",
-
"type": "host",
-
"attributes": {
-
"name": "easyredir.com",
-
"dns_status": "active",
-
"dns_tested_at": "2020-11-24T22:33:35Z",
-
"certificate_status": "active",
-
"acme_enabled": true,
-
"match_options": {
-
"case_insensitive": true,
-
"slash_insensitive": true
},
-
"not_found_action": {
-
"forward_params": true,
-
"forward_path": true,
-
"custom_404_body_present": "true",
-
"response_code": 302,
},
-
"security": {
-
"https_upgrade": true,
-
"prevent_foreign_embedding": true,
-
"hsts_include_sub_domains": true,
-
"hsts_max_age": 31536000,
-
"hsts_preload": true
},
-
"required_dns_entries": {
-
"recommended": {
-
"type": "A",
-
"values": [
-
"34.213.106.51",
- "54.68.182.72"
]
},
-
"alternatives": [
-
{
-
"type": "A",
-
"values": [
-
"34.213.106.51",
- "54.68.182.72"
]
}
]
},
-
"detected_dns_entries": [
-
{
-
"type": "A",
-
"values": [
-
"34.213.106.51",
- "54.68.182.72"
]
}
]
},
-
"links": {
-
"self": "/v1/hosts/abc-def"
}
}
}