Domains

List your site’s hostnames, attach a custom domain, and choose its primary address. Custom domains require Pro.

For DNS setup and address-allocation details, see Domains.

All endpoints require an organization API key. :site accepts a slug or an id.

Kinds of domain

List domains

GET /v1/sites/:site/domains

curl -s -H "authorization: Bearer $DOCSARY_KEY" \
  "$DOCSARY_API/v1/sites/acme/domains"

{
  "domains": [
    {
      "hostname": "acme.docsary.com",
      "is_primary": 0,
      "kind": "saas",
      "verified": true,
      "verified_at": 1756300000000
    },
    {
      "hostname": "docs.acme.com",
      "is_primary": 1,
      "kind": "custom",
      "verified": true,
      "verified_at": 1756300000000,
      "registered": true,
      "traffic": {
        "type": "CNAME",
        "name": "docs.acme.com",
        "value": "ssl.docsary.com",
        "how": "Point docs.acme.com at ssl.docsary.com with a CNAME once ownership is verified. The certificate is issued and renewed for you; there is nothing to install."
      }
    },
    {
      "hostname": "staging.acme.com",
      "is_primary": 0,
      "kind": "custom",
      "verified": false,
      "verified_at": null,
      "registered": false,
      "verification": {
        "type": "TXT",
        "name": "_docsary.staging.acme.com",
        "value": "docsary-verify=8f1c...",
        "how": "Publish this TXT record, then POST to /v1/sites/<site>/domains/staging.acme.com/verify. The hostname is not served until it verifies."
      },
      "traffic": {
        "type": "CNAME",
        "name": "staging.acme.com",
        "value": "ssl.docsary.com",
        "how": "..."
      }
    }
  ]
}

This call is how you recover both records if you lost the attach response.

Attach a domain

POST /v1/sites/:site/domains

curl -s -X POST "$DOCSARY_API/v1/sites/acme/domains" \
  -H "authorization: Bearer $DOCSARY_KEY" \
  -H "content-type: application/json" \
  -d '{"hostname":"docs.acme.com"}'

{
  "hostname": "docs.acme.com",
  "kind": "custom",
  "verified": false,
  "verification": {
    "type": "TXT",
    "name": "_docsary.docs.acme.com",
    "value": "docsary-verify=8f1c2d0a4b6e8f1c2d0a4b6e8f1c2d0a",
    "how": "Publish this TXT record, then POST to /v1/sites/<site>/domains/docs.acme.com/verify. The hostname is not served until it verifies."
  },
  "traffic": {
    "type": "CNAME",
    "name": "docs.acme.com",
    "value": "ssl.docsary.com",
    "how": "Point docs.acme.com at ssl.docsary.com with a CNAME once ownership is verified. The certificate is issued and renewed for you; there is nothing to install."
  }
}

201 on success. The attachment exists and is unverified; nothing is served on it, and no certificate is requested, until it verifies.

Reattaching a hostname creates a new verification token. Use the TXT record from the latest response.

Errors

A plan without custom domains returns limit: 0 and required_plan: "pro":

{
  "error": "Custom domains are part of Docsary Pro; the 'free' plan does not include them. Your site keeps serving on its docsary.com address. To put it on a hostname you own, upgrade to Pro — email hello@robota.us.",
  "quota": "custom_domains",
  "limit": 0,
  "plan": "free",
  "required_plan": "pro"
}

Pro quota responses identify the allowed count:

{
  "error": "quota exceeded: custom_domains limit is 25 on plan 'pro'",
  "quota": "custom_domains",
  "limit": 25,
  "plan": "pro"
}

The limit applies across your organization. Allocated docsary.com addresses do not count. Contact us for a higher allowance.

Hostnames are unique across every site. to_this_site distinguishes a re-run from a genuine conflict.

A hostname provisioned on your behalf may return kind: "route" and verified: true. Contact support if its setup report includes a failed step.

Verify a domain

POST /v1/sites/:site/domains/:hostname/verify

Publish the TXT record from the attach response, then call this. It resolves the record live on every call.

curl -s -X POST "$DOCSARY_API/v1/sites/acme/domains/docs.acme.com/verify" \
  -H "authorization: Bearer $DOCSARY_KEY"

{
  "hostname": "docs.acme.com",
  "verified": true,
  "traffic": {
    "type": "CNAME",
    "name": "docs.acme.com",
    "value": "ssl.docsary.com",
    "how": "..."
  },
  "certificate": { "status": "created" }
}

After ownership verification, publish the traffic record and wait for certificate issuance before checking the hostname over HTTPS.

For 409, compare expected with found, correct the TXT record if needed, allow time for DNS propagation, and retry.

The certificate block

A skipped or failed certificate request leaves ownership verified. Retry verification to request the certificate again; contact support if it continues to fail.

Set the primary domain

POST /v1/sites/:site/domains/:hostname/primary

Makes an already-attached hostname the site's canonical host and clears the flag from every other domain on the site, in one call.

curl -s -X POST "$DOCSARY_API/v1/sites/acme/domains/docs.acme.com/primary" \
  -H "authorization: Bearer $DOCSARY_KEY"

{
  "hostname": "docs.acme.com",
  "is_primary": true,
  "previous_primary": "acme.docsary.com",
  "already_primary": false,
  "note": "Canonical URLs, indexing, and the sitemap follow the primary host. ..."
}

Use this endpoint to change the primary host without detaching it or restarting certificate setup.

The primary flag moves in one operation. A refused request leaves the current primary unchanged.

Repeated calls are safe; an unchanged primary returns previous_primary: null.

What changes when the primary moves

Verify the new domain and confirm that it serves your content before making it primary. The change affects search indexing signals; search engines decide when to update their results.

Other hostnames remain public. Their noindex and crawler directives request exclusion from cooperating search engines, without guaranteeing it.

Errors

Verify an unverified custom hostname before promoting it. Otherwise the call returns 409.

Detach a domain

DELETE /v1/sites/:site/domains/:hostname

curl -s -X DELETE "$DOCSARY_API/v1/sites/acme/domains/docs.acme.com" \
  -H "authorization: Bearer $DOCSARY_KEY"

{ "deleted": "docs.acme.com", "certificate": { "status": "deleted" } }

The hostname stops serving and its certificate is released. certificate reads deleted, absent (there was none to release), skipped, or failed with a reason.

Your DNS records are never touched — they are yours, and removing them is your call.

404 {"error":"domain not found"} if the hostname is not attached to this site.

Detaching your docsary.com address works the same way and frees that name for somebody else, so do it deliberately. Deleting the site detaches everything it had.

When changes take effect

No deployment or separate publish call is required. Allow for DNS propagation, certificate issuance, and cached responses, then check the hostname over HTTPS.

Unattached or unverified hostnames return 404: docsary: no site bound to this host.