Custom domain
Covers 4 API operations in the hostnames category.
| Method | Path | Description |
|---|---|---|
| GET | /v1/orgs/{orgSlug}/projects/{projectName}/hostnames | List of domains attached to the project (runlot domain list) |
| POST | /v1/orgs/{orgSlug}/projects/{projectName}/hostnames | Connects a custom domain (runlot domain add) |
| DELETE | /v1/orgs/{orgSlug}/projects/{projectName}/hostnames/{host} | Disconnects a custom domain (runlot domain rm) |
| POST | /v1/orgs/{orgSlug}/projects/{projectName}/hostnames/{host}/verify | Verify a domain now (runlot domain verify) |
GET /v1/orgs/{orgSlug}/projects/{projectName}/hostnames
The default hostname (kind: default) and custom domains (kind: custom) are returned
together. Custom domain records include a guidance record (verify) and a status
(docs/domains.md §3.2). Requires viewer or higher.
operationId listHostnames
| Status code | Description | Response body |
|---|---|---|
| 200 | List | HostnameList |
| 403 | — | — |
| 404 | — | — |
POST /v1/orgs/{orgSlug}/projects/{projectName}/hostnames
The name is normalized to lowercase punycode and stored. Names under
wildcards and under our domains (*.runlot.app, *.runlot.dev,
*.runlot.io, the app domain) are not accepted.
The record is created in pending_dns state, and reserves that name from
that moment. No other project can use the same name while it is still
being verified. It is not added to routing until it is connected, so requests
to that name return 404 unknown_hostname.
If the same project sends the same name again, the existing row is returned
unchanged (idempotent) — because if the token changed, the TXT record already
in place would instantly become wrong. member and above.
Audited as hostname.add.
operationId addHostname
Request body: application/json · object
| Status code | Description | Response body |
|---|---|---|
| 200 | A newly created record, or an existing one | Hostname |
| 400 | Not a valid name shape (bad_request), a wildcard, or under our domain | Error |
| 403 | — | — |
| 404 | — | — |
| 409 | A name already in use by another project. code is hostname_taken | Error |
DELETE /v1/orgs/{orgSlug}/projects/{projectName}/hostnames/{host}
Deletes the Cloudflare custom hostname and the managed record in the
Runlot DNS zone together.
You cannot delete the default hostname (400). Since deployment
determines the address, deleting it here leaves the project unreachable
until the next deployment. Requires member or higher.
Audit hostname.delete.
operationId deleteHostname
| Status code | Description | Response body |
|---|---|---|
| 204 | detached | — |
| 400 | This is the default hostname | Error |
| 403 | — | — |
| 404 | — | — |
POST /v1/orgs/{orgSlug}/projects/{projectName}/hostnames/{host}/verify
Runs the same verification procedure immediately as the background job (1-minute cycle).
Ownership verification passes if it meets one of three conditions: the name is inside
our zone and the org matches, the _runlot-verify.<host> TXT record matches, or the
CNAME of <host> points to the fallback
origin.
There is no way to become active without proof of ownership. If it does not pass,
the status stays the same, and lastError holds what is currently observed. Requires
member or higher.
operationId verifyHostname
| Status code | Description | Response body |
|---|---|---|
| 200 | Row after confirmation | Hostname |
| 403 | — | — |
| 404 | — | — |