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.

OpenAPI Specification

freestyle-domains-api-openapi.yml Raw ↑
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: []