Guides/Custom subdomains and multi-page routing

Custom subdomains and multi-page routing

Your subdomain. Your pages. Your site.

Updated March 2026

Sutrena is the web runtime for AI agents. Every account gets a subdomain where pages are served. Set a memorable name, create pages with different slugs, and you have a complete website at your-name.sutrena.com. This guide covers subdomain setup, page routing, navigation patterns, and tips for building cohesive multi-page sites.

1. Understand subdomain routing

Every page you create has a slug. The slug maps directly to a path under your subdomain. The slug "index" is special -- it serves as the root page at your-name.sutrena.com/. All other slugs map to your-name.sutrena.com/slug. For example: slug "about" becomes your-name.sutrena.com/about, slug "contact" becomes your-name.sutrena.com/contact. Use relative links (/about, /contact) in your HTML to navigate between pages.

2. Set a memorable subdomain

Every account gets a random subdomain on creation (e.g. site-a1b2c3d4.sutrena.com). Change it to something memorable with PUT /api/account/subdomain. Rules: 3-30 characters, lowercase alphanumeric and hyphens, cannot start or end with a hyphen.

curl -X PUT https://sutrena.com/api/account/subdomain   -H "Authorization: Bearer $KEY"   -H "Content-Type: application/json"   -d '{"subdomain": "alice"}'

# Your pages are now at alice.sutrena.com/*

3. Plan your pages

Check your existing pages with GET /api/pages. Plan your site structure before creating pages. Common patterns: index (homepage), about, contact, blog, pricing, docs. Each slug must be unique within your account.

# List existing pages
curl https://sutrena.com/api/pages   -H "Authorization: Bearer $KEY"

# Response:
# {
#   "pages": [
#     { "id": "pg_001", "slug": "index", "title": "Home" },
#     { "id": "pg_002", "slug": "about", "title": "About" }
#   ]
# }

4. Create pages with shared navigation

Use the same navigation HTML across all pages for a consistent site. Relative links (/about, /schedule) work across subdomain and custom domain routing. Keep the nav in every page so visitors can move between pages.

curl -X POST https://sutrena.com/api/pages   -H "Authorization: Bearer $KEY"   -H "Content-Type: application/json"   -d '{
    "slug": "index",
    "title": "Home",
    "html": "<!DOCTYPE html><html><head><style>nav{padding:1rem;background:#1a1a1a}nav a{color:#fff;margin-right:1rem;text-decoration:none}nav a:hover{text-decoration:underline}main{max-width:720px;margin:2rem auto;padding:0 1rem}</style></head><body><nav><a href="/">Home</a><a href="/about">About</a><a href="/contact">Contact</a></nav><main><h1>Welcome</h1><p>This is alice.sutrena.com</p></main></body></html>"
  }'

# Repeat for /about and /contact with the same nav HTML

5. Optional: Add a custom domain

Builder+ plans can add a custom domain so your site is served at mysite.com. Each custom domain is linked to a specific subdomain — specify subdomainId to choose which one (defaults to your first subdomain). Both URLs work simultaneously.

# Get your subdomain ID first
curl https://sutrena.com/api/account/subdomains   -H "Authorization: Bearer $KEY"

# Add domain linked to that subdomain
curl -X POST https://sutrena.com/api/account/domains   -H "Authorization: Bearer $KEY"   -H "Content-Type: application/json"   -d '{"domain": "mysite.com", "subdomainId": "YOUR_SUBDOMAIN_ID"}'

# Then add a CNAME record: mysite.com → cname.sutrena.com
# Once DNS verifies, mysite.com/about serves the same page as alice.sutrena.com/about

FAQ

What happens to existing pages when I change my subdomain?

All your pages move to the new subdomain instantly. If you change from alice to bob, alice.sutrena.com/about stops working and bob.sutrena.com/about starts. Page IDs and slugs remain the same. Update any external links pointing to the old subdomain.

Can multiple users have the same slug?

Yes. Slugs are scoped to your account. Alice can have an "about" page and Bob can have an "about" page. They are served at alice.sutrena.com/about and bob.sutrena.com/about respectively. Slugs must be unique within a single account.

Do custom domains replace subdomains?

No. Both work simultaneously. Each custom domain is linked to one specific subdomain. Adding mysite.com linked to alice does not disable alice.sutrena.com. Both URLs serve the same pages. You can change which subdomain a domain serves from with PATCH /api/account/domains/:id.

How do custom domains work with multiple subdomains?

Each custom domain serves pages from exactly one subdomain. When you add a domain, specify subdomainId to choose which subdomain it serves from. If you have alice.sutrena.com and blog.sutrena.com, you can link mysite.com to alice and blog.mysite.com to blog.

Related

Set up a custom subdomain →Custom domains with CNAME →Deploy a page via API →Build a multi-page website via API →

What is Sutrena?

Sutrena is the web runtime for AI agents. Three primitives — pages, forms, and dashboards — accessible through one API. Your agent creates web artifacts, humans interact with them, and your agent gets the data back. Framework-agnostic. Works from any MCP client or HTTP client.

Get started in two API calls

1. Get a trial key (no auth, no signup)

curl -X POST https://sutrena.com/api/trial

2. Create a form + dashboard from a template

curl -X POST https://sutrena.com/api/forms \
  -H "Authorization: Bearer st_trial_xxx" \
  -H "Content-Type: application/json" \
  -d '{"templateId": "waitlist", "createDashboard": true}'
/llms.txt/api/schema/llms-full.txt/.well-known/mcp.json

Ready to build?

Get a trial API key instantly with no signup, or create an account for the full experience.

Start buildingAgent docs
Custom subdomains and multi-page routing — Sutrena | Sutrena