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.

Example

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

x-ratelimit-limit

The number of requests that may originate from your client during the set period.

x-ratelimit-remaining

The number of requests remaining until the reset cycle.

x-ratelimit-reset

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:

active

The Host is protected by a valid SSL certificate. It will automatically renew with no additional cost.

processing

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.

invalid_dns

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.

auto_ssl_not_supported

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.

hostname_contains_underscore

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.

invalid_caa_record

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.

aaaa_record_present

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:

active

DNS has been configured correctly for this Host.

invalid

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).

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.