Skip to main content

Teams API

The Teams API provides programmatic access to team management, team alignment cards, team reputation scores, and embeddable team badges. Teams are first-class meta-agents with persistent identity and accumulated reputation. Base URL: https://api.mnemom.ai/v1

Authentication

EndpointAuth RequiredNotes
POST /v1/teamsAPI keyCreate team (owner/admin)
GET /v1/teams/{team_id}API keyGet team details
PATCH /v1/teams/{team_id}API keyUpdate team (owner/admin)
DELETE /v1/teams/{team_id}API keyArchive team (owner/admin)
POST /v1/teams/{team_id}/membersAPI keyAdd members (owner/admin)
DELETE /v1/teams/{team_id}/members/{agent_id}API keyRemove member (owner/admin)
GET /v1/teams/{team_id}/roster-historyAPI keyRoster audit trail
GET /v1/orgs/{org_id}/teamsAPI keyList org teams
GET /v1/teams/{team_id}/cardAPI keyGet team alignment card
PUT /v1/teams/{team_id}/cardAPI keySet team card (owner/admin)
POST /v1/teams/{team_id}/card/deriveAPI keyAuto-derive card (owner/admin)
GET /v1/teams/{team_id}/card/historyAPI keyCard version history
GET /v1/teams/{team_id}/reputationNoPublic score retrieval
GET /v1/teams/{team_id}/reputation/historyNoPublic history
GET /v1/teams/{team_id}/reputation/verifyNoCryptographic verification
GET /v1/teams/{team_id}/badge.svgNoPublic badge
API key authentication: Pass in the Authorization header:
Authorization: Bearer {api_key}

Rate Limits

EndpointRate LimitWindow
Team CRUD endpoints60 requestsper minute
Member management60 requestsper minute
Card endpoints60 requestsper minute
Reputation endpoints100 requestsper minute
Badge endpoint300 requestsper minute
Rate-limited responses return HTTP 429 with a Retry-After header.

Endpoints

Team CRUD

MethodEndpointDescription
POST/v1/teamsCreate a team
GET/v1/teams/{team_id}Get team by ID
PATCH/v1/teams/{team_id}Update team
DELETE/v1/teams/{team_id}Archive team
POST/v1/teams/{team_id}/membersAdd members
DELETE/v1/teams/{team_id}/members/{agent_id}Remove member
GET/v1/teams/{team_id}/roster-historyRoster history
GET/v1/orgs/{org_id}/teamsList org teams

Team Alignment Cards

MethodEndpointDescription
GET/v1/teams/{team_id}/cardGet team card
PUT/v1/teams/{team_id}/cardSet team card
POST/v1/teams/{team_id}/card/deriveDerive card from members
GET/v1/teams/{team_id}/card/historyCard version history

Team Reputation

MethodEndpointDescription
GET/v1/teams/{team_id}/reputationGet reputation score
GET/v1/teams/{team_id}/reputation/historyReputation history
GET/v1/teams/{team_id}/reputation/verifyCryptographic verification
GET/v1/teams/{team_id}/badge.svgTeam trust badge

RBAC Requirements

OperationRequired Role
Create teamowner or admin
View teamAny org member
Update teamowner or admin
Archive teamowner or admin
Add/remove membersowner or admin
Set/derive team cardowner or admin
View card/roster historyAny org member
View reputationPublic (no auth for public teams)

Feature Gating

All team endpoints require the team_reputation feature flag, available on Team and Enterprise plans.
PlanAccess
FreeNot available
DeveloperNot available
Team200 team reputation computations/mo ($0.005/ea overage)
EnterpriseUnlimited
See Pricing for plan details.

Error Codes

StatusCodeDescription
400invalid_requestMissing or invalid parameters
401unauthorizedAPI key required but not provided or invalid
403forbiddenInsufficient permissions (wrong org role) or feature not available
404not_foundTeam not found
409conflictTeam name already exists in organization
429rate_limitedToo many requests; check Retry-After header
500internal_errorServer error; retry with exponential backoff
All error responses follow the standard envelope:
{
  "error": "Team name already exists in this organization"
}

SDK Usage

TypeScript

import { createTeam, getTeam, addMembers, deriveTeamCard } from '@mnemom/teams';
import { fetchTeamReputation } from '@mnemom/reputation';

// Create a team
const { team, members } = await createTeam({
  org_id: 'org-abc123',
  name: 'Pipeline Alpha',
  agent_ids: ['agent-a', 'agent-b', 'agent-c'],
});

// Add more members
await addMembers(team.id, ['agent-d']);

// Derive alignment card from member cards
const { derived_card } = await deriveTeamCard(team.id);

// Check team reputation
const reputation = await fetchTeamReputation(team.id);
if (reputation?.is_eligible) {
  console.log(`Team score: ${reputation.score} (${reputation.grade})`);
}

Python

import httpx

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

# Create a team
team = httpx.post(f"{API_BASE}/v1/teams", headers=HEADERS, json={
    "org_id": "org-abc123",
    "name": "Pipeline Alpha",
    "agent_ids": ["agent-a", "agent-b", "agent-c"],
}).json()

team_id = team["team"]["id"]

# Derive card
httpx.post(f"{API_BASE}/v1/teams/{team_id}/card/derive", headers=HEADERS)

# Check reputation (public, no auth)
reputation = httpx.get(f"{API_BASE}/v1/teams/{team_id}/reputation").json()
print(f"Score: {reputation['score']}, Grade: {reputation['grade']}")

Webhook Events

Nine webhook events are emitted for team operations. See Webhook Notifications for delivery details.
EventTrigger
team.createdTeam was created
team.archivedTeam was archived
team.member_addedAgent added to team
team.member_removedAgent removed from team
team.card_updatedTeam alignment card changed
team_reputation.score_changedTeam score changed by more than 10 points
team_reputation.grade_changedTeam letter grade changed
quota.team_reputation_exceededTeam reputation usage exceeded plan limit
quota.team_reputation_warningTeam reputation usage approaching limit (80%+)

See Also