Teams

Create Team

Changed on Oct 13, 2026

Create a new team

post/api/v3/meta/workspaces/{workspaceId}/teams

Request

Base URL
https://app.nocodb.com
Auth
- API key in header xc-token
- or HTTP bearer
TypeScript
https://skmtc.dev/nocodb/apis/nocodb-v3/docs/api/v3/meta/workspaces/:workspaceId/teams/post.ts
A function with typed inputs. Its response is checked against the schema.

Path parameters

workspaceIdstring required

Workspace ID

Request body

titlestring required

Team name

iconstring nullable

Team icon (emoji or icon identifier)

icon_type'EMOJI' | 'ICON' nullable

Team icon type

badge_colorstring

Team badge color (hex code)

parent_team_idstring nullable

Parent team ID. Null or omitted = root team.

Example request

{
  "title": "Design Team",
  "icon": "🎨",
  "icon_type": "EMOJI",
  "badge_color": "#FF5733",
  "members": [
    {
      "user_id": "xxxx",
      "team_role": "member"
    }
  ],
  "parent_team_id": "tmd_abc123"
}

Response

Created team

idstring required

Unique team identifier

titlestring required

Team name

iconstring nullable

Team icon (emoji or icon identifier)

icon_type'EMOJI' | 'ICON' nullable

Team icon type

badge_colorstring

Team badge color (hex code)

members_countinteger required

Number of team members

managers_countinteger

Number of team managers

fk_org_idstring

Organization ID (for Cloud Enterprise)

fk_workspace_idstring

Workspace ID (for other plans)

created_atstring date-time

Team creation timestamp

updated_atstring date-time

Team last update timestamp

fk_parent_team_idstring nullable

Parent team ID. Null = root team.

depthinteger

Depth in the team tree. Root teams have depth 0.

pathstring

Materialized path for efficient ancestor/descendant queries.

is_memberboolean

Whether the requesting user is a member of this team.

scim_managedboolean

Whether the team is provisioned by SCIM from an identity provider.

managersstring[]

List of user IDs who are owners/managers of this team.

Example response

{
  "id": "t12345",
  "title": "Design Team",
  "icon": "🎨",
  "icon_type": "EMOJI",
  "badge_color": "#FF5733",
  "members_count": 10,
  "managers_count": 2,
  "depth": 1,
  "path": "/eng/fe/web"
}

Changes

Oct 13, 20262ba4267a99d7 Revision changes
- info
  api operation id teams-create-v3 removed and replaced with teams-create
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the optional property to the response with the status

Operation history