Concepts

Platforms

A platform is your thin.host account. It represents an agent product or SaaS that integrates thin.host for custom domain provisioning. Each platform gets:

• An API key for authentication
• A webhook URL for status change notifications
• A plan tier (Free, Indie, Platform, Enterprise) with usage limits
• Optional white-label settings for the claim page

Domains

A domain represents a custom domain provisioned through your platform. Domains go through a lifecycle:

pending_payment → pending_dns → pending_ssl → active
                                                  ↓
                                              released (via DELETE)

Each domain is tied to a platform, has an origin URL (where traffic is proxied to), and has billing state (Stripe subscription).

Claim Sessions

When a domain is provisioned, thin.host creates a claim session — a short-lived (24h) URL that the end user visits to:

1. Complete Stripe payment ($8/mo default)
2. View DNS configuration instructions
3. Monitor DNS propagation and SSL provisioning in real-time

The claim page is hosted by thin.host, so your agent product never needs to build billing or DNS UX.

Webhooks

Configure a webhook URL in your platform settings to receive notifications when domain status changes:

{
  "event": "payment_completed",
  "domain_id": "uuid",
  "hostname": "mysite.com",
  "status": "pending_dns"
}

Events: payment_completed, domain_active, subscription_cancelled

Idempotency

All write endpoints support idempotency keys (via the idempotency_key body field or Idempotency-Key header). If you retry a provision with the same key, thin.host returns the existing domain instead of creating a duplicate. This is critical for agent calling patterns where retries are common.

DNS

thin.host uses Approximated for proxy and SSL. The end user needs to set one DNS record:

Type:  CNAME
Name:  mysite.com
Value: cname.thin.host

For apex domains (no www), an A or ALIAS record may be needed depending on the registrar. The claim page provides registrar-specific instructions.