Teams

Team model

Teams now include:

• visibility: PUBLIC or PRIVATE
• joinPolicy: AUTO_JOIN or APPROVAL_REQUIRED
• membershipRole: OWNER, ADMIN, MEMBER, or null
• isMember: whether the current user has joined the team

Rules:

• Creating a team makes the creator the first OWNER
• AUTO_JOIN is only valid for PUBLIC teams
• OWNER can delete teams and manage all roles
• ADMIN can manage invitations, join requests, members, and basic settings
• A team must always retain at least one OWNER

---

POST /api/v1/teams

Create a new team.

Request body

{
  "name": "Backend Team",
  "visibility": "PUBLIC",
  "joinPolicy": "AUTO_JOIN"
}

Defaults:

• visibility: PRIVATE
• joinPolicy: APPROVAL_REQUIRED

Response 201

{
  "data": {
    "id": "...",
    "name": "Backend Team",
    "slug": "backend-team",
    "visibility": "PUBLIC",
    "joinPolicy": "AUTO_JOIN",
    "isMember": true,
    "membershipRole": "OWNER",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}

---

GET /api/v1/teams

List teams visible to the current user.

Query parameters

Parameter	Description
limit	Page size (default: 20, max: 100)
cursor	Pagination cursor
includePublic	When true, include discoverable public teams you have not joined

By default this endpoint only returns teams you have joined.

---

GET /api/v1/teams/:id

Get a team's details.

• Members can see full details and the member list
• Non-members can only see basic details for PUBLIC teams
• Non-members cannot see PRIVATE teams

---

PATCH /api/v1/teams/:id

Update team settings. Only OWNER and ADMIN may update a team.

Request body

{
  "name": "Platform Team",
  "visibility": "PRIVATE",
  "joinPolicy": "APPROVAL_REQUIRED"
}

---

DELETE /api/v1/teams/:id

Soft-delete a team. Only OWNER may delete a team.

---

POST /api/v1/teams/:id/join

Join a team.

• PUBLIC + AUTO_JOIN creates membership immediately
• All other combinations create or reuse a pending join request

Immediate join response

{
  "data": { "result": "JOINED", "message": "Joined team" }
}

Approval-required response

{
  "data": {
    "result": "REQUEST_SUBMITTED",
    "message": "Join request submitted",
    "requestId": "..."
  }
}

---

POST /api/v1/teams/:id/leave

Leave a team as the current member.

• MEMBER and ADMIN can leave directly
• OWNER can only leave if another OWNER remains
• the last OWNER cannot leave

---

GET /api/v1/teams/:id/members

List all members of a team. Only accessible to team members.

Each member includes:

• role: OWNER, ADMIN, or MEMBER
• joinedAt
• embedded user summary

---

GET /api/v1/teams/:id/join-requests

List pending join requests. Only OWNER and ADMIN may access this endpoint.

---

POST /api/v1/teams/:id/join-requests/:requestId/approve

Approve a join request and add the requester as a MEMBER.

---

POST /api/v1/teams/:id/join-requests/:requestId/reject

Reject a pending join request.

---

POST /api/v1/teams/:id/invitations

Invite an existing Doto user into a team. Only OWNER and ADMIN may invite.

Request body

{
  "userId": "..."
}

---

GET /api/v1/teams/:id/invitations

List invitations for a team. Only OWNER and ADMIN may access this endpoint.

---

GET /api/v1/invitations

List pending invitations for the current user.

This endpoint is for invitees, so they can discover invitation IDs before accepting or declining.

---

POST /api/v1/teams/:id/invitations/:invitationId/accept

Accept an invitation as the invited user.

---

POST /api/v1/teams/:id/invitations/:invitationId/decline

Decline an invitation as the invited user.

---

POST /api/v1/teams/:id/invitations/:invitationId/cancel

Cancel a pending invitation. Only OWNER and ADMIN may cancel.

---

PATCH /api/v1/teams/:id/members/:memberId

Change a member role.

• OWNER can manage OWNER, ADMIN, and MEMBER
• ADMIN can only manage MEMBER
• the last OWNER cannot be downgraded

---

DELETE /api/v1/teams/:id/members/:memberId

Remove a member from a team.

• OWNER can remove OWNER, ADMIN, and MEMBER
• ADMIN can only remove MEMBER
• the last OWNER cannot be removed