Skip to main content
All team endpoints are scoped to a project. Only the project manager can add or remove team members.
Two-step workflow to add a member:You cannot add a user directly by email. The intended flow is:
  1. Use POST /projects/:projectId/team/find to search for a user by their email address. The response returns the user’s _id.
  2. Use POST /projects/:projectId/team with that _id to add them to the project.
This ensures you confirm the correct user before granting project access.

​
List team members

GET /projects/:projectId/team Returns all current members of the project team. Auth required: Yes

​
Path parameters

​
projectId
string
required
The project ID.

​
Response

Returns an array of TeamMember objects.
​
_id
string
required
User ID.
​
name
string
required
Full name of the team member.
​
email
string
required
Email address of the team member.

​
Example request

curl --request GET \
  --url https://api.example.com/projects/64a1f2c3b4e5d6f7a8b9c0d1/team \
  --header 'Authorization: Bearer <token>'

​
Example response

[
  {
    "_id": "64a1f2c3b4e5d6f7a8b9c0d2",
    "name": "Ana Torres",
    "email": "[email protected]"
  },
  {
    "_id": "64a1f2c3b4e5d6f7a8b9c0d3",
    "name": "Luis Mendez",
    "email": "[email protected]"
  }
]

​
Errors

StatusDescription
401Missing or invalid token.
403You are not a member of this project.
404Project not found.

​
Add a team member

POST /projects/:projectId/team Adds an existing Babel user to the project team by their user ID. Use POST /team/find first to look up the user’s ID from their email. Auth required: Yes

​
Path parameters

​
projectId
string
required
The project ID.

​
Request body

​
id
string
required
The user ID to add to the team.

​
Response

Returns a confirmation message and the updated team array.

​
Example request

curl --request POST \
  --url https://api.example.com/projects/64a1f2c3b4e5d6f7a8b9c0d1/team \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{"id": "64a1f2c3b4e5d6f7a8b9c0d2"}'

​
Example response

{
  "message": "Team member added successfully."
}

​
Errors

StatusDescription
400User not found or already a member.
401Missing or invalid token.
403Only the project manager can add team members.
404Project not found.

​
Remove a team member

DELETE /projects/:projectId/team/:userId Removes a user from the project team. The project manager cannot be removed.
Removing a team member does not unassign their existing tasks. Reassign any open tasks before removing the member.
Auth required: Yes

​
Path parameters

​
projectId
string
required
The project ID.
​
userId
string
required
The user ID to remove from the team.

​
Example request

curl --request DELETE \
  --url https://api.example.com/projects/64a1f2c3b4e5d6f7a8b9c0d1/team/64a1f2c3b4e5d6f7a8b9c0d2 \
  --header 'Authorization: Bearer <token>'

​
Example response

{
  "message": "Team member removed successfully."
}

​
Errors

StatusDescription
401Missing or invalid token.
403Only the project manager can remove team members.
404Project or team member not found.

​
Find a user by email

POST /projects/:projectId/team/find Searches for a registered Babel user by their exact email address. Returns the user’s ID and confirmation status so you can decide whether to add them. Auth required: Yes

​
Path parameters

​
projectId
string
required
The project ID.

​
Request body

​
email
string
required
Exact email address to search for.

​
Response

​
_id
string
required
User ID. Pass this to POST /team to add them to the project.
​
name
string
required
Full name of the user.
​
email
string
required
Email address of the user.
​
confirmed
boolean
required
Whether the user has confirmed their email address. Unconfirmed users cannot access projects.

​
Example request

curl --request POST \
  --url https://api.example.com/projects/64a1f2c3b4e5d6f7a8b9c0d1/team/find \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{"email": "[email protected]"}'

​
Example response

{
  "_id": "64a1f2c3b4e5d6f7a8b9c0d2",
  "name": "Ana Torres",
  "email": "[email protected]",
  "confirmed": true
}

​
Errors

StatusDescription
400No user found with that email address.
401Missing or invalid token.
403You are not a member of this project.
404Project not found.

​
Search team members

GET /projects/:projectId/team/search Searches the existing project team by name or email. Useful for autocomplete fields when assigning or mentioning team members. Auth required: Yes

​
Path parameters

​
projectId
string
required
The project ID.

​
Query parameters

​
q
string
required
Search query matched against team member names and email addresses.

​
Response

Returns an array of matching TeamMember objects.

​
Example request

curl --request GET \
  --url 'https://api.example.com/projects/64a1f2c3b4e5d6f7a8b9c0d1/team/search?q=ana' \
  --header 'Authorization: Bearer <token>'

​
Example response

[
  {
    "_id": "64a1f2c3b4e5d6f7a8b9c0d2",
    "name": "Ana Torres",
    "email": "[email protected]"
  }
]

​
Errors

StatusDescription
401Missing or invalid token.
403You are not a member of this project.
404Project not found.

Build docs developers (and LLMs) love

Get started for freeTalk to us