REST API: domains

AgentStack keeps domains in two places. An email domain is registered for the whole organization and handles sending, and optionally receiving. A web custom domain belongs to one agent and serves that agent's widget, Help Page, or Help Center. AgentStack also issues two hostnames of its own: the shared mail host that auto-generated agent addresses sit on, and the free <slug>.help.agentstack.build subdomain that every Help Center site gets. GET /domains answers all four in one call.

The response is a list of groups. Each group is one hostname, and each group's uses array holds one entry for each thing that hostname does. A use carries its kind (email_send, email_receive, widget, help_page, help_center, platform_email, or platform_help_center), the status from the record that owns it, the agent it belongs to when it belongs to one, and the DNS records that use needs. A web use lists both records it needs: the CNAME at the hostname, and the _agentstack ownership TXT record that AgentStack checks before it verifies anything with the platform. Every DNS record name is a fully qualified name, so you can copy it straight into a DNS provider without working out whether the provider wants a label or a full host.

A web use carries two more fields. statusDetail holds the reason the record itself gives for its status, such as a missing ownership TXT record or an expired verification window, and is null when the record gives none. helpPageEnabled reports whether the owning agent has the Help Page turned on, because a domain routed to help_page serves the widget while that setting is off. Both fields are null on an email use and on a platform use.

The status of a use is the vocabulary of the record behind it, not a shared vocabulary. A web use uses the custom-domain lifecycle (pending_dns, verifying_dns, pending_ssl, active, failed_dns, failed_ssl, removing, suspended). A receiving use uses pending_mx or active. A sending use is pending, verified, or failed. Do not compare a status across two different kinds.

Read owned to tell your own hostnames from the ones AgentStack issued. A group with owned: false holds only platform-issued uses. You cannot add DNS records for it, change it, or remove it, and it does not count against either domain limit.

Conflicts

A group carries a conflict when the same hostname both receives email and serves a web surface. Receiving publishes an MX record at the hostname itself, and a web domain needs a CNAME at that same name. DNS does not permit a CNAME to coexist with any other record, so one of the two cannot work. AgentStack now refuses to create this pair: POST /agents/{id}/custom-domains answers 409 EMAIL_RECEIVING_CONFLICT, and POST /channels/email/domains/{domainId}/receiving/request answers 409 WEB_DOMAIN_CONFLICT. A conflict in this response is therefore a pair that already existed. Resolve it by removing the web domain, or by disabling receiving on that hostname.

Sending alone does not clash with a web domain. AgentStack's sending records sit at child names such as s1._domainkey.support.example.com, which leaves the hostname itself free, so a send-only email domain and a web domain can share one hostname and are not reported as a conflict.

Access

This endpoint is a read. Use an API key with the read scope. The key's role must hold the channels:view permission, which is the same permission that gates the two per-kind domain lists and the Domains page in the dashboard. The call is scoped to the organization the key belongs to, and it never reports a hostname held by another organization.

The response is derived for each request and is not cached. It makes no external call, so it does not consult SendGrid, Vercel, or public DNS, and it never changes any record. Poll it as often as your rate limit permits.