chore: Update OpenAPI Specs

platform/beta.yml

@@ -28,6 +28,11 @@ tags:
     description: An object representing a Clerk application. Each `application` can have multiple `instances`, typically one for development and one for production, each with distinct user pools.
   - name: Domains
     description: An object representing a domain associated with a Clerk application. In development `instances`, a domain is provided by Clerk. Production `instances` require additional configuration to be set up.
+  - name: Domain Intents
+    description: |-
+      An object representing the intent to create a Clerk domain.
+      The high-level for domain intent consumption:
+      1. Create a domain intent, and receive the DNS records for the future domain to function. 2. Create a domain, supplying the intent ID.
   - name: Application Transfers
     description: |-
       An object representing a transfer request for an application between workspaces.
@@ -799,6 +804,180 @@ paths:
           $ref: '#/components/responses/AuthorizationInvalid'
         '404':
           $ref: '#/components/responses/ResourceNotFound'
+  /platform/domain_intents:
+    get:
+      operationId: PlatformListDomainIntents
+      x-speakeasy-group: platform
+      x-speakeasy-name-override: listDomainIntents
+      tags:
+        - Domain Intents
+      summary: List domain intents
+      description: |
+        List all domain intents created by the authenticated workspace. Returns
+        intents sorted by creation date in descending order (most recent first).
+      security:
+        - platform_api_access_token: []
+      parameters:
+        - name: name
+          in: query
+          description: Filter by exact domain name.
+          required: false
+          schema:
+            type: string
+        - name: status
+          in: query
+          description: |
+            Filter by domain intent status. Multiple values can be provided by
+            repeating the parameter (e.g., `?status=pending&status=canceled`).
+          required: false
+          style: form
+          explode: true
+          schema:
+            type: array
+            items:
+              type: string
+              enum:
+                - pending
+                - completed
+                - expired
+                - canceled
+        - name: limit
+          in: query
+          description: Number of results to return per page (1-500, default 10).
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 500
+            default: 10
+        - name: starting_after
+          in: query
+          description: |
+            Cursor for pagination. Provide the ID of the last domain intent from
+            the previous page to get the next page of results.
+          required: false
+          schema:
+            type: string
+        - name: ending_before
+          in: query
+          description: |
+            Cursor for pagination. Provide the ID of the first domain intent from
+            the previous page to get the previous page of results.
+          required: false
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Domain intents retrieved successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlatformListDomainIntentsResponse'
+        '401':
+          $ref: '#/components/responses/AuthenticationInvalid'
+        '403':
+          $ref: '#/components/responses/AuthorizationInvalid'
+        '422':
+          $ref: '#/components/responses/UnprocessableEntity'
+    post:
+      operationId: PlatformCreateDomainIntent
+      x-speakeasy-group: platform
+      x-speakeasy-name-override: createDomainIntent
+      tags:
+        - Domain Intents
+      summary: Create a domain intent
+      description: |
+        Create a pending domain intent and receive DNS records for
+        the domain name.
+      security:
+        - platform_api_access_token: []
+      requestBody:
+        description: Domain intent data to create.
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/PlatformCreateDomainIntentRequest'
+      responses:
+        '201':
+          description: Domain intent created successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlatformDomainIntentResponse'
+        '400':
+          $ref: '#/components/responses/ClerkErrors'
+        '401':
+          $ref: '#/components/responses/AuthenticationInvalid'
+        '403':
+          $ref: '#/components/responses/AuthorizationInvalid'
+        '422':
+          $ref: '#/components/responses/UnprocessableEntity'
+  /platform/domain_intents/{domainIntentID}:
+    get:
+      operationId: PlatformGetDomainIntent
+      x-speakeasy-group: platform
+      x-speakeasy-name-override: getDomainIntent
+      tags:
+        - Domain Intents
+      summary: Get a domain intent
+      description: |
+        Retrieve a domain intent by ID.
+      security:
+        - platform_api_access_token: []
+      parameters:
+        - name: domainIntentID
+          in: path
+          description: Domain intent ID.
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Domain intent retrieved successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlatformDomainIntentResponse'
+        '401':
+          $ref: '#/components/responses/AuthenticationInvalid'
+        '403':
+          $ref: '#/components/responses/AuthorizationInvalid'
+        '404':
+          $ref: '#/components/responses/ResourceNotFound'
+    delete:
+      operationId: PlatformCancelDomainIntent
+      x-speakeasy-group: platform
+      x-speakeasy-name-override: cancelDomainIntent
+      tags:
+        - Domain Intents
+      summary: Cancel a domain intent
+      description: |
+        Cancel a pending domain intent.
+      security:
+        - platform_api_access_token: []
+      parameters:
+        - name: domainIntentID
+          in: path
+          description: Domain intent ID.
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Domain intent canceled successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlatformDomainIntentResponse'
+        '400':
+          $ref: '#/components/responses/ClerkErrors'
+        '401':
+          $ref: '#/components/responses/AuthenticationInvalid'
+        '403':
+          $ref: '#/components/responses/AuthorizationInvalid'
+        '404':
+          $ref: '#/components/responses/ResourceNotFound'
   /platform/application_transfers:
     get:
       operationId: PlatformListApplicationTransfers
@@ -2418,6 +2597,20 @@ components:
           description: Optional proxy path for provider domains.
       required:
         - name
+    PlatformCNameTarget:
+      type: object
+      additionalProperties: false
+      properties:
+        host:
+          type: string
+        value:
+          type: string
+        required:
+          type: boolean
+      required:
+        - host
+        - value
+        - required
     PlatformDomainApplicationSummary:
       type: object
       additionalProperties: false
@@ -2502,14 +2695,7 @@ components:
         cname_targets:
           type: array
           items:
-            type: object
-            properties:
-              host:
-                type: string
-              value:
-                type: string
-              required:
-                type: boolean
+            $ref: '#/components/schemas/PlatformCNameTarget'
           description: |
             CNAME targets for the domain. Omitted for development domains, which do not use custom-domain DNS setup.
         created_at:
@@ -2559,10 +2745,13 @@ components:
       properties:
         name:
           type: string
-          description: The provider domain name.
+          description: The domain name.
         proxy_path:
           type: string
           description: Optional proxy path for provider domains.
+        domain_intent_id:
+          type: string
+          description: Optional domain intent ID to complete into this domain.
       required:
         - name
     FailureHint:
@@ -2753,6 +2942,80 @@ components:
       required:
         - data
         - total_count
+    PlatformDomainIntentResponse:
+      title: Domain Intent
+      description: Represents the intent to create a domain. Can later be completed into a real application domain.
+      type: object
+      additionalProperties: false
+      properties:
+        object:
+          type: string
+          enum:
+            - domain_intent
+        id:
+          type: string
+          description: The unique identifier for the domain intent.
+          example: dmnint_2abc123def456
+        status:
+          type: string
+          enum:
+            - pending
+            - completed
+            - expired
+            - canceled
+          description: The current status of the domain intent.
+        expires_at:
+          type: integer
+          format: int64
+          description: Unix timestamp in milliseconds when the intent expires.
+        domain_id:
+          type: string
+          description: The completed domain ID, if the intent has been completed.
+        domain_name:
+          type: string
+          description: The intended domain name.
+        records:
+          type: array
+          description: DNS records to configure before completion.
+          items:
+            $ref: '#/components/schemas/PlatformCNameTarget'
+      required:
+        - object
+        - id
+        - status
+        - expires_at
+        - records
+    PlatformListDomainIntentsResponse:
+      title: List Domain Intents Response
+      description: A paginated list of domain intents.
+      type: object
+      additionalProperties: false
+      properties:
+        data:
+          type: array
+          description: The list of domain intents.
+          items:
+            $ref: '#/components/schemas/PlatformDomainIntentResponse'
+        total_count:
+          type: integer
+          format: int64
+          description: The total number of domain intents matching the query.
+          example: 5
+      required:
+        - data
+        - total_count
+    PlatformCreateDomainIntentRequest:
+      type: object
+      additionalProperties: false
+      properties:
+        name:
+          type: string
+          description: Domain name.
+        proxy_path:
+          type: string
+          description: Optional proxy path for the domain intent. Treated as a hint to determine optionality of DNS records in the response.
+      required:
+        - name
     PlatformApplicationTransferResponse:
       title: Application Transfer
       description: Represents an application transfer request. Application transfers allow transferring ownership of an application from one organization to another.
@@ -4499,6 +4762,7 @@ x-tagGroups:
     tags:
       - Applications
       - Domains
+      - Domain Intents
       - Application Transfers
       - Users
       - JWT Templates