> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mnemom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Team Management

> Create teams, manage rosters, derive alignment cards, and monitor team reputation

**Teams are first-class meta-agents in Mnemom.** Create a team, add agents, derive a collective alignment card, and monitor team reputation -- all through the API or dashboard.

This guide covers the full team lifecycle: creation, roster management, alignment cards, reputation monitoring, and team badges.

<Info>
  Team operations require your org's plan to include the `team_reputation` capability. If it isn't enabled, team endpoints return `403 feature_gated` with an `upgrade_url` pointing at [Pricing](/pricing/overview).
</Info>

***

## Quick start

Create a team, add members, and derive a card in three API calls, using the REST API directly or `@mnemom/sdk`'s generic HTTP client:

<CodeGroup>
  ```python Python theme={null}
  import httpx

  API_BASE = "https://api.mnemom.ai"
  HEADERS = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}

  # 1. Create a team with initial members
  response = httpx.post(f"{API_BASE}/v1/teams", headers=HEADERS, json={
      "org_id": "org-abc123",
      "name": "Support Pipeline Alpha",
      "description": "Customer support agent team",
      "agent_ids": ["agent-a", "agent-b", "agent-c"],
  })
  team = response.json()
  team_id = team["id"]
  print(f"Team created: {team_id}")

  # 2. Derive a team alignment card from member cards (at least 2 members
  #    need active alignment cards first)
  derived = httpx.post(f"{API_BASE}/v1/teams/{team_id}/card/derive", headers=HEADERS)
  print(f"Derived card: {derived.json()['card_json']}")
  ```
</CodeGroup>

***

## Team lifecycle

```
Create → Add Members → Derive Card → Monitor Reputation → Archive
  │          │              │               │                 │
  ▼          ▼              ▼               ▼                 ▼
POST      POST           POST           GET              DELETE
/teams    /members       /card/derive   /reputation      /teams/{id}
```

### 1. Create a team

Teams require an organization and a name. You can add up to 50 initial members, or create the team empty and add members afterward — at least 2 members with active alignment cards are needed before you can derive a card (step 3).

```bash theme={null}
curl -X POST https://api.mnemom.ai/v1/teams \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": "org-abc123",
    "name": "Support Pipeline Alpha",
    "description": "Customer support agent team",
    "agent_ids": ["agent-a", "agent-b", "agent-c"],
    "metadata": { "environment": "production", "domain": "support" }
  }'
```

Team names must be unique within an organization. Every agent you add must be governed by the team's own organization; an agent from another org gets the same `400` ("Agent not found") as an ID that doesn't exist, and the whole request is refused. The response includes the team object and the initial member list.

### 2. Manage roster

Add or remove members as your team evolves. Every roster change is logged in the audit trail.

**Add members:**

```bash theme={null}
curl -X POST https://api.mnemom.ai/v1/teams/{team_id}/members \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "agent_ids": ["agent-d", "agent-e"] }'
```

The response tells you which agents were added and which were already members (idempotent). The same org rule applies: every agent must be governed by the team's organization.

**Remove a member:**

```bash theme={null}
curl -X DELETE https://api.mnemom.ai/v1/teams/{team_id}/members/{agent_id} \
  -H "Authorization: Bearer $TOKEN"
```

<Warning>
  Teams must have at least 2 members. Removing the second-to-last member will fail with a 400 error. Archive the team instead if it's no longer needed.
</Warning>

**View roster history:**

```bash theme={null}
curl https://api.mnemom.ai/v1/teams/{team_id}/roster-history \
  -H "Authorization: Bearer $TOKEN"
```

Returns a paginated audit trail of all roster changes with timestamps, change types, and actors.

### 3. Team alignment cards

Team alignment cards declare the team's collective values, autonomy boundaries, and coordination mode. There are two approaches:

**Auto-derive from members** (recommended):

```bash theme={null}
curl -X POST https://api.mnemom.ai/v1/teams/{team_id}/card/derive \
  -H "Authorization: Bearer $TOKEN"
```

The derivation algorithm merges member cards:

* Values are unioned and ordered by frequency
* Forbidden actions from any member apply to the team
* The strictest audit retention policy wins
* Requires at least 2 members with active alignment cards

**Set manually:**

```bash theme={null}
curl -X PUT https://api.mnemom.ai/v1/teams/{team_id}/card \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": {
      "type": "organization",
      "identifier": "org-abc123",
      "relationship": "delegated_authority"
    },
    "values": {
      "declared": ["reliability", "transparency", "user_safety"]
    },
    "autonomy_envelope": {
      "bounded_actions": ["respond_to_customer", "escalate_ticket"],
      "forbidden_actions": ["delete_customer_data", "modify_billing"],
      "escalation_triggers": ["customer_complaint", "refund_request_over_100"]
    },
    "audit_commitment": {
      "retention_days": 90
    }
  }'
```

**View card history:**

```bash theme={null}
curl https://api.mnemom.ai/v1/teams/{team_id}/card/history \
  -H "Authorization: Bearer $TOKEN"
```

### 4. Monitor reputation

Once your team has 10+ risk assessments, a Team Trust Rating is published.

```bash theme={null}
curl -H "Authorization: Bearer $TOKEN" \
  https://api.mnemom.ai/v1/teams/{team_id}/reputation
```

Track score trends over time:

```bash theme={null}
curl -H "Authorization: Bearer $TOKEN" \
  https://api.mnemom.ai/v1/teams/{team_id}/reputation/history
```

See [Team Trust Rating](/concepts/team-reputation) for details on the 5-component scoring model.

### 5. Archive a team

Archiving soft-deletes the team. Historical data and reputation scores are preserved.

```bash theme={null}
curl -X DELETE https://api.mnemom.ai/v1/teams/{team_id} \
  -H "Authorization: Bearer $TOKEN"
```

***

## Team badges

Embed team reputation badges anywhere -- READMEs, documentation, dashboards.

```
GET https://api.mnemom.ai/v1/teams/{team_id}/badge.svg?variant={variant}&style={style}
```

`style` is `light` (default) or `dark`. Six badge variants are available:

| Variant | Display |
| - | - |
| `score` | `[ Team Trust \| 812 ]` |
| `grade` | `[ Team Trust \| AA ]` |
| `score_grade` | `[ Team Trust \| AA 812 ]` |
| `score_trend` | `[ Team Trust \| AA 812 ↑ ]` |
| `score_tier` | `[ Mnemom Team \| 812 Established ]` |
| `compact` | `[ AA ]` |

Pre-eligible teams (fewer than 10 assessments) show a progress badge:

```
[ Team Trust | Building 4/10 ]
```

**Markdown embed:**

```markdown theme={null}
[![Team Trust Rating](https://api.mnemom.ai/v1/teams/team-abc123/badge.svg?variant=score)](https://www.mnemom.ai/teams/team-abc123/reputation)
```

**HTML embed:**

```html theme={null}
<a href="https://www.mnemom.ai/teams/team-abc123/reputation">
  <img src="https://api.mnemom.ai/v1/teams/team-abc123/badge.svg?variant=score" alt="Team Trust Rating" />
</a>
```

**React:**

```jsx theme={null}
function TeamBadge({ teamId }) {
  const badgeUrl = `https://api.mnemom.ai/v1/teams/${teamId}/badge.svg?variant=score`;
  const pageUrl = `https://www.mnemom.ai/teams/${teamId}/reputation`;

  return (
    <a href={pageUrl} target="_blank" rel="noopener noreferrer">
      <img src={badgeUrl} alt="Team Trust Rating" />
    </a>
  );
}
```

Badges are cached for 60 minutes at the CDN edge. For real-time data, use the API directly.

***

## RBAC requirements

| Operation | Required Role |
| - | - |
| Create team | Org `owner` or `admin` |
| Update team | Org `owner`/`admin`, or a delegated `team_admin` grant on that team |
| Archive team | Org `owner` or `admin` |
| Add/remove members | Org `owner`/`admin`, or a delegated `team_admin` grant on that team |
| Set team card | Org `owner`/`admin`, or a delegated `team_admin` grant on that team |
| Derive team card | Org `owner`/`admin`, or a delegated `team_admin` grant on that team |
| View team details | Any org member |
| View roster history | Any org member |
| View card history | Any org member |
| View reputation | Public (no auth for public teams) |

A `team_admin` grant delegates day-to-day management of one team without full org `admin` — manage grants with `mnemom team admin grant`/`revoke`/`list` or `GET/POST /v1/teams/{team_id}/admins`.

***

## See also

* [Team Trust Rating](/concepts/team-reputation) -- How team reputation scoring works
* [Risk Assessment](/concepts/risk-assessment) -- Team risk model (feeds team reputation)
* [Teams API](/api-reference/team-overview) -- Full API reference
* [Embeddable Badges](/guides/reputation-badges) -- Badge variants and caching
* [Pricing](/pricing/overview) -- Plan details and feature comparison


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.