Teams

Overview

The Teams endpoints let you list teams in your organization, retrieve team details, and manage team membership. Teams are the primary organizational unit in Mandraki — channels, projects, and Drive folders are scoped to teams.

Base path: /orgs/{orgId}/bot/teams

List Teams

Retrieve all teams in the organization.

GET /orgs/{orgId}/bot/teams

Required scope: teams:read

Query Parameters

Parameter	Type	Description
search	string	Filter teams by name (case-insensitive partial match)
limit	integer	Maximum number of teams to return

Example Request

curl -X GET "https://app.mandraki.cloud/api/v1/orgs/{orgId}/bot/teams?search=engineering" \
  -H "Authorization: Bearer mak_..."

Example Response

{
  "teams": [
    {
      "id": "team-uuid-1",
      "name": "Engineering",
      "slug": "engineering",
      "description": "Product engineering team",
      "memberCount": 12,
      "createdAt": "2026-01-10T09:00:00.000Z"
    },
    {
      "id": "team-uuid-2",
      "name": "Platform Engineering",
      "slug": "platform-engineering",
      "description": "Infrastructure and platform team",
      "memberCount": 5,
      "createdAt": "2026-02-01T10:30:00.000Z"
    }
  ]
}

Get Team

Retrieve a single team by ID.

GET /orgs/{orgId}/bot/teams/{teamId}

Required scope: teams:read

Example Request

curl -X GET "https://app.mandraki.cloud/api/v1/orgs/{orgId}/bot/teams/{teamId}" \
  -H "Authorization: Bearer mak_..."

Example Response

{
  "id": "team-uuid-1",
  "name": "Engineering",
  "slug": "engineering",
  "description": "Product engineering team",
  "memberCount": 12,
  "createdAt": "2026-01-10T09:00:00.000Z"
}

Error: Team Not Found

{
  "error": "Team not found"
}

Add Team Member

Add a user to a team with an optional role.

POST /orgs/{orgId}/bot/teams/{teamId}/members

Required scope: teams:write

Request Body

Field	Type	Required	Description
userId	UUID	Yes	The user to add to the team
role	enum	No	TEAM_ADMIN or MEMBER (default: MEMBER)

Example Request

curl -X POST "https://app.mandraki.cloud/api/v1/orgs/{orgId}/bot/teams/{teamId}/members" \
  -H "Authorization: Bearer mak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-uuid",
    "role": "MEMBER"
  }'

Example Response

Returns 201 Created with the membership record:

{
  "id": "membership-uuid",
  "teamId": "team-uuid",
  "userId": "user-uuid",
  "role": "MEMBER",
  "createdAt": "2026-03-27T12:00:00.000Z"
}

Error: Missing userId

{
  "error": "userId is required"
}

Remove Team Member

Remove a user from a team.

DELETE /orgs/{orgId}/bot/teams/{teamId}/members/{userId}

Required scope: teams:write

Example Request

curl -X DELETE "https://app.mandraki.cloud/api/v1/orgs/{orgId}/bot/teams/{teamId}/members/{userId}" \
  -H "Authorization: Bearer mak_..."

Example Response

{
  "message": "Member removed"
}