Skip to content

Commit 8c99874

Browse files
stainless-app[bot]stainless-app[bot]
committed
feat(api): Organizations Open API docs (#31)
1 parent 364fd42 commit 8c99874

9 files changed

+661
-61
lines changed

Diff for: ‎.stats.yml

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

Diff for: ‎organization.go

+291-11
Original file line numberDiff line numberDiff line change
@@ -42,31 +42,136 @@ func NewOrganizationService(opts ...option.RequestOption) (r *OrganizationServic
4242
return
4343
}
4444

45-
// CreateOrganization creates a new Organization.
45+
// Creates a new organization with the specified name and settings.
46+
//
47+
// Use this method to:
48+
//
49+
// - Create a new organization for team collaboration
50+
// - Set up automatic domain-based invites for team members
51+
// - Join the organization immediately upon creation
52+
//
53+
// ### Examples
54+
//
55+
// - Create a basic organization:
56+
//
57+
// Creates an organization with just a name.
58+
//
59+
// ```yaml
60+
// name: "Acme Corp Engineering"
61+
// joinOrganization: true
62+
// ```
63+
//
64+
// - Create with domain-based invites:
65+
//
66+
// Creates an organization that automatically invites users with matching email
67+
// domains.
68+
//
69+
// ```yaml
70+
// name: "Acme Corp"
71+
// joinOrganization: true
72+
// inviteAccountsWithMatchingDomain: true
73+
// ```
4674
func (r *OrganizationService) New(ctx context.Context, body OrganizationNewParams, opts ...option.RequestOption) (res *OrganizationNewResponse, err error) {
4775
opts = append(r.Options[:], opts...)
4876
path := "gitpod.v1.OrganizationService/CreateOrganization"
4977
err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, &res, opts...)
5078
return
5179
}
5280

53-
// GetOrganization retrieves a single Organization.
81+
// Gets details about a specific organization.
82+
//
83+
// Use this method to:
84+
//
85+
// - Retrieve organization settings and configuration
86+
// - Check organization membership status
87+
// - View domain verification settings
88+
//
89+
// ### Examples
90+
//
91+
// - Get organization details:
92+
//
93+
// Retrieves information about a specific organization.
94+
//
95+
// ```yaml
96+
// organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
97+
// ```
5498
func (r *OrganizationService) Get(ctx context.Context, body OrganizationGetParams, opts ...option.RequestOption) (res *OrganizationGetResponse, err error) {
5599
opts = append(r.Options[:], opts...)
56100
path := "gitpod.v1.OrganizationService/GetOrganization"
57101
err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, &res, opts...)
58102
return
59103
}
60104

61-
// UpdateOrganization updates the properties of an Organization.
105+
// Updates an organization's settings including name, invite domains, and member
106+
// policies.
107+
//
108+
// Use this method to:
109+
//
110+
// - Modify organization display name
111+
// - Configure email domain restrictions
112+
// - Update organization-wide settings
113+
// - Manage member access policies
114+
//
115+
// ### Examples
116+
//
117+
// - Update basic settings:
118+
//
119+
// Changes organization name and invite domains.
120+
//
121+
// ```yaml
122+
// organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
123+
// name: "New Company Name"
124+
// inviteDomains:
125+
// domains:
126+
// - "company.com"
127+
// - "subsidiary.com"
128+
// ```
129+
//
130+
// - Remove domain restrictions:
131+
//
132+
// Clears all domain-based invite restrictions.
133+
//
134+
// ```yaml
135+
// organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
136+
// inviteDomains:
137+
// domains: []
138+
// ```
62139
func (r *OrganizationService) Update(ctx context.Context, body OrganizationUpdateParams, opts ...option.RequestOption) (res *OrganizationUpdateResponse, err error) {
63140
opts = append(r.Options[:], opts...)
64141
path := "gitpod.v1.OrganizationService/UpdateOrganization"
65142
err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, &res, opts...)
66143
return
67144
}
68145

69-
// ListOrganizations lists all organization the caller has access to.
146+
// Lists all organizations the caller has access to with optional filtering.
147+
//
148+
// Use this method to:
149+
//
150+
// - View organizations you're a member of
151+
// - Browse all available organizations
152+
// - Paginate through organization results
153+
//
154+
// ### Examples
155+
//
156+
// - List member organizations:
157+
//
158+
// Shows organizations where the caller is a member.
159+
//
160+
// ```yaml
161+
// pagination:
162+
// pageSize: 20
163+
// scope: SCOPE_MEMBER
164+
// ```
165+
//
166+
// - List all organizations:
167+
//
168+
// Shows all organizations visible to the caller.
169+
//
170+
// ```yaml
171+
// pagination:
172+
// pageSize: 50
173+
// scope: SCOPE_ALL
174+
// ```
70175
func (r *OrganizationService) List(ctx context.Context, params OrganizationListParams, opts ...option.RequestOption) (res *pagination.OrganizationsPage[Organization], err error) {
71176
var raw *http.Response
72177
opts = append(r.Options[:], opts...)
@@ -84,36 +189,153 @@ func (r *OrganizationService) List(ctx context.Context, params OrganizationListP
84189
return res, nil
85190
}
86191

87-
// ListOrganizations lists all organization the caller has access to.
192+
// Lists all organizations the caller has access to with optional filtering.
193+
//
194+
// Use this method to:
195+
//
196+
// - View organizations you're a member of
197+
// - Browse all available organizations
198+
// - Paginate through organization results
199+
//
200+
// ### Examples
201+
//
202+
// - List member organizations:
203+
//
204+
// Shows organizations where the caller is a member.
205+
//
206+
// ```yaml
207+
// pagination:
208+
// pageSize: 20
209+
// scope: SCOPE_MEMBER
210+
// ```
211+
//
212+
// - List all organizations:
213+
//
214+
// Shows all organizations visible to the caller.
215+
//
216+
// ```yaml
217+
// pagination:
218+
// pageSize: 50
219+
// scope: SCOPE_ALL
220+
// ```
88221
func (r *OrganizationService) ListAutoPaging(ctx context.Context, params OrganizationListParams, opts ...option.RequestOption) *pagination.OrganizationsPageAutoPager[Organization] {
89222
return pagination.NewOrganizationsPageAutoPager(r.List(ctx, params, opts...))
90223
}
91224

92-
// DeleteOrganization deletes the specified organization.
225+
// Permanently deletes an organization.
226+
//
227+
// Use this method to:
228+
//
229+
// - Remove unused organizations
230+
// - Clean up test organizations
231+
// - Complete organization migration
232+
//
233+
// ### Examples
234+
//
235+
// - Delete organization:
236+
//
237+
// Permanently removes an organization and all its data.
238+
//
239+
// ```yaml
240+
// organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
241+
// ```
93242
func (r *OrganizationService) Delete(ctx context.Context, body OrganizationDeleteParams, opts ...option.RequestOption) (res *OrganizationDeleteResponse, err error) {
94243
opts = append(r.Options[:], opts...)
95244
path := "gitpod.v1.OrganizationService/DeleteOrganization"
96245
err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, &res, opts...)
97246
return
98247
}
99248

100-
// JoinOrganization lets accounts join an Organization.
249+
// Allows users to join an organization through direct ID, invite link, or
250+
// domain-based auto-join.
251+
//
252+
// Use this method to:
253+
//
254+
// - Join an organization via direct ID or invite
255+
// - Join automatically based on email domain
256+
// - Accept organization invitations
257+
//
258+
// ### Examples
259+
//
260+
// - Join via organization ID:
261+
//
262+
// Joins an organization directly when you have the ID.
263+
//
264+
// ```yaml
265+
// organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
266+
// ```
267+
//
268+
// - Join via invite:
269+
//
270+
// Accepts an organization invitation link.
271+
//
272+
// ```yaml
273+
// inviteId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
274+
// ```
101275
func (r *OrganizationService) Join(ctx context.Context, body OrganizationJoinParams, opts ...option.RequestOption) (res *OrganizationJoinResponse, err error) {
102276
opts = append(r.Options[:], opts...)
103277
path := "gitpod.v1.OrganizationService/JoinOrganization"
104278
err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, &res, opts...)
105279
return
106280
}
107281

108-
// LeaveOrganization lets the passed user leave an Organization.
282+
// Removes a user from an organization while preserving organization data.
283+
//
284+
// Use this method to:
285+
//
286+
// - Remove yourself from an organization
287+
// - Clean up inactive memberships
288+
// - Transfer project ownership before leaving
289+
// - Manage team transitions
290+
//
291+
// ### Examples
292+
//
293+
// - Leave organization:
294+
//
295+
// Removes user from organization membership.
296+
//
297+
// ```yaml
298+
// userId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
299+
// ```
300+
//
301+
// Note: Ensure all projects and resources are transferred before leaving.
109302
func (r *OrganizationService) Leave(ctx context.Context, body OrganizationLeaveParams, opts ...option.RequestOption) (res *OrganizationLeaveResponse, err error) {
110303
opts = append(r.Options[:], opts...)
111304
path := "gitpod.v1.OrganizationService/LeaveOrganization"
112305
err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, &res, opts...)
113306
return
114307
}
115308

116-
// ListMembers lists all members of the specified organization.
309+
// Lists and filters organization members with optional pagination.
310+
//
311+
// Use this method to:
312+
//
313+
// - View all organization members
314+
// - Monitor member activity
315+
// - Manage team membership
316+
//
317+
// ### Examples
318+
//
319+
// - List active members:
320+
//
321+
// Retrieves active members with pagination.
322+
//
323+
// ```yaml
324+
// organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
325+
// pagination:
326+
// pageSize: 20
327+
// ```
328+
//
329+
// - List with pagination:
330+
//
331+
// Retrieves next page of members.
332+
//
333+
// ```yaml
334+
// organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
335+
// pagination:
336+
// pageSize: 50
337+
// token: "next-page-token-from-previous-response"
338+
// ```
117339
func (r *OrganizationService) ListMembers(ctx context.Context, params OrganizationListMembersParams, opts ...option.RequestOption) (res *pagination.MembersPage[OrganizationMember], err error) {
118340
var raw *http.Response
119341
opts = append(r.Options[:], opts...)
@@ -131,12 +353,70 @@ func (r *OrganizationService) ListMembers(ctx context.Context, params Organizati
131353
return res, nil
132354
}
133355

134-
// ListMembers lists all members of the specified organization.
356+
// Lists and filters organization members with optional pagination.
357+
//
358+
// Use this method to:
359+
//
360+
// - View all organization members
361+
// - Monitor member activity
362+
// - Manage team membership
363+
//
364+
// ### Examples
365+
//
366+
// - List active members:
367+
//
368+
// Retrieves active members with pagination.
369+
//
370+
// ```yaml
371+
// organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
372+
// pagination:
373+
// pageSize: 20
374+
// ```
375+
//
376+
// - List with pagination:
377+
//
378+
// Retrieves next page of members.
379+
//
380+
// ```yaml
381+
// organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
382+
// pagination:
383+
// pageSize: 50
384+
// token: "next-page-token-from-previous-response"
385+
// ```
135386
func (r *OrganizationService) ListMembersAutoPaging(ctx context.Context, params OrganizationListMembersParams, opts ...option.RequestOption) *pagination.MembersPageAutoPager[OrganizationMember] {
136387
return pagination.NewMembersPageAutoPager(r.ListMembers(ctx, params, opts...))
137388
}
138389

139-
// SetRole
390+
// Manages organization membership and roles by setting a user's role within the
391+
// organization.
392+
//
393+
// Use this method to:
394+
//
395+
// - Promote members to admin role
396+
// - Change member permissions
397+
// - Demote admins to regular members
398+
//
399+
// ### Examples
400+
//
401+
// - Promote to admin:
402+
//
403+
// Makes a user an organization administrator.
404+
//
405+
// ```yaml
406+
// organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
407+
// userId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
408+
// role: ORGANIZATION_ROLE_ADMIN
409+
// ```
410+
//
411+
// - Change to member:
412+
//
413+
// Changes a user's role to regular member.
414+
//
415+
// ```yaml
416+
// organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
417+
// userId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
418+
// role: ORGANIZATION_ROLE_MEMBER
419+
// ```
140420
func (r *OrganizationService) SetRole(ctx context.Context, body OrganizationSetRoleParams, opts ...option.RequestOption) (res *OrganizationSetRoleResponse, err error) {
141421
opts = append(r.Options[:], opts...)
142422
path := "gitpod.v1.OrganizationService/SetRole"

0 commit comments

Comments
 (0)