Freestyle Domains API

openapi: 3.2.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
security:
- bearerAuth: []
tags:
- name: Domains
  description: 'APIs for managing domains. This is only relevant when you want to start to deploy to custom domains.

    Please read this guide to understand how deployments work with custom domains.'
paths:
  /domains/v1/certs/{domain}/wildcard:
    post:
      tags:
      - 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 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 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:
  schemas:
    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
    FreestyleDomainVerificationRequest:
      type: object
      required:
      - domain
      properties:
        domain:
          type: string
          description: The domain to create a verification code for
          example: example.com
    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
    DeploymentId:
      type: string
      format: uuid
    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
    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
    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.'
    CreateDomainMappingSuccess:
      $ref: '#/components/schemas/FreestyleSandboxDomainMapping'
    VmId:
      type: string
      description: 'VM ID — always 20 alphanumeric lowercase characters.

        New IDs are fully random. Legacy short IDs are right-padded with ''0'' on parse.'
    SuccessfullyDeletedDomainMapping:
      type: object
    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'
    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
    VerifyDomainSuccess:
      type: object
      required:
      - domain
      properties:
        domain:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer