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

Domain routes: register, release, renew, search

The Domain Verbs register, release, renew, search as api.sb routes, with inputs, result, refusals and an example.

Reference for Domain, one group of Domain routes.

Domain.register

Register buys a hostname for a Startup and points it at the Startup’s address. Verb page.

Text
POST /{namespace}/domains/register

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

Inputs

InputTypeRequiredDescription
hostnamestringrequiredThe hostname to buy.
startupStartuprequiredThe Startup it serves.

Returns

OutputTypeRequiredDescription
domainDomainrequiredThe registered Domain.

Refuses when

CheckErrorFixThen call
The operation is part of an Offer the caller has not accepted or paid for.payment-requiredAccept the Offer named in the response, then retry the call.Offer.accept
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.

Example

Terminal
curl -X POST https://api.sb/kilnbakery.com/domains/register \
  -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.register",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/kilnbakery.com/actions/act_0y76a1jB6k"
  }
}

Domain.release

Release lets a Domain’s registration or claim end, keeping its record, history and aliases. Verb page.

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

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

Inputs

InputTypeRequiredDescription
domainDomainrequiredThe Domain to let go.
reasontextrequiredWhy it is released, recorded as a Decision.

Returns

OutputTypeRequiredDescription
domainDomainrequiredThe released 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 Domain whose carriedIdentity is true: it received mail, hosted a Mailbox or verified an outside accountrefusedClear what the check names, then call it again.None.
A canonical Domain while the Startup is LiverefusedClear what the check names, then call it again.None.

Example

Terminal
curl -X POST https://api.sb/kilnbakery.com/domains/domain_VbYut4CTsH/release \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Example reason"}'
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.release",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/kilnbakery.com/actions/act_0y76a1jB6k"
  }
}

Domain.renew

Renew extends a Domain’s registration by whole years at its renewal price, paid by its owner of record. Verb page.

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

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

Inputs

InputTypeRequiredDescription
domainDomainrequiredThe Domain to renew.
yearsintegerYears to add. Defaults to the Domain’s tier in the renewal Setting.

Returns

OutputTypeRequiredDescription
domainDomainrequiredThe Domain, with its new expiresAt.

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/renew \
  -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.renew",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/kilnbakery.com/actions/act_0y76a1jB6k"
  }
}

Domain.search

Search lists candidate names with availability, first-year price, renewal price and the rules of each extension. Verb page.

Text
POST /{namespace}/domains/search

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

Inputs

InputTypeRequiredDescription
querystringrequiredA name, or a word to build names from.
extensionsstring[]Extensions to check, such as com or ai.

Returns

OutputTypeRequiredDescription
candidateslist of DomainrequiredCandidate Domains, each with its prices, three-year cost and extension rules.

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/search \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"Example query"}'
JSON
{
  "api": "https://api.sb/kilnbakery.com",
  "candidates": [
    {
      "$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.search",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/kilnbakery.com/actions/act_0y76a1jB6k"
  }
}

authenticate, benchmark, claim, connect

Previous

transfer, verify

Next