Skip to content
Docs menu

Build on Org and teams

Read and manage the organisation's teams, subteams and team members from code or an agent, over REST or MCP, with the same rules as Settings, Teams.

View .md

An org has one tree of teams and subteams, shared by Tasks, Notes, People, Calendar and the other products. Each team has members (people user:<id> and agents agent:<id>) with a team role, admin or member. Everything Settings → Teams does is also an org_team_* MCP tool and a REST route under /api/v1/org/teams. Each tool calls the same functions as the console, so the permission checks, the Tasks and Notes mirrors and the audit rows are the same, with your credential as the actor.

The model itself (subteams, membership that flows down, private teams, teams synced from your identity provider) is described in Teams, subteams and roles. This page covers calling it.

What you can build

  • Teams from your HR system or org chart. Create a team for each department (POST /api/v1/org/teams), nest subteams with parentId, and move them when the org chart changes (POST /api/v1/org/teams/{teamId}/move).
  • Onboarding and offboarding. Add a new hire to their team (org_team_member_add) and take a leaver out of every team (org_team_member_remove). Members of a team are members of its subteams too, so one add is usually enough.
  • Team pickers in your own app. Read the tree you are allowed to see (GET /api/v1/org/teams) and use a team's id when you create work in Tasks, Notes or Calendar.
  • An access review. List each team's members with the ones they inherit from teams above (GET /api/v1/org/teams/{teamId}/members?inherited=true) and compare them with your directory.
  • A service agent that runs its own team. Bind a team key to a service agent, make that agent a team admin, and let it manage that team and its subteams without a person's key.

At a glance

Generated from the code on every docs build.

MCP endpoint https://cloud.usevenom.dev/workspace/mcp/org, server name venom-org
Connect claude mcp add --transport http venom-org https://cloud.usevenom.dev/workspace/mcp/org
MCP tools 10 (3 read, 7 write)
OAuth scopes org:read org:write
REST twin 10 routes under https://cloud.usevenom.dev/api/v1
Webhook events org.team.created, org.team.updated, org.team.archived, org.team.member_added, org.team.member_removed

Authentication and scopes

Who you act as depends on the credential:

  • A personal API key acts as its member (user:<id>) with their org role. Org owners and admins manage every team. Anyone else manages only the teams they are an admin of, and their subteams. Everyone reads the teams that are not private, plus the private teams they are in. A read-only personal key only reads. If the member has left the org, the key is refused.
  • A team key bound to a service agent acts as that agent (agent:<id>). It has no org role, so it manages only the teams the agent is an admin of. Its reads follow the same visibility rules.
  • A team key with no agent bound has no member at all. It reads the teams that are not private and is refused every change.
  • An OAuth app acts as the member who connected it. It needs org:read to use the tools at all and org:write to change anything, on top of that member's rights.

Some refusals come from the team, not the credential: a team that syncs from your identity provider refuses member changes, a team keeps at least one admin once it has one, and a team cannot move under itself or one of its subteams. A private team you may not see answers "No such team", the same as a missing one.

Over REST a refusal is 403, a missing team 404, a bad field 400. Over MCP the tool returns an error with the reason in words. See Authentication and scopes and Errors, limits and pagination.

Worked example

Create a Platform subteam under Engineering and add a new hire to it as a member:

# Find Engineering's id in the tree
curl "$VENOM_CLOUD/api/v1/org/teams" -H "Authorization: Bearer $VENOM_API_KEY"

# Make the subteam (you become its first admin)
curl -X POST "$VENOM_CLOUD/api/v1/org/teams" \
  -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \
  -d '{"name": "Platform", "key": "PLAT", "parentId": "<engineering-team-id>", "description": "Build, deploy and runtime"}'

# Add a person to it
curl -X POST "$VENOM_CLOUD/api/v1/org/teams/<platform-team-id>/members" \
  -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \
  -d '{"member": "user:<member-id>", "role": "member"}'

A person's id is their clerk_user_id from admin_member_list; an agent is agent:<agent id>. The same two changes over MCP, from any client connected to /workspace/mcp/org:

{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": { "name": "org_team_create",
              "arguments": { "name": "Platform", "key": "PLAT", "parentId": "<engineering-team-id>", "description": "Build, deploy and runtime" } } }
{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": { "name": "org_team_member_add",
              "arguments": { "teamId": "<platform-team-id>", "member": "user:<member-id>", "role": "member" } } }

Tools answer in compact markdown by default. Pass "format": "json" for the structured answer (the team, or the team's direct members after a member change). Adding someone who is already in the team changes their role instead.

Events

5 org webhook events, generated from lib/webhooks/events.ts. Subscribe an endpoint to them in Settings, Webhooks (see Webhooks and events).

Event When
org.team.created A team was created in the organisation (shared by Tasks, Chat, Notes and People): id, key, name, parent, whether it is private, and who.
org.team.updated A team's name, key, parent, privacy or description changed: the team as it is now, and who.
org.team.archived A team was archived (or restored: archived false), and who did it.
org.team.member_added A person or agent joined a team: the team, the member's id, their role in it, and who added them.
org.team.member_removed A person or agent left a team: the team, the member's id and who removed them.

Every team change is in the org's audit log with the credential as actor: org.team.created, org.team.updated, org.team.moved, org.team.archived, org.team.unarchived, org.team.member_added, org.team.role_changed, org.team.member_removed, org.team.left and org.team.synced (a SCIM group sync). A caller that may read the audit log can follow them with admin_audit_list and the action prefix org.team (GET /api/v1/admin/audit?action=org.team); see Build on Admin and the mesh.

REST routes

The REST twin: 10 routes under https://cloud.usevenom.dev/api/v1, each calling the MCP tool named in its row with the same arguments (see the REST twin).

Method Path Summary MCP tool
GET /api/v1/org/teams The organisation's teams as a tree org_team_list
POST /api/v1/org/teams Create a team, or a subteam with parentId org_team_create
GET /api/v1/org/teams/{teamId} A team with its place in the tree, subteams and members org_team_get
PATCH /api/v1/org/teams/{teamId} Rename a team, or change its description, key or private flag org_team_update
POST /api/v1/org/teams/{teamId}/move Put a team under another team, or at the top with parentId null org_team_move
POST /api/v1/org/teams/{teamId}/archive Archive a team, or bring it back with archived false org_team_archive
GET /api/v1/org/teams/{teamId}/members A team's members, with those inherited from the teams above org_team_members
POST /api/v1/org/teams/{teamId}/members Add a person (user:<id>) or an agent (agent:<id>) to a team org_team_member_add
PATCH /api/v1/org/teams/{teamId}/members/{member} Make a team member an admin or a member org_team_member_role
DELETE /api/v1/org/teams/{teamId}/members/{member} Take a person or agent out of a team org_team_member_remove

MCP tools

10 tools: 3 read, 7 write. Generated from the code; "write (destructive)" is the tool's destructiveHint. A tool with a REST route is the same call over HTTP.

Tool Title Access Scope REST route
org_team_archive Archive a team write org:write POST /api/v1/org/teams/{teamId}/archive
org_team_create Create a team write org:write POST /api/v1/org/teams
org_team_get Read a team read org:read GET /api/v1/org/teams/{teamId}
org_team_list List the organisation's teams read org:read GET /api/v1/org/teams
org_team_member_add Add a member to a team write org:write POST /api/v1/org/teams/{teamId}/members
org_team_member_remove Remove a member from a team write (destructive) org:write DELETE /api/v1/org/teams/{teamId}/members/{member}
org_team_member_role Change a member's team role write org:write PATCH /api/v1/org/teams/{teamId}/members/{member}
org_team_members List a team's members read org:read GET /api/v1/org/teams/{teamId}/members
org_team_move Move a team write org:write POST /api/v1/org/teams/{teamId}/move
org_team_update Rename or change a team write org:write PATCH /api/v1/org/teams/{teamId}

Linking a SCIM group to a team is an admin tool, not an org_team_* one: admin_sso_group_list and admin_sso_group_team_set, owners only (Teams from your identity provider).