Skip to main content

Documentation Index

Fetch the complete documentation index at: https://usenaive.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

curl https://api.usenaive.ai/v1/domains \
  -H "Authorization: Bearer nv_sk_live_..."

{
  "domains": [
    {
      "id": "domain-uuid-1",
      "domain": "acme-corp.usenaive.ai",
      "status": "active",
      "dns_status": "provisioned",
      "byod": false,
      "app_connect_status": null,
      "connected_app_id": null,
      "created_at": "2026-01-15T10:00:00Z"
    },
    {
      "id": "domain-uuid-2",
      "domain": "acme.com",
      "status": "pending_dns",
      "dns_status": "pending_verification",
      "byod": true,
      "app_connect_status": "agent_managed",
      "connected_app_id": null,
      "created_at": "2026-01-16T14:00:00Z"
    }
  ]
}

​
Domain Types

TypebyodDescription
SystemfalseAuto-provisioned on registration ({slug}.usenaive.ai). May start as pending_dns until the email provider verifies DNS.
Custom (BYOD)trueYour own domain, connected via POST /v1/domains/connect. Requires DNS setup.

​
Domain Statuses

statusdns_statusMeaning
activeprovisionedDomain is verified and ready for email
pending_dnspending_verificationWaiting for DNS records to be verified
pending_dnsprovisioningDomain registered with provider, records being generated

​
App-connection lifecycle

app_connect_statusMeaning
null / disconnectedDomain is not associated with a Naive app’s apex DNS
connectedApex DNS points at a Naive app and is reconciled by the platform
agent_managed_pendingAn agent is currently writing apex A/AAAA — transitional state
agent_managedAn agent has taken over apex DNS. Reapers and connect sweeps in either Naive product (SDK or paperclip) skip this domain
connected_app_id is the UUID of the Naive app the apex points at, when applicable.

​
Notes

  • System domains are auto-provisioned when you register but may not be immediately active
  • Use POST /v1/domains/:id/verify to trigger re-verification
  • Only active domains can be used to create email inboxes
  • app_connect_status flips to agent_managed automatically when an agent edits apex A/AAAA via POST /v1/domains/:id/zone-records — see Set Zone Record