> ## 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.

# Teams API

> API reference for team CRUD, alignment cards, and team reputation

Teams are first-class meta-agents with persistent identity and accumulated reputation. This page covers team management, team alignment cards, team-admin grants, and team reputation scores. For the reputation model itself, see [Team Trust Rating](/concepts/team-reputation).

**Base URL:** `https://api.mnemom.ai/v1`

## Authentication

Team endpoints accept either an API key or a Bearer token — see [Authentication](/api-reference/overview#authentication) for both. Reputation-verification and the embeddable badge are the only public (no-auth) endpoints.

```bash theme={null}
curl https://api.mnemom.ai/v1/teams/{team_id} \
  -H "X-Mnemom-Api-Key: <key>"
```

| Endpoint | Auth required | Notes |
| - | - | - |
| `POST /v1/teams` | Yes | Create team (`owner`/`admin`) |
| `GET /v1/teams/{team_id}` | Yes | Any org member |
| `PATCH /v1/teams/{team_id}` | Yes | Update team (`owner`/`admin`) |
| `DELETE /v1/teams/{team_id}` | Yes | Archive team, soft-delete (`owner`/`admin`) |
| `POST /v1/teams/{team_id}/members` | Yes | Add members (`owner`/`admin`) |
| `DELETE /v1/teams/{team_id}/members/{agent_id}` | Yes | Remove member (`owner`/`admin`) |
| `GET /v1/teams/{team_id}/roster-history` | Yes | Any org member |
| `GET /v1/orgs/{org_id}/teams` | Yes | Any org member |
| `GET /v1/teams/{team_id}/card` | Yes | Any org member |
| `PUT /v1/teams/{team_id}/card` | Yes | Set team card (`owner`/`admin`) |
| `POST /v1/teams/{team_id}/card/derive` | Yes | Auto-derive card from members (`owner`/`admin`) |
| `GET /v1/teams/{team_id}/card/history` | Yes | Any org member |
| `GET /v1/teams/{team_id}/admins` | Yes | List team-admin grants; any org member |
| `POST /v1/teams/{team_id}/admins` | Yes | Grant team-admin role (`owner`/`admin`) |
| `DELETE /v1/teams/{team_id}/admins/{user_id}` | Yes | Revoke team-admin role (`owner`/`admin`, or self) |
| `GET /v1/teams/{team_id}/reputation` | Yes | Any org member |
| `GET /v1/teams/{team_id}/reputation/history` | Yes | Any org member |
| `GET /v1/teams/{team_id}/reputation/verify` | **No** | Public — cryptographic verification |
| `GET /v1/teams/{team_id}/badge.svg` | **No** | Public — embeddable badge |

## Rate limits and feature gating

Team endpoints share the standard per-IP REST rate limit — see [Rate limits](/api-reference/overview#rate-limits). All of them additionally require the `team_reputation` feature flag on your organization; an org without it gets a `403` on every team endpoint. See [Pricing](/pricing/overview) for how usage-based access is granted.

## Endpoints

### Team CRUD

| Method | Endpoint | Description |
| - | - | - |
| `POST` | `/v1/teams` | [Create a team](/api-reference/endpoint/post-teams) |
| `GET` | `/v1/teams/{team_id}` | [Get team by ID](/api-reference/endpoint/get-teams-team-id) |
| `PATCH` | `/v1/teams/{team_id}` | [Update team](/api-reference/endpoint/patch-teams-team-id) |
| `DELETE` | `/v1/teams/{team_id}` | [Archive team](/api-reference/endpoint/delete-teams-team-id) |
| `POST` | `/v1/teams/{team_id}/members` | [Add members](/api-reference/endpoint/post-teams-team-id-members) |
| `DELETE` | `/v1/teams/{team_id}/members/{agent_id}` | [Remove member](/api-reference/endpoint/delete-teams-team-id-members-agent-id) |
| `GET` | `/v1/teams/{team_id}/roster-history` | [Roster history](/api-reference/endpoint/get-teams-team-id-roster-history) |
| `GET` | `/v1/orgs/{org_id}/teams` | [List org teams](/api-reference/endpoint/get-orgs-org-id-teams) |

### Team alignment cards

| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/v1/teams/{team_id}/card` | [Get team card](/api-reference/endpoint/get-teams-team-id-card) |
| `PUT` | `/v1/teams/{team_id}/card` | [Set team card](/api-reference/endpoint/put-teams-team-id-card) |
| `POST` | `/v1/teams/{team_id}/card/derive` | [Derive card from members](/api-reference/endpoint/post-teams-team-id-card-derive) |
| `GET` | `/v1/teams/{team_id}/card/history` | [Card version history](/api-reference/endpoint/get-teams-team-id-card-history) |

### Team-admin grants

A team-admin grant is scoped to one team, distinct from the org-level `owner`/`admin` role used elsewhere on this page.

| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/v1/teams/{team_id}/admins` | [List team-admin grants](/api-reference/endpoint/get-teams-team-id-admins) |
| `POST` | `/v1/teams/{team_id}/admins` | [Grant team-admin](/api-reference/endpoint/post-teams-team-id-admins) |
| `DELETE` | `/v1/teams/{team_id}/admins/{user_id}` | [Revoke team-admin](/api-reference/endpoint/delete-teams-team-id-admins-user-id) |

### Team reputation

| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/v1/teams/{team_id}/reputation` | [Get reputation score](/api-reference/endpoint/get-teams-team-id-reputation) |
| `GET` | `/v1/teams/{team_id}/reputation/history` | [Reputation history](/api-reference/endpoint/get-teams-team-id-reputation-history) |
| `GET` | `/v1/teams/{team_id}/reputation/verify` | [Cryptographic verification](/api-reference/endpoint/get-teams-team-id-reputation-verify) |
| `GET` | `/v1/teams/{team_id}/badge.svg` | [Team trust badge](/api-reference/endpoint/get-teams-team-id-badge-svg) |

## RBAC requirements

| Operation | Required role |
| - | - |
| Create team | `owner` or `admin` |
| View team, roster/card history, list org teams | Any org member |
| Update, archive team | `owner` or `admin` |
| Add/remove members | `owner` or `admin` |
| Set/derive team card | `owner` or `admin` |
| Grant/revoke team-admin | `owner`/`admin` (revoke also permits self) |
| View reputation | Any org member |
| Verify reputation, view badge | Public, no auth |

## Error codes

Team endpoints follow the standard [error envelope](/api-reference/errors). The codes you'll actually branch on here:

| Status | Code | When |
| - | - | - |
| `400` | `bad_request` | Missing/invalid parameters (e.g. team `name`). |
| `401` | `unauthorized` | No credentials, or credentials don't resolve to a principal. |
| `403` | `forbidden` | Authenticated, but not `owner`/`admin` for the operation, or the org lacks the `team_reputation` feature flag. |
| `404` | `not_found` | Team doesn't exist, or doesn't belong to your org. |
| `409` | `conflict` | A team with this name already exists in the organization. |
| `429` | `rate_limited` | Too many requests — see [Rate limits](/api-reference/overview#rate-limits). |

See [Errors](/api-reference/errors) for the full status/retry contract.

## Usage examples

Use the REST API directly, or the `mnemom team` CLI commands where noted.

### REST

```bash theme={null}
# Create a team
curl -X POST https://api.mnemom.ai/v1/teams \
  -H "X-Mnemom-Api-Key: <key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Pipeline Alpha"}'

# Add members
curl -X POST https://api.mnemom.ai/v1/teams/{team_id}/members \
  -H "X-Mnemom-Api-Key: <key>" \
  -H "Content-Type: application/json" \
  -d '{"agent_ids": ["agent-a", "agent-b", "agent-c"]}'

# Derive an alignment card from the team's members
curl -X POST https://api.mnemom.ai/v1/teams/{team_id}/card/derive \
  -H "X-Mnemom-Api-Key: <key>"

# Reputation (requires auth)
curl https://api.mnemom.ai/v1/teams/{team_id}/reputation \
  -H "X-Mnemom-Api-Key: <key>"

# Cryptographic verification (public, no auth)
curl https://api.mnemom.ai/v1/teams/{team_id}/reputation/verify
```

### CLI

The `mnemom` CLI covers a team's alignment/protection templates and team-admin grants directly (see `mnemom team --help`):

```bash theme={null}
mnemom team list
mnemom team show <team_id>
mnemom team alignment-template <team_id> --set alignment.yaml
mnemom team protection-template <team_id> --set protection.yaml
mnemom team admin grant <team_id> --user <user_id>
mnemom team admin list <team_id>
mnemom team coverage <team_id>
```

## Webhook events

Team operations emit these events (see the [Webhook event catalog](/api-reference/webhook-events) for the full payload shape of each, and the [Webhooks guide](/guides/webhooks) for delivery and signature verification):

| Event | Trigger |
| - | - |
| `team.created` | Team was created |
| `team.archived` | Team was archived |
| `team.member_added` | Agent added to team |
| `team.member_removed` | Agent removed from team |
| `team.card_updated` | Team alignment card changed |
| `quota.team_reputation_exceeded` | Team-reputation usage exceeded the org's limit |
| `quota.team_reputation_warning` | Team-reputation usage approaching the org's limit |

## See also

* [Team Trust Rating](/concepts/team-reputation) — how team reputation scoring works
* [Team Management Guide](/guides/team-management) — practical guide with examples
* [Risk Assessment](/concepts/risk-assessment) — the team risk model that feeds reputation
* [Webhook Notifications](/guides/webhooks) — event delivery and signature verification
* [Pricing](/pricing/overview) — usage-based access and current rates


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