Upstreams

Upstreams are a core part of SaaS Custom Domains.

An upstream refers to the server to which the reverse proxy forwards requests. In your case, this is most likely your web application, e.g. app.mydomain.com.

On this page, we'll dive into the different upstream endpoints you can use to manage upstreams programmatically. We'll look at how to query, create, update, and delete upstreams.

The upstream model

The upstream model contains all the information about your upstreams, such as their unique identifier, hostname, port, if upstream is expecting TLS traffic, if it is a Bubble.io app etc.

Properties

  • Name
    uuid
    Type
    string
    Description

    Unique identifier for the upstream.

  • Name
    host
    Type
    string
    Description

    The host of the upstream. This is the host of your web application where you expect to receive requests, e.g. app.mysaas.com.

  • Name
    port
    Type
    integer
    Description

    The port of the upstream. This is the port on which your web application listens. Default value is 443.

  • Name
    tls
    Type
    boolean
    Description

    Whether the upstream is using TLS. Default value is true.

  • Name
    created_at
    Type
    timestamp
    Description

    The date and time when the upstream was created.

  • Name
    updated_at
    Type
    timestamp
    Description

    The date and time when the upstream was last updated.

  • Name
    bubble_io
    Type
    boolean
    Description

    Whether the upstream is a Bubble.io app. Default value is false.

  • Name
    compression_enabled
    Type
    boolean
    Description

    Whether automatic response compression is enabled for this upstream. When enabled, responses over 512 bytes are automatically compressed using gzip or zstd based on the client's Accept-Encoding header. Default value is false.

  • Name
    geocoding_enabled
    Type
    boolean
    Description

    Whether geocoding headers are enabled for this upstream. When enabled, adds geographical headers (country, city, subdivision, postal code, continent, EU membership) based on the request's IP address to help with location-based content delivery and compliance. Default value is false.

Geocoding Headers

When geocoding_enabled is set to true, the following headers are automatically added to requests forwarded to your upstream:

  • X-SaaS-GeoIp-Country-Code - Two-letter country code (e.g., "US")
  • X-SaaS-GeoIp-Country-Name - Full country name (e.g., "United States")
  • X-SaaS-GeoIp-City - City name (if available)
  • X-SaaS-GeoIp-Subdivision-1-Name - Primary subdivision name (e.g., a state in the US)
  • X-SaaS-GeoIp-Subdivision-1-Code - Primary subdivision code (e.g., "CA")
  • X-SaaS-GeoIp-Subdivision-2-Name - Secondary subdivision name (if applicable)
  • X-SaaS-GeoIp-Subdivision-2-Code - Secondary subdivision code (if applicable)
  • X-SaaS-GeoIp-Postal-Code - Postal code or ZIP code
  • X-SaaS-GeoIp-Is-EU - Whether the country is in the EU ("1" for yes, "0" for no)
  • X-SaaS-GeoIp-Continent-Code - Two-letter continent code (e.g., "NA")
  • X-SaaS-GeoIp-Continent-Name - Full name of the continent
GET
/api/v1/accounts/:account_uuid/upstreams

List all upstreams for an account

This endpoint allows you to retrieve a paginated list of all your upstreams. By default, 20 upstreams are shown per page.

Optional attributes

  • Name
    host
    Type
    string
    Description

    Find upstream with the given host.

  • Name
    page
    Type
    integer
    Description

    The page number to retrieve. Default value is 1.

  • Name
    per_page
    Type
    integer
    Description

    The number of items to retrieve per page. Default value is 20.

Request

GET
/api/v1/accounts/:account_uuid/upstreams
curl -G https://app.saascustomdomains.com/api/v1/accounts/:account_uuid/upstreams \
  -H "Authorization: Bearer {token}" \
  -d page=7

Response

{
  "pagination": {
    "page": 7,
    "count": 237
  },
  "data": [
    {
      "uuid": "upstream_1234567890",
      "host": "app.myapp.com",
      "port": 443,
      "tls": true,
      "auth_token": "abcdef123456",
      "bubble_io": false,
      "compression_enabled": false,
      "geocoding_enabled": false,
      "created_at": "2023-03-10T07:14:35.823-06:00",
      "updated_at": "2023-03-10T07:14:35.823-06:00"
    },
    {
      "uuid": "upstream_0987654321",
      // ...
    }
  ]
}
POST
/api/v1/accounts/:account_uuid/upstreams

Create an upstream

This endpoint allows you to add a new upstream. To add an upstream, you must provide at least provide upstream's host.

Required attributes

  • Name
    host
    Type
    string
    Description

    The host of the upstream. This is the host of your web application where you expect to receive requests, e.g. app.mysaas.com.

Optional attributes

  • Name
    tls
    Type
    boolean
    Description

    Whether the upstream is using TLS. Default value is true.

  • Name
    port
    Type
    integer
    Description

    The port of the upstream. This is the port on which your web application listens. Default value is 443.

  • Name
    bubble_io
    Type
    boolean
    Description

    Whether the upstream is a Bubble.io app. Default value is false.

  • Name
    compression_enabled
    Type
    boolean
    Description

    Whether automatic response compression is enabled for this upstream. When enabled, responses over 512 bytes are automatically compressed using gzip or zstd. Default value is false.

  • Name
    geocoding_enabled
    Type
    boolean
    Description

    Whether geocoding headers are enabled for this upstream. When enabled, adds geographical headers based on the request's IP address. Default value is false.

  • Name
    auth_token
    Type
    string
    Description

    The auth token to use when forwarding requests to the upstream.

Request

POST
/api/v1/accounts/:account_uuid/upstreams
curl https://app.saascustomdomains.com/api/v1/accounts/:account_uuid/upstreams \
  -H "Authorization: Bearer {token}" \
  -d host="app.mysaas.com" \
  -d port=8888

Response

{
  "uuid": "upstream_180e8083",
  "host": "app.mysaas.com",
  "port": 8888,
  "tls": true,
  "auth_token": "abcdef123456",
  "bubble_io": false,
  "compression_enabled": false,
  "geocoding_enabled": false,
  "created_at": "2023-03-10T14:05:32.580+00:00",
  "updated_at": "2023-03-10T14:05:32.580+00:00",
}
GET
/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid

Retrieve an upstream

This endpoint allows you to retrieve an upstream by providing its UUID. Refer to the list at the top of this page to see which properties are included with upstream objects.

Request

GET
/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid
curl https://app.saascustomdomains.com/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid \
      -H "Authorization: Bearer {token}"

Response

{
  "uuid": "upstream_180e8083",
  "host": "app.mysaas.com",
  "port": 8888,
  "tls": true,
  "auth_token": "abcdef123456",
  "bubble_io": false,
  "compression_enabled": false,
  "geocoding_enabled": false,
  "created_at": "2023-03-10T14:05:32.580+00:00",
  "updated_at": "2023-03-10T14:05:32.580+00:00",
}
DELETE
/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid

Delete an upstream

This endpoint allows you to delete upstreams. Note: This will also delete custom domains for that upstream.

Request

DELETE
/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid
curl -X DELETE https://app.saascustomdomains.com/api/v1/accounts/:account_uuid/upstreams/:upstream_uuid \
  -H "Authorization: Bearer {token}"

Response

{
  "message": "Upstream upstream_180e8083 (app.mysaas.com) deleted."
}