Teams API

Manage teams and team membership. Teams are the primary organizational unit in NodeLoom -- all workflows, credentials, and executions are scoped to a team. Member management endpoints require the ADMIN role.

List Teams

GET

/api/teams

List all teams the authenticated user belongs to

Response

200 OK

[
  {
    "id": "uuid",
    "name": "Engineering",
    "memberCount": 8,
    "plan": "PRO",
    "role": "ADMIN",
    "createdAt": "2026-01-15T10:00:00.000Z"
  },
  {
    "id": "uuid",
    "name": "Marketing Ops",
    "memberCount": 3,
    "plan": "STARTER",
    "role": "BUILDER",
    "createdAt": "2026-02-01T08:00:00.000Z"
  }
]

Get Team

GET

/api/teams/:teamId

Get detailed information about a specific team

200 OK

{
  "id": "uuid",
  "name": "Engineering",
  "description": "Core engineering team",
  "memberCount": 8,
  "plan": "PRO",
  "workflowCount": 24,
  "credentialCount": 12,
  "createdAt": "2026-01-15T10:00:00.000Z",
  "updatedAt": "2026-02-10T14:00:00.000Z"
}

Create Team

POST

/api/teams

Create a new team

Request Body

Field	Type	Required	Description
`name`	string	Yes	Team name
`description`	string	No	Optional team description

Request

{
  "name": "Engineering",
  "description": "Core engineering team"
}

Response

The creating user is automatically added as an ADMIN member.

201 Created

{
  "id": "uuid",
  "name": "Engineering",
  "description": "Core engineering team",
  "createdAt": "2026-02-17T10:00:00.000Z"
}

Update Team

PUT

/api/teams/:teamId

Update team details (requires ADMIN role)

Request Body

Field	Type	Required	Description
`name`	string	No	Updated team name
`description`	string	No	Updated description

Response

Returns the updated team object with a 200 OK status.

Delete Team

DELETE

/api/teams/:teamId

Delete a team and all associated data (requires ADMIN role)

Destructive operation

Deleting a team permanently removes all workflows, executions, credentials, widgets, and chat sessions associated with the team. This action cannot be undone.

200 OK

{
  "message": "Team deleted successfully"
}

Team Members

Manage team membership and roles. All member management endpoints require the ADMIN role within the team.

List Members

GET

/api/teams/:teamId/members

List all members of a team

200 OK

[
  {
    "userId": "uuid",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@example.com",
    "role": "ADMIN",
    "joinedAt": "2026-01-15T10:00:00.000Z"
  },
  {
    "userId": "uuid",
    "firstName": "John",
    "lastName": "Smith",
    "email": "john@example.com",
    "role": "BUILDER",
    "joinedAt": "2026-01-20T14:00:00.000Z"
  }
]

Add Member

POST

/api/teams/:teamId/members

Add a new member to the team (requires ADMIN role)

Field	Type	Required	Description
`email`	string	Yes	Email of the user to add
`role`	string	Yes	Role to assign: ADMIN, BUILDER, or OPERATOR

Request

{
  "email": "john@example.com",
  "role": "BUILDER"
}

Update Member Role

PUT

/api/teams/:teamId/members/:userId

Update a member's role (requires ADMIN role)

Field	Type	Required	Description
`role`	string	Yes	New role: ADMIN, BUILDER, or OPERATOR

Request

{
  "role": "ADMIN"
}

Remove Member

DELETE

/api/teams/:teamId/members/:userId

Remove a member from the team (requires ADMIN role)

200 OK

{
  "message": "Member removed successfully"
}

Last admin

You cannot remove the last ADMIN from a team. Promote another member to ADMIN first, or delete the team entirely.

Role Definitions

Role	Permissions
`ADMIN`	Full access: team settings, member management, billing, plus all BUILDER and OPERATOR permissions
`BUILDER`	Create, edit, and delete workflows and credentials. Can also execute workflows.
`OPERATOR`	View workflows and execute them. Cannot modify workflow definitions or credentials.

Error Codes

Status	Meaning
`400`	Invalid request body or invalid role value
`403`	Insufficient permissions (requires ADMIN role for member management)
`404`	Team or user not found
`409`	User is already a member of the team

Monitoring

Audit