Connect

Connect a domain to a hosting or email provider

Connects a domain to a hosting or email provider by auto-detecting the provider from a target URL or accepting an explicit provider name.

For domains managed through the platform, DNS records are set automatically (status: dns_set). For imported domains (external registrar), returns the records as instructions to add manually at your registrar (status: manual_setup_required, records have status pending).

Supported hosting providers: vercel, netlify, cloudflare-pages, github-pages, railway, fly. Supported email providers: google-workspace, fastmail, proton.

Use GET /api/domains/{domain}/connect to list all available providers and methods.

Mail routing: a change to where the domain's mail is delivered (its MX or NS records, the address records an MX host inside the zone resolves through, or those of a host that receives Domani mail and publishes no MX) needs the email:auth_secrets scope, since whoever receives the mail receives its sign-in codes. Without it the request answers 403 INSUFFICIENT_SCOPE before anything changes, and a token confined to mailboxes answers 403 MAILBOX_CONFINED even with it. Other records need only domains:write. Every routing change is recorded in the audit log.

post/api/domains/{domain}/connect

Request

  • Base URL: https://domani.run
  • URL: https://domani.run/api/domains/{domain}/connect
  • Auth: HTTP bearer

Path parameters

domainstring required
Example:mysite.com

Domain name you own

Request body

targetstring

Target URL for auto-detection (e.g. my-app.vercel.app)

providerstring

Explicit provider name (e.g. vercel, google-workspace)

methodstring

Connection method if provider has multiple (e.g. cname-only)

dry_runboolean

Preview only: returns the diff (create/replace/already_set/keep) without writing anything.

confirm_replace_mxboolean

Required when the connect would replace existing MX records pointing at another provider (409 MX_REPLACEMENT_REQUIRES_CONFIRMATION otherwise) - it reroutes the domain's email.

Example request

{
  "target": "my-app.vercel.app",
  "provider": "vercel"
}

Response

Domain connected or DNS instructions returned

domainstring
providerstring
category'hosting' | 'email'
methodstring
docsstring uri
status'dns_set' | 'manual_setup_required' | 'dry_run'

dns_set = records written automatically. manual_setup_required = imported domain, add records at your registrar. dry_run = preview only, nothing written.

hintstring
next_stepsstring[]

Provider-specific actions to complete after DNS records are set

diffobject

Dry run only: what the write would do - create, replace (existing records that would be removed), already_set, keep (untouched rrsets).

Example response

{
  "records": [
    {
      "name": "@",
      "value": "76.76.21.21",
      "ttl": 3600
    }
  ]
}

Changes

No recorded changes to this operation across all 2 revisions of this API.