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

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

Get an organization

By ID

const { data: org } = await r.organizations.get('org_123');
console.log(org.name);
console.log(org.slug);
console.log(org.image);
console.log(org.members.length);
for (const member of org.members) {
  console.log(`  @${member.username} — ${member.role}`);
}

By slug

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

Returns: SingleResponse<OrganizationDetail>

interface OrganizationDetail {
  id: string;
  name: string;
  slug: string;
  image: string | null;
  created_at: string;
  updated_at: string;
  members: OrganizationMember[];
}
interface OrganizationMember {
  id: string;
  name: string;
  username: string;
  image: string | null;
  role: string;      // 'owner' | 'admin' | 'member'
  joined_at: string;
}

Create an organization

const { data: org } = await r.organizations.create({
  name: 'Acme Corporation',
  slug: 'acme-corp',
});
console.log(org.id);
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

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

Update fields:

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

Delete an organization

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

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

Add a member

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

const { data: membership } = await r.organizations.addMember('org_123', {
  user_id: 'user_456',
  role: 'member',
});
console.log(membership.role);      // 'member'
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.

const { data: result } = await r.organizations.invite('org_123', {
  email: 'new-member@example.com',
  role: 'member',
});
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

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

Update a member’s role

const { data: updated } = await r.organizations.updateMemberRole(
  'org_123',
  'user_456',
  'admin',
);
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

import { Recursiv } from '@recursiv/sdk';
const r = new Recursiv();
// 1. Create an organization
const { data: org } = await r.organizations.create({
  name: 'My Startup',
  slug: 'my-startup',
});
console.log('Created org:', org.id);
// 2. Invite team members
await r.organizations.invite(org.id, {
  email: 'alice@example.com',
  role: 'admin',
});
await r.organizations.invite(org.id, {
  email: 'bob@example.com',
  role: 'member',
});
// 3. List members
const { data: members } = await r.organizations.members(org.id);
console.log(`${members.length} members:`);
for (const m of members) {
  console.log(`  @${m.username} — ${m.role}`);
}
// 4. Create a project in the organization
const { data: project } = await r.projects.create({
  organization_id: org.id,
  name: 'Main App',
});
console.log('Created project:', project.slug);
// 5. Look up the org by slug
const { data: found } = await r.organizations.getBySlug('my-startup');
console.log('Found org:', found.name);
// 6. Update a member's role
// (Assuming we know Alice's user ID from the members list)
const alice = members.find((m) => m.username === 'alice');
if (alice) {
  await r.organizations.updateMemberRole(org.id, alice.id, 'admin');
  console.log('Alice promoted to admin');
}