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.

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
  },
  "records": [
    {
      "uuid": "upstream_1234567890",
      "host": "app.myapp.com",
      "port": 443,
      "tls": true,
      "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.

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,
  "bubble_io":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,
  "bubble_io":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."
}