Reference
Teams API
Updated 1 Oct 2026
On this page
- Team errors
- List teams
- List members
- Invite a member
- Remove a member
- List departments
- Create a department
- Rename a department
- Delete a department
- List department members
- Add a department member
- Remove a department member
- List shared books
- Share a book with the team
- Change how a book is shared
- Stop sharing a book
- Show the access matrix
For agents
Load this page when: you need to manage team members, departments or shared books over HTTP
- Every call needs a teamId from GET /teams. Your role in that team decides what you can do.
- Members can share a book they own read-only with the whole team. Owners and admins manage the rest.
- Team changes share one budget of 20 calls per minute.
A team shares a library. Roles are OWNER, ADMIN and MEMBER. See Teams. A dept path value is a department slug or id.
Team errors
| Status | Message | Code | Fix |
|---|---|---|---|
| 403 | You are not a member of this team. Run `trove team list` to see teams you belong to. | NOT_A_TEAM_MEMBER | Use a team from the list. |
| 403 | Only OWNER and ADMIN can manage team configuration — your role is MEMBER. | FORBIDDEN_ROLE | Ask an owner or admin. |
| 404 | No department '{dept}' in this team — run `trove team departments list` to see available departments. | DEPARTMENT_NOT_FOUND | Check the slug. |
| 429 | Too many team changes in a short window — wait a minute and retry. | RATE_LIMITED | Wait for Retry-After. |
Routes below add their own errors.
List teams
GET https://heytrove.ai/api/v1/teams
Lists the teams you belong to. It takes no parameters.
curl https://heytrove.ai/api/v1/teams \
-H "Authorization: Bearer trove_your_key"{ "teams": [{ "id": "cmteam1", "name": "Platform", "role": "OWNER", "memberCount": 4 }] }CLI equivalent: trove team list.
List members
GET https://heytrove.ai/api/v1/teams/{teamId}/members
Lists members and pending invites. Any member can call it. Plain members see masked emails, with emailHidden set.
{ "members": [{ "email": "[email protected]", "emailHidden": false, "name": "Ada", "role": "ADMIN", "departments": ["engineering"] }], "invites": [] }Invite a member
POST https://heytrove.ai/api/v1/teams/{teamId}/members
Invites a person by email. Only OWNER and ADMIN can call it. The person needs no account yet.
Parameters
| Name | In | Type | Required | Constraints | Meaning |
|---|---|---|---|---|---|
email | body | string | yes | an email address | Person to invite. |
role | body | string | no | MEMBER or ADMIN | Default MEMBER. Any other value becomes MEMBER. |
curl https://heytrove.ai/api/v1/teams/cmteam1/members \
-H "Authorization: Bearer trove_your_key" \
-H "Content-Type: application/json" \
-d '{"email":"[email protected]","role":"ADMIN"}'Status 201 for a new invite, and 200 when it was resent or the person is already a member. The body has invite, member, added, invited, pending, resent, created and alreadyExisted.
CLI equivalent: trove team invite.
Remove a member
DELETE https://heytrove.ai/api/v1/teams/{teamId}/members
Removes a member by email, and their access to shared books. Only the team OWNER can call it. The body is { "email": "..." }. The answer is { "success": true, "member": { "email": "..." } }.
| Status | Message | Code | Fix |
|---|---|---|---|
| 400 | You can't remove yourself. Delete the team instead, or transfer ownership first. | CANNOT_REMOVE_SELF | Ask another owner. |
| 403 | Only the team OWNER can do this — your role is {role}. | FORBIDDEN_ROLE | Ask the owner. |
CLI equivalent: trove team remove.
List departments
GET https://heytrove.ai/api/v1/teams/{teamId}/departments
Lists departments. A plain member sees only their own. The answer is { "departments": [{ "id", "name", "slug" }] }.
Create a department
POST https://heytrove.ai/api/v1/teams/{teamId}/departments
Creates a department. Only OWNER and ADMIN can call it. Creating the same name twice is not an error. Send { "name": "Engineering" }. The answer is status 201 with { "department", "created": true }, or 200 when it existed.
Rename a department
PATCH https://heytrove.ai/api/v1/teams/{teamId}/departments/{dept}
Renames a department. Only OWNER and ADMIN can call it. Send { "name": "..." }. A clash returns 409 DEPARTMENT_SLUG_TAKEN with A department with slug '{slug}' already exists in this team.
Delete a department
DELETE https://heytrove.ai/api/v1/teams/{teamId}/departments/{dept}
Deletes a department. Members lose the assignment, and books shared only with it are unshared. Only OWNER and ADMIN can call it. The answer is { "success": true, "department", "unsharedCount" }.
List department members
GET https://heytrove.ai/api/v1/teams/{teamId}/departments/{dept}/members
Lists the members of a department. Only OWNER and ADMIN can call it. The answer is { "members": [...] }.
Add a department member
POST https://heytrove.ai/api/v1/teams/{teamId}/departments/{dept}/members
Adds a team member by email. The person must already be on the team. Only OWNER and ADMIN can call it. Send { "email": "..." }. The answer is status 201 with { "department", "added": true }, or 200 when they were there.
| Status | Message | Code | Fix |
|---|---|---|---|
| 404 | No team member with email '{email}' — run `trove team show` to see members, or invite them with `trove team invite {email}`. | MEMBER_NOT_FOUND | Invite them first. |
Remove a department member
DELETE https://heytrove.ai/api/v1/teams/{teamId}/departments/{dept}/members
Removes a member from a department. Send { "email": "..." }. The answer has removed set to true, or false when they were not in it.
List shared books
GET https://heytrove.ai/api/v1/teams/{teamId}/items
Lists the books shared with the team. A plain member sees only their own departments.
{ "items": [{ "itemId": "cmabc123", "title": "Use The Index, Luke", "accessLevel": "READ", "teamWide": true, "departments": [], "sharedAt": "2026-09-01T09:00:00.000Z" }] }Share a book with the team
POST https://heytrove.ai/api/v1/teams/{teamId}/items
Shares a book you own. Without departments it goes to the whole team. OWNER and ADMIN can scope a share and grant write access. A plain member can share only read-only with the whole team.
Parameters
| Name | In | Type | Required | Constraints | Meaning |
|---|---|---|---|---|---|
itemId | body | string | yes | a book you own | Book to share. |
departmentSlugs | body | string array | no | up to 50 | Scope to these departments. |
departmentSlug | body | string or null | no | none | Older form with one department. |
accessLevel | body | string | no | READ or WRITE | Default READ. |
curl https://heytrove.ai/api/v1/teams/cmteam1/items \
-H "Authorization: Bearer trove_your_key" \
-H "Content-Type: application/json" \
-d '{"itemId":"cmabc123","departmentSlugs":["engineering"]}'Status 201 when granted, and 200 when it existed. The body has item, departments, teamWide, accessLevel, granted and alreadyExisted.
| Status | Message | Code | Fix |
|---|---|---|---|
| 403 | Item '{id}' not found in your library (you can only share books you own). | ITEM_NOT_OWNED | Share a book you own. |
| 402 | An active team subscription is required to share books with the team. | TEAM_SUBSCRIPTION_REQUIRED | The team needs a paid plan. |
| 400 | A book can be shared with at most 50 departments. | none | Send fewer. |
CLI equivalent: trove team access grant.
Change how a book is shared
PATCH https://heytrove.ai/api/v1/teams/{teamId}/items
Changes the scope, the access level, or both. Only OWNER and ADMIN can call it. Send itemId and at least one of accessLevel and departmentSlugs. An empty departmentSlugs means the whole team.
| Status | Message | Code | Fix |
|---|---|---|---|
| 400 | Provide accessLevel and/or departmentSlug(s) to update. | none | Send one of them. |
| 404 | Item '{id}' is not shared with this team — grant it first with `trove team access grant {id}`. | TEAM_ITEM_NOT_FOUND | Share it first. |
CLI equivalent: trove team access scope.
Stop sharing a book
DELETE https://heytrove.ai/api/v1/teams/{teamId}/items
Stops sharing a book for all members. The team OWNER, an admin, or the member who shared it can call it. Send { "itemId": "..." }. The answer is { "success": true, "item", "alreadyAbsent" }. Anyone else gets 403 FORBIDDEN_REVOKE.
CLI equivalent: trove team access revoke.
Show the access matrix
GET https://heytrove.ai/api/v1/teams/{teamId}/access-report
Shows which department can read which book. Only OWNER and ADMIN can call it. It returns the departments with member counts, and the shared books with their scope and access level.
CLI equivalent: trove team access matrix.