# SaaS Custom Domains API

> REST API for SaaS Custom Domains, a managed reverse proxy that gives your customers branded custom domains with automatic TLS. Base URL `https://app.saascustomdomains.com/api/v1`. Authenticate with `Authorization: Bearer <token>` (create tokens at https://app.saascustomdomains.com/api_tokens). JSON in and out. 360 requests per minute per token.

MCP server: `https://mcp.saascustomdomains.com/mcp` (Streamable HTTP; sign in with OAuth or send `Authorization: Bearer <token>`). It has tools for custom domains, DNS records, upstreams, redirects, rules and analytics. Setup: https://docs.saascustomdomains.com/mcp.

Every page below is also available as markdown: request it with `Accept: text/markdown`. The whole reference is in one file at https://docs.saascustomdomains.com/llms-full.txt, and the OpenAPI 3.1 spec is at https://docs.saascustomdomains.com/openapi.json.

To add custom domains to an app with an AI coding agent, use the skill at https://docs.saascustomdomains.com/.well-known/agent-skills/saas-custom-domains/SKILL.md. The plugin at https://github.com/saas-custom-domains/skills installs the skill and connects the MCP server in one step in Claude Code, Codex and VS Code; setup for each agent: https://saascustomdomains.com/agent-setup. To run operations from a terminal, a script or CI, use the CLI: `npx @saas-custom-domains/cli` (https://docs.saascustomdomains.com/cli). How agents get API credentials: https://docs.saascustomdomains.com/auth.md.

## Guides

- [Quickstart](https://docs.saascustomdomains.com/quickstart): base URL and your first authenticated request
- [MCP server](https://docs.saascustomdomains.com/mcp): connect claude.ai, ChatGPT, Claude Code, Cursor, VS Code, Windsurf, Cline or Codex, and the tools it offers
- [CLI](https://docs.saascustomdomains.com/cli): `npx @saas-custom-domains/cli`, for terminals, scripts, CI and coding agents
- [Authentication](https://docs.saascustomdomains.com/authentication): bearer tokens
- [Pagination](https://docs.saascustomdomains.com/pagination): `page` and `per_page` on list endpoints
- [Custom domain types](https://docs.saascustomdomains.com/custom-domains-guide): subdomains (CNAME), root domains (two A records) and wildcard domains (DNS-01), and the DNS records each needs
- [Handling forwarded requests](https://docs.saascustomdomains.com/handling-forwarded-requests): the headers your app receives (`X-Served-For`, `X-SaaS-Domains-Auth-Token`, ...), how to verify the auth token, and caches in front of your app
- [Webhooks](https://docs.saascustomdomains.com/webhooks): domain and upstream events, payloads, token verification, retries
- [Rate limits](https://docs.saascustomdomains.com/rate-limits): API limits and the 429 response
- [Errors](https://docs.saascustomdomains.com/errors): status codes and error codes

## API reference

- [Accounts](https://docs.saascustomdomains.com/accounts): list the accounts your token can access
- [Upstreams](https://docs.saascustomdomains.com/upstreams): the apps your custom domains forward to
- [Custom domains](https://docs.saascustomdomains.com/custom-domains): create, list, retrieve and delete custom domains, find a domain by host across accounts, get and re-check its DNS records, purge the HTTP cache
- [Rules](https://docs.saascustomdomains.com/rules): match requests (path, method, header, query, country, IP) and redirect, rewrite, respond, change headers or rate limit
- [Custom certificates](https://docs.saascustomdomains.com/custom-certificates): list, retrieve and delete uploaded certificates
- [Redirects](https://docs.saascustomdomains.com/redirects): domain-level URL redirects
- [Web analytics](https://docs.saascustomdomains.com/web-analytics): visitors, page views, sources, pages, locations and devices per custom domain, or a one-request summary
- [Proxy analytics](https://docs.saascustomdomains.com/proxy-analytics): requests, data transfer, response times, response codes, bots and datacenters per custom domain, or a one-request summary

## Optional

- [Example apps](https://github.com/saas-custom-domains): runnable multi-tenant examples for Next.js, Nuxt, SvelteKit, Express, Hono, Rails, Django, FastAPI, Laravel, Go, Phoenix, ASP.NET Core and Spring Boot
- [scd-mock](https://github.com/saas-custom-domains/scd-mock): a local mock of the API and proxy for development and CI
- [Help center](https://help.saascustomdomains.com): setup, DNS, billing and troubleshooting
- [Product overview](https://saascustomdomains.com/llms.txt)