Skip to content
StartupBuilder
by startups.studio
by Startups.Studio
Code
Changelog
APIProductDomains and accessDomain

Domain routes: authenticate, benchmark, claim, connect

The Domain Verbs authenticate, benchmark, claim, connect as api.sb routes, with inputs, result, refusals and an example.

Reference for Domain, one group of Domain routes.

Domain.authenticate

Authenticate writes a Domain’s SPF, DKIM and DMARC records and verifies them before its first send. Verb page.

Text
POST /{namespace}/domains/{domain}/authenticate

Path: domain. Body, as JSON: the other inputs. Emits Domain.authenticated.

Inputs

InputTypeRequiredDescription
domainDomainrequiredThe sending Domain.
dmarcstringThe DMARC policy; it starts at none with reports and tightens to quarantine.

Returns

OutputTypeRequiredDescription
domainDomainrequiredThe Domain, authenticated.

Refuses when

CheckErrorFixThen call
The key is valid, but its scopes do not allow this operation.forbiddenUse a key whose scopes cover the operation, or ask an owner of the namespace to grant them.None.

Example

Terminal
curl -X POST https://api.sb/kilnbakery.com/domains/domain_VbYut4CTsH/authenticate \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY"
JSON
{
  "api": "https://api.sb/kilnbakery.com",
  "domain": {
    "$id": "https://api.sb/kilnbakery.com/domains/domain_VbYut4CTsH",
    "$type": "Domain",
    "hostname": "kilnbakery.com",
    "role": "canonical",
    "state": "verifying"
  },
  "action": {
    "$id": "https://api.sb/kilnbakery.com/actions/act_0y76a1jB6k",
    "operation": "Domain.authenticate",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/kilnbakery.com/actions/act_0y76a1jB6k"
  }
}

Domain.benchmark

Benchmark measures a Domain’s estimated traffic, ranking Keywords, authority and referring domains beside the competitors named. Verb page.

Text
POST /{namespace}/domains/benchmark

Body, as JSON: the inputs. Emits Domain.benchmarked.

Inputs

InputTypeRequiredDescription
hostnamestringrequiredThe name to measure: the Startup’s own or a competitor’s.
competitorsstring[]Names to measure beside it.

Returns

OutputTypeRequiredDescription
readingsjsonrequiredOne measure per name, each with its method and observation time.
domainDomainrequiredThe Domain measured.

Refuses when

CheckErrorFixThen call
The key is valid, but its scopes do not allow this operation.forbiddenUse a key whose scopes cover the operation, or ask an owner of the namespace to grant them.None.

Example

Terminal
curl -X POST https://api.sb/kilnbakery.com/domains/benchmark \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"taxcalc.tools"}'
JSON
{
  "api": "https://api.sb/kilnbakery.com",
  "readings": {},
  "domain": {
    "$id": "https://api.sb/kilnbakery.com/domains/domain_VbYut4CTsH",
    "$type": "Domain",
    "hostname": "kilnbakery.com",
    "role": "canonical",
    "state": "verifying"
  },
  "action": {
    "$id": "https://api.sb/kilnbakery.com/actions/act_0y76a1jB6k",
    "operation": "Domain.benchmark",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/kilnbakery.com/actions/act_0y76a1jB6k"
  }
}

Domain.claim

Claim gives a Startup a one-label name under an issuing Domain, or assigns it a held Domain through an approved Change. Verb page.

Text
POST /{namespace}/domains/claim

Body, as JSON: the inputs. Emits Domain.claimed.

Inputs

InputTypeRequiredDescription
hostnamestringrequiredThe name to claim.
startupStartuprequiredThe Startup it serves.

Returns

OutputTypeRequiredDescription
domainDomainrequiredThe claimed Domain.

Refuses when

CheckErrorFixThen call
The key is valid, but its scopes do not allow this operation.forbiddenUse a key whose scopes cover the operation, or ask an owner of the namespace to grant them.None.
A label under an issuing Domain whose publicSuffix is falserefusedClear what the check names, then call it again.None.
Reserved labels such as www, api, admin, mail, mcp, docs and sibling BrandsrefusedClear what the check names, then call it again.None.

Example

Terminal
curl -X POST https://api.sb/kilnbakery.com/domains/claim \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"kilnbakery.headless.ly","startup":"startup_ROlZw7tNIz"}'
JSON
{
  "api": "https://api.sb/kilnbakery.com",
  "domain": {
    "$id": "https://api.sb/kilnbakery.com/domains/domain_VbYut4CTsH",
    "$type": "Domain",
    "hostname": "kilnbakery.com",
    "role": "canonical",
    "state": "verifying"
  },
  "action": {
    "$id": "https://api.sb/kilnbakery.com/actions/act_0y76a1jB6k",
    "operation": "Domain.claim",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/kilnbakery.com/actions/act_0y76a1jB6k"
  }
}

Domain.connect

Connect attaches a hostname a Startup already holds and verifies ownership through DNS. Verb page.

Text
POST /{namespace}/domains/connect

Body, as JSON: the inputs. Emits Domain.connected.

Inputs

InputTypeRequiredDescription
hostnamestringrequiredThe hostname to attach.
startupStartuprequiredThe Startup it serves.
tenantTenantThe Tenant it serves, when a Customer connects its own name.

Returns

OutputTypeRequiredDescription
domainDomainrequiredThe connected Domain.

Refuses when

CheckErrorFixThen call
The input does not match the schema of the operation.invalid-inputRead the schema of the operation, then send every required field with the right type.None.
The key is valid, but its scopes do not allow this operation.forbiddenUse a key whose scopes cover the operation, or ask an owner of the namespace to grant them.None.
The record changed since it was read, so the write would overwrite a newer version.conflictRead the record again, then retry the write against its current state.None.
A wildcard name for a Tenant, and past the Tenant’s name count follows its Entitlement’s atBoundrefusedClear what the check names, then call it again.None.

Example

Terminal
curl -X POST https://api.sb/kilnbakery.com/domains/connect \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"kilnbakery.com","startup":"startup_ROlZw7tNIz"}'
JSON
{
  "api": "https://api.sb/kilnbakery.com",
  "domain": {
    "$id": "https://api.sb/kilnbakery.com/domains/domain_VbYut4CTsH",
    "$type": "Domain",
    "hostname": "kilnbakery.com",
    "role": "canonical",
    "state": "verifying"
  },
  "action": {
    "$id": "https://api.sb/kilnbakery.com/actions/act_0y76a1jB6k",
    "operation": "Domain.connect",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/kilnbakery.com/actions/act_0y76a1jB6k"
  }
}

list, update, delete

Previous

register, release, renew, search

Next