Workspace Management

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const client = new ElevenLabsClient({ apiKey: "your-api-key" });
// Access this API via: client.workspace

/**
 * Updates attributes of a workspace member. Apart from the email identifier,
 * all parameters will remain unchanged unless specified.
 * This endpoint may only be called by workspace administrators.
 */
client.workspace.members.update(
  request: UpdateMemberRequest,
  requestOptions?: RequestOptions
): HttpResponsePromise<UpdateWorkspaceMemberResponseModel>;

interface UpdateMemberRequest {
  /** Email of the target user. (REQUIRED) */
  email: string;
  /** Whether to lock or unlock the user account. */
  isLocked?: boolean;
  /** Role dictating permissions in the workspace. */
  workspaceRole?: "owner" | "admin" | "member";
}

interface UpdateWorkspaceMemberResponseModel {
  /** Status message */
  status: string;
}

/**
 * Sends an email invitation to join your workspace to the provided email.
 * If the user doesn't have an account they will be prompted to create one.
 * If the user accepts this invite they will be added as a user to your workspace
 * and your subscription using one of your seats. This endpoint may only be called
 * by workspace administrators. If the user is already in the workspace a 400 error
 * will be returned.
 */
client.workspace.invites.create(
  request: InviteUserRequest,
  requestOptions?: RequestOptions
): HttpResponsePromise<AddWorkspaceInviteResponseModel>;

/**
 * Sends email invitations to join your workspace to the provided emails.
 * Requires all email addresses to be part of a verified domain. If the users
 * don't have an account they will be prompted to create one. If the users accept
 * these invites they will be added as users to your workspace and your subscription
 * using one of your seats. This endpoint may only be called by workspace administrators.
 */
client.workspace.invites.createBatch(
  request: BodyInviteMultipleUsersV1WorkspaceInvitesAddBulkPost,
  requestOptions?: RequestOptions
): HttpResponsePromise<AddWorkspaceInviteResponseModel>;

/**
 * Deletes a pending workspace invitation. This endpoint may only be called
 * by workspace administrators.
 */
client.workspace.invites.delete(
  request: BodyDeleteExistingInvitationV1WorkspaceInvitesDelete,
  requestOptions?: RequestOptions
): HttpResponsePromise<DeleteWorkspaceInviteResponseModel>;

interface BodyDeleteExistingInvitationV1WorkspaceInvitesDelete {
  /** The email of the customer */
  email: string;
}

interface DeleteWorkspaceInviteResponseModel {
  /** Status message */
  status: string;
}

interface InviteUserRequest {
  /** Email address to send the invitation to */
  email: string;
}

interface BodyInviteMultipleUsersV1WorkspaceInvitesAddBulkPost {
  /** List of email addresses to invite (must be from verified domain) */
  emails: string[];
}

interface AddWorkspaceInviteResponseModel {
  /** Status of the invitation */
  status: string;
  /** ID of the created invite (optional) */
  inviteId?: string;
}

/**
 * Gets the metadata of a resource by ID, including sharing permissions
 * and role assignments.
 */
client.workspace.resources.get(
  resource_id: string,
  request: ResourcesGetRequest,
  requestOptions?: RequestOptions
): HttpResponsePromise<ResourceMetadataResponseModel>;

/**
 * Grants a role on a workspace resource to a user, service account, group,
 * or workspace API key. Overrides any existing role. Requires admin access.
 * To target a user or service account, pass userEmail. To target a group,
 * pass groupId. To target a workspace API key, pass workspaceApiKeyId.
 */
client.workspace.resources.share(
  resource_id: string,
  request: ShareWorkspaceResourceRequest,
  requestOptions?: RequestOptions
): HttpResponsePromise<unknown>;

/**
 * Removes any existing role on a workspace resource from a user, service
 * account, group, or workspace API key. Requires admin access. Cannot
 * remove permissions from the resource creator.
 */
client.workspace.resources.unshare(
  resource_id: string,
  request: UnshareWorkspaceResourceRequest,
  requestOptions?: RequestOptions
): HttpResponsePromise<unknown>;

/**
 * Copies a workspace resource to another workspace.
 */
client.workspace.resources.copyToWorkspace(
  resource_id: string,
  request: CopyWorkspaceResourceRequest,
  requestOptions?: RequestOptions
): HttpResponsePromise<unknown>;

interface ResourcesGetRequest {
  /** Resource type of the target resource */
  resourceType: WorkspaceResourceType;
}

interface ShareWorkspaceResourceRequest {
  /** Role to grant (admin, editor, commenter, viewer) */
  role: "admin" | "editor" | "commenter" | "viewer";
  /** Resource type of the target resource */
  resourceType: WorkspaceResourceType;
  /** Email of the user or service account (optional) */
  userEmail?: string;
  /** ID of the target group, or 'default' for default permissions (optional) */
  groupId?: string;
  /** ID of the workspace API key (optional) */
  workspaceApiKeyId?: string;
}

interface UnshareWorkspaceResourceRequest {
  /** Resource type of the target resource */
  resourceType: WorkspaceResourceType;
  /** Email of the user or service account (optional) */
  userEmail?: string;
  /** ID of the target group, or 'default' for default permissions (optional) */
  groupId?: string;
  /** ID of the workspace API key (optional) */
  workspaceApiKeyId?: string;
}

interface CopyWorkspaceResourceRequest {
  /** Resource type of the target resource */
  resourceType: WorkspaceResourceType;
  /** ID of the target user */
  targetUserId: string;
}

interface ResourceMetadataResponseModel {
  /** The ID of the resource */
  resourceId: string;
  /** The type of the resource */
  resourceType: WorkspaceResourceType;
  /** The ID of the user who created the resource */
  creatorUserId?: string;
  /** Access level for anonymous users (if publicly shared) */
  anonymousAccessLevelOverride?: "admin" | "editor" | "commenter" | "viewer";
  /** Mapping of roles to group IDs */
  roleToGroupIds: Record<string, string[]>;
  /** List of users/groups who can be given access */
  shareOptions: ShareOptionResponseModel[];
}

interface ShareOptionResponseModel {
  /** Email or group name */
  name: string;
  /** User/group ID */
  id: string;
  /** Type: 'user', 'group', 'service_account', or 'workspace_api_key' */
  type: string;
}

type WorkspaceResourceType =
  | "voice"
  | "voice_collection"
  | "pronunciation_dictionary"
  | "dubbing"
  | "project"
  | "convai_agents"
  | "convai_knowledge_base_documents"
  | "convai_tools"
  | "convai_settings"
  | "convai_secrets"
  | "workspace_auth_connections"
  | "convai_phone_numbers"
  | "convai_mcp_servers"
  | "convai_api_integration_connections"
  | "convai_api_integration_trigger_connections"
  | "convai_batch_calls"
  | "convai_agent_response_tests"
  | "convai_test_suite_invocations"
  | "convai_crawl_jobs"
  | "convai_crawl_tasks"
  | "convai_whatsapp_accounts"
  | "convai_agent_versions"
  | "convai_agent_branches"
  | "convai_agent_versions_deployments"
  | "dashboard"
  | "dashboard_configuration"
  | "convai_agent_drafts"
  | "resource_locators"
  | "assets"
  | "content_generations";

/**
 * Searches for user groups in the workspace. Multiple or no groups may be returned.
 */
client.workspace.groups.search(
  request: GroupsSearchRequest,
  requestOptions?: RequestOptions
): HttpResponsePromise<WorkspaceGroupByNameResponseModel[]>;

interface GroupsSearchRequest {
  /** Name of the group to search for */
  name: string;
}

interface WorkspaceGroupByNameResponseModel {
  /** Workspace group name */
  name: string;
  /** Workspace group ID */
  id: string;
  /** Member emails in the group */
  membersEmails: string[];
}

/**
 * Adds a member of your workspace to the specified group.
 * This endpoint may only be called by workspace administrators.
 */
client.workspace.groups.members.add(
  group_id: string,
  request: AddMemberToGroupRequest,
  requestOptions?: RequestOptions
): HttpResponsePromise<AddWorkspaceGroupMemberResponseModel>;

/**
 * Removes a member from the specified group.
 * This endpoint may only be called by workspace administrators.
 */
client.workspace.groups.members.remove(
  group_id: string,
  request: BodyDeleteMemberFromUserGroupV1WorkspaceGroupsGroupIdMembersRemovePost,
  requestOptions?: RequestOptions
): HttpResponsePromise<DeleteWorkspaceGroupMemberResponseModel>;

interface AddMemberToGroupRequest {
  /** Email address of the member to add to the group */
  email: string;
}

interface BodyDeleteMemberFromUserGroupV1WorkspaceGroupsGroupIdMembersRemovePost {
  /** Email address of the member to remove from the group */
  email: string;
}

interface AddWorkspaceGroupMemberResponseModel {
  /** Request status ('ok' if successful) */
  status: string;
}

interface DeleteWorkspaceGroupMemberResponseModel {
  /** Request status ('ok' if successful) */
  status: string;
}

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const client = new ElevenLabsClient({ apiKey: "your-api-key" });

// Update member's groups
await client.workspace.members.update({
  email: "member@example.com",
  groups: ["group-id-1", "group-id-2"],
});

console.log("Member groups updated");

// Send invitation to new member
const invite = await client.workspace.invites.create({
  email: "newmember@example.com",
});

console.log("Invitation sent:", invite.status);
if (invite.inviteId) {
  console.log("Invite ID:", invite.inviteId);
}

// Invite multiple members at once (requires verified domain)
await client.workspace.invites.createBatch({
  emails: [
    "member1@example.com",
    "member2@example.com",
    "member3@example.com",
  ],
});

console.log("Bulk invitations sent");

// Delete a pending invitation
await client.workspace.invites.delete("invite-id");
console.log("Invitation deleted");

// Search for groups by name
const results = await client.workspace.groups.search({
  name: "Design",
});

console.log(`Found ${results.length} groups matching "Design"`);
for (const group of results) {
  console.log(`- ${group.name} (ID: ${group.id})`);
  console.log(`  Members: ${group.membersEmails.join(", ")}`);
}

// Add a member to a specific group
await client.workspace.groups.members.add("group-id", {
  email: "member@example.com",
});

console.log("Member added to group");

// Remove a member from a group
await client.workspace.groups.members.remove("group-id", {
  email: "member@example.com",
});

console.log("Member removed from group");

// Complete workflow for inviting and organizing a new team member
async function inviteAndOrganize(
  email: string,
  groupIds: string[]
): Promise<void> {
  // 1. Send invitation
  const invite = await client.workspace.invites.create({ email });
  console.log(`Invitation sent to ${email}`);

  // Note: Once the user accepts the invitation, you can then:
  // 2. Add them to appropriate groups
  for (const groupId of groupIds) {
    await client.workspace.groups.members.add(groupId, { email });
    console.log(`Added ${email} to group ${groupId}`);
  }

  console.log("Onboarding complete");
}

await inviteAndOrganize("new.member@example.com", ["team-group-id"]);

// Update member's role in workspace
await client.workspace.members.update({
  email: "member@example.com",
  role: "admin",
});

console.log("Member role updated to admin");

// Search for a group and add a member to it
const groups = await client.workspace.groups.search({
  name: "Engineering",
});

if (groups.length > 0) {
  const engineeringGroup = groups[0];
  await client.workspace.groups.members.add(engineeringGroup.id, {
    email: "developer@example.com",
  });
  console.log(`Added developer to ${engineeringGroup.name} group`);
} else {
  console.log("Engineering group not found");
}

// Get sharing permissions for a voice
const metadata = await client.workspace.resources.get("voice-id", {
  resourceType: "voice",
});

console.log("Resource ID:", metadata.resourceId);
console.log("Creator:", metadata.creatorUserId);
console.log("Role assignments:", metadata.roleToGroupIds);

// Check who has admin access
if (metadata.roleToGroupIds.admin) {
  console.log("Admins:", metadata.roleToGroupIds.admin);
}

// Show available share options
console.log("\nAvailable to share with:");
for (const option of metadata.shareOptions) {
  console.log(`- ${option.name} (${option.type})`);
}

// Share a voice with a user, granting editor role
await client.workspace.resources.share("voice-id", {
  role: "editor",
  resourceType: "voice",
  userEmail: "colleague@example.com",
});

console.log("Voice shared with colleague");

// Share a pronunciation dictionary with a group
await client.workspace.resources.share("dictionary-id", {
  role: "viewer",
  resourceType: "pronunciation_dictionary",
  groupId: "design-team-group-id",
});

console.log("Dictionary shared with design team");

// Share an agent with admin privileges
await client.workspace.resources.share("agent-id", {
  role: "admin",
  resourceType: "convai_agents",
  userEmail: "team-lead@example.com",
});

console.log("Agent shared with team lead as admin");

// Remove access from a user
await client.workspace.resources.unshare("voice-id", {
  resourceType: "voice",
  userEmail: "former-colleague@example.com",
});

console.log("Voice access removed");

// Copy a voice to another user's workspace
await client.workspace.resources.copyToWorkspace("voice-id", {
  resourceType: "voice",
  targetUserId: "other-user-id",
});

console.log("Voice copied to target workspace");

// Complete workflow for sharing a resource with multiple users
async function shareWithTeam(
  resourceId: string,
  resourceType: WorkspaceResourceType,
  teamEmails: string[]
): Promise<void> {
  // 1. Get current sharing state
  const metadata = await client.workspace.resources.get(resourceId, {
    resourceType,
  });

  console.log(`Sharing ${resourceType} ${resourceId}`);
  console.log(`Current creator: ${metadata.creatorUserId}`);

  // 2. Share with each team member
  for (const email of teamEmails) {
    await client.workspace.resources.share(resourceId, {
      role: "editor",
      resourceType,
      userEmail: email,
    });
    console.log(`✓ Shared with ${email}`);
  }

  console.log("Resource shared with entire team");
}

await shareWithTeam("voice-123", "voice", [
  "member1@example.com",
  "member2@example.com",
]);

// Set default permissions for a resource
// Any workspace member will have viewer access by default
await client.workspace.resources.share("project-id", {
  role: "viewer",
  resourceType: "project",
  groupId: "default", // Special value for default permissions
});

console.log("Default viewer permissions set for all workspace members");