Teams API

Endpoints for managing teams and team membership.

Teams#

Team CRUD endpoints. Teams provide the scope namespace for skills and control access to private skills.

GET/api/v1/teams

List all teams the current user belongs to.

Auth: Required

Response

{
  "data": [
    {
      "id": "uuid",
      "slug": "backend",
      "displayName": "Backend Team",
      "description": "Backend engineering team",
      "memberCount": 12,
      "skillCount": 8,
      "createdAt": "2025-03-10T09:00:00Z"
    }
  ]
}

POST/api/v1/teams

Create a new team. The authenticated user becomes the owner.

Auth: Required

Request Body

{
  "slug": "backend",
  "displayName": "Backend Team",
  "description": "Backend engineering team"
}

Response

{
  "id": "uuid",
  "slug": "backend",
  "displayName": "Backend Team",
  "description": "Backend engineering team",
  "memberCount": 1,
  "skillCount": 0,
  "createdAt": "2025-09-20T10:00:00Z"
}

GET/api/v1/teams/:slug

Get full details for a specific team. Requires team membership.

Auth: Required (viewer)

Response

{
  "id": "uuid",
  "slug": "backend",
  "displayName": "Backend Team",
  "description": "Backend engineering team",
  "avatarUrl": null,
  "memberCount": 12,
  "skillCount": 8,
  "createdAt": "2025-03-10T09:00:00Z",
  "updatedAt": "2025-09-18T14:00:00Z"
}

PATCH/api/v1/teams/:slug

Update a team's display name or description. Only provided fields are modified.

Auth: Required (admin)

Request Body

{
  "displayName": "Backend Engineering",
  "description": "Core backend engineering team"
}

Members#

Member management endpoints for listing, inviting, updating roles, and removing team members.

GET/api/v1/teams/:slug/members

List all members of a team with their roles.

Auth: Required (viewer)

Response

{
  "data": [
    {
      "userId": "uuid",
      "email": "alice@example.com",
      "displayName": "Alice",
      "avatarUrl": "https://example.com/avatar/alice.png",
      "role": "owner",
      "createdAt": "2025-03-10T09:00:00Z"
    },
    {
      "userId": "uuid",
      "email": "bob@example.com",
      "displayName": "Bob",
      "avatarUrl": "https://example.com/avatar/bob.png",
      "role": "member",
      "createdAt": "2025-04-02T11:00:00Z"
    }
  ]
}

POST/api/v1/teams/:slug/members

Add a member to the team by email.

Auth: Required (admin)

Request Body

{
  "email": "charlie@example.com",
  "role": "member"
}

Response

{
  "userId": "uuid",
  "email": "charlie@example.com",
  "displayName": "Charlie",
  "role": "member",
  "createdAt": "2025-09-20T10:00:00Z"
}

Available roles:

Role	Description
`viewer`	Can view team skills and members. Cannot publish or modify.
`member`	Can publish and manage skills within the team scope.
`admin`	Can manage team settings and members. Can invite and remove users.

PATCH/api/v1/teams/:slug/members/:userId

Update a team member's role. Only the team owner can change roles.

Auth: Required (admin)

Request Body

{
  "role": "admin"
}

DELETE/api/v1/teams/:slug/members/:userId

Remove a member from the team. Admins can remove members; members can remove themselves.

Auth: Required (admin)