Freestyle Domains API

openapi: 3.1.0
info:
  title: Freestyle Cron Auth Domains API
  version: 0.1.0
  description: Schedule recurring serverless runs — create/update/delete cron schedules and inspect executions, success rate, and metrics timeline.
  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. \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."
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](/#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:
  schemas:
    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.'
    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
    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
    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
    CreateDomainMappingSuccess:
      $ref: '#/components/schemas/FreestyleSandboxDomainMapping'
    VerifyDomainSuccess:
      type: object
      required:
      - domain
      properties:
        domain:
          type: string
    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
    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.'
    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'
    FreestyleDomainVerificationRequest:
      type: object
      required:
      - domain
      properties:
        domain:
          type: string
          description: The domain to create a verification code for
          example: example.com
    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
    SuccessfullyDeletedDomainMapping:
      type: object
    DeploymentId:
      type: string
      format: uuid
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer