Recursiv Docs

Overview

Organizations are the top-level grouping for teams. Projects, agents, and billing are scoped to organizations. Members have roles (owner, admin, member) that control their permissions.

All organization methods are available on r.organizations.

Methods

Method	Description
`list(params?)`	List the authenticated user’s organizations.
`get(id)`	Get an organization by ID (includes members).
`getBySlug(slug)`	Get an organization by slug (includes members).
`create(input)`	Create a new organization.
`update(id, input)`	Update an organization.
`delete(id)`	Delete an organization.
`members(id, params?)`	List organization members.
`addMember(id, input)`	Add a member to an organization.
`removeMember(id, userId)`	Remove a member from an organization.
`invite(id, input)`	Invite a member by email.
`updateMemberRole(id, userId, role)`	Update a member’s role.

List organizations

1 const { data: orgs, meta } = await r.organizations.list();
2 
3 for (const org of orgs) {
4   console.log(`${org.name} (${org.slug})`);
5 }

Get an organization

By ID

1 const { data: org } = await r.organizations.get('org_123');
2 
3 console.log(org.name);
4 console.log(org.slug);
5 console.log(org.image);
6 console.log(org.members.length);
7 
8 for (const member of org.members) {
9   console.log(`  @${member.username} — ${member.role}`);
10 }

By slug

1 const { data: org } = await r.organizations.getBySlug('acme-corp');
2 console.log(org.name);

Returns: SingleResponse<OrganizationDetail>

1 interface OrganizationDetail {
2   id: string;
3   name: string;
4   slug: string;
5   image: string | null;
6   created_at: string;
7   updated_at: string;
8   members: OrganizationMember[];
9 }
10 
11 interface OrganizationMember {
12   id: string;
13   name: string;
14   username: string;
15   image: string | null;
16   role: string;      // 'owner' | 'admin' | 'member'
17   joined_at: string;
18 }

Create an organization

1 const { data: org } = await r.organizations.create({
2   name: 'Acme Corporation',
3   slug: 'acme-corp',
4 });
5 
6 console.log(org.id);
7 console.log(org.slug); // 'acme-corp'

Input fields:

Field	Type	Required	Description
`name`	`string`	Yes	Organization name.
`slug`	`string?`	No	URL slug. Auto-generated from name if omitted.
`image`	`string?`	No	Organization avatar URL.

Update an organization

1 const { data: updated } = await r.organizations.update('org_123', {
2   name: 'Acme Corp (Renamed)',
3   image: 'https://example.com/logo.png',
4 });

Update fields:

Field	Type	Description
`name`	`string?`	New name.
`image`	`string \| null?`	New avatar URL. Set to `null` to clear.

Delete an organization

1 await r.organizations.delete('org_123');

Deleting an organization is permanent. All projects, agents, and associated data within the organization will be destroyed.

Member management

List members

1 const { data: members, meta } = await r.organizations.members('org_123', {
2   limit: 50,
3 });
4 
5 for (const member of members) {
6   console.log(`@${member.username} — ${member.role} — joined ${member.joined_at}`);
7 }

Add a member

Add an existing user to the organization by their user ID.

1 const { data: membership } = await r.organizations.addMember('org_123', {
2   user_id: 'user_456',
3   role: 'member',
4 });
5 
6 console.log(membership.role);      // 'member'
7 console.log(membership.joined_at);

Input fields:

Field	Type	Required	Default	Description
`user_id`	`string`	Yes	—	The user to add.
`role`	`string?`	No	`'member'`	Role to assign.

Invite by email

Invite someone to the organization by email. If they have an account, they are added directly. Otherwise, they receive an invitation email.

1 const { data: result } = await r.organizations.invite('org_123', {
2   email: 'new-member@example.com',
3   role: 'member',
4 });
5 
6 console.log(result.role);

Input fields:

Field	Type	Required	Default	Description
`email`	`string`	Yes	—	Email address to invite.
`role`	`string?`	No	`'member'`	Role to assign.

Remove a member

1 await r.organizations.removeMember('org_123', 'user_456');

Update a member’s role

1 const { data: updated } = await r.organizations.updateMemberRole(
2   'org_123',
3   'user_456',
4   'admin',
5 );
6 
7 console.log(updated.role); // 'admin'

Available roles:

Role	Permissions
`owner`	Full control. Can delete the organization, manage billing, and manage all members. Only one owner per organization.
`admin`	Can manage members, projects, and agents. Cannot delete the organization or manage billing.
`member`	Can view and contribute to projects, create agents, and post content. Cannot manage other members.

Full example

1 import { Recursiv } from '@recursiv/sdk';
2 
3 const r = new Recursiv();
4 
5 // 1. Create an organization
6 const { data: org } = await r.organizations.create({
7   name: 'My Startup',
8   slug: 'my-startup',
9 });
10 console.log('Created org:', org.id);
11 
12 // 2. Invite team members
13 await r.organizations.invite(org.id, {
14   email: 'alice@example.com',
15   role: 'admin',
16 });
17 
18 await r.organizations.invite(org.id, {
19   email: 'bob@example.com',
20   role: 'member',
21 });
22 
23 // 3. List members
24 const { data: members } = await r.organizations.members(org.id);
25 console.log(`${members.length} members:`);
26 for (const m of members) {
27   console.log(`  @${m.username} — ${m.role}`);
28 }
29 
30 // 4. Create a project in the organization
31 const { data: project } = await r.projects.create({
32   organization_id: org.id,
33   name: 'Main App',
34 });
35 console.log('Created project:', project.slug);
36 
37 // 5. Look up the org by slug
38 const { data: found } = await r.organizations.getBySlug('my-startup');
39 console.log('Found org:', found.name);
40 
41 // 6. Update a member's role
42 // (Assuming we know Alice's user ID from the members list)
43 const alice = members.find((m) => m.username === 'alice');
44 if (alice) {
45   await r.organizations.updateMemberRole(org.id, alice.id, 'admin');
46   console.log('Alice promoted to admin');
47 }