Freestyle
Freestyle Domains API

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.
Freestyle Domains API is one of 8 APIs that Freestyle publishes on the APIs.io network, described by a machine-readable OpenAPI specification.
This API exposes 5 machine-runnable capabilities that can be deployed as REST, MCP, or Agent Skill surfaces via Naftiko.
Tagged areas include Domains, DNS, Certificates, and SSL. The published artifact set on APIs.io includes API documentation, an OpenAPI specification, and 5 Naftiko capability specs.
Documentation GitHub OpenAPI
OpenAPI Specification

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: [email protected]
  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: []
Freestyle Domains API

Documentation

Specifications

Other Resources

OpenAPI Specification
