Custom Domains
This guide applies to yLnk domains. yShop is a separate application and its domain APIs are not interchangeable.
Authentication and ownership
Domain management requires the authenticated dashboard user/Bearer token and the correct active workspace. X-API-Key only authenticates /v2/external/client/**; it does not authenticate /v2/domains, LinkFolio, forms, blog or campaign management. Keep domain IDs and feature IDs distinct.
Registration to activation
POST /v2/domainswith{"domain":"links.example.com","purpose":"SHORT_LINK"}.- Save the returned
id; callPOST /v2/domains/{id}/instructions. - Apply the exact returned DNS records. Use the returned ownership TXT record/token and CNAME target; do not hardcode a VPS IP, verification token or shared target from another environment.
- Call
POST /v2/domains/{id}/verifyafter DNS propagation. This performs verification/provisioning checks; do not run an unbounded verification loop. - Read
GET /v2/domains/{id}orGET /v2/domainsfor status/message.ACTIVEis the serving state.VERIFIEDonly confirms an intermediate state;SSL_PENDINGstill needs certificate provisioning. ResolveFAILEDusing the returned message and records. - Bind the appropriate feature below. Keep existing active mappings until the new domain is active and tested.
Ownership, DNS routing, certificate readiness and application mapping are separate checks. A CNAME alone does not prove ownership or enable Cloudflare for SaaS. Provisioning requires the platform's correct Cloudflare zone/credentials and configured fallback origin. Never expose these secrets in client-side docs or requests.
Feature bindings
| Purpose | Management after activation | Public behavior |
|---|---|---|
SHORT_LINK |
Create link with domainId |
https://links.example.com/{code} resolves only inside that domain |
APP_LINK |
PATCH /v2/domains/{id}/config with appropriate appConfigId; short links can also use this purpose |
App/deep-link handling depends on the configured app and route; normal short-link HTTP(S) routing remains separate |
LINKFOLIO |
PATCH /v2/domains/linkfolio-mapping with linkFolioId, attachDomainIds, detachDomainIds |
Host root serves the mapped active profile |
BLOG |
PATCH /v2/domains/blog-profile-mapping with profileId, attachDomainIds, detachDomainIds |
Host root serves the mapped active blog; /{slug} serves a published article |
SURVEY |
PUT /v2/forms/{id}/domain with {"domainId":"DOMAIN_ID"}, then POST /v2/forms/{id}/publish |
Host root can serve its published default form; form requests remain domain-scoped |
| QR | Save QR style on the underlying link/profile/form/blog/deep link | QR encodes the intended public URL; it has no independent domain purpose |
| Campaign | Attach existing assets using campaign APIs | Uses each asset's domain/public URL; there is no CAMPAIGN domain purpose |
YSHOP is a legacy enum in this repository, not an instruction to configure standalone yShop through yLnk.
Example LinkFolio binding:
PATCH /v2/domains/linkfolio-mapping
Authorization: Bearer YOUR_SESSION_TOKEN
Content-Type: application/json
{"linkFolioId":"PROFILE_ID","attachDomainIds":["DOMAIN_ID"],"detachDomainIds":[]}
Changing a domain purpose/config may conflict with an existing mapping. Use the API's ownership/purpose checks rather than editing database fields. PATCH /v2/domains/{id}/canonical accepts {"canonical":true}; use returned canonical-host information instead of assuming every configured domain should redirect. DELETE /v2/domains/{id} removes the association; plan a safe URL migration first.
Public resolution and host forwarding
GET /v2/domains/public/route?host=blog.example.com returns route metadata including routeType, domainId, canonicalHost, and the relevant mapped profile username/form code. An unknown host can return routeType: UNKNOWN; this does not mean it is configured. GET /v2/domains/public/resolve?host=blog.example.com requires an active registered domain and returns 404 otherwise.
Use the exact public host during SSR and public API calls. Feature controllers that accept X-YLNK-HOST use it for domain scope. The edge proxy must preserve Host/forwarded host and protocol and strip/overwrite untrusted internal routing headers. Configure trusted proxy boundaries before accepting forwarded headers. Domain resolution is not an authorization mechanism for private endpoints.
The deployment chain may remain Cloudflare → Nginx forwarding → Dokploy/Traefik → app. Existing custom-domain mappings, original host, protocol, .well-known app-association routes and feature paths must survive each hop. Installing Dokploy alone does not migrate dynamic hostname routing or certificates. See the repository's Cloudflare/custom-domain deployment guides for infrastructure setup.
SEO on every domain
- Fetch the published resource with the same host context before rendering HTML.
- Emit server-rendered title, description, canonical URL, Open Graph, Twitter card and favicon from that resource; the canonical must follow the configured domain mapping.
- Social images must use public absolute HTTPS URLs, valid content type and known dimensions when available; do not use expiring private/signed image URLs for previews.
- Expose the correct domain's robots/sitemap routes. Never reuse one tenant's cached HTML for another host or cache private pages publicly.
- Test a browser and social crawler user-agent for the root, nested article/form/link path and missing-resource path. QR scans and campaign assets must lead to the same domain-scoped resource.
Short-link examples and analytics
Create using domainId, not Host manipulation:
{"originalUrl":"https://example.com","customUrl":"launch","domainId":"DOMAIN_ID"}
The public result is https://links.example.com/launch. The same launch on another domain is another record. Use the returned opaque link id for GET /v2/external/client/short-links/{id} and for analytics shortUrl=<link-id>. The legacy parameter name is shortUrl, but IDs are accepted and preferred. If using a code, add domainId=DOMAIN_ID; an ambiguous code returns 409. Analytics authorize the record before cache reads and query logs by link ID, preventing identical codes on different domains from mixing. Historical logs without urlId are not guessed into another tenant's report.
