/v3/api/sites (POST) - User Guide

Creates a new site.

POST https://api-<BlueCat.edge.url>/v3/api/sites
Authorization: Bearer token
Content-type: application/JSON
{
    "name": "name",
    "location": { 
        "address": "123 Anystreet Road, Some City, Canada",
        "lat": "43.77367", 
        "lng": "-79.383802"
        }, 
    "settings": {
        "timeZone":"Australia/Sydney", 
        "associatedNamespaces": [ 
            { 
            "id": "5721f5b9-fe9e-11e7-8bf7-0abb5ee73c46",
            "overridingForwarders": ["1.1.1.2"] 
            }
         ]
    },
    "version": "3.0.6"
    "streamDataToCI": true,
    "loggingEndpointId": "123e4567-e89b-12d3-a456-426614174000", 
    "identityServiceEnabled": false,
    "randomizeAddresses": false,
    "soaDefinition": {
        "authorityZone": "example.com",
        "mName": "ns.primaryserver.com",
        "rName": "admin.example.com",
        "minTTL": 200
    },
    "gslbTtl": 5,
    "healthCheckIds": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ],
    "gslbRuleIds": [
        "0196e75c-4779-75c4-bedf-ff4d27f3bd99"
    ],
    "serviceIngress": {
        "unencryptedEnabled": true,
        "dohEnabled": true,
        "dohPath": "/dns-query",
        "dotEnabled": true,
        "certificateSecretId": "7b6f3752-a442-4e3e-ba0b-f4f9d41bdaec"
    }
}

Parameters

Name	Description	Type	Required
name	The name of the site. Maximum 128 characters; can't begin or end with a whitespace; can't contain " /" in the name. Note: If you are using the Cisco Umbrella integration, the site name must be a maximum of 45 characters.	String	Required
address	The site address. Used to look up latitude, longitude, and time zone, if these aren't provided.	String	Required
lat and lng	The latitude (must be a value between "90" and "-90") and longitude (must be a value between "-180" and "180") of the site. If omitted, BlueCat Edge will look this information up based the address.	String	Optional
timeZone	Time zone: A list of permitted time zones is available at this link. Time zone is optional. If you don't specify a time zone, BlueCat Edge will look it up based on the latitude and longitude. If you specify coordinates of a location over a body of water, the default time zone (UTC) is assigned.	String	Optional
id (under associatedNamespaces)	The ID of the user-defined, discovered, or recursive namespace associated with the site. If no namespace is specified, the default(s) will be applied. Note: You must configure a site with at least one namespace and the maximum number of namespaces is dependent on Edge licenses. You can override the default forwarder IP addresses by entering a different IP address. To ensure optimal latency in sites using more than three namespaces, BlueCat recommends using Domain Lists to configure appropriate routing criteria.	String	Optional
overridingForwarders	The IP address of a forwarder to override the default address(es) in the namespace.	String	Optional
version	The DNS resolver service version of the site. This value must be a supported DNS resolver service version. Attention: This parameter must not be included if automatic DNS resolver service updates is enabled.	String	Required (when automatic DNS resolver service updates are disabled)
streamDataToCI	Sends DNS queries from a service point to the BlueCat Edge Cloud console. The default value is `true`. Note: If you do not enable any query logging options, the DNS resolver service operates as a resolver and no DNS queries will be stored or visible.	Boolean	Optional
loggingEndpointId	The ID of local logging endpoint. If this parameter does not have a value, the service point will not send DNS queries to a local logging endpoint. Note: If you do not enable any query logging options, the DNS resolver service operates as a resolver and no DNS queries will be stored or visible.	String	Optional
identityServiceEnabled	Indicates whether DNS queries include a mapping of user IDs, in addition to client IP addresses. This information is retrieved by the identity service when Azure Event Hub is configured to use Microsoft Active Directory. This authorization allows requests to extract data from the event logs stored in Azure Event Hub. The default value is `false`.	Boolean	Optional
randomizeAddresses	Indicates whether DNS Resolver Service shuffles responses in the Answer section that match the QTYPE of the query. The shuffled responses are limited to A, AAAA, MX, NS, PTR, and SRV QTYPES.	Boolean	Optional
soaDefinition	Updates the SOA definition for DNS queries that are modified based on a BlueCat Edge policy, such as blocking a query or removing unhealthy answers. When enabled, enter the following information: authorityZone—the FQDN of the DNS zone for which the SOA record is authoritative. mName—the FQDN of the primary name server for the zone. rName—the email address of the domain administrator, represented as a domain name. For example, `admin.example.com` minTtl—(Optional) the minimum TTL value of the zone, in seconds. The value must be between 0 and 86400 seconds inclusively. If left blank, the default value is 300 seconds.	String	Optional
gslbTtl	The maximum TTL for DNS responses sent to clients for queries that match a GSLB rule, in seconds. The value must be between 0 and 604800 seconds inclusively. The default value is 5 seconds.	Integer	Optional
healthCheckIds	A list of health check configuration IDs that the site will use to verify the health of the endpoints.	String	Optional
gslbRuleIds	A list of GSLB rule IDs that will be used to evaluate incoming queries from the site.	String	Optional
serviceIngress	The services that determine how the DNS resolver services provides resolution to clients. The services are as follows: Note: By default, if you do not specify the serviceIngress, inbound DNS queries are unencrypted. unencryptedEnabled—when set to true, inbound DNS queries are unencrypted. dohEnabled—when set to true, inbound DNS queries are encrypted using DNS over HTTPS (DoH). If enabled, enter the following additional parameters: dohPath—the path for the DoH endpoint. The default path is /dns-query. Note: The dohPath must conform to RFC9110 and RFC3986. The dohPath must include a prefixing slash ( / ) character in the path. certificateSecretId—the ID of the certificate in the Edge secrets manager. dotEnabled—when set to true, inbound DNS queries are encrypted using DNS over TLS (DoT). If enabled, enter the following information: certificateSecretId—the ID of the certificate in the Edge secrets manager. Note: To enable DNS over TLS or DNS over HTTPS, you must first upload a certificate to the BlueCat Edge secrets manager. For more information, refer to Secrets manager. Note: The following formats are supported for the certificate input data: The certificate must be PEM-encoded DER format and contain a server certificate, optional intermediates, and private key The PEM data of the certificate must not contain more than 10 intermediate certificates The server and intermediate certificates must be X.509 format The private key must be PKCS#8 encoded, and may be unencrypted or password encrypted The following private key encryption algorithms are supported: AES128CBC, AES128GCM, AES192CBC, AES192GCM, AES256CBC, AES256GCM, and TripleDESCBC The following private key signature algorithms are supported: RSA, ECDSA, and ED25519	String	Optional

Notes:

You can specify up to three namespaces for a site.
You can set an explicit order for the namespaces assigned to a site.
Time zone: A list of permitted time zones is available at this link.
Time zone is optional. If you don't specify a time zone, BlueCat Edge will look it up based on the address.
If you specify an address or coordinates of a location that's a body of water, the default time zone (UTC) is assigned.
Latitude and longitude are optional, if omitted BlueCat Edge will look this information up based the address.
If the value of streamDataToCI is false, loggingEndpointId must have a value. You must choose at least one destination for the DNS queries. DNS queries can also be sent to both the BlueCat Edge Cloud console and the local logging endpoint.

Successful response

The site name and location returned will be the same as you specified in the request.

201 CREATED
Location → ......../sites/66c6d94e-e252-4076-993b-b86d599df9f5

Possible error codes

UNAUTHORIZED
BAD_REQUEST
ERROR_INVALID_ARGUMENT
ERROR_DUPLICATE_SITE
UNEXPECTED_ERROR

/v3/api/sites (POST) - User Guide - BlueCat Edge

BlueCat Edge User Guide