Domains, DNS & TLS

Preview Three related resources put a custom hostname in front of an environment. Domains attach a hostname to an environment. DNS records are managed at the site level, where managed.dev runs your zone. TLS is issued and renewed automatically, with read and force-renew endpoints when you need them.

Developer preview

The managed.dev public API is in active development. Endpoints, scopes, and payloads described here reflect the current design and may change before general availability.

Domains

A domain points a hostname at one environment. Production gets your apex and www; preview and staging environments get their own hostnames. See custom domains for the conceptual walkthrough.

GET · POST · DELETE /v1/sites/{id}/environments/{envID}/domains[/{domainID}]

• List (domains:read) the domains on an environment.
• Add (domains:write) a domain — returns a 202 job while verification and certificate issuance run.
• Remove (domains:write) a domain.

Parameter	Type	Required	Description
hostname	string	yes	The custom hostname, e.g. shop.example.com.
redirect_to_primary	boolean	no	If true, redirect this hostname to the primary domain.

cURL

Attach a custom domain to production

curl -X POST https://api.managed.dev/v1/sites/site_01J7.../environments/env_01J8.../domains \
  -H "Authorization: Bearer mfk_live_..." \
  -H "Idempotency-Key: 6c1a...d8" \
  -H "Content-Type: application/json" \
  -d '{ "hostname": "shop.example.com" }'

Go

Attach a custom domain to production

job, err := client.Domains.Create(ctx, "site_01J7...", "env_01J8...",
    &forge.DomainCreateParams{Hostname: forge.String("shop.example.com")},
    forge.WithIdempotencyKey("6c1a...d8"))

TypeScript

Attach a custom domain to production

const job = await client.domains.create(
  "site_01J7...",
  "env_01J8...",
  { hostname: "shop.example.com" },
  { idempotencyKey: "6c1a...d8" },
);

Response (202 Accepted)

{
  "data": {
    "id": "job_01J9...",
    "type": "domain.attach",
    "status": "queued",
    "created_at": "2026-06-24T14:41:09Z",
    "resource": { "type": "domain", "id": "dom_01J8...", "hostname": "shop.example.com" },
    "links": { "self": "/v1/jobs/job_01J9...", "stream": "/v1/jobs/job_01J9.../stream" }
  },
  "request_id": "req_01J9..."
}

Note

Until DNS resolves to managed.dev and TLS issues, the domain reports a pending status. Poll the job or re-GET the domain to watch it go active.

DNS records

When managed.dev runs your zone, DNS records are a site-level resource. See DNS.

GET · POST · PATCH · DELETE /v1/sites/{id}/dns/records[/{recordID}]

• List (domains:read) records, cursor-paginated.
• Create, update, or delete (domains:write) a record.

Parameter	Type	Required	Description
type	string	yes	A, AAAA, CNAME, MX, TXT, …
name	string	yes	Record name, e.g. @, www, mail.
value	string	yes	Record value, e.g. an IP or target hostname.
ttl	integer	no	Time-to-live in seconds; a sensible default applies.
priority	integer	no	Priority for MX and SRV records.

Add a TXT record for domain verification

curl -X POST https://api.managed.dev/v1/sites/site_01J7.../dns/records \
  -H "Authorization: Bearer mfk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "type": "TXT", "name": "@", "value": "v=spf1 include:managed.dev ~all", "ttl": 3600 }'

Response

{
  "data": {
    "id": "rec_01J8...",
    "type": "TXT",
    "name": "@",
    "value": "v=spf1 include:managed.dev ~all",
    "ttl": 3600,
    "created_at": "2026-06-24T14:43:50Z"
  },
  "request_id": "req_01J9..."
}

TLS

Certificates are issued and renewed automatically — per-node wildcard certs via DNS-01. These endpoints let you read status and force a renewal. See TLS.

GET /v1/sites/{id}/environments/{envID}/tls

tls:read Read certificate status for an environment — issuer, covered hostnames, and expiry.

Read TLS status

curl https://api.managed.dev/v1/sites/site_01J7.../environments/env_01J8.../tls \
  -H "Authorization: Bearer mfk_live_..."

Response

{
  "data": {
    "status": "active",
    "issuer": "managed.dev",
    "hostnames": ["shop.example.com", "www.shop.example.com"],
    "expires_at": "2026-09-22T00:00:00Z",
    "auto_renew": true
  },
  "request_id": "req_01J9..."
}

POST /v1/sites/{id}/environments/{envID}/tls/renew

tls:write Force an early renewal. Returns a 202 job. You rarely need this — renewal is automatic — but it’s here for the case where you’ve just changed DNS and want a fresh cert immediately.

Force a TLS renewal

curl -X POST https://api.managed.dev/v1/sites/site_01J7.../environments/env_01J8.../tls/renew \
  -H "Authorization: Bearer mfk_live_..." \
  -H "Idempotency-Key: 0a7e...f3"

Next steps

Custom domainsThe conceptual walkthrough of attaching a hostname and cutting over DNS.

Async jobsTrack the 202 jobs that domain attach and TLS renew return.

EnvironmentsDomains attach to an environment — the resource they live under.