Skip to content
Blotout Docs

Create a site

POST
/teams/{teamId}/domains
curl --request POST \
  --url https://qinto-api.blotout.io/teams/7b8d1a52-6c1e-4b6f-9a30-2f8a54d1c3e9/domains \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "rootDomain": "example.com", "mode": "managed", "hostId": "9b1c7f30-2d85-4e77-a6c1-0f3d8e6b5a24", "name": "Storefront", "subdomain": "shop", "jurisdiction": "eu", "locationHint": "wnam" }'

Registers a customer domain as a site and provisions the hostname Qinto will serve it on. This is the first step of onboarding; the returned domainId is what every other site operation references.

How it works

The site is created pending and serves nothing until it is deployed. Its hostname is <subdomain>.<rootDomain>, with a random subdomain when none is given. jurisdiction, locationHint, subdomain and the host are fixed at creation and cannot be changed afterwards — create a new site to change them. Hostnames stay reserved after a site is deleted, so already_exists can name a site you can no longer see. Managed hosting needs no hostId; self-hosting requires one whose zone is already chosen.

Required permissions

  • domain:write on all domains, or on the addressed domain when its id is in the route

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
teamId
required

Unique id (UUID) of the team that owns the addressed resources, as shown in the team settings on the Blotout platform.

string format: uuid

Example 

7b8d1a52-6c1e-4b6f-9a30-2f8a54d1c3e9

Unique id (UUID) of the team that owns the addressed resources, as shown in the team settings on the Blotout platform.

Request Bodyrequired

Section titled “Request Bodyrequired”

The customer domain to serve, and where to host it.

Media typeapplication/json

The site to create, and where to host it.

object
rootDomain
required

Customer domain to serve the site under, with or without www..

string
>= 1 characters

Example 

example.com
mode

Who hosts the site: managed on Qinto’s own Cloudflare account, or self on one of the team’s hosts. Defaults to managed.

string
Allowed values: managed self

Example 

managed
hostId

Host to provision under. Required when mode is self, ignored otherwise.

string format: uuid

Example 

9b1c7f30-2d85-4e77-a6c1-0f3d8e6b5a24
name

Display name for the site. Defaults to the root domain. At most 80 characters.

string
<= 80 characters

Example 

Storefront
subdomain

Label to serve the site from. Lowercase letters, digits and hyphens, at most 15 characters, and not a reserved word. A random label is chosen when omitted.

string
<= 15 characters

Example 

shop
jurisdiction

Hold the site’s data in a jurisdiction. Guaranteed for Durable Objects and object storage; other storage follows locationHint where it is supported, and is otherwise placed automatically. Cannot be changed later.

string
Allowed values: eu us

Example 

eu
locationHint

Place the site’s state near a region. Cannot be changed later.

string
Allowed values: wnam enam weur eeur apac oc

Example 

weur

Responses

Section titled “Responses”

201

Section titled “201”

The site was created and its hostname provisioned.

Media typeapplication/json
object
site
required

A site a team serves through Qinto.

object
domainId
required

Server-assigned unique id of the site. Address the site with it in every other operation.

string
name
required

Display name of the site, as shown on the Blotout platform.

string | null
domain
required

Hostname Qinto serves this site on, built from its subdomain and root domain. It is fixed at creation.

string
rootDomain
required

Customer domain the site belongs to.

string
subdomain
required

Label Qinto serves the site from, under the root domain.

string
status
required

pending until the site is first deployed, then active. Deleted sites are not returned at all.

string
Allowed values: pending active
jurisdiction
required

Jurisdiction the site’s data is held in, or null when unrestricted. Guaranteed for Durable Objects and object storage; other storage follows locationHint where it is supported, and is otherwise placed automatically. Fixed at creation.

string | null
Allowed values: eu us
locationHint
required

Region the site’s state is placed near, or null to let Cloudflare choose. Fixed at creation.

string | null
Allowed values: wnam enam weur eeur apac oc
developmentUrl
required

Qinto URL the site can be served from while its own DNS is not set up, or null when it has none.

string | null
deliveryMode
required

Where the site is asked to be served from: its own domain, or its Qinto development_url.

string
Allowed values: domain development_url
deliveryLive
required

Whether the deployed worker already serves the requested deliveryMode. False on a site that has never deployed — call deploy — and false while a change to a deployed site has not reached the edge, which retries on its own.

boolean
hostId
required

Host the site is provisioned under. It is fixed at creation.

string

Example 

{
  "site": {
    "domainId": "3f2a9c81-5d47-4e0b-8c66-91b2a7f04d15",
    "name": "Storefront",
    "domain": "shop.example.com",
    "rootDomain": "example.com",
    "subdomain": "shop",
    "status": "pending",
    "jurisdiction": "eu",
    "locationHint": "wnam",
    "developmentUrl": "shopexamplecom.acme.workers.dev",
    "deliveryMode": "domain",
    "deliveryLive": true,
    "hostId": "9b1c7f30-2d85-4e77-a6c1-0f3d8e6b5a24"
  }
}

400

Section titled “400”

invalid_params — A path parameter failed validation (for example a malformed UUID); details pinpoints the offending parameter. invalid_body — The JSON body is unparseable or failed schema validation; details pinpoints the offending fields when the body could be parsed. invalid_site — The site details were rejected before anything was created — a malformed root domain, a reserved or malformed subdomain, an unknown jurisdiction or location, or a name that is too long. message states which.

Media typeapplication/json
object
error
required

Machine-readable error slug; switch on this value rather than on the HTTP status alone.

string
Allowed values: invalid_params invalid_body invalid_site
message

Human-readable reason for this specific failure, intended for display — do not parse it programmatically.

string
details

Field-level validation errors: a tree keyed by input property, each node carrying an errors array of human-readable messages. Render it to help the caller correct the request.

object
key
additional properties

Example 

{
  "error": "invalid_params",
  "message": "The Cloudflare API token is invalid or expired.",
  "details": {
    "errors": [],
    "properties": {
      "teamId": {
        "errors": [
          "Invalid UUID"
        ]
      }
    }
  }
}

401

Section titled “401”

unauthenticated — The Authorization: Bearer token is missing, malformed, or no longer valid. Generate a team API token or obtain a new OAuth access token.

Media typeapplication/json
object
error
required

Machine-readable error slug; switch on this value rather than on the HTTP status alone.

string
Allowed values: unauthenticated

Example 

{
  "error": "unauthenticated"
}

403

Section titled “403”

forbidden — The bearer credential lacks the required permission or belongs to another team, or its user lacks the organization role a developer operation needs. Update its policies, use a credential bound to the addressed team, or ask an organization owner for the role; message states the reason when one is known.

Media typeapplication/json
object
error
required

Machine-readable error slug; switch on this value rather than on the HTTP status alone.

string
Allowed values: forbidden
message

Human-readable reason for this specific failure, intended for display — do not parse it programmatically.

string

Example 

{
  "error": "forbidden",
  "message": "The Cloudflare API token is invalid or expired."
}

404

Section titled “404”

not_found — The addressed resource does not exist within this team; check the id and retry.

Media typeapplication/json
object
error
required

Machine-readable error slug; switch on this value rather than on the HTTP status alone.

string
Allowed values: not_found

Example 

{
  "error": "not_found"
}

409

Section titled “409”

already_exists — A site already occupies this hostname. Deleted sites keep their hostname reserved, so this can name a site that is no longer visible. message says whether it is one of yours.

Media typeapplication/json
object
error
required

Machine-readable error slug; switch on this value rather than on the HTTP status alone.

string
Allowed values: already_exists
message

Human-readable reason for this specific failure, intended for display — do not parse it programmatically.

string

Example 

{
  "error": "already_exists",
  "message": "The Cloudflare API token is invalid or expired."
}

422

Section titled “422”

host_not_ready — The site’s host is not ready to serve it — no Cloudflare zone chosen, no stored API token, a token scoped to the wrong zone, a conflicting DNS record, or a dispatcher that refused the request. message names the fix.

Media typeapplication/json
object
error
required

Machine-readable error slug; switch on this value rather than on the HTTP status alone.

string
Allowed values: host_not_ready
message

Human-readable reason for this specific failure, intended for display — do not parse it programmatically.

string

Example 

{
  "error": "host_not_ready",
  "message": "The Cloudflare API token is invalid or expired."
}

429

Section titled “429”

rate_limited — Too many requests for this API token or site in a short window; wait a minute and retry.

Media typeapplication/json
object
error
required

Machine-readable error slug; switch on this value rather than on the HTTP status alone.

string
Allowed values: rate_limited

Example 

{
  "error": "rate_limited"
}

500

Section titled “500”

internal — Unexpected server error. Nothing is guaranteed to have been persisted; idempotent operations are safe to retry.

Media typeapplication/json
object
error
required

Machine-readable error slug; switch on this value rather than on the HTTP status alone.

string
Allowed values: internal

Example 

{
  "error": "internal"
}

502

Section titled “502”

upstream_unavailable — A provider Qinto depends on (Cloudflare for the DNS records, or the email service) could not be reached or refused the request. Delivery is unconfirmed rather than ruled out — a lost response can follow an accepted send — so retry with the same submissionId, which de-duplicates an identical retry at the provider.

Media typeapplication/json
object
error
required

Machine-readable error slug; switch on this value rather than on the HTTP status alone.

string
Allowed values: upstream_unavailable

Example 

{
  "error": "upstream_unavailable"
}