Domains

Base URL https://api.apexly.dev. Send your key as Authorization: Bearer sk_live_… or sk_test_…; the examples read it from APEXLY_API_KEY.

Add a domain

POST/v1/domains

201 with the new domain in pending_dns, or 200 with the existing one when the app already has this hostname (idempotent on app + hostname; an expired one is re-added: back to pending_dns with the same connect link and a fresh 72 h window). The mode comes from the key: test keys create test domains, which never contact a CA. 422 invalid_hostname, hostname_is_apexly, hostname_is_public_suffix, hostname_held, domain_limit_reached (live domains at the plan hard cap: 2× included, 3 on Free, Growth during the 14-day trial; error.status_detail lists { plan, trial, used, limit, hostname, plans[] } that fit one more. New accounts: 10 in the first 24 hours), origin_not_allowed, validation_failed (metadata over 4 KB, apex_redirect on a subdomain, hostname already in the app in the other mode). origin needs the Scale plan; other plans ignore it and the response carries warnings.

Body

Response

200 OK: the hostname already exists in this app · 201 Created. Errors use the error envelope.

Example

curl -X POST https://api.apexly.dev/v1/domains \
  -H "Authorization: Bearer $APEXLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"careers.acme.com"}'

List domains

GET/v1/domains

Newest first (created_at desc), cursor-paginated: pass next_cursor as cursor. Filters: status, hostname (prefix), metadata.<key>=<value> (string equality on a top-level key, up to 5).

Query parameters

Response

200 OK. Errors use the error envelope.

Example

curl https://api.apexly.dev/v1/domains \
  -H "Authorization: Bearer $APEXLY_API_KEY"

Get a domain

GET/v1/domains/{id}

Another app’s domain, or a deleted one, is 404.

Path parameters

Response

200 OK. Errors use the error envelope.

Example

curl https://api.apexly.dev/v1/domains/dom_01J9X8T4Q5M6N7P8R9S0V1W2X3 \
  -H "Authorization: Bearer $APEXLY_API_KEY"

Update a domain

PATCH/v1/domains/{id}

origin (Scale plan; null removes the override; other plans ignore it with warnings), metadata (replaces the object; null removes it), apex_redirect (apex domains only).

Path parameters

Body

Response

200 OK. Errors use the error envelope.

Example

curl -X PATCH https://api.apexly.dev/v1/domains/dom_01J9X8T4Q5M6N7P8R9S0V1W2X3 \
  -H "Authorization: Bearer $APEXLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata":{"customer":"acme"}}'

Delete a domain

DELETE/v1/domains/{id}

Emits domain.deleted; routing is dropped within 5 seconds; the hostname can be added again at once.

Path parameters

Response

204 No Content. Errors use the error envelope.

Example

curl -X DELETE https://api.apexly.dev/v1/domains/dom_01J9X8T4Q5M6N7P8R9S0V1W2X3 \
  -H "Authorization: Bearer $APEXLY_API_KEY"

Check a domain now

POST/v1/domains/{id}/verify

Queues a DNS check right away instead of waiting for the next scheduled one; on a cert_failed domain it retries issuance (after re-checking CAA when that was the reason). One per 15 seconds per domain (429 rate_limited with Retry-After). 422 validation_failed when there is nothing to check (issuing, held, expired, or a test domain).

Path parameters

Response

202 Accepted. Errors use the error envelope.

Example

curl -X POST https://api.apexly.dev/v1/domains/dom_01J9X8T4Q5M6N7P8R9S0V1W2X3/verify \
  -H "Authorization: Bearer $APEXLY_API_KEY"