> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.recursiv.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.recursiv.io/_mcp/server.

# Organizations

## 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

```typescript
const { data: orgs, meta } = await r.organizations.list();

for (const org of orgs) {
  console.log(`${org.name} (${org.slug})`);
}
```

## Get an organization

### By ID

```typescript
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

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

**Returns:** `SingleResponse<OrganizationDetail>`

```typescript
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

```typescript
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

```typescript
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

```typescript
await r.organizations.delete('org_123');
```

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

## Member management

### List members

```typescript
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.

```typescript
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.

```typescript
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

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

### Update a member's role

```typescript
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

```typescript
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');
}
```