Approximated Custom Domains and SSL for SAAS Documentation

The virtual hosts API is how your application will interface directly with Approximated. You can use it to automate custom domains as needed. There are currently 6 endpoints: create, list, read, update, bulk update, and delete.

Note:
Make sure that you include headers for Content-Type and Accept set to 'application/json' for all requests to the API, and be sure to include your API key under the header api-key.

Understanding Virtual Hosts link

In Approximated, a virtual host represents a custom domain mapping. It defines how a custom domain (like "yourcustomdomain.com") should be routed to your application's actual domain (like "yourapp.com"). Virtual hosts are the core configuration objects in Approximated, and are automatically tied to a proxy cluster by the API key used to create them.

Each virtual host contains the following fields:

Not all fields are returned in every API response, and some fields (like monitoring data) are only available for existing virtual hosts. The sections below detail the endpoints for creating, listing, reading, updating, and deleting virtual hosts through the API.

Create Virtual Host link

Creating a virtual host is done with a JSON POST request to the Approximated API. It can be created at any time before or after the custom domain is pointed at the cluster with a DNS record.

// Example response:
{
"data": {
  "id": 445922,
  "incoming_address": "acustomdomain.com",
  "target_address": "myapp.com",
  "target_ports": "443",
  "keep_host": null,
  "lb_policy": "round_robin",
  "lb_enabled": true,
  "lb_sticky": false,
  "upstreams": [
    {
      "id": 123,
      "host": "myapp.com",
      "port": 443,
      "enabled": true
    },
    {
      "id": 124,
      "host": "server2.example.com",
      "port": 443,
      "enabled": true
    }
  ],
  "user_message": "In order to connect your domain, you'll need to have a DNS A record that points acustomdomain.com at 213.188.210.168. If you already have an A record for that address, please change it to point at 213.188.210.168 and remove any other A records for that exact address. It may take a few minutes for your SSL certificate to take effect once you've pointed your DNS A record."
}
}

// Example response
{
"errors": {
  "incoming_address": [
    "This incoming address has already been created on the cluster you selected."
  ],
  "upstreams": [
    {
      "params": {
        "host": "",
        "port": 0,
        "enabled": true
      },
      "index": 0,
      "errors": {
        "host": ["can't be blank"],
        "port": ["must be greater than 0"]
      }
    }
  ]
}
}

"upstreams": [
{
  "host": "server1.example.com",
  "port": 443,
  "enabled": true
},
{
  "host": "server2.example.com",
  "port": 443,
  "enabled": true
}
]

List Virtual Hosts link

We use a cursor based pagination system to page through your virtual hosts, up to 20 at a time. You can get the first page of the list by calling the first endpoint below, without a cursor.

You'll receive back a JSON object with a data field that contains the list of virtual hosts, as well as an after_cursor and before_cursor. You can then get the next or previous page by calling the endpoints below with the after or before cursor from the current results.

// Example response
{
"data": [
  {
    "apx_hit": true, // requests are reaching the cluster
    "created_at": "2023-04-03T17:59:28", // UTC timezone
    "dns_pointed_at": "213.188.210.168", // DNS for the incoming_address
    "has_ssl": true,
    "id": 405455,
    "incoming_address": "acustomdomain.com",
    "is_resolving": true, // is this returning a response
    "last_monitored_humanized": "1 hour ago",
    "last_monitored_unix": 1687194590,
    "ssl_active_from": "2023-06-02T20:19:15", // UTC timezone
    "ssl_active_until": "2023-08-31T20:19:14", // UTC timezone, auto-renews
    "status": "ACTIVE_SSL",
    "status_message": "Active with SSL",
    "target_address": "myapp.com",
    "target_ports": "443",
    "keep_host": null,
    "lb_policy": "round_robin",
    "lb_enabled": true,
    "lb_sticky": false,
    "upstreams": [
      {
        "id": 123,
        "host": "myapp.com",
        "port": 443,
        "enabled": true
      },
      {
        "id": 124,
        "host": "server2.example.com",
        "port": 443,
        "enabled": true
      }
    ]
  },
  // More virtual hosts...
],
"after_cursor": "a39fdk32kf", // will be null if there is no next page
"before_cursor": "lf3jeuc3406" // will be null if there is no previous page
}
      

The monitoring fields and statuses are from the latest monitoring results. A fresh check is not performed for the list before responding, and it cannot be force checked like an individual virtual host.

Read Virtual Host link

Use a GET request with the incoming_address at the end of the URL to retrieve the details of a single Virtual Host. If that Virtual Host was created with the API Key included in the header, it's details will be returned.

Note: to get by incoming incoming address, it must not include paths, query strings, or a protocol like https:// in the incoming address value. If you've included those in the virtual host you'd like to get, please use the alternative POST endpoint below that takes a JSON object with incoming_address instead.

{"incoming_address": "acustomdomain.com"}

// Example response
{
"data": {
  "apx_hit": true, // requests are reaching the cluster
  "created_at": "2023-04-03T17:59:28", // UTC timezone
  "dns_pointed_at": "213.188.210.168", // DNS for the incoming_address
  "has_ssl": true,
  "id": 405455,
  "incoming_address": "acustomdomain.com",
  "is_resolving": true, // is this returning a response
  "last_monitored_humanized": "1 hour ago",
  "last_monitored_unix": 1687194590,
  "ssl_active_from": "2023-06-02T20:19:15", // UTC timezone
  "ssl_active_until": "2023-08-31T20:19:14", // UTC timezone, auto-renews
  "status": "ACTIVE_SSL",
  "status_message": "Active with SSL",
  "target_address": "myapp.com",
  "target_ports": "443",
  "keep_host": null,
  "lb_policy": "round_robin",
  "lb_enabled": true,
  "lb_sticky": false,
  "upstreams": [
    {
      "id": 123,
      "host": "myapp.com",
      "port": 443,
      "enabled": true
    },
    {
      "id": 124,
      "host": "server2.example.com",
      "port": 443,
      "enabled": true
    }
  ]
}
}
      

In order to avoid spamming your custom domains with monitoring checks every time you call this endpoint, Approximated returns the results of the most recent recorded status check, which may be out of date.

If you'd prefer to have it check again before responding, you can add /force-check to the end of the endpoint URL. This may take up to 30 seconds if the domain DNS is not pointed yet, and is rate limited to minimize accidentally DDOSing your application.

Update Virtual Host link

Updating a virtual host is done with a JSON POST request to the Approximated API. It can be updated at any time before or after the custom domain is pointed at the cluster with a DNS record. Any optional fields not submitted will remain the same as they were previously.

// Example response
{
"data": {
  "apx_hit": true, // requests are reaching the cluster
  "created_at": "2023-04-03T17:59:28", // UTC timezone
  "dns_pointed_at": "213.188.210.168", // DNS for the incoming_address
  "has_ssl": true,
  "id": 405455,
  "incoming_address": "adifferentcustomdomain.com",
  "is_resolving": true, // is this returning a response
  "last_monitored_humanized": "1 hour ago",
  "last_monitored_unix": 1687194590,
  "ssl_active_from": "2023-06-02T20:19:15", // UTC timezone
  "ssl_active_until": "2023-08-31T20:19:14", // UTC timezone, auto-renews
  "status": "ACTIVE_SSL",
  "status_message": "Active with SSL",
  "target_address": "myapp.com",
  "target_ports": "443",
  "keep_host": true,
  "lb_policy": "least_conn",
  "lb_enabled": true,
  "lb_sticky": false,
  "upstreams": [
    {
      "id": 123,
      "host": "myapp.com",
      "port": 443,
      "enabled": true
    },
    {
      "id": 125,
      "host": "backup-server.example.com",
      "port": 443,
      "enabled": true
    }
  ]
}
}
      

// Example response
{
"errors": {
  "incoming_address": [
    "This incoming address has already been created on the cluster you selected."
  ],
  "upstreams": [
    {
      "params": {
        "host": "",
        "port": 0,
        "enabled": true
      },
      "index": 0,
      "errors": {
        "host": ["can't be blank"],
        "port": ["must be greater than 0"]
      }
    }
  ]
}
}

"upstreams": [
{
  "host": "server1.example.com",
  "port": 443,
  "enabled": true
},
{
  "host": "server2.example.com",
  "port": 443,
  "enabled": true
}
]

Bulk Update Virtual Hosts link

This endpoint allows you to update multiple virtual hosts at once with the same settings. It's useful when you need to change settings across many domains simultaneously, such as updating the target address for all domains in a batch.

You can update up to 100 virtual hosts in a single request. If more than 100 domains are provided, only the first 100 unique domains will be processed.

// Example request
{
  "incoming_addresses": [
    "domain1.com",
    "domain2.com",
    "domain3.com"
  ],
  "updates": {
    "target_address": "new-target.com",
    "target_ports": "443",
    "redirect": false,
    "exact_match": false,
    "keep_host": true,
    "lb_enabled": true,
    "lb_policy": "round_robin",
    "lb_sticky": true,
    "upstreams": [
      {
        "host": "upstream1.example.com",
        "port": 443,
        "enabled": true
      },
      {
        "host": "upstream2.example.com",
        "port": 443,
        "enabled": true
      }
    ]
  }
}

// Example response
{
  "data": {
    "summary": {
      "total_requested": 3,
      "successful": 2,
      "failed": 1,
      "not_found": 0
    },
    "successful": [
      "domain1.com",
      "domain2.com"
    ],
    "failed": [
      {
        "current_incoming_address": "domain3.com",
        "errors": {
          "target_address": ["can't be blank"]
        }
      }
    ],
    "not_found": []
  }
}

// Example response for validation errors
{
  "errors": {
    "target_address": ["can't be blank"],
    "upstreams": [
      {
        "params": {
          "host": "",
          "port": 0,
          "enabled": true
        },
        "index": 0,
        "errors": {
          "host": ["can't be blank"],
          "port": ["must be greater than 0"]
        }
      }
    ]
  }
}

// Example response for bad request
{
  "error": "Invalid incoming_addresses: must be a list"
}

Delete Virtual Host link

Use a DELETE request with the incoming_address or with the virtual host ID, to remove a single Virtual Host.

Note: to delete by incoming incoming address, it must not include paths, query strings, or a protocol like https:// in the incoming address value. If you've included those in the virtual host you'd like to delete, please use the alternative POST version of this endpoint that takes a JSON request object with a field for incoming_address instead.

{"incoming_address": "acustomdomain.com"}

Deleting customdomain.com

Virtual Host Statuses link

Virtual hosts can have different status codes that indicate their current state based on a variety of montoring checks. These are provided as a convenience, but may not be as granular as combining the various fields available within the virtual host response object yourself.

Note: this list may be added to in the future as we improve monitoring further, but existing statuses will not be deprecated without a new major API version release.

The DNS checks API allows you to check if DNS records exist for a domain or subdomain. It's provided as a convenience for your application, for scenarios like:

• Ensuring a user has pointed an A or CNAME record.
• Using TXT records to validate domain ownership.
• Helping you to support/debug DNS issues for your users.

Note:
Make sure that you include headers for Content-Type and Accept set to 'application/json' for all requests to the API, as well as including an Api-Key header with a current API key.

Check DNS Records Match Exactly link

Send a JSON POST request to the Approximated API with a list of data to compare against DNS records. Determines if an address has exactly one matching record for each data object in the list.

This check returns the list back to you with the results for 'match' and 'actual_values' injected into each object.

The 'match' field will only be true if there is exactly one DNS record/value for each address, and it must exactly match the 'match_against' value you've set.

{
  "records": [
    {
        "actual_values": [
            "93.184.216.34"
        ],
        "address": "example.com",
        "match": false,
        "match_against": "12.345.678.90",
        "type": "a"
    }
  ]
}

{
  "records": 
    [
      {
        "address": "example.com",
        "match_against": "12.345.678.90",
        "type": "a"
      }
    ]
}

Check DNS Records Exist link

Send a JSON POST request to the Approximated API with a list of data you'd like to check against the DNS records of an address.

DNS allows multiple records for the same address, and you may wish to check that at least one of them matches while disregarding the rest. This check is for that purpose.

The data list is returned back to you with injected fields for 'match' and 'actual_values'. The 'match' field will be true if there is any record/value that matches the 'match_against' field, regardless of how many other records/values there may be for that address.

{
  "records": [
    {
        "actual_values": [
            "93.184.216.34"
        ],
        "address": "example.com",
        "match": false,
        "match_against": "12.345.678.90",
        "type": "a"
    }
  ]
}

{
  "records": 
    [
      {
        "address": "example.com",
        "match_against": "12.345.678.90",
        "type": "a"
      }
    ]
}

We've created an optional DNS widget that's embeddable into your app, to help your users update their DNS records when connecting a custom domain.

The DNS widget detects the DNS provider and offers an automatic setup option where a supported provider integration is available. Provider-specific manual instructions are also available. Automation depends on the provider and requested record configuration.

DNS Widget Demo link

Try the widget with Classic, Dark, and Minimal styles in the full-page demo.

DNS Widget Basics link

• Embedded v2 uses two plain JavaScript files: the headless client and the widget renderer.
• Use the supplied CSS or override it to match your app.
• The widget renders directly in your page, with no iframe required.
• Start the widget by calling window.apxDns.init(config) after its container exists.
• The config object contains some settings and an array of the DNS records you'd like to apply to custom domains.
• You can optionally add a domain to the config to skip the domain entry UI step when the custom domain is already known.
• The widget calls Approximated API endpoints to detect domain DNS records, generate instructions/automation steps, and to verify changes.
• Embedded v2 renders instructions in the browser from the headless API’s JSON response.
  Prefer to render everything yourself? Use headless mode to display that JSON in your own components.

DNS Widget Setup link

We've tried to make the DNS widget easily compatible with as many different stacks and approaches as possible. The setup below uses embedded v2 with a scoped customer token, powered by the headless API.

1. Load the headless client, then the embedded v2 renderer:
   
   <script src="https://cloud.approximated.app/dnswidget/headless.v2.js"></script>
   <script src="https://cloud.approximated.app/dnswidget/dnswidget.v2.js"></script>
2. Link the CSS file from Approximated:
   
   <link rel="stylesheet" href="https://cloud.approximated.app/dnswidget/dnswidget.v2.css">
   Note: you can take a look at this file and override styles and variables as needed with your own CSS as well.
3. Add a container where the widget should render:
   
   <div id="apxdnswidget" class="apxdnswidget"></div>

   Then call the widget init function after the container exists. Replace the documentation address 192.0.2.10 with your cluster IPv4 address. The example configures the apex A record and a CNAME at www; {domain} is replaced with the domain entered by the customer.

   // Create the config data for the widget.
   const apx_dns_widget_config = {
       // Generate a scoped token on your server with GET /api/dns/v2/token.
       token: "use_token_api_endpoint_server_side_to_generate_this", 
       api_url: "https://cloud.approximated.app/api/dns/v2",
       /* 
       * The dnsRecords field is an array of record objects 
       * that you'd like to have applied to custom domains. 
       * 
       * These will likely be A records pointing at your cluster IP address,
       * or CNAME records pointing at an intermediary domain you control.
       * The dnsRecords always consist of:
       *      - [string]  type (Uppercase DNS record type like A, CNAME, or TXT)
       *      - [string]  host (Use @ for the apex domain or a subdomain with no trailing dot)
       *      - [string]  value (the address, value, text, etc. for that record type)
       *      - [integer] ttl (how many seconds the record should be cached in DNS servers)
       * We currently allow setting A, CNAME, and TXT records with the DNS widget.
       */
       dnsRecords: [
           {
               type: "A",
               host: "@",
               value: "192.0.2.10",
               ttl: 3600,
           },
           {
               type: "CNAME",
               host: "www",
               value: "{domain}",
               ttl: 3600,
           }
       ],
       // domain: "example.com", // optional, skips the domain entry UI step
       // prefillDomain: "example.com", // optional, prefills the domain without skipping
       verifyAutoScroll: true // optional, auto-scroll to verification results. Default: true
   };
       
   // Call the DNS widget init function to launch the widget.
   // In this example we call it after the DOM content is loaded.
   document.addEventListener("DOMContentLoaded", function(event) {
       // The DNS widget functions/data are automatically namespaced
       // and available from window.apxDns.
       window.apxDns.init(apx_dns_widget_config);
   });
   

4. Optionally, set javascript listeners to call some of your own logic based on widget events.

   // When the user submits a domain in the UI
   document.addEventListener('apx-dnswidget-user-submitted-domain', function(event) {
       // Your code to handle the event.
       // The event.detail string contains the custom domain/subdomain
       // submitted by the user into the UI.
   });
   
   // When the widget flow is restarted
   document.addEventListener('apx-dnswidget-restarted', function(event) {
       // Your code to handle the event.
   });
   
   // When all of the records are completely verified as updated successfully
   document.addEventListener('apx-dnswidget-records-completely-verified', function(event) {
       // Your code to handle the event.
       // The event.detail will contain the record results as a list of objects
   });
   
   // When none of the records match the desired updates, during verification
   document.addEventListener('apx-dnswidget-records-failed-verification', function(event) {
       // Your code to handle the event.
       // The event.detail will contain the record results as a list of objects
   });
   
   // When only some of the records are verified as updated successfully
   document.addEventListener('apx-dnswidget-records-partially-verified', function(event) {
       // Your code to handle the event.
       // The event.detail will contain the record results as a list of objects
       console.log(event.detail);
   
       // the output of the console.log above could look like this:
       [
           {
               actual_values: [
                   "192.0.2.10"
               ],
               apex: "example",
               combined_host: "@",
               domain: "example.com",
               full: "example.com",
               host: "@",
               match: true, // Approximated found an exact match DNS record
               match_against: "192.0.2.10", // The value to match against the DNS record
               non_tld: "example",
               subdomain: null,
               tld: "com",
               type: "A"
           },
           {
               actual_values: false,
               apex: "example",
               combined_host: "www",
               domain: "example.com",
               full: "example.com",
               host: "www",
               match: false, // Approximated could not find a matching DNS record
               match_against: "example.com", // The value to match against the DNS record
               non_tld: "example",
               subdomain: null,
               tld: "com",
               type: "CNAME"
           }
       ]
   });
   

5. You can optionally stop and clear the widget element or restart the flow.

   // Stop and clear the element used for the widget.
   // The init function will need to be called again to restart.
   window.apxDns.stop()
   
   // Alternatively, you can restart without stopping by calling this function:
   window.apxDns.restart()
   

DNS Widget Styling link

The widget comes with neutral styling that you can override with your own CSS. Its outermost element fills the available width up to 600px, with no fixed height, padding, or border, so you can fit it into your app. Explore the Classic, Dark, and Minimal styles to see how CSS can change its appearance.

Every CSS class in the element is prefixed with apxdns-, and the outermost element always has a class of apxdnswidget. The intention for this is to avoid any class name conflicts with your existing CSS code.

The widget also makes use of CSS variables scoped to the class apxdnswidget to enable easier theming. The available variables and their default values are as follows:

.apxdnswidget {
    --text-color: #333;
    --light-text-color: #666;
    --link-text-color: rgb(46, 90, 173);
    --main-bg-color: transparent;
    --shaded-bg-color: #FAFAFA;
    --shaded-border: 1px solid #EEE;
    --button-bg-color: #fb5168;
    --button-hover-bg-color: #da3551;
    --button-text-color: #FFF;
    --radius: 5px;
    --widget-max-width: 600px;
    --border-color: #EEE;
}

Scoped DNS Widget Tokens link

A scoped token is a temporary pass that lets the browser use the DNS widget without seeing your private API key. Create it on your server, then pass the returned token to the embedded widget or headless client. Each token is tied to the API key and proxy cluster that created it.

Call the URL below from an authenticated endpoint in your application. Check that the signed-in user is allowed to configure the domain, and send your cluster API key in the api-key header. Keep that key on your server.

{
    "token": "a-valid-token"
}

Each token lasts up to 10 minutes and 30 seconds. While the page is open, the client attempts renewal every five minutes. Renewals keep the same session going for at most 24 hours from its first token; they cannot extend that deadline. After expiry, restart the setup flow with a fresh token from your authenticated backend.

Deleting or replacing the API key that created a token stops that token and its renewals from working. Use a current key to start a new session. Token creation and renewal return Cache-Control: no-store; return that header from your own token endpoint too.

Use DNS Widget v2 throughout: /api/dns/v2/token creates the token, and instructions, DNS checks, and renewal use /api/dns/v2/. Load headless.v2.js for browser requests. The v2 browser API requires scoped tokens.

Widget tokens allow DNS instructions and checks. They do not prove domain ownership or give the browser permission to change your application’s accounts or domain settings.

Public demos use separate demo tokens: sessions last up to 30 minutes, requests allow one or two records, and instructions use manual setup without saving provider lookups. Use your own scoped customer token for your application, including supported automatic setup.

Headless Mode link

Build DNS setup into your own interface. Send us the customer’s domain and the records you need; we return their DNS provider, the values to enter, and step-by-step instructions as JSON. You decide how to display them.

Use headless mode when you want to use your own components, layout, or wording. If you’d prefer a complete interface you can drop into a page, start with the embeddable widget.

Explore the JSON demo to see the setup instructions alongside their API response.

1. Request the setup instructions link

For a browser integration, use our small JavaScript client. It has no dependencies, leaves the page’s HTML and styles to you, and renews the widget token while the customer works.

First, create an authenticated endpoint in your app that calls GET /api/dns/v2/token with your cluster API key. Have it return { "token": "…" } with Cache-Control: no-store. The examples call your endpoint /api/dns-widget-token; you need to implement it. Keep the API key on your server.

<script src="https://cloud.approximated.app/dnswidget/headless.v2.js"></script>
<script type="module">
  const tokenResponse = await fetch("/api/dns-widget-token", {
    credentials: "same-origin",
    cache: "no-store"
  });
  if (!tokenResponse.ok) throw new Error("Could not start DNS setup");
  const { token } = await tokenResponse.json();
  if (typeof token !== "string" || !token) {
    throw new Error("Your token endpoint returned an invalid token");
  }

  const client = window.apxDnsHeadless.createClient({ token });
  const result = await client.instructions({
    domain: "shop.customer.com",
    records: [
      { type: "CNAME", host: "@", value: "domains.example.com", ttl: 3600 }
    ]
  });
  console.log(result.domains);
</script>

This asks the customer to point shop.customer.com at domains.example.com. Replace both with the domain being connected and your application’s target hostname. Here, @ means the supplied domain itself, including its shop subdomain.

The snippet above logs the instructions. In your application, render them as described below and show a retry message if a request fails. If you prefer to call the API from your backend, skip to the API reference.

Start with React or Vue link

Preview the Simple, Dashboard, and Guided designs in your browser, then adapt the v2 starter for your app. You can switch designs without losing your progress. Each public starter includes provider instructions with copy buttons, verification results, retries, and a server endpoint that creates scoped tokens.

• React headless DNS widget starter · Try React demo
• Vue headless DNS widget starter · Try Vue demo

Use GitHub’s “Use this template” button or clone the starter for your framework. Open the starter folder and, with Node.js 22.12 or newer installed, run:

npm ci
cp .env.example .env

In .env, set APX_API_KEY to your server API key and VITE_CNAME_TARGET to the hostname customers should point to.

Both starters use headless.v2.js and the /api/dns/v2 API. Their server creates scoped customer tokens automatically. Start the interface:

npm run dev

Open http://127.0.0.1:5173. The API key stays on the Node server; the browser receives a short-lived token. The session code stops renewal when setup ends and ignores responses for a previous domain.

The included server runs locally only. When integrating with your application, move the token endpoint into your authenticated backend and check the customer's permission to configure the domain. Each repository’s README explains the files, configuration, and production integration.

2. Display the provider and record steps link

The response groups records by their root domain. For example, records for shop.customer.com and www.customer.com appear together under apex_domain: "customer.com". Each group has a provider object and a records array.

1. Show provider.message above the records. Add provider.login_url as a link when it’s available.
2. For each record, use record.title as a heading and render record.steps in order.
3. Choose how to display each step using its kind, as shown below.

{
  "kind": "field",
  "field": "host",
  "label": "Name",
  "value": "shop",
  "text": "Set Name to:"
}

For this step, your UI could show Name: shop. Use the step’s value for display: it already accounts for the provider’s conventions. An empty string means “leave this field blank”, and a TTL may be written as “1 Hour”. Render returned text as text, using your framework’s escaping or textContent.

If record.automation is present, you can also offer its url as an automatic setup link. Keep the manual steps available. A detected provider does not necessarily support automation; show the link only when it is returned.

If the provider can’t be identified, the API still returns general instructions. Use provider.lookup_status to distinguish a successful lookup from missing nameservers or a failed lookup, and give the customer a way to correct the domain or retry.

{
  "domains": [
    {
      "apex_domain": "customer.com",
      "provider": {
        "name": "Cloudflare",
        "provider_domain": "cloudflare.com",
        "detected": true,
        "supported": true,
        "lookup_status": "ok",
        "nameservers": [
          "ada.ns.cloudflare.com",
          "rob.ns.cloudflare.com"
        ],
        "message": "We've detected Cloudflare as your DNS provider.",
        "message_link": null,
        "login_url": "https://dash.cloudflare.com/",
        "logo_url": null
      },
      "records": [
        {
          "domain": "shop.customer.com",
          "apex_domain": "customer.com",
          "subdomain": "shop",
          "type": "CNAME",
          "host": "@",
          "combined_host": "shop",
          "value": "domains.example.com",
          "match_against": "domains.example.com",
          "ttl": 3600,
          "title": "Add a DNS CNAME record for shop.customer.com",
          "automation": null,
          "steps": [
            {
              "kind": "link",
              "text": "Sign in to Cloudflare.",
              "url": "https://dash.cloudflare.com/"
            },
            {
              "kind": "text",
              "text": "Select the account for customer.com, then open that domain."
            },
            {
              "kind": "text",
              "text": "In \"DNS management for customer.com\", click Add Record."
            },
            {
              "kind": "text",
              "text": "Select CNAME as the record type."
            },
            {
              "kind": "field",
              "field": "host",
              "label": "Name",
              "value": "shop",
              "text": "Set Name to:"
            },
            {
              "kind": "field",
              "field": "value",
              "label": "Target",
              "value": "domains.example.com",
              "text": "Set Target to:"
            },
            {
              "kind": "field",
              "field": "ttl",
              "label": "TTL",
              "value": "3600",
              "text": "Set TTL to:"
            },
            {
              "kind": "text",
              "text": "Click Save to add the record."
            }
          ]
        }
      ]
    }
  ]
}

3. Check the customer’s changes link

Once the customer has saved their DNS changes, let them run a check. Pass the original instructions result to client.verify(); the client sends the correct record fields for you. Run this when the customer clicks your check button, using the same client and result from step 1.

try {
  const check = await client.verify(result);
  const state = client.summarize(check.records);
  console.log(state);         // "complete", "partial", or "failed"
  console.log(check.records); // Each record includes match and actual_values
} catch (error) {
  console.error(error.code, error.message);
  // Show a retry message in your UI.
}

The client checks for an exact match: each queried name must have exactly one value for the requested record type, and it must equal match_against. To allow other values alongside the expected one, such as multiple TXT records, use the check-records-exist API instead.

Each checked record includes match and actual_values. The latter is an array of values when DNS returns records, or false when no values are found. DNS updates can take time to become visible because of caching. A successful check confirms the DNS result; your backend should check the domain’s association with the customer, routing, and HTTPS before marking the domain connected.

{
  "token": "YOUR_WIDGET_TOKEN",
  "records": [
    {
      "domain": "shop.customer.com",
      "host": "@",
      "type": "CNAME",
      "match_against": "domains.example.com"
    }
  ]
}

{
  "records": [
    {
      "address": "shop.customer.com",
      "type": "cname",
      "match_against": "domains.example.com"
    }
  ]
}

Manage the client’s lifecycle link

Keep the client alive while the customer follows the instructions. It attempts renewal every five minutes; each token lasts up to 10 minutes and 30 seconds, within the session’s 24-hour deadline. Call client.stop() when the setup component is removed or the flow is finished. Handle renewal errors with onError. After expiry or key replacement, stop the old client and create a new one with a fresh token from your authenticated backend.

Instructions API reference link

Both endpoints return the same JSON. Send Content-Type: application/json and Accept: application/json. Choose authentication based on where your code runs:

{
  "token": "YOUR_WIDGET_TOKEN",
  "domain": "shop.customer.com",
  "records": [
    { "type": "CNAME", "host": "@", "value": "domains.example.com", "ttl": 3600 }
  ]
}

Response field reference link

A successful request returns 200 with a domains array. Groups appear in the order their root domains first appeared in your request; records within each group keep their original order. Each group contains apex_domain, provider, and records.

DNS Widget v2 uses the /api/dns/v2/ API and headless.v2.js client. New response fields may be added within v2, so ignore fields you don’t need. Breaking changes will use a new API path and client version; existing versions will keep their contract.

Handle errors and expired sessions link

The instructions endpoints return the following error statuses. The client exposes API failures as ApxDnsError objects with code, message, status, and details.

{
  "error": "invalid_domain",
  "message": "One or more records are invalid; see details",
  "details": [
    { "index": 0, "field": "domain", "message": "must be a valid hostname such as example.com or app.example.com" }
  ]
}

The client also uses network_error when a fetch fails, and request_failed for an unsuccessful response without a JSON error code. Calling createClient() without a token throws missing_token immediately. Handle request failures with try/catch and use the onError callback for token renewal failures.

DNS Widget Versioning link

Use v2 for token creation, the browser API, and JavaScript files:

Customer sessions accept at most 25 A, CNAME, or TXT records per instructions request, with a valid domain, a non-empty host and value, and a positive numeric TTL when provided. Use @ for the entered domain; omit TTL to use the default of 3600 seconds instead of passing Auto.

Embedded v2 verifies the normalized records returned by the API. Verification events contain those check results; use match_against for the expected value. Call stop() before removing the widget during client-side navigation.

Security fixes and compatible patches may update a pinned version. Breaking changes get new asset names or API paths; existing paths will not silently switch to a newer version.

Approximated allows you to receive notifications about events happening with your virtual hosts by sending HTTP GET or POST requests to a URL you control.

Webhooks can be configured from your dashboard by logging in and navigating to the "Webhooks" section. A basic log history for each configured webhook is also available there.

Configuring Your Webhooks link

Understanding the following configuration options will help you make the most of the webhooks feature and ensure secure and reliable event handling.

Webhook Events link

The following webhook events can be configured:

{
  "idempotent_key": "apx-whl-1234567890",
  "data": {
    "id": 160389,
    "keep_host": null,
    "lb_policy": "first",
    "lb_sticky": true,
    "upstreams": [],
    "lb_enabled": false,
    "target_ports": "443",
    "target_address": "ourapplication.com",
    "incoming_address": "acustomdomain.com"
  },
  "type": "virtual_host",
  "event": "create"
}
            

{
  "idempotent_key": "apx-whl-1234567891",
  "data": {
    "id": 1599456,
    "status": "ACTIVE_SSL",
    "apx_hit": true,
    "has_ssl": true,
    "keep_host": null,
    "lb_policy": "first",
    "lb_sticky": true,
    "upstreams": [],
    "created_at": "2025-04-22T22:44:49",
    "lb_enabled": false,
    "is_resolving": true,
    "target_ports": "443",
    "dns_pointed_at": "213.188.215.88",
    "status_message": "Active with SSL",
    "target_address": "ourapp.com",
    "ssl_active_from": "2025-04-22T21:46:24",
    "incoming_address": "acustomdomain.com",
    "ssl_active_until": "2025-07-21T21:46:23",
    "last_monitored_unix": 1745361972
  },
  "type": "virtual_host",
  "event": "update"
}
            

{
  "idempotent_key": "apx-whl-1234567892",
  "data": {
    "id": 16054568,
    "keep_host": null,
    "lb_policy": "first",
    "lb_sticky": true,
    "upstreams": [],
    "lb_enabled": false,
    "target_ports": "443",
    "target_address": "ourapp.com",
    "incoming_address": "acustomdomain.com"
  },
  "type": "virtual_host",
  "event": "delete"
}
            

{
  "idempotent_key": "apx-whl-1234567893",
  "data": {
    "url": "acustomdomain.com",
    "status": "DNS_INCORRECT",
    "apx_hit": false,
    "changes": {
      "dns_resolution": {
        "new": "34.224.149.186, 3.18.255.247",
        "old": "4.16.255.147, 35.223.139.196"
      }
    },
    "has_ssl": false,
    "dns_details": {
      "values": [
        "34.224.149.186",
        "3.18.255.247"
      ],
      "wrong_ips": [
        "34.224.149.186",
        "3.18.255.247"
      ],
      "contains_cluster_ip": false
    },
    "is_resolving": false,
    "dns_pointed_at": "34.224.149.186, 3.18.255.247",
    "status_message": "DNS incorrect",
    "ssl_active_from": "2024-10-17T14:21:20",
    "virtual_host_id": 1186546,
    "ssl_active_until": "2025-11-17T14:20:20",
    "last_monitored_unix": 1746479579
  },
  "type": "virtual_host_monitor",
  "event": "update"
}
            

Edge Verify is invisible bot protection for your forms, built into your Approximated proxy. There are no CAPTCHA puzzles for your visitors to solve, no third-party scripts, no keys to manage, and no cookies.

Unlike CAPTCHA services, there's also no server-side integration: no verification API to call, no SDK to install, and no backend changes. Because Approximated is already your proxy, the edge validates submissions itself and blocks bad ones before they ever reach your app.

How It Works link

A small script, served first-party from your own domain by the edge, transparently proves that a visitor is a real browser using a background proof-of-work and environment signals. It then mints a short-lived signed token (valid for about 10 minutes and refreshed automatically) that is bound to the visitor and domain, and is single-use.

The script injects the token as a hidden _apx_verify_token field into every form on the page, including forms added later by single-page apps. When the form is submitted, the edge validates the token and either passes the request through to your app or blocks it.

Edge Verify blocks non-browser spam outright and makes automated abuse significantly more expensive, while staying invisible to your real users. The scoring intentionally errs toward letting a human through, because a false block would break a real form submission.

Setting Up Edge Verify link

Setup takes two steps, and neither one touches your backend.

1. Add the widget script to any pages with forms you want to protect:
   
   <script src="/__apx_verify/widget.js" defer></script>
   Note: the script is served from your own domain by the edge, so there's no third-party URL and nothing extra to host.
2. Create an Edge Verify rule for your virtual host by logging into your dashboard and navigating to your virtual host, then More, then the Edge Verify tab. You can also create rules for every virtual host at once from your cluster's panel. A rule consists of:
   • Method and path: the form submission to protect, e.g. POST /contact.
   • Mode: monitor or enforce, described below.

That's it - there is no step 3. There's no verification endpoint to call from your server, no secret to store, and no code change in your app. The edge blocks bad submissions before they reach your origin.

Monitor and Enforce Modes link

Each Edge Verify rule runs in one of two modes:

Running in monitor mode first lets you watch the stats and confirm that real submissions are passing before anything is blocked. Anything that would trip up the widget, like broken javascript on a page or an unusual browser, shows up as data instead of lost submissions. Once the passed rate looks right, flip the rule to enforce.

Edge Verify API link

Everything you can do with rules in the dashboard can also be automated through the REST API, using the same headers and api-key as the Virtual Hosts API. Rule changes propagate to the edge automatically within about a minute.

Rules can be managed per virtual host, identified by its incoming address in the JSON body - the same by-incoming convention as the Virtual Hosts API endpoints. All four endpoints are POST requests:

Or cluster-wide, where a rule applies to every virtual host on the cluster. The cluster is implicit from your API key, so there's no cluster id in the path:

Create and update requests accept the following rule fields, in both scopes:

For example, creating an enforce rule on a virtual host:

await fetch("https://cloud.approximated.app/api/edge-verify/rules/create/by/incoming", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "Accept": "application/json",
        "api-key": "your-cluster-api-key"
    },
    body: JSON.stringify({
        incoming_address: "acustomdomain.com",
        path_pattern: "/contact",
        methods: ["POST"],
        mode: "enforce"
    })
});

Which returns a 201 with the created rule:

{
  "data": {
    "id": 42,
    "virtual_host_id": 445922,
    "proxy_server_id": null,
    "path_pattern": "/contact",
    "methods": ["POST"],
    "mode": "enforce",
    "inserted_at": "2026-07-30T14:21:20",
    "updated_at": "2026-07-30T14:21:20"
  }
}

Fetch and JSON Submissions link

Regular HTML form posts need nothing extra - the hidden _apx_verify_token field is injected for you. If you submit with fetch or another javascript request instead, ask the widget for a token and send it in the X-Apx-Verify-Token header:

const token = await window.apxVerify.getToken();

await fetch("/contact", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-Apx-Verify-Token": token
    },
    body: JSON.stringify({ message: "Hello!" })
});

Reading the Stats link

The Edge Verify tab shows an outcomes panel for each rule, with a chart and a time range picker, available per virtual host and for the whole cluster. Submissions are counted by outcome:

The block rate shown is the share of submissions that didn't pass. In monitor mode, that's the share that would have been blocked, which is exactly what you want to review before switching a rule to enforce.

Limits and Troubleshooting link

• The form must POST to the proxied domain. Edge Verify can't protect forms that submit to a third-party or un-proxied endpoint, because those submissions never pass through the edge.
• Visitors with broken javascript or unusual browsers can't run the widget. In monitor mode these surface as missing-token data rather than lost submissions, which is another reason to start there.
• If a legitimate form is being flagged, check with your browser's dev tools that the hidden _apx_verify_token field is present in the submitted form, confirm the rule's method and path match the submission exactly, and use monitor mode while debugging.
• Edge Verify is currently rolling out across clusters, so it may not be available on yours quite yet. If you don't see the Edge Verify tab, feel free to reach out and we can prioritize your cluster.

Beyond Forms link

Because a rule is just a method and a path, and the token can ride a header, Edge Verify isn't limited to classic form submits. A valid token proves the request came from a real browser running your page, so you can attach it to anything your frontend calls: login and signup endpoints (against credential stuffing and signup abuse), comment and review submissions, votes, add-to-cart, or any JSON API behind your pages.

The mechanics are the same as any other javascript submission - send the token in the X-Apx-Verify-Token header as shown in Fetch and JSON Submissions, and create a rule for the endpoint's method and path.

Two boundaries to keep in mind: this only applies to browser traffic, since mobile apps and server-to-server clients can't run the widget. And plain page navigations aren't the target - the widget can't attach a token to a regular GET page load.

Privacy link

Edge Sequences let you inspect and change requests at the edge, before they reach your application. A sequence belongs to one proxy cluster and can match traffic for any virtual host on that cluster. Use them to add headers, rewrite paths, redirect old URLs, block unwanted requests, reroute traffic to a different origin, or apply rate limits.

Everything on this page is done from the dashboard: open Edge Sequences, choose the proxy cluster you want to change, and edit an inactive draft before you make it current and activate it. To automate the same work, see the Edge Sequences API.

How Edge Sequences Work link

A sequence has one or more matcher groups, which decide whether it applies to a request, and an ordered list of rules, which run from top to bottom when it does. Sequences run before the cluster's normal virtual-host routing, in the numbered cluster-wide order shown in the dashboard, so more than one sequence can act on the same request. Use the arrow controls beside a sequence to change that order.

1. 1
   A request arrives
   A visitor requests any virtual host on the cluster.
2. 2
   Edge Sequences run, in cluster order
   For each sequence: if any of its matcher groups matches, its rules run from top to bottom. Otherwise the sequence is skipped.
   A Blocker, Redirect, or Reroute rule answers the request right here. Nothing below runs.
3. 3
   Virtual host routing
   Sees the request as the rules left it and forwards it to the virtual host's origin.
4. 4
   Your application
   Handles the request. The response returns to the visitor through the cluster.

Changes made by an earlier rule, such as a rewritten path or an added request header, are visible to later rules, later sequences, virtual-host routing, and your application. A terminal rule (Blocker, Redirect, or Reroute) answers the request itself, so later rules and later sequences never run for it.

Create and Deploy a Sequence link

1. Choose the proxy cluster whose traffic you want to control.
2. Select Create Edge Sequence, give it a descriptive name, and save it. New sequences start inactive, with an empty draft.
3. Add at least one matcher group with at least one matcher. Without one, the sequence matches nothing.
4. Add one or more rules and arrange them in the order they should run. Without rules, the sequence has no effect.
5. Choose Save as current version while the sequence is inactive, then activate it when you are ready.

If you edit an active sequence, the dashboard creates a draft from its current version. The live version keeps serving until you choose Deploy as current version. Saving or activating a version queues a cluster configuration update, which reaches every region within about a minute.

Build Matcher Groups link

A matcher can be marked negative. With one negative matcher, the group simply skips requests that match it. With two or more, they act as a single combined exception: the group only skips requests that match all of them at the same time. To exclude requests that match any of several values, list those values in one negative matcher instead, for example several paths in a single Path matcher.

Match All Requests makes its group unconditional and causes other matchers in that group to be ignored, so use it by itself. A group with no matchers is ignored.

Matcher Types link

Each matcher checks one property of the request. Combine several in a group to narrow the match.

Rule Types and Ordering link

Rules run in the order they appear in the sequence. The last three below are terminal: they answer the request themselves.

Terminal rules stop later rules and later sequences, so put a Blocker, Redirect, or Reroute last. The dashboard warns when a terminal rule makes later rules unreachable, but does not reorder the sequence for you.

Write and Validate Regex Matchers link

A Regex matcher tests a pattern against one request value, chosen under Match against: the path, the incoming host, the query string, a request header of your choice, or the Edge Verify outcome. Give each matcher a short, unique name and enter a pattern using RE2 syntax. Use ^ and $ when the entire value must match; without anchors, a matching substring is enough.

Capture groups are exposed to later rules as placeholders scoped by the matcher's name. The example above makes the captured user segment available as {http.regexp.user_path.1}, and {http.regexp.user_path.0} holds the whole match. Named groups such as (?P<slug>[^/]+) are available as {http.regexp.user_path.slug}. RE2 intentionally does not support lookahead, lookbehind, or backreferences.

The dashboard checks that the pattern compiles when you save the matcher. That only proves the syntax is valid, not that the matcher group selects the traffic you expect, so confirm changes with representative non-production requests before relying on them to block, redirect, or reroute production traffic.

Drafts, Versions, and Activation link

• Draft: editable matcher groups and rules that do not serve traffic.
• Current version: the saved definition that serves traffic while the sequence is active.
• Historical version: a previous definition you can view, clone into a new draft, or make current again.

Version history covers matcher groups and rules only. A sequence's name, active state, and position in the cluster-wide order are separate settings and are not restored when you make an older version current. Reordering or activating a sequence acts on its current version even when a draft exists.

Safe Rollout Checklist link

1. Start with the narrowest matcher that covers representative test traffic.
2. Keep the sequence inactive while you review matcher groups, rule order, and terminal-rule warnings.
3. Save the draft as current, activate it, and allow about a minute for the configuration to propagate.
4. Test from more than one region when the behavior is region-sensitive.
5. If results differ from what you expect, deactivate the sequence first, then fix a new draft or restore a previous version.

Troubleshooting link

• Nothing happens: confirm the sequence is active, has a current version, contains a matcher group with at least one matcher, and has at least one rule.
• Too much traffic matches: check for a Match All Requests matcher, for extra groups (each one is another way to match), and for a regex that needs anchors.
• Negative matchers surprise you: several negatives in one group only exclude requests that match all of them at once.
• A later rule never runs: look for an earlier Blocker, Redirect, or Reroute rule, including one in an earlier sequence.
• A restored version behaves differently: check its active state and cluster-wide order separately, because those are not versioned.

For automation, dry-run validation, and complete request schemas, see the Edge Sequences API reference.

The Edge Sequences API automates everything the Edge Sequences dashboard can do: block, redirect, rewrite, reroute, rate limit, or change headers on requests before they reach your app. Read that guide first if you are new to sequences, matcher groups, and rules.

The API is declarative. A create or update request carries the full desired definition of a sequence, and the edge is updated to match it. Every apply becomes a new numbered version, so you get version history and one-call rollback for free. The cluster is implied by your api-key, so no path contains a cluster id.

Applying a Definition link

An apply (create or update) validates the whole definition, stores it as the next version, and promotes that version live in a single transaction. There is no partially-applied state. The previous live version moves into the version history, and so does any unpromoted draft from the dashboard editor. Changes reach the edge automatically within about a minute.

Reads round-trip: the data object returned by any read or list endpoint is itself a valid apply payload, so you can GET a sequence, change it, and POST it back.

Every apply also returns a warnings map, described under Warnings. A definition can save successfully and still need your attention.

Authentication and Rate Limits link

All endpoints use the same api-key header as the Virtual Hosts API, and everything is scoped to the cluster attached to that key. Sequences on other clusters return a 404.

The general API budget of 240 requests per minute per key applies to every endpoint. Writes (create, update, delete, activate, deactivate, reorder, and version rollback) have an additional budget of 30 requests per minute per key. Exceeding it returns a 429 with {"error": "rate_limit_exceeded"}. Reads and version listing only consume the general budget.

How Matching Works link

A sequence's matcher_groups decide which requests it applies to:

• The sequence matches when any group matches.
• A group matches when all of its positive matchers match.
• A group's negative matchers form one combined exception: the group is skipped only when every negative matcher matches at once. To exclude any of several values, list them in a single negative matcher instead. See Build Matcher Groups for examples.
• When a request matches, the sequence's rules run in array order.

Blocker, redirect, and reroute rules return a response and stop processing, so anything after them in the array never runs. The API accepts such definitions but reports the shadowing in warnings. Sequences themselves also run in a cluster-wide execution order (the order field), adjustable with the reorder endpoint.

The Apply Payload link

Create and update take the same JSON body:

Validation failures come back as a 422 whose errors map has one entry per problem location. Keys are JSON Pointers into the payload you sent, so /rules/0/config/max_events is the max_events field of your first rule, and the empty key "" is the sequence as a whole. Each value is a list of problems, each with a stable code for your code to branch on and a message for people. Warnings use the same shape.

{
  "errors": {
    "/matcher_groups/0/matchers/1/type": [
      {"code": "unknown_type", "message": "unknown matcher type"}
    ],
    "/rules/0/config/max_events": [
      {"code": "required", "message": "can't be blank"}
    ]
  }
}

Create a Sequence link

Creates the sequence at the end of the cluster's execution order and promotes it live as version 1:

curl -X POST https://cloud.approximated.app/api/edge-sequences \
  -H "Content-Type: application/json" \
  -H "api-key: your-cluster-api-key" \
  -d '{
    "name": "Block legacy admin panel",
    "description": "Deny requests to /admin on every domain",
    "matcher_groups": [
      {"matchers": [
        {"type": "path", "data": {"paths": ["/admin*"]}}
      ]}
    ],
    "rules": [
      {
        "type": "blocker",
        "name": "Deny admin",
        "config": {"status_code": "403", "body": "Forbidden"}
      }
    ]
  }'

Returns a 201 with a Location header and the created sequence:

{
  "data": {
    "id": 12,
    "name": "Block legacy admin panel",
    "description": "Deny requests to /admin on every domain",
    "order": 0,
    "active": true,
    "live_version": 1,
    "has_draft": false,
    "matcher_groups": [
      {
        "matchers": [
          {"type": "path", "negative": false, "data": {"paths": ["/admin*"]}}
        ]
      }
    ],
    "rules": [
      {
        "type": "blocker",
        "name": "Deny admin",
        "description": null,
        "config": {
          "handler": "static_response",
          "headers": {"apx-hit": ["true"]},
          "status_code": "403",
          "body": "Forbidden",
          "close": true
        }
      }
    ],
    "created_at": "2026-08-17T14:21:20",
    "updated_at": "2026-08-17T14:21:20"
  },
  "warnings": {}
}

A rule's returned config echoes the stored configuration, which can include server-computed keys such as handler and injected headers alongside the fields you supplied. The whole object is accepted back on apply, so the response stays a valid payload. A dry run ("dry_run": true) returns a 200 with "data": null and any warnings instead.

List and Read Sequences link

curl https://cloud.approximated.app/api/edge-sequences/12 \
  -H "api-key: your-cluster-api-key"

A read returns the same sequence object as above, with an always-empty warnings map. A list wraps the sequences with cursors, which are non-null when more results exist in that direction:

{
  "data": [{"id": 12, "name": "Block legacy admin panel", "...": "..."}],
  "cursors": {"before": null, "after": "g3QAAAABZAACaWRhDA=="}
}

Update a Sequence link

A full replace, not a patch: send the complete desired definition and it becomes the next live version. Anything you leave out of matcher_groups or rules is gone from the new version (though still in the version history). name and active may be omitted to keep their current values.

curl -X POST https://cloud.approximated.app/api/edge-sequences/12/update \
  -H "Content-Type: application/json" \
  -H "api-key: your-cluster-api-key" \
  -d '{
    "matcher_groups": [
      {"matchers": [
        {"type": "path", "data": {"paths": ["/admin*", "/wp-admin*"]}}
      ]}
    ],
    "rules": [
      {
        "type": "blocker",
        "name": "Deny admin",
        "config": {"status_code": "403", "body": "Forbidden"}
      }
    ]
  }'

Returns a 200 with the updated sequence (now "live_version": 2) and any warnings. Rate limit counters survive updates, so an update does not reset limits mid-window (see Rule Types).

Delete, Activate, and Deactivate link

curl -X POST https://cloud.approximated.app/api/edge-sequences/12/deactivate \
  -H "api-key: your-cluster-api-key"

Activate and deactivate return a 200 with the sequence. Both are safe to repeat.

Reorder Sequences link

Moves the sequence to a position in the cluster's execution order. The body is {"position": 0}: zero-based, and clamped into the valid range, so a large number means "move to the end". Other sequences shift accordingly. A missing or non-integer position returns a 422 with invalid_type at /position.

curl -X POST https://cloud.approximated.app/api/edge-sequences/12/reorder \
  -H "Content-Type: application/json" \
  -H "api-key: your-cluster-api-key" \
  -d '{"position": 0}'

Matcher Types link

Every matcher has the same shape:

{"type": "path", "negative": false, "data": {"paths": ["/admin*"]}}

• type picks one of the matcher types below.
• negative (optional, default false) inverts the match. Several negative matchers in one group combine into a single exception; see How Matching Works.
• data holds the fields for that type:

Rule Types link

Every rule has the same shape:

{"type": "blocker", "name": "Deny admin", "description": null, "config": {"status_code": "403"}}

• type picks one of the rule types below.
• name and description are optional labels for your own reference. They do not affect behavior.
• config holds the settings for that type:

Warnings link

Applies and dry runs return a warnings map for definitions that saved successfully but still need attention. It has the same shape as errors: JSON Pointer keys into your payload, a list of problems per key, and the empty key "" for the sequence as a whole. The map is empty when there is nothing to report.

"warnings": {
  "/rules/0": [
    {
      "code": "shadows_later_rules",
      "message": "redirect returns a response, so the rules after it never run"
    }
  ],
  "/rules/1": [
    {
      "code": "unreachable",
      "message": "rule 0 (redirect) returns a response before it",
      "blocked_by": "/rules/0"
    }
  ]
}

Version History and Rollback link

curl https://cloud.approximated.app/api/edge-sequences/12/versions \
  -H "api-key: your-cluster-api-key"

{
  "data": [
    {
      "version": 2,
      "live": true,
      "draft": false,
      "name": "Block legacy admin panel",
      "description": null,
      "matcher_group_count": 1,
      "rule_count": 1,
      "created_at": "2026-08-17T15:02:11"
    },
    {
      "version": 1,
      "live": false,
      "draft": false,
      "name": "Block legacy admin panel",
      "description": null,
      "matcher_group_count": 1,
      "rule_count": 1,
      "created_at": "2026-08-17T14:21:20"
    }
  ],
  "cursors": {"older": null, "newer": null}
}

Version summaries do not include the definition itself. A version's draft flag is true for an unpromoted dashboard draft. The cursors are opaque integers, not version numbers, and a cursor is null when there are no more versions in that direction. To roll back, promote a historical version by its number:

curl -X POST https://cloud.approximated.app/api/edge-sequences/12/versions/1/activate \
  -H "api-key: your-cluster-api-key"

Returns a 200 with the sequence now serving version 1. Activating the already-live version is a safe no-op, and a version number that doesn't exist for the sequence returns a 404.

Errors link

When a request for a custom domain reaches your application, you likely want to return content specific to that custom domain. For example, if your app hosts blogs, the custom domain should return content for that particular blog.

The sections below should help guide you in making any changes necessary to your application in order to handle custom domains.

The Request/Response Flow link

When a request goes through your Approximated cluster, it's relayed as shown below:

Approximated provides SSL encryption between the user and the cluster, but only your app or server can provide SSL encryption between the cluster and your app.

If your target address is a naked IP address, you won't be able to SSL encrypt a connection to it or use port 443 (typically reserved for SSL connections).

Luckily, most applications already have a domain or subdomain pointed at their application with an SSL certificate. It depends on your app, but it's very likely you can simply re-use this as your target address for custom domains.

Determining the custom domain link

Approximated has a few ways that your app can determine the custom domain for a request.

1. (Default) Apx-Incoming-Host header

   By default, Approximated will change the host header in each request to match the target address instead of the incoming address (the custom domain).

   We've made this choice because often apps, servers, or reverse proxies are not ready to handle any domain but the primary app domain without modifications.

   We always inject an extra header "Apx-Incoming-Host" to every request, which the app can use to determine the custom domain when it receives the request.

2. Keep the Host header as-is

   Alternatively, you can set your proxy cluster to keep the Host header for each request as the incoming address instead of modifying it.

   You can find this by opening your proxy cluster in the dashboard and changing the Keep Host Headers setting to True. This can be overridden for each virtual host, as well.

   To do so, in the dashboard under advanced settings you can set Keep Host to True/False/Default. In the API, you can set keep_host to true/false/null to achieve the same.

3. Send the X-Forwarded-Host header

   Finally, you can set your proxy cluster to add an X-Forwarded-Host header containing the incoming address for each request. This is independent of the other settings.

   You can find this by opening your proxy cluster in the dashboard and changing the Send X-Forwarded-Host setting to True.

Statically Generated Content link

With statically generated content, you probably have folders and files sitting on a server for each custom domain. For example, a request to mybloghost.com/some-blog will load the content directly from the /some-blog folder on your server.

In this situation, there's probably no code being run before that content is loaded directly from the files. You might have caching, but the end result is the same.

For statically generated sites, the easiest way to integrate custom domains is likely to target that user's folder URL directly. With Approximated, you can accomplish this by adding a path to your virtual host target address field.

For example:

There are some obstacles to this approach, however:

Laravel link

Laravel is one of the easiest frameworks to integrate with Approximated. We've created an entire guide for you, and a Laravel custom domains example repo to make things even easier.

You won't need to install any additional packages (security team high five!) and the guide covers every aspect you'll need to know about custom domains in a Laravel app - from request to response.

Ruby on Rails link

Ruby on Rails makes integrating with Approximated easy. The best way to learn how to integrate Approximated with your Rails app is to look at our Ruby on Rails custom domains guide and its companion GitHub example repo.

That guide and repo show a working example that demonstrates creating pages that can be tied to a custom domain, the routing required, and a class that interfaces with the Approximated API for you.

Elixir Phoenix link

Apps using Elixir's Phoenix framework can integrate with Approximated easily, including websockets for liveview. We've created a comprehensive developers guide for supporting custom domains in Phoenix to help you get up and running as fast as possible.

We've also created a companion example repo here for you to explore and run easily.

The example repo is a simple blog hosting platform, where you can create blogs and tie them to a custom domain. It should serve as a reference for how your Phoenix app can handle routing, liveviews/websockets, security features, and more for custom domains.

Next.js link

Next.js can be used with Approximated, whether you host it with Vercel or anywhere else. We've created a comprehensive developers guide for supporting custom domains in Next.js to help you get up and running as fast as possible, which includes examples using both the App and Page routers.

We've also created a companion example repo here for you to explore and run easily, to get a sense of how Approximated could be used to integrate custom domains into your Next.js app.