Manage custom domains for Freestyle Web Deployments and VMs — list domains, create/verify ownership, insert and remove domain → deployment mappings, provision wildcard SSL certificates, and manage DNS records for Freestyle-hosted domains.
openapi: 3.1.0
info:
title: Freestyle Domains API
version: 0.1.0
description: Manage custom domains, domain verifications, DNS records, domain mappings, and wildcard SSL certificates for
Freestyle Web Deployments and VMs.
contact:
name: Ben
email: ben@freestyle.sh
license:
name: Closed Source
servers:
- url: https://api.freestyle.sh
description: Production
tags:
- name: Domains
description: "APIs for managing domains. This is only relevant when you want to start to deploy to custom domains. \nPlease\
\ read [this guide](https://github.com/freestyle-sh/sandbox_sdks/blob/main/docs/custom_domains.md) to understand how deployments\
\ work with custom domains."
- name: DNS
description: APIs for managing DNS records.
- name: Certs
description: APIs for managing SSL certificates.
paths:
/dns/v1/records:
get:
tags:
- DNS
summary: List DNS Records
operationId: handle_list_records
parameters:
- name: domain
in: query
required: true
schema:
type: string
example: example.com
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ListRecordsResponse'
'400':
description: ''
content:
application/json:
schema:
type: object
required:
- message
properties:
message:
type: string
post:
tags:
- DNS
summary: Create DNS Record
operationId: handle_create_record
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateRecordParams'
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/CreateRecordResponse'
'403':
description: 'Possible errors: DomainOwnershipError, RecordOwnershipError, DomainOwnershipVerificationFailed'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
'500':
description: 'Possible errors: ErrorCreatingRecord, ErrorDeletingRecord'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
delete:
tags:
- DNS
summary: Delete DNS Record
operationId: handle_delete_record
parameters:
- name: domain
in: query
required: true
schema:
type: string
example: example.com
- name: record
in: query
required: true
schema:
$ref: '#/components/schemas/DnsRecord'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteRecordResponse'
'403':
description: 'Possible errors: DomainOwnershipError, RecordOwnershipError, DomainOwnershipVerificationFailed'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
'500':
description: 'Possible errors: ErrorCreatingRecord, ErrorDeletingRecord'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
/domains/v1/certs/{domain}/wildcard:
post:
tags:
- Certs
- Domains
summary: Provision a Wildcard Certificate
description: 'Provisions a wildcard certificate for a verified domain
This speeds up deploys on all subdomains of the domain. In order to use it, you must add the following record to your
DNS config:
`_acme-challenge.yourdomain.com` NS `dns.freestyle.sh`'
operationId: handle_verify_wildcard
parameters:
- name: domain
in: path
required: true
schema:
type: string
responses:
'200':
description: Domain verified
content:
application/json:
schema:
type: object
required:
- domain
properties:
domain:
type: string
example: example.com
'400':
description: Failed to preverify domain
content:
application/json:
schema:
type: object
required:
- message
properties:
message:
type: string
/domains/v1/domains:
get:
tags:
- Domains
summary: List Domains for an Account
description: This lists the domains that an account has verified ownership of. This includes the *.style.dev domains
the account has claimed.
operationId: handle_list_domains
parameters:
- name: limit
in: query
required: false
schema:
type:
- integer
- 'null'
format: int64
- name: offset
in: query
required: false
schema:
type:
- integer
- 'null'
format: int64
- name: implicitlyOwned
in: query
required: false
schema:
type:
- boolean
- 'null'
responses:
'200':
description: List of domains
content:
application/json:
schema:
type: array
items:
type: object
required:
- domain
- accountId
- createdAt
- id
- verifiedDns
- implicitlyOwned
- deployToDomain
- manageDns
- deployToSubdomains
properties:
domain:
type: string
accountId:
type: string
format: uuid
createdAt:
type: string
format: date-time
id:
type: string
format: uuid
verifiedDns:
type: boolean
implicitlyOwned:
type: boolean
deployToDomain:
type: boolean
manageDns:
type: boolean
deployToSubdomains:
type: boolean
'400':
description: Failed to get domains
content:
application/json:
schema:
type: object
required:
- message
properties:
message:
type: string
/domains/v1/mappings:
get:
tags:
- Domains
summary: List Domain Mappings
description: List domain mappings for any query based on exact domain or domain ownership (the domain ownership that
gave the right to use the domain)
operationId: handle_list_domain_mappings
parameters:
- name: offset
in: query
required: false
schema:
type:
- integer
- 'null'
format: int64
- name: limit
in: query
required: false
schema:
type:
- integer
- 'null'
format: int64
- name: domainOwnership
in: query
required: false
schema:
type:
- string
- 'null'
format: uuid
- name: domain
in: query
required: false
schema:
type:
- string
- 'null'
responses:
'200':
description: List of domain mappings
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/FreestyleSandboxDomainMapping'
'401':
description: Unauthorized
/domains/v1/mappings/{domain}:
post:
tags:
- Domains
summary: Insert Domain Mapping
description: This will unmap any other deployment to this domain. Provide either deployment_id or vm_id (with optional
vm_port), but not both.
operationId: handle_insert_domain_mapping
parameters:
- name: domain
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDomainMappingRequest'
required: true
responses:
'200':
description: Successfully mapped domain to deployment
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDomainMappingSuccess'
4XX:
description: Client error
content:
application/json:
schema:
$ref: '#/components/schemas/Public_DomainMappingError'
5XX:
description: Server error
content:
application/json:
schema:
$ref: '#/components/schemas/Public_DomainMappingError'
delete:
tags:
- Domains
summary: Remove Domain Mapping
operationId: handle_delete_domain_mapping
parameters:
- name: domain
in: path
required: true
schema:
type: string
responses:
'200':
description: Successfully deleted domain mapping
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessfullyDeletedDomainMapping'
'400':
description: 'Possible errors: DomainAlreadyExists, InvalidRequest'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
'401':
description: 'Possible errors: FailedPermissionsCheck, DeploymentAccessDenied, VmAccessDeniedForMapping, DomainOwnershipNotVerified'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
'422':
description: 'Error: FailedToProvisionCertificateForMapping'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
'500':
description: 'Possible errors: FailedRemoveDomainMapping, FailedToInsertOwnership, FailedInsertDomainMapping'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
'502':
description: 'Error: FailedToCheckDomainMappingPermissions'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
/domains/v1/verifications:
get:
tags:
- Domains
summary: List Domain Verification Requests for an Account
description: Lists domain verification requests for the current account.
operationId: handle_list_domain_verification_requests
responses:
'200':
description: List of verification codes
content:
application/json:
schema:
type: array
items:
type: object
required:
- verificationCode
- domain
- createdAt
properties:
verificationCode:
type: string
domain:
type: string
createdAt:
type: string
format: date-time
'400':
description: Failed to get verification codes
content:
application/json:
schema:
type: object
required:
- message
properties:
message:
type: string
put:
tags:
- Domains
summary: Verify a Domain Verification Request
description: This checks a pre-existing verification request for a domain. To create a verification request, call the
[create domain verification](/#tag/domains/POST/domains/v1/verifications) endpoint. This endpoint will check if the
domain has a TXT record with the verification code. If it does, the domain will be verified.
operationId: handle_verify_domain
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FreestyleVerifyDomainRequest'
required: true
responses:
'200':
description: Domain verified
content:
application/json:
schema:
$ref: '#/components/schemas/VerifyDomainSuccess'
'400':
description: 'Possible errors: InvalidDomain, FailedToCreateVerificationCode, FailedToDeleteVerification, VerificationFailed'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
'401':
description: 'Error: PermissionDenied'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
'403':
description: 'Error: LimitExceeded'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
'404':
description: 'Error: VerificationNotFound'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
'422':
description: 'Error: FailedToProvisionCertificate'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
'500':
description: 'Possible errors: FailedToVerifyDomain, FailedToListVerifications, FailedToListDomains, FailedToInsertDomainMapping,
InternalError'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
'502':
description: 'Error: FailedToCheckPermissions'
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code in SCREAMING_SNAKE_CASE
message:
type: string
description: Human-readable error message
post:
tags:
- Domains
summary: Create a Domain Verification Request
description: This creates a Freestyle Domain Verification Request. It returns a `verificationCode` for your domain.
You need to place this code in a TXT record at `_freestyle_custom_hostname.thedomain.com`, then call the [verify domain](/#tag/domains/PUT/domains/v1/verifications)
endpoint with the domain to verify it.
operationId: handle_create_domain_verification
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FreestyleDomainVerificationRequest'
required: true
responses:
'200':
description: Verification code created
content:
application/json:
schema:
$ref: '#/components/schemas/DomainVerificationRequest'
'400':
description: Failed to create verification code
content:
application/json:
schema:
type: object
required:
- message
properties:
message:
type: string
delete:
tags:
- Domains
summary: Delete a Domain Verification Request
description: This deletes a Freestyle Domain Verification Request. This does not remove the domain from the account
if it has already been verified, however the verification code will no longer be valid.
operationId: handle_delete_domain_verification
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FreestyleDeleteDomainVerificationRequest'
required: true
responses:
'200':
description: Verification code created
content:
application/json:
schema:
type: object
required:
- verificationCode
- domain
properties:
verificationCode:
type: string
domain:
type: string
example: example.com
'400':
description: Failed to create verification code
content:
application/json:
schema:
type: object
required:
- message
properties:
message:
type: string
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
schemas:
DnsRecordData:
type: object
required:
- kind
- name
- value
properties:
kind:
$ref: '#/components/schemas/DnsRecordKind'
name:
type: string
value:
type: string
ttl:
type:
- string
- 'null'
priority:
type:
- integer
- 'null'
format: int32
minimum: 0
FreestyleDomainVerificationRequest:
type: object
required:
- domain
properties:
domain:
type: string
description: The domain to create a verification code for
example: example.com
DeleteRecordResponse:
type: object
required:
- message
properties:
message:
type: string
Error_DomainMappingError:
type: object
description: 'The structure of an error - should rarely be interacted with directly.
Create your own error types, implement [`ServiceError`] for them, and they will automatically
convert to [`Error`] with `?` or `.into()`.'
required:
- error
properties:
error:
oneOf:
- type: object
required:
- FailedToCheckDomainMappingPermissions
properties:
FailedToCheckDomainMappingPermissions:
type: object
required:
- message
properties:
message:
type: string
- type: object
required:
- FailedPermissionsCheck
properties:
FailedPermissionsCheck:
type: object
required:
- domain
properties:
domain:
type: string
- type: object
required:
- FailedRemoveDomainMapping
properties:
FailedRemoveDomainMapping:
type: object
required:
- message
properties:
message:
type: string
- type: object
required:
- FailedToInsertOwnership
properties:
FailedToInsertOwnership:
type: object
required:
- message
properties:
message:
type: string
- type: object
required:
- DomainAlreadyExists
properties:
DomainAlreadyExists:
type: object
required:
- domain
properties:
domain:
type: string
- type: object
required:
- InvalidRequest
properties:
InvalidRequest:
type: object
required:
- message
properties:
message:
type: string
- type: object
required:
- FailedInsertDomainMapping
properties:
FailedInsertDomainMapping:
type: object
required:
- message
properties:
message:
type: string
- type: object
required:
- FailedToProvisionCertificateForMapping
properties:
FailedToProvisionCertificateForMapping:
type: object
required:
- message
properties:
message:
type: string
- type: object
required:
- DeploymentAccessDenied
properties:
DeploymentAccessDenied:
type: object
required:
- deployment_id
properties:
deployment_id:
type: string
- type: object
required:
- VmAccessDeniedForMapping
properties:
VmAccessDeniedForMapping:
type: object
required:
- vm_id
properties:
vm_id:
type: string
- type: object
required:
- DomainOwnershipNotVerified
properties:
DomainOwnershipNotVerified:
type: object
required:
- domain
properties:
domain:
type: string
headers:
type:
- object
- 'null'
additionalProperties:
type: string
propertyNames:
type: string
context:
type:
- object
- 'null'
additionalProperties: {}
propertyNames:
type: string
FreestyleSandboxDomainMapping:
type: object
required:
- id
- domain
- ownershipId
- createdAt
properties:
id:
type: string
format: uuid
domain:
type: string
deploymentId:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/DeploymentId'
vmId:
type:
- string
- 'null'
vmPort:
type:
- integer
- 'null'
format: int32
ownershipId:
type: string
format: uuid
createdAt:
type: string
format: date-time
unmappedAt:
type:
- string
- 'null'
format: date-time
CreateRecordResponse:
type: object
required:
- record
properties:
record:
$ref: '#/components/schemas/DnsRecord'
CreateDomainMappingRequest:
type: object
properties:
deploymentId:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/DeploymentId'
vmId:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/VmId'
vmPort:
type:
- integer
- 'null'
format: int32
Public_DomainMappingError:
$ref: '#/components/schemas/Error_DomainMappingError'
description: 'Public API error wrapper. Mark public APIs with `Public<T>` to ensure private error
details aren''t exposed.'
DomainVerificationRequest:
type: object
required:
- id
- domain
- accountId
- verificationCode
- createdAt
properties:
id:
type: string
format: uuid
example: 1234-5678-9012-3456
domain:
type: string
example: example.com
accountId:
type: string
format: uuid
example: 1234-5678-9012-3456
verificationCode:
type: string
example: freestyle-verification-v1-1234-5678-9012-3456
createdAt:
type: string
format: date-time
example: '1234567890'
SuccessfullyDeletedDomainMapping:
type: object
CreateDomainMappingSuccess:
$ref: '#/components/schemas/FreestyleSandboxDomainMapping'
DnsRecord:
type: object
required:
- kind
- name
- value
- ttl
- managed
properties:
kind:
$ref: '#/components/schemas/DnsRecordKind'
name:
type: string
value:
type: string
ttl:
type: string
priority:
type:
- integer
- 'null'
format: int32
minimum: 0
managed:
type: boolean
FreestyleDeleteDomainVerificationRequest:
type: object
required:
- domain
- verificationCode
properties:
domain:
type: string
description: The domain to create a verification code for
example: example.com
verificationCode:
type: string
description: The verification code
VerifyDomainSuccess:
type: object
required:
- domain
properties:
domain:
type: string
DnsRecordKind:
type: string
enum:
- A
- AAAA
- CNAME
- TXT
- NS
VmId:
type: string
description: "VM ID \u2014 always 20 alphanumeric lowercase characters.\nNew IDs are fully random. Legacy short IDs\
\ are right-padded with '0' on parse."
CreateRecordParams:
type: object
required:
- domain
- record
properties:
domain:
type: string
record:
$ref: '#/components/schemas/DnsRecordData'
FreestyleVerifyDomainRequest:
oneOf:
- type: object
required:
- domain
properties:
domain:
type: string
example: example.com
- type: object
required:
- id
properties:
id:
type: string
format: uuid
example: 1234-5678-9012-3456
description: Verify a domain verification request, can either be done for a domain, or for a specific request
DeploymentId:
type: string
format: uuid
ListRecordsResponse:
type: object
required:
- records
properties:
records:
type: array
items:
$ref: '#/components/schemas/DnsRecord'
security:
- bearerAuth: []