feat(api): Organizations Open API docs (#18)

Author: stainless-app[bot]

.stats.yml

@@ -1,2 +1,2 @@
 configured_endpoints: 111
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/gitpod%2Fgitpod-27f7bd641de1e4657ad8ce84a456fe0c5e8f1e14779bf1f567a4bc8667eba4da.yml
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/gitpod%2Fgitpod-0c37e687e2a070abfe49501156af6d906ff166b6eaad779ee6c2b568515f2b7e.yml

src/resources/organizations/domain-verifications.ts

@@ -7,7 +7,34 @@ import { RequestOptions } from '../../internal/request-options';
 
 export class DomainVerifications extends APIResource {
   /**
-   * CreateDomainVerification creates a new domain verification request
+   * Initiates domain verification process to enable organization features.
+   *
+   * Use this method to:
+   *
+   * - Start domain ownership verification
+   * - Enable automatic team joining
+   * - Set up SSO restrictions
+   * - Configure email-based policies
+   *
+   * ### Examples
+   *
+   * - Verify primary domain:
+   *
+   *   Starts verification for main company domain.
+   *
+   *   ```yaml
+   *   organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
+   *   domain: "acme-corp.com"
+   *   ```
+   *
+   * - Verify subsidiary domain:
+   *
+   *   Adds verification for additional company domain.
+   *
+   *   ```yaml
+   *   organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
+   *   domain: "acme-subsidiary.com"
+   *   ```
    */
   create(
     body: DomainVerificationCreateParams,
@@ -17,7 +44,23 @@ export class DomainVerifications extends APIResource {
   }
 
   /**
-   * GetDomainVerification retrieves a domain verification request
+   * Retrieves the status of a domain verification request.
+   *
+   * Use this method to:
+   *
+   * - Check verification progress
+   * - View verification requirements
+   * - Monitor domain status
+   *
+   * ### Examples
+   *
+   * - Get verification status:
+   *
+   *   Checks the current state of a domain verification.
+   *
+   *   ```yaml
+   *   domainVerificationId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   ```
    */
   retrieve(
     body: DomainVerificationRetrieveParams,
@@ -27,7 +70,37 @@ export class DomainVerifications extends APIResource {
   }
 
   /**
-   * ListDomainVerifications lists all domain verifications for an organization
+   * Lists and monitors domain verification status across an organization.
+   *
+   * Use this method to:
+   *
+   * - Track verification progress
+   * - View all verified domains
+   * - Monitor pending verifications
+   * - Audit domain settings
+   *
+   * ### Examples
+   *
+   * - List all verifications:
+   *
+   *   Shows all domain verifications regardless of status.
+   *
+   *   ```yaml
+   *   organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
+   *   pagination:
+   *     pageSize: 20
+   *   ```
+   *
+   * - List with pagination:
+   *
+   *   Retrieves next page of verifications.
+   *
+   *   ```yaml
+   *   organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
+   *   pagination:
+   *     pageSize: 20
+   *     token: "next-page-token-from-previous-response"
+   *   ```
    */
   list(
     params: DomainVerificationListParams,
@@ -42,14 +115,46 @@ export class DomainVerifications extends APIResource {
   }
 
   /**
-   * DeleteDomainVerification deletes a domain verification request
+   * Removes a domain verification request.
+   *
+   * Use this method to:
+   *
+   * - Cancel pending verifications
+   * - Remove verified domains
+   * - Clean up unused domain records
+   *
+   * ### Examples
+   *
+   * - Delete verification:
+   *
+   *   Removes a domain verification request.
+   *
+   *   ```yaml
+   *   domainVerificationId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   ```
    */
   delete(body: DomainVerificationDeleteParams, options?: RequestOptions): APIPromise<unknown> {
     return this._client.post('/gitpod.v1.OrganizationService/DeleteDomainVerification', { body, ...options });
   }
 
   /**
-   * VerifyDomain verifies a domain ownership
+   * Verifies domain ownership for an organization.
+   *
+   * Use this method to:
+   *
+   * - Complete domain verification process
+   * - Enable domain-based features
+   * - Validate DNS configuration
+   *
+   * ### Examples
+   *
+   * - Verify domain ownership:
+   *
+   *   Verifies ownership after DNS records are configured.
+   *
+   *   ```yaml
+   *   domainVerificationId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   ```
    */
   verify(
     body: DomainVerificationVerifyParams,

src/resources/organizations/invites.ts

@@ -6,24 +6,55 @@ import { RequestOptions } from '../../internal/request-options';
 
 export class Invites extends APIResource {
   /**
-   * CreateOrganizationInvite creates an invite for the organization. Any existing
+   * Creates an invite link for joining an organization. Any existing
    * OrganizationInvites are invalidated and can no longer be used.
+   *
+   * Use this method to:
+   *
+   * - Generate shareable invite links
+   * - Manage team growth
+   * - Control organization access
+   *
+   * ### Examples
+   *
+   * - Create organization invite:
+   *
+   *   Generates a new invite link for the organization.
+   *
+   *   ```yaml
+   *   organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
+   *   ```
    */
   create(body: InviteCreateParams, options?: RequestOptions): APIPromise<InviteCreateResponse> {
     return this._client.post('/gitpod.v1.OrganizationService/CreateOrganizationInvite', { body, ...options });
   }
 
   /**
-   * GetOrganizationInvite retrieves invite for the organization. If no invite
-   * exists, a new one is created.
+   * GetOrganizationInvite
    */
   retrieve(body: InviteRetrieveParams, options?: RequestOptions): APIPromise<InviteRetrieveResponse> {
     return this._client.post('/gitpod.v1.OrganizationService/GetOrganizationInvite', { body, ...options });
   }
 
   /**
-   * GetOrganizationInviteSummary retrieves a summary of the organization based on an
-   * Invite ID. Used to discover which organization an invite is for.
+   * Retrieves organization details and membership info based on an invite link.
+   *
+   * Use this method to:
+   *
+   * - Preview organization details before joining
+   * - Validate invite link authenticity
+   * - Check organization size and activity
+   * - View team information before accepting
+   *
+   * ### Examples
+   *
+   * - Get invite summary:
+   *
+   *   Retrieves organization information from an invite.
+   *
+   *   ```yaml
+   *   inviteId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   ```
    */
   getSummary(body: InviteGetSummaryParams, options?: RequestOptions): APIPromise<InviteGetSummaryResponse> {
     return this._client.post('/gitpod.v1.OrganizationService/GetOrganizationInviteSummary', {