Domains

Site creation attempts to allocate a docsary.com address on either plan. Check the returned subdomain; allocation can fail. When one is allocated it serves as soon as you push a page — nothing to configure.

Use your own hostname, such as docs.acme.com, with Pro. Setup requires access to that domain’s DNS records.

The address you get automatically

When you create a site, the response tells you where it lives:

curl -s -X POST "$DOCSARY_API/v1/sites" \
  -H "authorization: Bearer $DOCSARY_KEY" \
  -H "content-type: application/json" \
  -d '{"slug":"acme","name":"Acme Docs"}'

{ "id": "site_...", "slug": "acme", "subdomain": "acme.docsary.com" }

Create a version and push pages to serve documentation at the returned HTTPS address.

The address normally uses your site slug. If that name is taken or reserved, Docsary tries <your-org>-<your-site>.docsary.com. Always read subdomain from the response.

In the rare case where both names are taken, the site is still created, subdomain comes back null, and a subdomain_note says why. Stop before uploading. If this newly created site is still empty, delete it using its returned id (DELETE /v1/sites/:site), then retry creation with a different slug. This works on Free and avoids consuming another site slot. For a populated site, contact support before deleting anything. On Pro you can also attach a hostname you own instead.

Your docsary.com address remains available after you add a custom domain. Both addresses are public; see primary and staging hosts.

Your own domain

Custom domains require Pro. Self-service checkout is not available; email hello@robota.us to arrange an upgrade. Your existing content and addresses remain in place.

A downgrade alone does not stop existing custom hostnames from serving. You cannot add another custom domain until your plan permits it.

Pro includes up to 25 custom hostnames per organization. Allocated docsary.com addresses do not count toward that limit. Contact us if you need more.

1. Attach

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."
  }
}

The response includes an ownership record (verification) and a traffic record (traffic). You can verify ownership before moving traffic from an existing site.

The hostname is lowercased and trimmed, and must be a normal dotted hostname. A bare hostname without a dot is rejected with 400. So is anything ending in docsary.com — those names are allocated, not attached.

2. Prove you own it

Publish the TXT record exactly as given — name _docsary.<your hostname>, value docsary-verify=<token> — then 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" }
}

If verification returns 409, check the DNS records shown in found:

{
  "hostname": "docs.acme.com",
  "verified": false,
  "expected": { "name": "_docsary.docs.acme.com", "value": "docsary-verify=8f1c..." },
  "found": []
}

Check the record name and docsary-verify= prefix. Some DNS providers append your domain automatically. Correct the record, allow time for DNS propagation, and retry.

Verification is permanent for that attachment. You may remove the TXT record afterwards, though leaving it costs nothing.

3. Point the traffic

Publish the CNAME from the traffic block:

docs.acme.com    CNAME    ssl.docsary.com

A certificate is requested after verification and issued once the CNAME is ready. Issuance and renewal are automatic. Confirm HTTPS works, then make the hostname primary when you are ready to use it for canonical links and search indexing.

For a root domain such as acme.com, use a DNS provider with ALIAS/ANAME flattening. Otherwise, use a subdomain such as docs.acme.com.

What the certificate block is telling you

Check certificate.status: created or exists means a certificate has been requested, not necessarily issued. For skipped or failed, retry verification; contact us with the reason if it persists. Ownership verification remains valid.

Primary and staging hosts

A site can have several hostnames. One is primary. That flag drives three behaviours:

Your allocated address starts as primary. The primary host supplies canonical URLs; other hosts request exclusion from search indexes. These directives do not prevent access or guarantee removal from an index.

Only one hostname can be primary.

Changing your mind later

To change the primary hostname without detaching it:

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

Use this after verifying the new hostname and checking that it serves your content. See Set the primary domain.

Do not detach and reattach to change the primary host. Detaching stops service on that hostname and releases its certificate.

An unverified custom domain cannot be promoted; the request returns 409. Verify it first.

Changing the primary host changes canonical links, the sitemap, and indexing directives. Search engines decide when to reflect those changes.

Listing

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": "..." }
    }
  ]
}

kind is saas for the address we allocated and custom for a hostname you own. A hostname still waiting on its challenge comes back "verified": false with its verification block, so this call is also how you recover the records to publish if you lost the attach response.

Detaching

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" } }

Detaching stops the hostname serving and releases its certificate. Your DNS records are yours and are not touched — remove them on your own schedule, since those names may be doing other work for you.

Deleting a site detaches everything it had, the docsary.com address included, and that name becomes available again.

A hostname that is not attached to any site is answered with a plain 404 reading docsary: no site bound to this host. So is one that is attached but not yet verified.

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.

See Publishing for cache behavior.